1 /* 2 * CDDL HEADER START 3 * 4 * The contents of this file are subject to the terms of the 5 * Common Development and Distribution License (the "License"). 6 * You may not use this file except in compliance with the License. 7 * 8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9 * or http://www.opensolaris.org/os/licensing. 10 * See the License for the specific language governing permissions 11 * and limitations under the License. 12 * 13 * When distributing Covered Code, include this CDDL HEADER in each 14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15 * If applicable, add the following below this CDDL HEADER, with the 16 * fields enclosed by brackets "[]" replaced with your own identifying 17 * information: Portions Copyright [yyyy] [name of copyright owner] 18 * 19 * CDDL HEADER END 20 */ 21 22 /* 23 * Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved. 24 */ 25 26 #ifndef _SYS_DAMAP_H 27 #define _SYS_DAMAP_H 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 /* 34 * Delta (device) Address Map Interfaces 35 * 36 * These interfaces provide time-stablized sets of 'addresses', 37 * where addresses are string representations of device 38 * or bus-specific address. The mechanisms include interfaces to 39 * report and remove address from a map, time stabilization, callouts 40 * to higher-level configuration and unconfiguration actions, and 41 * address lookup functions. 42 * 43 * Per Address Reports 44 * With per-address reporting, the caller reports the addition and removal 45 * each address visible to it. Each report is independently time stabilized; 46 * Once a report has stabilized, the reported address is either 47 * activated & configured, or unconfigured & released. 48 * 49 * Full Set Reports 50 * When using fullset reporting, the report provider enumerates the entire 51 * set of addresses visible to the provider at a given point in time. 52 * The entire set is then stabilized. 53 * Upon stabilizing, any newly reported addresses are activated & configured 54 * and any previously active addresses which are no longer visible are 55 * automatically unconfigured and released, freeing the provider from 56 * the need to explicitly unconfigure addresses no longer present. 57 * 58 * Stabilization 59 * Once an address has been reported (or reported as removed), the report 60 * is time stabilized before the framework initiates a configuration 61 * or unconfiguration action. If the address is re-reported while undergoing 62 * stabilization, the timer is reset for either the address or the full 63 * set of addresses reported to the map. 64 * 65 * Activation/Release 66 * Once a reported address has passed its stabilization, the address is 67 * 'activated' by the framework. Once activated, the address is passed 68 * to a configuration callout to perform whatever actions are necessary. 69 * If a reported address is deleted or fails to stabilize, the address 70 * is released by the map. 71 * A report provider may register callback functions to be invoked 72 * as part of the address activation & release process. In addition to 73 * the callbacks, a provider can also supply a handle to provider-private 74 * data at the time an address is reported. This handle is returned to 75 * provider as an argument to the activation & release callbacks. 76 * 77 * Lookup/Access 78 * The set of stable addresses contained in a map can be obtained by 79 * calling interfaces to lookup either a single address or the full 80 * list of stable addresses. 81 */ 82 83 /* 84 * damap_t: Handle to a delta address map 85 * damap_id_t: Handle to an entry of damap_t 86 */ 87 typedef struct __damap_dm *damap_t; 88 typedef id_t damap_id_t; 89 90 /* 91 * damap_id_list_t: List of damap_id_handles 92 * NB. Not Used 93 */ 94 typedef struct __damap_id_list *damap_id_list_t; 95 96 #define NODAM (damap_id_t)0 97 98 /* 99 * activate_cb: Provider callback when reported address is activated 100 * deactivate_cb: Provider callback when address has been released 101 * 102 * configure_cb: Class callout to configure newly activated addresses 103 * unconfig_cb: Class callout to unconfigure deactivated addresses 104 */ 105 typedef enum { 106 DAMAP_DEACT_RSN_GONE = 0, 107 DAMAP_DEACT_RSN_CFG_FAIL, 108 DAMAP_DEACT_RSN_UNSTBL 109 } damap_deact_rsn_t; 110 111 typedef void (*damap_activate_cb_t)(void *, char *, int, void **); 112 typedef void (*damap_deactivate_cb_t)(void *, char *, int, void *, 113 damap_deact_rsn_t); 114 115 typedef int (*damap_configure_cb_t)(void *, damap_t *, damap_id_t); 116 typedef int (*damap_unconfig_cb_t)(void *, damap_t *, damap_id_t); 117 118 /* 119 * Map reporting mode 120 */ 121 typedef enum {DAMAP_REPORT_PERADDR, DAMAP_REPORT_FULLSET} damap_rptmode_t; 122 123 /* 124 * Map create options flags 125 * DAMAP_SERIALCONFIG - serialize activate/deactivate operations 126 * DAMAP_MTCONFIG - multithread config/unconfg operations 127 */ 128 #define DAMAP_SERIALCONFIG 0 129 #define DAMAP_MTCONFIG 1 130 131 int damap_create(char *, damap_rptmode_t, int, int, 132 void *, damap_activate_cb_t, damap_deactivate_cb_t, 133 void *, damap_configure_cb_t, damap_unconfig_cb_t, 134 damap_t **); 135 void damap_destroy(damap_t *); 136 137 char *damap_name(damap_t *); 138 int damap_size(damap_t *); 139 int damap_is_empty(damap_t *); 140 int damap_sync(damap_t *, int); 141 142 int damap_addr_add(damap_t *, char *, damap_id_t *, nvlist_t *, void *); 143 int damap_addr_del(damap_t *, char *); 144 int damap_addrid_del(damap_t *, int); 145 146 /* 147 * modifiers to damap_addrset_end() 148 */ 149 #define DAMAP_END_RESET 1 150 #define DAMAP_END_ABORT 2 151 152 int damap_addrset_begin(damap_t *); 153 int damap_addrset_add(damap_t *, char *, damap_id_t *, 154 nvlist_t *, void *); 155 int damap_addrset_end(damap_t *, int); 156 int damap_addrset_flush(damap_t *); 157 int damap_addrset_reset(damap_t *, int); 158 damap_id_t damap_id_next(damap_t *, damap_id_list_t, damap_id_t); 159 char *damap_id2addr(damap_t *, damap_id_t); 160 nvlist_t *damap_id2nvlist(damap_t *, damap_id_t); 161 int damap_id_hold(damap_t *, damap_id_t); 162 void damap_id_rele(damap_t *, damap_id_t); 163 int damap_id_ref(damap_t *, damap_id_t); 164 void damap_id_list_rele(damap_t *, damap_id_list_t); 165 void *damap_id_priv_get(damap_t *, damap_id_t); 166 void damap_id_priv_set(damap_t *, damap_id_t, void *); 167 damap_id_t damap_lookup(damap_t *, char *); 168 int damap_lookup_all(damap_t *, damap_id_list_t *); 169 170 #define DAM_SUCCESS 0 171 #define DAM_EEXIST 1 172 #define DAM_MAPFULL 2 173 #define DAM_EINVAL 3 174 #define DAM_FAILURE 4 175 #define DAM_SHAME 5 176 177 #ifdef __cplusplus 178 } 179 #endif 180 181 #endif /* _SYS_DAMAP_H */ 182