A driver for OpenTitan USB Device, which is used in the Sonata system. More...

#include <platform-usbdev.hh>

Inheritance diagram for OpenTitanUsbdev:

Collaboration diagram for OpenTitanUsbdev:

Classes
struct	ReceiveBufferInfo
	The information associated with a received packet. More...

Public Types
enum class	UsbdevInterrupt : uint32_t { PacketReceived = 1u << 0 , PacketSent = 1u << 1 , Disconnected = 1u << 2 , HostLost = 1u << 3 , LinkReset = 1u << 4 , LinkSuspend = 1u << 5 , LinkResume = 1u << 6 , AvailableOutEmpty = 1u << 7 , ReceiveFull = 1u << 8 , AvailableBufferOverflow = 1u << 9 , LinkInError = 1u << 10 , RedundancyCheckError = 1u << 11 , PacketIdentifierError = 1u << 12 , BitstuffingError = 1u << 13 , FrameUpdated = 1u << 14 , Powered = 1u << 15 , LinkOutError = 1u << 16 , AvailableSetupEmpty = 1u << 17 }
	Interrupt definitions for OpenTitan's USB Device. More...
enum class	UsbControlField : uint32_t { Enable = 1u << 0 , ResumeLinkActive = 1u << 1 , DeviceAddress = 0x7Fu << 16 }
	Definitions of fields (and their locations) for the USB Control register (offset 0x10). More...
enum class	UsbStatusField : uint32_t { Frame = 0x7FFu << 0 , HostLost = 1u << 11 , LinkState = 0x7u << 12 , Sense = 1u << 15 , AvailableOutDepth = 0xFu << 16 , AvailableSetupDepth = 0x7u << 20 , AvailableOutFull = 1u << 23 , ReceiveDepth = 0xFu << 24 , AvailableSetupFull = 1u << 30 , ReceiveEmpty = 1u << 31 }
	Definitions of fields (and their locations) for the USB Status register (offset 0x1c). More...
enum class	ReceiveBufferField : uint32_t { BufferId = 0x1Fu << 0 , Size = 0x7Fu << 8 , Setup = 1u << 19 , EndpointId = 0xFu << 20 }
	Definitions of fields (and their locations) for the Receive FIFO buffer register (offset 0x28). More...
enum class	ConfigInField : uint32_t { BufferId = 0x1Fu << 0 , Size = 0x7Fu << 8 , Sending = 1u << 29 , Pending = 1u << 30 , Ready = 1u << 31 }
	Definitions of fields (and their locations) for a Config In register (where there is one such register for each endpoint). More...
enum class	PhyConfigField : uint32_t { UseDifferentialReceiver = 1u << 0 }
	Definitions of fields (and their locations) for the PHY Config Register (offset 0x8c). More...

Public Member Functions
uint64_t	supply_buffers (uint64_t bufferBitmap) volatile
	Ensure that the Available OUT and Available SETUP buffers are kept supplied with buffers for packet reception.
void	interrupt_enable (UsbdevInterrupt interrupt) volatile
	Enable a specified interrupt / interrupts.
void	interrupt_disable (UsbdevInterrupt interrupt) volatile
	Disable a specified interrupt / interrupts.
int	init (uint64_t &bufferBitmap) volatile
	Initialise the USB device, ensuring that packet buffers are available for reception and that the PHY has been appropriately configured.
int	out_endpoint_configure (uint8_t endpointId, bool enabled, bool setup, bool isochronous) volatile
	Set up the configuration of an OUT endpoint for the USB device.
int	in_endpoint_configure (uint8_t endpointId, bool enabled, bool isochronous) volatile
	Set up the configuration of an IN endpoint for the USB device.
int	endpoint_stalling_set (uint8_t endpointId, bool stalling) volatile
	Set the STALL state of a specified endpoint pair (both IN and OUT).
int	connect () volatile
	Connect the device to the USB, indicating its presence to the USB host controller.
void	disconnect () volatile
	Disconnect the device from the USB.
