ctl_frontend.h revision 284798
138716Smsmith/*- 238716Smsmith * Copyright (c) 2003 Silicon Graphics International Corp. 338716Smsmith * All rights reserved. 438716Smsmith * 538716Smsmith * Redistribution and use in source and binary forms, with or without 638716Smsmith * modification, are permitted provided that the following conditions 738716Smsmith * are met: 838716Smsmith * 1. Redistributions of source code must retain the above copyright 938716Smsmith * notice, this list of conditions, and the following disclaimer, 1038716Smsmith * without modification. 1138716Smsmith * 2. Redistributions in binary form must reproduce at minimum a disclaimer 1238716Smsmith * substantially similar to the "NO WARRANTY" disclaimer below 1338716Smsmith * ("Disclaimer") and any redistribution must be conditioned upon 1450477Speter * including a substantially similar Disclaimer requirement for further 1538716Smsmith * binary redistribution. 1638716Smsmith * 1738716Smsmith * NO WARRANTY 1838716Smsmith * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 1938716Smsmith * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 2038716Smsmith * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR 2164187Sjhb * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 2238716Smsmith * HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 2338716Smsmith * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 2438716Smsmith * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 2538716Smsmith * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 2638716Smsmith * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 2738716Smsmith * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 2838716Smsmith * POSSIBILITY OF SUCH DAMAGES. 2938716Smsmith * 3038716Smsmith * $Id: //depot/users/kenm/FreeBSD-test2/sys/cam/ctl/ctl_frontend.h#2 $ 3138716Smsmith * $FreeBSD: stable/10/sys/cam/ctl/ctl_frontend.h 284798 2015-06-25 07:11:48Z mav $ 3238716Smsmith */ 3338716Smsmith/* 3438716Smsmith * CAM Target Layer front end registration hooks 3538716Smsmith * 3638716Smsmith * Author: Ken Merry <ken@FreeBSD.org> 3738716Smsmith */ 3838716Smsmith 3938716Smsmith#ifndef _CTL_FRONTEND_H_ 4038716Smsmith#define _CTL_FRONTEND_H_ 4138716Smsmith 4238716Smsmithtypedef enum { 4338716Smsmith CTL_PORT_STATUS_NONE = 0x00, 4438716Smsmith CTL_PORT_STATUS_ONLINE = 0x01 4538716Smsmith} ctl_port_status; 4638716Smsmith 4738716Smsmithtypedef int (*fe_init_t)(void); 4838716Smsmithtypedef void (*fe_shutdown_t)(void); 4938716Smsmithtypedef void (*port_func_t)(void *onoff_arg); 5038716Smsmithtypedef int (*port_info_func_t)(void *onoff_arg, struct sbuf *sb); 5138716Smsmithtypedef int (*lun_func_t)(void *arg, int lun_id); 5238716Smsmithtypedef int (*fe_ioctl_t)(struct cdev *dev, u_long cmd, caddr_t addr, int flag, 5338716Smsmith struct thread *td); 5438716Smsmith 5538716Smsmith#define CTL_FRONTEND_DECLARE(name, driver) \ 5642465Smsmith static int name ## _modevent(module_t mod, int type, void *data) \ 5738765Sjkh { \ 5838765Sjkh switch (type) { \ 5942465Smsmith case MOD_LOAD: \ 6038765Sjkh ctl_frontend_register( \ 6138765Sjkh (struct ctl_frontend *)data); \ 6238765Sjkh break; \ 6338765Sjkh case MOD_UNLOAD: \ 6438716Smsmith printf(#name " module unload - not possible for this module type\n"); \ 6538716Smsmith return EINVAL; \ 6638716Smsmith default: \ 6738716Smsmith return EOPNOTSUPP; \ 6838716Smsmith } \ 6938716Smsmith return 0; \ 7038716Smsmith } \ 7138716Smsmith static moduledata_t name ## _mod = { \ 7238716Smsmith #name, \ 7338716Smsmith name ## _modevent, \ 7438716Smsmith (void *)&driver \ 7538716Smsmith }; \ 7638716Smsmith DECLARE_MODULE(name, name ## _mod, SI_SUB_CONFIGURE, SI_ORDER_FOURTH); \ 7738716Smsmith MODULE_DEPEND(name, ctl, 1, 1, 1); \ 7838716Smsmith MODULE_DEPEND(name, cam, 1, 1, 1) 7938716Smsmith 8038716Smsmithstruct ctl_wwpn_iid { 8138716Smsmith int in_use; 8238716Smsmith time_t last_use; 8338716Smsmith uint64_t wwpn; 8438716Smsmith char *name; 8538716Smsmith}; 8638716Smsmith 8738716Smsmith/* 8838716Smsmith * The ctl_frontend structure is the registration mechanism between a FETD 8938716Smsmith * (Front End Target Driver) and the CTL layer. Here is a description of 9038716Smsmith * the fields: 9138716Smsmith * 9238716Smsmith * port_type: This field tells CTL what kind of front end it is 9338716Smsmith * dealing with. This field serves two purposes. 9438716Smsmith * The first is to let CTL know whether the frontend 9538716Smsmith * in question is inside the main CTL module (i.e. 9638716Smsmith * the ioctl front end), and therefore its module 9738716Smsmith * reference count shouldn't be incremented. The 9838716Smsmith * CTL ioctl front end should continue to use the 9938716Smsmith * CTL_PORT_IOCTL argument as long as it is part of 10038716Smsmith * the main CTL module. The second is to let CTL 10138716Smsmith * know what kind of front end it is dealing with, so 10238716Smsmith * it can return the proper inquiry data for that 10338716Smsmith * particular port. 10438716Smsmith * 10538716Smsmith * num_requested_ctl_io: This is the number of ctl_io structures that the 10638716Smsmith * front end needs for its pool. This should 10738716Smsmith * generally be the maximum number of outstanding 10838716Smsmith * transactions that the FETD can handle. The CTL 10938716Smsmith * layer will add a few to this to account for 11038716Smsmith * ctl_io buffers queued for pending sense data. 11138716Smsmith * (Pending sense only gets queued if the FETD 11238716Smsmith * doesn't support autosense. e.g. non-packetized 11338716Smsmith * parallel SCSI doesn't support autosense.) 11438716Smsmith * 11538716Smsmith * port_name: A string describing the FETD. e.g. "LSI 1030T U320" 11638716Smsmith * or whatever you want to use to describe the driver. 11738716Smsmith * 11838716Smsmith * 11938716Smsmith * physical_port: This is the physical port number of this 12038716Smsmith * particular port within the driver/hardware. This 12138716Smsmith * number is hardware/driver specific. 12238716Smsmith * virtual_port: This is the virtual port number of this 12338716Smsmith * particular port. This is for things like NP-IV. 12438716Smsmith * 12538716Smsmith * port_online(): This function is called, with onoff_arg as its 12638716Smsmith * argument, by the CTL layer when it wants the FETD 12738716Smsmith * to start responding to selections on the specified 12838716Smsmith * target ID. (targ_target) 12938716Smsmith * 13038716Smsmith * port_offline(): This function is called, with onoff_arg as its 13138716Smsmith * argument, by the CTL layer when it wants the FETD 13238716Smsmith * to stop responding to selection on the specified 13338716Smsmith * target ID. (targ_target) 13438716Smsmith * 13538716Smsmith * onoff_arg: This is supplied as an argument to port_online() 13638716Smsmith * and port_offline(). This is specified by the 13738716Smsmith * FETD. 13838716Smsmith * 13938716Smsmith * lun_enable(): This function is called, with targ_lun_arg, a target 14038716Smsmith * ID and a LUN ID as its arguments, by CTL when it 14138716Smsmith * wants the FETD to enable a particular LUN. If the 14238716Smsmith * FETD doesn't really know about LUNs, it should 14338716Smsmith * just ignore this call and return 0. If the FETD 14438716Smsmith * cannot enable the requested LUN for some reason, the 14538716Smsmith * FETD should return non-zero status. 14638716Smsmith * 14738716Smsmith * lun_disable(): This function is called, with targ_lun_arg, a target 14838716Smsmith * ID and LUN ID as its arguments, by CTL when it 14938716Smsmith * wants the FETD to disable a particular LUN. If the 15038716Smsmith * FETD doesn't really know about LUNs, it should just 15138716Smsmith * ignore this call and return 0. If the FETD cannot 15238716Smsmith * disable the requested LUN for some reason, the 15338716Smsmith * FETD should return non-zero status. 15438716Smsmith * 15538716Smsmith * targ_lun_arg: This is supplied as an argument to the targ/lun 15638716Smsmith * enable/disable() functions. This is specified by 15738716Smsmith * the FETD. 15838716Smsmith * 15938716Smsmith * fe_datamove(): This function is called one or more times per I/O 16038716Smsmith * by the CTL layer to tell the FETD to initiate a 16138716Smsmith * DMA to or from the data buffer(s) specified by 16238716Smsmith * the passed-in ctl_io structure. 16338716Smsmith * 16438716Smsmith * fe_done(): This function is called by the CTL layer when a 16538716Smsmith * particular SCSI I/O or task management command has 16638716Smsmith * completed. For SCSI I/O requests (CTL_IO_SCSI), 167 * sense data is always supplied if the status is 168 * CTL_SCSI_ERROR and the SCSI status byte is 169 * SCSI_STATUS_CHECK_COND. If the FETD doesn't 170 * support autosense, the sense should be queued 171 * back to the CTL layer via ctl_queue_sense(). 172 * 173 * fe_dump(): This function, if it exists, is called by CTL 174 * to request a dump of any debugging information or 175 * state to the console. 176 * 177 * max_targets: The maximum number of targets that we can create 178 * per-port. 179 * 180 * max_target_id: The highest target ID that we can use. 181 * 182 * targ_port: The CTL layer assigns a "port number" to every 183 * FETD. This port number should be passed back in 184 * in the header of every ctl_io that is queued to 185 * the CTL layer. This enables us to determine 186 * which bus the command came in on. 187 * 188 * ctl_pool_ref: Memory pool reference used by the FETD in calls to 189 * ctl_alloc_io(). 190 * 191 * max_initiators: Maximum number of initiators that the FETD is 192 * allowed to have. Initiators should be numbered 193 * from 0 to max_initiators - 1. This value will 194 * typically be 16, and thus not a problem for 195 * parallel SCSI. This may present issues for Fibre 196 * Channel. 197 * 198 * wwnn World Wide Node Name to be used by the FETD. 199 * Note that this is set *after* registration. It 200 * will be set prior to the online function getting 201 * called. 202 * 203 * wwpn World Wide Port Name to be used by the FETD. 204 * Note that this is set *after* registration. It 205 * will be set prior to the online function getting 206 * called. 207 * 208 * status: Used by CTL to keep track of per-FETD state. 209 * 210 * links: Linked list pointers, used by CTL. The FETD 211 * shouldn't touch this field. 212 */ 213struct ctl_port { 214 struct ctl_frontend *frontend; 215 ctl_port_type port_type; /* passed to CTL */ 216 int num_requested_ctl_io; /* passed to CTL */ 217 char *port_name; /* passed to CTL */ 218 int physical_port; /* passed to CTL */ 219 int virtual_port; /* passed to CTL */ 220 port_func_t port_online; /* passed to CTL */ 221 port_func_t port_offline; /* passed to CTL */ 222 port_info_func_t port_info; /* passed to CTL */ 223 void *onoff_arg; /* passed to CTL */ 224 lun_func_t lun_enable; /* passed to CTL */ 225 lun_func_t lun_disable; /* passed to CTL */ 226 uint32_t *lun_map; /* passed to CTL */ 227 void *targ_lun_arg; /* passed to CTL */ 228 void (*fe_datamove)(union ctl_io *io); /* passed to CTL */ 229 void (*fe_done)(union ctl_io *io); /* passed to CTL */ 230 int max_targets; /* passed to CTL */ 231 int max_target_id; /* passed to CTL */ 232 int32_t targ_port; /* passed back to FETD */ 233 void *ctl_pool_ref; /* passed back to FETD */ 234 uint32_t max_initiators; /* passed back to FETD */ 235 struct ctl_wwpn_iid *wwpn_iid; /* used by CTL */ 236 uint64_t wwnn; /* set by CTL before online */ 237 uint64_t wwpn; /* set by CTL before online */ 238 ctl_port_status status; /* used by CTL */ 239 ctl_options_t options; /* passed to CTL */ 240 struct ctl_devid *port_devid; /* passed to CTL */ 241 struct ctl_devid *target_devid; /* passed to CTL */ 242 struct ctl_devid *init_devid; /* passed to CTL */ 243 STAILQ_ENTRY(ctl_port) fe_links; /* used by CTL */ 244 STAILQ_ENTRY(ctl_port) links; /* used by CTL */ 245}; 246 247struct ctl_frontend { 248 char name[CTL_DRIVER_NAME_LEN]; /* passed to CTL */ 249 fe_init_t init; /* passed to CTL */ 250 fe_ioctl_t ioctl; /* passed to CTL */ 251 void (*fe_dump)(void); /* passed to CTL */ 252 fe_shutdown_t shutdown; /* passed to CTL */ 253 STAILQ_HEAD(, ctl_port) port_list; /* used by CTL */ 254 STAILQ_ENTRY(ctl_frontend) links; /* used by CTL */ 255}; 256 257/* 258 * This may block until resources are allocated. Called at FETD module load 259 * time. Returns 0 for success, non-zero for failure. 260 */ 261int ctl_frontend_register(struct ctl_frontend *fe); 262 263/* 264 * Called at FETD module unload time. 265 * Returns 0 for success, non-zero for failure. 266 */ 267int ctl_frontend_deregister(struct ctl_frontend *fe); 268 269/* 270 * Find the frontend by its name. Returns NULL if not found. 271 */ 272struct ctl_frontend * ctl_frontend_find(char *frontend_name); 273 274/* 275 * This may block until resources are allocated. Called at FETD module load 276 * time. Returns 0 for success, non-zero for failure. 277 */ 278int ctl_port_register(struct ctl_port *port); 279 280/* 281 * Called at FETD module unload time. 282 * Returns 0 for success, non-zero for failure. 283 */ 284int ctl_port_deregister(struct ctl_port *port); 285 286/* 287 * Called to set the WWNN and WWPN for a particular frontend. 288 */ 289void ctl_port_set_wwns(struct ctl_port *port, int wwnn_valid, 290 uint64_t wwnn, int wwpn_valid, uint64_t wwpn); 291 292/* 293 * Called to bring a particular frontend online. 294 */ 295void ctl_port_online(struct ctl_port *fe); 296 297/* 298 * Called to take a particular frontend offline. 299 */ 300void ctl_port_offline(struct ctl_port *fe); 301 302/* 303 * This routine queues I/O and task management requests from the FETD to the 304 * CTL layer. Returns immediately. Returns 0 for success, non-zero for 305 * failure. 306 */ 307int ctl_queue(union ctl_io *io); 308 309/* 310 * This routine is used if the front end interface doesn't support 311 * autosense (e.g. non-packetized parallel SCSI). This will queue the 312 * scsiio structure back to a per-lun pending sense queue. This MUST be 313 * called BEFORE any request sense can get queued to the CTL layer -- I 314 * need it in the queue in order to service the request. The scsiio 315 * structure passed in here will be freed by the CTL layer when sense is 316 * retrieved by the initiator. Returns 0 for success, non-zero for failure. 317 */ 318int ctl_queue_sense(union ctl_io *io); 319 320/* 321 * This routine adds an initiator to CTL's port database. 322 * The iid field should be the same as the iid passed in the nexus of each 323 * ctl_io from this initiator. 324 * The WWPN should be the FC WWPN, if available. 325 */ 326int ctl_add_initiator(struct ctl_port *port, int iid, uint64_t wwpn, char *name); 327 328/* 329 * This routine will remove an initiator from CTL's port database. 330 * The iid field should be the same as the iid passed in the nexus of each 331 * ctl_io from this initiator. 332 */ 333int ctl_remove_initiator(struct ctl_port *port, int iid); 334 335#endif /* _CTL_FRONTEND_H_ */ 336