USBDEV Device Interface Functions More...

#include <stdbool.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 "dt/dt_usbdev.h"

Data Structures
struct	dif_usbdev
	A handle to usbdev. More...

Macros
#define	kDifUsbdevIrqPktReceived kDtUsbdevIrqPktReceived
	A usbdev interrupt request type.

#define	kDifUsbdevIrqPktSent kDtUsbdevIrqPktSent
	Raised if a packet was sent as part of an IN transaction.

#define	kDifUsbdevIrqDisconnected kDtUsbdevIrqDisconnected
	Raised if VBUS is lost, thus the link is disconnected.

#define	kDifUsbdevIrqHostLost kDtUsbdevIrqHostLost
	Raised if link is active but SOF was not received from host for 4.096 ms.

#define	kDifUsbdevIrqLinkReset kDtUsbdevIrqLinkReset
	Raised if the link is at SE0 longer than 3 us indicating a link reset (host asserts for min 10 ms, device can react after 2.5 us).

#define	kDifUsbdevIrqLinkSuspend kDtUsbdevIrqLinkSuspend
	Raised if the line has signaled J for longer than 3ms and is therefore in suspend state.

#define	kDifUsbdevIrqLinkResume kDtUsbdevIrqLinkResume
	Raised when the link becomes active again after being suspended.

#define	kDifUsbdevIrqAvOutEmpty kDtUsbdevIrqAvOutEmpty
	Raised when the Available OUT Buffer FIFO is empty and the device interface is enabled.

#define	kDifUsbdevIrqRxFull kDtUsbdevIrqRxFull
	Raised when the RX FIFO is full and the device interface is enabled.

#define	kDifUsbdevIrqAvOverflow kDtUsbdevIrqAvOverflow
	Raised if a write was done to either the Available OUT Buffer FIFO or the Available SETUP Buffer FIFO when the FIFO was full.

#define	kDifUsbdevIrqLinkInErr kDtUsbdevIrqLinkInErr
	Raised if a packet to an IN endpoint started to be received but was then dropped due to an error.

#define	kDifUsbdevIrqRxCrcErr kDtUsbdevIrqRxCrcErr
	Raised if a CRC error occurred on a received packet.

#define	kDifUsbdevIrqRxPidErr kDtUsbdevIrqRxPidErr
	Raised if an invalid Packet IDentifier (PID) was received.

#define	kDifUsbdevIrqRxBitstuffErr kDtUsbdevIrqRxBitstuffErr
	Raised if an invalid bitstuffing was received.

#define	kDifUsbdevIrqFrame kDtUsbdevIrqFrame
	Raised when the USB frame number is updated with a valid SOF.

#define	kDifUsbdevIrqPowered kDtUsbdevIrqPowered
	Raised if VBUS is applied.

#define	kDifUsbdevIrqLinkOutErr kDtUsbdevIrqLinkOutErr
	Raised if a packet to an OUT endpoint started to be received but was then dropped due to an error.

#define	kDifUsbdevIrqAvSetupEmpty kDtUsbdevIrqAvSetupEmpty
	Raised when the Available SETUP Buffer FIFO is empty and the device interface is enabled.

Typedefs
typedef struct dif_usbdev	dif_usbdev_t
	A handle to usbdev.

typedef enum dif_usbdev_alert	dif_usbdev_alert_t
	A usbdev alert type.

Enumerations
enum	dif_usbdev_alert { kDifUsbdevAlertFatalFault = 0 }
	A usbdev alert type. More...

Functions
OT_WARN_UNUSED_RESULT dif_result_t	dif_usbdev_init (mmio_region_t base_addr, dif_usbdev_t *usbdev)
	Creates a new handle for a(n) usbdev peripheral.

OT_WARN_UNUSED_RESULT dif_result_t	dif_usbdev_init_from_dt (dt_usbdev_t dt, dif_usbdev_t *usbdev)
	Creates a new handle for a(n) usbdev peripheral.

