Tue Jan 22 15:35:08 2013 UTC ()
document USBD_MPSAFE and USB_TASKQ_MPSAFE


(jmcneill)
diff -r1.24 -r1.25 src/share/man/man9/usbdi.9
cvs diff -r1.24 -r1.25 src/share/man/man9/usbdi.9 (expand / switch to unified diff)

--- src/share/man/man9/usbdi.9 2012/07/20 07:55:44 1.24
+++ src/share/man/man9/usbdi.9 2013/01/22 15:35:08 1.25
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1.\" $NetBSD: usbdi.9,v 1.24 2012/07/20 07:55:44 mrg Exp $ 1.\" $NetBSD: usbdi.9,v 1.25 2013/01/22 15:35:08 jmcneill Exp $
2.\" 2.\"
3.\" Copyright (c) 2012 Matthew R. Green 3.\" Copyright (c) 2012 Matthew R. Green
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" Redistribution and use in source and binary forms, with or without 6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions 7.\" modification, are permitted provided that the following conditions
8.\" are met: 8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright 9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer. 10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the 12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution. 13.\" documentation and/or other materials provided with the distribution.
14.\" 3. The name of the author may not be used to endorse or promote products 14.\" 3. The name of the author may not be used to endorse or promote products
@@ -44,27 +44,27 @@ @@ -44,27 +44,27 @@
44.\" 44.\"
45.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 45.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
46.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 46.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
47.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 47.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
48.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 48.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
49.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 49.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
50.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 50.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
51.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 51.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
52.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 52.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
53.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 53.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
54.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 54.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
55.\" POSSIBILITY OF SUCH DAMAGE. 55.\" POSSIBILITY OF SUCH DAMAGE.
56.\" 56.\"
57.Dd July 20, 2012 57.Dd January 22, 2013
58.Dt USBDI 9 58.Dt USBDI 9
59.Os 59.Os
60.Sh NAME 60.Sh NAME
61.Nm usbdi 61.Nm usbdi
62.Nd USB device drivers interface 62.Nd USB device drivers interface
63.Sh SYNOPSIS 63.Sh SYNOPSIS
64.In dev/usb/usb.h 64.In dev/usb/usb.h
65.In dev/usb/usbdi.h 65.In dev/usb/usbdi.h
66.In dev/usb/usbdi_util.h 66.In dev/usb/usbdi_util.h
67.Ss Functions offered by usbdi.h 67.Ss Functions offered by usbdi.h
68.Ft usbd_status 68.Ft usbd_status
69.Fn usbd_open_pipe "usbd_interface_handle iface" "uint8_t address" \ 69.Fn usbd_open_pipe "usbd_interface_handle iface" "uint8_t address" \
70 "uint8_t flags" "usbd_pipe_handle *pipe" 70 "uint8_t flags" "usbd_pipe_handle *pipe"
@@ -189,27 +189,27 @@ @@ -189,27 +189,27 @@
189.Fn usbd_get_string0 "usbd_device_handle iface" "int" si "char *buf" \ 189.Fn usbd_get_string0 "usbd_device_handle iface" "int" si "char *buf" \
190 "int unicode" 190 "int unicode"
191.Ft void 191.Ft void
192.Fn usb_desc_iter_init "usbd_device_handle iface" "usbd_desc_iter_t *iter" 192.Fn usb_desc_iter_init "usbd_device_handle iface" "usbd_desc_iter_t *iter"
193.Ft const usb_descriptor_t * 193.Ft const usb_descriptor_t *
194.Fn usb_desc_iter_next "usbd_desc_iter_t *iter" 194.Fn usb_desc_iter_next "usbd_desc_iter_t *iter"
195.Ft void 195.Ft void
196.Fn usb_add_task "usbd_device_handle iface" "struct usb_task *task" \ 196.Fn usb_add_task "usbd_device_handle iface" "struct usb_task *task" \
197 "int queue" 197 "int queue"
198.Ft void 198.Ft void
199.Fn usb_rem_task "usbd_device_handle iface" "struct usb_task *task" 199.Fn usb_rem_task "usbd_device_handle iface" "struct usb_task *task"
200.Ft void 200.Ft void
201.Fn usb_init_task "struct usb_task *task" "void (*func)(void *)" \ 201.Fn usb_init_task "struct usb_task *task" "void (*func)(void *)" \
202 "void *arg" 202 "void *arg" uint8_t flags
203.Ft const struct usb_devno * 203.Ft const struct usb_devno *
204.Fn usb_lookup "const struct usb_devno *tbl" \ 204.Fn usb_lookup "const struct usb_devno *tbl" \
205 "u_int16_t vendor" "u_int16_t product" 205 "u_int16_t vendor" "u_int16_t product"
206.Ss Utilities from usbdi_util.h 206.Ss Utilities from usbdi_util.h
207Based on the routines in 207Based on the routines in
208.Dv usbdi.h 208.Dv usbdi.h
209a number of utility functions have been defined that are accessible 209a number of utility functions have been defined that are accessible
210through 210through
211.Dv usbdi_util.h . 211.Dv usbdi_util.h .
212.Ft usbd_status 212.Ft usbd_status
213.Fn usbd_get_desc "usbd_device_handle dev" "int type" "int index" \ 213.Fn usbd_get_desc "usbd_device_handle dev" "int type" "int index" \
214 "int len" "void *desc" 214 "int len" "void *desc"
215.Ft usbd_status 215.Ft usbd_status
@@ -480,29 +480,32 @@ macro can be used to match any USB produ @@ -480,29 +480,32 @@ macro can be used to match any USB produ
480.Sh PIPES 480.Sh PIPES
481Pipes are created and destroyed by using the 481Pipes are created and destroyed by using the
482.Fn usbd_open_pipe , 482.Fn usbd_open_pipe ,
483.Fn usbd_open_pipe_intr 483.Fn usbd_open_pipe_intr
484and 484and
485.Fn usbd_close_pipe 485.Fn usbd_close_pipe
486functions. 486functions.
487The open functions take the interface handle 487The open functions take the interface handle
488.Fa iface , 488.Fa iface ,
489the 489the
490.Fa address 490.Fa address
491of this pipe and 491of this pipe and
492.Fa flags 492.Fa flags
493for this pipe which currently may be 0 or 493for this pipe which currently may be 0, or a combination of
494.Dv USBD_EXCLUSIVE_USE , 494.Dv USBD_EXCLUSIVE_USE ,
495to enable exclusive access to this interface and address. 495to enable exclusive access to this interface and address, and
 496.Dv USBD_MPSAFE ,
 497to allow running transfer callbacks on this pipe without first acquiring
 498.Dv kernel_lock .
