IceCube display
LED display to show IceCube event data
All Data Structures Files Functions Variables Enumerations Enumerator Macros Modules Pages
descriptor.h File Reference

USB descriptor definitions and handling. More...

Include dependency graph for descriptor.h:

Go to the source code of this file.

Data Structures

struct  usb_descriptor_header_t
 Common header used for all USB descriptors. More...
 
struct  descriptor_list_t
 Single item of a linked list of descriptors. More...
 
struct  usb_descriptor_body_device_t
 Device descriptor body. More...
 
struct  usb_descriptor_body_configuration_t
 Configuration descriptor body. More...
 
struct  usb_descriptor_body_interface_t
 Interface descriptor body. More...
 
struct  usb_descriptor_body_endpoint_t
 Endpoint descriptor body. More...
 

Macros

#define USB_CONFIG_ATTRIBUTES(self_powered, remote_wakeup)   ((1<<7)|((self_powered)<<6)|((remote_wakeup)<<5))
 
#define USB_MAX_POWER(milli_amps)   (milli_amps/2)
 

Enumerations

enum  usb_descriptor_type_t {
  DESC_TYPE_DEVICE = 1, DESC_TYPE_CONFIGURATION = 2, DESC_TYPE_STRING = 3, DESC_TYPE_INTERFACE = 4,
  DESC_TYPE_ENDPOINT = 5
}
 

Functions

uint8_t usb_descriptor_size (const enum usb_descriptor_type_t type, const void *body, const enum memspace_t memspace)
 Calculate the total size of a USB descriptor. More...
 
uint8_t usb_descriptor_body_size (const enum usb_descriptor_type_t type, const void *body, const enum memspace_t memspace)
 Calculate the size of a USB descriptor's body. More...
 
struct descriptor_list_tgenerate_descriptor_list (const struct usb_setup_packet_t *req)
 
uint16_t get_list_total_length (const struct descriptor_list_t *head)
 Calculate the sum of all descriptor sizes in a linked list. More...
 

Detailed Description

USB descriptor definitions and handling.

In the USB protocol descriptors are a vital part of device enumeration. It is a flexible system, but requires some effort from the developer to implement properly. The constants, structs and functions provided here attempt to make adding new descriptors as painless as possible. Most structs defined in this file use the notation from the USB specification instead of notation used elsewhere in this project for easier referencing.

When a setup request response is generated using generate_descriptor_list(), a linked list with the required descriptors will be dynamically allocated. Since USB descriptors are usually only requested during device enumeration, the leaves the memory free to be used for other purposes during USB operation, such as remote display frame transfers.

Descriptor bodies are provided for the following descriptor types:

Author
Sander Vanheule (Universiteit Gent)
See also
USB 2.0 specification §9

Enumeration Type Documentation

◆ usb_descriptor_type_t

List of used USB descriptors. Note that more descriptor types are defined by the USB 2.0 standard. Since these are not supported or used anywhere, there is currently no need to define them.

Enumerator
DESC_TYPE_DEVICE 

Device descriptor.

DESC_TYPE_CONFIGURATION 

Configuration descriptor.

DESC_TYPE_STRING 

String descriptor.

DESC_TYPE_INTERFACE 

Interface descriptor.

DESC_TYPE_ENDPOINT 

Endpoint descriptor.

Function Documentation

◆ generate_descriptor_list()

struct descriptor_list_t* generate_descriptor_list ( const struct usb_setup_packet_t req)

Create a linked list of USB descriptors based on the provided setup request. Only pass setup packets that contain a GET_DESCRIPTOR request, as this function does not check the validity of the packet.

Parameters
reqPointer to the setup request packet with a GET_DESCRIPTOR request.
Returns
A linked list of descriptor_list_t objects.

◆ get_list_total_length()

uint16_t get_list_total_length ( const struct descriptor_list_t head)

Calculate the sum of all descriptor sizes in a linked list.

This function is used when a configuration descriptor is provided, which needs to contain the total lenght off all returned descriptors.

Parameters
headPointer to the first item in the list.
Returns
Total byte size of the descriptor list.

◆ usb_descriptor_body_size()

uint8_t usb_descriptor_body_size ( const enum usb_descriptor_type_t  type,
const void *  body,
const enum memspace_t  memspace 
)

Calculate the size of a USB descriptor's body.

Most descriptors have a predifined length, so in those cases this function just returns a constant. String descriptors however have no predetermined length, so their length needs to be determined at runtime.

Parameters
typeType of the descriptor.
bodyPointer to the body of the descriptor.
memspaceMemory space the descriptor body resides in.
Returns
The total size in bytes of a USB descriptor's body.

◆ usb_descriptor_size()

uint8_t usb_descriptor_size ( const enum usb_descriptor_type_t  type,
const void *  body,
const enum memspace_t  memspace 
)

Calculate the total size of a USB descriptor.

This function performs the same calculation as usb_descriptor_body_size(), but adds the size of the descriptor header that is identical for all descriptors.

Returns
The total size in bytes of a USB descriptor.