Collaboration diagram for USB Driver:

Detailed Description

Generic USB Driver.

This module implements a generic USB (Universal Serial Bus) driver supporting device-mode operations.

Precondition:: In order to use the USB driver the HAL_USE_USB option must be enabled in halconf.h.

Driver State Machine

The driver implements a state machine internally, not all the driver functionalities can be used in any moment, any transition not explicitly shown in the following diagram has to be considered an error and shall be captured by an assertion (if enabled).

USB Operations

The USB driver is quite complex and USB is complex in itself, it is recommended to study the USB specification before trying to use the driver.

USB Implementation

The USB driver abstracts the inner details of the underlying USB hardware. The driver works asynchronously and communicates with the application using callbacks. The application is responsible of the descriptors and strings required by the USB device class to be implemented and of the handling of the specific messages sent over the endpoint zero. Standard messages are handled internally to the driver. The application can use hooks in order to handle custom messages or override the handling of the default handling of standard messages.

USB Endpoints

USB endpoints are the objects that the application uses to exchange data with the host. There are two kind of endpoints:

IN endpoints are used by the application to transmit data to the host.
OUT endpoints are used by the application to receive data from the host.

The driver invokes a callback after finishing an IN or OUT transaction. States diagram for OUT endpoints in transaction mode:

States diagram for IN endpoints in transaction mode:

USB Callbacks

The USB driver uses callbacks in order to interact with the application. There are several kinds of callbacks to be handled:

Driver events callback. As example errors, suspend event, reset event etc.
Messages Hook callback. This hook allows the application to implement handling of custom messages or to override the default handling of standard messages on endpoint zero.
Descriptor Requested callback. When the driver endpoint zero handler receives a GET DESCRIPTOR message and needs to send a descriptor to the host it queries the application using this callback.
Start of Frame callback. This callback is invoked each time a SOF packet is received.
Endpoint callbacks. Each endpoint informs the application about I/O conditions using those callbacks.

Data Structures
struct	USBDescriptor
	Type of an USB descriptor. More...
struct	stm32_usb_t
	USB registers block. More...
struct	stm32_usb_descriptor_t
	USB descriptor registers block. More...
struct	USBInEndpointState
	Type of an IN endpoint state structure. More...
struct	USBOutEndpointState
	Type of an OUT endpoint state structure. More...
struct	USBEndpointConfig
	Type of an USB endpoint configuration structure. More...
struct	USBConfig
	Type of an USB driver configuration structure. More...
struct	USBDriver
	Structure representing an USB driver. More...
Functions
void	usbInit (void)
	USB Driver initialization.
void	usbObjectInit (USBDriver *usbp)
	Initializes the standard part of a `USBDriver` structure.
void	usbStart (USBDriver usbp, const USBConfig config)
	Configures and activates the USB peripheral.
void	usbStop (USBDriver *usbp)
	Deactivates the USB peripheral.
void	usbInitEndpointI (USBDriver usbp, usbep_t ep, const USBEndpointConfig epcp)
	Enables an endpoint.
void	usbDisableEndpointsI (USBDriver *usbp)
	Disables all the active endpoints.
void	usbPrepareReceive (USBDriver usbp, usbep_t ep, uint8_t buf, size_t n)
	Prepares for a receive transaction on an OUT endpoint.
void	usbPrepareTransmit (USBDriver usbp, usbep_t ep, const uint8_t buf, size_t n)
	Prepares for a transmit transaction on an IN endpoint.
void	usbPrepareQueuedReceive (USBDriver usbp, usbep_t ep, InputQueue iqp, size_t n)
	Prepares for a receive transaction on an OUT endpoint.
void	usbPrepareQueuedTransmit (USBDriver usbp, usbep_t ep, OutputQueue oqp, size_t n)
	Prepares for a transmit transaction on an IN endpoint.
bool_t	usbStartReceiveI (USBDriver *usbp, usbep_t ep)
	Starts a receive transaction on an OUT endpoint.
bool_t	usbStartTransmitI (USBDriver *usbp, usbep_t ep)
	Starts a transmit transaction on an IN endpoint.
bool_t	usbStallReceiveI (USBDriver *usbp, usbep_t ep)
	Stalls an OUT endpoint.
bool_t	usbStallTransmitI (USBDriver *usbp, usbep_t ep)
	Stalls an IN endpoint.
void	_usb_reset (USBDriver *usbp)
	USB reset routine.
void	_usb_ep0setup (USBDriver *usbp, usbep_t ep)
	Default EP0 SETUP callback.
void	_usb_ep0in (USBDriver *usbp, usbep_t ep)
	Default EP0 IN callback.
void	_usb_ep0out (USBDriver *usbp, usbep_t ep)
	Default EP0 OUT callback.
	CH_IRQ_HANDLER (STM32_USB1_HP_HANDLER)
	USB high priority interrupt handler.
	CH_IRQ_HANDLER (STM32_USB1_LP_HANDLER)
	USB low priority interrupt handler.
void	usb_lld_init (void)
	Low level USB driver initialization.
void	usb_lld_start (USBDriver *usbp)
	Configures and activates the USB peripheral.
void	usb_lld_stop (USBDriver *usbp)
	Deactivates the USB peripheral.
void	usb_lld_reset (USBDriver *usbp)
	USB low level reset routine.
void	usb_lld_set_address (USBDriver *usbp)
	Sets the USB address.
void	usb_lld_init_endpoint (USBDriver *usbp, usbep_t ep)
	Enables an endpoint.
void	usb_lld_disable_endpoints (USBDriver *usbp)
	Disables all the active endpoints except the endpoint zero.
usbepstatus_t	usb_lld_get_status_out (USBDriver *usbp, usbep_t ep)
	Returns the status of an OUT endpoint.
usbepstatus_t	usb_lld_get_status_in (USBDriver *usbp, usbep_t ep)
	Returns the status of an IN endpoint.
void	usb_lld_read_setup (USBDriver usbp, usbep_t ep, uint8_t buf)
	Reads a setup packet from the dedicated packet buffer.
void	usb_lld_prepare_receive (USBDriver *usbp, usbep_t ep)
	Prepares for a receive operation.
void	usb_lld_prepare_transmit (USBDriver *usbp, usbep_t ep)
	Prepares for a transmit operation.
void	usb_lld_start_out (USBDriver *usbp, usbep_t ep)
	Starts a receive operation on an OUT endpoint.
void	usb_lld_start_in (USBDriver *usbp, usbep_t ep)
	Starts a transmit operation on an IN endpoint.
void	usb_lld_stall_out (USBDriver *usbp, usbep_t ep)
	Brings an OUT endpoint in the stalled state.
void	usb_lld_stall_in (USBDriver *usbp, usbep_t ep)
	Brings an IN endpoint in the stalled state.
void	usb_lld_clear_out (USBDriver *usbp, usbep_t ep)
	Brings an OUT endpoint in the active state.
void	usb_lld_clear_in (USBDriver *usbp, usbep_t ep)
	Brings an IN endpoint in the active state.
Variables
USBDriver	USBD1
	USB1 driver identifier.