496The 499The
497.Fn usbd_open_pipe_intr 500.Fn usbd_open_pipe_intr
498takes additional arguments 501takes additional arguments
499.Fa priv 502.Fa priv
500to set the default private handle. 503to set the default private handle.
501.Fa buffer 504.Fa buffer
502and 505and
503.Fa len 506.Fa len
504to describe the buffer to be used, 507to describe the buffer to be used,
505.Fa callback 508.Fa callback
506for the function to call at interrupt time, and finally the 509for the function to call at interrupt time, and finally the
507.Fa interval 510.Fa interval
508for interrupts to be delivered in milliseconds. 511for interrupts to be delivered in milliseconds.
@@ -913,29 +916,39 @@ function works like @@ -913,29 +916,39 @@ function works like
913.Sh USB TASK MANAGEMENT 916.Sh USB TASK MANAGEMENT
914The USB stack provides a task management framework to execute tasks 917The USB stack provides a task management framework to execute tasks
915in a thread context at the soonest opportunity. 918in a thread context at the soonest opportunity.
916Typically this is used by network drivers to handle periodic updates 919Typically this is used by network drivers to handle periodic updates
917or status change requests, or other operations that need to run in 920or status change requests, or other operations that need to run in
918a normal context. 921a normal context.
919.Pp 922.Pp
920The 923The
921.Fn usb_init_task 924.Fn usb_init_task
922function takes a pointer to a 925function takes a pointer to a
923.Ft struct usb_task 926.Ft struct usb_task
924that will be initalised, a function to call for this task 927that will be initalised, a function to call for this task
925.Fa func , 928.Fa func ,
926and the argument to pass to 929the argument to pass to
927.Fa func , 930.Fa func ,
928.Fa arg . 931.Fa arg ,
 932and the task flags
 933.Fa flags .
 934If the
 935.Fa flags
 936argument is
 937.Dt USB_TASKQ_MPSAFE ,
 938the
 939.Fa func
 940function will be called without first acquiring
 941.Dt kernel_lock .
929.Pp 942.Pp
930To invoke the task callback the 943To invoke the task callback the
931.Fn usb_add_task 944.Fn usb_add_task
932function should be called with the 945function should be called with the
933.Fa iface 946.Fa iface
934associated with this device, the task structure 947associated with this device, the task structure
935.Fa task , 948.Fa task ,
936and the 949and the
937.Fa queue 950.Fa queue
938to run against, either 951to run against, either
939.Dv USB_TASKQ_HC 952.Dv USB_TASKQ_HC
940for operations initiated by host controllers or 953for operations initiated by host controllers or
941.Dv USB_TASKQ_DRIVER 954.Dv USB_TASKQ_DRIVER