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