Helper macros for USB descriptors
#define	USB_DESC_INDEX(i) ((uint8_t)(i))
	Helper macro for index values into descriptor strings.
#define	USB_DESC_BYTE(b) ((uint8_t)(b))
	Helper macro for byte values into descriptor strings.
#define	USB_DESC_WORD(w)
	Helper macro for word values into descriptor strings.
#define	USB_DESC_BCD(bcd)
	Helper macro for BCD values into descriptor strings.
#define	USB_DESC_DEVICE(bcdUSB, bDeviceClass, bDeviceSubClass,bDeviceProtocol, bMaxPacketSize, idVendor,idProduct, bcdDevice, iManufacturer,iProduct, iSerialNumber, bNumConfigurations)
	Device Descriptor helper macro.
#define	USB_DESC_CONFIGURATION(wTotalLength, bNumInterfaces,bConfigurationValue, iConfiguration,bmAttributes, bMaxPower)
	Configuration Descriptor helper macro.
#define	USB_DESC_INTERFACE(bInterfaceNumber, bAlternateSetting,bNumEndpoints, bInterfaceClass,bInterfaceSubClass, bInterfaceProtocol,iInterface)
	Interface Descriptor helper macro.
#define	USB_DESC_INTERFACE_ASSOCIATION(bFirstInterface,bInterfaceCount, bFunctionClass,bFunctionSubClass, bFunctionProcotol,iInterface)
	Interface Association Descriptor helper macro.
#define	USB_DESC_ENDPOINT(bEndpointAddress, bmAttributes, wMaxPacketSize,bInterval)
	Endpoint Descriptor helper macro.
Endpoint types and settings
#define	USB_EP_MODE_TYPE 0x0003
#define	USB_EP_MODE_TYPE_CTRL 0x0000
#define	USB_EP_MODE_TYPE_ISOC 0x0001
#define	USB_EP_MODE_TYPE_BULK 0x0002
#define	USB_EP_MODE_TYPE_INTR 0x0003
#define	USB_EP_MODE_LINEAR_BUFFER 0x0000
#define	USB_EP_MODE_QUEUE_BUFFER 0x0010
Macro Functions
#define	usbGetDriverStateI(usbp) ((usbp)->state)
	Returns the driver state.
#define	usbFetchWord(p) ((uint16_t)(p) \| ((uint16_t)((p) + 1) << 8))
	Fetches a 16 bits word value from an USB message.
#define	usbConnectBus(usbp) usb_lld_connect_bus(usbp)
	Connects the USB device.
#define	usbDisconnectBus(usbp) usb_lld_disconnect_bus(usbp)
	Disconnect the USB device.
#define	usbGetFrameNumber(usbp) usb_lld_get_frame_number(usbp)
	Returns the current frame number.
#define	usbGetTransmitStatusI(usbp, ep) ((usbp)->transmitting & (1 << (ep)))
	Returns the status of an IN endpoint.
#define	usbGetReceiveStatusI(usbp, ep) ((usbp)->receiving & (1 << (ep)))
	Returns the status of an OUT endpoint.
#define	usbGetReceiveTransactionSizeI(usbp, ep) usb_lld_get_transaction_size(usbp, ep)
	Returns the exact size of a receive transaction.
#define	usbSetupTransfer(usbp, buf, n, endcb)
	Request transfer setup.
#define	usbReadSetup(usbp, ep, buf) usb_lld_read_setup(usbp, ep, buf)
	Reads a setup packet from the dedicated packet buffer.
Low Level driver helper macros
#define	_usb_isr_invoke_event_cb(usbp, evt)
	Common ISR code, usb event callback.
#define	_usb_isr_invoke_sof_cb(usbp)
	Common ISR code, SOF callback.
#define	_usb_isr_invoke_setup_cb(usbp, ep)
	Common ISR code, setup packet callback.
#define	_usb_isr_invoke_in_cb(usbp, ep)
	Common ISR code, IN endpoint callback.
#define	_usb_isr_invoke_out_cb(usbp, ep)
	Common ISR code, OUT endpoint event.
Register aliases
#define	RXADDR1 TXADDR0
#define	TXADDR1 RXADDR0
Defines
#define	USB_ENDOPOINTS_NUMBER 7
	Number of the available endpoints.
#define	STM32_USB_BASE (APB1PERIPH_BASE + 0x5C00)
	USB registers block numeric address.
#define	STM32_USBRAM_BASE (APB1PERIPH_BASE + 0x6000)
	USB RAM numeric address.
#define	STM32_USB ((stm32_usb_t *)STM32_USB_BASE)
	Pointer to the USB registers block.
#define	STM32_USBRAM ((uint32_t *)STM32_USBRAM_BASE)
	Pointer to the USB RAM.
#define	USB_PMA_SIZE 512
	Size of the dedicated packet memory.
#define	EPR_TOGGLE_MASK
	Mask of all the toggling bits in the EPR register.
#define	USB_GET_DESCRIPTOR(ep)
	Returns an endpoint descriptor pointer.
#define	USB_ADDR2PTR(addr) ((uint32_t )((addr) 2 + STM32_USBRAM_BASE))
	Converts from a PMA address to a physical address.
#define	USB_MAX_ENDPOINTS USB_ENDOPOINTS_NUMBER
	Maximum endpoint address.
#define	USB_SET_ADDRESS_MODE USB_LATE_SET_ADDRESS
	This device requires the address change after the status packet.
#define	STM32_USB_USE_USB1 FALSE
	USB1 driver enable switch.
#define	STM32_USB_LOW_POWER_ON_SUSPEND FALSE
	Enables the USB device low power mode on suspend.
#define	STM32_USB_USB1_HP_IRQ_PRIORITY 13
	USB1 interrupt priority level setting.
#define	STM32_USB_USB1_LP_IRQ_PRIORITY 14
	USB1 interrupt priority level setting.
#define	usb_lld_get_frame_number(usbp) (STM32_USB->FNR & FNR_FN_MASK)
	Returns the current frame number.
#define	usb_lld_get_transaction_size(usbp, ep) ((usbp)->epc[ep]->out_state->rxcnt)
	Returns the exact size of a receive transaction.
#define	usb_lld_get_packet_size(usbp, ep) ((size_t)USB_GET_DESCRIPTOR(ep)->RXCOUNT & RXCOUNT_COUNT_MASK)
	Returns the exact size of a received packet.
Typedefs
typedef struct USBDriver	USBDriver
	Type of a structure representing an USB driver.
typedef uint8_t	usbep_t
	Type of an endpoint identifier.
typedef void(*	usbcallback_t )(USBDriver *usbp)
	Type of an USB generic notification callback.
typedef void(*	usbepcallback_t )(USBDriver *usbp, usbep_t ep)
	Type of an USB endpoint callback.
typedef void(*	usbeventcb_t )(USBDriver *usbp, usbevent_t event)
	Type of an USB event notification callback.
typedef bool_t(*	usbreqhandler_t )(USBDriver *usbp)
	Type of a requests handler callback.
