usb_ch9.h File Reference

USB Chapter 9 structures and definitions. More...

#include <zephyr/version.h>
#include <zephyr/sys/util.h>
#include <zephyr/math/ilog2.h>
#include <zephyr/usb/class/usb_hub.h>

Go to the source code of this file.

Data Structures
struct	usb_req_type_field
struct	usb_setup_packet
	USB Setup Data packet defined in spec. More...
struct	usb_desc_header
	Header of an USB descriptor. More...
struct	usb_device_descriptor
	USB Standard Device Descriptor defined in spec. More...
struct	usb_device_qualifier_descriptor
	USB Device Qualifier Descriptor defined in spec. More...
struct	usb_cfg_descriptor
	USB Standard Configuration Descriptor defined in spec. More...
struct	usb_if_descriptor
	USB Standard Interface Descriptor defined in spec. More...
struct	usb_ep_desc_bmattr
struct	usb_ep_descriptor
	USB Standard Endpoint Descriptor defined in spec. More...
struct	usb_string_descriptor
	USB Unicode (UTF16LE) String Descriptor defined in spec. More...
struct	usb_association_descriptor
	USB Association Descriptor defined in USB 3 spec. More...

Macros
#define	USB_REQTYPE_DIR_TO_DEVICE   0
	USB Setup packet RequestType Direction values (from Table 9-2)
#define	USB_REQTYPE_DIR_TO_HOST   1
#define	USB_REQTYPE_TYPE_STANDARD   0
	USB Setup packet RequestType Type values (from Table 9-2)
#define	USB_REQTYPE_TYPE_CLASS   1
#define	USB_REQTYPE_TYPE_VENDOR   2
#define	USB_REQTYPE_TYPE_RESERVED   3
#define	USB_REQTYPE_RECIPIENT_DEVICE   0
	USB Setup packet RequestType Recipient values (from Table 9-2)
#define	USB_REQTYPE_RECIPIENT_INTERFACE   1
#define	USB_REQTYPE_RECIPIENT_ENDPOINT   2
#define	USB_REQTYPE_RECIPIENT_OTHER   3
#define	USB_REQTYPE_GET_DIR(bmRequestType)
	Get data transfer direction from bmRequestType.
#define	USB_REQTYPE_GET_TYPE(bmRequestType)
	Get request type from bmRequestType.
#define	USB_REQTYPE_GET_RECIPIENT(bmRequestType)
	Get request recipient from bmRequestType.
#define	USB_SREQ_GET_STATUS   0x00
	USB Standard Request Codes defined in spec.
#define	USB_SREQ_CLEAR_FEATURE   0x01
#define	USB_SREQ_SET_FEATURE   0x03
#define	USB_SREQ_SET_ADDRESS   0x05
#define	USB_SREQ_GET_DESCRIPTOR   0x06
#define	USB_SREQ_SET_DESCRIPTOR   0x07
#define	USB_SREQ_GET_CONFIGURATION   0x08
#define	USB_SREQ_SET_CONFIGURATION   0x09
#define	USB_SREQ_GET_INTERFACE   0x0A
#define	USB_SREQ_SET_INTERFACE   0x0B
#define	USB_SREQ_SYNCH_FRAME   0x0C
#define	USB_DESC_DEVICE   1
	Descriptor Types defined in spec.
#define	USB_DESC_CONFIGURATION   2
#define	USB_DESC_STRING   3
#define	USB_DESC_INTERFACE   4
#define	USB_DESC_ENDPOINT   5
#define	USB_DESC_DEVICE_QUALIFIER   6
#define	USB_DESC_OTHER_SPEED   7
#define	USB_DESC_INTERFACE_POWER   8
#define	USB_DESC_OTG   9
	Additional Descriptor Types defined in USB 3 spec.
#define	USB_DESC_DEBUG   10
#define	USB_DESC_INTERFACE_ASSOC   11
#define	USB_DESC_BOS   15
#define	USB_DESC_DEVICE_CAPABILITY   16
#define	USB_DESC_CS_DEVICE   0x21
	Class-Specific Descriptor Types as defined by USB Common Class Specification.
