source: mainline/uspace/lib/usbdev/src/pipesinit.c@ 86650db

lfn serial ticket/834-toolchain-update topic/msim-upgrade topic/simplify-dev-export
Last change on this file since 86650db was 86650db, checked in by Ondřej Hlavatý <aearsis@…>, 7 years ago

usbdev refactoring: isolate standard descriptor parsing

  • Property mode set to 100644
File size: 13.5 KB
RevLine 
[93ef8f6]1/*
2 * Copyright (c) 2011 Vojtech Horky
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * - Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 * - Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
14 * - The name of the author may not be used to endorse or promote products
15 * derived from this software without specific prior written permission.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 */
28
[160b75e]29/** @addtogroup libusbdev
[93ef8f6]30 * @{
31 */
32/** @file
[3538b0e]33 * Non trivial initialization of endpoint pipes.
[93ef8f6]34 *
35 */
[7d521e24]36#include <usb/dev/pipes.h>
37#include <usb/dev/dp.h>
38#include <usb/dev/request.h>
[c01987c]39#include <usb/usb.h>
[ec700c7]40#include <usb/debug.h>
[c01987c]41#include <usb/descriptor.h>
42
[93ef8f6]43#include <assert.h>
[c01987c]44#include <errno.h>
[93ef8f6]45
[206f71a]46#define DEV_DESCR_MAX_PACKET_SIZE_OFFSET 7
47
[93ef8f6]48#define NESTING(parentname, childname) \
49 { \
50 .child = USB_DESCTYPE_##childname, \
51 .parent = USB_DESCTYPE_##parentname, \
52 }
53#define LAST_NESTING { -1, -1 }
54
55/** Nesting pairs of standard descriptors. */
[3ddbd38]56static const usb_dp_descriptor_nesting_t descriptor_nesting[] = {
[93ef8f6]57 NESTING(CONFIGURATION, INTERFACE),
58 NESTING(INTERFACE, ENDPOINT),
59 NESTING(INTERFACE, HUB),
60 NESTING(INTERFACE, HID),
61 NESTING(HID, HID_REPORT),
[ec700c7]62 NESTING(ENDPOINT, SSPEED_EP_COMPANION),
[93ef8f6]63 LAST_NESTING
64};
65
66/** Tells whether given descriptor is of endpoint type.
67 *
68 * @param descriptor Descriptor in question.
69 * @return Whether the given descriptor is endpoint descriptor.
70 */
[8a121b1]71static inline bool is_endpoint_descriptor(const uint8_t *descriptor)
[93ef8f6]72{
73 return descriptor[1] == USB_DESCTYPE_ENDPOINT;
74}
75
[ec700c7]76/** Tells whether given descriptor is of superspeed companion type.
77 *
78 * @param descriptor Descriptor in question.
79 * @return Whether the given descriptor is superspeed companion descriptor.
80 */
81static inline bool is_superspeed_companion_descriptor(const uint8_t *descriptor)
82{
83 return descriptor[1] == USB_DESCTYPE_SSPEED_EP_COMPANION;
84}
85
[93ef8f6]86/** Tells whether found endpoint corresponds to endpoint described by user.
87 *
88 * @param wanted Endpoint description as entered by driver author.
89 * @param found Endpoint description obtained from endpoint descriptor.
90 * @return Whether the @p found descriptor fits the @p wanted descriptor.
91 */
92static bool endpoint_fits_description(const usb_endpoint_description_t *wanted,
[8a121b1]93 const usb_endpoint_description_t *found)
[93ef8f6]94{
95#define _SAME(fieldname) ((wanted->fieldname) == (found->fieldname))
96
97 if (!_SAME(direction)) {
98 return false;
99 }
100
101 if (!_SAME(transfer_type)) {
102 return false;
103 }
104
105 if ((wanted->interface_class >= 0) && !_SAME(interface_class)) {
106 return false;
107 }
108
109 if ((wanted->interface_subclass >= 0) && !_SAME(interface_subclass)) {
110 return false;
111 }
112
113 if ((wanted->interface_protocol >= 0) && !_SAME(interface_protocol)) {
114 return false;
115 }
116
117#undef _SAME
118
119 return true;
120}
121
122/** Find endpoint mapping for a found endpoint.
123 *
124 * @param mapping Endpoint mapping list.
125 * @param mapping_count Number of endpoint mappings in @p mapping.
126 * @param found_endpoint Description of found endpoint.
[18cb870]127 * @param interface_number Number of currently processed interface.
[93ef8f6]128 * @return Endpoint mapping corresponding to @p found_endpoint.
129 * @retval NULL No corresponding endpoint found.
130 */
131static usb_endpoint_mapping_t *find_endpoint_mapping(
132 usb_endpoint_mapping_t *mapping, size_t mapping_count,
[8a121b1]133 const usb_endpoint_description_t *found_endpoint,
[159b91f4]134 int interface_number, int interface_setting)
[93ef8f6]135{
136 while (mapping_count > 0) {
[18cb870]137 bool interface_number_fits = (mapping->interface_no < 0)
138 || (mapping->interface_no == interface_number);
139
[159b91f4]140 bool interface_setting_fits = (mapping->interface_setting < 0)
141 || (mapping->interface_setting == interface_setting);
142
[18cb870]143 bool endpoint_descriptions_fits = endpoint_fits_description(
144 mapping->description, found_endpoint);
145
[159b91f4]146 if (interface_number_fits
147 && interface_setting_fits
148 && endpoint_descriptions_fits) {
[93ef8f6]149 return mapping;
150 }
151
152 mapping++;
153 mapping_count--;
154 }
155 return NULL;
156}
157
[86650db]158static void parse_endpoint_descriptors(usb_endpoint_desc_t *ep_desc,
159 usb_standard_endpoint_descriptor_t *endpoint_desc,
160 usb_superspeed_endpoint_companion_descriptor_t *companion_desc)
161{
162 *ep_desc = (usb_endpoint_desc_t) {
163 /* Actual endpoint number is in bits 0..3 */
164 .endpoint_no = endpoint_desc->endpoint_address & 0x0F,
165 /* Transfer type is in bits 0..2 and
166 * the enum values corresponds 1:1 */
167 .transfer_type = endpoint_desc->attributes & 3,
168 /* Endpoint direction is set by bit 7 */
169 .direction = (endpoint_desc->endpoint_address & 128)
170 ? USB_DIRECTION_IN : USB_DIRECTION_OUT,
171 // FIXME: USB2 max_packet_size is limited to 1023 bytes, 1024+ doesn't work for USB3
172 // See 4.14.2.1.1 of XHCI specification -> possibly refactor into one somehow-named field
173 .max_packet_size
174 = ED_MPS_PACKET_SIZE_GET(uint16_usb2host(endpoint_desc->max_packet_size)),
175 .interval = endpoint_desc->poll_interval,
176 // FIXME: USB2 packets and USB3 max_burst are probably the same thing
177 .packets = ED_MPS_TRANS_OPPORTUNITIES_GET(uint16_usb2host(endpoint_desc->max_packet_size)),
178 };
179
180 /* TODO Extract USB2-related information */
181 ep_desc->usb2 = (usb2_endpoint_desc_t) { 0 };
182
183 if (companion_desc) {
184 ep_desc->usb3 = (usb3_endpoint_desc_t) {
185 .max_burst = companion_desc->max_burst,
186 .max_streams
187 = SS_COMPANION_MAX_STREAMS(companion_desc->attributes),
188 .bytes_per_interval
189 = companion_desc->bytes_per_interval,
190 .mult = SS_COMPANION_MULT(companion_desc->attributes),
191 };
192 }
193}
194
195
[93ef8f6]196/** Process endpoint descriptor.
197 *
198 * @param mapping Endpoint mapping list.
199 * @param mapping_count Number of endpoint mappings in @p mapping.
200 * @param interface Interface descriptor under which belongs the @p endpoint.
201 * @param endpoint Endpoint descriptor.
[ec700c7]202 * @param companion Superspeed companion descriptor.
[93ef8f6]203 * @return Error code.
204 */
205static int process_endpoint(
206 usb_endpoint_mapping_t *mapping, size_t mapping_count,
207 usb_standard_interface_descriptor_t *interface,
[48f0f73a]208 usb_standard_endpoint_descriptor_t *endpoint_desc,
[ec700c7]209 usb_superspeed_endpoint_companion_descriptor_t *companion_desc,
[d93f5afb]210 usb_dev_session_t *bus_session)
[93ef8f6]211{
212
213 /*
214 * Get endpoint characteristics.
215 */
[86650db]216 usb_endpoint_desc_t ep_desc;
217 parse_endpoint_descriptors(&ep_desc, endpoint_desc, companion_desc);
[8a121b1]218
219 const usb_endpoint_description_t description = {
[86650db]220 .direction = ep_desc.direction,
221 .transfer_type = ep_desc.transfer_type,
[8a121b1]222
223 /* Get interface characteristics. */
224 .interface_class = interface->interface_class,
225 .interface_subclass = interface->interface_subclass,
226 .interface_protocol = interface->interface_protocol,
227 };
[93ef8f6]228
229 /*
230 * Find the most fitting mapping and initialize the pipe.
231 */
232 usb_endpoint_mapping_t *ep_mapping = find_endpoint_mapping(mapping,
[159b91f4]233 mapping_count, &description,
234 interface->interface_number, interface->alternate_setting);
[93ef8f6]235 if (ep_mapping == NULL) {
236 return ENOENT;
237 }
238
239 if (ep_mapping->present) {
[8a637a4]240 return EEXIST;
[93ef8f6]241 }
242
[9e5b162]243 int err = usb_pipe_initialize(&ep_mapping->pipe, bus_session, &ep_desc);
244 if (err)
245 return err;
[93ef8f6]246
247 ep_mapping->present = true;
[48f0f73a]248 ep_mapping->descriptor = endpoint_desc;
[ec700c7]249 ep_mapping->companion_descriptor = companion_desc;
[9d4579e]250 ep_mapping->interface = interface;
[93ef8f6]251
252 return EOK;
253}
254
255/** Process whole USB interface.
256 *
257 * @param mapping Endpoint mapping list.
258 * @param mapping_count Number of endpoint mappings in @p mapping.
259 * @param parser Descriptor parser.
260 * @param parser_data Descriptor parser data.
261 * @param interface_descriptor Interface descriptor.
262 * @return Error code.
263 */
264static int process_interface(
265 usb_endpoint_mapping_t *mapping, size_t mapping_count,
[7c95d6f5]266 const usb_dp_parser_t *parser, const usb_dp_parser_data_t *parser_data,
[8582076]267 const uint8_t *interface_descriptor, usb_dev_session_t *bus_session)
[93ef8f6]268{
[8a121b1]269 const uint8_t *descriptor = usb_dp_get_nested_descriptor(parser,
[93ef8f6]270 parser_data, interface_descriptor);
271
272 if (descriptor == NULL) {
273 return ENOENT;
274 }
275
276 do {
277 if (is_endpoint_descriptor(descriptor)) {
[ec700c7]278 /* Check if companion descriptor is present too, it should immediatelly follow. */
279 const uint8_t *companion_desc = usb_dp_get_nested_descriptor(parser,
280 parser_data, descriptor);
281 if (companion_desc && !is_superspeed_companion_descriptor(companion_desc)) {
282 /* Not what we wanted, don't pass it further. */
283 companion_desc = NULL;
284 }
285
[93ef8f6]286 (void) process_endpoint(mapping, mapping_count,
287 (usb_standard_interface_descriptor_t *)
288 interface_descriptor,
289 (usb_standard_endpoint_descriptor_t *)
290 descriptor,
[ec700c7]291 (usb_superspeed_endpoint_companion_descriptor_t *)
292 companion_desc,
[8582076]293 bus_session);
[93ef8f6]294 }
295
296 descriptor = usb_dp_get_sibling_descriptor(parser, parser_data,
297 interface_descriptor, descriptor);
298 } while (descriptor != NULL);
299
300 return EOK;
301}
302
303/** Initialize endpoint pipes from configuration descriptor.
304 *
305 * The mapping array is expected to conform to following rules:
[b77931d]306 * - @c pipe must be uninitialized pipe
[93ef8f6]307 * - @c description must point to prepared endpoint description
308 * - @c descriptor does not need to be initialized (will be overwritten)
[9d4579e]309 * - @c interface does not need to be initialized (will be overwritten)
[93ef8f6]310 * - @c present does not need to be initialized (will be overwritten)
311 *
312 * After processing the configuration descriptor, the mapping is updated
313 * in the following fashion:
314 * - @c present will be set to @c true when the endpoint was found in the
315 * configuration
316 * - @c descriptor will point inside the configuration descriptor to endpoint
[1110ebd]317 * corresponding to given description (or NULL for not found descriptor)
[9d4579e]318 * - @c interface will point inside the configuration descriptor to interface
319 * descriptor the endpoint @c descriptor belongs to (or NULL for not found
320 * descriptor)
[93ef8f6]321 * - @c pipe will be initialized when found, otherwise left untouched
322 * - @c description will be untouched under all circumstances
323 *
324 * @param mapping Endpoint mapping list.
325 * @param mapping_count Number of endpoint mappings in @p mapping.
326 * @param configuration_descriptor Full configuration descriptor (is expected
327 * to be in USB endianness: i.e. as-is after being retrieved from
328 * the device).
329 * @param configuration_descriptor_size Size of @p configuration_descriptor
330 * in bytes.
331 * @param connection Connection backing the endpoint pipes.
332 * @return Error code.
333 */
[3954a63b]334int usb_pipe_initialize_from_configuration(
[93ef8f6]335 usb_endpoint_mapping_t *mapping, size_t mapping_count,
[7c95d6f5]336 const uint8_t *config_descriptor, size_t config_descriptor_size,
[d93f5afb]337 usb_dev_session_t *bus_session)
[93ef8f6]338{
[58563585]339 if (config_descriptor == NULL)
[93ef8f6]340 return EBADMEM;
[816f5f4]341
[58563585]342 if (config_descriptor_size <
343 sizeof(usb_standard_configuration_descriptor_t)) {
[93ef8f6]344 return ERANGE;
345 }
346
[b77931d]347 /* Go through the mapping and set all endpoints to not present. */
348 for (size_t i = 0; i < mapping_count; i++) {
[93ef8f6]349 mapping[i].present = false;
350 mapping[i].descriptor = NULL;
[9d4579e]351 mapping[i].interface = NULL;
[93ef8f6]352 }
353
[b77931d]354 /* Prepare the descriptor parser. */
[7c95d6f5]355 const usb_dp_parser_t dp_parser = {
[93ef8f6]356 .nesting = descriptor_nesting
357 };
[7c95d6f5]358 const usb_dp_parser_data_t dp_data = {
359 .data = config_descriptor,
360 .size = config_descriptor_size,
[93ef8f6]361 };
362
363 /*
364 * Iterate through all interfaces.
365 */
[8a121b1]366 const uint8_t *interface = usb_dp_get_nested_descriptor(&dp_parser,
[7c95d6f5]367 &dp_data, config_descriptor);
[93ef8f6]368 if (interface == NULL) {
369 return ENOENT;
370 }
371 do {
372 (void) process_interface(mapping, mapping_count,
[8582076]373 &dp_parser, &dp_data, interface, bus_session);
[93ef8f6]374 interface = usb_dp_get_sibling_descriptor(&dp_parser, &dp_data,
[7c95d6f5]375 config_descriptor, interface);
[93ef8f6]376 } while (interface != NULL);
377
378 return EOK;
379}
380
[206f71a]381/** Probe default control pipe for max packet size.
382 *
383 * The function tries to get the correct value of max packet size several
384 * time before giving up.
385 *
386 * The session on the pipe shall not be started.
387 *
388 * @param pipe Default control pipe.
389 * @return Error code.
390 */
[3954a63b]391int usb_pipe_probe_default_control(usb_pipe_t *pipe)
[206f71a]392{
393 assert(pipe);
[1cf26ab]394 static_assert(DEV_DESCR_MAX_PACKET_SIZE_OFFSET < CTRL_PIPE_MIN_PACKET_SIZE);
[206f71a]395
[816f5f4]396 if ((pipe->desc.direction != USB_DIRECTION_BOTH) ||
397 (pipe->desc.transfer_type != USB_TRANSFER_CONTROL) ||
398 (pipe->desc.endpoint_no != 0)) {
[206f71a]399 return EINVAL;
400 }
401
402 uint8_t dev_descr_start[CTRL_PIPE_MIN_PACKET_SIZE];
403 size_t transferred_size;
[02fc5c4]404 int rc;
405 for (size_t attempt_var = 0; attempt_var < 3; ++attempt_var) {
[206f71a]406 rc = usb_request_get_descriptor(pipe, USB_REQUEST_TYPE_STANDARD,
407 USB_REQUEST_RECIPIENT_DEVICE, USB_DESCTYPE_DEVICE,
408 0, 0, dev_descr_start, CTRL_PIPE_MIN_PACKET_SIZE,
409 &transferred_size);
410 if (rc == EOK) {
411 if (transferred_size != CTRL_PIPE_MIN_PACKET_SIZE) {
412 rc = ELIMIT;
413 continue;
414 }
415 break;
416 }
417 }
418 if (rc != EOK) {
[bf4cc3e]419 return rc;
420 }
[dc04868]421
[816f5f4]422 pipe->desc.max_packet_size
[206f71a]423 = dev_descr_start[DEV_DESCR_MAX_PACKET_SIZE_OFFSET];
424
425 return EOK;
[dc04868]426}
427
[93ef8f6]428/**
429 * @}
430 */
Note: See TracBrowser for help on using the repository browser.