Software APIs
Data Structures | Macros | Typedefs | Enumerations | Functions
dif_usbdev.h File Reference

(8a1a5fe)

USB Device Device Interface Functions More...

#include <stddef.h>
#include <stdint.h>
#include "sw/device/lib/base/macros.h"
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_base.h"
#include "sw/device/lib/dif/autogen/dif_usbdev_autogen.h"

Go to the source code of this file.

Data Structures

struct  dif_usbdev_endpoint_id
 
struct  dif_usbdev_buffer_pool
 Free buffer pool. More...
 
struct  dif_usbdev_buffer
 A USB device buffer. More...
 
struct  dif_usbdev_config
 Configuration for initializing a USB device. More...
 
struct  dif_usbdev_rx_packet_info
 Information about a received packet. More...
 
struct  dif_usbdev_wake_status
 
struct  dif_usbdev_phy_pins_sense
 
struct  dif_usbdev_phy_pins_drive
 

Macros

#define USBDEV_NUM_ENDPOINTS   12
 Hardware constants.
 
#define USBDEV_MAX_PACKET_SIZE   64
 
#define USBDEV_NUM_BUFFERS   32
 
#define USBDEV_ENDPOINT_DIR_IN   1
 
#define USBDEV_ENDPOINT_DIR_OUT   0
 

Typedefs

typedef struct dif_usbdev_endpoint_id dif_usbdev_endpoint_id_t
 
typedef struct dif_usbdev_buffer_pool dif_usbdev_buffer_pool_t
 Free buffer pool. More...
 
typedef enum dif_usbdev_buffer_type dif_usbdev_buffer_type_t
 Buffer types.
 
typedef struct dif_usbdev_buffer dif_usbdev_buffer_t
 A USB device buffer. More...
 
typedef struct dif_usbdev_config dif_usbdev_config_t
 Configuration for initializing a USB device.
 
typedef struct dif_usbdev_rx_packet_info dif_usbdev_rx_packet_info_t
 Information about a received packet.
 
typedef enum dif_usbdev_tx_status dif_usbdev_tx_status_t
 Status of an outgoing packet.
 
typedef enum dif_usbdev_link_state dif_usbdev_link_state_t
 USB link state.
 
typedef struct dif_usbdev_wake_status dif_usbdev_wake_status_t
 
typedef struct dif_usbdev_phy_pins_sense dif_usbdev_phy_pins_sense_t
 
typedef struct dif_usbdev_phy_pins_drive dif_usbdev_phy_pins_drive_t
 

Enumerations

enum  dif_usbdev_buffer_type {
  kDifUsbdevBufferTypeRead,
  kDifUsbdevBufferTypeWrite,
  kDifUsbdevBufferTypeStale
}
 Buffer types. More...
 
enum  dif_usbdev_tx_status {
  kDifUsbdevTxStatusNoPacket,
  kDifUsbdevTxStatusPending,
  kDifUsbdevTxStatusSent,
  kDifUsbdevTxStatusCancelled
}
 Status of an outgoing packet. More...
 
enum  dif_usbdev_link_state {
  kDifUsbdevLinkStateDisconnected,
  kDifUsbdevLinkStatePowered,
  kDifUsbdevLinkStatePoweredSuspended,
  kDifUsbdevLinkStateActive,
  kDifUsbdevLinkStateSuspended,
  kDifUsbdevLinkStateActiveNoSof,
  kDifUsbdevLinkStateResuming
}
 USB link state.
 

