sys/cam/ctl/ctl_frontend.h

   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_ */