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 2006 Sun Microsystems, Inc. All rights reserved. 24 * Use is subject to license terms. 25 */ 26 27 /* 28 * etm_xport_api.h FMA ETM-to-Transport API header 29 * for sun4v/Ontario 30 * 31 * const/type defns for transporting data between an 32 * event transport module (ETM) and its associated transport 33 * within a fault domain 34 */ 35 36 #ifndef _ETM_XPORT_API_H 37 #define _ETM_XPORT_API_H 38 39 #pragma ident "%Z%%M% %I% %E% SMI" 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /* 46 * ------------------------------ includes ----------------------------------- 47 */ 48 49 #include <sys/fm/protocol.h> 50 #include <fm/fmd_api.h> 51 52 #include <libnvpair.h> 53 54 /* 55 * -------------------------------- typdefs ---------------------------------- 56 */ 57 58 typedef void* etm_xport_addr_t; /* transport address handle */ 59 typedef void* etm_xport_conn_t; /* transport connection handle */ 60 61 typedef enum { 62 63 ETM_XPORT_LCC_TOO_LOW, /* place holder to ease range checking */ 64 ETM_XPORT_LCC_CAME_UP, /* endpoint came up (booted) */ 65 ETM_XPORT_LCC_WENT_DN, /* endpoint went down (crashed/shutdown) */ 66 ETM_XPORT_LCC_TOO_BIG /* place holder to ease range checking */ 67 68 } etm_xport_lcc_t; /* life cycle change of an endpoint */ 69 70 /* 71 * -------------------- connection management functions ---------------------- 72 */ 73 74 /* 75 * etm_xport_init - initialize/setup any transport infrastructure 76 * before any connections are opened, 77 * return 0 or -errno value if initialization failed 78 */ 79 80 int 81 etm_xport_init(fmd_hdl_t *hdl); 82 83 /* 84 * etm_xport_open - open a connection with the given endpoint, 85 * return the connection handle, 86 * or NULL and set errno if open failed 87 */ 88 89 etm_xport_conn_t 90 etm_xport_open(fmd_hdl_t *hdl, etm_xport_addr_t addr); 91 92 /* 93 * etm_xport_accept - accept a request to open a connection, 94 * pending until a remote endpoint opens a 95 * a new connection to us [and sends an ETM msg], 96 * per non-NULL addrp optionally indicate the 97 * remote address if known/avail (NULL if not), 98 * return the connection handle, 99 * or NULL and set errno on failure 100 * 101 * caveats: 102 * any returned transport address is valid only for 103 * as long as the associated connection remains open; 104 * callers should NOT try to free the transport address 105 * 106 * if new connections are rapid relative to how 107 * frequently this function is called, fairness will 108 * be provided among which connections are accepted 109 * 110 * this function may maintain state to recognize [new] 111 * connections and/or to provide fairness 112 */ 113 114 etm_xport_conn_t 115 etm_xport_accept(fmd_hdl_t *hdl, etm_xport_addr_t *addrp); 116 117 /* 118 * etm_xport_close - close a connection from either endpoint, 119 * return the original connection handle, 120 * or NULL and set errno if close failed 121 */ 122 123 etm_xport_conn_t 124 etm_xport_close(fmd_hdl_t *hdl, etm_xport_conn_t conn); 125 126 /* 127 * etm_xport_get_ev_addrv - indicate which transport addresses 128 * are implied as destinations by the 129 * given FMA event, if given no FMA event 130 * (NULL) indicate default or policy 131 * driven dst transport addresses, 132 * return an allocated NULL terminated 133 * vector of allocated transport addresses, 134 * or NULL and set errno if none 135 * caveats: 136 * callers should never try to individually free an addr 137 * within the returned vector 138 */ 139 140 etm_xport_addr_t * 141 etm_xport_get_ev_addrv(fmd_hdl_t *hdl, nvlist_t *ev); 142 143 /* 144 * etm_xport_free_addrv - free the given vector of transport addresses, 145 * including each transport address 146 */ 147 148 void 149 etm_xport_free_addrv(fmd_hdl_t *hdl, etm_xport_addr_t *addrv); 150 151 /* 152 * etm_xport_get_addr_conn - indicate which connections in a NULL 153 * terminated vector of connection 154 * handles are associated with the 155 * given transport address, 156 * return an allocated NULL terminated 157 * vector of those connection handles, 158 * or NULL and set errno if none 159 */ 160 161 etm_xport_conn_t * 162 etm_xport_get_addr_conn(fmd_hdl_t *hdl, etm_xport_conn_t *connv, 163 etm_xport_addr_t addr); 164 165 /* 166 * etm_xport_get_any_lcc - indicate which endpoint has undergone 167 * a life cycle change and what that change 168 * was (ex: come up), pending until a change 169 * has occured for some/any endpoint, 170 * return the appropriate address handle, 171 * or NULL and set errno if problem 172 * 173 * caveats: 174 * this function maintains or accesses state/history 175 * regarding life cycle changes of endpoints 176 * 177 * if life cycle changes are rapid relative to how 178 * frequently this function is called, fairness will 179 * be provided among which endpoints are reported 180 */ 181 182 etm_xport_addr_t 183 etm_xport_get_any_lcc(fmd_hdl_t *hdl, etm_xport_lcc_t *lccp); 184 185 /* 186 * etm_xport_fini - finish/teardown any transport infrastructure 187 * after all connections are closed, 188 * return 0 or -errno value if teardown failed 189 */ 190 191 int 192 etm_xport_fini(fmd_hdl_t *hdl); 193 194 /* 195 * ------------------------ input/output functions --------------------------- 196 */ 197 198 /* 199 * etm_xport_read - try to read N bytes from the connection 200 * into the given buffer, 201 * return how many bytes actually read 202 * or -errno value 203 */ 204 205 ssize_t 206 etm_xport_read(fmd_hdl_t *hdl, etm_xport_conn_t conn, void* buf, 207 size_t byte_cnt); 208 209 /* 210 * etm_xport_write - try to write N bytes to the connection 211 * from the given buffer, 212 * return how many bytes actually written 213 * or -errno value 214 */ 215 216 ssize_t 217 etm_xport_write(fmd_hdl_t *hdl, etm_xport_conn_t conn, void* buf, 218 size_t byte_cnt); 219 220 /* 221 * ------------------------ miscellaneous functions -------------------------- 222 */ 223 224 typedef enum { 225 226 ETM_XPORT_OPT_TOO_LOW = 0, /* range check place holder */ 227 ETM_XPORT_OPT_MTU_SZ, /* read/write MTU in bytes */ 228 ETM_XPORT_OPT_LINGER_TO, /* close linger timeout in sec */ 229 ETM_XPORT_OPT_TOO_BIG /* range check place holder */ 230 231 } etm_xport_opt_t; /* transport options w/ non-neg values */ 232 233 /* 234 * etm_xport_get_opt - get a connection's transport option value, 235 * return the current value 236 * or -errno value (ex: -ENOTSUP) 237 */ 238 239 ssize_t 240 etm_xport_get_opt(fmd_hdl_t *hdl, etm_xport_conn_t conn, etm_xport_opt_t opt); 241 242 243 /* 244 * -------------------------- device driver defns ---------------------------- 245 * 246 * Design_Note: These device driver interface defns should be based upon a 247 * public sys include file provided by the transport device 248 * driver; the header uts/sun4v/sys/glvc.h was not accessible 249 * from the build's default include paths. Until that issue 250 * is resolved they need to be manually synced based upon the 251 * Ontario FMA Phase 1 ETM-to-Transport API Interface Spec. 252 */ 253 254 /* ioctls for peeking data and getting/setting options */ 255 256 #define ETM_XPORT_IOCTL_DATA_PEEK (1) 257 #define ETM_XPORT_IOCTL_OPT_OP (2) 258 259 typedef struct etm_xport_msg_peek { 260 void* pk_buf; /* ptr to buffer to hold peeked data */ 261 size_t pk_buflen; /* number of bytes of peeked data */ 262 uint16_t pk_flags; /* future control flags -- set to 0 */ 263 uint16_t pk_rsvd; /* reserved/padding -- set to 0 */ 264 } etm_xport_msg_peek_t; 265 266 #define ETM_XPORT_OPT_GET (1) 267 #define ETM_XPORT_OPT_SET (2) 268 269 /* options for MTU size in bytes and linger timeout in sec */ 270 271 #define ETM_XPORT_OPT_MTU_SZ (1) 272 #define ETM_XPORT_OPT_LINGER_TO (2) 273 274 typedef struct etm_xport_opt_op { 275 int oo_op; /* which operation (ex: GET) */ 276 int oo_opt; /* which option (ex: MTU_SZ) */ 277 size_t oo_val; /* option value to use (ex: 512) */ 278 } etm_xport_opt_op_t; 279 280 /* default values for options [if unable to get/set] */ 281 282 /* 283 * Design_Note: These might need to be made into properties in prep 284 * for internet domain sockets as a future transport. 285 */ 286 287 #define ETM_XPORT_MTU_SZ_DEF (64) 288 #define ETM_XPORT_LINGER_TO_DEF (0) 289 290 /* 291 * --------------------------------- prolog ---------------------------------- 292 */ 293 294 #ifdef __cplusplus 295 } 296 #endif 297 298 #endif /* _ETM_XPORT_API_H */ 299