Functions

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_configure (const dif_usbdev_t *usbdev, dif_usbdev_buffer_pool_t *buffer_pool, dif_usbdev_config_t config)
 Configures a USB device with runtime information. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_fill_available_fifos (const dif_usbdev_t *usbdev, dif_usbdev_buffer_pool_t *buffer_pool)
 Fill the available buffer FIFO of a USB device. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_endpoint_setup_enable (const dif_usbdev_t *usbdev, uint8_t endpoint, dif_toggle_t new_state)
 Enable or disable reception of SETUP packets for an endpoint. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_endpoint_out_enable (const dif_usbdev_t *usbdev, uint8_t endpoint, dif_toggle_t new_state)
 Enable or disable reception of OUT packets for an active endpoint. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_endpoint_set_nak_out_enable (const dif_usbdev_t *usbdev, uint8_t endpoint, dif_toggle_t new_state)
 Enable or disable clearing the out_enable bit after completion of an OUT transaction to an endpoint. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_endpoint_stall_enable (const dif_usbdev_t *usbdev, dif_usbdev_endpoint_id_t endpoint, dif_toggle_t new_state)
 Enable or disable STALL for an endpoint. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_endpoint_stall_get (const dif_usbdev_t *usbdev, dif_usbdev_endpoint_id_t endpoint, bool *state)
 Get STALL state of an endpoint. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_endpoint_iso_enable (const dif_usbdev_t *usbdev, dif_usbdev_endpoint_id_t endpoint, dif_toggle_t new_state)
 Enable or disable isochronous mode for an endpoint. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_endpoint_enable (const dif_usbdev_t *usbdev, dif_usbdev_endpoint_id_t endpoint, dif_toggle_t new_state)
 Enable or disable an endpoint. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_interface_enable (const dif_usbdev_t *usbdev, dif_toggle_t new_state)
 Enable the USB interface of a USB device. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_recv (const dif_usbdev_t *usbdev, dif_usbdev_rx_packet_info_t *packet_info, dif_usbdev_buffer_t *buffer)
 Get the packet at the front of RX FIFO. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_buffer_read (const dif_usbdev_t *usbdev, dif_usbdev_buffer_pool_t *buffer_pool, dif_usbdev_buffer_t *buffer, uint8_t *dst, size_t dst_len, size_t *bytes_written)
 Read incoming packet payload. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_buffer_return (const dif_usbdev_t *usbdev, dif_usbdev_buffer_pool_t *buffer_pool, dif_usbdev_buffer_t *buffer)
 Return a buffer to the free buffer pool. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_buffer_request (const dif_usbdev_t *usbdev, dif_usbdev_buffer_pool_t *buffer_pool, dif_usbdev_buffer_t *buffer)
 Request a buffer for outgoing packet payload. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_buffer_write (const dif_usbdev_t *usbdev, dif_usbdev_buffer_t *buffer, const uint8_t *src, size_t src_len, size_t *bytes_written)
 Write outgoing packet payload. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_send (const dif_usbdev_t *usbdev, uint8_t endpoint, dif_usbdev_buffer_t *buffer)
 Mark a packet ready for transmission from an endpoint. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_get_tx_sent (const dif_usbdev_t *usbdev, uint16_t *sent)
 Get which IN endpoints have sent packets. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_clear_tx_status (const dif_usbdev_t *usbdev, dif_usbdev_buffer_pool_t *buffer_pool, uint8_t endpoint)
 Clear the TX state of the provided endpoint and restore its associated buffer to the pool. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_get_tx_status (const dif_usbdev_t *usbdev, uint8_t endpoint, dif_usbdev_tx_status_t *status)
 Get the status of a packet that has been queued to be sent from an endpoint. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_address_set (const dif_usbdev_t *usbdev, uint8_t addr)
 Set the address of a USB device. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_address_get (const dif_usbdev_t *usbdev, uint8_t *addr)
 Get the address of a USB device. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_data_toggle_out_read (const dif_usbdev_t *usbdev, uint16_t *toggles)
 Read the data toggle bits of the OUT endpoints. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_data_toggle_in_read (const dif_usbdev_t *usbdev, uint16_t *toggles)
 Read the data toggle bits of the IN endpoints. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_data_toggle_out_write (const dif_usbdev_t *usbdev, uint16_t mask, uint16_t state)
 Write to the data toggle bits of a subset of the OUT endpoints. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_data_toggle_in_write (const dif_usbdev_t *usbdev, uint16_t mask, uint16_t state)
 Write to the data toggle bits of a subset of the IN endpoints. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_clear_data_toggle (const dif_usbdev_t *usbdev, uint8_t endpoint)
 Clear the data toggle bits for the selected endpoint. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_status_get_frame (const dif_usbdev_t *usbdev, uint16_t *frame_index)
 Get USB frame index. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_status_get_host_lost (const dif_usbdev_t *usbdev, bool *host_lost)
 Check if the host is lost. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_status_get_link_state (const dif_usbdev_t *usbdev, dif_usbdev_link_state_t *link_state)
 Get USB link state. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_status_get_sense (const dif_usbdev_t *usbdev, bool *sense)
 Get the state of the sense pin. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_status_get_available_fifo_depths (const dif_usbdev_t *usbdev, uint8_t *setup_depth, uint8_t *out_depth)
 Get the depths of the AV OUT and AV SETUP FIFOs. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_status_get_available_fifo_full (const dif_usbdev_t *usbdev, bool *setup_is_full, bool *out_is_full)
 Check if AV OUT and AV SETUP FIFOs are full. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_status_get_rx_fifo_depth (const dif_usbdev_t *usbdev, uint8_t *depth)
 Get the depth of the RX FIFO. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_status_get_rx_fifo_empty (const dif_usbdev_t *usbdev, bool *is_empty)
 Check if the RX FIFO is empty. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_set_osc_test_mode (const dif_usbdev_t *usbdev, dif_toggle_t enable)
 Control whether oscillator test mode is enabled. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_set_wake_enable (const dif_usbdev_t *usbdev, dif_toggle_t enable)
 Control whether the AON wake module is active. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_get_wake_status (const dif_usbdev_t *usbdev, dif_usbdev_wake_status_t *status)
 Get the status of the AON wake module. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_resume_link_to_active (const dif_usbdev_t *usbdev)
 Force the link state machine to resume to an active state. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_get_phy_pins_status (const dif_usbdev_t *usbdev, dif_usbdev_phy_pins_sense_t *status)
 Get the current state of the USB PHY pins. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_set_phy_pins_state (const dif_usbdev_t *usbdev, dif_toggle_t override_enable, dif_usbdev_phy_pins_drive_t overrides)
 Control whether to override the USB PHY and drive pins as GPIOs. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_buffer_raw_write (const dif_usbdev_t *usbdev, uint8_t id, const uint8_t *src, size_t src_len)
 Raw data transfer directly to the packet buffer memory. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_buffer_raw_read (const dif_usbdev_t *usbdev, uint8_t id, uint8_t *dst, size_t dst_len)
 Raw data transfer directly from the packet buffer memory. More...
 

Detailed Description

USB Device Device Interface Functions

Definition in file dif_usbdev.h.


Data Structure Documentation

◆ dif_usbdev_endpoint_id

