sys/cam/ctl/README.ctl.txt

   1 /* $FreeBSD$ */
   2
   3 CTL - CAM Target Layer Description
   4
   5 Revision 1.4 (December 29th, 2011)
   6 Ken Merry <ken@FreeBSD.org>
   7
   8 Table of Contents:
   9 =================
  10
  11 Introduction
  12 Features
  13 Configuring and Running CTL
  14 Revision 1.N Changes
  15 To Do List
  16 Code Roadmap
  17 Userland Commands
  18
  19 Introduction:
  20 ============
  21
  22 CTL is a disk and processor device emulation subsystem originally written
  23 for Copan Systems under Linux starting in 2003.  It has been shipping in
  24 Copan (now SGI) products since 2005.
  25
  26 It was ported to FreeBSD in 2008, and thanks to an agreement between SGI
  27 (who acquired Copan's assets in 2010) and Spectra Logic in 2010, CTL is
  28 available under a BSD-style license.  The intent behind the agreement was
  29 that Spectra would work to get CTL into the FreeBSD tree.
  30
  31 Features:
  32 ========
  33
  34  - Disk and processor device emulation.
  35  - Tagged queueing
  36  - SCSI task attribute support (ordered, head of queue, simple tags)
  37  - SCSI implicit command ordering support.  (e.g. if a read follows a mode
  38    select, the read will be blocked until the mode select completes.)
  39  - Full task management support (abort, LUN reset, target reset, etc.)
  40  - Support for multiple ports
  41  - Support for multiple simultaneous initiators
  42  - Support for multiple simultaneous backing stores
  43  - Persistent reservation support
  44  - Mode sense/select support
  45  - Error injection support
  46  - High Availability support
  47  - All I/O handled in-kernel, no userland context switch overhead.
  48
  49 Configuring and Running CTL:
  50 ===========================
  51
  52  - After applying the CTL patchset to your tree, build world and install it
  53    on your target system.
  54
  55  - Add 'device ctl' to your kernel configuration file.
  56
  57  - If you're running with a 8Gb or 4Gb Qlogic FC board, add
  58    'options ISP_TARGET_MODE' to your kernel config file.  Keep in mind that
  59    the isp(4) driver can run in target or initiator mode, but not both on
  60    the same machine.  'device ispfw' or loading the ispfw module is also
  61    recommended.
  62
  63  - Rebuild and install a new kernel.
  64
  65  - Reboot with the new kernel.
  66
  67  - To add a LUN with the RAM disk backend:
  68
  69         ctladm create -b ramdisk -s 10485760000000000000
  70         ctladm port -o on
  71
  72  - You should now see the CTL disk LUN through camcontrol devlist:
  73
  74 scbus6 on ctl2cam0 bus 0:
  75 <FREEBSD CTLDISK 0001>             at scbus6 target 1 lun 0 (da24,pass32)
  76 <>                                 at scbus6 target -1 lun -1 ()
  77
  78    This is visible through the CTL CAM SIM.  This allows using CTL without
  79    any physical hardware.  You should be able to issue any normal SCSI
  80    commands to the device via the pass(4)/da(4) devices.
  81
  82    If any target-capable HBAs are in the system (e.g. isp(4)), and have
  83    target mode enabled, you should now also be able to see the CTL LUNs via
  84    that target interface.
  85
  86    Note that all CTL LUNs are presented to all frontends.  There is no
  87    LUN masking, or separate, per-port configuration.
  88
  89  - Note that the ramdisk backend is a "fake" ramdisk.  That is, it is
  90    backed by a small amount of RAM that is used for all I/O requests.  This
  91    is useful for performance testing, but not for any data integrity tests.
  92
  93  - To add a LUN with the block/file backend:
  94
  95         truncate -s +1T myfile
  96         ctladm create -b block -o file=myfile
  97         ctladm port -o on
  98
  99  - You can also see a list of LUNs and their backends like this:
 100
 101 # ctladm devlist
 102 LUN Backend       Size (Blocks)   BS Serial Number    Device ID
 103   0 block            2147483648  512 MYSERIAL   0     MYDEVID   0
 104   1 block            2147483648  512 MYSERIAL   1     MYDEVID   1
 105   2 block            2147483648  512 MYSERIAL   2     MYDEVID   2
 106   3 block            2147483648  512 MYSERIAL   3     MYDEVID   3
 107   4 block            2147483648  512 MYSERIAL   4     MYDEVID   4
 108   5 block            2147483648  512 MYSERIAL   5     MYDEVID   5
 109   6 block            2147483648  512 MYSERIAL   6     MYDEVID   6
 110   7 block            2147483648  512 MYSERIAL   7     MYDEVID   7
 111   8 block            2147483648  512 MYSERIAL   8     MYDEVID   8
 112   9 block            2147483648  512 MYSERIAL   9     MYDEVID   9
 113  10 block            2147483648  512 MYSERIAL  10     MYDEVID  10
 114  11 block            2147483648  512 MYSERIAL  11     MYDEVID  11
 115
 116  - You can see the LUN type and backing store for block/file backend LUNs
 117    like this:
 118
 119 # ctladm devlist -v
 120 LUN Backend       Size (Blocks)   BS Serial Number    Device ID
 121   0 block            2147483648  512 MYSERIAL   0     MYDEVID   0
 122       lun_type=0
 123       num_threads=14
 124       file=testdisk0
 125   1 block            2147483648  512 MYSERIAL   1     MYDEVID   1
 126       lun_type=0
 127       num_threads=14
 128       file=testdisk1
 129   2 block            2147483648  512 MYSERIAL   2     MYDEVID   2
 130       lun_type=0
 131       num_threads=14
 132       file=testdisk2
 133   3 block            2147483648  512 MYSERIAL   3     MYDEVID   3
 134       lun_type=0
 135       num_threads=14
 136       file=testdisk3
 137   4 block            2147483648  512 MYSERIAL   4     MYDEVID   4
 138       lun_type=0
 139       num_threads=14
 140       file=testdisk4
 141   5 block            2147483648  512 MYSERIAL   5     MYDEVID   5
 142       lun_type=0
 143       num_threads=14
 144       file=testdisk5
 145   6 block            2147483648  512 MYSERIAL   6     MYDEVID   6
 146       lun_type=0
 147       num_threads=14
 148       file=testdisk6
 149   7 block            2147483648  512 MYSERIAL   7     MYDEVID   7
 150       lun_type=0
 151       num_threads=14
 152       file=testdisk7
 153   8 block            2147483648  512 MYSERIAL   8     MYDEVID   8
 154       lun_type=0
 155       num_threads=14
 156       file=testdisk8
 157   9 block            2147483648  512 MYSERIAL   9     MYDEVID   9
 158       lun_type=0
 159       num_threads=14
 160       file=testdisk9
 161  10 ramdisk                   0    0 MYSERIAL   0     MYDEVID   0
 162       lun_type=3
 163  11 ramdisk     204800000000000  512 MYSERIAL   1     MYDEVID   1
 164       lun_type=0
 165
 166
 167 Revision 1.4 Changes
 168 ====================
 169  - Added in the second HA mode (where CTL does the data transfers instead
 170    of having data transfers done below CTL), and abstracted out the Copan
 171    HA API.
 172
 173  - Fixed the phantom device problem in the CTL CAM SIM and improved the
 174    CAM SIM to automatically trigger a rescan when the port is enabled and
 175    disabled.
 176
 177  - Made the number of threads in the block backend configurable via sysctl,
 178    loader tunable and the ctladm command line.  (You can now specify
 179    -o num_threads=4 when creating a LUN with ctladm create.)
 180
 181  - Fixed some LUN selection issues in ctlstat(8) and allowed for selection
 182    of LUN numbers up to 1023.
 183
 184  - General cleanup.
 185
 186  - This version intended for public release.
 187
 188 Revision 1.3 Changes
 189 ====================
 190  - Added descriptor sense support to CTL.  It can be enabled through the
 191    control mode page (10), but is disabled by default.
 192
 193  - Improved error injection support.  The number of errors that can be
 194    injected with 'ctladm inject' has been increased, and any arbitrary
 195    sense data may now be injected as well.
 196
 197  - The port infrastructure has been revamped.  Individual ports and types
 198    of ports may now be enabled and disabled from the command line.  ctladm
 199    now has the ability to set the WWNN and WWPN for each port.
 200
 201  - The block backend can now send multiple I/Os to backing files.  Multiple
 202    writes are only allowed for ZFS, but multiple readers are allowed for
 203    any filesystem.
 204
 205  - The block and ramdisk backends now support setting the LUN blocksize.
 206    There are some restrictions when the backing device is a block device,
 207    but otherwise the blocksize may be set to anything.
 208
 209 Revision 1.2 Changes
 210 ====================
 211
 212  - CTL initialization process has been revamped.  Instead of using an
 213    ad-hoc method, it is now sequenced through SYSINIT() calls.
 214
 215  - A block/file backend has been added.  This allows using arbitrary files
 216    or block devices as a backing store.
 217
 218  - The userland LUN configuration interface has been completely rewritten.
 219    Configuration is now done out of band.
 220
 221  - The ctladm(8) command line interface has been revamped, and is now
 222    similar to camcontrol(8).
 223
 224 To Do List:
 225 ==========
 226
 227  - Use devstat(9) for CTL's statistics collection.  CTL uses a home-grown
 228    statistics collection system that is similar to devstat(9).  ctlstat
 229    should be retired in favor of iostat, etc., once aggregation modes are
 230    available in iostat to match the behavior of ctlstat -t and dump modes
 231    are available to match the behavior of ctlstat -d/ctlstat -J.
 232
 233  - ZFS ARC backend for CTL.  Since ZFS copies all I/O into the ARC
 234    (Adaptive Replacement Cache), running the block/file backend on top of a
 235    ZFS-backed zdev or file will involve an extra set of copies.  The
 236    optimal solution for backing targets served by CTL with ZFS would be to
 237    allocate buffers out of the ARC directly, and DMA to/from them directly.
 238    That would eliminate an extra data buffer allocation and copy.
 239
 240  - Switch CTL over to using CAM CCBs instead of its own union ctl_io.  This
 241    will likely require a significant amount of work, but will eliminate
 242    another data structure in the stack, more memory allocations, etc.  This
 243    will also require changes to the CAM CCB structure to support CTL.
 244
 245 Code Roadmap:
 246 ============
 247
 248 CTL has the concept of pluggable frontend ports and backends.  All
 249 frontends and backends can be active at the same time.  You can have a
 250 ramdisk-backed LUN present along side a file backed LUN.
 251
 252 ctl.c:
 253 -----
 254
 255 This is the core of CTL, where all of the command handlers and a lot of
 256 other things live.  Yes, it is large.  It started off small and grew to its
 257 current size over time.  Perhaps it can be split into more files at some
 258 point.
 259
 260 Here is a roadmap of some of the primary functions in ctl.c.  Starting here
 261 and following the various leaf functions will show the command flow.
 262
 263 ctl_queue()             This is where commands from the frontend ports come
 264                         in.
 265
 266 ctl_queue_sense()       This is only used for non-packetized SCSI.  i.e.
 267                         parallel SCSI prior to U320 and perhaps U160.
 268
 269 ctl_work_thread()       This is the primary work thread, and everything gets
 270                         executed from there.
 271
 272 ctl_scsiio_precheck()   This where all of the initial checks are done, and I/O
 273                         is either queued for execution or blocked.
 274
 275 ctl_scsiio()            This is where the command handler is actually
 276                         executed.  (See ctl_cmd_table.c for the mapping of
 277                         SCSI opcode to command handler function.)
 278
 279 ctl_done()              This is the routine called (or ctl_done_lock()) to
 280                         initiate the command completion process.
 281
 282 ctl_process_done()      This is where command completion actually happens.
 283
 284 ctl.h:
 285 -----
 286
 287 Basic function declarations and data structures.
 288
 289 ctl_backend.c,
 290 ctl_backend.h:
 291 -------------
 292
 293 These files define the basic CTL backend API.  The comments in the header
 294 explain the API.
 295
 296 ctl_backend_block.c
 297 -------------------
 298
 299 The block and file backend.  This allows for using a disk or a file as the
 300 backing store for a LUN.  Multiple threads are started to do I/O to the
 301 backing device, primarily because the VFS API requires that to get any
 302 concurrency.
 303
 304 ctl_backend_ramdisk.c:
 305 ---------------------
 306
 307 A "fake" ramdisk backend.  It only allocates a small amount of memory to
 308 act as a source and sink for reads and writes from an initiator.  Therefore
 309 it cannot be used for any real data, but it can be used to test for
 310 throughput.  It can also be used to test initiators' support for extremely
 311 large LUNs.
 312
 313 ctl_cmd_table.c:
 314 ---------------
 315
 316 This is a table with all 256 possible SCSI opcodes, and command handler
 317 functions defined for supported opcodes.  It is included in ctl.c.
 318
 319 ctl_debug.h:
 320 -----------
 321
 322 Simplistic debugging support.
 323
 324 ctl_error.c,
 325 ctl_error.h:
 326 -----------
 327
 328 CTL-specific wrappers around the CAM sense building functions.
 329
 330 ctl_frontend.c,
 331 ctl_frontend.h:
 332 --------------
 333
 334 These files define the basic CTL frontend port API.  The comments in the
 335 header explain the API.
 336
 337 ctl_frontend_cam_sim.c:
 338 ----------------------
 339
 340 This is a CTL frontend port that is also a CAM SIM.  The idea is that this
 341 frontend allows for using CTL without any target-capable hardware.  So any
 342 LUNs you create in CTL are visible via this port.
 343
 344 ctl_ha.c:
 345 ctl_ha.h:
 346 --------
 347
 348 This is a High Availability API and TCP-based interlink implementation.
 349
 350 ctl_io.h:
 351 --------
 352
 353 This defines most of the core CTL I/O structures.  union ctl_io is
 354 conceptually very similar to CAM's union ccb.
 355
 356 ctl_ioctl.h:
 357 -----------
 358
 359 This defines all ioctls available through the CTL character device, and
 360 the data structures needed for those ioctls.
 361
 362 ctl_private.h:
 363 -------------
 364
 365 Private data structres (e.g. CTL softc) and function prototypes.  This also
 366 includes the SCSI vendor and product names used by CTL.
 367
 368 ctl_scsi_all.c
 369 ctl_scsi_all.h:
 370 --------------
 371
 372 CTL wrappers around CAM sense printing functions.
 373
 374 ctl_ser_table.c:
 375 ---------------
 376
 377 Command serialization table.  This defines what happens when one type of
 378 command is followed by another type of command.  e.g., what do you do when
 379 you have a mode select followed by a write?  You block the write until the
 380 mode select is complete.  That is defined in this table.
 381
 382 ctl_util.c
 383 ctl_util.h:
 384 ----------
 385
 386 CTL utility functions, primarily designed to be used from userland.  See
 387 ctladm for the primary consumer of these functions.  These include CDB
 388 building functions.
 389
 390 scsi_ctl.c:
 391 ----------
 392
 393 CAM target peripheral driver and CTL frontend port.  This is the path into
 394 CTL for commands from target-capable hardware/SIMs.
 395
 396 Userland Commands:
 397 =================
 398
 399 ctladm(8) fills a role similar to camcontrol(8).  It allow configuring LUNs,
 400 issuing commands, injecting errors and various other control functions.
 401
 402 ctlstat(8) fills a role similar to iostat(8).  It reports I/O statistics
 403 for CTL.