OT_WARN_UNUSED_RESULT dif_result_t	dif_usbdev_get_dt (const dif_usbdev_t usbdev, dt_usbdev_t dt)
	Get the DT handle from this DIF.

OT_WARN_UNUSED_RESULT dif_result_t	dif_usbdev_alert_force (const dif_usbdev_t *usbdev, dif_usbdev_alert_t alert)
	Forces a particular alert, causing it to be escalated as if the hardware had raised it.

OT_WARN_UNUSED_RESULT dif_result_t	dif_usbdev_irq_get_type (const dif_usbdev_t usbdev, dif_usbdev_irq_t, dif_irq_type_t type)
	Returns the type of a given interrupt (i.e., event or status) for this IP.

OT_WARN_UNUSED_RESULT dif_result_t	dif_usbdev_irq_get_state (const dif_usbdev_t usbdev, dif_usbdev_irq_state_snapshot_t snapshot)
	Returns the state of all interrupts (i.e., pending or not) for this IP.

OT_WARN_UNUSED_RESULT dif_result_t	dif_usbdev_irq_is_pending (const dif_usbdev_t usbdev, dif_usbdev_irq_t, bool is_pending)
	Returns whether a particular interrupt is currently pending.

OT_WARN_UNUSED_RESULT dif_result_t	dif_usbdev_irq_acknowledge_state (const dif_usbdev_t *usbdev, dif_usbdev_irq_state_snapshot_t snapshot)
	Acknowledges all interrupts that were pending at the time of the state snapshot.

OT_WARN_UNUSED_RESULT dif_result_t	dif_usbdev_irq_acknowledge_all (const dif_usbdev_t *usbdev)
	Acknowledges all interrupts, indicating to the hardware that all interrupts have been successfully serviced.

OT_WARN_UNUSED_RESULT dif_result_t	dif_usbdev_irq_acknowledge (const dif_usbdev_t *usbdev, dif_usbdev_irq_t)
	Acknowledges a particular interrupt, indicating to the hardware that it has been successfully serviced.

OT_WARN_UNUSED_RESULT dif_result_t	dif_usbdev_irq_force (const dif_usbdev_t *usbdev, dif_usbdev_irq_t, const bool val)
	Forces a particular interrupt, causing it to be serviced as if hardware had asserted it.

OT_WARN_UNUSED_RESULT dif_result_t	dif_usbdev_irq_get_enabled (const dif_usbdev_t usbdev, dif_usbdev_irq_t, dif_toggle_t state)
	Checks whether a particular interrupt is currently enabled or disabled.

OT_WARN_UNUSED_RESULT dif_result_t	dif_usbdev_irq_set_enabled (const dif_usbdev_t *usbdev, dif_usbdev_irq_t, dif_toggle_t state)
	Sets whether a particular interrupt is currently enabled or disabled.

OT_WARN_UNUSED_RESULT dif_result_t	dif_usbdev_irq_disable_all (const dif_usbdev_t usbdev, dif_usbdev_irq_enable_snapshot_t snapshot)
	Disables all interrupts, optionally snapshotting all enable states for later restoration.

OT_WARN_UNUSED_RESULT dif_result_t	dif_usbdev_irq_restore_all (const dif_usbdev_t usbdev, const dif_usbdev_irq_enable_snapshot_t snapshot)
	Restores interrupts from the given (enable) snapshot.

Detailed Description

USBDEV Device Interface Functions

Definition in file dif_usbdev_autogen.h.

Data Structure Documentation

◆ dif_usbdev

struct dif_usbdev

A handle to usbdev.

This type should be treated as opaque by users.

Definition at line 37 of file dif_usbdev_autogen.h.

Data Fields
mmio_region_t	base_addr	The base address for the usbdev hardware registers.
dt_usbdev_t	dt	The instance, set to `kDtUsbdevCount` if not initialized through `dif_usbdev_init_from_dt`.

Macro Definition Documentation

◆ kDifUsbdevIrqAvOutEmpty

#define kDifUsbdevIrqAvOutEmpty kDtUsbdevIrqAvOutEmpty

Raised when the Available OUT Buffer FIFO is empty and the device interface is enabled.

This interrupt is directly tied to the FIFO status, so the Available OUT Buffer FIFO must be provided with a free buffer before the interrupt can be cleared.

Definition at line 162 of file dif_usbdev_autogen.h.

◆ kDifUsbdevIrqAvOverflow

#define kDifUsbdevIrqAvOverflow kDtUsbdevIrqAvOverflow

Raised if a write was done to either the Available OUT Buffer FIFO or the Available SETUP Buffer FIFO when the FIFO was full.

Definition at line 170 of file dif_usbdev_autogen.h.

◆ kDifUsbdevIrqAvSetupEmpty

#define kDifUsbdevIrqAvSetupEmpty kDtUsbdevIrqAvSetupEmpty

Raised when the Available SETUP Buffer FIFO is empty and the device interface is enabled.

This interrupt is directly tied to the FIFO status, so the Available SETUP Buffer FIFO must be provided with a free buffer before the interrupt can be cleared.

Definition at line 202 of file dif_usbdev_autogen.h.

◆ kDifUsbdevIrqDisconnected

#define kDifUsbdevIrqDisconnected kDtUsbdevIrqDisconnected

Raised if VBUS is lost, thus the link is disconnected.

Definition at line 142 of file dif_usbdev_autogen.h.

◆ kDifUsbdevIrqFrame

#define kDifUsbdevIrqFrame kDtUsbdevIrqFrame

Raised when the USB frame number is updated with a valid SOF.

Definition at line 190 of file dif_usbdev_autogen.h.

◆ kDifUsbdevIrqHostLost

#define kDifUsbdevIrqHostLost kDtUsbdevIrqHostLost

Raised if link is active but SOF was not received from host for 4.096 ms.

The SOF should be every 1 ms.

Definition at line 146 of file dif_usbdev_autogen.h.

◆ kDifUsbdevIrqLinkInErr

#define kDifUsbdevIrqLinkInErr kDtUsbdevIrqLinkInErr

Raised if a packet to an IN endpoint started to be received but was then dropped due to an error.

After transmitting the IN payload, the USB device expects a valid ACK handshake packet. This error is raised if either the packet or CRC is invalid, leading to a NAK instead, or if a different token was received.

Definition at line 174 of file dif_usbdev_autogen.h.

◆ kDifUsbdevIrqLinkOutErr

#define kDifUsbdevIrqLinkOutErr kDtUsbdevIrqLinkOutErr

Raised if a packet to an OUT endpoint started to be received but was then dropped due to an error.

This error is raised if the data toggle, token, packet and/or CRC are invalid, or if the appropriate Available OUT Buffer FIFO is empty and/or the Received Buffer FIFO is full when a packet should have been received.

Definition at line 198 of file dif_usbdev_autogen.h.

◆ kDifUsbdevIrqLinkReset

#define kDifUsbdevIrqLinkReset kDtUsbdevIrqLinkReset

Raised if the link is at SE0 longer than 3 us indicating a link reset (host asserts for min 10 ms, device can react after 2.5 us).

Definition at line 150 of file dif_usbdev_autogen.h.

◆ kDifUsbdevIrqLinkResume

#define kDifUsbdevIrqLinkResume kDtUsbdevIrqLinkResume

Raised when the link becomes active again after being suspended.

Definition at line 158 of file dif_usbdev_autogen.h.

◆ kDifUsbdevIrqLinkSuspend

#define kDifUsbdevIrqLinkSuspend kDtUsbdevIrqLinkSuspend

Raised if the line has signaled J for longer than 3ms and is therefore in suspend state.

Definition at line 154 of file dif_usbdev_autogen.h.

◆ kDifUsbdevIrqPktReceived

#define kDifUsbdevIrqPktReceived kDtUsbdevIrqPktReceived

A usbdev interrupt request type.

DEPRECATED Use dt_usbdev_irq_t instead. This enumeration exists solely for the transition to dt-based interrupt numbers and will be removed in the future.

The following are defines to keep the types consistent with DT. Raised if a packet was received using an OUT or SETUP transaction. This interrupt is directly tied to whether the RX FIFO is empty, so it should be cleared only after handling the FIFO entry.

Definition at line 134 of file dif_usbdev_autogen.h.

◆ kDifUsbdevIrqPktSent

#define kDifUsbdevIrqPktSent kDtUsbdevIrqPktSent

Raised if a packet was sent as part of an IN transaction.

This interrupt is directly tied to whether a sent packet has not been acknowledged in the !!in_sent register. It should be cleared only after clearing all bits in the !!in_sent register.

Definition at line 138 of file dif_usbdev_autogen.h.

◆ kDifUsbdevIrqPowered

#define kDifUsbdevIrqPowered kDtUsbdevIrqPowered

Raised if VBUS is applied.

Definition at line 194 of file dif_usbdev_autogen.h.

◆ kDifUsbdevIrqRxBitstuffErr

#define kDifUsbdevIrqRxBitstuffErr kDtUsbdevIrqRxBitstuffErr

Raised if an invalid bitstuffing was received.

Definition at line 186 of file dif_usbdev_autogen.h.

◆ kDifUsbdevIrqRxCrcErr

#define kDifUsbdevIrqRxCrcErr kDtUsbdevIrqRxCrcErr

Raised if a CRC error occurred on a received packet.

Definition at line 178 of file dif_usbdev_autogen.h.

◆ kDifUsbdevIrqRxFull

#define kDifUsbdevIrqRxFull kDtUsbdevIrqRxFull

Raised when the RX FIFO is full and the device interface is enabled.

This interrupt is directly tied to the FIFO status, so the RX FIFO must have an entry removed before the interrupt is cleared. If the condition is not cleared, the interrupt can re-assert.

Definition at line 166 of file dif_usbdev_autogen.h.

◆ kDifUsbdevIrqRxPidErr

#define kDifUsbdevIrqRxPidErr kDtUsbdevIrqRxPidErr

Raised if an invalid Packet IDentifier (PID) was received.

Definition at line 182 of file dif_usbdev_autogen.h.

Typedef Documentation

◆ dif_usbdev_t

typedef struct dif_usbdev dif_usbdev_t

A handle to usbdev.

This type should be treated as opaque by users.

Enumeration Type Documentation

◆ dif_usbdev_alert

enum dif_usbdev_alert

A usbdev alert type.

Enumerator
kDifUsbdevAlertFatalFault	This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected.

Definition at line 98 of file dif_usbdev_autogen.h.

Function Documentation

◆ dif_usbdev_alert_force()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_alert_force	(	const dif_usbdev_t *	usbdev,
		dif_usbdev_alert_t	alert )

Forces a particular alert, causing it to be escalated as if the hardware had raised it.

Parameters

usbdev	A usbdev handle.
alert	The alert to force.

Returns: The result of the operation.

Definition at line 62 of file dif_usbdev_autogen.c.

◆ dif_usbdev_get_dt()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_get_dt	(	const dif_usbdev_t *	usbdev,
		dt_usbdev_t *	dt )

Get the DT handle from this DIF.

If this DIF was initialized by dif_usbdev_init_from_dt(dt, ..) then this function will return dt. Otherwise it will return an error.

Parameters

	usbdev	A usbdev handle.
[out]	dt	DT handle.

Returns: kDifBadArg if the DIF has no DT information, kDifOk otherwise.

Definition at line 52 of file dif_usbdev_autogen.c.

◆ dif_usbdev_init()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_init	(	mmio_region_t	base_addr,
		dif_usbdev_t *	usbdev )

Creates a new handle for a(n) usbdev peripheral.

This function does not actuate the hardware.

Parameters

	base_addr	The MMIO base address of the usbdev peripheral.
[out]	usbdev	Out param for the initialized handle.

Returns: The result of the operation.

DEPRECATED This function exists solely for the transition to dt-based DIFs and will be removed in the future.

Definition at line 25 of file dif_usbdev_autogen.c.

◆ dif_usbdev_init_from_dt()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_init_from_dt	(	dt_usbdev_t	dt,
		dif_usbdev_t *	usbdev )

Creates a new handle for a(n) usbdev peripheral.

This function does not actuate the hardware.

Parameters

	dt	The devicetable description of the device.
[out]	usbdev	Out param for the initialized handle.

Returns: The result of the operation.

Definition at line 39 of file dif_usbdev_autogen.c.

◆ dif_usbdev_irq_acknowledge()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_irq_acknowledge	(	const dif_usbdev_t *	usbdev,
		dif_usbdev_irq_t	irq )

Acknowledges a particular interrupt, indicating to the hardware that it has been successfully serviced.

Parameters

usbdev	A usbdev handle.
irq	An interrupt request.

Returns: The result of the operation.

Definition at line 277 of file dif_usbdev_autogen.c.

◆ dif_usbdev_irq_acknowledge_all()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_irq_acknowledge_all ( const dif_usbdev_t * usbdev )

Acknowledges all interrupts, indicating to the hardware that all interrupts have been successfully serviced.

Parameters

usbdev A usbdev handle.

Returns: The result of the operation.

Definition at line 258 of file dif_usbdev_autogen.c.

◆ dif_usbdev_irq_acknowledge_state()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_irq_acknowledge_state	(	const dif_usbdev_t *	usbdev,
		dif_usbdev_irq_state_snapshot_t	snapshot )

Acknowledges all interrupts that were pending at the time of the state snapshot.

Parameters

usbdev	A usbdev handle.
snapshot	Interrupt state snapshot.

Returns: The result of the operation.

Definition at line 216 of file dif_usbdev_autogen.c.

◆ dif_usbdev_irq_disable_all()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_irq_disable_all	(	const dif_usbdev_t *	usbdev,
		dif_usbdev_irq_enable_snapshot_t *	snapshot )

Disables all interrupts, optionally snapshotting all enable states for later restoration.

Parameters

	usbdev	A usbdev handle.
[out]	snapshot	Out-param for the snapshot; may be `NULL`.

Returns: The result of the operation.

Definition at line 385 of file dif_usbdev_autogen.c.

◆ dif_usbdev_irq_force()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_irq_force	(	const dif_usbdev_t *	usbdev,
		dif_usbdev_irq_t	irq,
		const bool	val )

Forces a particular interrupt, causing it to be serviced as if hardware had asserted it.

Parameters

usbdev	A usbdev handle.
irq	An interrupt request.
val	Value to be set.

Returns: The result of the operation.

Definition at line 302 of file dif_usbdev_autogen.c.

◆ dif_usbdev_irq_get_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_irq_get_enabled	(	const dif_usbdev_t *	usbdev,
		dif_usbdev_irq_t	irq,
		dif_toggle_t *	state )

Checks whether a particular interrupt is currently enabled or disabled.

Parameters

	usbdev	A usbdev handle.
	irq	An interrupt request.
[out]	state	Out-param toggle state of the interrupt.

Returns: The result of the operation.

Definition at line 327 of file dif_usbdev_autogen.c.

◆ dif_usbdev_irq_get_state()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_irq_get_state	(	const dif_usbdev_t *	usbdev,
		dif_usbdev_irq_state_snapshot_t *	snapshot )

Returns the state of all interrupts (i.e., pending or not) for this IP.

Parameters

	usbdev	A usbdev handle.
[out]	snapshot	Out-param for interrupt state snapshot.

Returns: The result of the operation.

Definition at line 199 of file dif_usbdev_autogen.c.

◆ dif_usbdev_irq_get_type()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_irq_get_type	(	const dif_usbdev_t *	usbdev,
		dif_usbdev_irq_t	irq,
		dif_irq_type_t *	type )

Returns the type of a given interrupt (i.e., event or status) for this IP.

Parameters

	usbdev	A usbdev handle.
	irq	An interrupt request.
[out]	type	Out-param for the interrupt type.

Returns: The result of the operation.

Definition at line 180 of file dif_usbdev_autogen.c.

◆ dif_usbdev_irq_is_pending()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_irq_is_pending	(	const dif_usbdev_t *	usbdev,
		dif_usbdev_irq_t	irq,
		bool *	is_pending )

Returns whether a particular interrupt is currently pending.

Parameters

	usbdev	A usbdev handle.
	irq	An interrupt request.
[out]	is_pending	Out-param for whether the interrupt is pending.

Returns: The result of the operation.

Definition at line 233 of file dif_usbdev_autogen.c.

◆ dif_usbdev_irq_restore_all()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_irq_restore_all	(	const dif_usbdev_t *	usbdev,
		const dif_usbdev_irq_enable_snapshot_t *	snapshot )

Restores interrupts from the given (enable) snapshot.

Parameters

usbdev	A usbdev handle.
snapshot	A snapshot to restore from.

Returns: The result of the operation.

Definition at line 412 of file dif_usbdev_autogen.c.

◆ dif_usbdev_irq_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_usbdev_irq_set_enabled	(	const dif_usbdev_t *	usbdev,
		dif_usbdev_irq_t	irq,
		dif_toggle_t	state )

Sets whether a particular interrupt is currently enabled or disabled.

Parameters

usbdev	A usbdev handle.
irq	An interrupt request.
state	The new toggle state for the interrupt.

Returns: The result of the operation.

Definition at line 354 of file dif_usbdev_autogen.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ dif_usbdev

Macro Definition Documentation

◆ kDifUsbdevIrqAvOutEmpty

◆ kDifUsbdevIrqAvOverflow

◆ kDifUsbdevIrqAvSetupEmpty

◆ kDifUsbdevIrqDisconnected

◆ kDifUsbdevIrqFrame

◆ kDifUsbdevIrqHostLost

◆ kDifUsbdevIrqLinkInErr

◆ kDifUsbdevIrqLinkOutErr

◆ kDifUsbdevIrqLinkReset

◆ kDifUsbdevIrqLinkResume

◆ kDifUsbdevIrqLinkSuspend

◆ kDifUsbdevIrqPktReceived

◆ kDifUsbdevIrqPktSent

◆ kDifUsbdevIrqPowered

◆ kDifUsbdevIrqRxBitstuffErr

◆ kDifUsbdevIrqRxCrcErr

◆ kDifUsbdevIrqRxFull

◆ kDifUsbdevIrqRxPidErr

Typedef Documentation

◆ dif_usbdev_t

Enumeration Type Documentation

◆ dif_usbdev_alert

Function Documentation

◆ dif_usbdev_alert_force()

◆ dif_usbdev_get_dt()

◆ dif_usbdev_init()

◆ dif_usbdev_init_from_dt()

◆ dif_usbdev_irq_acknowledge()

◆ dif_usbdev_irq_acknowledge_all()

◆ dif_usbdev_irq_acknowledge_state()

◆ dif_usbdev_irq_disable_all()

◆ dif_usbdev_irq_force()

◆ dif_usbdev_irq_get_enabled()

◆ dif_usbdev_irq_get_state()

◆ dif_usbdev_irq_get_type()

◆ dif_usbdev_irq_is_pending()

◆ dif_usbdev_irq_restore_all()

◆ dif_usbdev_irq_set_enabled()