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$ 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 42 typedef 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 49 typedef void (*port_func_t)(void *onoff_arg); 50 typedef int (*targ_func_t)(void *arg, struct ctl_id targ_id); 51 typedef int (*lun_func_t)(void *arg, struct ctl_id targ_id, int lun_id); 52 typedef int (*fe_ioctl_t)(struct cdev *dev, u_long cmd, caddr_t addr, int flag, 53 struct thread *td); 54 typedef 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 */ 206 struct 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 */ 240 int 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 */ 246 int ctl_frontend_deregister(struct ctl_frontend *fe); 247 248 /* 249 * Called to set the WWNN and WWPN for a particular frontend. 250 */ 251 void 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 */ 257 void ctl_frontend_online(struct ctl_frontend *fe); 258 259 /* 260 * Called to take a particular frontend offline. 261 */ 262 void 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 */ 269 int 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 */ 280 int 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 */ 289 int 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 */ 297 int 298 ctl_remove_initiator(int32_t targ_port, uint32_t iid); 299 300 #endif /* _CTL_FRONTEND_H_ */ 301