Home

USBRC User's Guide

1. Lu E T 41 USBRC User s Guide Engineering Report 950061 Rev J T Gl RRUPTION HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY DING EGLIGENCE OR OTHERWISE ARISING IN ANY WAY OUT OF TH I WHETHER IN CONTRACT STRICT LIABILITY OR TORT INCLU N T Generated H hursday January 19 2006 5 03 pm make sure we get the V3 structures ifndef USBRCTAB WANT V3 define _ USBRCTAB WANT V3 1 endif USBRCTAB WANT V3 include no header file name given beginning of resource data RESCHAR gk_UsbResourceData l8 120 1 050 9 9 124 4 52 18 5 2 0 0 OF Ly 9 2 32 0 1 1 0 224 25 957 4405 05 2y 14 Ry Bip Qu Lh Ly 327 I6 0 0 Ty 3 129 2 16 Po Sd Wd 09505 pod 45 525 09 5 57 3 o5 Ly cg 2 32 05 224 5 9 4 O0 Pp Sly uu poA OF Ty 5 129 beginning of descriptor table RESPTRS gk UsbResourceTable 1 RESPTRVAL gk UsbResourceData 0 end of gk UsbResourceTable 1 beginning of descriptor table RESPTRS gk UsbResourceTable 2 RESPTRVAL gk UsbResourceData 18 end of gk UsbResourceTable 2 beginning of descriptor table RESPTRS gk UsbRe
2. interface 0 USBRC User s Guide Engineering Report 950061 Rev J INTERFACE 0 is the COMM CLASS interface We have assigned a vendor specific sub class However we can still use the UNION descriptor to bind the DATA interface to this COMM interface class 2 comm class subclass 0x06 ethernet control model protocol 0x0 no protocol name COMMIFC string class descriptors follow the interface header Since USBRC doesn t know how to compile CDC descriptors we have to code them by hand private descriptors CDC header raw Ox24 interface functional descriptor 0 functional descriptor header the version of the CDC specification word 0x110 CDC union descriptor raw 0x24 interface 6 union interface number of control interface 0 interface number of data interface 1 h CDC ethernet control model functional descriptor raw 0x24 interface OxOF ethernet o mac address string index string index MACADDR dword 0 supported statistics bitmap word 1514 max seg size word 0x8040 64 imperfect d multicast filters 0 bNumberPowerFilters the communication class interface has a notification endpoint 35 USBRC User s Guide Engineering Report 950061 Rev J endpoints interrupt in 1 packet size 64 polling interval 10 ms INTERFACE 1 is the DATA CLASS interface In addition to setting 0
3. which must have no endpoints there are two alternate settings one using BULK to transfer data and another using BULK to transfer data using vendor specific wrappers dE de dE dE db db interface 1 alternate setting 0 class OxA data class subclass 0 4normal data class protocol 0 vendor specific name RESET string o o no endpoints alternate setting 1 class OxA data class subclass 0 normal data class protocol 0 vendor specific name BULKDATA string endpoints bulk out 2 packet size 64 bulk in 2 packet size 64 alternate setting 2 class OxA data class subclass 0 normal data class protocol OxFF vendor specific name WRAPPERDATA string endpoints bulk out 2 packet size 64 bulk in 2 packet size 64 h In this example we want to get the serial number and the MAC address from an external EEPROM We could have used exactly the same index but we re assuming that the SERIALNUMBER might be shorter than the MAC address to accommodate operating system limitations Anyway we ve coded them separately in this example ze strings USBRC User s Guide Engineering Report 950061 Rev J properties external SERIALNUMBER MACADDR default language English USA VENDOR_ID Moore Computer Consultants Inc PRODUCT Skimmer Ethernet Adapter SERIALNUMBER 19980906a IACADDR
4. beginning of resource data RESCHAR gk_UsbResourceData Gi Sly Oyo Ags 2555 2557 Or 3B D M dy 3225 05 Tuc Ly 27 3 d 9 2 163 0 4 1 4 96 4 0 9 4 0 0 1 0 OR 255p Oy T5255 129 395 T0 Li 9744 155 05 2 05 0 255 6 lj 5 2y5 2 l6 0 0 Te Sr 1913 2 6 05 05 9 2 y 1 25 0 0 255 di 164 54 2y 3 T6 Oy dk Wy bx 315 T6 O0 1 439 455 2072 050 2555 Ge Tg bp 7 2 0106 Oy 0 7 59 533 2 T6 Oy 07 95 By 25 hp 23 OF 07 2 555 Ei Le 55234 56 0 dg l33y Wy l6 4 0 159 2 23 05 25 05 0 2555 6 Tp By cep 165 05 05 Gb 55 2595 2 16 05 05 9 Ay 3 dy 27 0 0 255 Ty Ty Br 6 Lye 16 0 ly 7 5j 135 ly165 05 1 385 95 9 Oy 45 4 4 66 3 PT Oy IT 0 VE Oy ULIX 0y4 X01 05 32y O0 677 0 ILI 0 109 0s AND 0 Le OL 16 07 1041 05 114 0 32 0 677 05 TLL 0 110 0 115 0 117 0 108 O 116 O0 97 O 110 O 116 0 115 0 44 0 32 0 73 0 110 0 99 O 46 O0 106 3 ER 05 07 005 675 054 7354 0 174 0 32 0 842 0 114 0 117 0 101 0 84 0 97 0 115 O 107 O 174 O 32 0 85 0 83 0 66 0 32 0 68 0 97 O 116 0 97 05 325 05 9045 0p TET 0 509 0 112 0 32 0 68 0 101 0 109 0 111 0 110 0 115 0 116 O0 114 O 97 O 116 0 105 0 111 0 110 0 32 0 70 0 105 O0 114 O 109 Oy A195 0 97 05 114 0 LOL 0 1854 3 48 5 0 48 0 48 0 48 0 48 0 48 0 48 0 48 0 84 3 Tl 0 67 25 USBRC
5. Device 39 USBRC User s Guide Engineering Report 950061 Rev J USB version 1 00 Class 0 SubClass 0 Protocol 0 Control Packet Size 8 Vendor 0x040E Product ID 0x1234 Device Version 2 05 2 g P1 6 serial number omitted Sno label here s the first Configuration 1 configuration name would go here Self Powered Remot string name omitted name omitted and only 2 E P 6 configuration 9 Wak Power 10 mA P1 6 next we have th interface 0 Alternate Setting Class 1 Subclass 2 Protocol 3 9 6 name omitted 9 6 9 6 endpoints for endpoints bulk out 1 packet siz bulk in private descriptors would go here only private descriptors 1 packet siz up Bus Powered the flags o 6 interface E 0 Q P 6 9 this setting speed full speed full 16 16 512 512 more endpoints would go here Sno label Sno label for 9 6 g end of file o for config statement resource file DataPump Information for USBRC Data Pump Chip Name Uivtra Include File Name ivtrakern h Chip Header Name UDEVIVTRA HDR Chip Data Structure Name UDEVIVTRA 40 USBRC User s Guide Engineering Report 950061 Rev J Init Function Name UDEVIVTRAInit Endpoin
6. MCCI 3520 Krums Corners Road Ithaca New York 14850 USA Phone 1 607 277 1029 Fax 1 607 277 6844 www mcci com USBRC User s Guide Engineering Report 950061 Rev J Date 08 01 2006 Copyright 2006 All rights reserved PROPRIETARY NOTICE AND DISCLAIMER Unless noted otherwise this document and the information herein disclosed are proprietary to Moore Computer Consultants Incorporated 3520 Krums Corners Road Ithaca New York 14850 MCCI Any person or entity to whom this document is furnished or having possession thereof by acceptance assumes custody thereof and agrees that the document is given in confidence and will not be copied or reproduced in whole or in part nor used or revealed to any person in any manner except to meet the purposes for which it was delivered Additional rights and obligations regarding this document and its contents may be defined by a separate written agreement with MCCI and if so such separate written agreement shall be controlling The information in this document is subject to change without notice and should not be construed as a commitment by MCCI Although MCCI will make every effort to inform users of substantive errors MCCI disclaims all liability for any loss or damage resulting from the use of this manual or any software described herein including without limitation contingent special or incidental liability MCCI TrueCard TrueTask MCCI Catena and MCCI USB DataPump are re
7. detected Xh Requests that string IDs be defined and that the definitions be included in the Data Pump header file Default is not to include this information Conflicts with Xo Xn name to compile into string id file If a separate string ID file is selected this name will be compiled into the header for that file Xo string id output file Specifies that a separate string ID file is to be created If the file name is the file is written to STDOUT Xp prefix string The specified prefix will be added to each generated string ID symbol EXIT STATUS USBRC exits with status 0 if the input file was successfully translated or was translated with warnings It exits with status 1 if errors were detected If Werror is specified then USBRC will exit with status 1 if any warning messages are detected ENVIRONMENT VARIABLES USBRC examines the value of the environment variable USBRCFLAGS for additional options These options are scanned before the command line options are scanned NOTES USBRC does not remove the output files created by the o Ho or Io options if it exits with errors EXAMPLES Assume that you have a URC file named mydevice urc in the current directory and a chip definition URC file named uss820 urc also in the current directory To create a data pump header file named mydevice h you can call the resource compiler this way zo USBRC User s Guide Engineering Repor
8. dummy none by default CONFIG1_ID MCCI r CDC Ethernet Prototype Configuration RESETDATA Data Interface Reset BULKDATA Data Interface Bulk Mode IXEDDATA Data Interface Wrapper MCCI Mode strings Sno names 5 8 A Simple Device with OTG Input file ex8 urc USB resource file with device descriptor OTG config descriptor and interface descriptor with first setting but nothing else Test Options fil USB resourc 1 00 Device USB version 2 00 Class 0 SubClass 0 Protocol 0 Control Packet Size 8 Vendor 0x040E string name omitted Product ID 0x1234 Device Version 2 05 name omitted o serial number omitted Sno label for devices on the go hnp here s the first Configuration 1 and only configuration gu USBRC User s Guide Engineering Report 950061 Rev J 9 configuration name would go here Self Powered Remote Wakeup Bus Powered the flags Power 10 mA private descriptors would go here Next we have the only interface interface 0 Alternate Setting 0 Class 1 Subclass 2 Protocol 3 name stringid private descriptors endpoints for this setting endpoints Sonly one interrupt in address 0x01 packet size 1 polling interval 1 more endpoints would be here i no label on the configuration descriptor no label on the overall resource file end of
9. index assigned to the specified string value string expression string expression Concatenates two string expressions Please see section 5 7 page 34 for a sample device description that uses these constructs to add several USB Communication Device Class descriptors to a configuration descriptor 3 Using the output Please refer to the header file usbrctab h which is included in the USBRC distribution for information on how to define the macros that USBRC expects 4 Command Line Reference NAME usbrc Universal Serial Bus descriptor and string resource compiler SYNOPSIS usbrc options input file s Where options are e Input file control this group tells USBRC how to process the input files e input file encoding e Output file control this group tells USBRC where to put its output and what to call the files it produces Ho header output file Io initialization output file o table output file Xo string ID output file e Compilation Overrides this group allows you to override many of the names compiled into the files produced by USBRC All of this information is normally placed in the application section of the input files but it can be convenient to be able to specify this information on the command line as well i header to include in table Fn initialization function name Hn header reference name In init file reference name Rn name of descriptor table USB
10. 325 05 97 05 32 07 100 0 117 07 99 05 20375 05 9 45 Os Or Do d 2 9705 26 122 76 4 9 lll 0 l16 0 DLS 0 32 0j lll1 0 1024 0 32 07 108 0 1317 05 997 OF LOR 50s 72 5 129 3 16 0 5 1 9 2 163 0 4 2y 0 96 0 49 4 Op 07 1 0 0 2255 0 T7 55 12957 3335 Ly 05 13 49533 1 054 25 0 0 425525 05 Dy 2 2 76 320 04 Ww Dy L3L4 25 16 4 0 0 9 4 1 1 25 Oy 05 Boo Qo Ub 22 ER Dep Oy m GR 491 l 10 0 Ly 95 45 2707 25 0 0 255 0 7 5 4 2 0 0 s X6 0 Or Te Dy I33 2 10 Op 0 9 4 2 Il 2 1505 2555 078 Tae oy AG Tu 69 04 bp Pu pp d 335 ly 06 poda 9 Api sy 4512 0740 255 0 Y 5 09 2 106 Oy OR Ty pe dgoy Diy doy x Up oy Ap Sin du 2p Oy OY 2555705 07 Dy 65 15 1657 O Ty Py 5 9135 15 16 0 t beginning of descriptor table RESPTRS gk UsbResourceTable 1 di USBRC User s Guide Engineering Report 950061 Rev J ESPTRVAL gk UsbResource Data beginning of descriptor table RESPTRS gk_UsbResourceTable_2 RVAL gk_UsbResource RVAL gk_UsbResource Data Data the root table ROOTTABLE name devtbl cfgtbl strtbl others flangs NULL len others NULL end of generated data 5 5 Sample DataPump section 0 end of gk UsbResourceTable 1 gk UsbDescriptorRoot len devtbl gk UsbResourceTable 1 len cfgtbl gk UsbReso
11. 51 A Simple Device Input file exl urc USB resource file with device descriptor and config descriptor and interface descriptor with first setting but nothing else Test Options USB resource file 1 00 Device 2125 Commentary Since this is commented it is not analyzed by USBRC The remainder of the material in this col umn are referenced to the Standard USB Descriptor Definition listed in 9 6 of the Universal Serial Bus Specifications Revi sion 1 00 The material in this section is placed into the device descriptor USBRC User s Guide Engineering Report 950061 Rev J USB version 1 00 Specifies the version of the USB specifi cation with which this device claims com pliance Class 0 Specifies the class of the device bDe viceClass code assigned by the USB stan dard or the USB IF SubClass 0 See USB Class Code Manual for required class and subclass descriptors for values between 1 and OxFE Protocol 0 Protocol is qualified by the device class and subclass and is assigned by USB Values are available from the USB IF Packet size is hardware specific and de Control Packet Size 8 termined by the interface hardware For practical reasons this should always be set to 8 Vendor 0x040E string name omitted Vendor number is supplied by USBIF Vendor ID 0x040E is MCCI s vendor ID Please change this to your own company s ID Feel free to contact MCCI for assistance in gett
12. Descriptor statements These have the following form configuration configuration index optional configuration name string or ID bus powered self powered remote wakeup power number ma optional private descriptor s interface interface number interface clause s see below interface interface number interface clause s see below optional label USBRC translates this statement into a configuration descriptor followed by the interface de scriptors and endpoint descriptors that go with this descriptor 11 USBRC User s Guide Engineering Report 950061 Rev J The fields must appear in the order shown above Any or all of the flags bus powered self powered remote wakeup may appear in any order before the power keyword The power of the device is specified by the power keyword The power is specified in milli amperes If the device is not bus powered the field should be zero The keyword ma is op tional and is simply commentary Any private descriptors specified are inserted in the resulting configuration descriptor between the basic configuration descriptor and the first interface descriptor 2 3 8 The Interface Statement Normally a configuration has at least one interface Each interface is represented by an interface statement interface interface number alternate setting alternate setting code class interface class
13. No table of figures entries found iv USBRC User s Guide Engineering Report 950061 Rev J 1 Introduction This document describes and specifies version V2 23n of the USB Resource Compiler USBRC developed by MCCI USBRC simplifies the development of USB peripherals by generating data for USB descriptors USBRC reads a text file containing a high level description of a particular USB device and produces another file containing several tables of data suitable for feeding to an ANSI C compiler At runtime the device firmware passes the data to the host in response to GET DESCRIPTOR commands transmitting the data directly from ROM When used with the MCCI USB DataPump USBRC also simplifies peripheral design by automatically generating the header files and initialization code needed by the DataPump code 11 Q amp A Why is a resource compiler needed USB devices must return predefined data structures in response to GET DESCRIPTOR commands from the host These descriptors are simply put unwieldy to develop and maintain e Some operating systems are extremely sensitive to errors in the USB resource data files and will crash while attempting to recognize a device that returns erroneous data e The string and configuration descriptors are variable length as is the endpoint de scriptor in pending revisions of the specification Standard C has no convenient way to place the needed data in ROM USBRC automatically determines the
14. User s Guide Engineering Report 950061 Rev J 67 97 32 107 117 71 112 110 116 73 101 97 98 101 115 117 76 32 0 0 99 0 152 79 129 126 0 73 116 76 32 114 617 0 98 0 116 0 101 0 10 0 58 3 116 0 97 0 114 ITI 115 111 73 0 0 0 32 9 TII 0 67 0 97 67 0 OF Quy 114 114 116 66 97 O 99 0 0 102 0 99 057 5327 0 IIl 0 110 DOl 07 I8 2 LLL 85 108 81 248 83 152 238 149 108 0 0 0 85 325 TS 0 VIT 0 116 Tay 705 99 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 101 T1 32 107 0 0 0 0 91 104 68 112 0 116 Xu Xo Oy SO Oy OO i GF eG O QA CCP COCOS NCO beginning of descriptor table RESPTRS gk_UsbResourceTable_1 RESPTRVAL gk UsbResource Data beginning of descriptor tabl RESPTRS gk UsbResourceTable 2 RESPTRVAL gk UsbResource e Data 0 0 111 114 0 0 83 0 80 0 T3 110 0 105 327 0 107 0 0 0 0 66 0 117 0 98 0 102 0r 111 Loy 05 0 32 108 0 117 0 32 0 0 0 0 111 Ora o7 47 0 112 0 0 109 0 9ihy Qi 1
15. number subclass interface subclass number protocol interface protocol number name interface name string or ID optional private descriptors endpoints endpoint statement s see below r and optionally alternate setting alternate setting code class interface class number and so forth USBRC translates each interface statement into one or more interface descriptors with asso ciated endpoints One interface descriptor is produced for each alternate setting for the inter face If the alternate setting code is zero the alternate setting alternate setting code phrase can be omitted Because some interface settings might not have any valid endpoints associated with them the endpoints statement is optional 2 3 4 The Endpoints Statement The endpoints of an interface alternate setting are represented by the endpoints statement endpoints endpoint specification s Each endpoint specification has the following form 12 USBRC User s Guide Engineering Report 950061 Rev J control isochronous bulk interrupt in out endpoint address number packet size maximum size in bytes polling interval polling interval in milliseconds data raw data sequence optional private descriptors Not all of the combinations of the above options make sense Interrupt endpoints must al ways be in The direction of contro
16. tire 2 24 Whe DataP ump SCHON sessions tecto diet tetto Cen Dio EE REE E o ee Detur us 2 29 Ihe Applicaton Dectlofistssdssostatr ire upto ed debe m RR QR EL Mee ad dtr odo dd 4 25 Sing Expressions IN DSBRE 3a aee nieenn tanta mde AR AU 6 3 Using tle Oltpt aoo os Gn rA Gaeta r e EE Y ciate alten cases tdv C V dede bn itin t 7 4 Command Line Reference Josie RI dnb dai Mab Mea 7 5 Example resource description files norit rire tar is aiia i 12 5 A Simple Device ienna eea na e a e e Qr eae uer bend len p ca babes Dengue eite 12 52 A Device with Multiple Interfaces concetto harte pibe eto ese ee trip erede pea 16 iii USBRC User s Guide Engineering Report 950061 Rev J 53 A Multiple Interface Device With Strings For Several Languages 21 5 4 Multiple Configurations and Private Data us tege etra stetec eu teter ds Re n Pedes 28 5 5 Sample DaraPump secobo oues thia det a PM et oA d EO E ud V tuae 32 5 6 Sample Application Seclobseoitte p pes aibi DU Fc pecie aepo te Ful aco IR ETE elude 33 5 7 Sample CDC USB Ethernet Adapter ics assis Sie nian endicut e Sleiman Scoala 34 5 8 A Simple Device with OTR stunner Maes Go pta ay un aren lau 37 5 9 A Simple Device with High speed Expressions 5515 oui rel ereetet tia Evae oio 39 LIST OF TABLES Table 1 String Values in A pplication Seeliofts us eese orpetetera ten thee tri te eio Nope d tese ab Vei Or 5 LIST OF FIGURES Error
17. with the digits 1 through 9 are interpreted as decimal numbers e Numbers beginning with the strings 0x or are interpreted as hexadecimal numbers e Numbers beginning with 0 are interpreted as octal numbers Numbers can have any value from 0 to 232 1 in hex 0 to OXFFFFFFFF Here are some exam ples 1 12 binary 1100 l 12 in hexadecimal 1 12 in another hexadecimal style 1 12 in octal 2 1 5 Strings Strings are written by enclosing characters inside double quotes In USBRC strings are used for two purposes to specify string descriptor values and to select languages for multi lingual peripherals Internally USBRC represents all strings in UNICODE If the input file is encoded in UNICODE or UTF 8 any UNICODE character can be embedded in a string without special handling ex cept for X close quote and newline Within strings the USBRC recognizes the normal C escape sequences a f n r t 000 377 x00 XFF Vend of line USBRC User s Guide Engineering Report 950061 Rev J represents a bell character represents form feed represents newline line feed represents carriage return represents a tab represent a single character encoded in octal For compatibility with C USBRC limits the representation to three octal digits represent a single character encoded in hexadecimal For compatibility with C USBRC limits the representation to two hex d
18. word 7 This string will be stored as Unicode Another example private descriptors generate a raw descriptor entry of type OxDB length 7 containing data 0x06 OxDB OxAO 0x86 01 00 and the string index for the tag SERIALNUMBER 100000 is 0x186A0 hence the sequence OxA0 0x86 1 O raw OxDB dword 100000 string index SERIALNUMBER Private descriptors are most frequently used for inserting additional newly standardized or proposed standard descriptors that the USBRC compiler doesn t yet directly support 2 3 7 The Data Statement Data allows you to use USBRC to generate arbitrary data in a portable way using any of the types supported by USBRC The syntax is data label byte or string data 2 3 8 The On The Go Statement Each device must have one On The Go descriptor of the following form on the go srp hnp Each of the parts of an On The Go statement must occur as given above The parts enclosed in square brackets and are optional 24 The DataPump Section The DataPump section is optional It supplies information that is used for building the initialization functions and data structures required by the MCCI USB DataPump If you need to create the c file or header file for use with the DataPump you must add this section to the input URC file or add the name of the file containing this information to the USBRC command line Because USBRC w
19. 05 110 0 68 112 99 0 103 0 84 111 0 111 73 0 110 116 0 32 114 0 102 0 97 0 99 108 0 107 0 32 0 68 T6 0 IIT 0 IIl 05 112 32 0 73 0 110 0 116 0 997 05 TOT y 25 33 0 l14 0 lll 0 IT0 0 Ill 0 97 0 16 0 97 Q 32 0 98 0 97 0 997 0 LOT Os 101 Oy LTA OF 102 05 97 131 l5 108 251 150 102 129 103 18 Sy ITl l31 15 108 53 121 Li 81 248 83 0 0 0 end of gk UsbResourceTable 1 18 end of gk UsbResourceTable 2 181 This is the string table for English 189 also the default language for this de 255 vice Note that all the entries are the 361 same as the other string tables except 379 for entry 1 which points to the Eng 463 lish name for MCCI 547 605 beginning of descriptor table RESPTRS gk_UsbResourceTable_3 RESPTRVAL gk_UsbResourceData RESPTRVAL gk_UsbResourceData RESPTRVAL gk_UsbResourceData RESPTRVAL gk_UsbResourceData RESPTRVAL gk_UsbResourceData RESPTRVAL gk_UsbResourceData RESPTRVAL gk_UsbResourceData RESPTRVAL gk_UsbResourceData end of gk UsbResourceTable 3 beginning of descriptor table 26 RESPTRS gk U USBRC User s Guide Engineering Report 950061 Rev J sbResourceTable_4 DDWDDWDDD Do EM ESPTRVAL gk UsbResourceData 181 ESPTRVAL gk U
20. 12 0 110 0 11554507 0 66 2 0 16 0 0 0 0 TX TS 44 19 USBRC User s Guide Engineering Report 950061 Rev J beginning of descriptor table RESPTRS gk UsbResourceTable 1 RESPTRVAL gk UsbResourceData 0 end of gk UsbResourceTable 1 beginning of descriptor table RESPTRS gk UsbResourceTable 2 RESPTRVAL gk UsbResourceData 18 end of gk UsbResourceTable 2 20 07 32 05 68 OF TO 707 109 07 111 707 32 O 114 O 109 O 119 O 97 O 114 O 101 0 101 0 102 0 97 0 117 0 108 O 116 0 111 0 110 0 102 0 105 0 103 0 Oy 116 0 LOS 0 D1 y Op 1107 07 38 3 343 07 LOL 0 112 0 dq125 0 1X7 0 X12 0 0 110 0 100 0 1125 0 111 0 105 0 3 66 0 117 0 108 0 107 O 32 O0 68 0 97 0 18 3 73 0 83 0 79 O 32 0 0 116 0 97 O 0 105 44 3 68 32 0 99 114 05 97 110 0 116 32 0 101 116 0 20 0 116 97 Table of pointers to device descriptors Table of pointers to configuration descriptors USBRC User s Guide Engineering Report 950061 Rev J beginning of descriptor table J RESPTRS gk UsbResourceTable 3 ESPTRVAL gk UsbResourceData 181 ESPTRVAL gk UsbResourceData 185 ESPTRVAL gk UsbResourceData 249 RVAL gk UsbResourceData 285 ESPTRVAL gk UsbResourceData 3
21. 16 bit codeword and another million characters using two Unicode codewords All the character values are selected from the 31 bit space defined by the ISO in their standard ISO 10646 For most Unicode characters those in which one codeword represents one character the Unicode encoding is the same as the ISO 10646 code UTF 8 is an ISO 10646 standardized method of represent ing ISO 10646 character values using an 8 bit codeword Each character value maps into one or more codewords UTF 8 is particularly convenient for use in most current com puting environments because the first 128 codes are identical to ASCII Only the codes between 0x80 and OxFF differ from their normal interpretations they are used only to make 2 to 6 byte sequences that represent a single ISO 10646 character UTF 8 is very easy to transport has no byte ordering issues and is easy to enter if tedious if the de sired Unicode characters are known It also mixes very nicely into plain text such as the input files read by USBRC I can prepare files in Unicode using Notepad on Windows XP 2000 or NT How do I get the data into USBRC USBRC can read Windows XP 2000 NT 4 0 Notepad Unicode files directly in any of the common formats It will automatically detect these files A heuristic is used to detect these files which may cause problems so you can force USBRC to assume a particular file encoding SEE COMMAND LINE SYNTAX AT SECTION 4 PAGE 7 USBRC User s Guide Engin
22. 29 ESPTRVAL gk UsbResourceData 367 ESPTRVAL gk UsbResourceData 387 end of gk UsbResourceTable 3 oU UU UU ou uo uw uw amp n d beginning of language ID data LANGIDPTRS gk UsbLangidTable 4 LANGPTRVAL 0x0409 7 gk UsbResourceTable 3 LANGPTRVAL 0x0000 7 gk UsbResourceTable 3 end of gk UsbLangidTable 4 the root table ROOTTABLE name gk UsbDescriptorRoot V devtbl len devtbl gk UsbResourceTable 1 1 cfgtbl len cfgtbl gk UsbResourceTable 2 1 strtbl langs gk UsbLangidTable 4 2 others len others NULL 0 i end of generated data Table of pointers to string descriptors for the default language Table of language mapping tables This table has two entries one for language ID 0x0409 English supplied by default and another for language ID 0 the default language The two languages share the same table which has 7 entries 53 A Multiple Interface Device With Strings For Several Languages ex3 urc valid USB resource file with device descriptor config descriptor and interface descriptors set up to duplicate the slinky spec This is the USB resource file 1 00 Device USB version 1 00 Class OxFF vendor specific SubClass OxFF serial device 21 same as ex2 urc but with strings for several languages it also illustrat
23. Data Loopback Interface String 4 ISODATA Isochronous Data Loopback Interface We provide string tables for translating traditional and simplified Chinese We omit language Chinese because typically you have to choose Simplified or traditional Chinese depending on installed fonts language Chinese traditional MCCI x 83AB x 6c0Of x 96fb x 8166 x 9867 x 554F x 516c x 53f 8 52 CAA zx 8 For convenience we have written the string in two fragments enclosed in pa rentheses USBRC automatically concate nates the strings PRODUCT default SERIALNUMBER default CONFIG1_ID default Config 0 Ifc 0 default BULKDATA Bulk Data Loopback Interface ISODATA Isochronous Data Loopback Interface The same thing for simplified Chinese Note that the middle four characters are different even though 24 USBRC User s Guide Engineering Report 950061 Rev J they are pronounced the same language Chinese simplified a SR RT A 9 x 83AB x 6c0Of x 7535 x 8111 x 987E x 95ee x 516c x 53f8 RODUCT default ERIALNUMBER default CONFIG1_ID default Config 0 Ifc 0 default BULKDATA Bulk Data Loopback Interface AS T a ISODATA Isochronous Data Loopback Interface send of strings no label send of resource data no label end of file Output file include usbrctab h
24. Dutch Dutch Belgium Dutch Netherlands English English Australia English Belize English Canada English Caribbean English Eire English Ireland English Jamaica English New Zealand English Philippines English South Africa English Trinidad English UK English United Kingdom English United States English USA English Zimbabwe Estonian Faeroese Ears Finnish French French Belgium French Canada French France French Luxembourg French standard French Switzerland German German Austria German Germany German Liechtenstein German Luxembourg German standard German Switzerland Greek Gujarati Hebrew HID Usage Data Descriptor HID Vendor Defined 1 HID Vendor Defined 2 HID Vendor Defined 3 HID Vendor Defined 4 Meee Hungarian Icelandic Indonesian Italian Italian Italy Italian standard Italian Switzerland Japanese Kannada Kashmiri India Konkani Korean Korean Extended Wansung Korean Johab Latvian Lithuanian Lithuanian classic Macedonian Malay Brunei Darussalam Malay Malaysian Malayalam Manipuri Marathi Nepali India Norwegian Bokmal Norwegian Nynorsk Oriya Polish Portuguese Portuguese Brazil Portuguese Portugal Portugese standard Romani
25. RC User s Guide Engineering Report 950061 Rev J Rs Sn name of top level structure Xn string ID file reference name Xp prefix for string ids e Miscellaneous chipinfo filename dpapi bitmask type output type DESCRIPTION USBRC is a utility that allows USB developers to create and manipulate USB device descriptors in a high level format USBRC reads a device description from the input files conventionally of the type urc and produces equivalent tables as an ANSI C module When used with the MCCI USB DataPump USBRC can optionally generate a header file that describes the device to the DataPump an initialization function that will set up the data structure at run time and a header file containing string index information Therefore USBRC can produce up to four files in a single compilation 1 The descriptor tables the table file This file is written to STDOUT or to the file specified by the o option It is always produced 2 A header file describing the logical structure of the device the data pump header file This file is written to the file specified by the Ho option and is only written if Ho is specified 3 AC file containing a function that will initialize the data structures appropriately the data pump initialization file This file is written to the file specified by the Io option and is only written if Io is specified 4 A header file containing symbols equated to th
26. adtalsseetaiatcaietsanecoe 4 21 The Basics D er yuna na E EEE E a peas ATE E Ei R EET ER 4 Z1 Tdentifeis eoo rent a aa aa E aA 4 PANNE KeyWords OE TM E eei E TE 4 2 1 2 1 Special Keywords in the DataPump Section 5 2 1 2 2 Special Keywords in the Application Section B 2 1 2 3 Special Keywords in the On The Go Section 5 2 1 9 COMMA SENS Lie peer Do Pret REP ereet ped iere iO E eH ER MEE IPIE 5 2 4 Nets weten aein eena repete te chosen era tet aen etit t ENESE ferite tei aeo EP OE 6 2l ZOEIS s deat eto adeb mre int ecu 6 21 0 EXDEGSSIOR S Disi ciet ob GU Saber E teas ike ola e I dated COGN don 8 2 1 6 1 Operators 9 22 ENS ptt Language cunas ena date abere mv al n il t abies 10 2 3 Th USB resource file SeCHODS uu pepe Pea SERRE nies ID e ERROR LUCR RE rH Eae 10 2 3 1 Be DSB deviee Statement annas bon eb pad d oA EEEE 10 2 3 2 The Configuration State melts ca once m Sei c tp emu en decd 11 29 9 The Interface Statement uota Creed tese tees aedem em am Dee gets 12 2 5 4 Ihe Endpoints Statement sais seipi eien ian cd rei ie a ed epe bcn sets 12 2 090 Lhe Stings Statement oues n e MR RE OLDER nana EU UNOMA ADR EN SUR 13 2 3 6 The Private Descriptor Statement aea adi te RI oe irpo ecc nre RE eR cYp 1 237 The Data Statene tiss eres eii te toe ed ea traen e iter eb EEA EAEEREN Ee 2 2 9 8 The On The Go Statement siscisisnisissssesotsatssstasinocsosnccnessneeaseanass E OH tor Ebo iare
27. ame that is used by the DataPump chip driver Chip Header Name gives the name to be used as the chip header Data Structure For example we could have UDEV620_HDR UDEV820 HDR etc The name chosen must match the name used by the DataPump chip driver Chip Data Structure Name gives the name of the chip level Data Structure It must match the name that is used for this purpose by the DataPump chip driver For example we can have UDEV620 UDEV820 etc It is optional and the default name is UDEV Chip Name For example suppose the chip name is xyz then the default name would be UDEVxyz Endpoint Data Structure Name gives the name of the chip specific endpoint data structure It must match the name that is used for this purpose by the DataPump chip driver For example we can have UEP620 UEP820 etc This field is optional and the default name is UEP Chip Name For example suppose the chip name is xyz then the default name would be UEPxyz Init Function Name gives the name of the function that initializes the chip level data structure It is optional and the default name is UsbPumpInit im USBRC User s Guide Engineering Report 950061 Rev J Config Data Structure Name gives the name of the config data structure It is optional and the default name is UCONFIG You should not change the value as it must match the name used by the DataPump common code Interface Data Struct
28. ample shows that and are very important when entering UNICODE characters in hex a string consisting of 4 characters 8 bytes 0041 0042 0043 and 0044 The serves to escape the newlin 2 1 6 Expression Expression can be used in the place where numbers and strings are allowed in the input resource file Expressions must be formed using constants i e numbers and strings Keywords speed low full and high are the only identifiers allowed in relational expression to differentiate high and full speed Here are some examples of expression An expression involving additive operator with numbers YAB CD An expression for string concatenation with strings Result is equivalent to ABCD AB 1 An expression for string concatenation with a string and a number Result is equivalent to ABI speed high An expression involving relational operator with keywords as operand 2 1 6 1 Operators USBRC User s Guide Engineering Report 950061 Rev J The following is the list of operators supported by USBRC Operator lt lt gt gt Operator Syntax lt expression gt lt expression gt lt expression gt lt expression gt lt expression gt lt expression gt lt expression gt lt expression gt lt expression gt lt expression gt lt expression gt lt expression gt expression lt expressi
29. an Russian Serbian Cyrillic Serbian Latin Sindhi Slovak Slovenian Spanish Spanish Argentina Spanish Bolivia Spanish Castilian Spanish Chile Spanish Colombia Spanish Costa Rica Spanish Dominican Republic Spanish Ecuador Spanish El Salvador Spanish Guatemala Spanish Honduras Spanish Mexican Spanish Modern Spanish modern sort Spanish Nicaragua Spanish Panama 15 USBRC User s Guide Engineering Report 950061 Rev J Spanish Paraguay Spanish Peru Spanish Puerto Rico Spanish traditional sort Spanish Uruguay Spanish Venezuela Sutu Swahili Kenya Swedish Swedish Finland Swedish Sweden Tamil Tatar Tatarstan Telugu Thai Turkish Ukrainian Urdu Pakistan Urdu India Uzbek Cyrillic Uzbek Latin Vietnamese USBRC User s Guide Engineering Report 950061 Rev J Each string or ID is one of the strings or identifiers previously mentioned in a USB Device configuration or interface statement Each string in these languages gives the translation as a UNICODE string To specify that the translation should be the same as the default language you can use the keyword default and the syntax string or ID default USBRC will notice if a given string is used more than once and will only generate one copy of that string descriptor The string desc
30. ass 0 none protocol OxFF vendor specific endpoints isochronous out 2 packet size 16 polling interval 1 isochronous in 3 packet size 16 polling interval 1 Send interface interface 2 is used for sending data interface 2 alternate setting 0 class 0 none subclass 0x0 none protocol OxFF vendor specific endpoints bulk out 4 packet size 16 bulk in 5 packet size 16 i alternate setting 1 class 0 none subclass 0 none protocol OxFF vendor specific endpoints isochronous out 4 packet size 16 polling interval 1 isochronous in 5 packet size 16 polling interval 1 o interface 3 is used for sending data interface 3 alternate setting 0 class 0 none subclass 0x0 none zs USBRC User s Guide Engineering Report 950061 Rev J protocol OxFF vendor specific endpoints bulk out 6 packet size 16 bulk in 7 packet size 16 i alternate setting 1 class 0 none subclass 0 none protocol OxFF vendor specific endpoints isochronous out 6 packet size 16 polling interval 1 isochronous in 7 packet size 16 polling interval 1 i end interface Send config 2 no label Send device no labels o o end of file Output file commentary omitted for brevity finclude usbrctab h beginning of resource data RESCHAR gk UsbResourceData Tgp La OR Ay 05 07 20 8545 G1454 4 52 18 37 3275 Oye 04 Of 27 394 2 1S 7 Oy Ty 0 05 2247 35 24 85 3 05 325 OOF 205 109 07
31. defines a separate option If omitted the generated code is compatible with DataPump API versions through V1 78 The defined bits are dpapi 1 USBRC generates extra code required starting with V1 79a which places pointers to the relevant descriptors in the initialized UDEVICE UCONFIG UINTERFACE and UENDPOINT structures Input file text encoding method The possible selections are e auto e ascii e utf8 e unicode e unicode big e ucs4 little e ucs4 big USBRC automatically detects the encoding scheme This is the default The input file is in ASCII no multi byte characters are embed ded in the file The input file is encoded in UTF 8 This encoding is the same as ascii for normal text If the file begins with the character sequence OxEF OxBB OxBF USBRC automatically detects that the input file is UTF 8 text Otherwise USBRC will default to reading ASCII If you have UTF 8 text that does not begin with the signature you will need to use this switch to force USBRC to decode the input as being UTF 8 The input file is in UNICODE in Windows NT x86 byte order Normally you don t need to specify this because USBRC will automatically detect this kind of file The input file is in UNICODE with the most significant byte first Again normally this encoding is automatically detected The input file is in ISO 10646 4 byte characters with the least significant byte of each character first Th
32. der file Without is the default The creation of a separate string ID file is not affected by this option String ID definitions can be sent to either place or to both places Please see section 5 6 page 33 for an example of a completed application section 26 String Expressions in USBRC USBRC can parse a limited set of expression operators when building string and private descriptor values The following are recognized String Generates a UNICODE string with each char acter stored in low high order Number Generates a single byte of data Word number Generates two bytes of data the number stored in low high order three byte number Generates three bytes of data representing the number stored in low high order dword number Generates four bytes of data the number stored in low high order language language name string Generates two bytes of data the language code corresponding to the given language name string value string value Concatenates each of the specified values to gether to form a single string value string index ID Generates a single byte containing the string index assigned to the specified identifier string index literal string value Generates a single byte containing the string E c USBRC User s Guide Engineering Report 950061 Rev J index assigned to the specified string value string index string expression Generates a single byte containing the string
33. dpoints setting data structure name Speeds Otherwise these keywords have no special meaning 2 1 22 Special Keywords in the Application Section In the application section section 2 5 the following additional keywords are defined descriptor file filter function functions get descriptor global header file ids initialization internal names prefix root set descriptor static string structure table type with without Otherwise these keywords have no special meaning 2 1 23 Special Keywords in the On The Go Section In the On The Go section section 2 5 the following additional keywords are defined hnp srp Otherwise these keywords have no special meaning 2 1 3 Comments Comments may be written in two ways USBRC treats comments the same as spaces USBRC User s Guide Engineering Report 950061 Rev J 1 Text included between percent signs is treated as commentary The text may include any number of lines Examples this is commentary this is a multi line comment This is a comment Note that signs are ignored within this kind of comment 9 Similarly is ignored inside percent signs 2 1 4 Numbers Numbers are used to specify many different things including vendor IDs product IDs con figuration numbers endpoint addresses power consumption and so on USBRC recognizes numbers in several forms e Numbers beginning
34. e liseconds i no label on the configuration descriptor no label on the overall resource file end of file Output file generated with dpapi 0 commentary omitted for brevity include usbrctab h beginning of resource data RESCHAR gk UsbResourceData Device descriptor data Configuration 1 descriptor data Interface 0 descriptor data Endpoint descriptor data beginning of descriptor table B RESPTRS gk UsbResourceTable 1 Table of pointers to device m descriptors RESPTRVAL gk_UsbResourceData 0 end of gk UsbResourceTable 1 15 USBRC User s Guide Engineering Report 950061 Rev J Table of pointers to configuration descriptors beginning of descriptor table RESPTRS gk_UsbResourceTable_2 RESPTRVAL gk UsbResourceData 18 end of gk UsbResourceTable 2 Table of pointers to tables of descriptors Generated via a layo t the root table ROOTTABLE name gk UsbDescriptorRoot V devtbl len devtbl gk UsbResourceTable 1 1 cfgtbl len cfgtbl gk UsbResourceTable 2 1 strtbl langs NULL O others len others NULL 0 i end of generated data 52 A Device with Multiple Interfaces This example shows how to prepare the descriptors for a device with multiple interfaces Input file ex2 urc USB resource file with de
35. e indices of string descriptors that were declared as being externally stored This simplifies the coding of the functions that provide these descriptors This file is only written if Xo is specified USBRC operates by parsing each of the input files in turn treating them as a single logical input file After the input has been parsed it produces the requested output files The data pump header file and the data pump initialization file refer to files and functions by name For example the data pump initialization file includes the data pump header file For convenience you specify the reference names that are compiled into the code separately from the names that are used for the output files The options Ho and Io specify only the names of the output files Reference names can be obtained from the application statement or from the command line USBRC User s Guide Engineering Report 950061 Rev J The following options are available chipinfo filename dpapi bitmask e encoding Specifies the name and location of the chip information file The file named by this switch is read after all the other input files have been read Specifying the chip information file as part of the USBRC options can make it easier to build Makefiles Specifies MCCI USB DataPump API options to be used when compiling the resource file The bitmask is specified as a number in decimal octal or hexadecimal as in C Within the mask each bit
36. e input file is in ISO 10646 4 byte characters with the most significant byte first USBRC User s Guide Engineering Report 950061 Rev J Fn function Specifies the name of the initialization function that is to be generated The Hn file h Ho file h i header In file c Io file c o table file default is UsbPumpInit however this is usually overridden by the DataPump section or the application section of the input file This is used to create both the initialization c file and the data pump header file Specifies the reference name of the data pump header file that is compiled into the output files Requests that a data pump header file be generated and specifies the name of the file If the file name is specified as USBRC will write its output to STDOUT Controls the name of the header file that is included by the table file If i is not specified then the value given for Hn is used if neither i nor Hn is given USBRC will use include usbrctab h You may want to use a different file in the table file for some applications Using i you can override the default in one of two ways i file h USBRC will insert include file h at the appropriate place in the table file i USBRC will not insert any include command in the table file This may be appropriate if you want to generate the table file as a h file rather than a c file Specifies the reference name of the data pum
37. eTable 4 Traditional Chinese 0x0404 pointer LANGPTRVAL 0x0804 8 gk UsbResourceTable 5 Simplified Chinese 0x0804 pointer end of gk UsbLangidTable 6 the root table ROOTTABLI E N name devtbl cfgtbl strtbl others gk UsbDescriptorRoot V len devtbl gk UsbResourceTable 1 1 len cfgtbl gk UsbResourceTable 2 1 flangs gk UsbLangidTable 6 4 len others NULL 0 Pointer to language table indicates that four distinct language IDs are supported including language code 0 which is used for reading the list of known languages 27 USBRC User s Guide Engineering Report 950061 Rev J 5 4 Multiple Configurations and Private Data Finally we present a grab bag example that shows a number of different extra features of USBRC Input file ex4 urc USB resource file with two configs one little from example 1 and one large from example 2 Also has some private descriptors USB resource file 1 00 Device USB version 1 00 Class 0 SubClass 0 Protocol 0 Control Packet Size 8 9 o Vendor 0x40E could have a name here 9 Product ID 0x1234 could have a name here Device Version 2 05 could have a serial number here Sno label here s the first configuration Ideally we ought to support autonum Configuration 1 string id would go here Self Powered Remote Wakeup Bus P
38. eering Report 950061 Rev J What platforms does USBRC run on MCCI has versions of USBRC for Windows supporting Window 95 98 98SE ME NT 4 0 Windows 2000 and Windows XP for X86 platforms NetBSD 386 SunOS 4 1 3 and Solaris 2 5 and later Other platforms are available by special order How do I use USBRC USBRC is invoked as a command line utility You must prepare the input file using a text editor and then USBRC to convert the file to C USBRC is designed for integration into a MAKEFILE or BUILD based programming environment 2 TheLayout of USBRC files 2 1 The Basics USBRC parses the input files according to some simple rules The input file is first broken up into tokens which are words strings and punctuation marks USBRC ignores spaces and newlines except that spaces and newlines always mark the end of a word Each of the following punctuation marks is significant to USBRC The meaning depends on the context Co Gb ey POS Each of the following characters begins a longer special token as defined below Ego 21 1 Identifiers Identifiers are sequences of letters digits underscores minus signs and other punctuation marks that are not recognizable as numbers In USBRC input files you use identifiers to specify names to be used in the C output code and also if you choose to specify strings 2 12 Keywords Certain identifiers are reserved by USBRC for use as keywords alternate setting appl
39. es the use of string tags for localization USBRC User s Guide Engineering Report 950061 Rev J Protocol 0x0 none specified Control Packet Size 8 Vendor 0x40E tag MCCI MCCI Defined in Strings Section 1 Product ID OxE101 tag PRODUCT Product ID Defined in Strings Device Version 1 00 Section 2 serial number SERIALNUMBER Serial Number Defined in Strings Section 3 Sno label for device descriptors here s the first configuration Configuration 1 stags CONFIG1_ID Config ID Defined in Strings Section 4 Remote Wakeup Self Powered sthe flags Power 0 mA P1 2 interface 0 has the interrupt endpoint private descriptors would go here o interface 0 Alternate Setting 0 Class 0 none defined Subclass 0 sno subclass Protocol OxFF vendor specific name Config 0 Ifc 0 stringtag o private descriptors endpoints sonly one interrupt in address 0x01 packet size 1 polling interval 1 interface 1 is used for sending data interface 1 alternate setting 0 class 0 none subclass 0x0 none protocol OxFF vendor specific name BULKDATA string endpoints bulk out 2 packet size 16 bulk in 3 packet size 16 alternate setting 1 22 USBRC User s Guide Engineering Report 950061 Rev J class 0 none subclass 0 none protocol OxFF vendor specific name ISODATA string endpoints isochronous out 2 packet size 16 pol
40. escriptions of each of the endpoints available when the host selects the containing configuration and then selects if necessary the appropriate alternate interface setting If you only want to include strings for a single language you can put the strings in the appropriate places in the device configuration and interface descriptors USBRC will automatically create string descriptors and keep track of string IDs USBRC User s Guide Engineering Report 950061 Rev J e If you want to include strings for multiple languages you will need to include a strings section The strings section is divided into sections that are associated with specific languages You can specify the language by name or use a numeric language code as specified by the USB specification SEE EXAMPLES AT SECTION 5 PAGE 12 How do I enter UNICODE strings If your strings consist of characters that are part of the 7 bit ASCII set you can simply enter the strings in quotes If you are entering characters outside the ASCII range you have several choices e prepare the text file in UNICODE rather than in ASCII e prepare the file in UTF 8 UTF 16 or ISO 10646 or e look up the UNICODE character values and enter the hexadecimal values using a special notation What is UTF 8 How does it differ from Unicode Why does USBRC use it Unicode is a 16 bit means of representing a wide range of characters Unicode can rep resent about 60 000 characters using a
41. file Output file generated with dpapi 0 commentary omitted for brevity gt gt include usbrctab h beginning of resource data RESCHAR gk UsbResourceData Device descriptor data Configuration 1 descriptor data onn 3 Interface 0 descriptor data OTG descriptor data js Endpoint descriptor data 38 USBRC User s Guide Engineering Report 950061 Rev J i Table of pointers to device i i i g beginning of descriptor table A descriptors RESPTRS gk_UsbResourceTable_1 i RESPTRVAL gk UsbResourceData 0 end of gk UsbResourceTable 1 Table of pointers to configuration descriptors beginning of descriptor table RESPTRS gk UsbResourceTable 2 RESPTRVAL gk UsbResourceData 18 end of gk UsbResourceTable 2 Table of pointers to tables of descriptors Generated via a the root table ROOTTABLE name gk UsbDescriptorRoot V devtbl len devtbl gk UsbResourceTable 1 1 cfgtbl len cfgtbl gk UsbResourceTable 2 1 strtbl langs NULL O others len others NULL 0 end of generated data 59 A Simple Device with High speed Expressions Input file ex9 urc USB resource file with device descriptor and config descriptor and interface descriptor with first setting but nothing else dE db db db HE USB resource file 1 00
42. gistered trademarks of Moore Computer Consultants Inc MCCI Instant RS 232 MCCI Wombat and InstallRight Pro are trademarks of Moore Computer Consultants Inc All other trademarks and registered trademarks are owned by the respective holders of the trademarks or registered trademarks Copyright O 2006 by Moore Computer Consultants Incorporated Document Release History Rev A 7 24 1997 Initial release for USBRC V1 24a Rev B 7 28 1997 Correct typos for USBRC V1 25a Rev C 9 15 1997 Update for USBRC V1 26a example output changed due to correction of a bug in string descriptor handling MCCI SPR 0046 Rev D 8 4 1998 Update for USBRC V2 00h RevE 9 3 1998 Editorial corrections Rev F 9 21 1998 Update to add string index header generation info for V2 10a Rev G 3 19 2001 add descriptor info and language codes changes between V2 10a and V2 11a CDC Ethernet adapter example Rev H 2 10 2003 Update for V2 22 Add dpapi and chipinfo switches DataPump is now the preferred keyword for the URC file section that provides MCCI USB DataPump specific information Rev 2 27 2006 Update for V2 23b Add On The Go statement under USB resource file and an example Rev J 8 1 2006 Update for V2 23n Add Expression evaluation for high speed support USBRC User s Guide Engineering Report 950061 Rev J TABLE OF CONTENTS As EMMETT OR e RR 1 LI NDGA E 1 2 The Layout of USBRC files paci its ck neci elata eat EA abtanipelatstanc
43. ication bulk bus powered class configuration control control packet size data data pump datapump default device device version dword lse nd ndpoint endpoints external full hidden high if in Include File Name Init Function Name interface Interface Data Structure Name USBRC User s Guide Engineering Report 950061 Rev J interrupt isochronous language low ma mux name on the go out packet size polling interval power private data private descriptors private descriptor table product id Properties protocol raw Read only rem remote wakeup self powered serial number speed string index strings subclass three byte usb resource file usb version vendor word These words cannot be used for any other purpose USBRC ignores uppercase lowercase dis tinctions when checking for keywords Bulk BuLK and BULK are all equivalent ways of writing the keyword bulk In addition some tokens are keywords within certain clauses but not elsewhere 2 1 21 Special Keywords in the DataPump Section In the DataPump section section 2 3 8 the following additional keywords are defined buffer size chip data structure name chip header name chip name config data structure name endpoint data structure name endpoint mapping include file name init function name interface data structure name number of en
44. ide Engineering Report 950061 Rev J USB version major minor Class class number SubClass subclass number Protocol protocol number Control Packet Size max bytes Vendor USBIF vendor ID number optional vendor name string or ID Product ID vendors product id number optional product name string or ID Device Version major minor Serial Number string or ID optional label Each of the parts of a USB Device statement must occur in the order given above The parts enclosed in square brackets and are optional The three string or ID fields if present are used in building the string descriptor table You can write either a string enclosed in quotes or a USBRC identifier If you are not worried about translating you can just write a string enclosed in quotes see section 5 2 page 16 for an example If you want to provide support for multiple languages you can use an identifier and then provide a string table that specifies the translation See section 5 3 page 21 for an example USBRC automatically assigns the string table indices USBRC can optionally create a header file containing define commands that define each of the assigned indices This can be helpful if you are storing some of the descriptors in external EEPROM and need to know what descriptor in particular is being assigned 23 2 The Configuration Statement Each device must have one or more USB Configuration
45. igits represents a backslash represents a quote that is embedded in the string Allows a string to be written on multiple lines The and the new line character are not part of the string In addition USBRC provides the following escape sequence as an extension to the normal C escape sequences hex represents an extended UNICODE or ISO 10646 character The backslash left brace and right brace must all be entered literally Hex is a sequence of hex digits and may represent up to 32 bits of information If the resulting value is a 16 bit UNICODE character it will be converted to a single character in the string If the resulting value can be represented as a two character four byte extended UNICODE sequence USBRC will convert it to the appropriate sequence If the resulting value cannot be represented in UNICODE USBRC will print an error message USBRC User s Guide Engineering Report 950061 Rev J Here are some examples of strings ABC tring consisti ters 6 bytes h values 0041 xp tring consisti E ter 2 bytes ith value 000A x 516c x 53f8 a string consisting of 2 characters 4 bytes These are the Chinese characters for the word gongsi meaning company NxX5T6C a string consistion of 3 characters 6 bytes the character 0051 Q the character 0036 6 and the character 0043 C This is because the C Nx sequence scans at most 2 digits This ex
46. ill accept multiple file names on its command line it is normally more convenient to keep this information in a separate chip specific file which can be selected using ze USBRC User s Guide Engineering Report 950061 Rev J the chipinfo switch Normally this file is supplied by MCCI as a separate URC file for each supported chip The keyword Data Pump is also recognized for backwards compatibility with older versions of USBRC The section has the following form DataPump Chip Name chip name string Include File Name include file name string Chip Header Name chip header name string Chip Data Structure Name data structure name string Init Function Name init function name string Endpoint Data Structure Name endpoint name string Config Data Structure Name config name string Interface Data Structure Name interface name string Setting Data Structure Name setting name string Endpoint Number numEndpoint number Speeds low full high low full high EndpointMappingExpr Each of the parts of a DataPump section must occur in the order given above The parts enclosed in square brackets and are optional You must write each of the string fields if present as a string enclosed in quotes Include File Name gives the name of the file which has the definitions for the use of the chip specific kernel For example it could be u820kern h This must match the n
47. ing an ID if you re not sure how to go about getting one Product ID 0x1234 name omitted Product ID is determined by the vendor Device Version 2 05 Device version is determined by the ven dor It must be between 0 0 and 99 99 serial number omitted In this example we have not provided a serial number clause Sno label for device As the comment indicates we have not named the device descriptor Naming of device descriptors is not useful in this version of USBRC here s the first and only configuration bLength bDescription wTotalLength and bNumberlInterfaces are all automatically computed from user data 2434 USBRC User s Guide Engineering Report 950061 Rev J Configuration 1 o configuration name would go here Self Powered Remote Wakeup Bus Powered the flags Power 10 mA private descriptors would go here Next we have the only interface interface 0 Alternate Setting 0 Class 1 Subclass 2 Protocol 3 o o name stringid o o private descriptors zd bConfigurationValue is specified by the user Since the device has only one con figuration and since configurations are numbered starting at one this is configu ration 1 We have not provided a configuration name in this example bmAttributes is determined automatically from the combination of flags specified Here we have specified all the flags bMaxPower is determined aut
48. l endpoints is ignored USBRC verifies that the specified packet size makes sense for the endpoint type according to the USB specification Polling interval should only be specified for isochronous and interrupt endpoints The endpoint address number must be between 1 and 15 inclusive USBRC automatically generates the appropriate endpoint descriptor based on the type direction packet size and polling interval If the data clause is present then the data bytes in the raw data sequence are appended to the generated endpoint descriptor This is useful for generating Audio class endpoint descriptors If the opt ional private descriptors are present then the specified descriptors are inserted into the configuration bundle after the specified endpoint descriptor 23 5 The Strings Statement The strings statement is used to provide translations for USB device strings in multiple lan guages strings optional property list language spec list string or ID string or ID string in these languages string in these languages language spec list string or ID string or ID string in these languages string in these languages optional label USBRC automatically generates the string descriptors and data structures needed to represent the strings you specify including string descriptor 0 which returns a list of language IDs Some string descriptors may
49. length for each descriptor and places the data in the appropriate places in the descriptor table e When working in portable C creating the Unicode string tables is awkward at best e The USB specification provides for devices that store the string descriptors in many languages If one wishes to create such devices it is difficult to find portable tools that will generate the required Unicode in a format that is useful on any micropro cessor Because of these issues MCCI developed a special program the USB Resource Compiler USBRC Instead of hand coding the tables with Chapter 9 of the USB specifications in hand the compiler allows a programmer to describe USB devices in plain text The compiler then translates the descriptive files into C data initialization statements for data structures that are intended to be placed in ROM USBRC User s Guide Engineering Report 950061 Rev J Embedded macros often have very stringent storage requirements How can one program meet all these needs The produced code is intended to be used with a C macro package A sample package is provided on the distribution disk which you should edit with a text editor to meet your requirements USBRC makes certain assumptions about how best to represent the data structures Usually these assumptions are correct If they are not you can edit the file produced by USBRC to meet your needs But I don t want to use C I need to use assembler There are at least
50. leted application section application descriptor table root name test37_root internal names static functions with string filter table get descriptor testapp_get_descriptor set descriptor testapp set descriptor h header file file name test37dh h with string ids initialization assumed name of file CIS USBRC User s Guide Engineering Report 950061 Rev J file name initfile c name to compile for the init function function name test37 init function hn strings info for writing the string header file assumed name of output file file name test37st h prefix for emitted string ids prefix TEST37STRING hn structure type name TEST37 TYPE Nn h 5 7 Sample CDC USB Ethernet Adapter The following example shows how to use USBRC to generate the descriptors for a USB Ethernet adapter This example is based on the CDC 1 1 spec USB resource file 1 00 Device USB version 1 1 Class OxFF vendor specific SubClass OxFF serial device Protocol 0x0 none specified Control Packet Size 64 Vendor O0x40E tag VENDOR ID 4 MCCI s vendor ID Product ID OxF102 tag PRODUCT Device Version 1 10 serial number SERIALNUMBER no external name here s the first configuration Configuration 1 Stags CONFIG1_ID Bus Powered Self Powered the flags Power 2 mA 9 config private descriptors would go here Os
51. ling interval 1 isochronous in 3 packet size 16 polling interval 1 o o interface 2 is used for sending data interface 2 alternate setting 0 class 0 none subclass 0x0 none protocol OxFF vendor specific name BULKDATA string endpoints bulk out 4 packet size 16 bulk in 5 packet size 16 i alternate setting 1 class 0 none subclass 0 none protocol OxFF vendor specific name ISODATA string endpoints isochronous out 4 packet size 16 polling interval 1 isochronous in 5 packet size 16 polling interval 1 o 9 interface 3 is used for sending data interface 3 alternate setting 0 class 0 none subclass 0x0 none protocol OxFF vendor specific name BULKDATA string endpoints bulk out 6 packet size 16 bulk in 7 packet size 16 208 USBRC User s Guide Engineering Report 950061 Rev J alternate setting 1 class 0 none subclass 0 none protocol OxFF vendor specific name ISODATA string endpoints isochronous out 6 packet size 16 polling interval 1 isochronous in 7 packet size 16 polling interval 1 Sno names strings default language English USA MCCI Moore Computer Consultants Inc String 1 PRODUCT MCCI xAE TrueTask xAE USB Data Pump Demonstration Firmware String 2 SERIALNUMBER 00000000 String 3 CONFIG1_ID MCCI USB Data Pump Loopback Configuration Config 0 Ifc 0 MCCI Loopback Control Interrupt Interface BULKDATA Bulk
52. nd interface 0 each of interfaces 1 2 and 3 can be configured independently for bulk or isochronous data transfer interface 1 the bulk setting alternate setting 0 class 0 none subclass 0x0 none protocol OxFF vendor specific BAT USBRC User s Guide Engineering Report 950061 Rev J name Bulk Data endpoints bulk out 2 packet size 16 bulk in 3 packet size 16 the isochronous setting alternate setting 1 class 0 none subclass 0 none protocol OxFF vendor specific name ISO Data endpoints isochronous out 2 packet size 16 polling interval 1 isochronous in 3 packet size 16 polling interval 1 Send interface 1 interface 2 is used for sending data interface 2 alternate setting 0 class 0 none subclass 0x0 none protocol OxFF vendor specific name Bulk Data endpoints bulk out 4 packet size 16 bulk in 5 packet size 16 i alternate setting 1 class 0 none subclass 0 none protocol OxFF vendor specific name ISO Data endpoints isochronous out 4 packet size 16 polling interval 1 isochronous in 5 packet size 16 polling interval 1 end interface 2 interface 3 is used for sending data interface 3 alternate setting 0 class O0 none 248 2 Send resource data 9 Output file end configuration s end of file USBRC User s Guide Engineering Report 950061 Rev J subclass 0x0 none protocol OxFF Bulk Data endpoints bulk out 6 packet size 16
53. need to be stored in EEROM or other storage external to the tables generated by the resource compiler Usually only a few descriptors need to be stored externally You identify those descriptors by providing one or more optional property list statements Each statement has the form z413 USBRC User s Guide Engineering Report 950061 Rev J properties external ID ID properties external read only ID ID Notice that the permitted set of properties is either external or external read only Specifying that a string is external does not change how USBRC records data about the string Normally you ll provide the default or initial values for the strings as part of the resource file and you ll arrange to supersede these values with externally stored values If you are using the MCCI USB DataPump most of this process is automatically handled for you Since USBRC assigns the string indices automatically you may need a way to associate the string indices with specific string descriptors For example the serial number might be computed based on the Ethernet node ID which might be stored in a network controller chip USBRC can generate an additional header file the string index header file which automatically defines symbolic names for each of the external string descriptor IDs The names are based on the IDs you use in the USB resource file Each 1anguage spec 1ist specifies one or more language codes a
54. ns 2 2 The Input Language The input file consists of the following sections e There must be a USB resource file section which defines the data that is to be emitted to the descriptor file and also define the layout of the device e Optionally there can be a DataPump section which provides information to the resource compiler about the target USB chip Normally this information comes from a separate file provided by MCCI that matches the target USB chip s miniport driver for the MCCI USB DataPump e Optionally there can be an application section which provides information to the resource compiler that customizes the output files to match the application Much of the information in the application section can be overridden from the command line However for a given application of the DataPump it is normally more convenient to place the information in the resource file than it is to put it in the make file The sections may appear in any order 23 The USB resource file Section The USB resource file section has the following structure USB resource file 1 0 USB Device Descriptor USB Configuration Descriptor s String Translation Table s Private Descriptor s Data Tables s The statements in the resource file section may occur in any order 2 3 1 The USB device Statement Each device must have one USB Device Descriptor of the following form USB Device 210 USBRC User s Gu
55. omatically from the value specified For example the Microsoft power man agement descriptors could be coded here Interfaces are specified following after the information that is common to the con figuration In this case we have a single interface since interfaces are numbered starting at zero this is interface 0 Each interface has an alternate setting value By default the alternate setting is zero so USBRC allows you to omit it in this case Each interface and alternate setting has its own device class subclass and proto col code In this case we are using arbi trary values Each interface and alternate setting can have its own string identification In this case we have omitted a name The private descriptors placed here will be placed in the configuration descriptor between this interface descriptor and the associated endpoints We have not used any in this example USBRC User s Guide Engineering Report 950061 Rev J 9 9 endpoints for this setting Finally we can specify zero or more end points associated with this setting In this example the device has a single interrupt endpoints endpoint only one interrupt The type of endpoint in The direction into the host address 0x01 The endpoint address packet size 1 The maximum packet size only one byte polling interval 1 For interrupt endpoints you must specify how often the host should poll in mil more endpoints would be her
56. on of the following form application descriptor table functions with without string filter table get descriptor get fn string set descriptor set fn string internal names static global 4 USBRC User s Guide Engineering Report 950061 Rev J root name root table name header file file name header file name with without string ids initialization file name init code file name function name init fn name strings file name string id file name prefix prefix string structure type name structure name All of the subsections of the application section are optional and may appear in any order For ease of reference the above table is sorted in alphabetical order All of the variable fields in the application structure should be specified as strings The string fields are used by USBRC for the purposes given in Table 1 Table 1 String Values in Application Section get fn string The name of the function that is to be called to filter get descriptor operations header file name The reference name for the data pump header file which will contain the structural definition for the device described by this resource file init code file name The reference name for the initialization code file which will contain the C function that initializes the data structures for this device init fn name The name to be given to
57. on gt expression expression expression lt expression expression lt expression expression gt expression expression gt expression expression amp expression expression expression expression expression lt expression1 gt lt lt lt expression2 gt expression gt gt lt expression2 gt Syntax lt expression gt lt expression gt lt expression gt Description Adds two number expressions Subtracts two number expressions Multiplies two number expressions Divides two number expressions Gives remider of a division Concatenates two string expressions Compares two number expressions for inequality Compares two number expressions for equality Compares two number expressions for less than Compares two number expressions for less than or equal Compares two number expressions for greater than Compares two number expressions for greater than or equal Bit wise AND two number expressions Bit wise OR two number expressions Bit wise EX OR two number expressions Left shifts lt expression1 gt by lt expression2 gt times Right shifts lt expression1 gt by lt expression2 gt times Description Negates a number expression Logical NOT of a number expression USBRC User s Guide Engineering Report 950061 Rev J 5 lt expression gt Bit wise NOT of a number expression Please see section 2 6 String Expressions in USBRC for string related expressio
58. owered the flags Power 10 mA private descriptors would go here private descriptors raw code 0x55 body just unicode I am a duck o o interfaces go here interface 0 Alternate Setting 0 Class 1 28 USBRC User s Guide Engineering Report 950061 Rev J Subclass 2 Protocol 3 o name stringid oe o private descriptors private descriptors raw code 123 Sbody just unicode Lots of luck o o endpoints would go here endpoints interrupt in 1 packet size 16 polling interval 1 end config 1 no label here s the second configuration Configuration 2 string id would go here Remote Wakeup Self Powered the flags Power 0 mA o o private descriptors would go here interface 0 has the interrupt endpoint interface 0 Alternate Setting 0 Class 0 none defined Subclass 0 no subclass Protocol OxFF Svendor specifics 5 name stringid o private descriptors endpoints only one interrupt in address 0x01 packet size 1 polling interval 1 i end interface interface 1 is used for sending data interface 1 220 USBRC User s Guide Engineering Report 950061 Rev J alternate setting 0 class 0 none subclass 0x0 none protocol OxFF vendor specific endpoints bulk out 2 packet size 16 bulk in 3 packet size 16 i alternate setting 1 class 0 none subcl
59. p initialization file that is compiled into the output files C file which contains the initialization function If the file name is specified as USBRC will write its output to STDOUT Designates the output file for the table file Normally USBRC writes its output to STDOUT Using o you can send the output directly to a file without redirection Rn name of descriptor table Designates the name to be used for the descriptor table and for the subsidiary tables produced by this compilation Normally USBRC assigns default names based on information assigned in the application section of the input file USBRC will declare all tables except the topmost table as being static Normally or with noRs all tables are global This overrides any information given in the application section of the input file Sn structure Name of top level data pump structure 10 USBRC User s Guide Engineering Report 950061 Rev J type type Specifies the format of the output file Default is type c source In this ver sion of USBRC this is the only output format available v Display copyright and version information e g Version 2 22 at startup The default is to run quietly Werror Treats warning messages as errors By default warnings are displayed but do not affect the exit status of the program If Werror is specified USBRC will treat warnings as errors and will exit with error status if any warnings or errors are
60. riptor will be used as many times as needed in the gen erated data structures 2 3 6 The Private Descriptor Statement For special applications USBRC allows you to create private descriptors The syntax of the private descriptor statement is private descriptor optional label Raw Descriptor Configuration Interface Endpoint Device Configuration Interface Endpoint and Device statements are as given above however the Interface and Endpoint statements generate only the corresponding interface and end point descriptors Raw Descriptor is used to generate descriptors with arbitrary contents The syntax is raw code byte data code byte is the descriptor code data specifies the byte data to be embedded in the descriptor as a list of bytes or strings USBRC automatically calculates and inserts the descriptor length for you See section 2 6 page 5 for more details on the operators that can be used to construct the data The label is used to label the generated table of descriptors if private descriptor is used at the top level of the USB resource file otherwise it is ignored A simple example is private descriptor generate a RAW descriptor of type 0x55 with a body consisting 4 of bytes 3 5 7 0 and the unicode version of the string The 7 0 comes from the word operator f USBRC User s Guide Engineering Report 950061 Rev J raw 0x55 3 5
61. s defined by the USB speci fication for which you want to provide translations Each entry in the list is separated by commas You can use the following things in the list default language language id number language language name string If you use 1anguage name string you can specify the language directly The language name must be quoted Language name comparisons are not case sensitive The known languages are as defined in the specification Universal Serial Bus Language Identifiers LANGIDs 3 29 00 Version 1 0 available to USB IF members through the website http www usb org You can also arrange for these names to be defined in the same header file that defines the structure of your device for the DataPump 14 Afrikaans Albanian Arabic Arabic Algeria Arabic Bahrain Arabic Egypt Arabic Iraq Arabic Jordan Arabic Kuwait Arabic Lebanon Arabic Libya Arabic Morocco Arabic Oman Arabic Qatar Arabic Saudi Arabia Arabic Syria Arabic Tunisia Arabic United Arab Emirates Arabic Yemen Assamese Azeri Cyrillic Azeri Latin Basque Belarusian Bengali Bulgarian Burmese Catalan Chinese Hong Kong Chinese Hong Kong SAR Chinese Macau SAR Chinese PRC Chinese Singapore Chinese Taiwan Chinese simplified Chinese traditional Croatian Czech Danish
62. sbResourceData 6077 ESPTRVAL gk UsbResourceData 255 ESPTRVAL gk UsbResourceData 361 ESPTRVAL gk UsbResourceData 379 ESPTRVAL gk UsbResourceData 463 ESPTRVAL gk UsbResourceData 547 ESPTRVAL gk UsbResourceData 605 This is the table for traditional Chinese Note that all the entries are the same as the other string tables except for entry 1 which points to the traditional Chinese UNICODE string for MCCI s Chinese name end of gk UsbResourceTable 4 beginning of descriptor table RESPTRS gk U US UU UU uw uou uw Do EM ESPTRVAL gk UsbResourceData 181 ESPTRVAL gk UsbResourceData 695 ESPTRVAL gk UsbResourceData 255 ESPTRVAL gk UsbResourceData 361 ESPTRVAL gk UsbResourceData 379 ESPTRVAL gk UsbResourceData 463 ESPTRVAL gk UsbResourceData 547 ESPTRVAL gk UsbResourceData 605 SbResourceTable 5 This is the table for simplified Chinese Note that all the entries are the same as the other string tables except for entry 1 which points to the simplified Chinese UNICODE string for MCC s Chinese name end of gk UsbResourceTable 5 beginning of language ID data LANGIDPTRS gk UsbLangidTable 6 LANGPTRVAL 0x0000 8 gk UsbResourceTable 3 The default language 0000 pointer LANGPTRVAL 0x0409 8 gk UsbResourceTable 3 US English 0x409 pointer LANGPTRVAL 0x0404 8 gk UsbResourc
63. sourceTable 3 42 US OF HIS SOFTWARE EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE Gl USBRC User s Guide Engineering Report 950061 Rev J RESPTRVAL gk UsbResourceData 50 end of gk UsbResourceTable 3 beginning of descriptor table RESPTRS gk UsbResourceTable 4 RESPTRVAL gk UsbResourceData 68 end of gk UsbResourceTable 4 init function declaration USBRCTAB DECLARE DCD INIT FN NOCLASS UDEVIVTRAInit the root table ROOTTABLE V3 WITH SEMI V name gk UsbDescriptorRoot init device fn UDEVIVTRAInit UDEVICE size sizeof UDEVIVTRA devtbl len devtbl gk UsbResourceTable 1 1 cfgtbl len cfgtbl gk UsbResourceTable 2 1 hsdevtbl len hsdevtbl gk UsbResourceTable 3 1 hscfgtbl len hscfgtbl gk UsbResourceTable 4 1 pOsFeatureTable 0 strtbl langs 05 0 others len others 0 0 N N get descriptor fn ext bitmap len r o bitmap len 0 set descriptor fn 0 N 0r 30 0 Q end of generated data d
64. t 950061 Rev J usbrc exe o nul chipinfo uss820 urc Fn Ho mydevice h Sn UDEVCHIP APP mydevice chip app init Hn mydevice h urc The o nul option on Windows causes the descriptor table information to be discarded To create a data pump initialization c file named mydevice c for the same chip application you can call the resource compiler this way usbrc exe chipinfo uss820 urc Fn chip app init Hn mydevice h In mydevice c Io Sn UDEVCHIP APP o mydevice urc gt mydevice c This example generates a file that contains both the initialization code and the descriptor tables o redirects the descriptor table output to STDOUT and Io redirects the initialization function output to STDOUT gt mydevice c sends the combined output to the file mydevice c To create the table header and initialization files at the same time usbrc exe chipinfo uss820 urc Fn chip app init Hn mydevice h Ho mydevice h In mydevice c Io Sn UDEVCHIP APP o mydevice urc gt mydevice c 5 Example resource description files Following are example resource description files These files use the syntax outlined above here however the keywords are not all lower case For each example there is a corresponding descriptor table output file showing the expected results of a successful compilation No examples are given of the corresponding data pump header and initialization code files
65. t Data Structure Name UEPIVTRA umber of Endpoints 2 speeds full high oe oe The only requirement for the mapping is that oe oe for each endpoint address there is only one jo oe 5 corresponding endpoint index Endpoint Mapping 0 0 0x80 1 h end of file Output file generated with dpapi 2 i Module ex6 new c Function USB peripheral device descriptor data generated automatically from ex6 new urc by v223m version V2 23m Jan 19 2006 Copyright Copyright 1997 2006 Moore Computer Consultants Inc Distribution and use in source and binary forms with or without modification are permitted provided that the following conditions are met 1 Redistribution of source code must retain the above copyright notice this list of conditions and the following disclaimer 2 MCCI s name may not be used to endorse or promote products derived from this software without specific prior written permission Disclaimer THIS FILE IS PROVIDED BY MCCI AS IS AND ANY EXPRESS OR IMPLIED WARRANTIES INCLUDING BUT NOT LIMITED TO HE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSI ARE DISCLAIMED IN NO EVENT SHALL MCCI BE LIABLE FOR ANY DIRECT INDIRECT INCIDENTAL SPECIAL EXEMPLARY OR CONSEQUENTIAL DAMAGES INCLUDING BUT NOT LIMITED TO PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES LOSS OF USE DATA OR PROFITS OR BUSINESS
66. the initialization function prefix string The string that is to be prefixed to the string index symbolic definitions root table name The name to be given to the root descriptor table set fn string The name of the function that is to be called to filter set descriptor operations string id file name The reference name for the string id header file which will contain the symbolic names of the exported string IDs structure name The typedef name for the structure that models this USB device In addition several Boolean options are provided descriptor table functions with without string filter table controls whether USBRC generates additional bit maps for the root descriptor table With string s USBRC User s Guide Engineering Report 950061 Rev J filter table causes USBRC to generate two bit maps one for the string IDs that were declared to be external and another for the string IDs that were declared to be read only descriptor table names static global controls whether USBRC uses global or static definitions to generate the resource table Global the default causes USBRC to use global definitions Static causes USBRC to mark all global data cells in the data file as static except for the root table header file with string ids causes USBRC to generate string ID definitions into the DataPump header file header file without string ids causes USBRC to omit the string ID definitions from the DataPump hea
67. two ways to do this If you have a C compiler you can use it to compile the data structures only and link the resulting file with your assembly code You can use SED or a manual text editor to convert the output into the format your assembler requires What about changes in the standard Microsoft for example has requested a new power management descriptor embedded in the data returned by Request Configuration Descrip tor If Iuse USBRC can I represent the descriptor Yes At various places you can insert private descriptor clauses which allow you to enter custom descriptors at the appropriate place in the resulting data stream Of course you must hand format the body of the descriptor but USBRC will take care of setting the length for you How do I specify a USB devices using USBRC The resource compiler reads a simple language input file that is divided into sections that track the USB specification The device section includes the information that goes into the Device Descriptor A device only has one Device Descriptor so there is only one device section For each configuration of the device you must write a configuration section Each configuration section contains the information that goes into that configuration s Configuration Descriptor along with the associated Interface and Endpoint descriptors Each configuration has one or more interface clauses and each interface clause includes endpoint d
68. urceTable 2 0 0 Table of pointers to configura tion descriptors 18 93 end of gk_UsbResourceTable_2 1 2 This section gives an example of the DataPump section that is appropriate for the Agere USS820 This information is normally passed in using the chipinfo switch the information here must match the conventions used by the chip driver The chipinfo file for a given chip is normally found in ifc chip common chipinfo urc Input file ex5 urc Data Pump Information for USBRC DataPump Chip Name Uss820 Include File Name u820kern h Chip Header Name UDEV820 HDR Chip Data Structure Name UDEV820 Init Function Name Endpoint Data Structure Name Config Data Structure Name Interface Data Structure Name Setting Data Structure Name 16 Number of Endpoints UDEV820Init EPIO820 UCFG820 UIFCSET820 UIFC820 32 USBRC User s Guide Engineering Report 950061 Rev J ae The only requirement for the mapping is that o for each endpoint address there is only one oe oe corresponding endpoint index Endpoint Mapping 0x80 1 1 2 0x81 3 2 4 0x82 5 3 6 0x83 7 4 8 0x84 9 5 10 0x85 11 6 12 0x86 13 0x87 15 5 6 Sample Application Section This section presents an example of a correctly comp
69. ure Name gives the name of the interface set data structure This is the data structure that collects all alternate settings for a given interface This field is optional and the default is UINTERFACESETS You must not change the value as it must match the name used by the DataPump common code Setting Data Structure Name gives the name of the interface data structure The interface data structure models a single alternate setting of an interface This field is optional and the default is UINTERFACE You must not change the value as it must match the name used by the DataPump common code Endpoint Number gives the total number of the physical endpoints that are defined by the hardware Speeds gives the speeds that are supported by this device among low full and high EndpointMappingExpr provides the mapping from endpoint address to endpoint index The requirement is that for each endpoint address there is only one corresponding endpoint index The EndpointMappingExpr has the following syntax 1 if lt expr gt lt mapping set gt else lt mapping set gt 2 lt mapping set gt The mapping set has the following syntax Endpoint Mapping endpoint_address endpoint_index The meaning of the endpoint index is defined by the chip specific code that uses it Please see section 5 5 page 32 for an example 2 5 The Application Section Each input file may have an application secti
70. vendor specific name bulk in 7 packet size 16 i alternate setting 1 class 0 none subclass 0 none protocol OxFF ISO Data endpoints vendor specific name isochronous out 6 packet size 16 polling interval 1 isochronous in 7 packet size 16 polling interval 1 Send interface 3 no label no label 5 lt lt Commentary omitted for brevity gt gt usbrctab h include beginning of resourc RESCHAR gk UsbResourceData 18 e oe Wwe OOO 0n WANTON CO OO o 1 EQ oQ O JS r 9 p 299 255 r 9 r1 r 2 133 r 6 r 2 data some linebreaks removed for brevity 0 I 2 255 163 4 7 Sy uy Is T Tedy 5 4 232 OF 1 16 16 0 255 0 0 4 1 Dr 0329 9A Ly 27 0 0 Ly 16 707 2y 16570 0 255 0 7 dp Oy Oy Ty coa 0 2097 Oy T5 0 1 4 3 9 4 IQQ 325505 67 I01 0 I145 0 32 108 0 116 O0 97 dor Op LLO 0 99 0 8 14 3 96 pcd Oi 16 0 255 I Oy 0 Ty 6 7 4A 3 135 2 65 y 64 0 4 0 1 0 6 4 5 5 0 1 9 9 7 225 4 0 4 1 2r 131 Yu Ou El Zy Oy 25 07 l33 L6 Oi 4 1 l6 0 l 2 0 0 255 167 0 0 9 LO yn Oy bz Sr Ty OF 111 111 0 109 0 Or 6 Q0 LILA 0 0 110 0 116 O 36 3 85 0 83 0 0 0 2 16 0 1 2 16 4 5 7 1 0 5 4 5 0 111 1
71. vice descriptor config descriptor and interface descriptors as follows ifc 0 1 interrupt endpoint ifc 1 alt setting 2 bulk endpoints i o ifc l alt setting iso endpoints i o ifc 2 alt setting bulk endpoints i o ifc 2 alt setting iso endpoints i o ifc 3 alt setting bulk endpoints i o Ho G ipic O perc ji AERA Kn NNN DS ifc 3 alt setting iso endpoints i o This example also includes string descriptors in the default language USB resource file 1 00 16 USBRC User s Guide Engineering Report 950061 Rev J Device USB version 1 00 Class OxFF vendor specific SubClass OxFF serial device Protocol 0x0 none specified Control Packet Size 8 Vendor 0x40E Moore Computer Consultants Inc Product ID OxE101 USB Demo Firmware Device Version 1 00 o o serial number omitted o no device descriptor label here s the first and only configuration Configuration 1 Default configuration Remote Wakeup Self Powered sthe flags Power 0 mA private descriptors would go here interface 0 has the interrupt endpoint it has only one alternate setting interface 0 Alternate Setting 0 Class 0 none defined Subclass 0 no subclass Protocol OxFF vendor specific name Interrupt endpoint o o private descriptors endpoints only one interrupt in address 0x01 packet size 1 polling interval 1 Se

USBRC User's Guide

Contents

Download Pdf Manuals

Related Search

Related Contents