typedef const USBDescriptor (	usbgetdescriptor_t )(USBDriver *usbp, uint8_t dtype, uint8_t dindex, uint16_t lang)
	Type of an USB descriptor-retrieving callback.
Enumerations
enum	usbstate_t { USB_UNINIT = 0, USB_STOP = 1, USB_READY = 2, USB_SELECTED = 3, USB_ACTIVE = 4 }
	Type of a driver state machine possible states. More...
enum	usbepstatus_t { EP_STATUS_DISABLED = 0, EP_STATUS_STALLED = 1, EP_STATUS_ACTIVE = 2 }
	Type of an endpoint status. More...
enum	usbep0state_t { USB_EP0_WAITING_SETUP, USB_EP0_TX, USB_EP0_WAITING_STS, USB_EP0_RX, USB_EP0_SENDING_STS, USB_EP0_ERROR }
	Type of an endpoint zero state machine states. More...
enum	usbevent_t { USB_EVENT_RESET = 0, USB_EVENT_ADDRESS = 1, USB_EVENT_CONFIGURED = 2, USB_EVENT_SUSPEND = 3, USB_EVENT_WAKEUP = 4, USB_EVENT_STALLED = 5 }
	Type of an enumeration of the possible USB events. More...

Function Documentation

void usbInit ( void )

USB Driver initialization.

Note:: This function is implicitly invoked by halInit(), there is no need to explicitly initialize the driver.

Function Class:: Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 228 of file usb.c.

References usb_lld_init().

Referenced by halInit().

Here is the call graph for this function:

void usbObjectInit ( USBDriver * usbp )

Initializes the standard part of a USBDriver structure.

Parameters:

[out] usbp pointer to the USBDriver object

Function Class:: Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 240 of file usb.c.

References USBDriver::config, USBDriver::param, USBDriver::receiving, USBDriver::state, USBDriver::transmitting, and USB_STOP.

Referenced by usb_lld_init().

void usbStart	(	USBDriver *	usbp,
		const USBConfig *	config
	)

Configures and activates the USB peripheral.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	config	pointer to the `USBConfig` object

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 257 of file usb.c.

References USBDriver::config, USBDriver::epc, USBDriver::state, usb_lld_start(), USB_MAX_ENDPOINTS, USB_READY, and USB_STOP.

Here is the call graph for this function:

void usbStop ( USBDriver * usbp )

Deactivates the USB peripheral.

Parameters:

[in] usbp pointer to the USBDriver object

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 280 of file usb.c.

References USBDriver::state, usb_lld_stop(), USB_READY, and USB_STOP.

Here is the call graph for this function:

void usbInitEndpointI	(	USBDriver *	usbp,
		usbep_t	ep,
		const USBEndpointConfig *	epcp
	)

Enables an endpoint.

This function enables an endpoint, both IN and/or OUT directions depending on the configuration structure.

Note:: This function must be invoked in response of a SET_CONFIGURATION or SET_INTERFACE message.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number
[in]	epcp	the endpoint configuration

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 305 of file usb.c.

References USBDriver::epc, USBEndpointConfig::in_state, USBEndpointConfig::out_state, USBDriver::state, USB_ACTIVE, and usb_lld_init_endpoint().

Here is the call graph for this function:

void usbDisableEndpointsI ( USBDriver * usbp )

Disables all the active endpoints.

This function disables all the active endpoints except the endpoint zero.

Note:: This function must be invoked in response of a SET_CONFIGURATION message with configuration number zero.

Parameters:

[in] usbp pointer to the USBDriver object

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 338 of file usb.c.

References USBDriver::epc, USBDriver::receiving, USBDriver::state, USBDriver::transmitting, usb_lld_disable_endpoints(), USB_MAX_ENDPOINTS, and USB_SELECTED.

Here is the call graph for this function:

void usbPrepareReceive	(	USBDriver *	usbp,
		usbep_t	ep,
		uint8_t *	buf,
		size_t	n
	)

Prepares for a receive transaction on an OUT endpoint.

Postcondition:: The endpoint is ready for usbStartReceiveI().

Note:: This function can be called both in ISR and thread context.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number
[out]	buf	buffer where to copy the received data
[in]	n	transaction size

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 367 of file usb.c.

References USBDriver::epc, USBEndpointConfig::out_state, USBOutEndpointState::rxcnt, USBOutEndpointState::rxqueued, USBOutEndpointState::rxsize, and usb_lld_prepare_receive().

Referenced by _usb_ep0in(), and _usb_ep0setup().

Here is the call graph for this function:

void usbPrepareTransmit	(	USBDriver *	usbp,
		usbep_t	ep,
		const uint8_t *	buf,
		size_t	n
	)

Prepares for a transmit transaction on an IN endpoint.

Postcondition:: The endpoint is ready for usbStartTransmitI().

Note:: This function can be called both in ISR and thread context.; The queue must contain at least the amount of data specified as transaction size.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number
[in]	buf	buffer where to fetch the data to be transmitted
[in]	n	transaction size

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 392 of file usb.c.

References USBDriver::epc, USBEndpointConfig::in_state, USBInEndpointState::txcnt, USBInEndpointState::txqueued, USBInEndpointState::txsize, and usb_lld_prepare_transmit().

Referenced by _usb_ep0in(), _usb_ep0out(), and _usb_ep0setup().

Here is the call graph for this function:

void usbPrepareQueuedReceive	(	USBDriver *	usbp,
		usbep_t	ep,
		InputQueue *	iqp,
		size_t	n
	)

Prepares for a receive transaction on an OUT endpoint.

Postcondition:: The endpoint is ready for usbStartReceiveI().

Note:: This function can be called both in ISR and thread context.; The queue must have enough free space to accommodate the specified transaction size rounded to the next packet size boundary. For example if the transaction size is 1 and the packet size is 64 then the queue must have space for at least 64 bytes.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number
[in]	iqp	input queue to be filled with incoming data
[in]	n	transaction size

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 421 of file usb.c.

References USBDriver::epc, USBEndpointConfig::out_state, USBOutEndpointState::rxcnt, USBOutEndpointState::rxqueued, USBOutEndpointState::rxsize, and usb_lld_prepare_receive().

Here is the call graph for this function:

void usbPrepareQueuedTransmit	(	USBDriver *	usbp,
		usbep_t	ep,
		OutputQueue *	oqp,
		size_t	n
	)

Prepares for a transmit transaction on an IN endpoint.

Postcondition:: The endpoint is ready for usbStartTransmitI().

Note:: This function can be called both in ISR and thread context.; The transmit transaction size is equal to the data contained in the queue.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number
[in]	oqp	output queue to be fetched for outgoing data
[in]	n	transaction size

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 447 of file usb.c.

References USBDriver::epc, USBEndpointConfig::in_state, USBInEndpointState::txcnt, USBInEndpointState::txqueued, USBInEndpointState::txsize, and usb_lld_prepare_transmit().

Here is the call graph for this function:

bool_t usbStartReceiveI	(	USBDriver *	usbp,
		usbep_t	ep
	)

Starts a receive transaction on an OUT endpoint.