#define	USB_DESC_CS_CONFIGURATION   0x22
#define	USB_DESC_CS_STRING   0x23
#define	USB_DESC_CS_INTERFACE   0x24
#define	USB_DESC_CS_ENDPOINT   0x25
#define	USB_SFS_ENDPOINT_HALT   0x00
	USB Standard Feature Selectors defined in spec.
#define	USB_SFS_REMOTE_WAKEUP   0x01
#define	USB_SFS_TEST_MODE   0x02
#define	USB_GET_STATUS_SELF_POWERED   BIT(0)
	Bits used for GetStatus response defined in spec.
#define	USB_GET_STATUS_REMOTE_WAKEUP   BIT(1)
#define	USB_SCD_RESERVED   BIT(7)
	USB Standard Configuration Descriptor Characteristics from Table 9-10.
#define	USB_SCD_SELF_POWERED   BIT(6)
#define	USB_SCD_REMOTE_WAKEUP   BIT(5)
#define	USB_BCC_AUDIO   0x01
	USB Defined Base Class Codes from https://www.usb.org/defined-class-codes.
#define	USB_BCC_CDC_CONTROL   0x02
#define	USB_BCC_HID   0x03
#define	USB_BCC_MASS_STORAGE   0x08
#define	USB_BCC_CDC_DATA   0x0A
#define	USB_BCC_VIDEO   0x0E
#define	USB_BCC_WIRELESS_CONTROLLER   0xE0
#define	USB_BCC_MISCELLANEOUS   0xEF
#define	USB_BCC_APPLICATION   0xFE
#define	USB_BCC_VENDOR   0xFF
#define	USB_SRN_1_1   0x0110
	USB Specification Release Numbers (bcdUSB Descriptor field)
#define	USB_SRN_2_0   0x0200
#define	USB_SRN_2_0_1   0x0201
#define	USB_SRN_2_1   0x0210
#define	USB_DEC_TO_BCD(dec)
#define	USB_BCD_DRN
	USB Device release number (bcdDevice Descriptor field)
#define	USB_GET_DESCRIPTOR_TYPE(wValue)
	Macro to obtain descriptor type from USB_SREQ_GET_DESCRIPTOR request.
#define	USB_GET_DESCRIPTOR_INDEX(wValue)
	Macro to obtain descriptor index from USB_SREQ_GET_DESCRIPTOR request.
#define	USB_CONTROL_EP_MPS   64U
	USB Control Endpoints maximum packet size (MPS)
#define	USB_EP_DIR_MASK   (uint8_t)BIT(7)
	USB endpoint direction mask.
#define	USB_EP_DIR_IN   (uint8_t)BIT(7)
	USB IN endpoint direction.
#define	USB_EP_DIR_OUT   0U
	USB OUT endpoint direction.
#define	USB_EP_GET_IDX(ep)
	Get endpoint index (number) from endpoint address.
#define	USB_EP_GET_DIR(ep)
	Get direction based on endpoint address.
#define	USB_EP_GET_ADDR(idx, dir)
	Get endpoint address from endpoint index and direction.
#define	USB_EP_DIR_IS_IN(ep)
	True if the endpoint is an IN endpoint.
#define	USB_EP_DIR_IS_OUT(ep)
	True if the endpoint is an OUT endpoint.
#define	USB_CONTROL_EP_OUT   (USB_EP_DIR_OUT | 0U)
	USB Control Endpoints OUT address.
#define	USB_CONTROL_EP_IN   (USB_EP_DIR_IN | 0U)
	USB Control Endpoints IN address.
#define	USB_EP_TRANSFER_TYPE_MASK   0x3U
	USB endpoint transfer type mask.
#define	USB_EP_TYPE_CONTROL   0U
	USB endpoint transfer type control.
#define	USB_EP_TYPE_ISO   1U
	USB endpoint transfer type isochronous.
#define	USB_EP_TYPE_BULK   2U
	USB endpoint transfer type bulk.
#define	USB_EP_TYPE_INTERRUPT   3U
	USB endpoint transfer type interrupt.
#define	USB_FS_INT_EP_INTERVAL(us)
	Calculate full speed interrupt endpoint bInterval from a value in microseconds.
