Print this page
12309 errors in section 9e of the manual
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man9e/usba_hcdi_pipe_open.9e.man.txt
+++ new/usr/src/man/man9e/usba_hcdi_pipe_open.9e.man.txt
1 1 USBA_HCDI_PIPE_OPEN(9E) Driver Entry Points USBA_HCDI_PIPE_OPEN(9E)
2 2
3 3 NAME
4 4 usba_hcdi_pipe_open, usba_hcdi_pipe_close - open and close a USB pipe
5 5
6 6 SYNOPSIS
7 7 #include <sys/usb/usba/hcdi.h>
8 8
9 9 int
10 10 prefix_hcdi_pipe_open(usba_pipe_handle_data_t *ph,
11 11 usb_flags_t usb_flags);
12 12
13 13 int
14 14 prefix_hcdi_pipe_close(usba_pipe_handle_data_t *ph,
15 15 usb_flags_t usb_flags);
16 16
17 17 INTERFACE LEVEL
18 18 Volatile - illumos USB HCD private function
19 19
20 20 This is a private function that is not part of the stable DDI. It may be
21 21 removed or changed at any time.
22 22
23 23 PARAMETERS
24 24 ph A pointer to a USB pipe handle as defined in
25 25 usba_pipe_handle_data(9S).
26 26
27 27 usb_flags Flags which describe how allocations should be performed.
28 28 Valid flags are:
29 29
30 30 USB_FLAGS_NOSLEEP
31 31 Do not block waiting for memory. If memory is not
32 32 available the allocation will fail.
33 33
34 34 USB_FLAGS_SLEEP
35 35 Perform a blocking allocation. If memory is not
36 36 available, the function will wait until memory is
37 37 made available.
38 38
39 39 Note, the request may still fail even if
40 40 USB_FLAGS_SLEEP is specified.
41 41
42 42 DESCRIPTION
43 43 The usba_hcdi_pipe_open() and usba_hcdi_pipe_close() entry points are
44 44 called by the USB framework whenever a client, or the framework itself,
45 45 need to open or close a specific pipe. For additional background see
46 46 usba_hcdi(9E).
47 47
48 48 When a pipe is opened, the host controller driver is responsible for
49 49 preparing the specified endpoint for performing transfers. This may
50 50 include allocating bandwidth, programming the controller, and more. When
51 51 the pipe is closed, the host controller driver is responsible for
52 52 cleaning up any resources that were allocated during the open call.
53 53
54 54 The pipe handle, ph, identifies the endpoint that it the USBA is trying
55 55 to open or close through its endpoint descriptor in the p_ep member. The
56 56 endpoint descriptor is described in usb_ep_descr(9S). From the endpoint
57 57 descriptor the driver can determine the type of endpoint, what the
58 58 address of the endpoint is, and what direction the endpoint is in. When
59 59 combined, these uniquely describe the pipe.
60 60
61 61 To open a pipe, the driver may need additional companion endpoint
62 62 descriptors. If these are available, they will be in the p_xep member of
63 63 the pipe handle. See usb_ep_xdescr(9S) for more information on how to
64 64 determine which descriptors are present and get the information encoded
65 65 in them.
66 66
67 67 Host controller drivers should check the USB address of the USB device
68 68 that ph belongs to. The driver may be asked to open a pipe to the root
69 69 hub. As the root hub is often synthetic, the driver may need to take a
70 70 different path than normal.
71 71
72 72 Pipe open specifics
73 73 A given endpoint on a device can only be opened once. If there's a
74 74 request to open an already open endpoint, then the request to open the
75 75 pipe should be failed.
76 76
77 77 By the time the call to open a pipe returns, the driver should expect
78 78 that any of the pipe transfer or reset entry points will be called on the
79 79 pipe.
|
↓ open down ↓ |
79 lines elided |
↑ open up ↑ |
80 80
81 81 A driver can establish private data on an endpoint. During pipe open it
82 82 may set the p_hcd_private member to any value. Generally this points to
83 83 an allocated structure that contains data specific to the host
84 84 controller. This value will remain on the pipe handle. It is the
85 85 responsibility of the driver to clear the data when the pipe is closed.
86 86
87 87 Pipe close specifics
88 88 When a pipe is closed, the driver must clean up all of the resources that
89 89 it allocated when opening the pipe. For non-periodic transfers, the host
90 - controller driver may assueme that there are no outstanding transfers
91 - that need to be cleaned up. However, the same is not true for periodic
92 - pipes.
90 + controller driver may assume that there are no outstanding transfers that
91 + need to be cleaned up. However, the same is not true for periodic pipes.
93 92
94 93 For pipes that have outstanding periodic transfers, the host controller
95 94 driver needs to clean them up and quiesce them as though a call to either
96 95 usba_hcdi_pipe_stop_intr_polling(9E) or
97 96 usba_hcdi_pipe_stop_isoc_polling(9E) had been called.
98 97
99 98 Just as with opening the pipe, the driver should pay attention to the
100 99 address of the USB device, as it may be the root hub, which may be a
101 100 synthetic pipe.
102 101
103 102 When a call to usba_hcdi_pipe_close() completes, the device should be in
104 103 a state that the pipe can be opened again.
105 104
|
↓ open down ↓ |
3 lines elided |
↑ open up ↑ |
106 105 RETURN VALUES
107 106 Upon successful completion, the usba_hcdi_pipe_open() and
108 107 uba_hcdi_pipe_close() functions should return USB_SUCCESS. Otherwise, it
109 108 should return the appropriate USB error. If uncertain, use USB_FAILURE.
110 109
111 110 SEE ALSO
112 111 usba_hcdi(9E), usba_hcdi_pipe_stop_intr_polling(9E),
113 112 usba_hcdi_pipe_stop_isoc_polling(9E), usb_ep_descr(9S),
114 113 usb_ep_xdescr(9S), usba_pipe_handle_data(9S)
115 114
116 -illumos November 26, 2017 illumos
115 +illumos February 15, 2020 illumos
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX