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: head/sys/cam/ctl/ctl_frontend.h 229997 2012-01-12 00:34:33Z ken $
|
| 31 * $FreeBSD: head/sys/cam/ctl/ctl_frontend.h 254759 2013-08-24 01:50:31Z trasz $ |
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 void (*port_func_t)(void *onoff_arg);
50typedef int (*targ_func_t)(void *arg, struct ctl_id targ_id);
51typedef int (*lun_func_t)(void *arg, struct ctl_id targ_id, int lun_id);
|
52typedef int (*fe_ioctl_t)(struct cdev *dev, u_long cmd, caddr_t addr, int flag,
53 struct thread *td);
54typedef 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 */
206struct 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 */
240int 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 */
246int ctl_frontend_deregister(struct ctl_frontend *fe);
247
248/*
249 * Called to set the WWNN and WWPN for a particular frontend.
250 */
251void 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 */
257void ctl_frontend_online(struct ctl_frontend *fe);
258
259/*
260 * Called to take a particular frontend offline.
261 */
262void 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 */
269int 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 */
280int 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 */
289int 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 */
297int
298ctl_remove_initiator(int32_t targ_port, uint32_t iid);
299
300#endif /* _CTL_FRONTEND_H_ */
|