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_t *	generate_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:

• Device: usb_descriptor_body_device_t
• Configuration: usb_descriptor_body_configuration_t
• Interface: usb_descriptor_body_interface_t
• Endpoint: usb_descriptor_body_endpoint_t
• String: Use a little endian UTF-16 string. e.g. u"IceTop display"

Author

Sander Vanheule (Universiteit Gent)

See also

USB 2.0 specification §9

Enumeration Type Documentation

usb_descriptor_type_t

enum 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

req	Pointer 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

head	Pointer 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

type	Type of the descriptor.
body	Pointer to the body of the descriptor.
memspace	Memory 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.