Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
PASS(4)		       FreeBSD Kernel Interfaces Manual		       PASS(4)

NAME
     pass -- CAM application passthrough driver

SYNOPSIS
     device pass

DESCRIPTION
     The pass driver provides a	way for	userland applications to issue CAM
     CCBs to the kernel.

     Since the pass driver allows direct access	to the CAM subsystem, system
     administrators should exercise caution when granting access to this
     driver.  If used improperly, this driver can allow	userland applications
     to	crash a	machine	or cause data loss.

     The pass driver attaches to every SCSI and	ATA device found in the	sys-
     tem.  Since it attaches to	every device, it provides a generic means of
     accessing SCSI and	ATA devices, and allows	the user to access devices
     which have	no "standard" peripheral driver	associated with	them.

KERNEL CONFIGURATION
     It	is only	necessary to configure one pass	device in the kernel; pass
     devices are automatically allocated as SCSI and ATA devices are found.

IOCTLS
     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	through	the passthrough	device,	and must be sent
	    through the	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.

     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 pass	driver,	it is of limited use,
	    since the caller must already know that the	device in question is
	    a passthrough device if they are issuing this ioctl.  It is	proba-
	    bly	more useful to issue this ioctl	through	the xpt(4) device.

     CAMIOQUEUE	union ccb *
	    Queue a CCB	to the pass(4) driver to be executed asynchronously.
	    The	caller may use select(2), poll(2) or kevent(2) to receive
	    notification when the CCB has completed.

	    This ioctl takes most CAM CCBs, but	some CCB types are not allowed
	    through the	pass device, and must be sent through the 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.

	    Although the 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 ioctl(2) handler.  The completed CCB will be returned via
	    the	CAMIOGET ioctl.	 An error will only be returned	from the
	    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
	    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 CAMIOGET ioctl and the status	exam-
	    ined.

	    Multiple CCBs may be queued	via the	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 periph_priv structure
	    inside struct ccb_hdr is available for userland use	with the
	    CAMIOQUEUE and 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 CAMIOQUEUE and
	    CAMIOGET ioctls and	will be	preserved across calls.

     CAMIOGET union ccb	*
	    Retrieve completed CAM CCBs	queued via the CAMIOQUEUE ioctl.  An
	    error will only be returned	from the CAMIOGET ioctl	if the 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 ENOENT.

	    All	other errors will be reported as standard CAM CCB status
	    errors.

	    Although the 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
	    ioctl(2) handler.

	    The	pass driver will report	via select(2), poll(2) or kevent(2)
	    when a CCB has completed.  One CCB may be retrieved	per CAMIOGET
	    call.  CCBs	may be returned	in an order different than the order
	    they were submitted.  So the caller	should use the periph_priv
	    area inside	the CCB	header to store	pointers to identifying	infor-
	    mation.

FILES
     /dev/passn	 Character device nodes	for the	pass driver.  There should be
		 one of	these for each device accessed through the CAM subsys-
		 tem.

DIAGNOSTICS
     None.

SEE ALSO
     kqueue(2),	poll(2), select(2), cam(3), cam(4), cam_cdbparse(3), cd(4),
     ctl(4), da(4), sa(4), xpt(4), camcontrol(8), camdd(8)

HISTORY
     The CAM passthrough driver	first appeared in FreeBSD 3.0.

AUTHORS
     Kenneth Merry <ken@FreeBSD.org>

FreeBSD	10.3			March 17, 2015			  FreeBSD 10.3

NAME | SYNOPSIS | DESCRIPTION | KERNEL CONFIGURATION | IOCTLS | FILES | DIAGNOSTICS | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pass&sektion=4&manpath=FreeBSD+10.3-RELEASE>

home | help