AN249 Silicon_Laboratories, AN249 Datasheet - Page 20

• Manufacturer Part Number: AN249
• Description: Human Interface Device Tutorial
• Manufacturer: Silicon_Laboratories

AN249
5.5. F3xx_USB0_ReportHandler.c File
All
Report
preparation and formatting takes place inside Report Handlers
contained within
the
USB_ReportHandler.c file. Locations in the .c file that must be modified by the user are clearly commented. The
following subsections describe how the firmware system functions and discuss each location where modifications
will be necessary.
5.5.1. Behavior of the F3xx_USB0_ReportHandler.c File
Firmware calls handlers defined inside F3xx_USB0_ReportHandler.c every time a newly received output report
has been received and every time an input report needs to be formatted before transmission.
The F3xx_USB0_ReportHandler.c file defines two Report Vector Tables, one for input reports and one for output
reports. Each element of a vector table is composed of a struct linking a Report ID to its corresponding custom
Report Handler. Designers are responsible for entering their Report IDs and Report Handler function names into
these tables.
When a report needs to be prepared or processed, firmware calls either ReportHandler_IN() or
ReportHandler_OUT(), with the Report ID passed as a parameter. These functions search the Report Vector
Tables for a matching Report ID and then call the corresponding Report Handler.
5.5.2. Handler Prototypes And Declarations
Toward the top of the file, designers will find a few sections where custom code must be added. A function
prototype for each Report Handler must be placed in the Local Function Prototype section. Designers should link
each of these functions to their corresponding Report IDs inside the Report Vector Tables. Input Reports should be
added to IN_VectorTable, while output reports should be added to OUT_VectorTable. Designers must also
set the vector table array sizes correctly by setting the pre-compiler directives IN_VectorTableSize and
OUT_VectorTableSize.
In the case where the HID system requires only one input or output report, the Vector Tables must link the Report
Handler to Report ID of 0x00. For an example of this, see “7. USB Mouse Example” .
5.5.3. Report Handler Requirements
Designers must define a function body for each Report Handler, and these handlers must follow a few simple
guidelines. Input Report handlers must set the IN_Buffer field “Ptr” to the buffer containing data to be
transferred, and must set the IN_Buffer field “length” to the number of bytes the USB system should attempt to
transfer.
Before the firmware system calls the appropriate Output Report Handler, the system calls a function defined in
F3xx_USB0_ReportHandler.c called Setup_OUT_Buffer(). This routine points the OUT_Buffer field “Ptr” to a
buffer where the received report can be stored. The routine must also set OUT_Buffer’s field “Length” to the
size of the buffer.
Output Report Handlers must assume that data contained in OUT_Buffer will be overwritten after the Handler
exits and should copy any data that needs to be preserved elsewhere in memory.
5.5.4. Including Report IDs
If the Report Descriptor defines Report IDs, Report Handlers must include Report IDs in the IN_Buffer.Ptr and
adjust the IN_Buffer.Length accordingly. The first byte of the input buffer should be set to the Report ID of the
report about to be transmitted. The number of bytes transmitted should be increased by 1 to include the Report ID
byte. The USB Mouse example uses only one report, does not define any Report IDs, and so the Report Handler
does not include any Report ID information in the buffer. The HID Blinky Example does use more than one report,
so all of its Report Handlers must take Report IDs into account.
For systems that use more than one Report, each report must be tagged with a unique Report ID.
20
Rev. 0.2