#define	USB_HS_INT_EP_INTERVAL(us)
	Calculate high speed interrupt endpoint bInterval from a value in microseconds.
#define	USB_FS_ISO_EP_INTERVAL(us)
	Calculate high speed isochronous endpoint bInterval from a value in microseconds.
#define	USB_HS_ISO_EP_INTERVAL(us)
	Calculate high speed isochronous endpoint bInterval from a value in microseconds.
#define	USB_MPS_EP_SIZE(mps)
	Get endpoint size field from Max Packet Size value.
#define	USB_MPS_ADDITIONAL_TRANSACTIONS(mps)
	Get number of additional transactions per microframe from Max Packet Size value.
#define	USB_MPS_TO_TPL(mps)
	Calculate total payload length from Max Packet Size value.
#define	USB_TPL_TO_MPS(tpl)
	Calculate Max Packet Size value from total payload length.
#define	USB_TPL_ROUND_UP(tpl)
	Round up total payload length to next valid value.
#define	USB_TPL_IS_VALID(tpl)
	Determine whether total payload length value is valid according to USB 2.0.

Functions
static bool	usb_reqtype_is_to_host (const struct usb_setup_packet *setup)
	Check if request transfer direction is to host.
static bool	usb_reqtype_is_to_device (const struct usb_setup_packet *setup)
	Check if request transfer direction is to device.

Detailed Description

USB Chapter 9 structures and definitions.

This file contains the USB Chapter 9 structures definitions and follows, with few exceptions, the USB Specification 2.0.

Macro Definition Documentation

USB_BCC_APPLICATION

#define USB_BCC_APPLICATION   0xFE

USB_BCC_AUDIO

#define USB_BCC_AUDIO   0x01

USB Defined Base Class Codes from https://www.usb.org/defined-class-codes.

USB_BCC_CDC_CONTROL

#define USB_BCC_CDC_CONTROL   0x02

USB_BCC_CDC_DATA

#define USB_BCC_CDC_DATA   0x0A

USB_BCC_HID

#define USB_BCC_HID   0x03

USB_BCC_MASS_STORAGE

#define USB_BCC_MASS_STORAGE   0x08

USB_BCC_MISCELLANEOUS

#define USB_BCC_MISCELLANEOUS   0xEF

USB_BCC_VENDOR

#define USB_BCC_VENDOR   0xFF

USB_BCC_VIDEO

#define USB_BCC_VIDEO   0x0E

USB_BCC_WIRELESS_CONTROLLER

#define USB_BCC_WIRELESS_CONTROLLER   0xE0

USB_BCD_DRN

#define USB_BCD_DRN

Value:

                                 (USB_DEC_TO_BCD(KERNEL_VERSION_MAJOR) << 8 | \
                                 USB_DEC_TO_BCD(KERNEL_VERSION_MINOR))

USB Device release number (bcdDevice Descriptor field)

USB_CONTROL_EP_IN

#define USB_CONTROL_EP_IN   (USB_EP_DIR_IN | 0U)

USB Control Endpoints IN address.

USB_CONTROL_EP_MPS

#define USB_CONTROL_EP_MPS   64U

USB Control Endpoints maximum packet size (MPS)

This value may not be correct for devices operating at speeds other than high speed.

USB_CONTROL_EP_OUT

#define USB_CONTROL_EP_OUT   (USB_EP_DIR_OUT | 0U)

USB Control Endpoints OUT address.

USB_DEC_TO_BCD

#define USB_DEC_TO_BCD

(

dec

)

Value:

((((dec) / 10) << 4) | ((dec) % 10))

USB_DESC_BOS

#define USB_DESC_BOS   15

USB_DESC_CONFIGURATION

#define USB_DESC_CONFIGURATION   2

USB_DESC_CS_CONFIGURATION

#define USB_DESC_CS_CONFIGURATION   0x22

USB_DESC_CS_DEVICE

#define USB_DESC_CS_DEVICE   0x21

Class-Specific Descriptor Types as defined by USB Common Class Specification.

USB_DESC_CS_ENDPOINT

#define USB_DESC_CS_ENDPOINT   0x25