struct dif_usbdev_endpoint_id

Definition at line 39 of file dif_usbdev.h.

Data Fields
unsigned int direction: 1 Endpoint direction.

1 = IN endpoint, 0 = OUT endpoint

unsigned int number: 4 Endpoint number.
unsigned int reserved: 3 Reserved.

Should be zero.

◆ dif_usbdev_buffer_pool

struct dif_usbdev_buffer_pool

Free buffer pool.

A USB device has a fixed number of buffers that are used for storing incoming and outgoing packets and the software is responsible for keeping track of free buffers. The pool is implemented as a stack for constant-time add and remove. top points to the last free buffer added to the pool. The pool is full when top == USBDEV_NUM_BUFFERS - 1 and empty when top == -1.

Definition at line 63 of file dif_usbdev.h.

Data Fields
uint8_t buffers[USBDEV_NUM_BUFFERS]
int8_t top

◆ dif_usbdev_buffer

struct dif_usbdev_buffer

A USB device buffer.

This struct represents a USB device buffer that has been provided to a client in response to a buffer request. Clients should treat instances of this struct as opaque objects and should pass them to the appropriate functions of this library to read and write payloads of incoming and outgoing packets, respectively.

See also: dif_usbdev_recv, dif_usbdev_buffer_read, dif_usbdev_buffer_request, dif_usbdev_buffer_write, dif_usbdev_send, dif_usbdev_buffer_return.

Definition at line 101 of file dif_usbdev.h.

Data Fields
uint8_t id Hardware buffer id.
uint8_t offset Byte offset for the next read or write operation.
uint8_t remaining_bytes For read buffers: remaining number of bytes to read.

For write buffers: remaining number of bytes that can be written.

dif_usbdev_buffer_type_t type Type of this buffer.

◆ dif_usbdev_config

struct dif_usbdev_config

Configuration for initializing a USB device.

Definition at line 124 of file dif_usbdev.h.

Data Fields
dif_toggle_t clock_sync_signals Reference signal generation for clock synchronization.
dif_toggle_t have_differential_receiver Activate the single-ended D signal for detecting K and J symbols, for use with a differential receiver.
dif_toggle_t pin_flip Flip the D+/D- pins.
dif_toggle_t single_bit_eop
dif_toggle_t use_tx_d_se0 Use the TX interface with D and SE0 signals instead of Dp/Dn, for use with certain transceivers.

◆ dif_usbdev_rx_packet_info

struct dif_usbdev_rx_packet_info

Information about a received packet.

Definition at line 320 of file dif_usbdev.h.

Data Fields
uint8_t endpoint Endpoint of the packet.
bool is_setup Indicates if the packet is a SETUP packet.
uint8_t length Payload length in bytes.

◆ dif_usbdev_wake_status

struct dif_usbdev_wake_status

Definition at line 819 of file dif_usbdev.h.

Data Fields
bool active Whether the AON wake module is active.
bool bus_reset Whether the USB was reset while the AON wake module was active.
bool disconnected Whether the USB disconnected while the AON wake module was active.

◆ dif_usbdev_phy_pins_sense

struct dif_usbdev_phy_pins_sense

Definition at line 862 of file dif_usbdev.h.

Data Fields
bool output_enable: 1 USB output enable for D+ / D-.
bool rx_d: 1 USB data input from an external differential receiver, if available.
bool rx_dn: 1 USB D- input.
bool rx_dp: 1 USB D+ input.
bool tx_d: 1 USB transmit data value output.
bool tx_dn: 1 USB transmit D- output.
bool tx_dp: 1 USB transmit D+ output.
bool tx_se0: 1 USB single-ended zero output.
bool vbus_sense: 1 USB VBUS sense pin.

◆ dif_usbdev_phy_pins_drive

struct dif_usbdev_phy_pins_drive

Definition at line 894 of file dif_usbdev.h.

Data Fields
bool data: 1 USB data output, encoding K and J when se0 is 0.
bool diff_receiver_enable: 1 Enable control pin for the differential receiver.
bool dn: 1 USB D- output.

for use with dp.

bool dn_pullup_en: 1 Controls whether to pull up the D- pin.
bool dp: 1 USB D+ output, for use with dn.
bool dp_pullup_en: 1 Controls whether to pull up the D+ pin.
bool output_enable: 1 USB output enable for D+ / D-.
bool se0: 1 USB single-ended zero output.

Typedef Documentation

◆ dif_usbdev_buffer_pool_t

Free buffer pool.

A USB device has a fixed number of buffers that are used for storing incoming and outgoing packets and the software is responsible for keeping track of free buffers. The pool is implemented as a stack for constant-time add and remove. top points to the last free buffer added to the pool. The pool is full when top == USBDEV_NUM_BUFFERS - 1 and empty when top == -1.

◆ dif_usbdev_buffer_t

A USB device buffer.

This struct represents a USB device buffer that has been provided to a client in response to a buffer request. Clients should treat instances of this struct as opaque objects and should pass them to the appropriate functions of this library to read and write payloads of incoming and outgoing packets, respectively.

See also: dif_usbdev_recv, dif_usbdev_buffer_read, dif_usbdev_buffer_request, dif_usbdev_buffer_write, dif_usbdev_send, dif_usbdev_buffer_return.

Enumeration Type Documentation

◆ dif_usbdev_buffer_type

Buffer types.

