usb.tmpl

Linux Kernel 2.6.9 for OMAP1710

        unsigned int  interface;
        char          driver[USBDEVFS_MAXDRIVERNAME + 1];
};</programlisting>
		    File modification time is not updated by this request.
		    </para></listitem></varlistentry>

		<varlistentry><term>USBDEVFS_IOCTL</term>
		    <listitem><para>Passes a request from userspace through
		    to a kernel driver that has an ioctl entry in the
		    <emphasis>struct usb_driver</emphasis> it registered.
<programlisting>struct usbdevfs_ioctl {
        int     ifno;
        int     ioctl_code;
        void    *data;
};

/* user mode call looks like this.
 * 'request' becomes the driver->ioctl() 'code' parameter.
 * the size of 'param' is encoded in 'request', and that data
 * is copied to or from the driver->ioctl() 'buf' parameter.
 */
static int
usbdev_ioctl (int fd, int ifno, unsigned request, void *param)
{
        struct usbdevfs_ioctl	wrapper;

        wrapper.ifno = ifno;
        wrapper.ioctl_code = request;
        wrapper.data = param;

        return ioctl (fd, USBDEVFS_IOCTL, &amp;wrapper);
} </programlisting>
		    File modification time is not updated by this request.
		    </para><para>
		    This request lets kernel drivers talk to user mode code
		    through filesystem operations even when they don't create
		    a charactor or block special device.
		    It's also been used to do things like ask devices what
		    device special file should be used.
		    Two pre-defined ioctls are used
		    to disconnect and reconnect kernel drivers, so
		    that user mode code can completely manage binding
		    and configuration of devices.
		    </para></listitem></varlistentry>

		<varlistentry><term>USBDEVFS_RELEASEINTERFACE</term>
		    <listitem><para>This is used to release the claim usbfs
		    made on interface, either implicitly or because of a
		    USBDEVFS_CLAIMINTERFACE call, before the file
		    descriptor is closed.
		    The ioctl parameter is an integer holding the number of
		    the interface (bInterfaceNumber from descriptor);
		    File modification time is not updated by this request.
		    </para><warning><para>
		    <emphasis>No security check is made to ensure
		    that the task which made the claim is the one
		    which is releasing it.
		    This means that user mode driver may interfere
		    other ones.  </emphasis>
		    </para></warning></listitem></varlistentry>

		<varlistentry><term>USBDEVFS_RESETEP</term>
		    <listitem><para>Resets the data toggle value for an endpoint
		    (bulk or interrupt) to DATA0.
		    The ioctl parameter is an integer endpoint number
		    (1 to 15, as identified in the endpoint descriptor),
		    with USB_DIR_IN added if the device's endpoint sends
		    data to the host.
		    </para><warning><para>
		    <emphasis>Avoid using this request.
		    It should probably be removed.</emphasis>
		    Using it typically means the device and driver will lose
		    toggle synchronization.  If you really lost synchronization,
		    you likely need to completely handshake with the device,
		    using a request like CLEAR_HALT
		    or SET_INTERFACE.
		    </para></warning></listitem></varlistentry>

		</variablelist>

		</sect2>

	    <sect2>
		<title>Synchronous I/O Support</title>

		<para>Synchronous requests involve the kernel blocking
		until until the user mode request completes, either by
		finishing successfully or by reporting an error.
		In most cases this is the simplest way to use usbfs,
		although as noted above it does prevent performing I/O
		to more than one endpoint at a time.
		</para>

		<variablelist>

		<varlistentry><term>USBDEVFS_BULK</term>
		    <listitem><para>Issues a bulk read or write request to the
		    device.
		    The ioctl parameter is a pointer to this structure:
<programlisting>struct usbdevfs_bulktransfer {
        unsigned int  ep;
        unsigned int  len;
        unsigned int  timeout; /* in milliseconds */
        void          *data;
};</programlisting>
		    </para><para>The "ep" value identifies a
		    bulk endpoint number (1 to 15, as identified in an endpoint
		    descriptor),
		    masked with USB_DIR_IN when referring to an endpoint which
		    sends data to the host from the device.
		    The length of the data buffer is identified by "len";
		    Recent kernels support requests up to about 128KBytes.
		    <emphasis>FIXME say how read length is returned,
		    and how short reads are handled.</emphasis>.
		    </para></listitem></varlistentry>

		<varlistentry><term>USBDEVFS_CLEAR_HALT</term>
		    <listitem><para>Clears endpoint halt (stall) and
		    resets the endpoint toggle.  This is only
		    meaningful for bulk or interrupt endpoints.
		    The ioctl parameter is an integer endpoint number
		    (1 to 15, as identified in an endpoint descriptor),
		    masked with USB_DIR_IN when referring to an endpoint which
		    sends data to the host from the device.
		    </para><para>
		    Use this on bulk or interrupt endpoints which have
		    stalled, returning <emphasis>-EPIPE</emphasis> status
		    to a data transfer request.
		    Do not issue the control request directly, since
		    that could invalidate the host's record of the
		    data toggle.
		    </para></listitem></varlistentry>

		<varlistentry><term>USBDEVFS_CONTROL</term>
		    <listitem><para>Issues a control request to the device.
		    The ioctl parameter points to a structure like this:
<programlisting>struct usbdevfs_ctrltransfer {
        __u8   bRequestType;
        __u8   bRequest;
        __u16  wValue;
        __u16  wIndex;
        __u16  wLength;
        __u32  timeout;  /* in milliseconds */
        void   *data;
};</programlisting>
		    </para><para>
		    The first eight bytes of this structure are the contents
		    of the SETUP packet to be sent to the device; see the
		    USB 2.0 specification for details.
		    The bRequestType value is composed by combining a
		    USB_TYPE_* value, a USB_DIR_* value, and a
		    USB_RECIP_* value (from
		    <emphasis>&lt;linux/usb.h&gt;</emphasis>).
		    If wLength is nonzero, it describes the length of the data
		    buffer, which is either written to the device
		    (USB_DIR_OUT) or read from the device (USB_DIR_IN).
		    </para><para>
		    At this writing, you can't transfer more than 4 KBytes
		    of data to or from a device; usbfs has a limit, and
		    some host controller drivers have a limit.
		    (That's not usually a problem.)
		    <emphasis>Also</emphasis> there's no way to say it's
		    not OK to get a short read back from the device.
		    </para></listitem></varlistentry>

		<varlistentry><term>USBDEVFS_RESET</term>
		    <listitem><para>Does a USB level device reset.
		    The ioctl parameter is ignored.
		    After the reset, this rebinds all device interfaces.
		    File modification time is not updated by this request.
		    </para><warning><para>
		    <emphasis>Avoid using this call</emphasis>
		    until some usbcore bugs get fixed,
		    since it does not fully synchronize device, interface,
		    and driver (not just usbfs) state.
		    </para></warning></listitem></varlistentry>
	    
		<varlistentry><term>USBDEVFS_SETINTERFACE</term>
		    <listitem><para>Sets the alternate setting for an
		    interface.  The ioctl parameter is a pointer to a
		    structure like this:
<programlisting>struct usbdevfs_setinterface {
        unsigned int  interface;
        unsigned int  altsetting;
}; </programlisting>
		    File modification time is not updated by this request.
		    </para><para>
		    Those struct members are from some interface descriptor
		    applying to the the current configuration.
		    The interface number is the bInterfaceNumber value, and
		    the altsetting number is the bAlternateSetting value.
		    (This resets each endpoint in the interface.)
		    </para></listitem></varlistentry>

		<varlistentry><term>USBDEVFS_SETCONFIGURATION</term>
		    <listitem><para>Issues the
		    <function>usb_set_configuration</function> call
		    for the device.
		    The parameter is an integer holding the number of
		    a configuration (bConfigurationValue from descriptor).
		    File modification time is not updated by this request.
		    </para><warning><para>
		    <emphasis>Avoid using this call</emphasis>
		    until some usbcore bugs get fixed,
		    since it does not fully synchronize device, interface,
		    and driver (not just usbfs) state.
		    </para></warning></listitem></varlistentry>

		</variablelist>
	    </sect2>

	    <sect2>
		<title>Asynchronous I/O Support</title>

		<para>As mentioned above, there are situations where it may be
		important to initiate concurrent operations from user mode code.
		This is particularly important for periodic transfers
		(interrupt and isochronous), but it can be used for other
		kinds of USB requests too.
		In such cases, the asynchronous requests described here
		are essential.  Rather than submitting one request and having
		the kernel block until it completes, the blocking is separate.
		</para>

		<para>These requests are packaged into a structure that
		resembles the URB used by kernel device drivers.
		(No POSIX Async I/O support here, sorry.)
		It identifies the endpoint type (USBDEVFS_URB_TYPE_*),
		endpoint (number, masked with USB_DIR_IN as appropriate),
		buffer and length, and a user "context" value serving to
		uniquely identify each request.
		(It's usually a pointer to per-request data.)
		Flags can modify requests (not as many as supported for
		kernel drivers).
		</para>

		<para>Each request can specify a realtime signal number
		(between SIGRTMIN and SIGRTMAX, inclusive) to request a
		signal be sent when the request completes.
		</para>

		<para>When usbfs returns these urbs, the status value
		is updated, and the buffer may have been modified.
		Except for isochronous transfers, the actual_length is
		updated to say how many bytes were transferred; if the
		USBDEVFS_URB_DISABLE_SPD flag is set
		("short packets are not OK"), if fewer bytes were read
		than were requested then you get an error report.
		</para>

<programlisting>struct usbdevfs_iso_packet_desc {
        unsigned int                     length;
        unsigned int                     actual_length;
        unsigned int                     status;
};

struct usbdevfs_urb {
        unsigned char                    type;
        unsigned char                    endpoint;
        int                              status;
        unsigned int                     flags;
        void                             *buffer;
        int                              buffer_length;
        int                              actual_length;
        int                              start_frame;
        int                              number_of_packets;
        int                              error_count;
        unsigned int                     signr;
        void                             *usercontext;
        struct usbdevfs_iso_packet_desc  iso_frame_desc[];
};</programlisting>

		<para> For these asynchronous requests, the file modification
		time reflects when the request was initiated.
		This contrasts with their use with the synchronous requests,
		where it reflects when requests complete.
		</para>

		<variablelist>

		<varlistentry><term>USBDEVFS_DISCARDURB</term>
		    <listitem><para>
		    <emphasis>TBS</emphasis>
		    File modification time is not updated by this request.
		    </para><para>
		    </para></listitem></varlistentry>

		<varlistentry><term>USBDEVFS_DISCSIGNAL</term>
		    <listitem><para>
		    <emphasis>TBS</emphasis>
		    File modification time is not updated by this request.
		    </para><para>
		    </para></listitem></varlistentry>

		<varlistentry><term>USBDEVFS_REAPURB</term>
		    <listitem><para>
		    <emphasis>TBS</emphasis>
		    File modification time is not updated by this request.
		    </para><para>
		    </para></listitem></varlistentry>

		<varlistentry><term>USBDEVFS_REAPURBNDELAY</term>
		    <listitem><para>
		    <emphasis>TBS</emphasis>
		    File modification time is not updated by this request.
		    </para><para>
		    </para></listitem></varlistentry>

		<varlistentry><term>USBDEVFS_SUBMITURB</term>
		    <listitem><para>
		    <emphasis>TBS</emphasis>
		    </para><para>
		    </para></listitem></varlistentry>

		</variablelist>
	    </sect2>

	</sect1>

    </chapter>

</book>
<!-- vim:syntax=sgml:sw=4
-->