USB_DESC_CS_INTERFACE

#define USB_DESC_CS_INTERFACE   0x24

USB_DESC_CS_STRING

#define USB_DESC_CS_STRING   0x23

USB_DESC_DEBUG

#define USB_DESC_DEBUG   10

USB_DESC_DEVICE

#define USB_DESC_DEVICE   1

Descriptor Types defined in spec.

Table 9-5

USB_DESC_DEVICE_CAPABILITY

#define USB_DESC_DEVICE_CAPABILITY   16

USB_DESC_DEVICE_QUALIFIER

#define USB_DESC_DEVICE_QUALIFIER   6

USB_DESC_ENDPOINT

#define USB_DESC_ENDPOINT   5

USB_DESC_INTERFACE

#define USB_DESC_INTERFACE   4

USB_DESC_INTERFACE_ASSOC

#define USB_DESC_INTERFACE_ASSOC   11

USB_DESC_INTERFACE_POWER

#define USB_DESC_INTERFACE_POWER   8

USB_DESC_OTG

#define USB_DESC_OTG   9

Additional Descriptor Types defined in USB 3 spec.

Table 9-5

USB_DESC_OTHER_SPEED

#define USB_DESC_OTHER_SPEED   7

USB_DESC_STRING

#define USB_DESC_STRING   3

USB_EP_DIR_IN

#define USB_EP_DIR_IN   (uint8_t)BIT(7)

USB IN endpoint direction.

USB_EP_DIR_IS_IN

#define USB_EP_DIR_IS_IN

(

ep

)

Value:

(USB_EP_GET_DIR(ep) == USB_EP_DIR_IN)

True if the endpoint is an IN endpoint.

USB_EP_DIR_IS_OUT

#define USB_EP_DIR_IS_OUT

(

ep

)

Value:

(USB_EP_GET_DIR(ep) == USB_EP_DIR_OUT)

True if the endpoint is an OUT endpoint.

USB_EP_DIR_MASK

#define USB_EP_DIR_MASK   (uint8_t)BIT(7)

USB endpoint direction mask.

USB_EP_DIR_OUT

#define USB_EP_DIR_OUT   0U

USB OUT endpoint direction.

USB_EP_GET_ADDR

#define USB_EP_GET_ADDR	(		idx,
			dir )

Value:

((idx) | ((dir) & USB_EP_DIR_MASK))

Get endpoint address from endpoint index and direction.

USB_EP_GET_DIR

#define USB_EP_GET_DIR

(

ep

)

Value:

((ep) & USB_EP_DIR_MASK)

Get direction based on endpoint address.

USB_EP_GET_IDX

#define USB_EP_GET_IDX

(

ep

)

Value:

((ep) & ~USB_EP_DIR_MASK)

Get endpoint index (number) from endpoint address.

USB_EP_TRANSFER_TYPE_MASK

#define USB_EP_TRANSFER_TYPE_MASK   0x3U

USB endpoint transfer type mask.

USB_EP_TYPE_BULK

#define USB_EP_TYPE_BULK   2U

USB endpoint transfer type bulk.

USB_EP_TYPE_CONTROL

#define USB_EP_TYPE_CONTROL   0U

USB endpoint transfer type control.

USB_EP_TYPE_INTERRUPT

#define USB_EP_TYPE_INTERRUPT   3U

USB endpoint transfer type interrupt.

USB_EP_TYPE_ISO

#define USB_EP_TYPE_ISO   1U

USB endpoint transfer type isochronous.

USB_FS_INT_EP_INTERVAL

#define USB_FS_INT_EP_INTERVAL

(

us

)

Value:

CLAMP(((us) / 1000U), 1U, 255U)

Calculate full speed interrupt endpoint bInterval from a value in microseconds.

USB_FS_ISO_EP_INTERVAL

#define USB_FS_ISO_EP_INTERVAL

(

us

)

Value:

CLAMP(((us) / 1000U), 1U, 16U)

Calculate high speed isochronous endpoint bInterval from a value in microseconds.

USB_GET_DESCRIPTOR_INDEX

#define USB_GET_DESCRIPTOR_INDEX

