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 void (*damap_activate_cb_t)(void *, char *, int, void **); 107 typedef void (*damap_deactivate_cb_t)(void *, char *, int, void *); 108 109 typedef int (*damap_configure_cb_t)(void *, damap_t *, damap_id_t); 110 typedef int (*damap_unconfig_cb_t)(void *, damap_t *, damap_id_t); 111 112 /* 113 * Map reporting mode 114 */ 115 typedef enum {DAMAP_REPORT_PERADDR, DAMAP_REPORT_FULLSET} damap_rptmode_t; 116 117 /* 118 * Map create options flags 119 * DAMAP_SERIALCONFIG - serialize activate/deactivate operations 120 * DAMAP_MTCONFIG - multithread config/unconfg operations 121 */ 122 #define DAMAP_SERIALCONFIG 0 123 #define DAMAP_MTCONFIG 1 124 125 int damap_create(char *, damap_rptmode_t, int, clock_t, 126 void *, damap_activate_cb_t, damap_deactivate_cb_t, 127 void *, damap_configure_cb_t, damap_unconfig_cb_t, 128 damap_t **); 129 void damap_destroy(damap_t *); 130 131 char *damap_name(damap_t *); 132 int damap_sync(damap_t *); 133 134 int damap_addr_add(damap_t *, char *, damap_id_t *, nvlist_t *, void *); 135 int damap_addr_del(damap_t *, char *); 136 int damap_addrid_del(damap_t *, int); 137 138 /* 139 * modifiers to damap_addrset_end() 140 */ 141 #define DAMAP_END_RESET 1 142 #define DAMAP_END_ABORT 2 143 144 int damap_addrset_begin(damap_t *); 145 int damap_addrset_add(damap_t *, char *, damap_id_t *, 146 nvlist_t *, void *); 147 int damap_addrset_end(damap_t *, int); 148 int damap_addrset_reset(damap_t *, int); 149 damap_id_t damap_id_next(damap_t *, damap_id_list_t, damap_id_t); 150 char *damap_id2addr(damap_t *, damap_id_t); 151 nvlist_t *damap_id2nvlist(damap_t *, damap_id_t); 152 int damap_id_hold(damap_t *, damap_id_t); 153 void damap_id_rele(damap_t *, damap_id_t); 154 int damap_id_ref(damap_t *, damap_id_t); 155 void damap_id_list_rele(damap_t *, damap_id_list_t); 156 void *damap_id_priv_get(damap_t *, damap_id_t); 157 void damap_id_priv_set(damap_t *, damap_id_t, void *); 158 damap_id_t damap_lookup(damap_t *, char *); 159 int damap_lookup_all(damap_t *, damap_id_list_t *); 160 161 #define DAM_SUCCESS 0 162 #define DAM_EEXIST 1 163 #define DAM_MAPFULL 2 164 #define DAM_EINVAL 3 165 #define DAM_FAILURE 4 166 #define DAM_SHAME 5 167 168 #ifdef __cplusplus 169 } 170 #endif 171 172 #endif /* _SYS_DAMAP_H */ 173