view usr/src/cmd/fm/modules/sun4v/etm/etm_xport_api.h @ 0:c9caec207d52 b86

Initial porting based on b86
author Koji Uno <koji.uno@sun.com>
date Tue, 02 Jun 2009 18:56:50 +0900
parents
children 1a15d5aaf794
line wrap: on
line source

/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License (the "License").
 * You may not use this file except in compliance with the License.
 *
 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
 * or http://www.opensolaris.org/os/licensing.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
 * If applicable, add the following below this CDDL HEADER, with the
 * fields enclosed by brackets "[]" replaced with your own identifying
 * information: Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 */

/*
 * Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 */

/*
 * etm_xport_api.h	FMA ETM-to-Transport API header
 *			for sun4v/Ontario
 *
 * const/type defns for transporting data between an
 * event transport module (ETM) and its associated transport
 * within a fault domain
 */

#ifndef _ETM_XPORT_API_H
#define	_ETM_XPORT_API_H

#pragma ident	"@(#)etm_xport_api.h	1.2	06/05/10 SMI"

#ifdef __cplusplus
extern "C" {
#endif

/*
 * ------------------------------ includes -----------------------------------
 */

#include <sys/fm/protocol.h>
#include <fm/fmd_api.h>

#include <libnvpair.h>

/*
 * -------------------------------- typdefs ----------------------------------
 */

typedef void* etm_xport_addr_t;  /* transport address handle */
typedef void* etm_xport_conn_t;  /* transport connection handle */

typedef enum {

	ETM_XPORT_LCC_TOO_LOW,	/* place holder to ease range checking */
	ETM_XPORT_LCC_CAME_UP,	/* endpoint came up (booted) */
	ETM_XPORT_LCC_WENT_DN,	/* endpoint went down (crashed/shutdown) */
	ETM_XPORT_LCC_TOO_BIG	/* place holder to ease range checking */

} etm_xport_lcc_t;		/* life cycle change of an endpoint */

/*
 * -------------------- connection management functions ----------------------
 */

/*
 * etm_xport_init - initialize/setup any transport infrastructure
 *			before any connections are opened,
 *			return 0 or -errno value if initialization failed
 */

int
etm_xport_init(fmd_hdl_t *hdl);

/*
 * etm_xport_open - open a connection with the given endpoint,
 *			return the connection handle,
 *			or NULL and set errno if open failed
 */

etm_xport_conn_t
etm_xport_open(fmd_hdl_t *hdl, etm_xport_addr_t addr);

/*
 * etm_xport_accept - accept a request to open a connection,
 *			pending until a remote endpoint opens a
 *			a new connection to us [and sends an ETM msg],
 *			per non-NULL addrp optionally indicate the
 *			remote address if known/avail (NULL if not),
 *			return the connection handle,
 *			or NULL and set errno on failure
 *
 * caveats:
 *		any returned transport address is valid only for
 *		as long as the associated connection remains open;
 *		callers should NOT try to free the transport address
 *
 *		if new connections are rapid relative to how
 *		frequently this function is called, fairness will
 *		be provided among which connections are accepted
 *
 *		this function may maintain state to recognize [new]
 *		connections and/or to provide fairness
 */

etm_xport_conn_t
etm_xport_accept(fmd_hdl_t *hdl, etm_xport_addr_t *addrp);

/*
 * etm_xport_close - close a connection from either endpoint,
 *			return the original connection handle,
 *			or NULL and set errno if close failed
 */

etm_xport_conn_t
etm_xport_close(fmd_hdl_t *hdl, etm_xport_conn_t conn);

/*
 * etm_xport_get_ev_addrv - indicate which transport addresses
 *				are implied as destinations by the
 *				given FMA event, if given no FMA event
 *				(NULL) indicate default or policy
 *				driven dst transport addresses,
 *				return an allocated NULL terminated
 *				vector of allocated transport addresses,
 *				or NULL and set errno if none
 * caveats:
 *		callers should never try to individually free an addr
 *		within the returned vector
 */

etm_xport_addr_t *
etm_xport_get_ev_addrv(fmd_hdl_t *hdl, nvlist_t *ev);

/*
 * etm_xport_free_addrv - free the given vector of transport addresses,
 *				including each transport address
 */

void
etm_xport_free_addrv(fmd_hdl_t *hdl, etm_xport_addr_t *addrv);

/*
 * etm_xport_get_addr_conn - indicate which connections in a NULL
 *				terminated vector of connection
 *				handles are associated with the
 *				given transport address,
 *				return an allocated NULL terminated
 *				vector of those connection handles,
 *				or NULL and set errno if none
 */

etm_xport_conn_t *
etm_xport_get_addr_conn(fmd_hdl_t *hdl, etm_xport_conn_t *connv,
			    etm_xport_addr_t addr);

/*
 * etm_xport_get_any_lcc - indicate which endpoint has undergone
 *			a life cycle change and what that change
 *			was (ex: come up), pending until a change
 *			has occured for some/any endpoint,
 *			return the appropriate address handle,
 *			or NULL and set errno if problem
 *
 * caveats:
 *		this function maintains or accesses state/history
 *		regarding life cycle changes of endpoints
 *
 *		if life cycle changes are rapid relative to how
 *		frequently this function is called, fairness will
 *		be provided among which endpoints are reported
 */

etm_xport_addr_t
etm_xport_get_any_lcc(fmd_hdl_t *hdl, etm_xport_lcc_t *lccp);

/*
 * etm_xport_fini - finish/teardown any transport infrastructure
 *			after all connections are closed,
 *			return 0 or -errno value if teardown failed
 */

int
etm_xport_fini(fmd_hdl_t *hdl);

/*
 * ------------------------ input/output functions ---------------------------
 */

/*
 * etm_xport_read - try to read N bytes from the connection
 *			into the given buffer,
 *			return how many bytes actually read
 *			or -errno value
 */

ssize_t
etm_xport_read(fmd_hdl_t *hdl, etm_xport_conn_t conn, void* buf,
							size_t byte_cnt);

/*
 * etm_xport_write - try to write N bytes to the connection
 *			from the given buffer,
 *			return how many bytes actually written
 *			or -errno value
 */

ssize_t
etm_xport_write(fmd_hdl_t *hdl, etm_xport_conn_t conn, void* buf,
							size_t byte_cnt);

/*
 * ------------------------ miscellaneous functions --------------------------
 */

typedef enum {

	ETM_XPORT_OPT_TOO_LOW = 0,	/* range check place holder */
	ETM_XPORT_OPT_MTU_SZ,		/* read/write MTU in bytes */
	ETM_XPORT_OPT_LINGER_TO,	/* close linger timeout in sec */
	ETM_XPORT_OPT_TOO_BIG		/* range check place holder */

} etm_xport_opt_t;		/* transport options w/ non-neg values */

/*
 * etm_xport_get_opt - get a connection's transport option value,
 *			return the current value
 *			or -errno value (ex: -ENOTSUP)
 */

ssize_t
etm_xport_get_opt(fmd_hdl_t *hdl, etm_xport_conn_t conn, etm_xport_opt_t opt);


/*
 * -------------------------- device driver defns ----------------------------
 *
 * Design_Note:	These device driver interface defns should be based upon a
 *		public sys include file provided by the transport device
 *		driver; the header uts/sun4v/sys/glvc.h was not accessible
 *		from the build's default include paths. Until that issue
 *		is resolved they need to be manually synced based upon the
 *		Ontario FMA Phase 1 ETM-to-Transport API Interface Spec.
 */

/* ioctls for peeking data and getting/setting options */

#define	ETM_XPORT_IOCTL_DATA_PEEK	(1)
#define	ETM_XPORT_IOCTL_OPT_OP		(2)

typedef struct etm_xport_msg_peek {
	void*		pk_buf;		/* ptr to buffer to hold peeked data */
	size_t		pk_buflen;	/* number of bytes of peeked data */
	uint16_t	pk_flags;	/* future control flags -- set to 0 */
	uint16_t	pk_rsvd;	/* reserved/padding -- set to 0 */
} etm_xport_msg_peek_t;

#define	ETM_XPORT_OPT_GET	(1)
#define	ETM_XPORT_OPT_SET	(2)

/* options for MTU size in bytes and linger timeout in sec */

#define	ETM_XPORT_OPT_MTU_SZ	(1)
#define	ETM_XPORT_OPT_LINGER_TO	(2)

typedef struct etm_xport_opt_op {
	int	oo_op;	/* which operation (ex: GET) */
	int	oo_opt;	/* which option (ex: MTU_SZ) */
	size_t	oo_val;	/* option value to use (ex: 512) */
} etm_xport_opt_op_t;

/* default values for options [if unable to get/set] */

/*
 * Design_Note:	These might need to be made into properties in prep
 *		for internet domain sockets as a future transport.
 */

#define	ETM_XPORT_MTU_SZ_DEF	(64)
#define	ETM_XPORT_LINGER_TO_DEF	(0)

/*
 * --------------------------------- prolog ----------------------------------
 */

#ifdef __cplusplus
}
#endif

#endif /* _ETM_XPORT_API_H */