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

(dcee03a)

USB Device Device Interface Functions More...

#include <stddef.h>
#include <stdint.h>
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_warn_unused_result.h"

Go to the source code of this file.

Data Structures

struct  dif_usbdev_buffer_pool
 Free buffer pool. More...
 
struct  dif_usbdev_buffer
 A USB device buffer. More...
 
struct  dif_usbdev
 Internal state of a USB device. More...
 
struct  dif_usbdev_config
 Configuration for initializing a USB device. More...
 
struct  dif_usbdev_rx_packet_info
 Information about a received packet. More...
 

Macros

#define USBDEV_NUM_ENDPOINTS   12
 Hardware constants.
 
#define USBDEV_MAX_PACKET_SIZE   64
 
#define USBDEV_NUM_BUFFERS   32
 

Typedefs

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 dif_usbdev_t
 Internal state of a USB device. More...
 
typedef enum dif_usbdev_toggle dif_usbdev_toggle_t
 Enumeration for enabling/disabling various functionality.
 
typedef enum dif_usbdev_power_sense_override dif_usbdev_power_sense_override_t
 Set of allowed configurations for USB power sense override.
 
typedef struct dif_usbdev_config dif_usbdev_config_t
 Configuration for initializing a USB device.
 
typedef enum dif_usbdev_result dif_usbdev_result_t
 Common return codes for the functions in this library.
 
typedef struct dif_usbdev_rx_packet_info dif_usbdev_rx_packet_info_t
 Information about a received packet.
 
typedef enum dif_usbdev_recv_result dif_usbdev_recv_result_t
 Return codes for dif_usbdev_recv.
 
typedef enum dif_usbdev_buffer_read_result dif_usbdev_buffer_read_result_t
 Return codes for dif_usbdev_buffer_read.
 
typedef enum dif_usbdev_buffer_request_result dif_usbdev_buffer_request_result_t
 Return codes for dif_usbdev_buffer_request.
 
typedef enum dif_usbdev_buffer_write_result dif_usbdev_buffer_write_result_t
 
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 enum dif_usbdev_irq dif_usbdev_irq_t
 USB device interrupts.
 

Enumerations

enum  dif_usbdev_buffer_type {
  kDifUsbdevBufferTypeRead,
  kDifUsbdevBufferTypeWrite,
  kDifUsbdevBufferTypeStale
}
 Buffer types. More...
 
enum  dif_usbdev_toggle {
  kDifUsbdevToggleDisable,
  kDifUsbdevToggleEnable
}
 Enumeration for enabling/disabling various functionality.
 
enum  dif_usbdev_power_sense_override {
  kDifUsbdevPowerSenseOverrideDisabled,
  kDifUsbdevPowerSenseOverridePresent,
  kDifUsbdevPowerSenseOverrideNotPresent
}
 Set of allowed configurations for USB power sense override.
 
enum  dif_usbdev_result {
  kDifUsbdevOK = 0,
  kDifUsbdevError = 1,
  kDifUsbdevBadArg = 2
}
 Common return codes for the functions in this library. More...
 
enum  dif_usbdev_recv_result {
  kDifUsbdevRecvResultOK = kDifUsbdevOK,
  kDifUsbdevRecvResultError = kDifUsbdevError,
  kDifUsbdevRecvResultBadArg = kDifUsbdevBadArg,
  kDifUsbdevRecvResultNoNewPacket
}
 Return codes for dif_usbdev_recv. More...
 
enum  dif_usbdev_buffer_read_result {
  kDifUsbdevBufferReadResultOK,
  kDifUsbdevBufferReadResultError,
  kDifUsbdevBufferReadResultBadArg,
  kDifUsbdevBufferReadResultContinue
}
 Return codes for dif_usbdev_buffer_read. More...
 
enum  dif_usbdev_buffer_request_result {
  kDifUsbdevBufferRequestResultOK = kDifUsbdevOK,
  kDifUsbdevBufferRequestResultError = kDifUsbdevError,
  kDifUsbdevBufferRequestResultBadArg = kDifUsbdevBadArg,
  kDifUsbdevBufferRequestResultNoBuffers
}
 Return codes for dif_usbdev_buffer_request. More...
 
