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 * damap_id_list_t: List of damap_id_handles 88 */ 89 typedef struct __damap_dm *damap_t; 90 typedef struct __damap_id_list *damap_id_list_t; 91 typedef id_t damap_id_t; 92 93 #define NODAM (damap_id_t)0 94 95 /* 96 * activate_cb: Provider callback when reported address is activated 97 * deactivate_cb: Provider callback when address has been released 98 * 99 * configure_cb: Class callout to configure newly activated addresses 100 * unconfig_cb: Class callout to unconfigure deactivated addresses 101 */ 102 typedef void (*damap_activate_cb_t)(void *, char *, int, void **); 103 typedef void (*damap_deactivate_cb_t)(void *, char *, int, void *); 104 105 typedef void (*damap_configure_cb_t)(void *, damap_t *, damap_id_list_t); 106 typedef void (*damap_unconfig_cb_t)(void *, damap_t *, damap_id_list_t); 107 108 /* 109 * Map reporting mode 110 */ 111 typedef enum {DAMAP_REPORT_PERADDR, DAMAP_REPORT_FULLSET} damap_rptmode_t; 112 113 #define DAMAP_RESET 1 /* flag to damap_addrset_end */ 114 115 int damap_create(char *, size_t, damap_rptmode_t, clock_t, 116 void *, damap_activate_cb_t, damap_deactivate_cb_t, 117 void *, damap_configure_cb_t, damap_unconfig_cb_t, 118 damap_t **); 119 void damap_destroy(damap_t *); 120 121 char *damap_name(damap_t *); 122 int damap_sync(damap_t *); 123 124 int damap_addr_add(damap_t *, char *, damap_id_t *, nvlist_t *, void *); 125 int damap_addr_del(damap_t *, char *); 126 int damap_addrid_del(damap_t *, int); 127 128 int damap_addrset_begin(damap_t *); 129 int damap_addrset_add(damap_t *, char *, damap_id_t *, nvlist_t *, void *); 130 int damap_addrset_end(damap_t *, int); 131 int damap_addrset_reset(damap_t *, int); 132 133 damap_id_t damap_id_next(damap_t *, damap_id_list_t, damap_id_t); 134 char *damap_id2addr(damap_t *, damap_id_t); 135 nvlist_t *damap_id2nvlist(damap_t *, damap_id_t); 136 int damap_id_hold(damap_t *, damap_id_t); 137 void damap_id_rele(damap_t *, damap_id_t); 138 int damap_id_ref(damap_t *, damap_id_t); 139 void damap_id_list_rele(damap_t *, damap_id_list_t); 140 void *damap_id_priv_get(damap_t *, damap_id_t); 141 void damap_id_priv_set(damap_t *, damap_id_t, void *); 142 damap_id_t damap_lookup(damap_t *, char *); 143 int damap_lookup_all(damap_t *, damap_id_list_t *); 144 145 #define DAM_SUCCESS 0 146 #define DAM_EEXIST 1 147 #define DAM_MAPFULL 2 148 #define DAM_EINVAL 3 149 #define DAM_FAILURE 4 150 #define DAM_SHAME 5 151 152 #ifdef __cplusplus 153 } 154 #endif 155 156 #endif /* _SYS_DAMAP_H */ 157