share/man/man4/targ.4

   1 .\" Copyright (c) 2002
   2 .\"     Nate Lawson.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Neither the name of the author nor the names of any co-contributors
  10 .\"    may be used to endorse or promote products derived from this software
  11 .\"    without specific prior written permission.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY Nate Lawson AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd December 13, 2011
  28 .Dt TARG 4
  29 .Os
  30 .Sh NAME
  31 .Nm targ
  32 .Nd SCSI target emulator driver
  33 .Sh SYNOPSIS
  34 To compile this driver into the kernel,
  35 place the following line in your
  36 kernel configuration file:
  37 .Bd -ragged -offset indent
  38 .Cd "device targ"
  39 .Ed
  40 .Sh DESCRIPTION
  41 The
  42 .Nm
  43 driver provides an interface for usermode programs to emulate SCSI target
  44 devices.
  45 A sample program that emulates a disk drive (similar to
  46 .Xr da 4 )
  47 can be found in
  48 .Pa /usr/share/examples/scsi_target .
  49 .Pp
  50 The
  51 .Nm
  52 driver supplies the control device
  53 .Pa /dev/targ .
  54 After opening the device, the file descriptor must be bound to a
  55 specific bus/target/LUN and enabled to process CCBs using the
  56 .Dv TARGIOCENABLE
  57 ioctl.
  58 The process then uses
  59 .Xr write 2
  60 to send CCBs to the SIM and
  61 .Xr poll 2
  62 or
  63 .Xr kqueue 2
  64 to see if responses are ready.
  65 Pointers to completed CCBs are returned via
  66 .Xr read 2 .
  67 Any data transfers requested by the user CCBs are done via zero-copy IO.
  68 .Sh IOCTLS
  69 The following
  70 .Xr ioctl 2
  71 calls are defined in the header file
  72 .In cam/scsi/scsi_targetio.h .
  73 .Bl -tag -width ".Dv TARGIOCDISABLE"
  74 .It Dv TARGIOCENABLE
  75 .Pq Vt "struct ioc_enable_lun"
  76 Enable target mode on the LUN specified by the following structure:
  77 .Bd -literal -offset indent
  78 struct ioc_enable_lun {
  79         path_id_t       path_id;
  80         target_id_t     target_id;
  81         lun_id_t        lun_id;
  82         int             grp6_len;
  83         int             grp7_len;
  84 };
  85 .Ed
  86 .Pp
  87 The selected path (bus), target, and LUN must not already be in use or
  88 .Er EADDRINUSE
  89 is returned.
  90 If
  91 .Va grp6_len
  92 or
  93 .Va grp7_len
  94 are non-zero, reception of vendor-specific commands
  95 is enabled.
  96 .It Dv TARGIOCDISABLE
  97 Disable target mode and abort all pending CCBs.
  98 The CCBs may optionally be read as they complete.
  99 .Dv TARGIOCENABLE
 100 can then be called to activate a different LUN.
 101 Multiple disable calls have no effect.
 102 The
 103 .Xr close 2
 104 system call automatically disables target mode if enabled.
 105 .It Dv TARGIOCDEBUG
 106 .Pq Vt int
 107 Enables
 108 .Dv CAM_PERIPH
 109 debugging if the argument is non-zero, otherwise disables
 110 it.
 111 .El
 112 .Sh FILES
 113 .Bl -tag -width ".Pa /sys/cam/scsi/scsi_target.c" -compact
 114 .It In cam/scsi/scsi_targetio.h
 115 describes the usermode interface.
 116 .It Pa /sys/cam/scsi/scsi_target.c
 117 is the driver source file.
 118 .It Pa /dev/targ
 119 is the control device.
 120 .El
 121 .Sh SEE ALSO
 122 .Pa /usr/share/examples/scsi_target ,
 123 .Xr ahc 4 ,
 124 .Xr isp 4 ,
 125 .Xr scsi 4
 126 .Rs
 127 .%T "FreeBSD Target Information"
 128 .%U http://www.root.org/~nate/freebsd/
 129 .Re
 130 .Sh AUTHORS
 131 .An -nosplit
 132 The
 133 .Nm
 134 driver first appeared in
 135 .Fx 3.0
 136 and was written by
 137 .An Justin T. Gibbs .
 138 It was rewritten
 139 for
 140 .Fx 5.0
 141 by
 142 .An Nate Lawson Aq nate@root.org .
 143 .Sh BUGS
 144 Currently, only the
 145 .Xr ahc 4
 146 and
 147 .Xr isp 4
 148 drivers fully support target mode.
 149 .Pp
 150 The
 151 .Xr ahc 4
 152 driver does not support tagged queuing in target mode.