enum  dif_usbdev_buffer_write_result {
  kDifUsbdevBufferWriteResultOK = kDifUsbdevOK,
  kDifUsbdevBufferWriteResultError = kDifUsbdevError,
  kDifUsbdevBufferWriteResultBadArg = kDifUsbdevBadArg,
  kDifUsbdevBufferWriteResultFull
}
 
enum  dif_usbdev_tx_status {
  kDifUsbdevTxStatusNoPacket,
  kDifUsbdevTxStatusPending,
  kDifUsbdevTxStatusSent,
  kDifUsbdevTxStatusCancelled
}
 Status of an outgoing packet. More...
 
enum  dif_usbdev_link_state {
  kDifUsbdevLinkStateDisconnected,
  kDifUsbdevLinkStatePowered,
  kDifUsbdevLinkStatePoweredSuspend,
  kDifUsbdevLinkStateActive,
  kDifUsbdevLinkStateSuspend
}
 USB link state.
 
enum  dif_usbdev_irq {
  kDifUsbdevIrqFirst,
  kDifUsbdevIrqPktReceived = kDifUsbdevIrqFirst,
  kDifUsbdevIrqPktSent,
  kDifUsbdevIrqDisconnected,
  kDifUsbdevIrqHostLost,
  kDifUsbdevIrqLinkReset,
  kDifUsbdevIrqLinkSuspend,
  kDifUsbdevIrqLinkResume,
  kDifUsbdevIrqAvEmpty,
  kDifUsbdevIrqRxFull,
  kDifUsbdevIrqAvOverflow,
  kDifUsbdevIrqLinkInError,
  kDifUsbdevIrqRxCrcError,
  kDifUsbdevIrqRxPidError,
  kDifUsbdevIrqRxBitstuffError,
  kDifUsbdevIrqFrame,
  kDifUsbdevIrqConnected,
  kDifUsbdevIrqLast = kDifUsbdevIrqConnected
}
 USB device interrupts. More...
 

