+/rtos

git clone https://git.julia.blue/+/rtos

Joseph RyanRe-add usblib files83915e3

master
17.1 KiB453 linesraw
1//*****************************************************************************
2//
3// usbdesc.c - USB descriptor parsing functions.
4//
5// Copyright (c) 2008-2017 Texas Instruments Incorporated.  All rights reserved.
6// Software License Agreement
7//
8// Texas Instruments (TI) is supplying this software for use solely and
9// exclusively on TI's microcontroller products. The software is owned by
10// TI and/or its suppliers, and is protected under applicable copyright
11// laws. You may not combine this software with "viral" open-source
12// software in order to form a larger program.
13//
14// THIS SOFTWARE IS PROVIDED "AS IS" AND WITH ALL FAULTS.
15// NO WARRANTIES, WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT
16// NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
17// A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. TI SHALL NOT, UNDER ANY
18// CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
19// DAMAGES, FOR ANY REASON WHATSOEVER.
20//
21// This is part of revision 2.1.4.178 of the Tiva USB Library.
22//
23//*****************************************************************************
24
25#include "tivaware/hw_types.h"
26#include "usblib/usblib.h"
27#include <stdbool.h>
28#include <stdint.h>
29
30//*****************************************************************************
31//
32// Assumptions:
33// ------------
34//
35// The following assumptions are made in this module.  From reading chapter 9
36// of the USB 2.0 specification, these appear to be perfectly valid.
37//
38// 1.  The interface number, bInterfaceNumber in the interface descriptor, is
39//     a zero based index and takes values between 0 and
40//     (pConfigDescriptor->bNumInterfaces - 1) inclusive.
41// 2.  Similarly, the alternate setting number, bAlternateSetting in the
42//     interface descriptor, is a zero based index.
43// 3.  Interface descriptors are ordered by interface number in the
44//     configuration descriptor.
45// 4.  If alternate settings are available for an interface, the interface
46//     descriptors are ordered by alternate setting value bAlternateSetting.
47// 5.  Although the endpoints associated with a given interface must follow
48//     their associated interface descriptor, it is possible for other,
49//     device specific descriptors to be found between an interface descriptor
50//     and its endpoints or between endpoint descriptors for the same
51//     interface.
52//
53//*****************************************************************************
54
55//*****************************************************************************
56//
57//! \addtogroup general_usblib_api
58//! @{
59//
60//*****************************************************************************
61
62//*****************************************************************************
63//
64//! Determines the number of individual descriptors of a particular type within
65//! a supplied buffer.
66//!
67//! \param psDesc points to the first byte of a block of standard USB
68//! descriptors.
69//! \param ui32Size is the number of bytes of descriptor data found at pointer
70//! \e psDesc.
71//! \param ui32Type identifies the type of descriptor that is to be counted.
72//! If the value is \b USB_DESC_ANY, the function returns the total number of
73//! descriptors regardless of type.
74//!
75//! This function can be used to count the number of descriptors of a
76//! particular type within a block of descriptors.  The caller can provide a
77//! specific type value which the function matches against the second byte of
78//! each descriptor or, alternatively, can specify \b USB_DESC_ANY to have the
79//! function count all descriptors regardless of their type.
80//!
81//! \return Returns the number of descriptors found in the supplied block of
82//! data.
83//
84//*****************************************************************************
85uint32_t USBDescGetNum(tDescriptorHeader* psDesc, uint32_t ui32Size,
86                       uint32_t ui32Type) {
87    tDescriptorHeader* psDescCheck;
88    uint32_t ui32TotLength;
89    uint32_t ui32Count;
90
91    //
92    // Set up for our descriptor counting loop.
93    //
94    psDescCheck = psDesc;
95    ui32TotLength = 0;
96    ui32Count = 0;
97
98    //
99    // Keep looking through the supplied data until we reach the end.
100    //
101    while (ui32TotLength < ui32Size) {
102        //
103        // Does this descriptor match the type passed (if a specific type
104        // has been specified)?
105        //
106        if ((ui32Type == USB_DESC_ANY) ||
107            (psDescCheck->bDescriptorType == (uint8_t)(ui32Type & 0xFF))) {
108            ui32Count++;
109        }
110
111        //
112        // Move on to the next descriptor.
113        //
114        ui32TotLength += (uint32_t)psDescCheck->bLength;
115        psDescCheck = NEXT_USB_DESCRIPTOR(psDescCheck);
116    }
117
118    //
119    // Return the descriptor count to the caller.
120    //
121    return (ui32Count);
122}
123
124//*****************************************************************************
125//
126//! Determines the number of individual descriptors of a particular type within
127//! a supplied buffer.
128//!
129//! \param psDesc points to the first byte of a block of standard USB
130//! descriptors.
131//! \param ui32Size is the number of bytes of descriptor data found at pointer
132//! \e psDesc.
133//! \param ui32Type identifies the type of descriptor that is to be found.  If
134//! the value is \b USB_DESC_ANY, the function returns a pointer to the n-th
135//! descriptor regardless of type.
136//! \param ui32Index is the zero based index of the descriptor whose pointer is
137//! to be returned.  For example, passing value 1 in \e ui32Index returns the
138//! second matching descriptor.
139//!
140//! Return a pointer to the n-th descriptor of a particular type found in the
141//! block of \e ui32Size bytes starting at \e psDesc.
142//!
143//! \return Returns a pointer to the header of the required descriptor if
144//! found or NULL otherwise.
145//
146//*****************************************************************************
147tDescriptorHeader* USBDescGet(tDescriptorHeader* psDesc, uint32_t ui32Size,
148                              uint32_t ui32Type, uint32_t ui32Index) {
149    tDescriptorHeader* psDescCheck;
150    uint32_t ui32TotLength;
151    uint32_t ui32Count;
152
153    //
154    // Set up for our descriptor counting loop.
155    //
156    psDescCheck = psDesc;
157    ui32TotLength = 0;
158    ui32Count = 0;
159
160    //
161    // Keep looking through the supplied data until we reach the end.
162    //
163    while (ui32TotLength < ui32Size) {
164        //
165        // Does this descriptor match the type passed (if a specific type
166        // has been specified)?
167        //
168        if ((ui32Type == USB_DESC_ANY) ||
169            (psDescCheck->bDescriptorType == (uint8_t)(ui32Type & 0xFF))) {
170            //
171            // We found a matching descriptor.  If our count matches the
172            // supplied index, we are done so return the pointer.
173            //
174            if (ui32Count == ui32Index) {
175                return (psDescCheck);
176            }
177
178            //
179            // We have not found enough descriptors yet to satisfy the supplied
180            // index so increment our count and continue.
181            //
182            ui32Count++;
183        }
184
185        //
186        // Move on to the next descriptor.
187        //
188        ui32TotLength += (uint32_t)psDescCheck->bLength;
189        psDescCheck = NEXT_USB_DESCRIPTOR(psDescCheck);
190    }
191
192    //
193    // If we get here, we reached the end of the data without finding the
194    // required descriptor.  Return NULL.
195    //
196    return ((tDescriptorHeader*)0);
197}
198
199//*****************************************************************************
200//
201//! Determines the number of different alternate configurations for a given
202//! interface within a configuration descriptor.
203//!
204//! \param psConfig points to the first byte of a standard USB configuration
205//! descriptor.
206//! \param ui8InterfaceNumber is the interface number for which the number of
207//! alternate configurations is to be counted.
208//!
209//! This function can be used to count the number of alternate settings for a
210//! specific interface within a configuration.
211//!
212//! \return Returns the number of alternate versions of the specified interface
213//! or 0 if the interface number supplied cannot be found in the config
214//! descriptor.
215//
216//*****************************************************************************
217uint32_t USBDescGetNumAlternateInterfaces(tConfigDescriptor* psConfig,
218                                          uint8_t ui8InterfaceNumber) {
219    tDescriptorHeader* psDescCheck;
220    uint32_t ui32TotLength;
221    uint32_t ui32Count;
222
223    //
224    // Set up for our descriptor counting loop.
225    //
226    psDescCheck = (tDescriptorHeader*)psConfig;
227    ui32TotLength = 0;
228    ui32Count = 0;
229
230    //
231    // Keep looking through the supplied data until we reach the end.
232    //
233    while (ui32TotLength < (uint32_t)psConfig->wTotalLength) {
234        //
235        // Is this an interface descriptor with the required interface number?
236        //
237        if ((psDescCheck->bDescriptorType == USB_DTYPE_INTERFACE) &&
238            (((tInterfaceDescriptor*)psDescCheck)->bInterfaceNumber ==
239             ui8InterfaceNumber)) {
240            //
241            // Yes - increment our count.
242            //
243            ui32Count++;
244        }
245
246        //
247        // Move on to the next descriptor.
248        //
249        ui32TotLength += (uint32_t)psDescCheck->bLength;
250        psDescCheck = NEXT_USB_DESCRIPTOR(psDescCheck);
251    }
252
253    //
254    // Return the descriptor count to the caller.
255    //
256    return (ui32Count);
257}
258
259//*****************************************************************************
260//
261//! Returns a pointer to the n-th interface descriptor in a config descriptor
262//! with the supplied interface number.
263//!
264//! \param psConfig points to the first byte of a standard USB configuration
265//! descriptor.
266//! \param ui8InterfaceNumber is the interface number of the descriptor that is
267//! being queried.
268//! \param ui32Index is the zero based index of the descriptor to return.
269//!
270//! This function returns a pointer to the n-th interface descriptor in the
271//! supplied configuration which has the requested interface number.  It may be
272//! used by a client to retrieve the descriptors for each alternate setting
273//! of a given interface within the configuration passed.
274//!
275//! \return Returns a pointer to the n-th interface descriptor with interface
276//! number as specified or NULL of this descriptor does not exist.
277//
278//*****************************************************************************
279static tInterfaceDescriptor*
280USBDescGetAlternateInterface(tConfigDescriptor* psConfig,
281                             uint8_t ui8InterfaceNumber, uint32_t ui32Index) {
282    tDescriptorHeader* psDescCheck;
283    uint32_t ui32TotLength;
284    uint32_t ui32Count;
285
286    //
287    // Set up for our descriptor counting loop.
288    //
289    psDescCheck = (tDescriptorHeader*)psConfig;
290    ui32TotLength = 0;
291    ui32Count = 0;
292
293    //
294    // Keep looking through the supplied data until we reach the end.
295    //
296    while (ui32TotLength < (uint32_t)psConfig->wTotalLength) {
297        //
298        // Does this descriptor match the type passed (if a specific type
299        // has been specified)?
300        //
301        if ((psDescCheck->bDescriptorType == USB_DTYPE_INTERFACE) &&
302            (((tInterfaceDescriptor*)psDescCheck)->bInterfaceNumber ==
303             ui8InterfaceNumber)) {
304            //
305            // This is an interface descriptor for interface
306            // ui8InterfaceNumber.  Determine if this is the n-th one we have
307            // found and, if so, return its pointer.
308            //
309            if (ui32Count == ui32Index) {
310                //
311                // Found it - return the pointer.
312                //
313                return ((tInterfaceDescriptor*)psDescCheck);
314            }
315
316            //
317            // Increment our count of matching descriptors found and go back
318            // to look for another since we have not yet reached the n-th
319            // match.
320            //
321            ui32Count++;
322        }
323
324        //
325        // Move on to the next descriptor.
326        //
327        ui32TotLength += (uint32_t)psDescCheck->bLength;
328        psDescCheck = NEXT_USB_DESCRIPTOR(psDescCheck);
329    }
330
331    //
332    // If we drop out the end of the loop, we did not find the requested
333    // descriptor so return NULL.
334    //
335    return ((tInterfaceDescriptor*)0);
336}
337
338//*****************************************************************************
339//
340//! Returns a pointer to the n-th interface descriptor in a configuration
341//! descriptor that applies to the supplied alternate setting number.
342//!
343//! \param psConfig points to the first byte of a standard USB configuration
344//! descriptor.
345//! \param ui32Index is the zero based index of the interface that is to be
346//! found.  If \e ui32Alt is set to a value other than \b USB_DESC_ANY, this
347//! will be equivalent to the interface number being searched for.
348//! \param ui32Alt is the alternate setting number which is to be
349//! searched for.  If this value is \b USB_DESC_ANY, the alternate setting
350//! is ignored and all interface descriptors are considered in the search.
351//!
352//! Return a pointer to the n-th interface descriptor found in the supplied
353//! configuration descriptor.  If \e ui32Alt is not \b USB_DESC_ANY, only
354//! interface descriptors which are part of the supplied alternate setting are
355//! considered in the search otherwise all interface descriptors are
356//! considered.
357//!
358//! Note that, although alternate settings can be applied on an interface-by-
359//! interface basis, the number of interfaces offered is fixed for a given
360//! config descriptor.  Hence, this function will correctly find the unique
361//! interface descriptor for that interface's alternate setting number
362//! \e ui32Alt if \e ui32Index is set to the required interface number and
363//! \e ui32Alt is set to a valid alternate setting number for that interface.
364//!
365//! \return Returns a pointer to the required interface descriptor if
366//! found or NULL otherwise.
367//
368//*****************************************************************************
369tInterfaceDescriptor* USBDescGetInterface(tConfigDescriptor* psConfig,
370                                          uint32_t ui32Index,
371                                          uint32_t ui32Alt) {
372    //
373    // If we are being told to ignore the alternate configuration, this boils
374    // down to a very simple query.
375    //
376    if (ui32Alt == USB_DESC_ANY) {
377        //
378        // Return the ui32Index-th interface descriptor we find in the
379        // configuration descriptor.
380        //
381        return ((tInterfaceDescriptor*)USBDescGet(
382            (tDescriptorHeader*)psConfig, (uint32_t)psConfig->wTotalLength,
383            USB_DTYPE_INTERFACE, ui32Index));
384    } else {
385        //
386        // In this case, a specific alternate setting number is required.
387        // Given that interface numbers are zero based indices, we can
388        // pass the supplied ui32Index parameter directly as the interface
389        // number to USBDescGetAlternateInterface to retrieve the requested
390        // interface descriptor pointer.
391        //
392        return (USBDescGetAlternateInterface(psConfig, ui32Index, ui32Alt));
393    }
394}
395
396//*****************************************************************************
397//
398//! Return a pointer to the n-th endpoint descriptor in the supplied
399//! interface descriptor.
400//!
401//! \param psInterface points to the first byte of a standard USB interface
402//! descriptor.
403//! \param ui32Index is the zero based index of the endpoint that is to be
404//! found.
405//! \param ui32Size contains the maximum number of bytes that the function may
406//! search beyond \e psInterface while looking for the requested endpoint
407//! descriptor.
408//!
409//! Return a pointer to the n-th endpoint descriptor found in the supplied
410//! interface descriptor.  If the \e ui32Index parameter is invalid (greater
411//! than or equal to the bNumEndpoints field of the interface descriptor) or
412//! the endpoint cannot be found within \e ui32Size bytes of the interface
413//! descriptor pointer, the function will return NULL.
414//!
415//! Note that, although the USB 2.0 specification states that endpoint
416//! descriptors must follow the interface descriptor that they relate to, it
417//! also states that device specific descriptors should follow any standard
418//! descriptor that they relate to.  As a result, we cannot assume that each
419//! interface descriptor will be followed by nothing but an ordered list of
420//! its own endpoints and, hence, the function needs to be provided \e ui32Size
421//! to limit the search range.
422//!
423//! \return Returns a pointer to the requested endpoint descriptor if
424//! found or NULL otherwise.
425//
426//*****************************************************************************
427tEndpointDescriptor*
428USBDescGetInterfaceEndpoint(tInterfaceDescriptor* psInterface,
429                            uint32_t ui32Index, uint32_t ui32Size) {
430    //
431    // Is the index passed valid?
432    //
433    if (ui32Index >= psInterface->bNumEndpoints) {
434        //
435        // It's out of bounds so return a NULL.
436        //
437        return ((tEndpointDescriptor*)0);
438    } else {
439        //
440        // Endpoint index is valid so find the descriptor.
441        //
442        return ((tEndpointDescriptor*)USBDescGet(
443            (tDescriptorHeader*)psInterface, ui32Size, USB_DTYPE_ENDPOINT,
444            ui32Index));
445    }
446}
447
448//*****************************************************************************
449//
450// Close the Doxygen group.
451//! @}
452//
453//*****************************************************************************