MFC r291716, r291724, r291741, r291742

In addition to those revisions, add this change to a file that is not in
head:

sys/ia64/include/bus.h:
  	Guard kernel-only parts of the ia64 machine/bus.h header with
  	#ifdef _KERNEL.

  	This allows userland programs to include <machine/bus.h> to get the
  	definition of bus_addr_t and bus_size_t.

  ------------------------------------------------------------------------
  r291716 | ken | 2015-12-03 15:54:55 -0500 (Thu, 03 Dec 2015) | 257 lines

  Add asynchronous command support to the pass(4) driver, and the new
  camdd(8) utility.

  CCBs may be queued to the driver via the new CAMIOQUEUE ioctl, and
  completed CCBs may be retrieved via the CAMIOGET ioctl.  User
  processes can use poll(2) or kevent(2) to get notification when
  I/O has completed.

  While the existing CAMIOCOMMAND blocking ioctl interface only
  supports user virtual data pointers in a CCB (generally only
  one per CCB), the new CAMIOQUEUE ioctl supports user virtual and
  physical address pointers, as well as user virtual and physical
  scatter/gather lists.  This allows user applications to have more
  flexibility in their data handling operations.

  Kernel memory for data transferred via the queued interface is
  allocated from the zone allocator in MAXPHYS sized chunks, and user
  data is copied in and out.  This is likely faster than the
  vmapbuf()/vunmapbuf() method used by the CAMIOCOMMAND ioctl in
  configurations with many processors (there are more TLB shootdowns
  caused by the mapping/unmapping operation) but may not be as fast
  as running with unmapped I/O.

  The new memory handling model for user requests also allows
  applications to send CCBs with request sizes that are larger than
  MAXPHYS.  The pass(4) driver now limits queued requests to the I/O
  size listed by the SIM driver in the maxio field in the Path
  Inquiry (XPT_PATH_INQ) CCB.

  There are some things things would be good to add:

  1. Come up with a way to do unmapped I/O on multiple buffers.
     Currently the unmapped I/O interface operates on a struct bio,
     which includes only one address and length.  It would be nice
     to be able to send an unmapped scatter/gather list down to
     busdma.  This would allow eliminating the copy we currently do
     for data.

  2. Add an ioctl to list currently outstanding CCBs in the various
     queues.

  3. Add an ioctl to cancel a request, or use the XPT_ABORT CCB to do
     that.

  4. Test physical address support.  Virtual pointers and scatter
     gather lists have been tested, but I have not yet tested
     physical addresses or scatter/gather lists.

  5. Investigate multiple queue support.  At the moment there is one
     queue of commands per pass(4) device.  If multiple processes
     open the device, they will submit I/O into the same queue and
     get events for the same completions.  This is probably the right
     model for most applications, but it is something that could be
     changed later on.

  Also, add a new utility, camdd(8) that uses the asynchronous pass(4)
  driver interface.

  This utility is intended to be a basic data transfer/copy utility,
  a simple benchmark utility, and an example of how to use the
  asynchronous pass(4) interface.

  It can copy data to and from pass(4) devices using any target queue
  depth, starting offset and blocksize for the input and ouptut devices.
  It currently only supports SCSI devices, but could be easily extended
  to support ATA devices.

  It can also copy data to and from regular files, block devices, tape
  devices, pipes, stdin, and stdout.  It does not support queueing
  multiple commands to any of those targets, since it uses the standard
  read(2)/write(2)/writev(2)/readv(2) system calls.

  The I/O is done by two threads, one for the reader and one for the
  writer.  The reader thread sends completed read requests to the
  writer thread in strictly sequential order, even if they complete
  out of order.  That could be modified later on for random I/O patterns
  or slightly out of order I/O.

  camdd(8) uses kqueue(2)/kevent(2) to get I/O completion events from
  the pass(4) driver and also to send request notifications internally.

  For pass(4) devcies, camdd(8) uses a single buffer (CAM_DATA_VADDR)
  per CAM CCB on the reading side, and a scatter/gather list
  (CAM_DATA_SG) on the writing side.  In addition to testing both
  interfaces, this makes any potential reblocking of I/O easier.  No
  data is copied between the reader and the writer, but rather the
  reader's buffers are split into multiple I/O requests or combined
  into a single I/O request depending on the input and output blocksize.

  For the file I/O path, camdd(8) also uses a single buffer (read(2),
  write(2), pread(2) or pwrite(2)) on reads, and a scatter/gather list
  (readv(2), writev(2), preadv(2), pwritev(2)) on writes.

  Things that would be nice to do for camdd(8) eventually:

  1.  Add support for I/O pattern generation.  Patterns like all
      zeros, all ones, LBA-based patterns, random patterns, etc. Right
      Now you can always use /dev/zero, /dev/random, etc.

  2.  Add support for a "sink" mode, so we do only reads with no
      writes.  Right now, you can use /dev/null.

  3.  Add support for automatic queue depth probing, so that we can
      figure out the right queue depth on the input and output side
      for maximum throughput.  At the moment it defaults to 6.

  4.  Add support for SATA device passthrough I/O.

  5.  Add support for random LBAs and/or lengths on the input and
      output sides.

  6.  Track average per-I/O latency and busy time.  The busy time
      and latency could also feed in to the automatic queue depth
      determination.

  sys/cam/scsi/scsi_pass.h:
  	Define two new ioctls, CAMIOQUEUE and CAMIOGET, that queue
  	and fetch asynchronous CAM CCBs respectively.

  	Although these ioctls do not have a declared argument, they
  	both take a union ccb pointer.  If we declare a size here,
  	the ioctl code in sys/kern/sys_generic.c will malloc and free
  	a buffer for either the CCB or the CCB pointer (depending on
  	how it is declared).  Since we have to keep a copy of the
  	CCB (which is fairly large) anyway, having the ioctl malloc
  	and free a CCB for each call is wasteful.

  sys/cam/scsi/scsi_pass.c:
  	Add asynchronous CCB support.

  	Add two new ioctls, CAMIOQUEUE and CAMIOGET.

  	CAMIOQUEUE adds a CCB to the incoming queue.  The CCB is
  	executed immediately (and moved to the active queue) if it
  	is an immediate CCB, but otherwise it will be executed
  	in passstart() when a CCB is available from the transport layer.

  	When CCBs are completed (because they are immediate or
  	passdone() if they are queued), they are put on the done
  	queue.

  	If we get the final close on the device before all pending
  	I/O is complete, all active I/O is moved to the abandoned
  	queue and we increment the peripheral reference count so
  	that the peripheral driver instance doesn't go away before
  	all pending I/O is done.

  	The new passcreatezone() function is called on the first
  	call to the CAMIOQUEUE ioctl on a given device to allocate
  	the UMA zones for I/O requests and S/G list buffers.  This
  	may be good to move off to a taskqueue at some point.
  	The new passmemsetup() function allocates memory and
  	scatter/gather lists to hold the user's data, and copies
  	in any data that needs to be written.  For virtual pointers
  	(CAM_DATA_VADDR), the kernel buffer is malloced from the
  	new pass(4) driver malloc bucket.  For virtual
  	scatter/gather lists (CAM_DATA_SG), buffers are allocated
  	from a new per-pass(9) UMA zone in MAXPHYS-sized chunks.
  	Physical pointers are passed in unchanged.  We have support
  	for up to 16 scatter/gather segments (for the user and
  	kernel S/G lists) in the default struct pass_io_req, so
  	requests with longer S/G lists require an extra kernel malloc.

  	The new passcopysglist() function copies a user scatter/gather
  	list to a kernel scatter/gather list.  The number of elements
  	in each list may be different, but (obviously) the amount of data
  	stored has to be identical.

  	The new passmemdone() function copies data out for the
  	CAM_DATA_VADDR and CAM_DATA_SG cases.

  	The new passiocleanup() function restores data pointers in
  	user CCBs and frees memory.

  	Add new functions to support kqueue(2)/kevent(2):

  	passreadfilt() tells kevent whether or not the done
  	queue is empty.

  	passkqfilter() adds a knote to our list.

  	passreadfiltdetach() removes a knote from our list.

  	Add a new function, passpoll(), for poll(2)/select(2)
  	to use.

  	Add devstat(9) support for the queued CCB path.

  sys/cam/ata/ata_da.c:
  	Add support for the BIO_VLIST bio type.

  sys/cam/cam_ccb.h:
  	Add a new enumeration for the xflags field in the CCB header.
  	(This doesn't change the CCB header, just adds an enumeration to
  	use.)

  sys/cam/cam_xpt.c:
  	Add a new function, xpt_setup_ccb_flags(), that allows specifying
  	CCB flags.

  sys/cam/cam_xpt.h:
  	Add a prototype for xpt_setup_ccb_flags().

  sys/cam/scsi/scsi_da.c:
  	Add support for BIO_VLIST.

  sys/dev/md/md.c:
  	Add BIO_VLIST support to md(4).

  sys/geom/geom_disk.c:
  	Add BIO_VLIST support to the GEOM disk class.  Re-factor the I/O size
  	limiting code in g_disk_start() a bit.

  sys/kern/subr_bus_dma.c:
  	Change _bus_dmamap_load_vlist() to take a starting offset and
  	length.

  	Add a new function, _bus_dmamap_load_pages(), that will load a list
  	of physical pages starting at an offset.

  	Update _bus_dmamap_load_bio() to allow loading BIO_VLIST bios.
  	Allow unmapped I/O to start at an offset.

  sys/kern/subr_uio.c:
  	Add two new functions, physcopyin_vlist() and physcopyout_vlist().

  sys/pc98/include/bus.h:
  	Guard kernel-only parts of the pc98 machine/bus.h header with
  	#ifdef _KERNEL.

  	This allows userland programs to include <machine/bus.h> to get the
  	definition of bus_addr_t and bus_size_t.

  sys/sys/bio.h:
  	Add a new bio flag, BIO_VLIST.

  sys/sys/uio.h:
  	Add prototypes for physcopyin_vlist() and physcopyout_vlist().

  share/man/man4/pass.4:
  	Document the CAMIOQUEUE and CAMIOGET ioctls.

  usr.sbin/Makefile:
  	Add camdd.

  usr.sbin/camdd/Makefile:
  	Add a makefile for camdd(8).

  usr.sbin/camdd/camdd.8:
  	Man page for camdd(8).

  usr.sbin/camdd/camdd.c:
  	The new camdd(8) utility.

  Sponsored by:	Spectra Logic

  ------------------------------------------------------------------------
  r291724 | ken | 2015-12-03 17:07:01 -0500 (Thu, 03 Dec 2015) | 6 lines

  Fix typos in the camdd(8) usage() function output caused by an error in
  my diff filter script.

  Sponsored by:	Spectra Logic

  ------------------------------------------------------------------------
  r291741 | ken | 2015-12-03 22:38:35 -0500 (Thu, 03 Dec 2015) | 10 lines

  Fix g_disk_vlist_limit() to work properly with deletes.

  Add a new bp argument to g_disk_maxsegs(), and add a new function,
  g_disk_maxsize() tha will properly determine the maximum I/O size for a
  delete or non-delete bio.

  Submitted by:	will
  Sponsored by:	Spectra Logic

  ------------------------------------------------------------------------
  ------------------------------------------------------------------------
  r291742 | ken | 2015-12-03 22:44:12 -0500 (Thu, 03 Dec 2015) | 5 lines

  Fix a style issue in g_disk_limit().

  Noticed by:	bdrewery

  ------------------------------------------------------------------------

Sponsored by:	Spectra Logic

1 files changed, 122 insertions, 10 deletions

diff --git a/share/man/man4/pass.4 b/share/man/man4/pass.4
index 7819ea3..00b9ccd 100644
--- a/share/man/man4/pass.4
+++ b/share/man/man4/pass.4
@@ -27,7 +27,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd October 10, 1998
+.Dd March 17, 2015
 .Dt PASS 4
 .Os
 .Sh NAME
@@ -53,9 +53,13 @@ The
 .Nm
 driver attaches to every
 .Tn SCSI
+and
+.Tn ATA
 device found in the system.
 Since it attaches to every device, it provides a generic means of accessing
 .Tn SCSI
+and
+.Tn ATA
 devices, and allows the user to access devices which have no
 "standard" peripheral driver associated with them.
 .Sh KERNEL CONFIGURATION
@@ -65,10 +69,12 @@ device in the kernel;
 .Nm
 devices are automatically allocated as
 .Tn SCSI
+and
+.Tn ATA
 devices are found.
 .Sh IOCTLS
-.Bl -tag -width 012345678901234
-.It CAMIOCOMMAND
+.Bl -tag -width 5n
+.It CAMIOCOMMAND union ccb *
 This ioctl takes most kinds of CAM CCBs and passes them through to the CAM
 transport layer for action.
 Note that some CCB types are not allowed