Postcondition:: The endpoint callback is invoked when the transfer has been completed.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Returns:: The operation status.

Return values:

FALSE	Operation started successfully.
TRUE	Endpoint busy, operation not started.

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 473 of file usb.c.

References USBDriver::receiving, usb_lld_start_out(), and usbGetReceiveStatusI.

Referenced by _usb_ep0in(), and _usb_ep0setup().

Here is the call graph for this function:

bool_t usbStartTransmitI	(	USBDriver *	usbp,
		usbep_t	ep
	)

Starts a transmit transaction on an IN endpoint.

Postcondition:: The endpoint callback is invoked when the transfer has been completed.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Returns:: The operation status.

Return values:

FALSE	Operation started successfully.
TRUE	Endpoint busy, operation not started.

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 500 of file usb.c.

References USBDriver::transmitting, usb_lld_start_in(), and usbGetTransmitStatusI.

Referenced by _usb_ep0in(), _usb_ep0out(), and _usb_ep0setup().

Here is the call graph for this function:

bool_t usbStallReceiveI	(	USBDriver *	usbp,
		usbep_t	ep
	)

Stalls an OUT endpoint.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Returns:: The operation status.

Return values:

FALSE	Endpoint stalled.
TRUE	Endpoint busy, not stalled.

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 525 of file usb.c.

References usb_lld_stall_out(), and usbGetReceiveStatusI.

Here is the call graph for this function:

bool_t usbStallTransmitI	(	USBDriver *	usbp,
		usbep_t	ep
	)

Stalls an IN endpoint.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Returns:: The operation status.

Return values:

FALSE	Endpoint stalled.
TRUE	Endpoint busy, not stalled.

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 549 of file usb.c.

References usb_lld_stall_in(), and usbGetTransmitStatusI.

Here is the call graph for this function:

void _usb_reset ( USBDriver * usbp )

USB reset routine.

This function must be invoked when an USB bus reset condition is detected.

Parameters:

[in] usbp pointer to the USBDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 570 of file usb.c.

References USBDriver::address, USBDriver::configuration, USBDriver::ep0state, USBDriver::epc, USBDriver::receiving, USBDriver::state, USBDriver::status, USBDriver::transmitting, USB_EP0_WAITING_SETUP, usb_lld_reset(), USB_MAX_ENDPOINTS, and USB_READY.

Referenced by CH_IRQ_HANDLER(), and usb_lld_start().

Here is the call graph for this function:

void _usb_ep0setup	(	USBDriver *	usbp,
		usbep_t	ep
	)

Default EP0 SETUP callback.

This function is used by the low level driver as default handler for EP0 SETUP events.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number, always zero

Function Class:: Not an API, this function is for internal use only.

Definition at line 601 of file usb.c.

References _usb_isr_invoke_event_cb, USBDriver::config, USBDriver::ep0n, USBDriver::ep0next, USBDriver::ep0state, USBConfig::requests_hook_cb, USBDriver::setup, USB_EP0_ERROR, USB_EP0_RX, USB_EP0_SENDING_STS, USB_EP0_TX, USB_EP0_WAITING_SETUP, USB_EP0_WAITING_STS, USB_EVENT_STALLED, usb_lld_stall_in(), usb_lld_stall_out(), usbFetchWord, usbPrepareReceive(), usbPrepareTransmit(), usbReadSetup, usbStartReceiveI(), and usbStartTransmitI().

Here is the call graph for this function:

void _usb_ep0in	(	USBDriver *	usbp,
		usbep_t	ep
	)

Default EP0 IN callback.

This function is used by the low level driver as default handler for EP0 IN events.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number, always zero

Function Class:: Not an API, this function is for internal use only.

Definition at line 685 of file usb.c.

References _usb_isr_invoke_event_cb, USBDriver::ep0endcb, USBDriver::ep0n, USBDriver::ep0state, USBDriver::epc, USBEndpointConfig::in_maxsize, USBDriver::setup, USB_EP0_ERROR, USB_EP0_SENDING_STS, USB_EP0_TX, USB_EP0_WAITING_SETUP, USB_EP0_WAITING_STS, USB_EVENT_STALLED, usb_lld_stall_in(), usb_lld_stall_out(), usbFetchWord, usbPrepareReceive(), usbPrepareTransmit(), usbStartReceiveI(), and usbStartTransmitI().

Here is the call graph for this function:

void _usb_ep0out	(	USBDriver *	usbp,
		usbep_t	ep
	)

Default EP0 OUT callback.

This function is used by the low level driver as default handler for EP0 OUT events.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number, always zero

Function Class:: Not an API, this function is for internal use only.

Definition at line 739 of file usb.c.

References _usb_isr_invoke_event_cb, USBDriver::ep0endcb, USBDriver::ep0state, USB_EP0_ERROR, USB_EP0_RX, USB_EP0_SENDING_STS, USB_EP0_WAITING_SETUP, USB_EP0_WAITING_STS, USB_EVENT_STALLED, usb_lld_stall_in(), usb_lld_stall_out(), usbGetReceiveTransactionSizeI, usbPrepareTransmit(), and usbStartTransmitI().

Here is the call graph for this function:

CH_IRQ_HANDLER ( STM32_USB1_HP_HANDLER )

USB high priority interrupt handler.

Function Class:: Interrupt handler, this function should not be directly invoked.

Definition at line 276 of file usb_lld.c.

CH_IRQ_HANDLER ( STM32_USB1_LP_HANDLER )

USB low priority interrupt handler.

Function Class:: Interrupt handler, this function should not be directly invoked.

Definition at line 291 of file usb_lld.c.

References _usb_isr_invoke_event_cb, _usb_isr_invoke_in_cb, _usb_isr_invoke_out_cb, _usb_isr_invoke_setup_cb, _usb_isr_invoke_sof_cb, _usb_reset(), USBDriver::epc, USBEndpointConfig::in_maxsize, USBEndpointConfig::in_state, USBEndpointConfig::out_state, USBOutEndpointState::rxcnt, stm32_usb_descriptor_t::RXCOUNT0, USBOutEndpointState::rxpkts, USBOutEndpointState::rxqueued, USBOutEndpointState::rxsize, STM32_USB, USBInEndpointState::txcnt, USBInEndpointState::txqueued, USBInEndpointState::txsize, USB_EVENT_RESET, USB_EVENT_SUSPEND, USB_EVENT_WAKEUP, USB_GET_DESCRIPTOR, usb_lld_start_in(), and USBD1.

Here is the call graph for this function:

void usb_lld_init ( void )

Low level USB driver initialization.

Function Class:: Not an API, this function is for internal use only.

Definition at line 433 of file usb_lld.c.

References usbObjectInit().

Referenced by usbInit().

Here is the call graph for this function:

void usb_lld_start ( USBDriver * usbp )

Configures and activates the USB peripheral.

Parameters:

[in] usbp pointer to the USBDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 446 of file usb_lld.c.

References _usb_reset(), rccEnableUSB, USBDriver::state, STM32_USB, STM32_USB_USB1_HP_IRQ_PRIORITY, STM32_USB_USB1_LP_IRQ_PRIORITY, and USB_STOP.

