2 * SPDX-License-Identifier: BSD-2-Clause-FreeBSD
4 * Copyright (c) 2003 Silicon Graphics International Corp.
5 * Copyright (c) 2014-2017 Alexander Motin <mav@FreeBSD.org>
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
11 * 1. Redistributions of source code must retain the above copyright
12 * notice, this list of conditions, and the following disclaimer,
13 * without modification.
14 * 2. Redistributions in binary form must reproduce at minimum a disclaimer
15 * substantially similar to the "NO WARRANTY" disclaimer below
16 * ("Disclaimer") and any redistribution must be conditioned upon
17 * including a substantially similar Disclaimer requirement for further
18 * binary redistribution.
21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
24 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 * HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
29 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
30 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
31 * POSSIBILITY OF SUCH DAMAGES.
33 * $Id: //depot/users/kenm/FreeBSD-test2/sys/cam/ctl/ctl_frontend.h#2 $
37 * CAM Target Layer front end registration hooks
39 * Author: Ken Merry <ken@FreeBSD.org>
42 #ifndef _CTL_FRONTEND_H_
43 #define _CTL_FRONTEND_H_
45 #include <cam/ctl/ctl_ioctl.h>
48 CTL_PORT_STATUS_NONE = 0x00,
49 CTL_PORT_STATUS_ONLINE = 0x01,
50 CTL_PORT_STATUS_HA_SHARED = 0x02
53 typedef int (*fe_init_t)(void);
54 typedef int (*fe_shutdown_t)(void);
55 typedef void (*port_func_t)(void *onoff_arg);
56 typedef int (*port_info_func_t)(void *onoff_arg, struct sbuf *sb);
57 typedef int (*lun_func_t)(void *arg, int lun_id);
58 typedef int (*fe_ioctl_t)(struct cdev *dev, u_long cmd, caddr_t addr, int flag,
61 #define CTL_FRONTEND_DECLARE(name, driver) \
62 static int name ## _modevent(module_t mod, int type, void *data) \
66 return (ctl_frontend_register( \
67 (struct ctl_frontend *)data)); \
70 return (ctl_frontend_deregister( \
71 (struct ctl_frontend *)data)); \
78 static moduledata_t name ## _mod = { \
83 DECLARE_MODULE(name, name ## _mod, SI_SUB_CONFIGURE, SI_ORDER_FOURTH); \
84 MODULE_DEPEND(name, ctl, 1, 1, 1); \
85 MODULE_DEPEND(name, cam, 1, 1, 1)
95 * The ctl_frontend structure is the registration mechanism between a FETD
96 * (Front End Target Driver) and the CTL layer. Here is a description of
99 * port_type: This field tells CTL what kind of front end it is
100 * dealing with. This field serves two purposes.
101 * The first is to let CTL know whether the frontend
102 * in question is inside the main CTL module (i.e.
103 * the ioctl front end), and therefore its module
104 * reference count shouldn't be incremented. The
105 * CTL ioctl front end should continue to use the
106 * CTL_PORT_IOCTL argument as long as it is part of
107 * the main CTL module. The second is to let CTL
108 * know what kind of front end it is dealing with, so
109 * it can return the proper inquiry data for that
112 * num_requested_ctl_io: This is the number of ctl_io structures that the
113 * front end needs for its pool. This should
114 * generally be the maximum number of outstanding
115 * transactions that the FETD can handle. The CTL
116 * layer will add a few to this to account for
117 * ctl_io buffers queued for pending sense data.
118 * (Pending sense only gets queued if the FETD
119 * doesn't support autosense. e.g. non-packetized
120 * parallel SCSI doesn't support autosense.)
122 * port_name: A string describing the FETD. e.g. "LSI 1030T U320"
123 * or whatever you want to use to describe the driver.
125 * physical_port: This is the physical port number of this
126 * particular port within the driver/hardware. This
127 * number is hardware/driver specific.
128 * virtual_port: This is the virtual port number of this
129 * particular port. This is for things like NP-IV.
131 * port_online(): This function is called, with onoff_arg as its
132 * argument, by the CTL layer when it wants the FETD
133 * to start responding to selections on the specified
136 * port_offline(): This function is called, with onoff_arg as its
137 * argument, by the CTL layer when it wants the FETD
138 * to stop responding to selection on the specified
141 * onoff_arg: This is supplied as an argument to port_online()
142 * and port_offline(). This is specified by the
145 * lun_enable(): This function is called, with targ_lun_arg, a target
146 * ID and a LUN ID as its arguments, by CTL when it
147 * wants the FETD to enable a particular LUN. If the
148 * FETD doesn't really know about LUNs, it should
149 * just ignore this call and return 0. If the FETD
150 * cannot enable the requested LUN for some reason, the
151 * FETD should return non-zero status.
153 * lun_disable(): This function is called, with targ_lun_arg, a target
154 * ID and LUN ID as its arguments, by CTL when it
155 * wants the FETD to disable a particular LUN. If the
156 * FETD doesn't really know about LUNs, it should just
157 * ignore this call and return 0. If the FETD cannot
158 * disable the requested LUN for some reason, the
159 * FETD should return non-zero status.
161 * targ_lun_arg: This is supplied as an argument to the targ/lun
162 * enable/disable() functions. This is specified by
165 * fe_datamove(): This function is called one or more times per I/O
166 * by the CTL layer to tell the FETD to initiate a
167 * DMA to or from the data buffer(s) specified by
168 * the passed-in ctl_io structure.
170 * fe_done(): This function is called by the CTL layer when a
171 * particular SCSI I/O or task management command has
172 * completed. For SCSI I/O requests (CTL_IO_SCSI),
173 * sense data is always supplied if the status is
174 * CTL_SCSI_ERROR and the SCSI status byte is
175 * SCSI_STATUS_CHECK_COND. If the FETD doesn't
176 * support autosense, the sense should be queued
177 * back to the CTL layer via ctl_queue_sense().
179 * fe_dump(): This function, if it exists, is called by CTL
180 * to request a dump of any debugging information or
181 * state to the console.
183 * targ_port: The CTL layer assigns a "port number" to every
184 * FETD. This port number should be passed back in
185 * in the header of every ctl_io that is queued to
186 * the CTL layer. This enables us to determine
187 * which bus the command came in on.
189 * ctl_pool_ref: Memory pool reference used by the FETD in calls to
192 * max_initiators: Maximum number of initiators that the FETD is
193 * allowed to have. Initiators should be numbered
194 * from 0 to max_initiators - 1. This value will
195 * typically be 16, and thus not a problem for
196 * parallel SCSI. This may present issues for Fibre
199 * wwnn World Wide Node Name to be used by the FETD.
200 * Note that this is set *after* registration. It
201 * will be set prior to the online function getting
204 * wwpn World Wide Port Name to be used by the FETD.
205 * Note that this is set *after* registration. It
206 * will be set prior to the online function getting
209 * status: Used by CTL to keep track of per-FETD state.
211 * links: Linked list pointers, used by CTL. The FETD
212 * shouldn't touch this field.
215 struct ctl_softc *ctl_softc;
216 struct ctl_frontend *frontend;
217 ctl_port_type port_type; /* passed to CTL */
218 int num_requested_ctl_io; /* passed to CTL */
219 char *port_name; /* passed to CTL */
220 int physical_port; /* passed to CTL */
221 int virtual_port; /* passed to CTL */
222 port_func_t port_online; /* passed to CTL */
223 port_func_t port_offline; /* passed to CTL */
224 port_info_func_t port_info; /* passed to CTL */
225 void *onoff_arg; /* passed to CTL */
226 lun_func_t lun_enable; /* passed to CTL */
227 lun_func_t lun_disable; /* passed to CTL */
228 int lun_map_size; /* passed to CTL */
229 uint32_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 int32_t targ_port; /* passed back to FETD */
234 void *ctl_pool_ref; /* passed back to FETD */
235 uint32_t max_initiators; /* passed back to FETD */
236 struct ctl_wwpn_iid *wwpn_iid; /* used by CTL */
237 uint64_t wwnn; /* set by CTL before online */
238 uint64_t wwpn; /* set by CTL before online */
239 ctl_port_status status; /* used by CTL */
240 ctl_options_t options; /* passed to CTL */
241 struct ctl_devid *port_devid; /* passed to CTL */
242 struct ctl_devid *target_devid; /* passed to CTL */
243 struct ctl_devid *init_devid; /* passed to CTL */
244 struct ctl_io_stats stats; /* used by CTL */
245 struct mtx port_lock; /* used by CTL */
246 STAILQ_ENTRY(ctl_port) fe_links; /* used by CTL */
247 STAILQ_ENTRY(ctl_port) links; /* used by CTL */
250 struct 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 */
261 * This may block until resources are allocated. Called at FETD module load
262 * time. Returns 0 for success, non-zero for failure.
264 int ctl_frontend_register(struct ctl_frontend *fe);
267 * Called at FETD module unload time.
268 * Returns 0 for success, non-zero for failure.
270 int ctl_frontend_deregister(struct ctl_frontend *fe);
273 * Find the frontend by its name. Returns NULL if not found.
275 struct ctl_frontend * ctl_frontend_find(char *frontend_name);
278 * This may block until resources are allocated. Called at FETD module load
279 * time. Returns 0 for success, non-zero for failure.
281 int ctl_port_register(struct ctl_port *port);
284 * Called at FETD module unload time.
285 * Returns 0 for success, non-zero for failure.
287 int ctl_port_deregister(struct ctl_port *port);
290 * Called to set the WWNN and WWPN for a particular frontend.
292 void ctl_port_set_wwns(struct ctl_port *port, int wwnn_valid,
293 uint64_t wwnn, int wwpn_valid, uint64_t wwpn);
296 * Called to bring a particular frontend online.
298 void ctl_port_online(struct ctl_port *fe);
301 * Called to take a particular frontend offline.
303 void ctl_port_offline(struct ctl_port *fe);
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
310 int ctl_queue(union ctl_io *io);
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.
321 int ctl_queue_sense(union ctl_io *io);
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.
329 int ctl_add_initiator(struct ctl_port *port, int iid, uint64_t wwpn, char *name);
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.
336 int ctl_remove_initiator(struct ctl_port *port, int iid);
338 #endif /* _CTL_FRONTEND_H_ */