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