+/rtos
git clone https://git.julia.blue/+/rtos
83915e3
master
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 , 72uint32_t * pui32Sec , 73tDescriptorHeader * psDesc ) { 74// 75// Determine where the next descriptor after the supplied one should be 76// assuming it is within the current section. 77// 78psDesc = NEXT_USB_DESCRIPTOR (psDesc ); 79 80// 81// Did we run off the end of the section? 82// 83if ((uint8_t * )psDesc >= (psConfig -> psSections [* pui32Sec ]-> pui8Data + 84psConfig -> 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// 93if (* pui32Sec < psConfig -> ui8NumSections ) { 94// 95// Yes - the new descriptor is at the start of the new section. 96// 97psDesc = 98 (tDescriptorHeader * )psConfig -> psSections [* pui32Sec ]-> pui8Data ; 99 }else { 100// 101// No - we ran off the end of the descriptor so return NULL. 102// 103psDesc = (tDescriptorHeader * )0 ; 104 } 105 } 106 107// 108// Return the new descriptor pointer. 109// 110return (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 , 139uint8_t ui8InterfaceNumber ,uint32_t ui32Index , 140uint32_t * pui32Section ) { 141tDescriptorHeader * psDescCheck ; 142uint32_t ui32Count ,ui32Sec ; 143 144// 145// Set up for our descriptor counting loop. 146// 147psDescCheck = (tDescriptorHeader * )psConfig -> psSections [0 ]-> pui8Data ; 148ui32Count = 0 ; 149ui32Sec = 0 ; 150 151// 152// Keep looking through the supplied data until we reach the end. 153// 154while (psDescCheck ) { 155// 156// Does this descriptor match the type passed (if a specific type 157// has been specified)? 158// 159if ((psDescCheck -> bDescriptorType == USB_DTYPE_INTERFACE )&& 160 (((tInterfaceDescriptor * )psDescCheck )-> bInterfaceNumber == 161ui8InterfaceNumber )) { 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// 167if (ui32Count == ui32Index ) { 168// 169// Found it - return the pointer and section number. 170// 171* pui32Section = ui32Sec ; 172return ((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// 180ui32Count ++ ; 181 } 182 183// 184// Move on to the next descriptor. 185// 186psDescCheck = 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// 193return ((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 ) { 211uint32_t ui32Loop ,ui32Len ; 212 213ui32Len = 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// 219for (ui32Loop = 0 ;ui32Loop < psConfig -> ui8NumSections ;ui32Loop ++ ) { 220ui32Len += psConfig -> psSections [ui32Loop ]-> ui16Size ; 221 } 222 223return (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 , 255uint32_t ui32Type ) { 256uint32_t ui32Section ,ui32NumDescs ; 257 258// 259// Initialize our counts. 260// 261ui32NumDescs = 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// 268for (ui32Section = 0 ;ui32Section < (uint32_t )psConfig -> ui8NumSections ; 269ui32Section ++ ) { 270ui32NumDescs += USBDescGetNum ( 271 (tDescriptorHeader * )psConfig -> psSections [ui32Section ]-> pui8Data , 272psConfig -> psSections [ui32Section ]-> ui16Size ,ui32Type ); 273 } 274 275return (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 , 309uint32_t ui32Type ,uint32_t ui32Index , 310uint32_t * pui32Section ) { 311uint32_t ui32Section ,ui32TotalDescs ,ui32NumDescs ; 312 313// 314// Initialize our counts. 315// 316ui32TotalDescs = 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// 323for (ui32Section = 0 ;ui32Section < (uint32_t )psConfig -> ui8NumSections ; 324ui32Section ++ ) { 325// 326// How many descriptors of the requested type exist in this section? 327// 328ui32NumDescs = USBDescGetNum ( 329 (tDescriptorHeader * )psConfig -> psSections [ui32Section ]-> pui8Data , 330psConfig -> psSections [ui32Section ]-> ui16Size ,ui32Type ); 331 332// 333// Does this section contain the descriptor whose index we are looking 334// for? 335// 336if ((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// 346return (USBDescGet ( 347 (tDescriptorHeader * )psConfig -> psSections [ui32Section ]-> pui8Data , 348psConfig -> psSections [ui32Section ]-> ui16Size ,ui32Type , 349ui32Index - 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// 357ui32TotalDescs += ui32NumDescs ; 358 } 359 360// 361// If we drop out of the loop, we can't find the requested descriptor 362// so return NULL. 363// 364return ((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 , 393uint8_t ui8InterfaceNumber ) { 394tDescriptorHeader * psDescCheck ; 395uint32_t ui32Count ,ui32Sec ; 396 397// 398// Set up for our descriptor counting loop. 399// 400psDescCheck = (tDescriptorHeader * )psConfig -> psSections [0 ]-> pui8Data ; 401ui32Sec = 0 ; 402ui32Count = 0 ; 403 404// 405// Keep looking through the supplied data until we reach the end. 406// 407while (psDescCheck ) { 408// 409// Is this an interface descriptor with the required interface number? 410// 411if ((psDescCheck -> bDescriptorType == USB_DTYPE_INTERFACE )&& 412 (((tInterfaceDescriptor * )psDescCheck )-> bInterfaceNumber == 413ui8InterfaceNumber )) { 414// 415// Yes - increment our count. 416// 417ui32Count ++ ; 418 } 419 420// 421// Move on to the next descriptor. 422// 423psDescCheck = NextConfigDescGet (psConfig ,& ui32Sec ,psDescCheck ); 424 } 425 426// 427// Return the descriptor count to the caller. 428// 429return (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 , 474uint32_t ui32Index , 475uint32_t ui32Alt , 476uint32_t * pui32Section ) { 477// 478// If we are being told to ignore the alternate configuration, this boils 479// down to a very simple query. 480// 481if (ui32Alt == USB_DESC_ANY ) { 482// 483// Return the ui32Index-th interface descriptor we find in the 484// configuration descriptor. 485// 486return ((tInterfaceDescriptor * )USBDCDConfigDescGet ( 487psConfig ,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// 496return (ConfigAlternateInterfaceGet (psConfig ,ui32Index ,ui32Alt , 497pui32Section )); 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 , 534uint32_t ui32InterfaceNumber , 535uint32_t ui32AltCfg ,uint32_t ui32Index ) { 536tInterfaceDescriptor * psInterface ; 537tDescriptorHeader * psEndpoint ; 538uint32_t ui32Section ,ui32Count ; 539 540// 541// Find the requested interface descriptor. 542// 543psInterface = USBDCDConfigGetInterface (psConfig ,ui32InterfaceNumber , 544ui32AltCfg ,& ui32Section ); 545 546// 547// Did we find the requested interface? 548// 549if (psInterface ) { 550// 551// Is the index passed valid? 552// 553if (ui32Index >=psInterface -> bNumEndpoints ) { 554// 555// It's out of bounds so return a NULL. 556// 557return ((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// 564ui32Count = 0 ; 565psEndpoint = (tDescriptorHeader * )psInterface ; 566 567while (psEndpoint ) { 568if (psEndpoint -> bDescriptorType == USB_DTYPE_ENDPOINT ) { 569// 570// We found an endpoint descriptor. Have we reached the 571// one we want? 572// 573if (ui32Count == ui32Index ) { 574// 575// Yes - return the descriptor pointer to the caller. 576// 577return ((tEndpointDescriptor * )psEndpoint ); 578 } 579 580// 581// Move on to look for the next endpoint. 582// 583ui32Count ++ ; 584 } 585 586// 587// Move to the next descriptor. 588// 589psEndpoint = 590NextConfigDescGet (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// 599return ((tEndpointDescriptor * )0 ); 600} 601 602//***************************************************************************** 603// 604// Close the Doxygen group. 605//! @} 606// 607//*****************************************************************************