 |
Software APIs
|
|
Software APIs
|
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. | |
USB Device Device Interface Functions
Definition in file dif_usbdev.h.
| 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. |
| 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 | |
| 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. |
| 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. |
| 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. |
| struct dif_usbdev_wake_status |
Definition at line 819 of file dif_usbdev.h.
| struct dif_usbdev_phy_pins_sense |
Definition at line 862 of file dif_usbdev.h.
| struct dif_usbdev_phy_pins_drive |
Definition at line 894 of file dif_usbdev.h.
| typedef struct dif_usbdev_buffer_pool 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.
| typedef struct dif_usbdev_buffer 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.
Buffer types.
Definition at line 71 of file dif_usbdev.h.
| enum dif_usbdev_tx_status |
Status of an outgoing packet.
Definition at line 555 of file dif_usbdev.h.
| 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.
| usbdev | A USB device. | |
| [out] | addr | Current address. |
Definition at line 673 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. |
| addr | New address. Only the last 7 bits are significant. |
Definition at line 659 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. | |
| buffer_pool | A USB device buffer pool. | |
| buffer | A buffer provided by dif_usbdev_recv. | |
| [out] | dst | Destination buffer. |
| dst_len | Length of the destination buffer. | |
| [out] | bytes_written | Number of bytes written to destination buffer. |
Definition at line 476 of file dif_usbdev.c.
| 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:
dif_usbdev_buffer_request,dif_usbdev_buffer_write,dif_usbdev_send, anddif_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.
| usbdev | A USB device. | |
| buffer_pool | A USB device buffer pool. | |
| [out] | buffer | A buffer for writing outgoing packet payload. |
Definition at line 428 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. |
| buffer_pool | A USB device buffer pool. |
| buffer | A buffer provided by dif_usbdev_recv or dif_usbdev_buffer_request. |
Definition at line 454 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. | |
| buffer | A buffer provided by dif_usbdev_buffer_request. | |
| src | Source buffer. | |
| src_len | Length of the source buffer. | |
| [out] | bytes_written | Number of bytes written to the USB device buffer. |
Definition at line 517 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. |
| endpoint | An endpoint number. |
Definition at line 741 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. |
| buffer_pool | A USB device buffer pool. |
| endpoint | An IN endpoint number. |
Definition at line 597 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. |
| buffer_pool | A USB device buffer pool. |
| config | Runtime configuration parameters for a USB device. |
Configures a USB device with runtime information.
Definition at line 212 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. | |
| [out] |
Definition at line 701 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. |
| mask | Mask of IN endpoint data toggles to be changed. |
| state | New states of that IN endpoint data toggles being changed. |
Definition at line 728 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. | |
| [out] |
Definition at line 687 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. |
| mask | Mask of OUT endpoint data toggles to be changed. |
| state | New states of that OUT endpoint data toggles being changed. |
Definition at line 715 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. |
| endpoint | An endpoint. |
| new_state | New endpoint state. |
Definition at line 363 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. |
| endpoint | An endpoint. |
| new_state | New isochronous state. |
Definition at line 351 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. |
| endpoint | An OUT endpoint number. |
| new_state | New OUT packet reception state. |
Definition at line 308 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. |
| endpoint | An OUT endpoint number. |
| new_state | New set_nak_on_out state. |
Definition at line 315 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. |
| endpoint | An endpoint number. |
| new_state | New SETUP packet reception state. |
Definition at line 301 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. |
| endpoint | An endpoint ID. |
| new_state | New STALL state. |
Definition at line 322 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. | |
| endpoint | An endpoint ID. | |
| [out] | state | Current STALL state. |
Definition at line 334 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. |
| buffer_pool | A USB device buffer pool. |
Definition at line 258 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. | |
| [out] | status | The current state of the pins. |
Definition at line 955 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. | |
| [out] | sent | A bitmap of which endpoints have sent packets. |
Definition at line 587 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. | |
| endpoint | An IN endpoint number. | |
| [out] | status | Status of the packet. |
Definition at line 623 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. | |
| [out] | status | The status of the module. |
Definition at line 927 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. |
| new_state | New interface state. |
Definition at line 376 of file dif_usbdev.c.
| 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:
dif_usbdev_recv, anddif_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.
| usbdev | A USB device. | |
| [out] | packet_info | Packet information. |
| [out] | buffer | Buffer that holds the packet payload. |
Definition at line 391 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. |
Definition at line 943 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. |
| endpoint | An OUT endpoint number. |
| buffer | A buffer provided by dif_usbdev_buffer_request. |
Definition at line 551 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. |
| enable | Whether the test mode should be enabled. |
Definition at line 896 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. |
| override_enable | Enable / disable the GPIO-like overrides. |
| overrides | The values to set the pins to. |
Definition at line 981 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. |
| enable | Whether the AON wake module is enabled. |
Definition at line 910 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. | |
| [out] | setup_depth | Depth of the AV SETUP FIFO. |
| [out] | out_depth | Depth of the AV OUT FIFO. |
Definition at line 835 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. | |
| [out] | setup_is_full | State of the AV SETUP FIFO. true if full, false otherwise. |
| [out] | out_is_full | State of the AV OUT FIFO. true if full, false otherwise. |
Definition at line 853 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. | |
| [out] | frame_index | USB frame index. |
Definition at line 756 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. | |
| [out] | host_lost | Status of the host. true if the host is lost, false otherwise. |
Definition at line 771 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. | |
| [out] | link_state | USB link state. |
Definition at line 784 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. | |
| [out] | depth | Depth of the RX FIFO. |
Definition at line 868 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. | |
| [out] | is_empty | State of the RX FIFO. true if empty, false otherwise. |
Definition at line 883 of file dif_usbdev.c.
| 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.
| usbdev | A USB device. | |
| [out] | sense | State of the sense pin. true if the host is providing VBUS, false otherwise. |
Definition at line 823 of file dif_usbdev.c.