bool	connected () volatile
	Check whether the USB device is connected (i.e.
int	device_address_set (uint8_t address) volatile
	Set the device address on the USB; this address will have been supplied by the USB host controller in the standard SET_ADDRESS Control Transfer.
int	retrieve_collected_packet (uint8_t &endpointId, uint8_t &bufferId) volatile
	Check and retrieve the endpoint and buffer numbers of a recently-collected IN data packet.
void	packet_send (uint8_t bufferId, uint8_t endpointId, const uint32_t *data, uint8_t size) volatile
	Present a packet on the specified IN endpoint for collection by the USB host controller.
std::optional< ReceiveBufferInfo >	packet_take () volatile
	If a packet has been received, removes the packet's buffer from the receive FIFO giving it's information and ownership to the user.
void	packet_data_get (ReceiveBufferInfo bufferInfo, uint32_t *destination) volatile
	Retrieves the data from a buffer containing a received packet.

Public Attributes
uint32_t	interruptState
	Device Registers.
uint32_t	interruptEnable
uint32_t	interruptTest
uint32_t	alertTest
uint32_t	usbControl
uint32_t	endpointOutEnable
uint32_t	endpointInEnable
uint32_t	usbStatus
uint32_t	availableOutBuffer
uint32_t	availableSetupBuffer
uint32_t	receiveBuffer
uint32_t	receiveEnableSetup
	Register to enable receive SETUP transactions.
uint32_t	receiveEnableOut
	Register to enable receive OUT transactions.
uint32_t	setNotAcknowledgeOut
	Register to set NAK (Not/Negated Acknowledge) after OUT transactions.
uint32_t	inSent
	Register showing ACK receival to indicate a successful IN send.
uint32_t	outStall
	Registers for controlling the stalling of OUT and IN endpoints.
uint32_t	inStall
uint32_t	configIn [MaxEndpoints]
	IN transaction configuration registers.
uint32_t	outIsochronous
	Registers for configuring which endpoints should be treated as isochronous endpoints.
uint32_t	inIsochronous
uint32_t	outDataToggle
	Registers for configuring if endpoints data toggle on transactions.
uint32_t	inDataToggle
uint32_t	phyConfig
	Config register for the USB PHY pins.

Static Public Attributes
static constexpr uint8_t	MaxPacketLength = 64u
	Supported sizes for the USB Device.
static constexpr uint8_t	BufferCount = 32u
static constexpr uint8_t	MaxEndpoints = 12u
static constexpr uint32_t	BufferStartAddress = 0x800u
	The offset from the start of the USB Device MMIO region at which packet buffer memory begins.

Detailed Description

A driver for OpenTitan USB Device, which is used in the Sonata system.

This peripheral's source and documentation can be found at: https://github.com/lowRISC/opentitan/tree/ab878b5d3578939a04db72d4ed966a56a869b2ed/hw/ip/usbdev

With rendered register documentation served at: https://opentitan.org/book/hw/ip/usbdev/doc/registers.html

An incredibly brief overview of how the USB device and it's buffers: Data packet ingress and egress goes via a pool of 64 byte buffers living in a 2kB SRAM packet buffer, which is accessable as a large MMIO region. The software manages these buffers using buffer IDs as references. IDs are pushed or popped into different FIFOs by either the software or device depending on whether they contain a packet to be sent, are available for a packet to be received into them, or contain a packet that has been received.

See https://opentitan.org/book/hw/ip/usbdev/doc/programmers_guide.html for more information.

Definition at line 31 of file platform-usbdev.hh.

Member Enumeration Documentation

◆ ConfigInField

enum class OpenTitanUsbdev::ConfigInField : uint32_t

strong

Definitions of fields (and their locations) for a Config In register (where there is one such register for each endpoint).

These are the registers with offsets 0x44 up to (and not including) 0x74.

https://opentitan.org/book/hw/ip/usbdev/doc/registers.html#configin

Definition at line 221 of file platform-usbdev.hh.

◆ PhyConfigField

enum class OpenTitanUsbdev::PhyConfigField : uint32_t

strong

Definitions of fields (and their locations) for the PHY Config Register (offset 0x8c).

https://opentitan.org/book/hw/ip/usbdev/doc/registers.html#phy_config

Definition at line 236 of file platform-usbdev.hh.

◆ ReceiveBufferField

enum class OpenTitanUsbdev::ReceiveBufferField : uint32_t

strong

Definitions of fields (and their locations) for the Receive FIFO buffer register (offset 0x28).

https://opentitan.org/book/hw/ip/usbdev/doc/registers.html#rxfifo

Definition at line 206 of file platform-usbdev.hh.

◆ UsbControlField

enum class OpenTitanUsbdev::UsbControlField : uint32_t

strong

Definitions of fields (and their locations) for the USB Control register (offset 0x10).

https://opentitan.org/book/hw/ip/usbdev/doc/registers.html#usbctrl

Definition at line 173 of file platform-usbdev.hh.

◆ UsbdevInterrupt

enum class OpenTitanUsbdev::UsbdevInterrupt : uint32_t

strong

Interrupt definitions for OpenTitan's USB Device.

Enumerator
PacketReceived	Interrupt asserted whilst the receive FIFO (buffer) is not empty.
PacketSent	Interrupt asserted when a packet was sent as part of an IN transaction, but not cleared from the inSent register.
Disconnected	Interrupt raised when VBUS (power supply) is lost, i.e. the link to the USB host controller has been disconnected.
HostLost	Interrupt raised when the link is active, but a Start of Frame (SOF) packet has not been received within a given timeout threshold, which is set to 4.096 milliseconds.
LinkReset	Interrupt raised when a Bus Reset condition is indicated on the link by the link being held in an SE0 state (Single Ended Zero, both lines being pulled low) for longer than 3 microseconds.
LinkSuspend	Interrupt raised when the link has entered the suspend state, due to being idle for more than 3 milliseconds.
LinkResume	Interrupt raised on link transition from suspended to non-idle.
AvailableOutEmpty	Interrupt asserted whilst the Available OUT buffer is empty.
ReceiveFull	Interrupt asserted whilst the Receive buffer is full.
AvailableBufferOverflow	Interrupt raised when the Available OUT buffer or the Available SETUP buffer overflows.
LinkInError	Interrupt raised when an error occurs during an IN transaction.
RedundancyCheckError	Interrupt raised when a CRC (cyclic redundancy check) error occurs on a received packet; i.e. there was an error in transmission.
PacketIdentifierError	Interrupt raised when an invalid Packet Identifier is received.
BitstuffingError	Interrupt raised when a bit stuffing violation is detected.
FrameUpdated	Interrupt raised when the USB frame number is updated with a valid SOF (Start of Frame) packet.
Powered	Interrupt raised when VBUS (power supply) is detected.
LinkOutError	Interrupt raised when an error occurs during an OUT transaction.
AvailableSetupEmpty	Interrupt asserted whilst the Available SETUP buffer is empty.

Definition at line 101 of file platform-usbdev.hh.

◆ UsbStatusField

enum class OpenTitanUsbdev::UsbStatusField : uint32_t

strong

Definitions of fields (and their locations) for the USB Status register (offset 0x1c).

https://opentitan.org/book/hw/ip/usbdev/doc/registers.html#usbstat

Definition at line 186 of file platform-usbdev.hh.

Member Function Documentation

◆ connect()

int OpenTitanUsbdev::connect ( ) volatile

inlinenodiscard

Connect the device to the USB, indicating its presence to the USB host controller.

Endpoints must already have been configured at this point because traffic may be received imminently.

Returns: 0 if successful, and non-zero otherwise.; -1 if endpoint 0 isn't enabled, suggesting the endpoints haven't been configured.

Definition at line 403 of file platform-usbdev.hh.

◆ connected()

bool OpenTitanUsbdev::connected ( ) volatile

inlinenodiscard

Check whether the USB device is connected (i.e.

pullup enabled).

Returns: True to indicate it is connected, and false otherwise.

Definition at line 430 of file platform-usbdev.hh.

◆ device_address_set()

int OpenTitanUsbdev::device_address_set ( uint8_t address ) volatile

inlinenodiscard

Set the device address on the USB; this address will have been supplied by the USB host controller in the standard SET_ADDRESS Control Transfer.

Parameters

address The device address to set on the USB.

Returns: 0 if successful, and non-zero otherwise.

Definition at line 444 of file platform-usbdev.hh.

◆ disconnect()

void OpenTitanUsbdev::disconnect ( ) volatile

inline

Disconnect the device from the USB.

Returns: 0 if successful, and non-zero otherwise.

Definition at line 419 of file platform-usbdev.hh.

◆ endpoint_stalling_set()

int OpenTitanUsbdev::endpoint_stalling_set	(	uint8_t	endpointId,
		bool	stalling ) volatile

inlinenodiscard

Set the STALL state of a specified endpoint pair (both IN and OUT).

Parameters

endpointId	The ID of the endpoint pair to modify.
stalling	Whether the endpoints are stalling or not.

Returns: 0 if successful, and non-zero otherwise.

Definition at line 381 of file platform-usbdev.hh.

References outStall.

◆ in_endpoint_configure()

int OpenTitanUsbdev::in_endpoint_configure	(	uint8_t	endpointId,
		bool	enabled,
		bool	isochronous ) volatile

inlinenodiscard

Set up the configuration of an IN endpoint for the USB device.

Parameters

endpointId	The ID of the IN endpoint to configure
enabled	Whether the IN endpoint should be enabled or not.
isochronous	Whether the endpoint should operate isochronously or non-isochronously.

Returns: 0 if configuration is successful, and non-zero otherwise.

Definition at line 359 of file platform-usbdev.hh.

◆ init()

int OpenTitanUsbdev::init ( uint64_t & bufferBitmap ) volatile

inlinenodiscard

Initialise the USB device, ensuring that packet buffers are available for reception and that the PHY has been appropriately configured.

Note that at this stage, endpoints have not been configured and the device has not been connected to the USB.

Parameters

bufferBitmap An out-parameter, to initialise a bitmap of the buffers that are not currently commited (1 corresponds to not in use).

Returns: 0 if initialisation is sucessful, and non-zero otherwise.

Definition at line 311 of file platform-usbdev.hh.

References phyConfig, and supply_buffers().

◆ interrupt_disable()

void OpenTitanUsbdev::interrupt_disable ( UsbdevInterrupt interrupt ) volatile

inline

Disable a specified interrupt / interrupts.

Definition at line 295 of file platform-usbdev.hh.

◆ interrupt_enable()

void OpenTitanUsbdev::interrupt_enable ( UsbdevInterrupt interrupt ) volatile

inline

Enable a specified interrupt / interrupts.

Definition at line 287 of file platform-usbdev.hh.

◆ out_endpoint_configure()

int OpenTitanUsbdev::out_endpoint_configure	(	uint8_t	endpointId,
		bool	enabled,
		bool	setup,
		bool	isochronous ) volatile

inlinenodiscard

Set up the configuration of an OUT endpoint for the USB device.

Parameters

endpointId	The ID of the OUT endpoint to configure.
enabled	Whether the OUT endpoint should be enabled or not.
setup	Whether SETUP transactions should be enabled for the endpoint.
isochronous	Whether the endpoint should operate isochronously or non-isochronously.

Returns: 0 if configuration is successful, and non-zero otherwise.

Definition at line 332 of file platform-usbdev.hh.

References outIsochronous, receiveEnableOut, and receiveEnableSetup.

◆ packet_data_get()

void OpenTitanUsbdev::packet_data_get	(	ReceiveBufferInfo	bufferInfo,
		uint32_t *	destination ) volatile

inline

Retrieves the data from a buffer containing a received packet.

Parameters

destination A destination buffer to read the packet's data into.

Definition at line 574 of file platform-usbdev.hh.

References OpenTitanUsbdev::ReceiveBufferInfo::buffer_id(), and OpenTitanUsbdev::ReceiveBufferInfo::size().

◆ packet_send()

void OpenTitanUsbdev::packet_send	(	uint8_t	bufferId,
		uint8_t	endpointId,
		const uint32_t *	data,
		uint8_t	size ) volatile

inline

Present a packet on the specified IN endpoint for collection by the USB host controller.

Parameters

bufferId	The buffer to use to store the packet.
endpointId	The IN endpoint used to send the packet.
data	The packet to be transmitted.
size	The size of the packet.

Definition at line 502 of file platform-usbdev.hh.

References configIn.

◆ packet_take()

std::optional< ReceiveBufferInfo > OpenTitanUsbdev::packet_take ( ) volatile

inlinenodiscard

If a packet has been received, removes the packet's buffer from the receive FIFO giving it's information and ownership to the user.

packet_data_get can be used to retrieve the packet's data.

Returns: Information about the received packet, if a packet had been received.

Definition at line 560 of file platform-usbdev.hh.

◆ retrieve_collected_packet()

int OpenTitanUsbdev::retrieve_collected_packet	(	uint8_t &	endpointId,
		uint8_t &	bufferId ) volatile

inlinenodiscard

Check and retrieve the endpoint and buffer numbers of a recently-collected IN data packet.

The caller is responsible for reusing or releasing the buffer.

Parameters

endpointId	An out-parameter, to which the ID of the endpoint for a recently-collected IN data packet will be written.
bufferId	An out-parameter, to which the ID of the buffer for a recently-collected IN data packet will be written.

Returns: 0 if successful, and non-zero otherwise.

Definition at line 468 of file platform-usbdev.hh.

References configIn, and inSent.

◆ supply_buffers()

uint64_t OpenTitanUsbdev::supply_buffers ( uint64_t bufferBitmap ) volatile

inlinenodiscard

Ensure that the Available OUT and Available SETUP buffers are kept supplied with buffers for packet reception.

Parameters

bufferBitmap A bitmap of the buffers that are not currently committed (where 1 corresponds to not in use).

Returns: The updated bitmap after supplying buffers.

Definition at line 250 of file platform-usbdev.hh.

Referenced by init().

Member Data Documentation

◆ alertTest

uint32_t OpenTitanUsbdev::alertTest

Definition at line 49 of file platform-usbdev.hh.

◆ availableOutBuffer

uint32_t OpenTitanUsbdev::availableOutBuffer

Definition at line 54 of file platform-usbdev.hh.

◆ availableSetupBuffer

uint32_t OpenTitanUsbdev::availableSetupBuffer

Definition at line 55 of file platform-usbdev.hh.

◆ BufferCount

uint8_t OpenTitanUsbdev::BufferCount = 32u

staticconstexpr

Definition at line 36 of file platform-usbdev.hh.

◆ BufferStartAddress

uint32_t OpenTitanUsbdev::BufferStartAddress = 0x800u

staticconstexpr

The offset from the start of the USB Device MMIO region at which packet buffer memory begins.

Definition at line 43 of file platform-usbdev.hh.

◆ configIn

uint32_t OpenTitanUsbdev::configIn[MaxEndpoints]

IN transaction configuration registers.

There is one register per endpoint for the USB device.

Definition at line 72 of file platform-usbdev.hh.

Referenced by packet_send(), and retrieve_collected_packet().

◆ endpointInEnable

uint32_t OpenTitanUsbdev::endpointInEnable

Definition at line 52 of file platform-usbdev.hh.

◆ endpointOutEnable

uint32_t OpenTitanUsbdev::endpointOutEnable

Definition at line 51 of file platform-usbdev.hh.

◆ inDataToggle

uint32_t OpenTitanUsbdev::inDataToggle

Definition at line 83 of file platform-usbdev.hh.

◆ inIsochronous

uint32_t OpenTitanUsbdev::inIsochronous

Definition at line 80 of file platform-usbdev.hh.

◆ inSent

uint32_t OpenTitanUsbdev::inSent

Register showing ACK receival to indicate a successful IN send.

Definition at line 64 of file platform-usbdev.hh.

Referenced by retrieve_collected_packet().

◆ inStall

uint32_t OpenTitanUsbdev::inStall

Definition at line 67 of file platform-usbdev.hh.

◆ interruptEnable

uint32_t OpenTitanUsbdev::interruptEnable

Definition at line 47 of file platform-usbdev.hh.

◆ interruptState

uint32_t OpenTitanUsbdev::interruptState

Device Registers.

Definition at line 46 of file platform-usbdev.hh.

◆ interruptTest

uint32_t OpenTitanUsbdev::interruptTest

Definition at line 48 of file platform-usbdev.hh.

◆ MaxEndpoints

uint8_t OpenTitanUsbdev::MaxEndpoints = 12u

staticconstexpr

Definition at line 37 of file platform-usbdev.hh.

◆ MaxPacketLength

uint8_t OpenTitanUsbdev::MaxPacketLength = 64u

staticconstexpr

Supported sizes for the USB Device.

Definition at line 35 of file platform-usbdev.hh.

◆ outDataToggle

uint32_t OpenTitanUsbdev::outDataToggle

Registers for configuring if endpoints data toggle on transactions.

Definition at line 82 of file platform-usbdev.hh.

◆ outIsochronous

uint32_t OpenTitanUsbdev::outIsochronous

Registers for configuring which endpoints should be treated as isochronous endpoints.

This means that if the corresponding bit is set, then that no handshake packet will be sent for an OUT/IN transaction on that endpoint.

Definition at line 79 of file platform-usbdev.hh.

Referenced by out_endpoint_configure().

◆ outStall

uint32_t OpenTitanUsbdev::outStall

Registers for controlling the stalling of OUT and IN endpoints.

Definition at line 66 of file platform-usbdev.hh.

Referenced by endpoint_stalling_set().

◆ phyConfig

uint32_t OpenTitanUsbdev::phyConfig

Config register for the USB PHY pins.

Definition at line 98 of file platform-usbdev.hh.

Referenced by init().

◆ receiveBuffer

uint32_t OpenTitanUsbdev::receiveBuffer

Definition at line 56 of file platform-usbdev.hh.

◆ receiveEnableOut

uint32_t OpenTitanUsbdev::receiveEnableOut

Register to enable receive OUT transactions.

Definition at line 60 of file platform-usbdev.hh.

Referenced by out_endpoint_configure().

◆ receiveEnableSetup

uint32_t OpenTitanUsbdev::receiveEnableSetup

Register to enable receive SETUP transactions.

Definition at line 58 of file platform-usbdev.hh.

Referenced by out_endpoint_configure().

◆ setNotAcknowledgeOut

uint32_t OpenTitanUsbdev::setNotAcknowledgeOut

Register to set NAK (Not/Negated Acknowledge) after OUT transactions.

Definition at line 62 of file platform-usbdev.hh.

◆ usbControl

uint32_t OpenTitanUsbdev::usbControl

Definition at line 50 of file platform-usbdev.hh.

◆ usbStatus

uint32_t OpenTitanUsbdev::usbStatus

Definition at line 53 of file platform-usbdev.hh.

The documentation for this class was generated from the following file:

sdk/include/platform/sunburst/platform-usbdev.hh

Classes

Public Types

Public Member Functions

Public Attributes

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ ConfigInField

◆ PhyConfigField

◆ ReceiveBufferField

◆ UsbControlField

◆ UsbdevInterrupt

◆ UsbStatusField

Member Function Documentation

◆ connect()

◆ connected()

◆ device_address_set()

◆ disconnect()

◆ endpoint_stalling_set()

◆ in_endpoint_configure()

◆ init()

◆ interrupt_disable()

◆ interrupt_enable()

◆ out_endpoint_configure()

◆ packet_data_get()

◆ packet_send()

◆ packet_take()

◆ retrieve_collected_packet()

◆ supply_buffers()

Member Data Documentation

◆ alertTest

◆ availableOutBuffer

◆ availableSetupBuffer

◆ BufferCount

◆ BufferStartAddress

◆ configIn

◆ endpointInEnable

◆ endpointOutEnable

◆ inDataToggle

◆ inIsochronous

◆ inSent

◆ inStall

◆ interruptEnable

◆ interruptState

◆ interruptTest

◆ MaxEndpoints

◆ MaxPacketLength

◆ outDataToggle

◆ outIsochronous

◆ outStall

◆ phyConfig

◆ receiveBuffer

◆ receiveEnableOut

◆ receiveEnableSetup

◆ setNotAcknowledgeOut

◆ usbControl

◆ usbStatus