Enumerator
kDifUsbdevBufferTypeRead 

For reading payloads of incoming packets.

kDifUsbdevBufferTypeWrite 

For writing payloads of outgoing packets.

kDifUsbdevBufferTypeStale 

Clients must not use a buffer after it is handed over to hardware or returned to the free buffer pool.

This type exists to protect against such cases.

Definition at line 71 of file dif_usbdev.h.

◆ dif_usbdev_tx_status

Status of an outgoing packet.

Enumerator
kDifUsbdevTxStatusNoPacket 

There is no packet for the given OUT endpoint.

kDifUsbdevTxStatusPending 

Packet is pending transmission.

kDifUsbdevTxStatusSent 

Packet was sent successfully.

kDifUsbdevTxStatusCancelled 

Transmission was canceled due to an incoming SETUP packet.

Definition at line 555 of file dif_usbdev.h.

Function Documentation

◆ dif_usbdev_address_get()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_address_get ( const dif_usbdev_t usbdev,
uint8_t *  addr 
)

Get the address of a USB device.

Parameters
usbdevA USB device.
[out]addrCurrent address.
Returns
The result of the operation.

Definition at line 674 of file dif_usbdev.c.

◆ dif_usbdev_address_set()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_address_set ( const dif_usbdev_t usbdev,
uint8_t  addr 
)

Set the address of a USB device.

Parameters
usbdevA USB device.
addrNew address. Only the last 7 bits are significant.
Returns
The result of the operation.

Definition at line 660 of file dif_usbdev.c.

◆ dif_usbdev_buffer_raw_read()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_buffer_raw_read ( const dif_usbdev_t usbdev,
uint8_t  id,
uint8_t *  dst,
size_t  dst_len 
)

Raw data transfer directly from the packet buffer memory.

This is a faster implementation of the generic mmio_memcpy_from_mmio32 that is specialized for the USB device and gives a significant performance improvemenet.

Parameters
usbdevA USB device.
idBuffer number.
dstDestination buffer.
dst_lenNumber of bytes to transfer.
Returns
The result of the operation.

Definition at line 1071 of file dif_usbdev.c.

◆ dif_usbdev_buffer_raw_write()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_buffer_raw_write ( const dif_usbdev_t usbdev,
uint8_t  id,
const uint8_t *  src,
size_t  src_len 
)

Raw data transfer directly to the packet buffer memory.

This is a faster implementation of the generic mmio_memcpy_to_mmio32 that is specialized for the USB device and gives a significant performance improvement.

Parameters
usbdevA USB device.
idBuffer number.
srcSource data.
src_lenNumber of bytes to transfer.
Returns
The result of the operation.

Definition at line 1017 of file dif_usbdev.c.

◆ dif_usbdev_buffer_read()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_buffer_read ( const dif_usbdev_t usbdev,
dif_usbdev_buffer_pool_t buffer_pool,
dif_usbdev_buffer_t buffer,
uint8_t *  dst,
size_t  dst_len,
size_t *  bytes_written 
)

Read incoming packet payload.

Clients should call this function with a buffer provided by dif_usbdev_recv to read the payload of an incoming packet. This function copies the smaller of dst_len and remaining number of bytes in the buffer to dst. The buffer that holds the packet payload is returned to the free buffer pool when the entire packet payload is read.

See also: dif_usbdev_recv.

Parameters
usbdevA USB device.
buffer_poolA USB device buffer pool.
bufferA buffer provided by dif_usbdev_recv.
[out]dstDestination buffer.
dst_lenLength of the destination buffer.
[out]bytes_writtenNumber of bytes written to destination buffer.
Returns
The result of the operation.

Definition at line 477 of file dif_usbdev.c.

◆ dif_usbdev_buffer_request()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_buffer_request ( const dif_usbdev_t usbdev,
dif_usbdev_buffer_pool_t buffer_pool,
dif_usbdev_buffer_t buffer 
)

Request a buffer for outgoing packet payload.

Clients should call this function to request a buffer to write the payload of an outgoing packet. Sending a packet from a particular endpoint to the host involves four main steps:

  • Calling this function, i.e. dif_usbdev_buffer_request,
  • Calling dif_usbdev_buffer_write,
  • Calling dif_usbdev_send, and
  • Calling dif_usbdev_get_tx_status.

In order to send a packet, clients should first call this function to obtain a buffer for the packet payload. Clients should then call dif_usbdev_buffer_write (one or more times depending on the sizes of their internal buffers) to write the packet payload to this buffer. After writing the packet payload, clients should call dif_usbdev_send to mark the packet as ready for transmission from a particular endpoint. Then, clients should call dif_usbdev_get_tx_status to check the status of the transmission. dif_usbdev_get_tx_status returns the buffer that holds the packet payload to the free buffer pool once the packet is either successfully transmitted or canceled due to an incoming SETUP packet or a link reset. If the packet should no longer be sent, clients can call dif_usbdev_buffer_return to return the buffer to the free buffer pool as long as dif_usbdev_send is not called yet.

See also: dif_usbdev_buffer_write, dif_usbdev_send, dif_usbdev_get_tx_status, dif_usbdev_buffer_return.

Parameters
usbdevA USB device.
buffer_poolA USB device buffer pool.
[out]bufferA buffer for writing outgoing packet payload.
Returns
The result of the operation.

Definition at line 429 of file dif_usbdev.c.

