Microchip® Advanced Software Framework

usb.c File Reference

SAM USB Driver.

Copyright (c) 2014-2018 Microchip Technology Inc. and its subsidiaries.

#include <string.h>
#include "usb.h"

Macros

#define NVM_USB_PAD_TRANSN_POS   45
 
#define NVM_USB_PAD_TRANSN_SIZE   5
 
#define NVM_USB_PAD_TRANSP_POS   50
 
#define NVM_USB_PAD_TRANSP_SIZE   5
 
#define NVM_USB_PAD_TRIM_POS   55
 
#define NVM_USB_PAD_TRIM_SIZE   3
 
#define UHD_BULK_INTERVAL_MIN   1
 Minimal bulk interval value. More...
 
#define USB_EP_ADDR_MASK   0x0f
 Mask selecting the index part of an endpoint address. More...
 
#define USB_EP_DIR_IN   0x80
 Endpoint transfer direction is IN. More...
 
#define USB_EP_DIR_OUT   0x00
 Endpoint transfer direction is OUT. More...
 
#define USB_LPM_ATTRIBUT_BLINKSTATE(value)   ((value & 0xF) << 0)
 
#define USB_LPM_ATTRIBUT_BLINKSTATE_L1   USB_LPM_ATTRIBUT_BLINKSTATE(1)
 
#define USB_LPM_ATTRIBUT_BLINKSTATE_MASK   (0xF << 0)
 Fields definition from a LPM TOKEN. More...
 
#define USB_LPM_ATTRIBUT_HIRD(value)   ((value & 0xF) << 4)
 
#define USB_LPM_ATTRIBUT_HIRD_MASK   (0xF << 4)
 
#define USB_LPM_ATTRIBUT_REMOTEWAKE(value)   ((value & 1) << 8)
 
#define USB_LPM_ATTRIBUT_REMOTEWAKE_MASK   (1 << 8)
 
#define USB_STATUS_PIPE_CRC16ER   (1 << 4)
 

Functions

static void _usb_device_interrupt_handler (void)
 
static void _usb_host_interrupt_handler (void)
 Function called by USB interrupt to manage USB host interrupts. More...
 
enum status_code usb_device_disable_callback (struct usb_module *module_inst, enum usb_device_callback callback_type)
 Disables USB device callback generation for a given type. More...
 
enum status_code usb_device_enable_callback (struct usb_module *module_inst, enum usb_device_callback callback_type)
 Enables USB device callback generation for a given type. More...
 
void usb_device_endpoint_abort_job (struct usb_module *module_inst, uint8_t ep)
 Abort ongoing job on the endpoint. More...
 
void usb_device_endpoint_clear_halt (struct usb_module *module_inst, uint8_t ep)
 Clear endpoint halt state. More...
 
enum status_code usb_device_endpoint_disable_callback (struct usb_module *module_inst, uint8_t ep, enum usb_device_endpoint_callback callback_type)
 Disables USB device endpoint callback generation for a given type. More...
 
enum status_code usb_device_endpoint_enable_callback (struct usb_module *module_inst, uint8_t ep, enum usb_device_endpoint_callback callback_type)
 Enables USB device endpoint callback generation for a given type. More...
 
void usb_device_endpoint_get_config_defaults (struct usb_device_endpoint_config *ep_config)
 Initializes an USB device endpoint configuration structure to defaults. More...
 
bool usb_device_endpoint_is_configured (struct usb_module *module_inst, uint8_t ep)
 Check if current endpoint is configured. More...
 
bool usb_device_endpoint_is_halted (struct usb_module *module_inst, uint8_t ep)
 Check if endpoint is halted. More...
 
enum status_code usb_device_endpoint_read_buffer_job (struct usb_module *module_inst, uint8_t ep_num, uint8_t *pbuf, uint32_t buf_size)
 Start read buffer job on a endpoint. More...
 
enum status_code usb_device_endpoint_register_callback (struct usb_module *module_inst, uint8_t ep_num, enum usb_device_endpoint_callback callback_type, usb_device_endpoint_callback_t callback_func)
 Registers a USB device endpoint callback. More...
 
enum status_code usb_device_endpoint_set_config (struct usb_module *module_inst, struct usb_device_endpoint_config *ep_config)
 Writes an USB device endpoint configuration to the hardware module. More...
 
void usb_device_endpoint_set_halt (struct usb_module *module_inst, uint8_t ep)
 Halt the endpoint (send STALL) More...
 
enum status_code usb_device_endpoint_setup_buffer_job (struct usb_module *module_inst, uint8_t *pbuf)
 Start setup packet read job on a endpoint. More...
 
enum status_code usb_device_endpoint_unregister_callback (struct usb_module *module_inst, uint8_t ep_num, enum usb_device_endpoint_callback callback_type)
 Unregisters a USB device endpoint callback. More...
 
enum status_code usb_device_endpoint_write_buffer_job (struct usb_module *module_inst, uint8_t ep_num, uint8_t *pbuf, uint32_t buf_size)
 Start write buffer job on a endpoint. More...
 
