+/rtos

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

Joseph RyanRe-add usblib files83915e3

master
23.1 KiB607 linesraw
1//*****************************************************************************
2//
3// usbcdesc.c - Config descriptor parsing functions.
4//
5// Copyright (c) 2007-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 "tivaware/usb.h"
27#include "usblib/device/usbdevice.h"
28#include "usblib/usblib.h"
29#include "usblib/usblibpriv.h"
30#include <stdbool.h>
31#include <stdint.h>
32
33//*****************************************************************************
34//
35// The functions in this file mirror the descriptor parsing APIs available
36// in usblib.h but parse configuration descriptors defined in terms of a list
37// of sections rather than as a single block of descriptor data.
38//
39//*****************************************************************************
40
41//*****************************************************************************
42//
43//! \addtogroup device_api
44//! @{
45//
46//*****************************************************************************
47
48//*****************************************************************************
49//
50//! \internal
51//!
52//! Walk to the next descriptor after the supplied one within a section-based
53//! config descriptor.
54//!
55//! \param psConfig points to the header structure for the configuration
56//! descriptor which contains \e pi16Desc.
57//! \param pui32Sec points to a variable containing the section within
58//! \e psConfig which contains \e pi16Desc.
59//! \param pi16Desc points to the descriptor that we want to step past.
60//!
61//! This function walks forward one descriptor within a configuration
62//! descriptor.  The value returned is a pointer to the header of the next
63//! descriptor after the descriptor supplied in \e pi16Desc.  If the next
64//! descriptor is in the next section, \e *pui32Sec will be incremented
65//! accordingly.
66//!
67//! \return Returns a pointer to the next descriptor in the configuration
68//! descriptor.
69//
70//*****************************************************************************
71static tDescriptorHeader* NextConfigDescGet(const tConfigHeader* psConfig,
72                                            uint32_t* pui32Sec,
73                                            tDescriptorHeader* psDesc) {
74    //
75    // Determine where the next descriptor after the supplied one should be
76    // assuming it is within the current section.
77    //
78    psDesc = NEXT_USB_DESCRIPTOR(psDesc);
79
80    //
81    // Did we run off the end of the section?
82    //
83    if ((uint8_t*)psDesc >= (psConfig->psSections[*pui32Sec]->pui8Data +
84                             psConfig->psSections[*pui32Sec]->ui16Size)) {
85        //
86        // Yes - move to the next section.
87        //
88        (*pui32Sec)++;
89
90        //
91        // Are we still within the configuration descriptor?
92        //
93        if (*pui32Sec < psConfig->ui8NumSections) {
94            //
95            // Yes - the new descriptor is at the start of the new section.
96            //
97            psDesc =
98                (tDescriptorHeader*)psConfig->psSections[*pui32Sec]->pui8Data;
99        } else {
100            //
101            // No - we ran off the end of the descriptor so return NULL.
102            //
103            psDesc = (tDescriptorHeader*)0;
104        }
105    }
106
107    //
108    // Return the new descriptor pointer.
109    //
110    return (psDesc);
111}
112
113//*****************************************************************************
114//
115//! \internal
116//!
117//! Returns a pointer to the n-th interface descriptor in a configuration
118//! descriptor with the supplied interface number.
119//!
120//! \param psConfig points to the header structure for the configuration
121//! descriptor to search.
122//! \param ui8InterfaceNumber is the interface number of the descriptor to
123//! query.
124//! \param ui32Index is the zero based index of the descriptor.
125//! \param pui32Section points to storage which is written with the index
126//! of the section containing the returned descriptor.
127//!
128//! This function returns a pointer to the n-th interface descriptor in the
129//! supplied configuration which has the requested interface number.  It may be
130//! used by a client to retrieve the descriptors for each alternate setting
131//! of a given interface within the configuration passed.
132//!
133//! \return Returns a pointer to the n-th interface descriptor with interface
134//! number as specified or NULL of this descriptor does not exist.
135//
136//*****************************************************************************
137static tInterfaceDescriptor*
138ConfigAlternateInterfaceGet(const tConfigHeader* psConfig,
139                            uint8_t ui8InterfaceNumber, uint32_t ui32Index,
140                            uint32_t* pui32Section) {
141    tDescriptorHeader* psDescCheck;
142    uint32_t ui32Count, ui32Sec;
143
144    //
145    // Set up for our descriptor counting loop.
146    //
147    psDescCheck = (tDescriptorHeader*)psConfig->psSections[0]->pui8Data;
148    ui32Count = 0;
149    ui32Sec = 0;
150
151    //
152    // Keep looking through the supplied data until we reach the end.
153    //
154    while (psDescCheck) {
155        //
156        // Does this descriptor match the type passed (if a specific type
157        // has been specified)?
158        //
159        if ((psDescCheck->bDescriptorType == USB_DTYPE_INTERFACE) &&
160            (((tInterfaceDescriptor*)psDescCheck)->bInterfaceNumber ==
161             ui8InterfaceNumber)) {
162            //
163            // This is an interface descriptor for interface
164            // ui8InterfaceNumber.  Determine if this is the n-th one we have
165            // found and, if so, return its pointer.
166            //
167            if (ui32Count == ui32Index) {
168                //
169                // Found it - return the pointer and section number.
170                //
171                *pui32Section = ui32Sec;
172                return ((tInterfaceDescriptor*)psDescCheck);
173            }
174
175            //
176            // Increment our count of matching descriptors found and go back
177            // to look for another since we have not yet reached the n-th
178            // match.
179            //
180            ui32Count++;
181        }
182
183        //
184        // Move on to the next descriptor.
185        //
186        psDescCheck = NextConfigDescGet(psConfig, &ui32Sec, psDescCheck);
187    }
188
189    //
190    // If we drop out the end of the loop, we did not find the requested
191    // descriptor so return NULL.
192    //
193    return ((tInterfaceDescriptor*)0);
194}
195
196//*****************************************************************************
197//
198//! \internal
199//!
200//! Determines the total length of a configuration descriptor defined in terms
201//! of a collection of concatenated sections.
202//!
203//! \param psConfig points to the header structure for the configuration
204//! descriptor whose size is to be determined.
205//!
206//! \return Returns the number of bytes in the configuration descriptor will
207//! result from concatenating the required sections.
208//
209//*****************************************************************************
210uint32_t USBDCDConfigDescGetSize(const tConfigHeader* psConfig) {
211    uint32_t ui32Loop, ui32Len;
212
213    ui32Len = 0;
214
215    //
216    // Determine the size of the whole descriptor by adding the sizes of
217    // each section which will be concatenated to produce it.
218    //
219    for (ui32Loop = 0; ui32Loop < psConfig->ui8NumSections; ui32Loop++) {
220        ui32Len += psConfig->psSections[ui32Loop]->ui16Size;
221    }
222
223    return (ui32Len);
224}
225
226//*****************************************************************************
227//
228//! \internal
229//!
230//! Determines the number of individual descriptors of a particular type within
231//! a supplied configuration descriptor.
232//!
233//! \param psConfig points to the header structure for the configuration
234//! descriptor that is to be searched.
235//! \param ui32Type identifies the type of descriptor that is to be counted.
236//! If the value is \b USB_DESC_ANY, the function returns the total number of
237//! descriptors regardless of type.
238//!
239//! This function can be used to count the number of descriptors of a
240//! particular type within a configuration descriptor.  The caller can provide
241//! a specific type value which the function matches against the second byte
242//! of each descriptor or, alternatively, can specify \b USB_DESC_ANY to have
243//! the function count all descriptors regardless of their type.
244//!
245//! The search performed by this function traverses through the list of
246//! sections comprising the configuration descriptor.  Note that the similar
247//! top-level function, USBDescGetNum(), searches through a single, contiguous
248//! block of data to perform the same enumeration.
249//!
250//! \return Returns the number of descriptors found in the supplied block of
251//! data.
252//
253//*****************************************************************************
254uint32_t USBDCDConfigDescGetNum(const tConfigHeader* psConfig,
255                                uint32_t ui32Type) {
256    uint32_t ui32Section, ui32NumDescs;
257
258    //
259    // Initialize our counts.
260    //
261    ui32NumDescs = 0;
262
263    //
264    // Determine the number of descriptors of the given type in each of the
265    // sections comprising the configuration descriptor.  Note that this
266    // assumes each section contains only whole descriptors!
267    //
268    for (ui32Section = 0; ui32Section < (uint32_t)psConfig->ui8NumSections;
269         ui32Section++) {
270        ui32NumDescs += USBDescGetNum(
271            (tDescriptorHeader*)psConfig->psSections[ui32Section]->pui8Data,
272            psConfig->psSections[ui32Section]->ui16Size, ui32Type);
273    }
274
275    return (ui32NumDescs);
276}
277
278//*****************************************************************************
279//
280//! \internal
281//!
282//! Finds the n-th descriptor of a particular type within the supplied
283//! configuration descriptor.
284//!
285//! \param psConfig points to the header structure for the configuration
286//! descriptor that is to be searched.
287//! \param ui32Type identifies the type of descriptor that is to be found.  If
288//! the value is \b USB_DESC_ANY, the function returns a pointer to the n-th
289//! descriptor regardless of type.
290//! \param ui32Index is the zero based index of the descriptor whose pointer is
291//! to be returned.  For example, passing value 1 in \e ui32Index returns the
292//! second matching descriptor.
293//! \param pui32Section points to storage which will receive the section index
294//! containing the requested descriptor.
295//!
296//! Return a pointer to the n-th descriptor of a particular type found in the
297//! configuration descriptor passed.
298//!
299//! The search performed by this function traverses through the list of
300//! sections comprising the configuration descriptor.  Note that the similar
301//! top-level function, USBDescGet(), searches through a single, contiguous
302//! block of data to perform the same enumeration.
303//!
304//! \return Returns a pointer to the header of the required descriptor if
305//! found or NULL otherwise.
306//
307//*****************************************************************************
308tDescriptorHeader* USBDCDConfigDescGet(const tConfigHeader* psConfig,
309                                       uint32_t ui32Type, uint32_t ui32Index,
310                                       uint32_t* pui32Section) {
311    uint32_t ui32Section, ui32TotalDescs, ui32NumDescs;
312
313    //
314    // Initialize our counts.
315    //
316    ui32TotalDescs = 0;
317
318    //
319    // Determine the number of descriptors of the given type in each of the
320    // sections comprising the configuration descriptor.  This allows us to
321    // determine which section contains the descriptor we are being asked for.
322    //
323    for (ui32Section = 0; ui32Section < (uint32_t)psConfig->ui8NumSections;
324         ui32Section++) {
325        //
326        // How many descriptors of the requested type exist in this section?
327        //
328        ui32NumDescs = USBDescGetNum(
329            (tDescriptorHeader*)psConfig->psSections[ui32Section]->pui8Data,
330            psConfig->psSections[ui32Section]->ui16Size, ui32Type);
331
332        //
333        // Does this section contain the descriptor whose index we are looking
334        // for?
335        //
336        if ((ui32TotalDescs + ui32NumDescs) > ui32Index) {
337            //
338            // We know the requested descriptor exists in the current
339            // block so write the section number to the caller's storage.
340            //
341            *pui32Section = ui32Section;
342
343            //
344            // Now find the actual descriptor requested and return its pointer.
345            //
346            return (USBDescGet(
347                (tDescriptorHeader*)psConfig->psSections[ui32Section]->pui8Data,
348                psConfig->psSections[ui32Section]->ui16Size, ui32Type,
349                ui32Index - ui32TotalDescs));
350        }
351
352        //
353        // We have not found the required descriptor yet.  Update our running
354        // count of the number of type matches found so far then move on to
355        // the next section.
356        //
357        ui32TotalDescs += ui32NumDescs;
358    }
359
360    //
361    // If we drop out of the loop, we can't find the requested descriptor
362    // so return NULL.
363    //
364    return ((tDescriptorHeader*)0);
365}
366
367//*****************************************************************************
368//
369//! \internal
370//!
371//! Determines the number of different alternate configurations for a given
372//! interface within a configuration descriptor.
373//!
374//! \param psConfig points to the header structure for the configuration
375//! descriptor that is to be searched.
376//! \param ui8InterfaceNumber is the interface number for which the number of
377//! alternate configurations is to be counted.
378//!
379//! This function can be used to count the number of alternate settings for a
380//! specific interface within a configuration.
381//!
382//! The search performed by this function traverses through the list of
383//! sections comprising the configuration descriptor.  Note that the similar
384//! top-level function, USBDescGetNumAlternateInterfaces(), searches through
385//! a single, contiguous block of data to perform the same enumeration.
386//!
387//! \return Returns the number of alternate versions of the specified interface
388//! or 0 if the interface number supplied cannot be found in the configuration
389//! descriptor.
390//
391//*****************************************************************************
392uint32_t USBDCDConfigGetNumAlternateInterfaces(const tConfigHeader* psConfig,
393                                               uint8_t ui8InterfaceNumber) {
394    tDescriptorHeader* psDescCheck;
395    uint32_t ui32Count, ui32Sec;
396
397    //
398    // Set up for our descriptor counting loop.
399    //
400    psDescCheck = (tDescriptorHeader*)psConfig->psSections[0]->pui8Data;
401    ui32Sec = 0;
402    ui32Count = 0;
403
404    //
405    // Keep looking through the supplied data until we reach the end.
406    //
407    while (psDescCheck) {
408        //
409        // Is this an interface descriptor with the required interface number?
410        //
411        if ((psDescCheck->bDescriptorType == USB_DTYPE_INTERFACE) &&
412            (((tInterfaceDescriptor*)psDescCheck)->bInterfaceNumber ==
413             ui8InterfaceNumber)) {
414            //
415            // Yes - increment our count.
416            //
417            ui32Count++;
418        }
419
420        //
421        // Move on to the next descriptor.
422        //
423        psDescCheck = NextConfigDescGet(psConfig, &ui32Sec, psDescCheck);
424    }
425
426    //
427    // Return the descriptor count to the caller.
428    //
429    return (ui32Count);
430}
431
432//*****************************************************************************
433//
434//! \internal
435//!
436//! Returns a pointer to the n-th interface descriptor in a configuration
437//! descriptor that applies to the supplied alternate setting number.
438//!
439//! \param psConfig points to the header structure for the configuration
440//! descriptor that is to be searched.
441//! \param ui32Index is the zero based index of the interface that is to be
442//! found.  If \e ui32Alt is set to a value other than \b USB_DESC_ANY, this
443//! is equivalent to the interface number being searched for.
444//! \param ui32Alt is the alternate setting number which is to be
445//! searched for.  If this value is \b USB_DESC_ANY, the alternate setting
446//! is ignored and all interface descriptors are considered in the search.
447//! \param pui32Section points to storage which will receive the index of the
448//! config descriptor section which contains the requested interface
449//! descriptor.
450//!
451//! Return a pointer to the n-th interface descriptor found in the supplied
452//! configuration descriptor.  If \e ui32Alt is not \b USB_DESC_ANY, only
453//! interface descriptors which are part of the supplied alternate setting are
454//! considered in the search otherwise all interface descriptors are
455//! considered.
456//!
457//! Note that, although alternate settings can be applied on an interface-by-
458//! interface basis, the number of interfaces offered is fixed for a given
459//! config descriptor.  Hence, this function will correctly find the unique
460//! interface descriptor for that interface's alternate setting number \e
461//! ui32Alt if \e ui32Index is set to the required interface number and
462//! \e ui32Alt is set to a valid alternate setting number for that interface.
463//!
464//! The search performed by this function traverses through the list of
465//! sections comprising the configuration descriptor.  Note that the similar
466//! top-level function, USBDescGetInterface(), searches through a single,
467//! contiguous block of data to perform the same enumeration.
468//!
469//! \return Returns a pointer to the required interface descriptor if
470//! found or NULL otherwise.
471//
472//*****************************************************************************
473tInterfaceDescriptor* USBDCDConfigGetInterface(const tConfigHeader* psConfig,
474                                               uint32_t ui32Index,
475                                               uint32_t ui32Alt,
476                                               uint32_t* pui32Section) {
477    //
478    // If we are being told to ignore the alternate configuration, this boils
479    // down to a very simple query.
480    //
481    if (ui32Alt == USB_DESC_ANY) {
482        //
483        // Return the ui32Index-th interface descriptor we find in the
484        // configuration descriptor.
485        //
486        return ((tInterfaceDescriptor*)USBDCDConfigDescGet(
487            psConfig, USB_DTYPE_INTERFACE, ui32Index, pui32Section));
488    } else {
489        //
490        // In this case, a specific alternate setting number is required.
491        // Given that interface numbers are zero based indices, we can
492        // pass the supplied ui32Index parameter directly as the interface
493        // number to USBDescGetAlternateInterface() to retrieve the requested
494        // interface descriptor pointer.
495        //
496        return (ConfigAlternateInterfaceGet(psConfig, ui32Index, ui32Alt,
497                                            pui32Section));
498    }
499}
500
501//*****************************************************************************
502//
503//! \internal
504//!
505//! Return a pointer to the n-th endpoint descriptor in a particular interface
506//! within a configuration descriptor.
507//!
508//! \param psConfig points to the header structure for the configuration
509//! descriptor that is to be searched.
510//! \param ui32InterfaceNumber is the interface number whose endpoint is to be
511//! found.
512//! \param ui32AltCfg is the alternate setting number which is to be searched
513//! for.  This must be a valid alternate setting number for the requested
514//! interface.
515//! \param ui32Index is the zero based index of the endpoint that is to be
516//! found within the appropriate alternate setting for the interface.
517//!
518//! Return a pointer to the n-th endpoint descriptor found in the supplied
519//! interface descriptor.  If the \e ui32Index parameter is invalid (greater
520//! than or equal to the bNumEndpoints field of the interface descriptor) or
521//! the endpoint descriptor cannot be found, the function will return NULL.
522//!
523//! The search performed by this function traverses through the list of
524//! sections comprising the configuration descriptor.  Note that the similar
525//! top-level function, USBDescGetInterfaceEndpoint(), searches through a
526//! single, contiguous block of data to perform the same enumeration.
527//!
528//! \return Returns a pointer to the requested endpoint descriptor if
529//! found or NULL otherwise.
530//
531//*****************************************************************************
532tEndpointDescriptor*
533USBDCDConfigGetInterfaceEndpoint(const tConfigHeader* psConfig,
534                                 uint32_t ui32InterfaceNumber,
535                                 uint32_t ui32AltCfg, uint32_t ui32Index) {
536    tInterfaceDescriptor* psInterface;
537    tDescriptorHeader* psEndpoint;
538    uint32_t ui32Section, ui32Count;
539
540    //
541    // Find the requested interface descriptor.
542    //
543    psInterface = USBDCDConfigGetInterface(psConfig, ui32InterfaceNumber,
544                                           ui32AltCfg, &ui32Section);
545
546    //
547    // Did we find the requested interface?
548    //
549    if (psInterface) {
550        //
551        // Is the index passed valid?
552        //
553        if (ui32Index >= psInterface->bNumEndpoints) {
554            //
555            // It's out of bounds so return a NULL.
556            //
557            return ((tEndpointDescriptor*)0);
558        } else {
559            //
560            // Endpoint index is valid so find the descriptor.  We start from
561            // the interface descriptor and look for following endpoint
562            // descriptors.
563            //
564            ui32Count = 0;
565            psEndpoint = (tDescriptorHeader*)psInterface;
566
567            while (psEndpoint) {
568                if (psEndpoint->bDescriptorType == USB_DTYPE_ENDPOINT) {
569                    //
570                    // We found an endpoint descriptor.  Have we reached the
571                    // one we want?
572                    //
573                    if (ui32Count == ui32Index) {
574                        //
575                        // Yes - return the descriptor pointer to the caller.
576                        //
577                        return ((tEndpointDescriptor*)psEndpoint);
578                    }
579
580                    //
581                    // Move on to look for the next endpoint.
582                    //
583                    ui32Count++;
584                }
585
586                //
587                // Move to the next descriptor.
588                //
589                psEndpoint =
590                    NextConfigDescGet(psConfig, &ui32Section, psEndpoint);
591            }
592        }
593    }
594
595    //
596    // We could not find the requested interface or we got to the end of the
597    // descriptor without finding the requested endpoint.
598    //
599    return ((tEndpointDescriptor*)0);
600}
601
602//*****************************************************************************
603//
604// Close the Doxygen group.
605//! @}
606//
607//*****************************************************************************