◆ dif_usbdev_buffer_return()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_buffer_return ( const dif_usbdev_t usbdev,
dif_usbdev_buffer_pool_t buffer_pool,
dif_usbdev_buffer_t buffer 
)

Return a buffer to the free buffer pool.

This function immediately returns the given buffer to the free buffer pool. Since dif_usbdev_buffer_read and dif_usbdev_get_tx_status return the buffers that they work on to the free buffer pool automatically, this function should only be called to discard the payload of a received packet or a packet that was being prepared for transmission before it is queued for transmission from an endpoint.

See also: dif_usbdev_recv, dif_usbdev_buffer_request.

Parameters
usbdevA USB device.
buffer_poolA USB device buffer pool.
bufferA buffer provided by dif_usbdev_recv or dif_usbdev_buffer_request.
Returns
The result of the operation.

Definition at line 455 of file dif_usbdev.c.

◆ dif_usbdev_buffer_write()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_buffer_write ( const dif_usbdev_t usbdev,
dif_usbdev_buffer_t buffer,
const uint8_t *  src,
size_t  src_len,
size_t *  bytes_written 
)

Write outgoing packet payload.

Clients should call this function with a buffer provided by dif_usbdev_buffer_request to write the payload of an outgoing packet. This function copies the smaller of src_len and remaining number of bytes in the buffer to the buffer. Clients should then call dif_usbdev_send to queue the packet for transmission from a particular endpoint.

See also: dif_usbdev_buffer_request, dif_usbdev_send, dif_usbdev_get_tx_status, dif_usbdev_buffer_return.

Parameters
usbdevA USB device.
bufferA buffer provided by dif_usbdev_buffer_request.
srcSource buffer.
src_lenLength of the source buffer.
[out]bytes_writtenNumber of bytes written to the USB device buffer.
Returns
The result of the operation.

Definition at line 518 of file dif_usbdev.c.

◆ dif_usbdev_clear_data_toggle()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_clear_data_toggle ( const dif_usbdev_t usbdev,
uint8_t  endpoint 
)

Clear the data toggle bits for the selected endpoint.

Parameters
usbdevA USB device.
endpointAn endpoint number.
Returns
The result of the operation.

Definition at line 742 of file dif_usbdev.c.

◆ dif_usbdev_clear_tx_status()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_clear_tx_status ( const dif_usbdev_t usbdev,
dif_usbdev_buffer_pool_t buffer_pool,
uint8_t  endpoint 
)

Clear the TX state of the provided endpoint and restore its associated buffer to the pool.

Note that this function should only be called when an endpoint has been provided a buffer. Without it, the buffer pool will become corrupted, as this function does not check the status.

In addition, if the endpoint has not yet completed or canceled the transaction, the user must not call this function while the device is in an active state. Otherwise, the user risks corrupting an ongoing transaction.

Parameters
usbdevA USB device.
buffer_poolA USB device buffer pool.
endpointAn IN endpoint number.
Returns
The result of the operation.

Definition at line 598 of file dif_usbdev.c.

◆ dif_usbdev_configure()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_configure ( const dif_usbdev_t usbdev,
dif_usbdev_buffer_pool_t buffer_pool,
dif_usbdev_config_t  config 
)

Configures a USB device with runtime information.

This function should need to be called once for the lifetime of handle.

Parameters
usbdevA USB device.
buffer_poolA USB device buffer pool.
configRuntime configuration parameters for a USB device.
Returns
The result of the operation.

Configures a USB device with runtime information.

Definition at line 213 of file dif_usbdev.c.

◆ dif_usbdev_data_toggle_in_read()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_data_toggle_in_read ( const dif_usbdev_t usbdev,
uint16_t *  toggles 
)

Read the data toggle bits of the IN endpoints.

Parameters
usbdevA USB device.
[out]

Definition at line 702 of file dif_usbdev.c.

◆ dif_usbdev_data_toggle_in_write()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_data_toggle_in_write ( const dif_usbdev_t usbdev,
uint16_t  mask,
uint16_t  state 
)

Write to the data toggle bits of a subset of the IN endpoints.

Set 1 in mask to change the data toggle bit of an IN endpoint to the value of the corresponding bit in state.

Parameters
usbdevA USB device.
maskMask of IN endpoint data toggles to be changed.
stateNew states of that IN endpoint data toggles being changed.
Returns
The result of the operation.

Definition at line 729 of file dif_usbdev.c.

◆ dif_usbdev_data_toggle_out_read()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_data_toggle_out_read ( const dif_usbdev_t usbdev,
uint16_t *  toggles 
)

Read the data toggle bits of the OUT endpoints.

Parameters
usbdevA USB device.
[out]

Definition at line 688 of file dif_usbdev.c.

◆ dif_usbdev_data_toggle_out_write()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_data_toggle_out_write ( const dif_usbdev_t usbdev,
uint16_t  mask,
uint16_t  state 
)

Write to the data toggle bits of a subset of the OUT endpoints.

Set 1 in mask to change the data toggle bit of an OUT endpoint to the value of the corresponding bit in state.

Parameters
usbdevA USB device.
maskMask of OUT endpoint data toggles to be changed.
stateNew states of that OUT endpoint data toggles being changed.
Returns
The result of the operation.

Definition at line 716 of file dif_usbdev.c.

◆ dif_usbdev_endpoint_enable()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_endpoint_enable ( const dif_usbdev_t usbdev,
dif_usbdev_endpoint_id_t  endpoint,
dif_toggle_t  new_state 
)

Enable or disable an endpoint.

An enabled endpoint responds to packets from the host. A disabled endpoint ignores them.

Parameters
usbdevA USB device.
endpointAn endpoint.
new_stateNew endpoint state.
Returns
The result of the operation.

Definition at line 364 of file dif_usbdev.c.

◆ dif_usbdev_endpoint_iso_enable()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_endpoint_iso_enable ( const dif_usbdev_t usbdev,
dif_usbdev_endpoint_id_t  endpoint,
dif_toggle_t  new_state 
)

Enable or disable isochronous mode for an endpoint.

Isochronous endpoints transfer data periodically. Since isochronous transfers do not have a handshaking stage, isochronous endpoints cannot report errors or STALL conditions.

Parameters
usbdevA USB device.
endpointAn endpoint.
new_stateNew isochronous state.
Returns
The result of the operation.

Definition at line 352 of file dif_usbdev.c.

◆ dif_usbdev_endpoint_out_enable()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_endpoint_out_enable ( const dif_usbdev_t usbdev,
uint8_t  endpoint,
dif_toggle_t  new_state 
)

Enable or disable reception of OUT packets for an active endpoint.

When disabling reception of OUT packets, what the endpoint will do depends on other factors. If the endpoint is currently configured as a control endpoint (receives SETUP packets) or it is configured as an isochronous endpoint, disabling reception of OUT packets will cause them to be ignored.

If the endpoint is neither a control nor isochronous endpoint, then its behavior depends on whether it is configured to respond with STALL. If the STALL response is not active, then disabling reception will cause usbdev to NAK the packet. Otherwise, the STALL response takes priority, regardless of the setting here.

Parameters
usbdevA USB device.
endpointAn OUT endpoint number.
new_stateNew OUT packet reception state.
Returns
The result of the operation.

Definition at line 309 of file dif_usbdev.c.

◆ dif_usbdev_endpoint_set_nak_out_enable()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_endpoint_set_nak_out_enable ( const dif_usbdev_t usbdev,
uint8_t  endpoint,
dif_toggle_t  new_state 
)

Enable or disable clearing the out_enable bit after completion of an OUT transaction to an endpoint.

If set_nak_out is enabled, an OUT endpoint will disable reception of OUT packets after each successful OUT transaction to that endpoint, requiring a call to dif_usbdev_endpoint_out_enable() to enable reception again.

Parameters
usbdevA USB device.
endpointAn OUT endpoint number.
new_stateNew set_nak_on_out state.
Returns
The result of the operation.

Definition at line 316 of file dif_usbdev.c.

◆ dif_usbdev_endpoint_setup_enable()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_endpoint_setup_enable ( const dif_usbdev_t usbdev,
uint8_t  endpoint,
dif_toggle_t  new_state 
)

Enable or disable reception of SETUP packets for an endpoint.

This controls whether the pair of IN and OUT endpoints with the specified endpoint number are control endpoints.

Parameters
usbdevA USB device.
endpointAn endpoint number.
new_stateNew SETUP packet reception state.
Returns
The result of the operation.

Definition at line 302 of file dif_usbdev.c.

◆ dif_usbdev_endpoint_stall_enable()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_endpoint_stall_enable ( const dif_usbdev_t usbdev,
dif_usbdev_endpoint_id_t  endpoint,
dif_toggle_t  new_state 
)

Enable or disable STALL for an endpoint.

Parameters
usbdevA USB device.
endpointAn endpoint ID.
new_stateNew STALL state.
Returns
The result of the operation.

Definition at line 323 of file dif_usbdev.c.

◆ dif_usbdev_endpoint_stall_get()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_endpoint_stall_get ( const dif_usbdev_t usbdev,
dif_usbdev_endpoint_id_t  endpoint,
bool *  state 
)

Get STALL state of an endpoint.

Parameters
usbdevA USB device.
endpointAn endpoint ID.
[out]stateCurrent STALL state.
Returns
The result of the operation.

Definition at line 335 of file dif_usbdev.c.

◆ dif_usbdev_fill_available_fifos()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_fill_available_fifos ( const dif_usbdev_t usbdev,
dif_usbdev_buffer_pool_t buffer_pool 
)

Fill the available buffer FIFO of a USB device.

The USB device has a small FIFO (AV FIFO) that stores free buffers for incoming packets. It is the responsibility of the software to ensure that the AV FIFO is never empty. If the host tries to send a packet when the AV FIFO is empty, the USB device will respond with a NAK. While this will typically cause the host to retry transmission for regular data packets, there are transactions in the USB protocol during which the USB device is not allowed to send a NAK. Thus, the software must make sure that the AV FIFO is never empty by calling this function periodically.

Parameters
usbdevA USB device.
buffer_poolA USB device buffer pool.
Returns
The result of the operation.

Definition at line 259 of file dif_usbdev.c.

◆ dif_usbdev_get_phy_pins_status()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_get_phy_pins_status ( const dif_usbdev_t usbdev,
dif_usbdev_phy_pins_sense_t status 
)

Get the current state of the USB PHY pins.

Parameters
usbdevA USB device.
[out]statusThe current state of the pins.
Returns
The result of the operation.

Definition at line 956 of file dif_usbdev.c.

◆ dif_usbdev_get_tx_sent()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_get_tx_sent ( const dif_usbdev_t usbdev,
uint16_t *  sent 
)

Get which IN endpoints have sent packets.

This function provides which endpoints have buffers that have successfully completed transmission to the host. It may be used to guide calls to dif_usbdev_clear_tx_status to return the used buffer to the pool and clear the state for the next transaction.

Parameters
usbdevA USB device.
[out]sentA bitmap of which endpoints have sent packets.
Returns
The result of the operation.

Definition at line 588 of file dif_usbdev.c.

◆ dif_usbdev_get_tx_status()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_get_tx_status ( const dif_usbdev_t usbdev,
uint8_t  endpoint,
dif_usbdev_tx_status_t status 
)

Get the status of a packet that has been queued to be sent from an endpoint.

While the USB device handles transmission errors automatically by retrying transmission, transmission of a packet may be canceled if the endpoint receives a SETUP packet or the link is reset before the queued packet is transmitted. In these cases, clients should handle the SETUP packet or the link reset first and then optionally send the same packet again.

This function does not modify any device state. dif_usbdev_clear_tx_status can be used to clear the status and return the buffer to the pool.

Parameters
usbdevA USB device.
endpointAn IN endpoint number.
[out]statusStatus of the packet.
Returns
The result of the operation.

Definition at line 624 of file dif_usbdev.c.

◆ dif_usbdev_get_wake_status()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_get_wake_status ( const dif_usbdev_t usbdev,
dif_usbdev_wake_status_t status 
)

Get the status of the AON wake module.

Note that the conditions triggering exit from suspended state must be read before disabling the AON wake module. Once the AON wake module is deactivated, that status information is lost.

Also note that the ordinary resume condition does not report to the usbdev module. Instead, it should be obtained from the module monitoring wakeup sources.

Parameters
usbdevA USB device.
[out]statusThe status of the module.
Returns
The result of the operation.

Definition at line 928 of file dif_usbdev.c.

◆ dif_usbdev_interface_enable()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_interface_enable ( const dif_usbdev_t usbdev,
dif_toggle_t  new_state 
)

Enable the USB interface of a USB device.

Calling this function causes the USB device to assert the full-speed pull-up signal to indicate its presence to the host. Ensure the default endpoint is set up before enabling the interface.

Parameters
usbdevA USB device.
new_stateNew interface state.
Returns
The result of the operation.

Definition at line 377 of file dif_usbdev.c.

◆ dif_usbdev_recv()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_recv ( const dif_usbdev_t usbdev,
dif_usbdev_rx_packet_info_t packet_info,
dif_usbdev_buffer_t buffer 
)

Get the packet at the front of RX FIFO.

The USB device has a small FIFO (RX FIFO) that stores received packets until the software has a chance to process them. It is the responsibility of the software to ensure that the RX FIFO is never full. If the host tries to send a packet when the RX FIFO is full, the USB device will respond with a NAK. While this will typically cause the host to retry transmission for regular data packets, there are transactions in the USB protocol during which the USB device is not allowed to send a NAK. Thus, the software must read received packets as soon as possible.

Reading received packets involves two main steps:

  • Calling this function, i.e. dif_usbdev_recv, and
  • Calling dif_usbdev_buffer_read until the entire packet payload is read.

In order to read an incoming packet, clients should first call this function to get information about the packet and the buffer that holds the packet payload. Then, clients should call dif_usbdev_buffer_read with this buffer one or more times (depending on the sizes of their internal buffers) until the entire packet payload is read. Once the entire payload is read, the buffer is returned to the free buffer pool. If the clients want to ignore the payload of a packet, e.g. for an unsupported or a zero-length packet, they can call dif_usbdev_buffer_return to immediately return the buffer to the free buffer pool.

Parameters
usbdevA USB device.
[out]packet_infoPacket information.
[out]bufferBuffer that holds the packet payload.
Returns
The result of the operation.

Definition at line 392 of file dif_usbdev.c.

◆ dif_usbdev_resume_link_to_active()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_resume_link_to_active ( const dif_usbdev_t usbdev)

Force the link state machine to resume to an active state.

This is used when waking from a low-power suspended state to resume to an active state. It moves the usbdev out of the Powered state (from the USB device state machine in the spec) without receiving a bus reset. Without help from software, the usbdev module cannot determine on its own when a bus reset is required.

Parameters
usbdevA USB device.
Returns
The result of the operation.

Definition at line 944 of file dif_usbdev.c.

◆ dif_usbdev_send()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_send ( const dif_usbdev_t usbdev,
uint8_t  endpoint,
dif_usbdev_buffer_t buffer 
)

Mark a packet ready for transmission from an endpoint.

The USB device has 12 endpoints, each of which can be used to send packets to the host. Since a packet is not actually transmitted to the host until the host sends an IN token, clients must write the packet payload to a device buffer and mark it as ready for transmission from a particular endpoint. A packet queued for transmission from a particular endpoint is transmitted once the host sends an IN token for that endpoint.

After a packet is queued for transmission, clients should check its status by calling dif_usbdev_get_tx_status. While the USB device handles transmission errors automatically by retrying transmission, transmission of a packet may be canceled if the endpoint receives a SETUP packet or the link is reset before the queued packet is transmitted. In these cases, clients should handle the SETUP packet or the link reset first and then optionally send the same packet again. Clients must also make sure that the given endpoint does not already have a packet pending for transmission before calling this function.

