include/sys/damap.h

   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 */