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