733a5356058ae0150a67d61f0ad8e5260d2acae3rb * CDDL HEADER START
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * The contents of this file are subject to the terms of the
31e37bb439502e3f7c4c0a9a77d655ea5d56887avn * Common Development and Distribution License (the "License").
31e37bb439502e3f7c4c0a9a77d655ea5d56887avn * You may not use this file except in compliance with the License.
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * See the License for the specific language governing permissions
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * and limitations under the License.
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * When distributing Covered Code, include this CDDL HEADER in each
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * If applicable, add the following below this CDDL HEADER, with the
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * fields enclosed by brackets "[]" replaced with your own identifying
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * information: Portions Copyright [yyyy] [name of copyright owner]
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * CDDL HEADER END
31e37bb439502e3f7c4c0a9a77d655ea5d56887avn * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * Use is subject to license terms.
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * etm_xport_api.h FMA ETM-to-Transport API header
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * const/type defns for transporting data between an
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * event transport module (ETM) and its associated transport
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * within a fault domain
733a5356058ae0150a67d61f0ad8e5260d2acae3rb#pragma ident "%Z%%M% %I% %E% SMI"
733a5356058ae0150a67d61f0ad8e5260d2acae3rbextern "C" {
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * ------------------------------ includes -----------------------------------
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * -------------------------------- typdefs ----------------------------------
733a5356058ae0150a67d61f0ad8e5260d2acae3rbtypedef void* etm_xport_addr_t; /* transport address handle */
733a5356058ae0150a67d61f0ad8e5260d2acae3rbtypedef void* etm_xport_conn_t; /* transport connection handle */
733a5356058ae0150a67d61f0ad8e5260d2acae3rbtypedef enum {
733a5356058ae0150a67d61f0ad8e5260d2acae3rb ETM_XPORT_LCC_TOO_LOW, /* place holder to ease range checking */
733a5356058ae0150a67d61f0ad8e5260d2acae3rb ETM_XPORT_LCC_WENT_DN, /* endpoint went down (crashed/shutdown) */
733a5356058ae0150a67d61f0ad8e5260d2acae3rb ETM_XPORT_LCC_TOO_BIG /* place holder to ease range checking */
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * -------------------- connection management functions ----------------------
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * etm_xport_init - initialize/setup any transport infrastructure
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * before any connections are opened,
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * return 0 or -errno value if initialization failed
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * etm_xport_open - open a connection with the given endpoint,
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * return the connection handle,
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * or NULL and set errno if open failed
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * etm_xport_accept - accept a request to open a connection,
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * pending until a remote endpoint opens a
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * a new connection to us [and sends an ETM msg],
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * per non-NULL addrp optionally indicate the
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * remote address if known/avail (NULL if not),
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * return the connection handle,
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * or NULL and set errno on failure
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * caveats:
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * any returned transport address is valid only for
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * as long as the associated connection remains open;
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * callers should NOT try to free the transport address
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * if new connections are rapid relative to how
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * frequently this function is called, fairness will
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * be provided among which connections are accepted
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * this function may maintain state to recognize [new]
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * connections and/or to provide fairness
733a5356058ae0150a67d61f0ad8e5260d2acae3rbetm_xport_accept(fmd_hdl_t *hdl, etm_xport_addr_t *addrp);
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * etm_xport_close - close a connection from either endpoint,
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * return the original connection handle,
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * or NULL and set errno if close failed
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * etm_xport_get_ev_addrv - indicate which transport addresses
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * are implied as destinations by the
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * given FMA event, if given no FMA event
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * (NULL) indicate default or policy
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * driven dst transport addresses,
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * return an allocated NULL terminated
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * vector of allocated transport addresses,
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * or NULL and set errno if none
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * caveats:
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * callers should never try to individually free an addr
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * within the returned vector
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * etm_xport_free_addrv - free the given vector of transport addresses,
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * including each transport address
733a5356058ae0150a67d61f0ad8e5260d2acae3rbetm_xport_free_addrv(fmd_hdl_t *hdl, etm_xport_addr_t *addrv);
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * etm_xport_get_addr_conn - indicate which connections in a NULL
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * terminated vector of connection
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * handles are associated with the
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * given transport address,
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * return an allocated NULL terminated
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * vector of those connection handles,
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * or NULL and set errno if none
733a5356058ae0150a67d61f0ad8e5260d2acae3rbetm_xport_get_addr_conn(fmd_hdl_t *hdl, etm_xport_conn_t *connv,
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * etm_xport_get_any_lcc - indicate which endpoint has undergone
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * a life cycle change and what that change
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * was (ex: come up), pending until a change
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * has occured for some/any endpoint,
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * return the appropriate address handle,
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * or NULL and set errno if problem
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * caveats:
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * this function maintains or accesses state/history
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * regarding life cycle changes of endpoints
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * if life cycle changes are rapid relative to how
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * frequently this function is called, fairness will
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * be provided among which endpoints are reported
733a5356058ae0150a67d61f0ad8e5260d2acae3rbetm_xport_get_any_lcc(fmd_hdl_t *hdl, etm_xport_lcc_t *lccp);
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * etm_xport_fini - finish/teardown any transport infrastructure
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * after all connections are closed,
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * return 0 or -errno value if teardown failed
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * ------------------------ input/output functions ---------------------------
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * etm_xport_read - try to read N bytes from the connection
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * into the given buffer,
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * return how many bytes actually read
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * or -errno value
733a5356058ae0150a67d61f0ad8e5260d2acae3rbetm_xport_read(fmd_hdl_t *hdl, etm_xport_conn_t conn, void* buf,
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * etm_xport_write - try to write N bytes to the connection
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * from the given buffer,
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * return how many bytes actually written
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * or -errno value
733a5356058ae0150a67d61f0ad8e5260d2acae3rbetm_xport_write(fmd_hdl_t *hdl, etm_xport_conn_t conn, void* buf,
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * ------------------------ miscellaneous functions --------------------------
733a5356058ae0150a67d61f0ad8e5260d2acae3rbtypedef enum {
733a5356058ae0150a67d61f0ad8e5260d2acae3rb ETM_XPORT_OPT_TOO_LOW = 0, /* range check place holder */
733a5356058ae0150a67d61f0ad8e5260d2acae3rb ETM_XPORT_OPT_LINGER_TO, /* close linger timeout in sec */
733a5356058ae0150a67d61f0ad8e5260d2acae3rb} etm_xport_opt_t; /* transport options w/ non-neg values */
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * etm_xport_get_opt - get a connection's transport option value,
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * return the current value
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * or -errno value (ex: -ENOTSUP)
733a5356058ae0150a67d61f0ad8e5260d2acae3rbetm_xport_get_opt(fmd_hdl_t *hdl, etm_xport_conn_t conn, etm_xport_opt_t opt);
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * -------------------------- device driver defns ----------------------------
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * Design_Note: These device driver interface defns should be based upon a
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * public sys include file provided by the transport device
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * driver; the header uts/sun4v/sys/glvc.h was not accessible
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * from the build's default include paths. Until that issue
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * is resolved they need to be manually synced based upon the
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * Ontario FMA Phase 1 ETM-to-Transport API Interface Spec.
733a5356058ae0150a67d61f0ad8e5260d2acae3rb/* ioctls for peeking data and getting/setting options */
733a5356058ae0150a67d61f0ad8e5260d2acae3rb uint16_t pk_flags; /* future control flags -- set to 0 */
733a5356058ae0150a67d61f0ad8e5260d2acae3rb/* options for MTU size in bytes and linger timeout in sec */
733a5356058ae0150a67d61f0ad8e5260d2acae3rb/* default values for options [if unable to get/set] */
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * Design_Note: These might need to be made into properties in prep
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * for internet domain sockets as a future transport.
733a5356058ae0150a67d61f0ad8e5260d2acae3rb * --------------------------------- prolog ----------------------------------
733a5356058ae0150a67d61f0ad8e5260d2acae3rb#endif /* _ETM_XPORT_API_H */