Referenced by usbStart().

Here is the call graph for this function:

void usb_lld_stop ( USBDriver * usbp )

Deactivates the USB peripheral.

Parameters:

[in] usbp pointer to the USBDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 479 of file usb_lld.c.

References rccDisableUSB, USBDriver::state, STM32_USB, and USB_STOP.

Referenced by usbStop().

void usb_lld_reset ( USBDriver * usbp )

USB low level reset routine.

Parameters:

[in] usbp pointer to the USBDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 501 of file usb_lld.c.

References USBDriver::config, USBDriver::epc, USBConfig::sof_cb, STM32_USB, and usb_lld_init_endpoint().

Referenced by _usb_reset().

Here is the call graph for this function:

void usb_lld_set_address ( USBDriver * usbp )

Sets the USB address.

Parameters:

[in] usbp pointer to the USBDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 531 of file usb_lld.c.

References USBDriver::address, and STM32_USB.

void usb_lld_init_endpoint	(	USBDriver *	usbp,
		usbep_t	ep
	)

Enables an endpoint.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Function Class:: Not an API, this function is for internal use only.

Definition at line 544 of file usb_lld.c.

References USBEndpointConfig::ep_mode, USBDriver::epc, USBEndpointConfig::in_cb, USBEndpointConfig::in_maxsize, USBEndpointConfig::out_cb, USBEndpointConfig::out_maxsize, stm32_usb_descriptor_t::RXADDR0, stm32_usb_descriptor_t::RXCOUNT0, stm32_usb_descriptor_t::TXADDR0, stm32_usb_descriptor_t::TXCOUNT0, USB_EP_MODE_TYPE, USB_EP_MODE_TYPE_BULK, USB_EP_MODE_TYPE_INTR, USB_EP_MODE_TYPE_ISOC, and USB_GET_DESCRIPTOR.

Referenced by usb_lld_reset(), and usbInitEndpointI().

void usb_lld_disable_endpoints ( USBDriver * usbp )

Disables all the active endpoints except the endpoint zero.

Parameters:

[in] usbp pointer to the USBDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 596 of file usb_lld.c.

References USB_ENDOPOINTS_NUMBER.

Referenced by usbDisableEndpointsI().

usbepstatus_t usb_lld_get_status_out	(	USBDriver *	usbp,
		usbep_t	ep
	)

Returns the status of an OUT endpoint.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Returns:: The endpoint status.

Return values:

EP_STATUS_DISABLED	The endpoint is not active.
EP_STATUS_STALLED	The endpoint is stalled.
EP_STATUS_ACTIVE	The endpoint is active.

Function Class:: Not an API, this function is for internal use only.

Definition at line 621 of file usb_lld.c.

References EP_STATUS_ACTIVE, EP_STATUS_DISABLED, EP_STATUS_STALLED, and STM32_USB.

usbepstatus_t usb_lld_get_status_in	(	USBDriver *	usbp,
		usbep_t	ep
	)

Returns the status of an IN endpoint.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Returns:: The endpoint status.

Return values:

EP_STATUS_DISABLED	The endpoint is not active.
EP_STATUS_STALLED	The endpoint is stalled.
EP_STATUS_ACTIVE	The endpoint is active.

Function Class:: Not an API, this function is for internal use only.

Definition at line 646 of file usb_lld.c.

References EP_STATUS_ACTIVE, EP_STATUS_DISABLED, EP_STATUS_STALLED, and STM32_USB.

void usb_lld_read_setup	(	USBDriver *	usbp,
		usbep_t	ep,
		uint8_t *	buf
	)

Reads a setup packet from the dedicated packet buffer.

This function must be invoked in the context of the setup_cb callback in order to read the received setup packet.

Precondition:: In order to use this function the endpoint must have been initialized as a control endpoint.

Postcondition:: The endpoint is ready to accept another packet.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number
[out]	buf	buffer where to copy the packet data

Function Class:: Not an API, this function is for internal use only.

Definition at line 673 of file usb_lld.c.

References stm32_usb_descriptor_t::RXADDR0, USB_ADDR2PTR, and USB_GET_DESCRIPTOR.

void usb_lld_prepare_receive	(	USBDriver *	usbp,
		usbep_t	ep
	)

Prepares for a receive operation.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Function Class:: Not an API, this function is for internal use only.

Definition at line 695 of file usb_lld.c.

References USBDriver::epc, USBEndpointConfig::out_maxsize, USBEndpointConfig::out_state, USBOutEndpointState::rxpkts, and USBOutEndpointState::rxsize.

Referenced by usbPrepareQueuedReceive(), and usbPrepareReceive().

void usb_lld_prepare_transmit	(	USBDriver *	usbp,
		usbep_t	ep
	)

Prepares for a transmit operation.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Function Class:: Not an API, this function is for internal use only.

Definition at line 714 of file usb_lld.c.

References USBDriver::epc, USBEndpointConfig::in_maxsize, USBEndpointConfig::in_state, USBInEndpointState::txqueued, USBInEndpointState::txsize, and USB_GET_DESCRIPTOR.

Referenced by usbPrepareQueuedTransmit(), and usbPrepareTransmit().

void usb_lld_start_out	(	USBDriver *	usbp,
		usbep_t	ep
	)

Starts a receive operation on an OUT endpoint.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Function Class:: Not an API, this function is for internal use only.

Definition at line 739 of file usb_lld.c.

Referenced by usbStartReceiveI().

void usb_lld_start_in	(	USBDriver *	usbp,
		usbep_t	ep
	)

Starts a transmit operation on an IN endpoint.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Function Class:: Not an API, this function is for internal use only.

Definition at line 754 of file usb_lld.c.

Referenced by CH_IRQ_HANDLER(), and usbStartTransmitI().

void usb_lld_stall_out	(	USBDriver *	usbp,
		usbep_t	ep
	)

Brings an OUT endpoint in the stalled state.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Function Class:: Not an API, this function is for internal use only.

Definition at line 769 of file usb_lld.c.

Referenced by _usb_ep0in(), _usb_ep0out(), _usb_ep0setup(), and usbStallReceiveI().

void usb_lld_stall_in	(	USBDriver *	usbp,
		usbep_t	ep
	)

Brings an IN endpoint in the stalled state.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Function Class:: Not an API, this function is for internal use only.

Definition at line 784 of file usb_lld.c.

Referenced by _usb_ep0in(), _usb_ep0out(), _usb_ep0setup(), and usbStallTransmitI().

void usb_lld_clear_out	(	USBDriver *	usbp,
		usbep_t	ep
	)

Brings an OUT endpoint in the active state.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Function Class:: Not an API, this function is for internal use only.

Definition at line 799 of file usb_lld.c.

References STM32_USB.

void usb_lld_clear_in	(	USBDriver *	usbp,
		usbep_t	ep
	)

Brings an IN endpoint in the active state.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Function Class:: Not an API, this function is for internal use only.

Definition at line 817 of file usb_lld.c.

References STM32_USB.

Variable Documentation

