xref: /freebsd/sys/cam/ctl/ctl_frontend.h (revision 0782240958117692ab9861abb5483c9e64f6bc39)
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 
42 typedef 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 
49 typedef void (*port_func_t)(void *onoff_arg);
50 typedef int (*targ_func_t)(void *arg, struct ctl_id targ_id);
51 typedef	int (*lun_func_t)(void *arg, struct ctl_id targ_id, int lun_id);
52 typedef int (*fe_ioctl_t)(struct cdev *dev, u_long cmd, caddr_t addr, int flag,
53 			  struct thread *td);
54 typedef int (*fe_devid_t)(struct ctl_scsiio *ctsio, int alloc_len);
55 
56 /*
57  * The ctl_frontend structure is the registration mechanism between a FETD
58  * (Front End Target Driver) and the CTL layer.  Here is a description of
59  * the fields:
60  *
61  * port_type:		  This field tells CTL what kind of front end it is
62  *                        dealing with.  This field serves two purposes.
63  *                        The first is to let CTL know whether the frontend
64  *                        in question is inside the main CTL module (i.e.
65  *                        the ioctl front end), and therefore its module
66  *                        reference count shouldn't be incremented.  The
67  *                        CTL ioctl front end should continue to use the
68  *                        CTL_PORT_IOCTL argument as long as it is part of
69  *                        the main CTL module.  The second is to let CTL
70  *                        know what kind of front end it is dealing with, so
71  *                        it can return the proper inquiry data for that
72  *                        particular port.
73  *
74  * num_requested_ctl_io:  This is the number of ctl_io structures that the
75  *			  front end needs for its pool.  This should
76  * 			  generally be the maximum number of outstanding
77  *			  transactions that the FETD can handle.  The CTL
78  *			  layer will add a few to this to account for
79  *			  ctl_io buffers queued for pending sense data.
80  *			  (Pending sense only gets queued if the FETD
81  * 			  doesn't support autosense.  e.g. non-packetized
82  * 			  parallel SCSI doesn't support autosense.)
83  *
84  * port_name:		  A string describing the FETD.  e.g. "LSI 1030T U320"
85  *			  or whatever you want to use to describe the driver.
86  *
87  *
88  * physical_port:	  This is the physical port number of this
89  * 			  particular port within the driver/hardware.  This
90  * 			  number is hardware/driver specific.
91  * virtual_port:	  This is the virtual port number of this
92  * 			  particular port.  This is for things like NP-IV.
93  *
94  * port_online():	  This function is called, with onoff_arg as its
95  *			  argument, by the CTL layer when it wants the FETD
96  *			  to start responding to selections on the specified
97  * 			  target ID.  (targ_target)
98  *
99  * port_offline():	  This function is called, with onoff_arg as its
100  *			  argument, by the CTL layer when it wants the FETD
101  * 			  to stop responding to selection on the specified
102  * 			  target ID.  (targ_target)
103  *
104  * onoff_arg:		  This is supplied as an argument to port_online()
105  *			  and port_offline().  This is specified by the
106  *			  FETD.
107  *
108  * targ_enable():	  This function is called, with targ_lun_arg and a
109  * 			  target ID as its arguments, by CTL when it wants
110  *			  the FETD to enable a particular target.  targ_enable()
111  *			  will always be called for a particular target ID
112  * 			  before any LUN is enabled for that target.  If the
113  *			  FETD does not support enabling targets, but rather
114  *			  LUNs, it should ignore this call and return 0.  If
115  *			  the FETD does support enabling targets, it should
116  *			  return 0 for success and non-zero if it cannot
117  *			  enable the given target.
118  *
119  *			  TODO:  Add the ability to specify a WWID here.
120  *
121  * targ_disable():	  This function is called, with targ_lun_arg and a
122  *			  target ID as its arguments, by CTL when it wants
123  *			  the FETD to disable a particular target.
124  *			  targ_disable() will always be called for a
125  *			  particular target ID after all LUNs are disabled
126  *			  on that particular target.  If the FETD does not
127  *			  support enabling targets, it should ignore this
128  *			  call and return 0.  If the FETD does support
129  *			  enabling targets, it should return 0 for success,
130  *			  and non-zero if it cannot disable the given target.
131  *
132  * lun_enable():	  This function is called, with targ_lun_arg, a target
133  *			  ID and a LUN ID as its arguments, by CTL when it
134  *			  wants the FETD to enable a particular LUN.  If the
135  *			  FETD doesn't really know about LUNs, it should
136  *			  just ignore this call and return 0.  If the FETD
137  *			  cannot enable the requested LUN for some reason, the
138  *			  FETD should return non-zero status.
139  *
140  * lun_disable():	  This function is called, with targ_lun_arg, a target
141  *			  ID and LUN ID as its arguments, by CTL when it
142  *			  wants the FETD to disable a particular LUN.  If the
143  *			  FETD doesn't really know about LUNs, it should just
144  *			  ignore this call and return 0.  If the FETD cannot
145  *			  disable the requested LUN for some reason, the
146  *			  FETD should return non-zero status.
147  *
148  * targ_lun_arg:	  This is supplied as an argument to the targ/lun
149  *			  enable/disable() functions.  This is specified by
150  *			  the FETD.
151  *
152  * fe_datamove():	  This function is called one or more times per I/O
153  *			  by the CTL layer to tell the FETD to initiate a
154  *			  DMA to or from the data buffer(s) specified by
155  * 			  the passed-in ctl_io structure.
156  *
157  * fe_done():	  	  This function is called by the CTL layer when a
158  *			  particular SCSI I/O or task management command has
159  * 			  completed.  For SCSI I/O requests (CTL_IO_SCSI),
160  *			  sense data is always supplied if the status is
161  *			  CTL_SCSI_ERROR and the SCSI status byte is
162  *			  SCSI_STATUS_CHECK_COND.  If the FETD doesn't
163  *			  support autosense, the sense should be queued
164  *			  back to the CTL layer via ctl_queue_sense().
165  *
166  * fe_dump():		  This function, if it exists, is called by CTL
167  *			  to request a dump of any debugging information or
168  *			  state to the console.
169  *
170  * max_targets:		  The maximum number of targets that we can create
171  *			  per-port.
172  *
173  * max_target_id:	  The highest target ID that we can use.
174  *
175  * targ_port:		  The CTL layer assigns a "port number" to every
176  *			  FETD.  This port number should be passed back in
177  *			  in the header of every ctl_io that is queued to
178  *			  the CTL layer.  This enables us to determine
179  *			  which bus the command came in on.
180  *
181  * ctl_pool_ref:	  Memory pool reference used by the FETD in calls to
182  * 			  ctl_alloc_io().
183  *
184  * max_initiators:	  Maximum number of initiators that the FETD is
185  *			  allowed to have.  Initiators should be numbered
186  *			  from 0 to max_initiators - 1.  This value will
187  * 			  typically be 16, and thus not a problem for
188  * 			  parallel SCSI.  This may present issues for Fibre
189  *			  Channel.
190  *
191  * wwnn			  World Wide Node Name to be used by the FETD.
192  *			  Note that this is set *after* registration.  It
193  * 			  will be set prior to the online function getting
194  * 			  called.
195  *
196  * wwpn			  World Wide Port Name to be used by the FETD.
197  *			  Note that this is set *after* registration.  It
198  * 			  will be set prior to the online function getting
199  * 			  called.
200  *
201  * status:		  Used by CTL to keep track of per-FETD state.
202  *
203  * links:		  Linked list pointers, used by CTL.  The FETD
204  *			  shouldn't touch this field.
205  */
206 struct ctl_frontend {
207 	ctl_port_type	port_type;		/* passed to CTL */
208 	int		num_requested_ctl_io;	/* passed to CTL */
209 	char		*port_name;		/* passed to CTL */
210 	int		physical_port;		/* passed to CTL */
211 	int		virtual_port;		/* passed to CTL */
212 	port_func_t	port_online;		/* passed to CTL */
213 	port_func_t	port_offline;		/* passed to CTL */
214 	void		*onoff_arg;		/* passed to CTL */
215 	targ_func_t	targ_enable;		/* passed to CTL */
216 	targ_func_t	targ_disable;		/* passed to CTL */
217 	lun_func_t	lun_enable;		/* passed to CTL */
218 	lun_func_t	lun_disable;		/* passed to CTL */
219 	fe_ioctl_t	ioctl;			/* passed to CTL */
220 	fe_devid_t	devid;			/* passed to CTL */
221 	void		*targ_lun_arg;		/* passed to CTL */
222 	void		(*fe_datamove)(union ctl_io *io); /* passed to CTL */
223 	void		(*fe_done)(union ctl_io *io); /* passed to CTL */
224 	void		(*fe_dump)(void);	/* passed to CTL */
225 	int		max_targets;		/* passed to CTL */
226 	int		max_target_id;		/* passed to CTL */
227 	int32_t		targ_port;		/* passed back to FETD */
228 	void		*ctl_pool_ref;		/* passed back to FETD */
229 	uint32_t	max_initiators;		/* passed back to FETD */
230 	uint64_t	wwnn;			/* set by CTL before online */
231 	uint64_t	wwpn;			/* set by CTL before online */
232 	ctl_port_status	status;			/* used by CTL */
233 	STAILQ_ENTRY(ctl_frontend) links;	/* used by CTL */
234 };
235 
236 /*
237  * This may block until resources are allocated.  Called at FETD module load
238  * time. Returns 0 for success, non-zero for failure.
239  */
240 int ctl_frontend_register(struct ctl_frontend *fe, int master_SC);
241 
242 /*
243  * Called at FETD module unload time.
244  * Returns 0 for success, non-zero for failure.
245  */
246 int ctl_frontend_deregister(struct ctl_frontend *fe);
247 
248 /*
249  * Called to set the WWNN and WWPN for a particular frontend.
250  */
251 void ctl_frontend_set_wwns(struct ctl_frontend *fe, int wwnn_valid,
252 			   uint64_t wwnn, int wwpn_valid, uint64_t wwpn);
253 
254 /*
255  * Called to bring a particular frontend online.
256  */
257 void ctl_frontend_online(struct ctl_frontend *fe);
258 
259 /*
260  * Called to take a particular frontend offline.
261  */
262 void ctl_frontend_offline(struct ctl_frontend *fe);
263 
264 /*
265  * This routine queues I/O and task management requests from the FETD to the
266  * CTL layer.  Returns immediately.  Returns 0 for success, non-zero for
267  * failure.
268  */
269 int ctl_queue(union ctl_io *io);
270 
271 /*
272  * This routine is used if the front end interface doesn't support
273  * autosense (e.g. non-packetized parallel SCSI).  This will queue the
274  * scsiio structure back to a per-lun pending sense queue.  This MUST be
275  * called BEFORE any request sense can get queued to the CTL layer -- I
276  * need it in the queue in order to service the request.  The scsiio
277  * structure passed in here will be freed by the CTL layer when sense is
278  * retrieved by the initiator.  Returns 0 for success, non-zero for failure.
279  */
280 int ctl_queue_sense(union ctl_io *io);
281 
282 /*
283  * This routine adds an initiator to CTL's port database.  The WWPN should
284  * be the FC WWPN, if available.  The targ_port field should be the same as
285  * the targ_port passed back from CTL in the ctl_frontend structure above.
286  * The iid field should be the same as the iid passed in the nexus of each
287  * ctl_io from this initiator.
288  */
289 int ctl_add_initiator(uint64_t wwpn, int32_t targ_port, uint32_t iid);
290 
291 /*
292  * This routine will remove an initiator from CTL's port database.  The
293  * targ_port field should be the same as the targ_port passed back in the
294  * ctl_frontend structure above.  The iid field should be the same as the
295  * iid passed in the nexus of each ctl_io from this initiator.
296  */
297 int
298 ctl_remove_initiator(int32_t targ_port, uint32_t iid);
299 
300 #endif	/* _CTL_FRONTEND_H_ */
301