+/rtos
git clone https://git.julia.blue/+/rtos
83915e3
master
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 , 86uint32_t ui32Type ) { 87tDescriptorHeader * psDescCheck ; 88uint32_t ui32TotLength ; 89uint32_t ui32Count ; 90 91// 92// Set up for our descriptor counting loop. 93// 94psDescCheck = psDesc ; 95ui32TotLength = 0 ; 96ui32Count = 0 ; 97 98// 99// Keep looking through the supplied data until we reach the end. 100// 101while (ui32TotLength < ui32Size ) { 102// 103// Does this descriptor match the type passed (if a specific type 104// has been specified)? 105// 106if ((ui32Type == USB_DESC_ANY )|| 107 (psDescCheck -> bDescriptorType == (uint8_t )(ui32Type & 0xFF ))) { 108ui32Count ++ ; 109 } 110 111// 112// Move on to the next descriptor. 113// 114ui32TotLength += (uint32_t )psDescCheck -> bLength ; 115psDescCheck = NEXT_USB_DESCRIPTOR (psDescCheck ); 116 } 117 118// 119// Return the descriptor count to the caller. 120// 121return (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 , 148uint32_t ui32Type ,uint32_t ui32Index ) { 149tDescriptorHeader * psDescCheck ; 150uint32_t ui32TotLength ; 151uint32_t ui32Count ; 152 153// 154// Set up for our descriptor counting loop. 155// 156psDescCheck = psDesc ; 157ui32TotLength = 0 ; 158ui32Count = 0 ; 159 160// 161// Keep looking through the supplied data until we reach the end. 162// 163while (ui32TotLength < ui32Size ) { 164// 165// Does this descriptor match the type passed (if a specific type 166// has been specified)? 167// 168if ((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// 174if (ui32Count == ui32Index ) { 175return (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// 182ui32Count ++ ; 183 } 184 185// 186// Move on to the next descriptor. 187// 188ui32TotLength += (uint32_t )psDescCheck -> bLength ; 189psDescCheck = 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// 196return ((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 , 218uint8_t ui8InterfaceNumber ) { 219tDescriptorHeader * psDescCheck ; 220uint32_t ui32TotLength ; 221uint32_t ui32Count ; 222 223// 224// Set up for our descriptor counting loop. 225// 226psDescCheck = (tDescriptorHeader * )psConfig ; 227ui32TotLength = 0 ; 228ui32Count = 0 ; 229 230// 231// Keep looking through the supplied data until we reach the end. 232// 233while (ui32TotLength < (uint32_t )psConfig -> wTotalLength ) { 234// 235// Is this an interface descriptor with the required interface number? 236// 237if ((psDescCheck -> bDescriptorType == USB_DTYPE_INTERFACE )&& 238 (((tInterfaceDescriptor * )psDescCheck )-> bInterfaceNumber == 239ui8InterfaceNumber )) { 240// 241// Yes - increment our count. 242// 243ui32Count ++ ; 244 } 245 246// 247// Move on to the next descriptor. 248// 249ui32TotLength += (uint32_t )psDescCheck -> bLength ; 250psDescCheck = NEXT_USB_DESCRIPTOR (psDescCheck ); 251 } 252 253// 254// Return the descriptor count to the caller. 255// 256return (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 , 281uint8_t ui8InterfaceNumber ,uint32_t ui32Index ) { 282tDescriptorHeader * psDescCheck ; 283uint32_t ui32TotLength ; 284uint32_t ui32Count ; 285 286// 287// Set up for our descriptor counting loop. 288// 289psDescCheck = (tDescriptorHeader * )psConfig ; 290ui32TotLength = 0 ; 291ui32Count = 0 ; 292 293// 294// Keep looking through the supplied data until we reach the end. 295// 296while (ui32TotLength < (uint32_t )psConfig -> wTotalLength ) { 297// 298// Does this descriptor match the type passed (if a specific type 299// has been specified)? 300// 301if ((psDescCheck -> bDescriptorType == USB_DTYPE_INTERFACE )&& 302 (((tInterfaceDescriptor * )psDescCheck )-> bInterfaceNumber == 303ui8InterfaceNumber )) { 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// 309if (ui32Count == ui32Index ) { 310// 311// Found it - return the pointer. 312// 313return ((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// 321ui32Count ++ ; 322 } 323 324// 325// Move on to the next descriptor. 326// 327ui32TotLength += (uint32_t )psDescCheck -> bLength ; 328psDescCheck = 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// 335return ((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 , 370uint32_t ui32Index , 371uint32_t ui32Alt ) { 372// 373// If we are being told to ignore the alternate configuration, this boils 374// down to a very simple query. 375// 376if (ui32Alt == USB_DESC_ANY ) { 377// 378// Return the ui32Index-th interface descriptor we find in the 379// configuration descriptor. 380// 381return ((tInterfaceDescriptor * )USBDescGet ( 382 (tDescriptorHeader * )psConfig , (uint32_t )psConfig -> wTotalLength , 383USB_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// 392return (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 , 429uint32_t ui32Index ,uint32_t ui32Size ) { 430// 431// Is the index passed valid? 432// 433if (ui32Index >=psInterface -> bNumEndpoints ) { 434// 435// It's out of bounds so return a NULL. 436// 437return ((tEndpointDescriptor * )0 ); 438 }else { 439// 440// Endpoint index is valid so find the descriptor. 441// 442return ((tEndpointDescriptor * )USBDescGet ( 443 (tDescriptorHeader * )psInterface ,ui32Size ,USB_DTYPE_ENDPOINT , 444ui32Index )); 445 } 446} 447 448//***************************************************************************** 449// 450// Close the Doxygen group. 451//! @} 452// 453//*****************************************************************************