Move DESCRIPTION below SYNOPSIS.
Remove function descriptions from SYNOPSIS. Some cleanup while here. XXX: most functions lack descriptions.
This commit is contained in:
wiz
parent
ce85630baa
commit
35ade9d47a
@ -1,4 +1,4 @@
|
||||
.\" $NetBSD: usbdi.9,v 1.10 2012/05/13 10:57:09 mrg Exp $
|
||||
.\" $NetBSD: usbdi.9,v 1.11 2012/05/13 11:57:39 wiz Exp $
|
||||
.\"
|
||||
.\" Copyright (c) 2012 Matthew R. Green
|
||||
.\" All rights reserved.
|
||||
@ -64,69 +64,7 @@
|
||||
.In dev/usb/usb.h
|
||||
.In dev/usb/usbdi.h
|
||||
.In dev/usb/usbdi_util.h
|
||||
.Sh DESCRIPTION
|
||||
Device driver access to the USB bus centers around transfers.
|
||||
A transfer describes a communication with a USB device.
|
||||
A transfer is an abstract concept that can result in several
|
||||
physical packets being transferred to or from a device.
|
||||
.Pp
|
||||
A transfer is described by a
|
||||
.Va usbd_xfer_handle ,
|
||||
a largely opaque cookie.
|
||||
Allocated and deallocate are performed with
|
||||
.Fn usbd_alloc_xfer
|
||||
and
|
||||
.Fn usbd_free_xfer .
|
||||
The data describing the transfer is filled by either
|
||||
.Fn usbd_setup_default_xfer
|
||||
for control pipe transfers, by
|
||||
.Fn usbd_setup_xfer
|
||||
for bulk and interrupt transfers, and by
|
||||
.Fn usbd_setup_isoc_xfer
|
||||
for isochronous transfers.
|
||||
.Pp
|
||||
A pipe is a logical connection to a USB device.
|
||||
Pipes are created and destroyed by using the
|
||||
.Fn usbd_open_pipe ,
|
||||
.Fn usbd_open_pipe_intr
|
||||
and
|
||||
.Fn usbd_close_pipe
|
||||
functions.
|
||||
It is common to have more than one pipe per device.
|
||||
Pipes are used to allocate
|
||||
.Va usbd_xfer_handle
|
||||
is required to
|
||||
Transfers are aborted via their parent pipe with
|
||||
.Fn usbd_abort_pipe .
|
||||
The
|
||||
.Fn usbd_clear_endpoint_stall
|
||||
and
|
||||
.Fn usbd_clear_endpoint_stall_async
|
||||
functions are used to clear endpoint halt in either a synchronous
|
||||
or asynchronous fashion.
|
||||
The
|
||||
.Fn usbd_bulk_transfer
|
||||
and
|
||||
.Fn usbd_intr_transfer
|
||||
functions are used to transfer data in either an interrupt or
|
||||
bulk fashion.
|
||||
.Pp
|
||||
A request is described by a
|
||||
.Va usb_device_request_t
|
||||
which must be initialised as necessary before calling either
|
||||
.Fn usbd_do_request
|
||||
or
|
||||
.Fn usbd_do_request_flags
|
||||
to submit the request.
|
||||
See the
|
||||
.Sx INITIALISING USB REQUESTS
|
||||
section for more details.
|
||||
.Pp
|
||||
Error handling and other return values are described in
|
||||
.Xr usbd_status 9 .
|
||||
.Sh SYNOPSIS
|
||||
.Ss Functions offered by usbdi.h
|
||||
.Pp
|
||||
.Ft usbd_status
|
||||
.Fn usbd_open_pipe "usbd_interface_handle iface" "uint8_t address" \
|
||||
"uint8_t flags" "usbd_pipe_handle *pipe"
|
||||
@ -225,26 +163,10 @@ Error handling and other return values are described in
|
||||
.Fn usbd_set_polling" usbd_device_handle iface" "int val"
|
||||
.Ft const char *
|
||||
.Fn usbd_errstr "usbd_status err"
|
||||
Return the string associated with
|
||||
.Fa err .
|
||||
.Ft void
|
||||
.Fn usbd_add_dev_event "int type" "usbd_device_handle iface"
|
||||
The
|
||||
.Ar type
|
||||
must be one of
|
||||
.Dv USB_EVENT_CTRLR_ATTACH ,
|
||||
.Dv USB_EVENT_CTRLR_DETACH ,
|
||||
.Dv USB_EVENT_DEVICE_ATTACH
|
||||
and
|
||||
.Dv USB_EVENT_DEVICE_DETACH .
|
||||
.Ft void
|
||||
.Fn usbd_add_drv_event "int type" "usbd_device_handle iface" "device_t dv"
|
||||
The
|
||||
.Fa type
|
||||
must be one of
|
||||
.Dv USB_EVENT_DRIVER_ATTACH
|
||||
and
|
||||
.Dv USB_EVENT_DRIVER_DETACH .
|
||||
.Ft char *
|
||||
.Fn usbd_devinfo_alloc "usbd_device_handle iface" "int showclass"
|
||||
.Ft void
|
||||
@ -278,17 +200,12 @@ and
|
||||
.Ft const struct usb_devno *
|
||||
.Fn usb_lookup "const struct usb_devno *tbl" \
|
||||
"u_int16_t vendor" "u_int16_t product"
|
||||
The
|
||||
.Dv USB_PRODUCT_ANY
|
||||
macro can be used to match any USB product.
|
||||
.Pp
|
||||
.Ss Utilities from usbdi_util.h
|
||||
Based on the routines in
|
||||
.Dv "usbdi.h"
|
||||
.Dv usbdi.h
|
||||
a number of utility functions have been defined that are accessible
|
||||
through
|
||||
.Dv "usbdi_util.h"
|
||||
.Bl -tag -width indent
|
||||
.Dv usbdi_util.h .
|
||||
.Ft usbd_status
|
||||
.Fn usbd_get_desc "usbd_device_handle dev" "int type" "int index" \
|
||||
"int len" "void *desc"
|
||||
@ -336,8 +253,8 @@ through
|
||||
.Ft usbd_status
|
||||
.Fn usbd_get_config "usbd_device_handle dev" "uint8_t *conf"
|
||||
.Ft usbd_status
|
||||
.Fn usbd_get_string_desc "usbd_device_handle dev" "int sindex" "int langid"
|
||||
usb_string_descriptor_t *sdesc"
|
||||
.Fn usbd_get_string_desc "usbd_device_handle dev" "int sindex" "int langid" \
|
||||
"usb_string_descriptor_t *sdesc"
|
||||
.Ft void
|
||||
.Fn usbd_delay_ms "usbd_device_handle dev" "u_int ms"
|
||||
.Ft usbd_status
|
||||
@ -359,9 +276,95 @@ through
|
||||
.\" .Fn usb_detach_wait "device_t dv" "kcondvar_t *cv" "kmutex_t *lk"
|
||||
.\" .Ft void
|
||||
.\" .Fn usb_detach_broadcast "device_t dv" "kcondvar_t *cv"
|
||||
.Sh DESCRIPTION
|
||||
Device driver access to the USB bus centers around transfers.
|
||||
A transfer describes a communication with a USB device.
|
||||
A transfer is an abstract concept that can result in several
|
||||
physical packets being transferred to or from a device.
|
||||
.Pp
|
||||
A transfer is described by a
|
||||
.Va usbd_xfer_handle ,
|
||||
a largely opaque cookie.
|
||||
Allocated and deallocate are performed with
|
||||
.Fn usbd_alloc_xfer
|
||||
and
|
||||
.Fn usbd_free_xfer .
|
||||
The data describing the transfer is filled by either
|
||||
.Fn usbd_setup_default_xfer
|
||||
for control pipe transfers, by
|
||||
.Fn usbd_setup_xfer
|
||||
for bulk and interrupt transfers, and by
|
||||
.Fn usbd_setup_isoc_xfer
|
||||
for isochronous transfers.
|
||||
.Pp
|
||||
A pipe is a logical connection to a USB device.
|
||||
Pipes are created and destroyed by using the
|
||||
.Fn usbd_open_pipe ,
|
||||
.Fn usbd_open_pipe_intr
|
||||
and
|
||||
.Fn usbd_close_pipe
|
||||
functions.
|
||||
It is common to have more than one pipe per device.
|
||||
Pipes are used to allocate
|
||||
.Va usbd_xfer_handle
|
||||
is required to
|
||||
Transfers are aborted via their parent pipe with
|
||||
.Fn usbd_abort_pipe .
|
||||
The
|
||||
.Fn usbd_clear_endpoint_stall
|
||||
and
|
||||
.Fn usbd_clear_endpoint_stall_async
|
||||
functions are used to clear endpoint halt in either a synchronous
|
||||
or asynchronous fashion.
|
||||
The
|
||||
.Fn usbd_bulk_transfer
|
||||
and
|
||||
.Fn usbd_intr_transfer
|
||||
functions are used to transfer data in either an interrupt or
|
||||
bulk fashion.
|
||||
.Pp
|
||||
A request is described by a
|
||||
.Va usb_device_request_t
|
||||
which must be initialised as necessary before calling either
|
||||
.Fn usbd_do_request
|
||||
or
|
||||
.Fn usbd_do_request_flags
|
||||
to submit the request.
|
||||
See the
|
||||
.Sx INITIALISING USB REQUESTS
|
||||
section for more details.
|
||||
.Pp
|
||||
Error handling and other return values are described in
|
||||
.Xr usbd_status 9 .
|
||||
.Pp
|
||||
Comments on particular functions:
|
||||
.Bl -tag -width 10n
|
||||
.It Fn usbd_errstr err
|
||||
Return the string associated with
|
||||
.Fa err .
|
||||
.It Fn usbd_add_dev_event type iface
|
||||
The
|
||||
.Ar type
|
||||
must be one of
|
||||
.Dv USB_EVENT_CTRLR_ATTACH ,
|
||||
.Dv USB_EVENT_CTRLR_DETACH ,
|
||||
.Dv USB_EVENT_DEVICE_ATTACH
|
||||
and
|
||||
.Dv USB_EVENT_DEVICE_DETACH .
|
||||
.It Fn usbd_add_drv_event type iface dv
|
||||
The
|
||||
.Fa type
|
||||
must be one of
|
||||
.Dv USB_EVENT_DRIVER_ATTACH
|
||||
and
|
||||
.Dv USB_EVENT_DRIVER_DETACH .
|
||||
.It Fn usb_lookup tbl vendor product
|
||||
The
|
||||
.Dv USB_PRODUCT_ANY
|
||||
macro can be used to match any USB product.
|
||||
.El
|
||||
.Sh INITIALISING USB REQUESTS
|
||||
There are 5 members of a
|
||||
There are 5 members of a
|
||||
.Va usb_device_request_t
|
||||
that must be initialised:
|
||||
.Pp
|
||||
@ -380,7 +383,7 @@ that must be initialised:
|
||||
.Pp
|
||||
The first two are normal byte values that may be simply assigned,
|
||||
but the last three must be initialised with the
|
||||
.Dv USETW()
|
||||
.Fn USETW
|
||||
macro.
|
||||
.Pp
|
||||
The
|
||||
@ -389,20 +392,20 @@ holds the request type of this USB request, which describes the
|
||||
indended recipient of the request.
|
||||
.Pp
|
||||
This may be one of:
|
||||
.Bl -tag -offset offset -compact
|
||||
.Bl -tag -width UT_WRITEXX -offset offset -compact
|
||||
.It Dv UT_WRITE
|
||||
.It Dv UT_READ
|
||||
.El
|
||||
.Pp
|
||||
with one of:
|
||||
.Bl -tag -offset offset -compact
|
||||
.Bl -tag -width UT_STANDARDXX -offset offset -compact
|
||||
.It Dv UT_STANDARD
|
||||
.It Dv UT_CLASS
|
||||
.It Dv UT_VENDOR
|
||||
.El
|
||||
.Pp
|
||||
and with one of:
|
||||
.Bl -tag -offset offset -compact
|
||||
.Bl -tag -width UT_INTERFACEXX -offset offset -compact
|
||||
.It Dv UT_DEVICE
|
||||
.It Dv UT_INTERFACE
|
||||
.It Dv UT_ENDPOINT
|
||||
@ -410,7 +413,7 @@ and with one of:
|
||||
.El
|
||||
.Pp
|
||||
These are also in combinations as:
|
||||
.Bl -tag -offset offset -compact
|
||||
.Bl -tag -width UT_WRITE_VENDOR_INTERFACEXX -offset offset -compact
|
||||
.It Dv UT_READ_DEVICE
|
||||
.It Dv UT_READ_INTERFACE
|
||||
.It Dv UT_READ_ENDPOINT
|
||||
@ -437,8 +440,9 @@ These are also in combinations as:
|
||||
.Pp
|
||||
The
|
||||
.Fa bRequest
|
||||
describes which request is being made. The available values are:
|
||||
.Bl -tag -offset offset -compact
|
||||
describes which request is being made.
|
||||
The available values are:
|
||||
.Bl -tag -width UR_GET_DESCRIPTORXX -offset offset -compact
|
||||
.It Dv UR_GET_STATUS
|
||||
.It Dv UR_CLEAR_FEATURE
|
||||
.It Dv UR_SET_FEATURE
|
||||
@ -458,9 +462,8 @@ The
|
||||
and
|
||||
.Fa wLength
|
||||
are device-specific values and must be initialised with the
|
||||
.Dv USETW()
|
||||
.Fn USETW
|
||||
macro.
|
||||
.Pp
|
||||
.Sh USB REQUEST TYPES AND STRUCTURES
|
||||
The
|
||||
.Dv UR_GET_STATUS
|
||||
@ -475,7 +478,7 @@ structure, which has this member:
|
||||
For device status requests, the
|
||||
.Fa wStatus
|
||||
member may have either of these bit flags set:
|
||||
.Bl -tag -offset offset -compact
|
||||
.Bl -tag -width UDS_REMOTE_WAKEUPXX -offset offset -compact
|
||||
.It Dv UDS_SELF_POWERED
|
||||
.It Dv UDS_REMOTE_WAKEUP
|
||||
.El
|
||||
@ -483,7 +486,7 @@ member may have either of these bit flags set:
|
||||
For endpoint status requests, the
|
||||
.Fa wStatus
|
||||
member may have this bit flag set:
|
||||
.Bl -tag -offset offset -compact
|
||||
.Bl -tag -width UES_HALTXX -offset offset -compact
|
||||
.It Dv UES_HALT
|
||||
.El
|
||||
.Pp
|
||||
@ -521,7 +524,7 @@ structure, which has these members:
|
||||
The
|
||||
.Fa bDescriptorType
|
||||
member may be one of the following values:
|
||||
.Bl -tag -offset offset -compact
|
||||
.Bl -tag -width UDESC_OTHER_SPEED_CONFIGURATIONXX -offset offset -compact
|
||||
.It Dv UDESC_DEVICE
|
||||
.It Dv UDESC_CONFIG
|
||||
.It Dv UDESC_STRING
|
||||
@ -538,9 +541,9 @@ member may be one of the following values:
|
||||
.It Dv UDESC_CS_STRING
|
||||
.It Dv UDESC_CS_INTERFACE
|
||||
.It Dv UDESC_CS_ENDPOINT
|
||||
.It Dv UDESC_HUB
|
||||
.It Dv UDESC_HUB
|
||||
.El
|
||||
.Pp
|
||||
.\".Pp
|
||||
.\" these have API front ends
|
||||
.\" .It Dv UR_GET_CONFIG
|
||||
.\" .It Dv UR_SET_CONFIG
|
||||
@ -548,7 +551,6 @@ member may be one of the following values:
|
||||
.\" .It Dv UR_SET_INTERFACE
|
||||
.\" this isn't supported
|
||||
.\" .It Dv UR_SYNCH_FRAME
|
||||
.\"
|
||||
.Sh SEE ALSO
|
||||
.Xr usb 4 ,
|
||||
.Xr usbd_status 9
|
||||
|
||||
Loading…
Reference in New Issue
Block a user