(

wValue

)

Value:

((uint8_t)(wValue))

Macro to obtain descriptor index from USB_SREQ_GET_DESCRIPTOR request.

USB_GET_DESCRIPTOR_TYPE

#define USB_GET_DESCRIPTOR_TYPE

(

wValue

)

Value:

((uint8_t)((wValue) >> 8))

Macro to obtain descriptor type from USB_SREQ_GET_DESCRIPTOR request.

USB_GET_STATUS_REMOTE_WAKEUP

#define USB_GET_STATUS_REMOTE_WAKEUP   BIT(1)

USB_GET_STATUS_SELF_POWERED

#define USB_GET_STATUS_SELF_POWERED   BIT(0)

Bits used for GetStatus response defined in spec.

Figure 9-4

USB_HS_INT_EP_INTERVAL

#define USB_HS_INT_EP_INTERVAL

(

us

)

Value:

CLAMP((ilog2((us) / 125U) + 1U), 1U, 16U)

Calculate high speed interrupt endpoint bInterval from a value in microseconds.

USB_HS_ISO_EP_INTERVAL

#define USB_HS_ISO_EP_INTERVAL

(

us

)

Value:

CLAMP((ilog2((us) / 125U) + 1U), 1U, 16U)

Calculate high speed isochronous endpoint bInterval from a value in microseconds.

USB_MPS_ADDITIONAL_TRANSACTIONS

#define USB_MPS_ADDITIONAL_TRANSACTIONS

(

mps

)

Value:

(((mps) & 0x1800) >> 11)

Get number of additional transactions per microframe from Max Packet Size value.

USB_MPS_EP_SIZE

#define USB_MPS_EP_SIZE

(

mps

)

Value:

((mps) & BIT_MASK(11))

Get endpoint size field from Max Packet Size value.

USB_MPS_TO_TPL

#define USB_MPS_TO_TPL

(

mps

)

Value:

        ((1 + USB_MPS_ADDITIONAL_TRANSACTIONS(mps)) * USB_MPS_EP_SIZE(mps))

Calculate total payload length from Max Packet Size value.

USB_REQTYPE_DIR_TO_DEVICE

#define USB_REQTYPE_DIR_TO_DEVICE   0

USB Setup packet RequestType Direction values (from Table 9-2)

USB_REQTYPE_DIR_TO_HOST

#define USB_REQTYPE_DIR_TO_HOST   1

USB_REQTYPE_GET_DIR

#define USB_REQTYPE_GET_DIR

(

bmRequestType

)

Value:

(((bmRequestType) >> 7) & 0x01U)

Get data transfer direction from bmRequestType.

USB_REQTYPE_GET_RECIPIENT

#define USB_REQTYPE_GET_RECIPIENT

(

bmRequestType

)

Value:

((bmRequestType) & 0x1FU)

Get request recipient from bmRequestType.

USB_REQTYPE_GET_TYPE

#define USB_REQTYPE_GET_TYPE

(

bmRequestType

)

Value:

(((bmRequestType) >> 5) & 0x03U)

Get request type from bmRequestType.

USB_REQTYPE_RECIPIENT_DEVICE

#define USB_REQTYPE_RECIPIENT_DEVICE   0

USB Setup packet RequestType Recipient values (from Table 9-2)

USB_REQTYPE_RECIPIENT_ENDPOINT

#define USB_REQTYPE_RECIPIENT_ENDPOINT   2

USB_REQTYPE_RECIPIENT_INTERFACE

#define USB_REQTYPE_RECIPIENT_INTERFACE   1

USB_REQTYPE_RECIPIENT_OTHER

#define USB_REQTYPE_RECIPIENT_OTHER   3

USB_REQTYPE_TYPE_CLASS

#define USB_REQTYPE_TYPE_CLASS   1

USB_REQTYPE_TYPE_RESERVED

#define USB_REQTYPE_TYPE_RESERVED   3

USB_REQTYPE_TYPE_STANDARD

#define USB_REQTYPE_TYPE_STANDARD   0

USB Setup packet RequestType Type values (from Table 9-2)

USB_REQTYPE_TYPE_VENDOR