enum status_code usb_device_register_callback (struct usb_module *module_inst, enum usb_device_callback callback_type, usb_device_callback_t callback_func)
 Registers a USB device callback. More...
 
enum status_code usb_device_unregister_callback (struct usb_module *module_inst, enum usb_device_callback callback_type)
 Unregisters a USB device callback. More...
 
void usb_disable (struct usb_module *module_inst)
 Disable the USB module peripheral. More...
 
void usb_enable (struct usb_module *module_inst)
 Enable the USB module peripheral. More...
 
void usb_get_config_defaults (struct usb_config *module_config)
 Get the default USB module settings. More...
 
void USB_Handler (void)
 Interrupt handler for the USB module. More...
 
enum status_code usb_host_disable_callback (struct usb_module *module_inst, enum usb_host_callback callback_type)
 Disables USB host callback generation for a given type. More...
 
enum status_code usb_host_enable_callback (struct usb_module *module_inst, enum usb_host_callback callback_type)
 Enables USB host callback generation for a given type. More...
 
enum status_code usb_host_pipe_abort_job (struct usb_module *module_inst, uint8_t pipe_num)
 USB host abort a pipe job. More...
 
enum status_code usb_host_pipe_disable_callback (struct usb_module *module_inst, uint8_t pipe_num, enum usb_host_pipe_callback callback_type)
 Disables USB host callback generation for a given type. More...
 
enum status_code usb_host_pipe_enable_callback (struct usb_module *module_inst, uint8_t pipe_num, enum usb_host_pipe_callback callback_type)
 Enables USB host pipe callback generation for a given type. More...
 
enum status_code usb_host_pipe_get_config (struct usb_module *module_inst, uint8_t pipe_num, struct usb_host_pipe_config *ep_config)
 Gets an USB host pipe configuration. More...
 
void usb_host_pipe_get_config_defaults (struct usb_host_pipe_config *ep_config)
 Initializes an USB host pipe configuration structure to defaults. More...
 
enum status_code usb_host_pipe_lpm_job (struct usb_module *module_inst, uint8_t pipe_num, bool b_remotewakeup, uint8_t hird)
 Sends the LPM package. More...
 
enum status_code usb_host_pipe_read_job (struct usb_module *module_inst, uint8_t pipe_num, uint8_t *buf, uint32_t buf_size)
 USB host pipe read job. More...
 
enum status_code usb_host_pipe_register_callback (struct usb_module *module_inst, uint8_t pipe_num, enum usb_host_pipe_callback callback_type, usb_host_pipe_callback_t callback_func)
 Registers a USB host pipe callback. More...
 
void usb_host_pipe_set_auto_zlp (struct usb_module *module_inst, uint8_t pipe_num, bool value)
 Sets USB host pipe auto ZLP setting value. More...
 
enum status_code usb_host_pipe_set_config (struct usb_module *module_inst, uint8_t pipe_num, struct usb_host_pipe_config *ep_config)
 Writes an USB host pipe configuration to the hardware module. More...
 
enum status_code usb_host_pipe_setup_job (struct usb_module *module_inst, uint8_t pipe_num, uint8_t *buf)
 Sends the setup package. More...
 
enum status_code usb_host_pipe_unregister_callback (struct usb_module *module_inst, uint8_t pipe_num, enum usb_host_pipe_callback callback_type)
 Unregisters a USB host pipe callback. More...
 
enum status_code usb_host_pipe_write_job (struct usb_module *module_inst, uint8_t pipe_num, uint8_t *buf, uint32_t buf_size)
 USB host pipe write job. More...
 
enum status_code usb_host_register_callback (struct usb_module *module_inst, enum usb_host_callback callback_type, usb_host_callback_t callback_func)
 Registers a USB host callback. More...
 
enum status_code usb_host_unregister_callback (struct usb_module *module_inst, enum usb_host_callback callback_type)
 Unregisters a USB host callback. More...
 
enum status_code usb_init (struct usb_module *module_inst, Usb *const hw, struct usb_config *module_config)
 Initializes USB module instance. More...
 

Variables

static const uint16_t _usb_device_irq_bits [USB_DEVICE_CALLBACK_N]
 
static const uint8_t _usb_endpoint_irq_bits [USB_DEVICE_EP_CALLBACK_N]
 
static struct usb_module_usb_instances
 Local USB module instance. More...
 
static uint32_t device_callback_lpm_wakeup_enable
 
static struct
usb_endpoint_callback_parameter 
ep_callback_para
 Device endpoint callback parameter variable, used to transfer info to UDD wrapper layer. More...
 
uint32_t host_pipe_job_busy_status = 0
 Bit mask for pipe job busy status. More...
 
static struct
usb_pipe_callback_parameter 
pipe_callback_para
 Host pipe callback structure variable. More...
 
USB SRAM data containing pipe descriptor table

The content of the USB SRAM can be :

  • modified by USB hardware interface to update pipe status. Thereby, it is read by software.
  • modified by USB software to control pipe. Thereby, it is read by hardware. This data section is volatile.