See also: dif_usbdev_buffer_request, dif_usbdev_buffer_write, dif_usbdev_get_tx_status, dif_usbdev_buffer_return.

Parameters
usbdevA USB device.
endpointAn OUT endpoint number.
bufferA buffer provided by dif_usbdev_buffer_request.
Returns
The result of the operation.

Definition at line 552 of file dif_usbdev.c.

◆ dif_usbdev_set_osc_test_mode()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_set_osc_test_mode ( const dif_usbdev_t usbdev,
dif_toggle_t  enable 
)

Control whether oscillator test mode is enabled.

In oscillator test mode, usbdev transmits a continuous 0101 pattern for evaluating the reference clock's quality.

Parameters
usbdevA USB device.
enableWhether the test mode should be enabled.
Returns
The result of the operation.

Definition at line 897 of file dif_usbdev.c.

◆ dif_usbdev_set_phy_pins_state()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_set_phy_pins_state ( const dif_usbdev_t usbdev,
dif_toggle_t  override_enable,
dif_usbdev_phy_pins_drive_t  overrides 
)

Control whether to override the USB PHY and drive pins as GPIOs.

Parameters
usbdevA USB device.
override_enableEnable / disable the GPIO-like overrides.
overridesThe values to set the pins to.
Returns
The result of the operation.

Definition at line 982 of file dif_usbdev.c.

◆ dif_usbdev_set_wake_enable()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_set_wake_enable ( const dif_usbdev_t usbdev,
dif_toggle_t  enable 
)

Control whether the AON wake module is active.

Parameters
usbdevA USB device.
enableWhether the AON wake module is enabled.
Returns
The result of the operation.

Definition at line 911 of file dif_usbdev.c.

◆ dif_usbdev_status_get_available_fifo_depths()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_status_get_available_fifo_depths ( const dif_usbdev_t usbdev,
uint8_t *  setup_depth,
uint8_t *  out_depth 
)

Get the depths of the AV OUT and AV SETUP FIFOs.

See also: dif_usbdev_fill_available_fifos.

Parameters
usbdevA USB device.
[out]setup_depthDepth of the AV SETUP FIFO.
[out]out_depthDepth of the AV OUT FIFO.
Returns
The result of the operation.

Definition at line 836 of file dif_usbdev.c.

◆ dif_usbdev_status_get_available_fifo_full()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_status_get_available_fifo_full ( const dif_usbdev_t usbdev,
bool *  setup_is_full,
bool *  out_is_full 
)

Check if AV OUT and AV SETUP FIFOs are full.

See also: dif_usbdev_fill_available_fifos.

Parameters
usbdevA USB device.
[out]setup_is_fullState of the AV SETUP FIFO. true if full, false otherwise.
[out]out_is_fullState of the AV OUT FIFO. true if full, false otherwise.
Returns
The result of the operation.

Definition at line 854 of file dif_usbdev.c.

◆ dif_usbdev_status_get_frame()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_status_get_frame ( const dif_usbdev_t usbdev,
uint16_t *  frame_index 
)

Get USB frame index.

Parameters
usbdevA USB device.
[out]frame_indexUSB frame index.
Returns
The result of the operation.

Definition at line 757 of file dif_usbdev.c.

◆ dif_usbdev_status_get_host_lost()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_status_get_host_lost ( const dif_usbdev_t usbdev,
bool *  host_lost 
)

Check if the host is lost.

The host is lost if the link is still active but a start of frame packet has not been received in the last 4.096ms.

Parameters
usbdevA USB device.
[out]host_lostStatus of the host. true if the host is lost, false otherwise.
Returns
The result of the operation.

Definition at line 772 of file dif_usbdev.c.

◆ dif_usbdev_status_get_link_state()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_status_get_link_state ( const dif_usbdev_t usbdev,
dif_usbdev_link_state_t link_state 
)

Get USB link state.

Parameters
usbdevA USB device.
[out]link_stateUSB link state.
Returns
The result of the operation.

Definition at line 785 of file dif_usbdev.c.

◆ dif_usbdev_status_get_rx_fifo_depth()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_status_get_rx_fifo_depth ( const dif_usbdev_t usbdev,
uint8_t *  depth 
)

Get the depth of the RX FIFO.

See also: dif_usbdev_recv.

Parameters
usbdevA USB device.
[out]depthDepth of the RX FIFO.
Returns
The result of the operation.

Definition at line 869 of file dif_usbdev.c.

◆ dif_usbdev_status_get_rx_fifo_empty()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_status_get_rx_fifo_empty ( const dif_usbdev_t usbdev,
bool *  is_empty 
)

Check if the RX FIFO is empty.

See also: dif_usbdev_recv.

Parameters
usbdevA USB device.
[out]is_emptyState of the RX FIFO. true if empty, false otherwise.
Returns
The result of the operation.

Definition at line 884 of file dif_usbdev.c.

◆ dif_usbdev_status_get_sense()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_status_get_sense ( const dif_usbdev_t usbdev,
bool *  sense 
)

Get the state of the sense pin.

Parameters
usbdevA USB device.
[out]senseState of the sense pin. true if the host is providing VBUS, false otherwise.
Returns
The result of the operation.

Definition at line 824 of file dif_usbdev.c.