Functions

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_init (dif_usbdev_config_t *config, dif_usbdev_t *usbdev)
 Initialize a USB device. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_fill_available_fifo (dif_usbdev_t *usbdev)
 Fill the available buffer FIFO of a USB device. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_endpoint_setup_enable (dif_usbdev_t *usbdev, uint8_t endpoint, dif_usbdev_toggle_t new_state)
 Enable or disable reception of SETUP packets for an endpoint. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_endpoint_out_enable (dif_usbdev_t *usbdev, uint8_t endpoint, dif_usbdev_toggle_t new_state)
 Enable or disable reception of OUT packets for an endpoint. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_endpoint_stall_enable (dif_usbdev_t *usbdev, uint8_t endpoint, dif_usbdev_toggle_t new_state)
 Enable or disable STALL for an endpoint. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_endpoint_stall_get (dif_usbdev_t *usbdev, uint8_t endpoint, bool *state)
 Get STALL state of an endpoint. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_endpoint_iso_enable (dif_usbdev_t *usbdev, uint8_t endpoint, dif_usbdev_toggle_t new_state)
 Enable or disable isochronous mode for an endpoint. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_interface_enable (dif_usbdev_t *usbdev, dif_usbdev_toggle_t new_state)
 Enable the USB interface of a USB device. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_recv_result_t dif_usbdev_recv (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...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_buffer_read_result_t dif_usbdev_buffer_read (dif_usbdev_t *usbdev, dif_usbdev_buffer_t *buffer, uint8_t *dst, size_t dst_len, size_t *bytes_written)
 Read incoming packet payload. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_buffer_return (dif_usbdev_t *usbdev, dif_usbdev_buffer_t *buffer)
 Return a buffer to the free buffer pool. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_buffer_request_result_t dif_usbdev_buffer_request (dif_usbdev_t *usbdev, dif_usbdev_buffer_t *buffer)
 Request a buffer for outgoing packet payload. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_buffer_write_result_t dif_usbdev_buffer_write (dif_usbdev_t *usbdev, dif_usbdev_buffer_t *buffer, uint8_t *src, size_t src_len, size_t *bytes_written)
 Write outgoing packet payload. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_send (dif_usbdev_t *usbdev, uint8_t endpoint, dif_usbdev_buffer_t *buffer)
 Mark a packet ready for transmission from an endpoint. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_get_tx_status (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...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_address_set (dif_usbdev_t *usbdev, uint8_t addr)
 Set the address of a USB device. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_address_get (dif_usbdev_t *usbdev, uint8_t *addr)
 Get the address of a USB device. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_status_get_frame (dif_usbdev_t *usbdev, uint16_t *frame_index)
 Get USB frame index. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_status_get_host_lost (dif_usbdev_t *usbdev, bool *host_lost)
 Check if the host is lost. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_status_get_link_state (dif_usbdev_t *usbdev, dif_usbdev_link_state_t *link_state)
 Get USB link state. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_status_get_sense (dif_usbdev_t *usbdev, bool *sense)
 Get the state of the sense pin. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_status_get_available_fifo_depth (dif_usbdev_t *usbdev, uint8_t *depth)
 Get the depth of the AV FIFO. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_status_get_available_fifo_full (dif_usbdev_t *usbdev, bool *is_full)
 Check if AV FIFO is full. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_status_get_rx_fifo_depth (dif_usbdev_t *usbdev, uint8_t *depth)
 Get the depth of the RX FIFO. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_status_get_rx_fifo_empty (dif_usbdev_t *usbdev, bool *is_empty)
 Check if the RX FIFO is empty. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_irq_enable (dif_usbdev_t *usbdev, dif_usbdev_irq_t irq, dif_usbdev_toggle_t state)
 Enable or disable an interrupt. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_irq_get (dif_usbdev_t *usbdev, dif_usbdev_irq_t irq, bool *state)
 Check if there is a pending request for an interrupt. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_irq_clear (dif_usbdev_t *usbdev, dif_usbdev_irq_t irq)
 Clear an interrupt. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_irq_clear_all (dif_usbdev_t *usbdev)
 Clear all pending interrupts. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_irq_disable_all (dif_usbdev_t *usbdev, uint32_t *cur_config)
 Disable all interrupts and optionally return the current interrupt configuration. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_irq_restore (dif_usbdev_t *usbdev, uint32_t new_config)
 Restore interrupt configuration. More...
 
DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_irq_test (dif_usbdev_t *usbdev, dif_usbdev_irq_t irq)
 Test an interrupt. More...
 

Detailed Description

USB Device Device Interface Functions

Definition in file dif_usbdev.h.


Data Structure Documentation

◆ 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 40 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 78 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

struct dif_usbdev

Internal state of a USB device.

Instances of this struct must be initialized by dif_usbdev_init() before being passed to other functions in this library. Its fields should be considered private and are only provided here so that callers can allocate it.

Definition at line 106 of file dif_usbdev.h.

Data Fields
mmio_region_t base_addr
dif_usbdev_buffer_pool_t buffer_pool

◆ dif_usbdev_config

struct dif_usbdev_config

Configuration for initializing a USB device.

Definition at line 131 of file dif_usbdev.h.

Data Fields
mmio_region_t base_addr Base address of the USB device.
dif_usbdev_toggle_t clock_sync_signals Reference signal generation for clock synchronization.
dif_usbdev_toggle_t differential_rx Use the differential rx signal instead of the single-ended signals.
dif_usbdev_toggle_t differential_tx Use the differential tx signal instead of the single-ended signals.
dif_usbdev_toggle_t pin_flip Flip the D+/D- pins.
dif_usbdev_power_sense_override_t power_sense_override Override USB power sense.
dif_usbdev_toggle_t single_bit_eop

◆ dif_usbdev_rx_packet_info

struct dif_usbdev_rx_packet_info

Information about a received packet.

Definition at line 298 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.

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.

◆ dif_usbdev_t

typedef struct dif_usbdev dif_usbdev_t

Internal state of a USB device.

Instances of this struct must be initialized by dif_usbdev_init() before being passed to other functions in this library. Its fields should be considered private and are only provided here so that callers can allocate it.

Enumeration Type Documentation

◆ dif_usbdev_buffer_read_result

Return codes for dif_usbdev_buffer_read.

Enumerator
kDifUsbdevBufferReadResultOK 

Indicates that the call succeeded and the entire packet payload is read.

kDifUsbdevBufferReadResultError 

Indicates that a non-specific error occurred and the hardware is in an invalid or irrecoverable state.

kDifUsbdevBufferReadResultBadArg 

Indicates that the caller supplied invalid arguments but the call did not cause any side-effects and the hardware is in a valid and recoverable state.

kDifUsbdevBufferReadResultContinue 

Indicates that the call was successful but there are remaining bytes to be read.

Definition at line 378 of file dif_usbdev.h.

◆ dif_usbdev_buffer_request_result

Return codes for dif_usbdev_buffer_request.

Enumerator
kDifUsbdevBufferRequestResultOK 

Indicates that the call succeeded.

kDifUsbdevBufferRequestResultError 

Indicates that a non-specific error occurred and the hardware is in an invalid or irrecoverable state.

kDifUsbdevBufferRequestResultBadArg 

Indicates that the caller supplied invalid arguments but the call did not cause any side-effects and the hardware is in a valid and recoverable state.

kDifUsbdevBufferRequestResultNoBuffers 

Indicates that there are no free buffers.

Definition at line 448 of file dif_usbdev.h.

◆ 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 48 of file dif_usbdev.h.

◆ dif_usbdev_buffer_write_result

Enumerator
kDifUsbdevBufferWriteResultOK 

Indicates that the call succeeded.

kDifUsbdevBufferWriteResultError 

Indicates that a non-specific error occurred and the hardware is in an invalid or irrecoverable state.

kDifUsbdevBufferWriteResultBadArg 

Indicates that the caller supplied invalid arguments but the call did not cause any side-effects and the hardware is in a valid and recoverable state.

kDifUsbdevBufferWriteResultFull 

Indicates that the requested write exceeds the device buffer size.

Definition at line 506 of file dif_usbdev.h.

◆ dif_usbdev_irq

USB device interrupts.

Enumerator
kDifUsbdevIrqPktReceived 

A packet was received as part of an OUT or SETUP transaction.

kDifUsbdevIrqPktSent 

A packet was sent as part of an IN transaction.

kDifUsbdevIrqDisconnected 

VBUS was lost and the link was disconnected.

kDifUsbdevIrqHostLost 

A Start-of-Frame (SOF) packet was not received on an active link for 4.096 ms.

The host must send a SOF packet every 1 ms.

kDifUsbdevIrqLinkReset 

Link was reset by the host.

kDifUsbdevIrqLinkSuspend 

Link was suspended by the host.

kDifUsbdevIrqLinkResume 

Link became active again after being suspended.

kDifUsbdevIrqAvEmpty 

Available buffer FIFO was empty.

kDifUsbdevIrqRxFull 

Received buffer FIFO was full.

kDifUsbdevIrqAvOverflow 

A write was done to available buffer FIFO when it was full.

kDifUsbdevIrqLinkInError 

The ACK packet expected in response to an IN transaction was not received.

kDifUsbdevIrqRxCrcError 

A CRC error occurred.

kDifUsbdevIrqRxPidError 

A packet with an invalid packet identifier (PID) was received.

kDifUsbdevIrqRxBitstuffError 

A packet with invalid bitstuffing was received.

kDifUsbdevIrqFrame 

USB frame number was updated with a valid SOF packet.

kDifUsbdevIrqConnected 

VBUS was detected.

Definition at line 763 of file dif_usbdev.h.

◆ dif_usbdev_recv_result

Return codes for dif_usbdev_recv.

Enumerator
kDifUsbdevRecvResultOK 

Indicates that the call succeeded.

kDifUsbdevRecvResultError 

Indicates that a non-specific error occurred and the hardware is in an invalid or irrecoverable state.

kDifUsbdevRecvResultBadArg 

Indicates that the caller supplied invalid arguments but the call did not cause any side-effects and the hardware is in a valid and recoverable state.

kDifUsbdevRecvResultNoNewPacket 

Indicates that RX FIFO is empty.

Definition at line 316 of file dif_usbdev.h.

◆ dif_usbdev_result

Common return codes for the functions in this library.

Enumerator
kDifUsbdevOK 

Indicates that the call succeeded.

kDifUsbdevError 

Indicates that a non-specific error occurred and the hardware is in an invalid or irrecoverable state.

kDifUsbdevBadArg 

Indicates that the caller supplied invalid arguments but the call did not cause any side-effects and the hardware is in a valid and recoverable state.

Definition at line 166 of file dif_usbdev.h.

◆ dif_usbdev_tx_status

Status of an outgoing packet.

Enumerator
kDifUsbdevTxStatusNoPacket 

There is no packet for the given endpoint.

kDifUsbdevTxStatusPending 

Packet is pending transmission.

kDifUsbdevTxStatusSent 

Packet was sent successfully.

kDifUsbdevTxStatusCancelled 

Transmission was canceled due to an incoming SETUP packet.

Definition at line 587 of file dif_usbdev.h.

Function Documentation

◆ dif_usbdev_address_get()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_address_get ( 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 707 of file dif_usbdev.c.

◆ dif_usbdev_address_set()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_address_set ( 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 695 of file dif_usbdev.c.

◆ dif_usbdev_buffer_read()

DIF_WARN_UNUSED_RESULT dif_usbdev_buffer_read_result_t dif_usbdev_buffer_read ( dif_usbdev_t usbdev,
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.
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 528 of file dif_usbdev.c.

◆ dif_usbdev_buffer_request()

DIF_WARN_UNUSED_RESULT dif_usbdev_buffer_request_result_t dif_usbdev_buffer_request ( dif_usbdev_t usbdev,
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.
[out]bufferA buffer for writing outgoing packet payload.
Returns
The result of the operation.

Definition at line 482 of file dif_usbdev.c.

◆ dif_usbdev_buffer_return()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_buffer_return ( dif_usbdev_t usbdev,
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.
bufferA buffer provided by dif_usbdev_recv or dif_usbdev_buffer_request.
Returns
The result of the operation.

Definition at line 507 of file dif_usbdev.c.

◆ dif_usbdev_buffer_write()

DIF_WARN_UNUSED_RESULT dif_usbdev_buffer_write_result_t dif_usbdev_buffer_write ( dif_usbdev_t usbdev,
dif_usbdev_buffer_t buffer,
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 567 of file dif_usbdev.c.

◆ dif_usbdev_endpoint_iso_enable()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_endpoint_iso_enable ( dif_usbdev_t usbdev,
uint8_t  endpoint,
dif_usbdev_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 424 of file dif_usbdev.c.

◆ dif_usbdev_endpoint_out_enable()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_endpoint_out_enable ( dif_usbdev_t usbdev,
uint8_t  endpoint,
dif_usbdev_toggle_t  new_state 
)

Enable or disable reception of OUT packets for an endpoint.

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

Definition at line 399 of file dif_usbdev.c.

◆ dif_usbdev_endpoint_setup_enable()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_endpoint_setup_enable ( dif_usbdev_t usbdev,
uint8_t  endpoint,
dif_usbdev_toggle_t  new_state 
)

Enable or disable reception of SETUP packets for an endpoint.

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

Definition at line 393 of file dif_usbdev.c.

◆ dif_usbdev_endpoint_stall_enable()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_endpoint_stall_enable ( dif_usbdev_t usbdev,
uint8_t  endpoint,
dif_usbdev_toggle_t  new_state 
)

Enable or disable STALL for an endpoint.

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

Definition at line 405 of file dif_usbdev.c.

◆ dif_usbdev_endpoint_stall_get()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_endpoint_stall_get ( dif_usbdev_t usbdev,
uint8_t  endpoint,
bool *  state 
)

Get STALL state of an endpoint.

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

Definition at line 411 of file dif_usbdev.c.

◆ dif_usbdev_fill_available_fifo()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_fill_available_fifo ( dif_usbdev_t usbdev)

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.
Returns
The result of the operation.

Definition at line 372 of file dif_usbdev.c.

◆ dif_usbdev_get_tx_status()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_get_tx_status ( 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 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.

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

Definition at line 634 of file dif_usbdev.c.

◆ dif_usbdev_init()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_init ( dif_usbdev_config_t config,
dif_usbdev_t usbdev 
)

Initialize a USB device.

A USB device must first be initialized by this function before calling other functions in this library.

Parameters
configConfiguration for initializing a USB device.
[out]usbdevInternal state of the initialized USB device.
Returns
The result of the operation.

Initialize a USB device.

Definition at line 262 of file dif_usbdev.c.

◆ dif_usbdev_interface_enable()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_interface_enable ( dif_usbdev_t usbdev,
dif_usbdev_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.

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

Definition at line 430 of file dif_usbdev.c.

◆ dif_usbdev_irq_clear()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_irq_clear ( dif_usbdev_t usbdev,
dif_usbdev_irq_t  irq 
)

Clear an interrupt.

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

Definition at line 877 of file dif_usbdev.c.

◆ dif_usbdev_irq_clear_all()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_irq_clear_all ( dif_usbdev_t usbdev)

Clear all pending interrupts.

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

Definition at line 889 of file dif_usbdev.c.

◆ dif_usbdev_irq_disable_all()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_irq_disable_all ( dif_usbdev_t usbdev,
uint32_t *  cur_config 
)

Disable all interrupts and optionally return the current interrupt configuration.

Parameters
usbdevA USB device.
[out]cur_configCurrent interrupt configuration.
Returns
The result of the operation.

Definition at line 900 of file dif_usbdev.c.

◆ dif_usbdev_irq_enable()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_irq_enable ( dif_usbdev_t usbdev,
dif_usbdev_irq_t  irq,
dif_usbdev_toggle_t  state 
)

Enable or disable an interrupt.

Parameters
usbdevA USB device.
irqAn interrupt.
stateNew state of the interrupt.
Returns
The result of the operation.

Definition at line 845 of file dif_usbdev.c.

◆ dif_usbdev_irq_get()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_irq_get ( dif_usbdev_t usbdev,
dif_usbdev_irq_t  irq,
bool *  state 
)

Check if there is a pending request for an interrupt.

Parameters
usbdevA USB device.
irqAn interrupt.
[out]stateState of the interrupt.
Returns
The result of the operation.

Definition at line 865 of file dif_usbdev.c.

◆ dif_usbdev_irq_restore()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_irq_restore ( dif_usbdev_t usbdev,
uint32_t  new_config 
)

Restore interrupt configuration.

Parameters
usbdevA USB device.
new_configNew interrupt configuration.
Returns
The result of the operation.

Definition at line 916 of file dif_usbdev.c.

◆ dif_usbdev_irq_test()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_irq_test ( dif_usbdev_t usbdev,
dif_usbdev_irq_t  irq 
)

Test an interrupt.

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

Definition at line 928 of file dif_usbdev.c.

◆ dif_usbdev_recv()

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 449 of file dif_usbdev.c.

◆ dif_usbdev_send()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_send ( 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 endpoint.
bufferA buffer provided by dif_usbdev_buffer_request.
Returns
The result of the operation.

Definition at line 600 of file dif_usbdev.c.

◆ dif_usbdev_status_get_available_fifo_depth()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_status_get_available_fifo_depth ( dif_usbdev_t usbdev,
uint8_t *  depth 
)

Get the depth of the AV FIFO.

See also: dif_usbdev_fill_available_fifo.

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

Definition at line 793 of file dif_usbdev.c.

◆ dif_usbdev_status_get_available_fifo_full()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_status_get_available_fifo_full ( dif_usbdev_t usbdev,
bool *  is_full 
)

Check if AV FIFO is full.

See also: dif_usbdev_fill_available_fifo.

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

Definition at line 807 of file dif_usbdev.c.

◆ dif_usbdev_status_get_frame()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_status_get_frame ( 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 721 of file dif_usbdev.c.

◆ dif_usbdev_status_get_host_lost()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_status_get_host_lost ( 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 735 of file dif_usbdev.c.

◆ dif_usbdev_status_get_link_state()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_status_get_link_state ( 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 748 of file dif_usbdev.c.

◆ dif_usbdev_status_get_rx_fifo_depth()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_status_get_rx_fifo_depth ( 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 819 of file dif_usbdev.c.

◆ dif_usbdev_status_get_rx_fifo_empty()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_status_get_rx_fifo_empty ( 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 833 of file dif_usbdev.c.

◆ dif_usbdev_status_get_sense()

DIF_WARN_UNUSED_RESULT dif_usbdev_result_t dif_usbdev_status_get_sense ( 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 781 of file dif_usbdev.c.