#define USB_REQTYPE_TYPE_VENDOR   2

USB_SCD_REMOTE_WAKEUP

#define USB_SCD_REMOTE_WAKEUP   BIT(5)

USB_SCD_RESERVED

#define USB_SCD_RESERVED   BIT(7)

USB Standard Configuration Descriptor Characteristics from Table 9-10.

USB_SCD_SELF_POWERED

#define USB_SCD_SELF_POWERED   BIT(6)

USB_SFS_ENDPOINT_HALT

#define USB_SFS_ENDPOINT_HALT   0x00

USB Standard Feature Selectors defined in spec.

Table 9-6

USB_SFS_REMOTE_WAKEUP

#define USB_SFS_REMOTE_WAKEUP   0x01

USB_SFS_TEST_MODE

#define USB_SFS_TEST_MODE   0x02

USB_SREQ_CLEAR_FEATURE

#define USB_SREQ_CLEAR_FEATURE   0x01

USB_SREQ_GET_CONFIGURATION

#define USB_SREQ_GET_CONFIGURATION   0x08

USB_SREQ_GET_DESCRIPTOR

#define USB_SREQ_GET_DESCRIPTOR   0x06

USB_SREQ_GET_INTERFACE

#define USB_SREQ_GET_INTERFACE   0x0A

USB_SREQ_GET_STATUS

#define USB_SREQ_GET_STATUS   0x00

USB Standard Request Codes defined in spec.

Table 9-4

USB_SREQ_SET_ADDRESS

#define USB_SREQ_SET_ADDRESS   0x05

USB_SREQ_SET_CONFIGURATION

#define USB_SREQ_SET_CONFIGURATION   0x09

USB_SREQ_SET_DESCRIPTOR

#define USB_SREQ_SET_DESCRIPTOR   0x07

USB_SREQ_SET_FEATURE

#define USB_SREQ_SET_FEATURE   0x03

USB_SREQ_SET_INTERFACE

#define USB_SREQ_SET_INTERFACE   0x0B

USB_SREQ_SYNCH_FRAME

#define USB_SREQ_SYNCH_FRAME   0x0C

USB_SRN_1_1

#define USB_SRN_1_1   0x0110

USB Specification Release Numbers (bcdUSB Descriptor field)

USB_SRN_2_0

#define USB_SRN_2_0   0x0200

USB_SRN_2_0_1

#define USB_SRN_2_0_1   0x0201

USB_SRN_2_1

#define USB_SRN_2_1   0x0210

USB_TPL_IS_VALID

#define USB_TPL_IS_VALID

(

tpl

)

Value:

        (((tpl) > 3072) ? false :                       \
         ((tpl) > 2048) ? ((tpl) % 3 == 0) :            \
         ((tpl) > 1024) ? ((tpl) % 2 == 0) :            \
         ((tpl) >= 0))

Determine whether total payload length value is valid according to USB 2.0.

USB_TPL_ROUND_UP

#define USB_TPL_ROUND_UP

(

tpl

)

Value:

        (((tpl) > 2048) ? ROUND_UP(tpl, 3) :            \
         ((tpl) > 1024) ? ROUND_UP(tpl, 2) :            \
         (tpl))

Round up total payload length to next valid value.

USB_TPL_TO_MPS

#define USB_TPL_TO_MPS

(

tpl

)

Value:

        (((tpl) > 2048) ? ((2 << 11) | ((tpl) / 3)) :   \
         ((tpl) > 1024) ? ((1 << 11) | ((tpl) / 2)) :   \
         (tpl))

Calculate Max Packet Size value from total payload length.

Function Documentation

usb_reqtype_is_to_device()

static bool usb_reqtype_is_to_device ( const struct usb_setup_packet * setup )

inlinestatic

Check if request transfer direction is to device.

Parameters

setup

Pointer to USB Setup packet

Returns

true If transfer direction is to device

usb_reqtype_is_to_host()

static bool usb_reqtype_is_to_host ( const struct usb_setup_packet * setup )

inlinestatic

Check if request transfer direction is to host.

Parameters

setup

Pointer to USB Setup packet

Returns

true If transfer direction is to host