USBDriver USBD1

USB1 driver identifier.

Definition at line 44 of file usb_lld.c.

Referenced by CH_IRQ_HANDLER().

USBInEndpointState { ... } in

IN EP0 state.

Definition at line 60 of file usb_lld.c.

USBOutEndpointState { ... } out

OUT EP0 state.

Definition at line 64 of file usb_lld.c.

Define Documentation

#define USB_DESC_INDEX ( i ) ((uint8_t)(i))

Helper macro for index values into descriptor strings.

Definition at line 88 of file usb.h.

#define USB_DESC_BYTE ( b ) ((uint8_t)(b))

Helper macro for byte values into descriptor strings.

Definition at line 93 of file usb.h.

#define USB_DESC_WORD ( w )

Value:

(uint8_t)((w) & 255),                                                     \
  (uint8_t)(((w) >> 8) & 255)

Helper macro for word values into descriptor strings.

Definition at line 98 of file usb.h.

#define USB_DESC_BCD ( bcd )

Value:

(uint8_t)((bcd) & 255),                                                   \
  (uint8_t)(((bcd) >> 8) & 255)

Helper macro for BCD values into descriptor strings.

Definition at line 105 of file usb.h.

#define USB_DESC_DEVICE	(	bcdUSB,
		bDeviceClass,
		bDeviceSubClass,
		bDeviceProtocol,
		bMaxPacketSize,
		idVendor,
		idProduct,
		bcdDevice,
		iManufacturer,
		iProduct,
		iSerialNumber,
		bNumConfigurations
	)

Value:

USB_DESC_BYTE(18),                                                        \
  USB_DESC_BYTE(USB_DESCRIPTOR_DEVICE),                                     \
  USB_DESC_BCD(bcdUSB),                                                     \
  USB_DESC_BYTE(bDeviceClass),                                              \
  USB_DESC_BYTE(bDeviceSubClass),                                           \
  USB_DESC_BYTE(bDeviceProtocol),                                           \
  USB_DESC_BYTE(bMaxPacketSize),                                            \
  USB_DESC_WORD(idVendor),                                                  \
  USB_DESC_WORD(idProduct),                                                 \
  USB_DESC_BCD(bcdDevice),                                                  \
  USB_DESC_INDEX(iManufacturer),                                            \
  USB_DESC_INDEX(iProduct),                                                 \
  USB_DESC_INDEX(iSerialNumber),                                            \
  USB_DESC_BYTE(bNumConfigurations)

Device Descriptor helper macro.

Definition at line 112 of file usb.h.

#define USB_DESC_CONFIGURATION	(	wTotalLength,
		bNumInterfaces,
		bConfigurationValue,
		iConfiguration,
		bmAttributes,
		bMaxPower
	)

Value:

USB_DESC_BYTE(9),                                                         \
  USB_DESC_BYTE(USB_DESCRIPTOR_CONFIGURATION),                              \
  USB_DESC_WORD(wTotalLength),                                              \
  USB_DESC_BYTE(bNumInterfaces),                                            \
  USB_DESC_BYTE(bConfigurationValue),                                       \
  USB_DESC_INDEX(iConfiguration),                                           \
  USB_DESC_BYTE(bmAttributes),                                              \
  USB_DESC_BYTE(bMaxPower)

Configuration Descriptor helper macro.

Definition at line 134 of file usb.h.

#define USB_DESC_INTERFACE	(	bInterfaceNumber,
		bAlternateSetting,
		bNumEndpoints,
		bInterfaceClass,
		bInterfaceSubClass,
		bInterfaceProtocol,
		iInterface
	)

Value:

USB_DESC_BYTE(9),                                                         \
  USB_DESC_BYTE(USB_DESCRIPTOR_INTERFACE),                                  \
  USB_DESC_BYTE(bInterfaceNumber),                                          \
  USB_DESC_BYTE(bAlternateSetting),                                         \
  USB_DESC_BYTE(bNumEndpoints),                                             \
  USB_DESC_BYTE(bInterfaceClass),                                           \
  USB_DESC_BYTE(bInterfaceSubClass),                                        \
  USB_DESC_BYTE(bInterfaceProtocol),                                        \
  USB_DESC_INDEX(iInterface)

Interface Descriptor helper macro.

Definition at line 149 of file usb.h.

#define USB_DESC_INTERFACE_ASSOCIATION	(	bFirstInterface,
		bInterfaceCount,
		bFunctionClass,
		bFunctionSubClass,
		bFunctionProcotol,
		iInterface
	)

Value:

USB_DESC_BYTE(8),                                                         \
  USB_DESC_BYTE(USB_DESCRIPTOR_INTERFACE_ASSOCIATION),                      \
  USB_DESC_BYTE(bFirstInterface),                                           \
  USB_DESC_BYTE(bInterfaceCount),                                           \
  USB_DESC_BYTE(bFunctionClass),                                            \
  USB_DESC_BYTE(bFunctionSubClass),                                         \
  USB_DESC_BYTE(bFunctionProcotol),                                         \
  USB_DESC_INDEX(iInterface)

Interface Association Descriptor helper macro.

Definition at line 166 of file usb.h.

#define USB_DESC_ENDPOINT	(	bEndpointAddress,
		bmAttributes,
		wMaxPacketSize,
		bInterval
	)

Value:

USB_DESC_BYTE(7),                                                         \
  USB_DESC_BYTE(USB_DESCRIPTOR_ENDPOINT),                                   \
  USB_DESC_BYTE(bEndpointAddress),                                          \
  USB_DESC_BYTE(bmAttributes),                                              \
  USB_DESC_WORD(wMaxPacketSize),                                            \
  USB_DESC_BYTE(bInterval)

Endpoint Descriptor helper macro.

Definition at line 182 of file usb.h.

#define USB_EP_MODE_TYPE 0x0003

Endpoint type mask.

Definition at line 196 of file usb.h.

Referenced by usb_lld_init_endpoint().

#define USB_EP_MODE_TYPE_CTRL 0x0000

Control endpoint.

Definition at line 197 of file usb.h.

#define USB_EP_MODE_TYPE_ISOC 0x0001

Isochronous endpoint.

Definition at line 198 of file usb.h.

Referenced by usb_lld_init_endpoint().

#define USB_EP_MODE_TYPE_BULK 0x0002

Bulk endpoint.

Definition at line 199 of file usb.h.

Referenced by usb_lld_init_endpoint().

#define USB_EP_MODE_TYPE_INTR 0x0003

Interrupt endpoint.

Definition at line 200 of file usb.h.

Referenced by usb_lld_init_endpoint().

#define USB_EP_MODE_LINEAR_BUFFER 0x0000

Linear buffer mode.

Definition at line 201 of file usb.h.

#define USB_EP_MODE_QUEUE_BUFFER 0x0010

Queue buffer mode.

Definition at line 202 of file usb.h.

#define usbGetDriverStateI ( usbp ) ((usbp)->state)

Returns the driver state.

Parameters:

[in] usbp pointer to the USBDriver object

Returns:: The driver state.

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 349 of file usb.h.

