1usb_request_attributes(9S)Data Structures for Driversusb_request_attributes(9S)
2
6 usb_request_attributes - Definition of USB request attributes
7
9 #include <sys/usb/usba.h>
10
13 Solaris DDI specific (Solaris DDI)
14
16 Request attributes specify how the USBA framework handles request exe‐
17 cution. Request attributes are specified in the request's *_attributes
18 field and belong to the enumerated type usb_req_attrs_t.
19 Supported request attributes are:
22 USB_ATTRS_SHORT_XFER_OK Use this attribute when the maximum
24 transfer size is known, but it is pos‐
25 sible for the request to receive a
26 smaller amount of data. This attribute
27 tells the USBA framework to accept with‐
28 out error transfers which are shorter
29 than expected.
30 USB_ATTRS_PIPE_RESET Have the USB framework reset the pipe
33 automatically if an error occurs dur‐
34 ing the transfer. Do not attempt to clear
35 any stall. The USB_CB_RESET_PIPE callback
36 flag is passed to the client driver's
37 exception handler to show the pipe has
38 been reset. Pending requests on pipes
39 which are reset are flushed unless the
40 pipe is the default pipe.
41 USB_ATTRS_AUTOCLEARING Have the USB framework reset the pipe and
44 clear functional stalls automatically if
45 an error occurs during the transfer. The
46 callback flags passed to the client
47 driver's exception handler show the sta‐
48 tus after the attempt to clear the stall.
49 USB_CB_FUNCTIONAL_STALL is set in the
51 callback flags to indicate that a func‐
52 tional stall occurred.
53 USB_CB_STALL_CLEARED is also set if the
54 stall is cleared. The default pipe never
55 shows a functional stall if the
56 USB_ATTRS_AUTOCLEARING attribute is set.
57 If USB_CB_FUNCTIONAL_STALL is seen when
58 autoclearing is enabled, the device has a
59 fatal error.
60 USB_CB_PROTOCOL_STALL is set without
62 USB_CB_STALL_CLEARED in the callback
63 flags to indicate that a protocol stall
64 was seen but was not explicitly cleared.
65 Protocol stalls are cleared automatically
66 when a subsequent command is issued.
67 Autoclearing a stalled default pipe is
69 not allowed. The USB_CB_PROTOCOL_STALL
70 callback flag is set in the callback
71 flags to indicate the default pipe is
72 stalled.
73 Autoclearing is not allowed when the
75 request is USB_REQ_GET_STATUS on the
76 default pipe.
77 USB_ATTRS_ONE_XFER Applies only to interrupt-IN requests.
80 Without this flag, interrupt-IN requests
81 start periodic polling of the interrupt
82 pipe. This flag specifies to perform only
83 a single transfer. Do not start periodic
84 transfers with this request.
85 USB_ATTRS_ISOC_START_FRAME Applies only to isochronous requests and
88 specifies that a request be started at a
89 given frame number. The starting frame
90 number is provided in the isoc_frame_no
91 field of the usb_isoc_req_t. Please see
92 usb_isoc_request(9S) for more information
93 about isochronous requests.
94 USB_ATTRS_ISOC_START_FRAME can be used to
96 delay a transfer by a few frames, allow‐
97 ing transfers to an endpoint to sync up
98 with another source. (For example,
99 synching up audio endpoints to a video
100 source.) The number of a suitable start‐
101 ing frame in the near future can be found
102 by adding an offset number of frames
103 (usually between four and ten) to the
104 current frame number returned from
105 usb_get_current_frame_number(9F). Note
106 that requests with starting frames which
107 have passed are rejected.
108 USB_ATTRS_ISOC_XFER_ASAP Applies only to isochronous requests and
111 specifies that a request start as soon as
112 possible. The host controller driver
113 picks a starting frame number which imme‐
114 diately follows the last frame of the
115 last queued request. The isoc_frame_no of
116 the usb_isoc_req_t is ignored. Please see
117 usb_isoc_request(9S) for more information
118 about isochronous requests.
119
122 /*
123 * Allocate, initialize and issue a synchronous bulk-IN request.
124 * Allow for short transfers.
125 */
126 struct buf *bp;
128 usb_bulk_req_t bulk_req;
129 mblk_t *mblk;
130 bulk_req = usb_alloc_bulk_req(dip, bp->b_bcount, USB_FLAGS_SLEEP);
132 bulk_req->bulk_attributes =
134 USB_ATTRS_AUTOCLEARING | USB_ATTRS_SHORT_XFER_OK;
135 if ((rval = usb_pipe_bulk_xfer(pipe, bulk_req, USB_FLAGS_SLEEP)) !=
137 USB_SUCCESS) {
138 cmn_err (CE_WARN, "%s%d: Error reading bulk data.",
139 ddi_driver_name(dip), ddi_get_instance(dip));
140 }
141 mblk = bulk_req->bulk_data;
143 bcopy(mblk->rptr, buf->b_un.b_addr, mblk->wptr - mblk->rptr);
144 bp->b_resid = bp->b_count - (mblk->wptr = mblk->rptr);
145 ...
146 ...
147 ----
149 usb_pipe_handle_t handle;
151 usb_frame_number_t offset = 10;
152 usb_isoc_req_t *isoc_req;
153 isoc_req = usb_alloc_isoc_req(...);
155 ...
156 ...
157 isoc_req->isoc_frame_no = usb_get_current_frame_number(dip) + offset;
158 isoc_req->isoc_attributes = USB_ATTRS_ISOC_START_FRAME;
159 ...
160 ...
161 if (usb_pipe_isoc_xfer(handle, isoc_req, 0) != USB_SUCCESS) {
162 ...
163 }
164
167 See attributes(5) for descriptions of the following attributes:
168 ┌─────────────────────────────┬─────────────────────────────┐
173 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
174 ├─────────────────────────────┼─────────────────────────────┤
175 │Architecture │PCI-based systems │
176 ├─────────────────────────────┼─────────────────────────────┤
177 │Interface stability │Committed │
178 ├─────────────────────────────┼─────────────────────────────┤
179 │Availability │SUNWusb, SUNWusbu │
180 └─────────────────────────────┴─────────────────────────────┘
181
183 usb_alloc_request(9F), usb_get_current_frame_number(9F),
184 usb_pipe_bulk_xfer(9F), usb_pipe_ctrl_xfer(9F), usb_pipe_intr_xfer(9F),
185 usb_pipe_isoc_xfer(9F), usb_bulk_request(9S), usb_callback_flags(9S),
186 usb_ctrl_request(9S), usb_intr_request(9S), usb_isoc_request(9S),
187 usb_completion_reason(9S)
188SunOS 5.11 5 Jan 2004 usb_request_attributes(9S)