sys/cam/ctl/ctl_frontend.h

   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$
  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
  45 typedef 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
  51 typedef int (*fe_init_t)(void);
  52 typedef int (*fe_shutdown_t)(void);
  53 typedef void (*port_func_t)(void *onoff_arg);
  54 typedef int (*port_info_func_t)(void *onoff_arg, struct sbuf *sb);
  55 typedef int (*lun_func_t)(void *arg, int lun_id);
  56 typedef 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
  85 struct 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  */
 218 struct 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
 256 struct 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  */
 270 int 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  */
 276 int ctl_frontend_deregister(struct ctl_frontend *fe);
 277
 278 /*
 279  * Find the frontend by its name. Returns NULL if not found.
 280  */
 281 struct 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  */
 287 int 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  */
 293 int ctl_port_deregister(struct ctl_port *port);
 294
 295 /*
 296  * Called to set the WWNN and WWPN for a particular frontend.
 297  */
 298 void 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  */
 304 void ctl_port_online(struct ctl_port *fe);
 305
 306 /*
 307  * Called to take a particular frontend offline.
 308  */
 309 void 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  */
 316 int 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  */
 327 int 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  */
 335 int 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  */
 342 int ctl_remove_initiator(struct ctl_port *port, int iid);
 343
 344 #endif  /* _CTL_FRONTEND_H_ */