#define usbFetchWord ( p ) ((uint16_t)*(p) | ((uint16_t)*((p) + 1) << 8))

Fetches a 16 bits word value from an USB message.

Parameters:

[in] p pointer to the 16 bits word

Function Class:: Not an API, this function is for internal use only.

Definition at line 358 of file usb.h.

Referenced by _usb_ep0in(), and _usb_ep0setup().

#define usbConnectBus ( usbp ) usb_lld_connect_bus(usbp)

Connects the USB device.

Parameters:

[in] usbp pointer to the USBDriver object

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 367 of file usb.h.

#define usbDisconnectBus ( usbp ) usb_lld_disconnect_bus(usbp)

Disconnect the USB device.

Parameters:

[in] usbp pointer to the USBDriver object

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 376 of file usb.h.

#define usbGetFrameNumber ( usbp ) usb_lld_get_frame_number(usbp)

Returns the current frame number.

Parameters:

[in] usbp pointer to the USBDriver object

Returns:: The current frame number.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 386 of file usb.h.

#define usbGetTransmitStatusI	(	usbp,
		ep
	)	((usbp)->transmitting & (1 << (ep)))

Returns the status of an IN endpoint.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Returns:: The operation status.

Return values:

FALSE	Endpoint ready.
TRUE	Endpoint transmitting.

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 399 of file usb.h.

Referenced by usbStallTransmitI(), and usbStartTransmitI().

#define usbGetReceiveStatusI	(	usbp,
		ep
	)	((usbp)->receiving & (1 << (ep)))

Returns the status of an OUT endpoint.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Returns:: The operation status.

Return values:

FALSE	Endpoint ready.
TRUE	Endpoint receiving.

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 412 of file usb.h.

Referenced by usbStallReceiveI(), and usbStartReceiveI().

#define usbGetReceiveTransactionSizeI	(	usbp,
		ep
	)	usb_lld_get_transaction_size(usbp, ep)

Returns the exact size of a receive transaction.

The received size can be different from the size specified in usbStartReceiveI() because the last packet could have a size different from the expected one.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Returns:: Received data size.

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 426 of file usb.h.

Referenced by _usb_ep0out().

#define usbSetupTransfer	(	usbp,
		buf,
		n,
		endcb
	)

Value:

{                             \
  (usbp)->ep0next  = (buf);                                                 \
  (usbp)->ep0n     = (n);                                                   \
  (usbp)->ep0endcb = (endcb);                                               \
}

Request transfer setup.

This macro is used by the request handling callbacks in order to prepare a transaction over the endpoint zero.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	buf	pointer to a buffer for the transaction data
[in]	n	number of bytes to be transferred
[in]	endcb	callback to be invoked after the transfer or `NULL`

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 441 of file usb.h.

#define usbReadSetup	(	usbp,
		ep,
		buf
	)	usb_lld_read_setup(usbp, ep, buf)

Reads a setup packet from the dedicated packet buffer.

This function must be invoked in the context of the setup_cb callback in order to read the received setup packet.

Precondition:: In order to use this function the endpoint must have been initialized as a control endpoint.

Note:: This function can be invoked both in thread and IRQ context.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number
[out]	buf	buffer where to copy the packet data

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 461 of file usb.h.

Referenced by _usb_ep0setup().

#define _usb_isr_invoke_event_cb	(	usbp,
		evt
	)

Value:

{                               \
  if (((usbp)->config->event_cb) != NULL)                                   \
    (usbp)->config->event_cb(usbp, evt);                                    \
}

Common ISR code, usb event callback.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	evt	USB event code

Function Class:: Not an API, this function is for internal use only.

Definition at line 476 of file usb.h.

Referenced by _usb_ep0in(), _usb_ep0out(), _usb_ep0setup(), and CH_IRQ_HANDLER().

#define _usb_isr_invoke_sof_cb ( usbp )

Value:

{                                      \
  if (((usbp)->config->sof_cb) != NULL)                                     \
    (usbp)->config->sof_cb(usbp);                                           \
}

Common ISR code, SOF callback.

Parameters:

[in] usbp pointer to the USBDriver object

Function Class:: Not an API, this function is for internal use only.

Definition at line 488 of file usb.h.

Referenced by CH_IRQ_HANDLER().

#define _usb_isr_invoke_setup_cb	(	usbp,
		ep
	)

Value:

{                                \
  (usbp)->epc[ep]->setup_cb(usbp, ep);                                      \
}

Common ISR code, setup packet callback.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Function Class:: Not an API, this function is for internal use only.

Definition at line 501 of file usb.h.

Referenced by CH_IRQ_HANDLER().

#define _usb_isr_invoke_in_cb	(	usbp,
		ep
	)

Value:

{                                   \
  (usbp)->transmitting &= ~(1 << (ep));                                     \
  (usbp)->epc[ep]->in_cb(usbp, ep);                                         \
}

Common ISR code, IN endpoint callback.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Function Class:: Not an API, this function is for internal use only.

Definition at line 513 of file usb.h.

Referenced by CH_IRQ_HANDLER().

#define _usb_isr_invoke_out_cb	(	usbp,
		ep
	)

Value:

{                                  \
  (usbp)->receiving &= ~(1 << (ep));                                        \
  (usbp)->epc[ep]->out_cb(usbp, ep);                                        \
}

Common ISR code, OUT endpoint event.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Function Class:: Not an API, this function is for internal use only.

Definition at line 526 of file usb.h.

Referenced by CH_IRQ_HANDLER().

#define USB_ENDOPOINTS_NUMBER 7

Number of the available endpoints.

This value does not include the endpoint 0 which is always present.

Definition at line 38 of file stm32_usb.h.

Referenced by usb_lld_disable_endpoints().

#define STM32_USB_BASE (APB1PERIPH_BASE + 0x5C00)

USB registers block numeric address.

Definition at line 115 of file stm32_usb.h.

#define STM32_USBRAM_BASE (APB1PERIPH_BASE + 0x6000)

USB RAM numeric address.

Definition at line 120 of file stm32_usb.h.

#define STM32_USB ((stm32_usb_t *)STM32_USB_BASE)

Pointer to the USB registers block.

Definition at line 125 of file stm32_usb.h.

Referenced by CH_IRQ_HANDLER(), usb_lld_clear_in(), usb_lld_clear_out(), usb_lld_get_status_in(), usb_lld_get_status_out(), usb_lld_reset(), usb_lld_set_address(), usb_lld_start(), and usb_lld_stop().

#define STM32_USBRAM ((uint32_t *)STM32_USBRAM_BASE)

Pointer to the USB RAM.

Definition at line 130 of file stm32_usb.h.

#define USB_PMA_SIZE 512

Size of the dedicated packet memory.

Definition at line 135 of file stm32_usb.h.

#define EPR_TOGGLE_MASK

Value:

(EPR_STAT_TX_MASK | EPR_DTOG_TX |           \
                                 EPR_STAT_RX_MASK | EPR_DTOG_RX |           \
                                 EPR_SETUP)

Mask of all the toggling bits in the EPR register.

