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 2009 Sun Microsystems, Inc. All rights reserved. 24 * Use is subject to license terms. 25 */ 26 27 #ifndef _SYS_DAMAP_H 28 #define _SYS_DAMAP_H 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 34 /* 35 * Delta (device) Address Map Interfaces 36 * 37 * These interfaces provide time-stablized sets of 'addresses', 38 * where addresses are string representations of device 39 * or bus-specific address. The mechanisms include interfaces to 40 * report and remove address from a map, time stabilization, callouts 41 * to higher-level configuration and unconfiguration actions, and 42 * address lookup functions. 43 * 44 * Per Address Reports 45 * With per-address reporting, the caller reports the addition and removal 46 * each address visible to it. Each report is independently time stabilized; 47 * Once a report has stabilized, the reported address is either 48 * activated & configured, or unconfigured & released. 49 * 50 * Full Set Reports 51 * When using fullset reporting, the report provider enumerates the entire 52 * set of addresses visible to the provider at a given point in time. 53 * The entire set is then stabilized. 54 * Upon stabilizing, any newly reported addresses are activated & configured 55 * and any previously active addresses which are no longer visible are 56 * automatically unconfigured and released, freeing the provider from 57 * the need to explicitly unconfigure addresses no longer present. 58 * 59 * Stabilization 60 * Once an address has been reported (or reported as removed), the report 61 * is time stabilized before the framework initiates a configuration 62 * or unconfiguration action. If the address is re-reported while undergoing 63 * stabilization, the timer is reset for either the address or the full 64 * set of addresses reported to the map. 65 * 66 * Activation/Release 67 * Once a reported address has passed its stabilization, the address is 68 * 'activated' by the framework. Once activated, the address is passed 69 * to a configuration callout to perform whatever actions are necessary. 70 * If a reported address is deleted or fails to stabilize, the address 71 * is released by the map. 72 * A report provider may register callback functions to be invoked 73 * as part of the address activation & release process. In addition to 74 * the callbacks, a provider can also supply a handle to provider-private 75 * data at the time an address is reported. This handle is returned to 76 * provider as an argument to the activation & release callbacks. 77 * 78 * Lookup/Access 79 * The set of stable addresses contained in a map can be obtained by 80 * calling interfaces to lookup either a single address or the full 81 * list of stable addresses. 82 */ 83 84 /* 85 * damap_t: Handle to a delta address map 86 * damap_id_t: Handle to an entry of damap_t 87 */ 88 typedef struct __damap_dm *damap_t; 89 typedef id_t damap_id_t; 90 91 /* 92 * damap_id_list_t: List of damap_id_handles 93 * NB. Not Used 94 */ 95 typedef struct __damap_id_list *damap_id_list_t; 96 97 #define NODAM (damap_id_t)0 98 99 /* 100 * activate_cb: Provider callback when reported address is activated 101 * deactivate_cb: Provider callback when address has been released 102 * 103 * configure_cb: Class callout to configure newly activated addresses 104 * unconfig_cb: Class callout to unconfigure deactivated addresses 105 */ 106 typedef enum { 107 DAMAP_DEACT_RSN_GONE = 0, 108 DAMAP_DEACT_RSN_CFG_FAIL 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, clock_t, 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_sync(damap_t *); 139 140 int damap_addr_add(damap_t *, char *, damap_id_t *, nvlist_t *, void *); 141 int damap_addr_del(damap_t *, char *); 142 int damap_addrid_del(damap_t *, int); 143 144 /* 145 * modifiers to damap_addrset_end() 146 */ 147 #define DAMAP_END_RESET 1 148 #define DAMAP_END_ABORT 2 149 150 int damap_addrset_begin(damap_t *); 151 int damap_addrset_add(damap_t *, char *, damap_id_t *, 152 nvlist_t *, void *); 153 int damap_addrset_end(damap_t *, int); 154 int damap_addrset_reset(damap_t *, int); 155 damap_id_t damap_id_next(damap_t *, damap_id_list_t, damap_id_t); 156 char *damap_id2addr(damap_t *, damap_id_t); 157 nvlist_t *damap_id2nvlist(damap_t *, damap_id_t); 158 int damap_id_hold(damap_t *, damap_id_t); 159 void damap_id_rele(damap_t *, damap_id_t); 160 int damap_id_ref(damap_t *, damap_id_t); 161 void damap_id_list_rele(damap_t *, damap_id_list_t); 162 void *damap_id_priv_get(damap_t *, damap_id_t); 163 void damap_id_priv_set(damap_t *, damap_id_t, void *); 164 damap_id_t damap_lookup(damap_t *, char *); 165 int damap_lookup_all(damap_t *, damap_id_list_t *); 166 167 #define DAM_SUCCESS 0 168 #define DAM_EEXIST 1 169 #define DAM_MAPFULL 2 170 #define DAM_EINVAL 3 171 #define DAM_FAILURE 4 172 #define DAM_SHAME 5 173 174 #ifdef __cplusplus 175 } 176 #endif 177 178 #endif /* _SYS_DAMAP_H */ 179