union {
   UsbDeviceDescriptor   usb_endpoint_table [USB_EPT_NUM]
 
   UsbHostDescriptor   usb_pipe_table [USB_PIPE_NUM]
 
usb_descriptor_table
 

#define NVM_USB_PAD_TRANSN_POS   45

Referenced by usb_init().

#define NVM_USB_PAD_TRANSN_SIZE   5

Referenced by usb_init().

#define NVM_USB_PAD_TRANSP_POS   50

Referenced by usb_init().

#define NVM_USB_PAD_TRANSP_SIZE   5

Referenced by usb_init().

#define NVM_USB_PAD_TRIM_POS   55

Referenced by usb_init().

#define NVM_USB_PAD_TRIM_SIZE   3

Referenced by usb_init().

#define UHD_BULK_INTERVAL_MIN   1

Minimal bulk interval value.

Referenced by usb_host_pipe_set_config().

#define USB_EP_DIR_OUT   0x00

Endpoint transfer direction is OUT.

Referenced by _usb_device_interrupt_handler().

#define USB_LPM_ATTRIBUT_BLINKSTATE (   value)    ((value & 0xF) << 0)
#define USB_LPM_ATTRIBUT_BLINKSTATE_L1   USB_LPM_ATTRIBUT_BLINKSTATE(1)

Referenced by usb_host_pipe_lpm_job().

#define USB_LPM_ATTRIBUT_BLINKSTATE_MASK   (0xF << 0)

Fields definition from a LPM TOKEN.

#define USB_LPM_ATTRIBUT_HIRD (   value)    ((value & 0xF) << 4)

Referenced by usb_host_pipe_lpm_job().

#define USB_LPM_ATTRIBUT_HIRD_MASK   (0xF << 4)
#define USB_LPM_ATTRIBUT_REMOTEWAKE (   value)    ((value & 1) << 8)

Referenced by usb_host_pipe_lpm_job().

#define USB_LPM_ATTRIBUT_REMOTEWAKE_MASK   (1 << 8)
#define USB_STATUS_PIPE_CRC16ER   (1 << 4)

enum status_code usb_device_disable_callback ( struct usb_module module_inst,
enum usb_device_callback  callback_type 
)

Disables USB device callback generation for a given type.

Disables asynchronous callbacks for a given logical type.

Parameters
[in]module_instPointer to USB software instance struct
[in]callback_typeCallback type given by an enum
Returns
Status of the callback disable operation.
Return values
STATUS_OKThe callback was disabled successfully.

References Assert, usb_module::device_enabled_callback_mask, usb_module::hw, and STATUS_OK.

enum status_code usb_device_enable_callback ( struct usb_module module_inst,
enum usb_device_callback  callback_type 
)

Enables USB device callback generation for a given type.

Enables asynchronous callbacks for a given logical type. This must be called before USB device generate callback events.

Parameters
[in]module_instPointer to USB software instance struct
[in]callback_typeCallback type given by an enum
Returns
Status of the callback enable operation.
Return values
STATUS_OKThe callback was enabled successfully.

References Assert, usb_module::device_enabled_callback_mask, usb_module::hw, and STATUS_OK.

void usb_device_endpoint_abort_job ( struct usb_module module_inst,
uint8_t  ep 
)

Abort ongoing job on the endpoint.

Parameters
module_instPointer to USB software instance struct
epEndpoint address

References usb_module::hw, USB_EP_ADDR_MASK, and USB_EP_DIR_IN.

void usb_device_endpoint_clear_halt ( struct usb_module module_inst,
uint8_t  ep 
)

Clear endpoint halt state.

Parameters
module_instPointer to USB software instance struct
epEndpoint address

References usb_module::hw, USB_EP_ADDR_MASK, and USB_EP_DIR_IN.

enum status_code usb_device_endpoint_disable_callback ( struct usb_module module_inst,
uint8_t  ep,
enum usb_device_endpoint_callback  callback_type 
)

Disables USB device endpoint callback generation for a given type.

Disables callbacks for a given logical type.

Parameters
[in]module_instPointer to USB software instance struct
[in]epEndpoint to configure
[in]callback_typeCallback type given by an enum
Returns
Status of the callback disable operation.
Return values
STATUS_OKThe callback was disabled successfully.

References Assert, usb_module::device_endpoint_enabled_callback_mask, usb_module::hw, STATUS_OK, USB_DEVICE_ENDPOINT_CALLBACK_RXSTP, USB_DEVICE_ENDPOINT_CALLBACK_STALL, USB_DEVICE_ENDPOINT_CALLBACK_TRCPT, USB_DEVICE_ENDPOINT_CALLBACK_TRFAIL, USB_EP_ADDR_MASK, and USB_EP_DIR_IN.

enum status_code usb_device_endpoint_enable_callback ( struct usb_module module_inst,
uint8_t  ep,
enum usb_device_endpoint_callback  callback_type 
)

Enables USB device endpoint callback generation for a given type.

Enables callbacks for a given logical type. This must be called before USB device pipe generate callback events.

Parameters
[in]module_instPointer to USB software instance struct
[in]epEndpoint to configure
[in]callback_typeCallback type given by an enum
Returns
Status of the callback enable operation.
Return values
STATUS_OKThe callback was enabled successfully.

References Assert, usb_module::device_endpoint_enabled_callback_mask, usb_module::hw, STATUS_OK, USB_DEVICE_ENDPOINT_CALLBACK_RXSTP, USB_DEVICE_ENDPOINT_CALLBACK_STALL, USB_DEVICE_ENDPOINT_CALLBACK_TRCPT, USB_DEVICE_ENDPOINT_CALLBACK_TRFAIL, USB_EP_ADDR_MASK, and USB_EP_DIR_IN.

void usb_device_endpoint_get_config_defaults ( struct usb_device_endpoint_config ep_config)

Initializes an USB device endpoint configuration structure to defaults.

Initializes a given USB device endpoint configuration structure to a set of known default values. This function should be called on all new instances of these configuration structures before being modified by the user application.

The default configuration is as follows:

  • endpoint address is 0
  • endpoint size is 8 bytes
  • auto_zlp is false
  • endpoint type is control
Parameters
[out]ep_configConfiguration structure to initialize to default values

References Assert, usb_device_endpoint_config::auto_zlp, usb_device_endpoint_config::ep_address, usb_device_endpoint_config::ep_size, usb_device_endpoint_config::ep_type, USB_DEVICE_ENDPOINT_TYPE_CONTROL, and USB_ENDPOINT_8_BYTE.

bool usb_device_endpoint_is_configured ( struct usb_module module_inst,
uint8_t  ep 
)

Check if current endpoint is configured.

Parameters
module_instPointer to USB software instance struct
epEndpoint address (direction & number)
Returns
true if endpoint is configured and ready to use

References usb_module::hw, USB_DEVICE_ENDPOINT_TYPE_DISABLE, USB_EP_ADDR_MASK, and USB_EP_DIR_IN.

bool usb_device_endpoint_is_halted ( struct usb_module module_inst,
uint8_t  ep 
)

Check if endpoint is halted.

Parameters
module_instPointer to USB software instance struct
epEndpoint address
Returns
true if the endpoint is halted

References usb_module::hw, USB_EP_ADDR_MASK, and USB_EP_DIR_IN.

enum status_code usb_device_endpoint_read_buffer_job ( struct usb_module module_inst,
uint8_t  ep_num,
uint8_t *  pbuf,
uint32_t  buf_size 
)

Start read buffer job on a endpoint.

Parameters
module_instPointer to USB module instance
ep_numEndpoint number
pbufPointer to buffer
buf_sizeSize of buffer
Returns
Status of procedure
Return values
STATUS_OKJob started successfully
STATUS_ERR_DENIEDEndpoint is not ready

References Assert, usb_module::hw, STATUS_ERR_DENIED, STATUS_OK, usb_descriptor_table, and USB_DEVICE_ENDPOINT_TYPE_DISABLE.

enum status_code usb_device_endpoint_register_callback ( struct usb_module module_inst,
uint8_t  ep_num,
enum usb_device_endpoint_callback  callback_type,
usb_device_endpoint_callback_t  callback_func 
)

Registers a USB device endpoint callback.

Registers a callback function which is implemented by the user.

Note
The callback must be enabled by usb_device_endpoint_enable_callback, in order for the interrupt handler to call it when the conditions for the callback type is met.
Parameters
[in]module_instPointer to USB software instance struct
[in]ep_numEndpoint to configure
[in]callback_typeCallback type given by an enum
[in]callback_funcPointer to callback function
Returns
Status of the registration operation.
Return values
STATUS_OKThe callback was registered successfully.

References Assert, usb_module::device_endpoint_callback, usb_module::device_endpoint_registered_callback_mask, and STATUS_OK.

enum status_code usb_device_endpoint_set_config ( struct usb_module module_inst,
struct usb_device_endpoint_config ep_config 
)

Writes an USB device endpoint configuration to the hardware module.

Writes out a given configuration of an USB device endpoint configuration to the hardware module. If the pipe is already configured, the new configuration will replace the existing one.

Parameters
[in]module_instPointer to USB software instance struct
[in]ep_configConfiguration settings for the endpoint
Returns
Status of the device endpoint configuration operation
Return values
STATUS_OKThe device endpoint was configured successfully
STATUS_ERR_DENIEDThe endpoint address is already configured

References Assert, usb_device_endpoint_config::auto_zlp, usb_device_endpoint_config::ep_address, usb_device_endpoint_config::ep_size, usb_device_endpoint_config::ep_type, usb_module::hw, STATUS_ERR_DENIED, STATUS_OK, usb_descriptor_table, USB_DEVICE_ENDPOINT_TYPE_BULK, USB_DEVICE_ENDPOINT_TYPE_CONTROL, USB_DEVICE_ENDPOINT_TYPE_DISABLE, USB_DEVICE_ENDPOINT_TYPE_INTERRUPT, USB_DEVICE_ENDPOINT_TYPE_ISOCHRONOUS, USB_EP_ADDR_MASK, and USB_EP_DIR_IN.

void usb_device_endpoint_set_halt ( struct usb_module module_inst,
uint8_t  ep 
)

Halt the endpoint (send STALL)

Parameters
module_instPointer to USB software instance struct
epEndpoint address

References usb_module::hw, USB_EP_ADDR_MASK, and USB_EP_DIR_IN.

enum status_code usb_device_endpoint_setup_buffer_job ( struct usb_module module_inst,
uint8_t *  pbuf 
)

Start setup packet read job on a endpoint.

Parameters
module_instPointer to USB device module instance
pbufPointer to buffer
Returns
Status of procedure
Return values
STATUS_OKJob started successfully
STATUS_ERR_DENIEDEndpoint is not ready

References Assert, usb_module::hw, STATUS_OK, and usb_descriptor_table.

enum status_code usb_device_endpoint_unregister_callback ( struct usb_module module_inst,
uint8_t  ep_num,
enum usb_device_endpoint_callback  callback_type 
)

Unregisters a USB device endpoint callback.

Unregisters an callback implemented by the user. Removing it from the internal callback registration table.

Parameters
[in]module_instPointer to USB software instance struct
[in]ep_numEndpoint to configure
[in]callback_typeCallback type given by an enum
Returns
Status of the de-registration operation.
Return values
STATUS_OKThe callback was unregistered successfully.

References Assert, usb_module::device_endpoint_callback, usb_module::device_endpoint_registered_callback_mask, and STATUS_OK.

enum status_code usb_device_endpoint_write_buffer_job ( struct usb_module module_inst,
uint8_t  ep_num,
uint8_t *  pbuf,
uint32_t  buf_size 
)

Start write buffer job on a endpoint.

Parameters
module_instPointer to USB module instance
ep_numEndpoint number
pbufPointer to buffer
buf_sizeSize of buffer
Returns
Status of procedure
Return values
STATUS_OKJob started successfully
STATUS_ERR_DENIEDEndpoint is not ready

References Assert, usb_module::hw, STATUS_ERR_DENIED, STATUS_OK, usb_descriptor_table, and USB_DEVICE_ENDPOINT_TYPE_DISABLE.

enum status_code usb_device_register_callback ( struct usb_module module_inst,
enum usb_device_callback  callback_type,
usb_device_callback_t  callback_func 
)

Registers a USB device callback.

Registers a callback function which is implemented by the user.

Note
The callback must be enabled by usb_device_enable_callback, in order for the interrupt handler to call it when the conditions for the callback type is met.
Parameters
[in]module_instPointer to USB software instance struct
[in]callback_typeCallback type given by an enum
[in]callback_funcPointer to callback function
Returns
Status of the registration operation.
Return values
STATUS_OKThe callback was registered successfully.

References Assert, usb_module::device_callback, usb_module::device_registered_callback_mask, and STATUS_OK.

enum status_code usb_device_unregister_callback ( struct usb_module module_inst,
enum usb_device_callback  callback_type 
)

Unregisters a USB device callback.

Unregisters an asynchronous callback implemented by the user. Removing it from the internal callback registration table.

Parameters
[in]module_instPointer to USB software instance struct
[in]callback_typeCallback type given by an enum
Returns
Status of the de-registration operation.
Return values
STATUS_OKThe callback was unregistered successfully.

References Assert, usb_module::device_callback, usb_module::device_registered_callback_mask, and STATUS_OK.

void usb_disable ( struct usb_module module_inst)

Disable the USB module peripheral.

Parameters
module_instpointer to USB module instance

References Assert, and usb_module::hw.

void usb_enable ( struct usb_module module_inst)

Enable the USB module peripheral.

Parameters
module_instpointer to USB module instance

References Assert, and usb_module::hw.

void usb_get_config_defaults ( struct usb_config module_config)

Get the default USB module settings.

Parameters
[out]module_configConfiguration structure to initialize to default values

References Assert, GCLK_GENERATOR_3, usb_config::run_in_standby, usb_config::select_host_mode, usb_config::source_generator, usb_config::speed_mode, and USB_SPEED_FULL.

void USB_Handler ( void  )

Interrupt handler for the USB module.

References _usb_device_interrupt_handler(), and _usb_host_interrupt_handler().

enum status_code usb_host_disable_callback ( struct usb_module module_inst,
enum usb_host_callback  callback_type 
)

Disables USB host callback generation for a given type.

Disables asynchronous callbacks for a given logical type.

Parameters
[in]module_instPointer to USB software instance struct
[in]callback_typeCallback type given by an enum
Returns
Status of the callback disable operation.
Return values
STATUS_OKThe callback was disabled successfully.

References Assert, usb_module::hw, STATUS_OK, USB_HOST_CALLBACK_CONNECT, USB_HOST_CALLBACK_DISCONNECT, USB_HOST_CALLBACK_DNRSM, USB_HOST_CALLBACK_RAMACER, USB_HOST_CALLBACK_RESET, USB_HOST_CALLBACK_SOF, USB_HOST_CALLBACK_UPRSM, and USB_HOST_CALLBACK_WAKEUP.

enum status_code usb_host_enable_callback ( struct usb_module module_inst,
enum usb_host_callback  callback_type 
)

Enables USB host callback generation for a given type.

Enables asynchronous callbacks for a given logical type. This must be called before USB host generate callback events.

Parameters
[in]module_instPointer to USB software instance struct
[in]callback_typeCallback type given by an enum
Returns
Status of the callback enable operation.
Return values
STATUS_OKThe callback was enabled successfully.

References Assert, usb_module::hw, STATUS_OK, USB_HOST_CALLBACK_CONNECT, USB_HOST_CALLBACK_DISCONNECT, USB_HOST_CALLBACK_DNRSM, USB_HOST_CALLBACK_RAMACER, USB_HOST_CALLBACK_RESET, USB_HOST_CALLBACK_SOF, USB_HOST_CALLBACK_UPRSM, and USB_HOST_CALLBACK_WAKEUP.

enum status_code usb_host_pipe_abort_job ( struct usb_module module_inst,
uint8_t  pipe_num 
)

USB host abort a pipe job.

USB host pipe abort job by freeze the pipe.

Parameters
[in]module_instPointer to USB software instance struct
[in]pipe_numPipe to configure
Returns
Status of the setting operation.
Return values
STATUS_OKThe abort job was set successfully.
STATUS_ERR_NOT_INITIALIZEDThe pipe has not been configured.

References Assert, usb_module::hw, STATUS_ERR_NOT_INITIALIZED, STATUS_OK, and USB_HOST_PIPE_TYPE_DISABLE.

enum status_code usb_host_pipe_disable_callback ( struct usb_module module_inst,
uint8_t  pipe_num,
enum usb_host_pipe_callback  callback_type 
)

Disables USB host callback generation for a given type.

Disables asynchronous callbacks for a given logical type.

Parameters
[in]module_instPointer to USB software instance struct
[in]pipe_numPipe to configure
[in]callback_typeCallback type given by an enum
Returns
Status of the callback disable operation.
Return values
STATUS_OKThe callback was disabled successfully.

References Assert, usb_module::hw, STATUS_OK, USB_HOST_PIPE_CALLBACK_ERROR, USB_HOST_PIPE_CALLBACK_SETUP, USB_HOST_PIPE_CALLBACK_STALL, and USB_HOST_PIPE_CALLBACK_TRANSFER_COMPLETE.

enum status_code usb_host_pipe_enable_callback ( struct usb_module module_inst,
uint8_t  pipe_num,
enum usb_host_pipe_callback  callback_type 
)

Enables USB host pipe callback generation for a given type.

Enables asynchronous callbacks for a given logical type. This must be called before USB host pipe generate callback events.

Parameters
[in]module_instPointer to USB software instance struct
[in]pipe_numPipe to configure
[in]callback_typeCallback type given by an enum
Returns
Status of the callback enable operation.
Return values
STATUS_OKThe callback was enabled successfully.

References Assert, usb_module::hw, STATUS_OK, USB_HOST_PIPE_CALLBACK_ERROR, USB_HOST_PIPE_CALLBACK_SETUP, USB_HOST_PIPE_CALLBACK_STALL, and USB_HOST_PIPE_CALLBACK_TRANSFER_COMPLETE.

enum status_code usb_host_pipe_get_config ( struct usb_module module_inst,
uint8_t  pipe_num,
struct usb_host_pipe_config ep_config 
)

Gets an USB host pipe configuration.

Gets out the configuration of an USB host pipe from the hardware module.

Parameters
[in]module_instPointer to USB software instance struct
[in]pipe_numPipe to configure
[out]ep_configConfiguration settings for the pipe
Returns
Status of the get host pipe configuration operation.
Return values
STATUS_OKThe host pipe configuration was read successfully.

References Assert, usb_host_pipe_config::binterval, usb_host_pipe_config::device_address, usb_host_pipe_config::endpoint_address, usb_module::hw, usb_host_pipe_config::pipe_type, usb_host_pipe_config::size, STATUS_OK, usb_descriptor_table, USB_EP_DIR_IN, and USB_HOST_PIPE_TOKEN_IN.

void usb_host_pipe_get_config_defaults ( struct usb_host_pipe_config ep_config)

Initializes an USB host pipe configuration structure to defaults.

Initializes a given USB host pipe configuration structure to a set of known default values. This function should be called on all new instances of these configuration structures before being modified by the user application.

The default configuration is as follows:

  • device address is 0
  • endpoint address is 0
  • pipe type is control
  • interval is 0
  • pipe size is 8
Parameters
[out]ep_configConfiguration structure to initialize to default values

References Assert, usb_host_pipe_config::binterval, usb_host_pipe_config::device_address, usb_host_pipe_config::endpoint_address, usb_host_pipe_config::pipe_type, usb_host_pipe_config::size, and USB_HOST_PIPE_TYPE_CONTROL.

enum status_code usb_host_pipe_lpm_job ( struct usb_module module_inst,
uint8_t  pipe_num,
bool  b_remotewakeup,
uint8_t  hird 
)

Sends the LPM package.

Sends the LPM package.

Parameters
[in]module_instPointer to USB software instance struct
[in]pipe_numPipe to configure
[in]b_remotewakeupRemote wake up flag
[in]hirdHost Initiated Resume Duration
Returns
Status of the setup operation.
Return values
STATUS_OKThe setup job was set successfully.
STATUS_BUSYThe pipe is busy.
STATUS_ERR_NOT_INITIALIZEDThe pipe has not been configured.

References Assert, usb_module::hw, STATUS_BUSY, STATUS_ERR_NOT_INITIALIZED, STATUS_OK, usb_descriptor_table, USB_HOST_PIPE_TYPE_DISABLE, USB_HOST_PIPE_TYPE_EXTENDED, USB_LPM_ATTRIBUT_BLINKSTATE_L1, USB_LPM_ATTRIBUT_HIRD, and USB_LPM_ATTRIBUT_REMOTEWAKE.

enum status_code usb_host_pipe_read_job ( struct usb_module module_inst,
uint8_t  pipe_num,
uint8_t *  buf,
uint32_t  buf_size 
)

USB host pipe read job.

USB host pipe read job by set and start an in transaction transfer.

Parameters
[in]module_instPointer to USB software instance struct
[in]pipe_numPipe to configure
[in]bufPointer to data buffer
[in]buf_sizeData buffer size
Note
The buffer length should not larger than 0x3FFF
Returns
Status of the setting operation.
Return values
STATUS_OKThe read job was set successfully.
STATUS_BUSYThe pipe is busy.
STATUS_ERR_NOT_INITIALIZEDThe pipe has not been configured.

References Assert, usb_module::hw, STATUS_BUSY, STATUS_ERR_NOT_INITIALIZED, STATUS_OK, usb_descriptor_table, USB_HOST_PIPE_TOKEN_IN, and USB_HOST_PIPE_TYPE_DISABLE.

enum status_code usb_host_pipe_register_callback ( struct usb_module module_inst,
uint8_t  pipe_num,
enum usb_host_pipe_callback  callback_type,
usb_host_pipe_callback_t  callback_func 
)

Registers a USB host pipe callback.

Registers a callback function which is implemented by the user.

Note
The callback must be enabled by usb_host_pipe_enable_callback, in order for the interrupt handler to call it when the conditions for the callback type is met.
Parameters
[in]module_instPointer to USB software instance struct
[in]pipe_numPipe to configure
[in]callback_typeCallback type given by an enum
[in]callback_funcPointer to callback function
Returns
Status of the registration operation.
Return values
STATUS_OKThe callback was registered successfully.

References Assert, and STATUS_OK.

void usb_host_pipe_set_auto_zlp ( struct usb_module module_inst,
uint8_t  pipe_num,
bool  value 
)

Sets USB host pipe auto ZLP setting value.

Parameters
[in]module_instPointer to USB software instance struct
[in]pipe_numPipe to configure
[in]valueAuto ZLP setting value, true to enable

References Assert, and usb_descriptor_table.

enum status_code usb_host_pipe_set_config ( struct usb_module module_inst,
uint8_t  pipe_num,
struct usb_host_pipe_config ep_config 
)

Writes an USB host pipe configuration to the hardware module.

Writes out a given configuration of an USB host pipe configuration to the hardware module. If the pipe is already configured, the new configuration will replace the existing one.

Parameters
[in]module_instPointer to USB software instance struct
[in]pipe_numPipe to configure
[in]ep_configConfiguration settings for the pipe
Returns
Status of the host pipe configuration operation.
Return values
STATUS_OKThe host pipe was configured successfully.

References Assert, usb_host_pipe_config::binterval, clz, usb_host_pipe_config::device_address, usb_host_pipe_config::endpoint_address, usb_module::hw, max, min, usb_host_pipe_config::pipe_type, usb_host_pipe_config::size, STATUS_OK, UHD_BULK_INTERVAL_MIN, usb_descriptor_table, USB_EP_ADDR_MASK, USB_EP_DIR_IN, USB_HOST_PIPE_TOKEN_IN, USB_HOST_PIPE_TOKEN_OUT, USB_HOST_PIPE_TOKEN_SETUP, and USB_HOST_PIPE_TYPE_BULK.

enum status_code usb_host_pipe_setup_job ( struct usb_module module_inst,
uint8_t  pipe_num,
uint8_t *  buf 
)

Sends the setup package.

Sends the setup package.

Parameters
[in]module_instPointer to USB software instance struct
[in]pipe_numPipe to configure
[in]bufPointer to data buffer
Returns
Status of the setup operation.
Return values
STATUS_OKThe setup job was set successfully.
STATUS_BUSYThe pipe is busy.
STATUS_ERR_NOT_INITIALIZEDThe pipe has not been configured.

References Assert, usb_module::hw, STATUS_BUSY, STATUS_ERR_NOT_INITIALIZED, STATUS_OK, usb_descriptor_table, USB_HOST_PIPE_TOKEN_SETUP, and USB_HOST_PIPE_TYPE_DISABLE.

enum status_code usb_host_pipe_unregister_callback ( struct usb_module module_inst,
uint8_t  pipe_num,
enum usb_host_pipe_callback  callback_type 
)

Unregisters a USB host pipe callback.

Unregisters an asynchronous callback implemented by the user. Removing it from the internal callback registration table.

Parameters
[in]module_instPointer to USB software instance struct
[in]pipe_numPipe to configure
[in]callback_typeCallback type given by an enum
Returns
Status of the de-registration operation.
Return values
STATUS_OKThe callback was unregistered successfully.

References Assert, and STATUS_OK.

enum status_code usb_host_pipe_write_job ( struct usb_module module_inst,
uint8_t  pipe_num,
uint8_t *  buf,
uint32_t  buf_size 
)

USB host pipe write job.

USB host pipe write job by set and start an out transaction transfer.

Parameters
[in]module_instPointer to USB software instance struct
[in]pipe_numPipe to configure
[in]bufPointer to data buffer
[in]buf_sizeData buffer size
Note
The buffer length should not larger than 0x3FFF
Returns
Status of the setting operation.
Return values
STATUS_OKThe write job was set successfully.
STATUS_BUSYThe pipe is busy.
STATUS_ERR_NOT_INITIALIZEDThe pipe has not been configured.

References Assert, usb_module::hw, STATUS_BUSY, STATUS_ERR_NOT_INITIALIZED, STATUS_OK, usb_descriptor_table, USB_HOST_PIPE_TOKEN_OUT, and USB_HOST_PIPE_TYPE_DISABLE.

enum status_code usb_host_register_callback ( struct usb_module module_inst,
enum usb_host_callback  callback_type,
usb_host_callback_t  callback_func 
)

Registers a USB host callback.

Registers a callback function which is implemented by the user.

Note
The callback must be enabled by usb_host_enable_callback, in order for the interrupt handler to call it when the conditions for the callback type is met.
Parameters
[in]module_instPointer to USB software instance struct
[in]callback_typeCallback type given by an enum
[in]callback_funcPointer to callback function
Returns
Status of the registration operation.
Return values
STATUS_OKThe callback was registered successfully.

References Assert, and STATUS_OK.

enum status_code usb_host_unregister_callback ( struct usb_module module_inst,
enum usb_host_callback  callback_type 
)

Unregisters a USB host callback.

Unregisters an asynchronous callback implemented by the user. Removing it from the internal callback registration table.

Parameters
[in]module_instPointer to USB software instance struct
[in]callback_typeCallback type given by an enum
Returns
Status of the de-registration operation.
Return values
STATUS_OKThe callback was unregistered successfully.

References Assert, and STATUS_OK.

enum status_code usb_init ( struct usb_module module_inst,
Usb *const  hw,
struct usb_config module_config 
)

const uint16_t _usb_device_irq_bits[USB_DEVICE_CALLBACK_N]
static
Initial value:
= {
USB_DEVICE_INTFLAG_SOF,
USB_DEVICE_INTFLAG_EORST,
USB_DEVICE_INTFLAG_WAKEUP | USB_DEVICE_INTFLAG_EORSM | USB_DEVICE_INTFLAG_UPRSM,
USB_DEVICE_INTFLAG_RAMACER,
USB_DEVICE_INTFLAG_SUSPEND,
USB_DEVICE_INTFLAG_LPMNYET,
USB_DEVICE_INTFLAG_LPMSUSP,
}

USB Device IRQ Mask Bits Map

const uint8_t _usb_endpoint_irq_bits[USB_DEVICE_EP_CALLBACK_N]
static
Initial value:
= {
USB_DEVICE_EPINTFLAG_TRCPT_Msk,
USB_DEVICE_EPINTFLAG_TRFAIL_Msk,
USB_DEVICE_EPINTFLAG_RXSTP,
USB_DEVICE_EPINTFLAG_STALL_Msk
}

USB Device IRQ Mask Bits Map

struct usb_module* _usb_instances
static

Local USB module instance.

uint32_t device_callback_lpm_wakeup_enable
static
struct usb_endpoint_callback_parameter ep_callback_para
static

Device endpoint callback parameter variable, used to transfer info to UDD wrapper layer.

Referenced by _usb_device_interrupt_handler().

uint32_t host_pipe_job_busy_status = 0

Bit mask for pipe job busy status.

struct usb_pipe_callback_parameter pipe_callback_para
static

Host pipe callback structure variable.

Referenced by _usb_host_interrupt_handler().

UsbDeviceDescriptor usb_endpoint_table[USB_EPT_NUM]
UsbHostDescriptor usb_pipe_table[USB_PIPE_NUM]