Definition at line 140 of file stm32_usb.h.

#define USB_GET_DESCRIPTOR ( ep )

Value:

((stm32_usb_descriptor_t *)((uint32_t)STM32_USBRAM_BASE +                 \
                              (uint32_t)STM32_USB->BTABLE * 2 +             \
                              (uint32_t)(ep) *                              \
                              sizeof(stm32_usb_descriptor_t)))

Returns an endpoint descriptor pointer.

Definition at line 233 of file stm32_usb.h.

Referenced by CH_IRQ_HANDLER(), usb_lld_init_endpoint(), usb_lld_prepare_transmit(), and usb_lld_read_setup().

#define USB_ADDR2PTR ( addr ) ((uint32_t *)((addr) * 2 + STM32_USBRAM_BASE))

Converts from a PMA address to a physical address.

Definition at line 242 of file stm32_usb.h.

Referenced by usb_lld_read_setup().

#define USB_MAX_ENDPOINTS USB_ENDOPOINTS_NUMBER

Maximum endpoint address.

Definition at line 43 of file usb_lld.h.

Referenced by _usb_reset(), usbDisableEndpointsI(), and usbStart().

#define USB_SET_ADDRESS_MODE USB_LATE_SET_ADDRESS

This device requires the address change after the status packet.

Definition at line 48 of file usb_lld.h.

#define STM32_USB_USE_USB1 FALSE

USB1 driver enable switch.

If set to TRUE the support for USB1 is included.

Note:: The default is TRUE.

Definition at line 60 of file usb_lld.h.

#define STM32_USB_LOW_POWER_ON_SUSPEND FALSE

Enables the USB device low power mode on suspend.

Definition at line 67 of file usb_lld.h.

#define STM32_USB_USB1_HP_IRQ_PRIORITY 13

USB1 interrupt priority level setting.

Definition at line 74 of file usb_lld.h.

Referenced by usb_lld_start().

#define STM32_USB_USB1_LP_IRQ_PRIORITY 14

USB1 interrupt priority level setting.

Definition at line 81 of file usb_lld.h.

Referenced by usb_lld_start().

#define usb_lld_get_frame_number ( usbp ) (STM32_USB->FNR & FNR_FN_MASK)

Returns the current frame number.

Parameters:

[in] usbp pointer to the USBDriver object

Returns:: The current frame number.

Function Class:: Not an API, this function is for internal use only.

Definition at line 362 of file usb_lld.h.

#define usb_lld_get_transaction_size	(	usbp,
		ep
	)	((usbp)->epc[ep]->out_state->rxcnt)

Returns the exact size of a receive transaction.

The received size can be different from the size specified in usbStartReceiveI() because the last packet could have a size different from the expected one.

Precondition:: The OUT endpoint must have been configured in transaction mode in order to use this function.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Returns:: Received data size.

Function Class:: Not an API, this function is for internal use only.

Definition at line 378 of file usb_lld.h.

#define usb_lld_get_packet_size	(	usbp,
		ep
	)	((size_t)USB_GET_DESCRIPTOR(ep)->RXCOUNT & RXCOUNT_COUNT_MASK)

Returns the exact size of a received packet.

Precondition:: The OUT endpoint must have been configured in packet mode in order to use this function.

Parameters:

[in]	usbp	pointer to the `USBDriver` object
[in]	ep	endpoint number

Returns:: Received data size.

Function Class:: Not an API, this function is for internal use only.

Definition at line 392 of file usb_lld.h.

Typedef Documentation

typedef struct USBDriver USBDriver

Type of a structure representing an USB driver.

Definition at line 220 of file usb.h.

typedef uint8_t usbep_t

Type of an endpoint identifier.

Definition at line 225 of file usb.h.

typedef void(* usbcallback_t)(USBDriver *usbp)

Type of an USB generic notification callback.

Parameters:

[in] usbp pointer to the USBDriver object triggering the callback

Definition at line 291 of file usb.h.

typedef void(* usbepcallback_t)(USBDriver *usbp, usbep_t ep)

Type of an USB endpoint callback.

Parameters:

[in]	usbp	pointer to the `USBDriver` object triggering the callback
[in]	ep	endpoint number

Definition at line 300 of file usb.h.

typedef void(* usbeventcb_t)(USBDriver *usbp, usbevent_t event)

Type of an USB event notification callback.

Parameters:

[in]	usbp	pointer to the `USBDriver` object triggering the callback
[in]	event	event type

Definition at line 309 of file usb.h.

typedef bool_t(* usbreqhandler_t)(USBDriver *usbp)

Type of a requests handler callback.

The request is encoded in the usb_setup buffer.

Parameters:

[in] usbp pointer to the USBDriver object triggering the callback

Returns:: The request handling exit code.

Return values:

FALSE	Request not recognized by the handler.
TRUE	Request handled.

Definition at line 321 of file usb.h.

typedef const USBDescriptor*(* usbgetdescriptor_t)(USBDriver *usbp, uint8_t dtype, uint8_t dindex, uint16_t lang)

Type of an USB descriptor-retrieving callback.

Definition at line 326 of file usb.h.

Enumeration Type Documentation

enum usbstate_t

Type of a driver state machine possible states.

Enumerator:

USB_UNINIT	Not initialized.
USB_STOP	Stopped.
USB_READY	Ready, after bus reset.
USB_SELECTED	Address assigned.
USB_ACTIVE	Active, configuration selected.

Definition at line 230 of file usb.h.

enum usbepstatus_t

Type of an endpoint status.

Enumerator:

EP_STATUS_DISABLED	Endpoint not active.
EP_STATUS_STALLED	Endpoint opened but stalled.
EP_STATUS_ACTIVE	Active endpoint.

Definition at line 241 of file usb.h.

enum usbep0state_t

Type of an endpoint zero state machine states.

Enumerator:

USB_EP0_WAITING_SETUP	Waiting for SETUP data.
USB_EP0_TX	Trasmitting.
USB_EP0_WAITING_STS	Waiting status.
USB_EP0_RX	Receiving.
USB_EP0_SENDING_STS	Sending status.
USB_EP0_ERROR	Error, EP0 stalled.

Definition at line 250 of file usb.h.

enum usbevent_t

Type of an enumeration of the possible USB events.

Enumerator:

USB_EVENT_RESET	Driver has been reset by host.
USB_EVENT_ADDRESS	Address assigned.
USB_EVENT_CONFIGURED	Configuration selected.
USB_EVENT_SUSPEND	Entering suspend mode.
USB_EVENT_WAKEUP	Leaving suspend mode.
USB_EVENT_STALLED	Endpoint 0 error, stalled.

Definition at line 262 of file usb.h.

Detailed Description

Driver State Machine

USB Operations

USB Implementation

USB Endpoints

USB Callbacks

Data Structures

Functions

Variables

Helper macros for USB descriptors

Endpoint types and settings

Macro Functions

Low Level driver helper macros

Register aliases

Defines

Typedefs

Enumerations

Function Documentation

Variable Documentation

Define Documentation

Typedef Documentation

Enumeration Type Documentation