@@ -79,7 +85,7 @@ Some examples of xpt-only CCBs are XPT_SCAN_BUS,
 XPT_DEV_MATCH, XPT_RESET_BUS, XPT_SCAN_LUN, XPT_ENG_INQ, and XPT_ENG_EXEC.
 These CCB types have various attributes that make it illogical or
 impossible to service them through the passthrough interface.
-.It CAMGETPASSTHRU
+.It CAMGETPASSTHRU union ccb *
 This ioctl takes an XPT_GDEVLIST CCB, and returns the passthrough device
 corresponding to the device in question.
 Although this ioctl is available through the
@@ -90,6 +96,109 @@ ioctl.
 It is probably more useful to issue this ioctl through the
 .Xr xpt 4
 device.
+.It CAMIOQUEUE union ccb *
+Queue a CCB to the
+.Xr pass 4
+driver to be executed asynchronously.
+The caller may use
+.Xr select 2 ,
+.Xr poll 2 
+or
+.Xr kevent 2
+to receive notification when the CCB has completed.
+.Pp
+This ioctl takes most CAM CCBs, but some CCB types are not allowed through
+the pass device, and must be sent through the
+.Xr xpt 4
+device instead.
+Some examples of xpt-only CCBs are XPT_SCAN_BUS,
+XPT_DEV_MATCH, XPT_RESET_BUS, XPT_SCAN_LUN, XPT_ENG_INQ, and XPT_ENG_EXEC.
+These CCB types have various attributes that make it illogical or
+impossible to service them through the passthrough interface.
+.Pp
+Although the
+.Dv CAMIOQUEUE
+ioctl is not defined to take an argument, it does require a
+pointer to a union ccb.
+It is not defined to take an argument to avoid an extra malloc and copy 
+inside the generic 
+.Xr ioctl 2
+handler.
+.pp
+The completed CCB will be returned via the
+.Dv CAMIOGET
+ioctl.
+An error will only be returned from the
+.Dv CAMIOQUEUE
+ioctl if there is an error allocating memory for the request or copying
+memory from userland.
+All other errors will be reported as standard CAM CCB status errors.
+Since the CCB is not copied back to the user process from the pass driver
+in the
+.Dv CAMIOQUEUE
+ioctl, the user's passed-in CCB will not be modfied.
+This is the case even with immediate CCBs.
+Instead, the completed CCB must be retrieved via the
+.Dv CAMIOGET
+ioctl and the status examined.
+.Pp
+Multiple CCBs may be queued via the
+.Dv CAMIOQUEUE
+ioctl at any given time, and they may complete in a different order than
+the order that they were submitted.
+The caller must take steps to identify CCBs that are queued and completed.
+The
+.Dv periph_priv
+structure inside struct ccb_hdr is available for userland use with the
+.Dv CAMIOQUEUE
+and
+.Dv CAMIOGET
+ioctls, and will be preserved across calls.
+Also, the periph_links linked list pointers inside struct ccb_hdr are
+available for userland use with the
+.Dv CAMIOQUEUE
+and
+.Dv CAMIOGET
+ioctls and will be preserved across calls.
+.It CAMIOGET union ccb *
+Retrieve completed CAM CCBs queued via the
+.Dv CAMIOQUEUE
+ioctl.
+An error will only be returned from the
+.Dv CAMIOGET
+ioctl if the
+.Xr pass 4
+driver fails to copy data to the user process or if there are no completed
+CCBs available to retrieve.
+If no CCBs are available to retrieve,
+errno will be set to 
+.Dv ENOENT .
+.Pp
+All other errors will be reported as standard CAM CCB status errors.
+.Pp
+Although the
+.Dv CAMIOGET
+ioctl is not defined to take an argument, it does require a
+pointer to a union ccb.
+It is not defined to take an argument to avoid an extra malloc and copy 
+inside the generic 
+.Xr ioctl 2
+handler.
+.Pp
+The pass driver will report via
+.Xr select 2 ,
+.Xr poll 2 
+or
+.Xr kevent 2
+when a CCB has completed.
+One CCB may be retrieved per
+.Dv CAMIOGET
+call.
+CCBs may be returned in an order different than the order they were
+submitted.
+So the caller should use the
+.Dv periph_priv
+area inside the CCB header to store pointers to identifying information.
 .El
 .Sh FILES
 .Bl -tag -width /dev/passn -compact
@@ -103,18 +212,21 @@ CAM subsystem.
 .Sh DIAGNOSTICS
 None.
 .Sh SEE ALSO
+.Xr kqueue 2 ,
+.Xr poll 2 ,
+.Xr select 2 ,
 .Xr cam 3 ,
 .Xr cam 4 ,
 .Xr cam_cdbparse 3 ,
+.Xr cd 4 ,
+.Xr ctl 4 ,
+.Xr da 4 ,
+.Xr sa 4 ,
 .Xr xpt 4 ,
-.Xr camcontrol 8
+.Xr camcontrol 8 ,
+.Xr camdd 8
 .Sh HISTORY
 The CAM passthrough driver first appeared in
 .Fx 3.0 .
 .Sh AUTHORS
 .An Kenneth Merry Aq ken@FreeBSD.org
-.Sh BUGS
-It might be nice to have a way to asynchronously send CCBs through the
-passthrough driver.
-This would probably require some sort of read/write
-interface or an asynchronous ioctl interface.