1/*-
2 * Copyright (c) 2003 Silicon Graphics International Corp.
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 * 1. Redistributions of source code must retain the above copyright
9 *    notice, this list of conditions, and the following disclaimer,
10 *    without modification.
11 * 2. Redistributions in binary form must reproduce at minimum a disclaimer
12 *    substantially similar to the "NO WARRANTY" disclaimer below
13 *    ("Disclaimer") and any redistribution must be conditioned upon
14 *    including a substantially similar Disclaimer requirement for further
15 *    binary redistribution.
16 *
17 * NO WARRANTY
18 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
21 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22 * HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
26 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
27 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 * POSSIBILITY OF SUCH DAMAGES.
29 *
30 * $Id: //depot/users/kenm/FreeBSD-test2/sys/cam/ctl/ctl_frontend.h#2 $
31 * $FreeBSD$
32 */
33/*
34 * CAM Target Layer front end registration hooks
35 *
36 * Author: Ken Merry <ken@FreeBSD.org>
37 */
38
39#ifndef	_CTL_FRONTEND_H_
40#define	_CTL_FRONTEND_H_
41
42typedef enum {
43	CTL_PORT_STATUS_NONE		= 0x00,
44	CTL_PORT_STATUS_ONLINE		= 0x01,
45	CTL_PORT_STATUS_TARG_ONLINE	= 0x02,
46	CTL_PORT_STATUS_LUN_ONLINE	= 0x04
47} ctl_port_status;
48
49typedef int (*fe_init_t)(void);
50typedef void (*fe_shutdown_t)(void);
51typedef void (*port_func_t)(void *onoff_arg);
52typedef int (*port_info_func_t)(void *onoff_arg, struct sbuf *sb);
53typedef	int (*lun_func_t)(void *arg, struct ctl_id targ_id, int lun_id);
54typedef	uint32_t (*lun_map_func_t)(void *arg, uint32_t lun_id);
55typedef int (*fe_ioctl_t)(struct cdev *dev, u_long cmd, caddr_t addr, int flag,
56			  struct thread *td);
57
58#define CTL_FRONTEND_DECLARE(name, driver) \
59	static int name ## _modevent(module_t mod, int type, void *data) \
60	{ \
61		switch (type) { \
62		case MOD_LOAD: \
63			ctl_frontend_register( \
64				(struct ctl_frontend *)data); \
65			break; \
66		case MOD_UNLOAD: \
67			printf(#name " module unload - not possible for this module type\n"); \
68			return EINVAL; \
69		default: \
70			return EOPNOTSUPP; \
71		} \
72		return 0; \
73	} \
74	static moduledata_t name ## _mod = { \
75		#name, \
76		name ## _modevent, \
77		(void *)&driver \
78	}; \
79	DECLARE_MODULE(name, name ## _mod, SI_SUB_CONFIGURE, SI_ORDER_FOURTH); \
80	MODULE_DEPEND(name, ctl, 1, 1, 1); \
81	MODULE_DEPEND(name, cam, 1, 1, 1)
82
83struct ctl_wwpn_iid {
84	int in_use;
85	time_t last_use;
86	uint64_t wwpn;
87	char *name;
88};
89
90/*
91 * The ctl_frontend structure is the registration mechanism between a FETD
92 * (Front End Target Driver) and the CTL layer.  Here is a description of
93 * the fields:
94 *
95 * port_type:		  This field tells CTL what kind of front end it is
96 *                        dealing with.  This field serves two purposes.
97 *                        The first is to let CTL know whether the frontend
98 *                        in question is inside the main CTL module (i.e.
99 *                        the ioctl front end), and therefore its module
100 *                        reference count shouldn't be incremented.  The
101 *                        CTL ioctl front end should continue to use the
102 *                        CTL_PORT_IOCTL argument as long as it is part of
103 *                        the main CTL module.  The second is to let CTL
104 *                        know what kind of front end it is dealing with, so
105 *                        it can return the proper inquiry data for that
106 *                        particular port.
107 *
108 * num_requested_ctl_io:  This is the number of ctl_io structures that the
109 *			  front end needs for its pool.  This should
110 * 			  generally be the maximum number of outstanding
111 *			  transactions that the FETD can handle.  The CTL
112 *			  layer will add a few to this to account for
113 *			  ctl_io buffers queued for pending sense data.
114 *			  (Pending sense only gets queued if the FETD
115 * 			  doesn't support autosense.  e.g. non-packetized
116 * 			  parallel SCSI doesn't support autosense.)
117 *
118 * port_name:		  A string describing the FETD.  e.g. "LSI 1030T U320"
119 *			  or whatever you want to use to describe the driver.
120 *
121 *
122 * physical_port:	  This is the physical port number of this
123 * 			  particular port within the driver/hardware.  This
124 * 			  number is hardware/driver specific.
125 * virtual_port:	  This is the virtual port number of this
126 * 			  particular port.  This is for things like NP-IV.
127 *
128 * port_online():	  This function is called, with onoff_arg as its
129 *			  argument, by the CTL layer when it wants the FETD
130 *			  to start responding to selections on the specified
131 * 			  target ID.  (targ_target)
132 *
133 * port_offline():	  This function is called, with onoff_arg as its
134 *			  argument, by the CTL layer when it wants the FETD
135 * 			  to stop responding to selection on the specified
136 * 			  target ID.  (targ_target)
137 *
138 * onoff_arg:		  This is supplied as an argument to port_online()
139 *			  and port_offline().  This is specified by the
140 *			  FETD.
141 *
142 * lun_enable():	  This function is called, with targ_lun_arg, a target
143 *			  ID and a LUN ID as its arguments, by CTL when it
144 *			  wants the FETD to enable a particular LUN.  If the
145 *			  FETD doesn't really know about LUNs, it should
146 *			  just ignore this call and return 0.  If the FETD
147 *			  cannot enable the requested LUN for some reason, the
148 *			  FETD should return non-zero status.
149 *
150 * lun_disable():	  This function is called, with targ_lun_arg, a target
151 *			  ID and LUN ID as its arguments, by CTL when it
152 *			  wants the FETD to disable a particular LUN.  If the
153 *			  FETD doesn't really know about LUNs, it should just
154 *			  ignore this call and return 0.  If the FETD cannot
155 *			  disable the requested LUN for some reason, the
156 *			  FETD should return non-zero status.
157 *
158 * targ_lun_arg:	  This is supplied as an argument to the targ/lun
159 *			  enable/disable() functions.  This is specified by
160 *			  the FETD.
161 *
162 * fe_datamove():	  This function is called one or more times per I/O
163 *			  by the CTL layer to tell the FETD to initiate a
164 *			  DMA to or from the data buffer(s) specified by
165 * 			  the passed-in ctl_io structure.
166 *
167 * fe_done():	  	  This function is called by the CTL layer when a
168 *			  particular SCSI I/O or task management command has
169 * 			  completed.  For SCSI I/O requests (CTL_IO_SCSI),
170 *			  sense data is always supplied if the status is
171 *			  CTL_SCSI_ERROR and the SCSI status byte is
172 *			  SCSI_STATUS_CHECK_COND.  If the FETD doesn't
173 *			  support autosense, the sense should be queued
174 *			  back to the CTL layer via ctl_queue_sense().
175 *
176 * fe_dump():		  This function, if it exists, is called by CTL
177 *			  to request a dump of any debugging information or
178 *			  state to the console.
179 *
180 * max_targets:		  The maximum number of targets that we can create
181 *			  per-port.
182 *
183 * max_target_id:	  The highest target ID that we can use.
184 *
185 * targ_port:		  The CTL layer assigns a "port number" to every
186 *			  FETD.  This port number should be passed back in
187 *			  in the header of every ctl_io that is queued to
188 *			  the CTL layer.  This enables us to determine
189 *			  which bus the command came in on.
190 *
191 * ctl_pool_ref:	  Memory pool reference used by the FETD in calls to
192 * 			  ctl_alloc_io().
193 *
194 * max_initiators:	  Maximum number of initiators that the FETD is
195 *			  allowed to have.  Initiators should be numbered
196 *			  from 0 to max_initiators - 1.  This value will
197 * 			  typically be 16, and thus not a problem for
198 * 			  parallel SCSI.  This may present issues for Fibre
199 *			  Channel.
200 *
201 * wwnn			  World Wide Node Name to be used by the FETD.
202 *			  Note that this is set *after* registration.  It
203 * 			  will be set prior to the online function getting
204 * 			  called.
205 *
206 * wwpn			  World Wide Port Name to be used by the FETD.
207 *			  Note that this is set *after* registration.  It
208 * 			  will be set prior to the online function getting
209 * 			  called.
210 *
211 * status:		  Used by CTL to keep track of per-FETD state.
212 *
213 * links:		  Linked list pointers, used by CTL.  The FETD
214 *			  shouldn't touch this field.
215 */
216struct ctl_port {
217	struct ctl_frontend *frontend;
218	ctl_port_type	port_type;		/* passed to CTL */
219	int		num_requested_ctl_io;	/* passed to CTL */
220	char		*port_name;		/* passed to CTL */
221	int		physical_port;		/* passed to CTL */
222	int		virtual_port;		/* passed to CTL */
223	port_func_t	port_online;		/* passed to CTL */
224	port_func_t	port_offline;		/* passed to CTL */
225	port_info_func_t port_info;		/* passed to CTL */
226	void		*onoff_arg;		/* passed to CTL */
227	lun_func_t	lun_enable;		/* passed to CTL */
228	lun_func_t	lun_disable;		/* passed to CTL */
229	lun_map_func_t	lun_map;		/* passed to CTL */
230	void		*targ_lun_arg;		/* passed to CTL */
231	void		(*fe_datamove)(union ctl_io *io); /* passed to CTL */
232	void		(*fe_done)(union ctl_io *io); /* passed to CTL */
233	int		max_targets;		/* passed to CTL */
234	int		max_target_id;		/* passed to CTL */
235	int32_t		targ_port;		/* passed back to FETD */
236	void		*ctl_pool_ref;		/* passed back to FETD */
237	uint32_t	max_initiators;		/* passed back to FETD */
238	struct ctl_wwpn_iid *wwpn_iid;		/* used by CTL */
239	uint64_t	wwnn;			/* set by CTL before online */
240	uint64_t	wwpn;			/* set by CTL before online */
241	ctl_port_status	status;			/* used by CTL */
242	ctl_options_t	options;		/* passed to CTL */
243	struct ctl_devid *port_devid;		/* passed to CTL */
244	struct ctl_devid *target_devid;		/* passed to CTL */
245	struct ctl_devid *init_devid;		/* passed to CTL */
246	STAILQ_ENTRY(ctl_port) fe_links;	/* used by CTL */
247	STAILQ_ENTRY(ctl_port) links;		/* used by CTL */
248};
249
250struct ctl_frontend {
251	char		name[CTL_DRIVER_NAME_LEN];	/* passed to CTL */
252	fe_init_t	init;			/* passed to CTL */
253	fe_ioctl_t	ioctl;			/* passed to CTL */
254	void		(*fe_dump)(void);	/* passed to CTL */
255	fe_shutdown_t	shutdown;		/* passed to CTL */
256	STAILQ_HEAD(, ctl_port) port_list;	/* used by CTL */
257	STAILQ_ENTRY(ctl_frontend) links;	/* used by CTL */
258};
259
260/*
261 * This may block until resources are allocated.  Called at FETD module load
262 * time. Returns 0 for success, non-zero for failure.
263 */
264int ctl_frontend_register(struct ctl_frontend *fe);
265
266/*
267 * Called at FETD module unload time.
268 * Returns 0 for success, non-zero for failure.
269 */
270int ctl_frontend_deregister(struct ctl_frontend *fe);
271
272/*
273 * Find the frontend by its name. Returns NULL if not found.
274 */
275struct ctl_frontend * ctl_frontend_find(char *frontend_name);
276
277/*
278 * This may block until resources are allocated.  Called at FETD module load
279 * time. Returns 0 for success, non-zero for failure.
280 */
281int ctl_port_register(struct ctl_port *port, int master_SC);
282
283/*
284 * Called at FETD module unload time.
285 * Returns 0 for success, non-zero for failure.
286 */
287int ctl_port_deregister(struct ctl_port *port);
288
289/*
290 * Called to set the WWNN and WWPN for a particular frontend.
291 */
292void ctl_port_set_wwns(struct ctl_port *port, int wwnn_valid,
293			   uint64_t wwnn, int wwpn_valid, uint64_t wwpn);
294
295/*
296 * Called to bring a particular frontend online.
297 */
298void ctl_port_online(struct ctl_port *fe);
299
300/*
301 * Called to take a particular frontend offline.
302 */
303void ctl_port_offline(struct ctl_port *fe);
304
305/*
306 * This routine queues I/O and task management requests from the FETD to the
307 * CTL layer.  Returns immediately.  Returns 0 for success, non-zero for
308 * failure.
309 */
310int ctl_queue(union ctl_io *io);
311
312/*
313 * This routine is used if the front end interface doesn't support
314 * autosense (e.g. non-packetized parallel SCSI).  This will queue the
315 * scsiio structure back to a per-lun pending sense queue.  This MUST be
316 * called BEFORE any request sense can get queued to the CTL layer -- I
317 * need it in the queue in order to service the request.  The scsiio
318 * structure passed in here will be freed by the CTL layer when sense is
319 * retrieved by the initiator.  Returns 0 for success, non-zero for failure.
320 */
321int ctl_queue_sense(union ctl_io *io);
322
323/*
324 * This routine adds an initiator to CTL's port database.
325 * The iid field should be the same as the iid passed in the nexus of each
326 * ctl_io from this initiator.
327 * The WWPN should be the FC WWPN, if available.
328 */
329int ctl_add_initiator(struct ctl_port *port, int iid, uint64_t wwpn, char *name);
330
331/*
332 * This routine will remove an initiator from CTL's port database.
333 * The iid field should be the same as the iid passed in the nexus of each
334 * ctl_io from this initiator.
335 */
336int ctl_remove_initiator(struct ctl_port *port, int iid);
337
338#endif	/* _CTL_FRONTEND_H_ */
339