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