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 42extern "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 58typedef void* etm_xport_addr_t; /* transport address handle */ 59typedef void* etm_xport_conn_t; /* transport connection handle */ 60 61typedef 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 80int 81etm_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 89etm_xport_conn_t 90etm_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 114etm_xport_conn_t 115etm_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 123etm_xport_conn_t 124etm_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 140etm_xport_addr_t * 141etm_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 148void 149etm_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 161etm_xport_conn_t * 162etm_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 182etm_xport_addr_t 183etm_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 191int 192etm_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 205ssize_t 206etm_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 216ssize_t 217etm_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 224typedef 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 239ssize_t 240etm_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 259typedef 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 274typedef 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