nRF52840 only: USB Device raw IP driver. More...

Data Structures
struct	nrf_drv_usbd_evt_t
	Event structure. More...

struct	nrf_drv_usbd_transfer_t
	The structure to be filled with the information about next transfer. More...

struct	nrf_drv_usbd_transfer_handler_desc_t
	USBD transfer callback structure. More...

struct	nrf_drv_usbd_setup_t
	Setup packet structure. More...

Macros
#define	NRF_DRV_USBD_EPSIZE 64
	Number of bytes in the endpoint. More...

#define	NRF_DRV_USBD_ISOSIZE 1024
	Number of bytes for isochronous endpoints. More...

#define	NRF_DRV_USBD_EP_TRANSFER_EVENT(name, endpont, ep_stat)
	Helper macro to create endpoint transfer event. More...

#define	NRF_DRV_USBD_TRANSFER_IN(name, tx_buff, tx_size)
	Helper macro for declaring IN transfer item (nrf_drv_usbd_transfer_t) More...

#define	NRF_DRV_USBD_TRANSFER_OUT(name, rx_buff, rx_size)
	Helper macro for declaring OUT transfer item (nrf_drv_usbd_transfer_t) More...

Typedefs
typedef void(*	nrf_drv_usbd_event_handler_t )(nrf_drv_usbd_evt_t const *const p_event)
	USBD event callback function type. More...

typedef bool(*	nrf_drv_usbd_next_transfer_handler_t )(nrf_drv_usbd_transfer_t p_next, void p_context)
	USBD event callback for the endpoint. More...

Enumerations
enum	nrf_drv_usbd_ep_t { NRF_DRV_USBD_EPOUT0 = NRF_USBD_EPOUT(0), NRF_DRV_USBD_EPOUT1 = NRF_USBD_EPOUT(1), NRF_DRV_USBD_EPOUT2 = NRF_USBD_EPOUT(2), NRF_DRV_USBD_EPOUT3 = NRF_USBD_EPOUT(3), NRF_DRV_USBD_EPOUT4 = NRF_USBD_EPOUT(4), NRF_DRV_USBD_EPOUT5 = NRF_USBD_EPOUT(5), NRF_DRV_USBD_EPOUT6 = NRF_USBD_EPOUT(6), NRF_DRV_USBD_EPOUT7 = NRF_USBD_EPOUT(7), NRF_DRV_USBD_EPOUT8 = NRF_USBD_EPOUT(8), NRF_DRV_USBD_EPIN0 = NRF_USBD_EPIN(0), NRF_DRV_USBD_EPIN1 = NRF_USBD_EPIN(1), NRF_DRV_USBD_EPIN2 = NRF_USBD_EPIN(2), NRF_DRV_USBD_EPIN3 = NRF_USBD_EPIN(3), NRF_DRV_USBD_EPIN4 = NRF_USBD_EPIN(4), NRF_DRV_USBD_EPIN5 = NRF_USBD_EPIN(5), NRF_DRV_USBD_EPIN6 = NRF_USBD_EPIN(6), NRF_DRV_USBD_EPIN7 = NRF_USBD_EPIN(7), NRF_DRV_USBD_EPIN8 = NRF_USBD_EPIN(8) }
	Endpoint identifier. More...

enum	nrf_drv_usbd_event_type_t { NRF_DRV_USBD_EVT_SOF, NRF_DRV_USBD_EVT_RESET, NRF_DRV_USBD_EVT_SUSPEND, NRF_DRV_USBD_EVT_RESUME, NRF_DRV_USBD_EVT_SETUP, NRF_DRV_USBD_EVT_EPTRANSFER, NRF_DRV_USBD_EVT_CNT }
	Events generated by the library. More...

enum	nrf_drv_usbd_ep_status_t { NRF_USBD_EP_OK, NRF_USBD_EP_WAITING, NRF_USBD_EP_OVERLOAD, NRF_USBD_EP_ABORTED }
	Possible endpoint error codes. More...

Functions
ret_code_t	nrf_drv_usbd_init (nrf_drv_usbd_event_handler_t const event_handler)
	Library initialization. More...

ret_code_t	nrf_drv_usbd_uninit (void)
	Library deinitialization.

void	nrf_drv_usbd_enable (void)
	Enable the USBD port. More...

void	nrf_drv_usbd_disable (void)
	Disable the USBD port. More...

void	nrf_drv_usbd_start (bool enable_sof)
	Start USB functionality. More...

void	nrf_drv_usbd_stop (void)
	Stop USB functionality. More...

bool	nrf_drv_usbd_is_initialized (void)
	Check if driver is initialized. More...

bool	nrf_drv_usbd_is_enabled (void)
	Check if driver is enabled. More...

bool	nrf_drv_usbd_is_started (void)
	Check if driver is started. More...

void	nrf_drv_usbd_ep_max_packet_size_set (nrf_drv_usbd_ep_t ep, uint16_t size)
	Configure packet size that should be supported by the endpoint. More...

uint16_t	nrf_drv_usbd_ep_max_packet_size_get (nrf_drv_usbd_ep_t ep)
	Get configured endpoint packet size. More...

void	nrf_drv_usbd_ep_enable (nrf_drv_usbd_ep_t ep)
	Enable selected endpoint. More...

void	nrf_drv_usbd_ep_disable (nrf_drv_usbd_ep_t ep)
	Disable selected endpoint. More...

ret_code_t	nrf_drv_usbd_ep_transfer (nrf_drv_usbd_ep_t ep, nrf_drv_usbd_transfer_t const const p_transfer, nrf_drv_usbd_transfer_handler_desc_t const const p_handler)
	Start sending data over endpoint. More...

ret_code_t	nrf_drv_usbd_ep_status_get (nrf_drv_usbd_ep_t ep, nrf_drv_usbd_transfer_t *p_transfer)
	Get the information about last finished transfer. More...

size_t	nrf_drv_usbd_epout_size_get (nrf_drv_usbd_ep_t ep)
	Get number of received bytes. More...

bool	nrf_drv_usbd_ep_is_busy (nrf_drv_usbd_ep_t ep)
	Check if endpoint buffer is ready or is under USB IP control. More...

void	nrf_drv_usbd_ep_stall (nrf_drv_usbd_ep_t ep)
	Stall endpoint. More...

void	nrf_drv_usbd_ep_stall_clear (nrf_drv_usbd_ep_t ep)
	Clear stall flag on endpoint. More...

bool	nrf_drv_usbd_ep_stall_check (nrf_drv_usbd_ep_t ep)
	Check if endpoint is stalled. More...

void	nrf_drv_usbd_setup_get (nrf_drv_usbd_setup_t *const p_setup)
	Get parsed setup data. More...

void	nrf_drv_usbd_setup_data_clear (void)
	Clear only for data transmission on setup endpoint. More...

void	nrf_drv_usbd_setup_clear (void)
	Clear setup endpoint. More...

void	nrf_drv_usbd_setup_stall (void)
	Stall setup endpoint. More...

void	usbd_drv_ep_abort (nrf_drv_usbd_ep_t ep)

nrf_drv_usbd_ep_t	nrf_drv_usbd_last_setup_dir_get (void)
	Get the information about expected transfer SETUP data direction. More...

void	nrf_drv_usbd_transfer_out_drop (nrf_drv_usbd_ep_t ep)
	Drop transfer on OUT endpoint. More...

Possible schemes of DMA scheduling
Definition of available configuration constants used by DMA scheduler
#define	NRF_DRV_USBD_DMASCHEDULER_PRIORITIZED 0
	Highly prioritized access. More...

#define	NRF_DRV_USBD_DMASCHEDULER_ROUNDROBIN 1
	Round robin scheme. More...

Macros for creating endpoint identifiers
Auxiliary macros to be used to create Endpoint identifier that is compatible with USB specification.
#define	NRF_DRV_USBD_EPIN(n) ((nrf_drv_usbd_ep_t)NRF_USBD_EPIN(n))
	Create identifier for IN endpoint. More...

#define	NRF_DRV_USBD_EPOUT(n) ((nrf_drv_usbd_ep_t)NRF_USBD_EPOUT(n))
	Create identifier for OUT endpoint. More...

Detailed Description

nRF52840 only: USB Device raw IP driver.

Macro Definition Documentation

#define NRF_DRV_USBD_DMASCHEDULER_PRIORITIZED 0

Highly prioritized access.

Endpoint with lower number has always higher priority and its data would be transfered first. OUT endpoints ale processed before IN endpoints

#define NRF_DRV_USBD_DMASCHEDULER_ROUNDROBIN 1

Round robin scheme.

All endpoints are processed in round-robin scheme. It means that when one endpoint is processed next in order would be the nearest with lower number. When no endpoints with lower number requires processing - then all endpoints from 0 are tested.

#define NRF_DRV_USBD_EP_TRANSFER_EVENT	(	name,
		endpont,
		ep_stat
	)

Value:

nrf_drv_usbd_evt_t name = { \
 NRF_DRV_USBD_EVT_EPTRANSFER, \
 .data = { \
 .eptransfer = { \
 .ep = endpont, \
 .status = ep_stat \
 } \
 } \
 }

Helper macro to create endpoint transfer event.

#define NRF_DRV_USBD_EPIN ( n ) ((nrf_drv_usbd_ep_t)NRF_USBD_EPIN(n))

Create identifier for IN endpoint.

Simple macro to create IN endpoint identifier for given endpoint number.

Parameters

[in] n Endpoint number.

Returns: Endpoint identifier that connects endpoint number and endpoint direction.

#define NRF_DRV_USBD_EPOUT ( n ) ((nrf_drv_usbd_ep_t)NRF_USBD_EPOUT(n))

Create identifier for OUT endpoint.

Simple macro to create OUT endpoint identifier for given endpoint number.

Parameters

[in] n Endpoint number.

Returns: Endpoint identifier that connects endpoint number and endpoint direction.

#define NRF_DRV_USBD_EPSIZE 64

Number of bytes in the endpoint.

Constant that informs about endpoint size

#define NRF_DRV_USBD_ISOSIZE 1024

Number of bytes for isochronous endpoints.

Number of bytes for isochronous endpoints in total. This number would be shared between IN and OUT endpoint. It may be also assigned totaly to one endpoint.

See Also: nrf_usbd_isosplit_set; nrf_usbd_isosplit_get

#define NRF_DRV_USBD_TRANSFER_IN	(	name,
		tx_buff,
		tx_size
	)

Value:

nrf_drv_usbd_transfer_t name = { \
 .p_data = { .tx = (tx_buff) }, \
 .size = (tx_size), \
 }

Helper macro for declaring IN transfer item (nrf_drv_usbd_transfer_t)

Parameters

name	Instance name
tx_buff	Buffer to transfer
tx_size	Transfer size

#define NRF_DRV_USBD_TRANSFER_OUT	(	name,
		rx_buff,
		rx_size
	)

Value:

nrf_drv_usbd_transfer_t name = { \
 .p_data = { .rx = (rx_buff) }, \
 .size = (rx_size), \
 }

Helper macro for declaring OUT transfer item (nrf_drv_usbd_transfer_t)

Parameters

name	Instance name
rx_buff	Buffer to transfer
rx_size	Transfer size

Typedef Documentation

typedef void(* nrf_drv_usbd_event_handler_t)(nrf_drv_usbd_evt_t const *const p_event)

USBD event callback function type.

Parameters

[in] p_event Event information structure.

typedef bool(* nrf_drv_usbd_next_transfer_handler_t)(nrf_drv_usbd_transfer_t *p_next, void *p_context)

USBD event callback for the endpoint.

Parameters

[out]	p_next	Structure with the data for the next transfer to be filled. Required only if the function returns true.
[in]	p_contex	Contex variable configured with the endpoint.

Return values

false	Nothing more to transfer
true	Settings to the next transfer filled into `p_next`.

Enumeration Type Documentation

enum nrf_drv_usbd_ep_status_t

Possible endpoint error codes.

Error codes that may be returned with NRF_DRV_USBD_EVT_EPTRANSFER

Enumerator
NRF_USBD_EP_OK	No error
NRF_USBD_EP_WAITING	Data received, no buffer prepared already - waiting for configured transfer
NRF_USBD_EP_OVERLOAD	Received number of bytes cannot fit given buffer This error would also be returned when next_transfer function has been defined but currently received data cannot fit completely in current buffer. No data split from single endpoint transmission is supported. When this error is reported - data is left inside endpoint buffer. Clear endpoint or prepare new buffer and read it.
NRF_USBD_EP_ABORTED	EP0 transfer can be aborted when new setup comes. Any other transfer can be aborted by USB reset or library stopping.

enum nrf_drv_usbd_ep_t

Endpoint identifier.

Endpoint identifier used in the driver. This endpoint number is consistent with USB 2.0 specification.

Enumerator
NRF_DRV_USBD_EPOUT0	Endpoint OUT 0
NRF_DRV_USBD_EPOUT1	Endpoint OUT 1
NRF_DRV_USBD_EPOUT2	Endpoint OUT 2
NRF_DRV_USBD_EPOUT3	Endpoint OUT 3
NRF_DRV_USBD_EPOUT4	Endpoint OUT 4
NRF_DRV_USBD_EPOUT5	Endpoint OUT 5
NRF_DRV_USBD_EPOUT6	Endpoint OUT 6
NRF_DRV_USBD_EPOUT7	Endpoint OUT 7
NRF_DRV_USBD_EPOUT8	Endpoint OUT 8
NRF_DRV_USBD_EPIN0	Endpoint IN 0
NRF_DRV_USBD_EPIN1	Endpoint IN 1
NRF_DRV_USBD_EPIN2	Endpoint IN 2
NRF_DRV_USBD_EPIN3	Endpoint IN 3
NRF_DRV_USBD_EPIN4	Endpoint IN 4
NRF_DRV_USBD_EPIN5	Endpoint IN 5
NRF_DRV_USBD_EPIN6	Endpoint IN 6
NRF_DRV_USBD_EPIN7	Endpoint IN 7
NRF_DRV_USBD_EPIN8	Endpoint IN 8

enum nrf_drv_usbd_event_type_t

Events generated by the library.

Enumeration of possible events that may be generated by the library.

Enumerator
NRF_DRV_USBD_EVT_SOF	Start Of Frame event on USB bus detected
NRF_DRV_USBD_EVT_RESET	Reset condition on USB bus detected
NRF_DRV_USBD_EVT_SUSPEND	This device should go to suspend mode now
NRF_DRV_USBD_EVT_RESUME	This device should resume from suspend now
NRF_DRV_USBD_EVT_SETUP	Setup frame received and decoded
NRF_DRV_USBD_EVT_EPTRANSFER	For Rx (OUT: Host->Device): The packet has been received but there is no buffer prepared for transfer already. Whole transfer has been finished For Tx (IN: Device->Host): The last packet from requested transfer has been transfered over USB bus and acknowledged
NRF_DRV_USBD_EVT_CNT	Number of defined events

Function Documentation

void nrf_drv_usbd_disable ( void )

Disable the USBD port.

After calling this function USBD peripheral would be disabled. No events would be detected or processed by the library. Clock for the peripheral would be disconnected.

void nrf_drv_usbd_enable ( void )

Enable the USBD port.

After calling this function USBD peripheral would be enabled. It means that High Frequency clock would be requested and USB LDO would be enabled.

In normal situation this function should be called in reaction to USBDETECTED event from POWER peripheral.

Interrupts and USB pins pull-up would stay disabled until nrf_drv_usbd_start function is called.

void nrf_drv_usbd_ep_disable ( nrf_drv_usbd_ep_t ep )

Disable selected endpoint.

This function disables endpoint itself and its interrupts.

Parameters

ep	Endpoint number to disable

void nrf_drv_usbd_ep_enable ( nrf_drv_usbd_ep_t ep )

Enable selected endpoint.

This function enables endpoint itself and its interrupts.

Parameters

ep	Endpoint number to enable

Note: Max packet size is set to endpoint default maximum value.

See Also: nrf_drv_usbd_ep_max_packet_size_set

bool nrf_drv_usbd_ep_is_busy ( nrf_drv_usbd_ep_t ep )

Check if endpoint buffer is ready or is under USB IP control.

Function to test if endpoint is busy. Endpoint that is busy cannot be accessed by MCU. It means that:

OUT (TX) endpoint: Last uploaded data is still in endpoint and is waiting to be received by the host.
IN (RX) endpoint: Endpoint is ready to receive data from the host and the endpoint does not have any data. When endpoint is not busy:
OUT (TX) endpoint: New data can be uploaded.
IN (RX) endpoint: New data can be downloaded using nrf_drv_usbd_ep_transfer function.

uint16_t nrf_drv_usbd_ep_max_packet_size_get ( nrf_drv_usbd_ep_t ep )

Get configured endpoint packet size.

Function to get configured endpoint size on the buffer.

Parameters

[in] ep Endpoint number

Returns: Maximum pocket size configured on selected endpoint

void nrf_drv_usbd_ep_max_packet_size_set	(	nrf_drv_usbd_ep_t	ep,
		uint16_t	size
	)

Configure packet size that should be supported by the endpoint.

The real endpoint buffer size is always the same. This value sets max packet size that would be transmitted over the endpoint. This is required by the library

Parameters

[in]	ep	Endpoint number
[in]	size	Required maximum packet size

Note: Endpoint size is always set to NRF_DRV_USBD_EPSIZE or NRF_DRV_USBD_ISOSIZE / 2 when nrf_drv_usbd_ep_enable function is called.

void nrf_drv_usbd_ep_stall ( nrf_drv_usbd_ep_t ep )

Stall endpoint.

Stall endpoit to send error information during next transfer request from the host.

Note: To stall endpoint it is safer to use nrf_drv_usbd_setup_stall; Stalled endpoint would not be cleared when DMA transfer finishes.

Parameters

ep	Endpoint number to stall

bool nrf_drv_usbd_ep_stall_check ( nrf_drv_usbd_ep_t ep )

Check if endpoint is stalled.

This function gets stall state of selected endpoint

Parameters

ep	Endpoint number to check

void nrf_drv_usbd_ep_stall_clear ( nrf_drv_usbd_ep_t ep )

Clear stall flag on endpoint.

This function clears endpoint that is stalled.

Note: If it is OUT endpoint (receiving) it would be also prepared for reception. It means that busy flag would be set.; In endpoint (transmitting) would not be cleared - it gives possibility to write new data before transmitting.

ret_code_t nrf_drv_usbd_ep_status_get	(	nrf_drv_usbd_ep_t	ep,
		nrf_drv_usbd_transfer_t *	p_transfer
	)

Get the information about last finished transfer.

Function returns the status of the last buffer set for transfer on selected endpoint. The status considers last buffer set by nrf_drv_usbd_ep_transfer function or by transfer callback function.

Parameters

[in]	ep	Endpoint number.
[out]	p_transfer	Structure that would be filled by transfer details: buffer pointer and number of bytes received.

Return values

NRF_SUCCESS	Transfer already finished
NRF_ERROR_BUSY	Ongoing transfer
NRF_ERROR_DATA_SIZE	Too much of data received that cannot fit into buffer and cannot be splited into chunks. This may happen if buffer size is not a multiplication of endpoint buffer size.

ret_code_t nrf_drv_usbd_ep_transfer	(	nrf_drv_usbd_ep_t	ep,
		nrf_drv_usbd_transfer_t const *const	p_transfer,
		nrf_drv_usbd_transfer_handler_desc_t const *const	p_handler
	)

Start sending data over endpoint.

Function initializes endpoint transmission. This is asynchronous function - it finishes immediately after configuration for transmission is prepared.

Note: Data buffer pointed by p_data have to be kept active till NRF_DRV_USBD_EVT_EPTRANSFER event is generated.

Parameters

[in]	ep	Endpoint number. For IN endpoint sending would be initiated. For OUT endpoint receiving would be initiated.
[in]	p_transfer
[in]	p_handler	Description of transfer handler to be called when buffer is ready. Can be NULL when not required by the caller.

Return values

NRF_ERROR_BUSY	Selected endpoint is pending.
NRF_ERROR_INVALID_ADDR	Unexpected transfer on EPIN0 or EPOUT0.
NRF_ERROR_FORBIDDEN	Endpoint stalled.
NRF_SUCCESS	Transfer queued or started.

size_t nrf_drv_usbd_epout_size_get ( nrf_drv_usbd_ep_t ep )

Get number of received bytes.

Get the number of received bytes. The function behavior is undefined when called on IN endpoint.

Parameters

ep	Endpoint number.

Returns: Number of received bytes

ret_code_t nrf_drv_usbd_init ( nrf_drv_usbd_event_handler_t const event_handler )

Library initialization.

Parameters

[in] event_handler Event handler provided by the user.

bool nrf_drv_usbd_is_enabled ( void )

Check if driver is enabled.

Return values

false	Driver is disabled
true	Driver is enabled

bool nrf_drv_usbd_is_initialized ( void )

Check if driver is initialized.

Return values

false	Driver is not initialized
true	Driver is initialized

bool nrf_drv_usbd_is_started ( void )

Check if driver is started.

Return values

false	Driver is not started
true	Driver is started (fully functional)

Note: The USBD peripheral interrupt state is checked

nrf_drv_usbd_ep_t nrf_drv_usbd_last_setup_dir_get ( void )

Get the information about expected transfer SETUP data direction.

Function returns the information about last expected transfer direction.

Return values

NRF_DRV_USBD_EPOUT0	Expecting OUT (Host->Device) direction or no data
NRF_DRV_USBD_EPIN0	Expecting IN (Device->Host) direction

void nrf_drv_usbd_setup_clear ( void )

Clear setup endpoint.

This function acknowledges setup when SETUP command was received and processed. It has to be called if no data respond for the SETUP command is sent.

When there is any data transmission after SETUP command the data transmission itself would clear the endpoint.

void nrf_drv_usbd_setup_data_clear ( void )

Clear only for data transmission on setup endpoint.

This function may be called if any more data in control write transfer is expected. Clears only OUT endpoint to be able to take another OUT data token. It does not allow STATUS stage.

See Also: nrf_drv_usbd_setup_clear

void nrf_drv_usbd_setup_get ( nrf_drv_usbd_setup_t *const p_setup )

Get parsed setup data.

Function fills the parsed setup data structure.

Parameters

[out] p_setup Pointer to data structure that would be filled by parsed data.

void nrf_drv_usbd_setup_stall ( void )

Stall setup endpoint.

Mark and error on setup endpoint.

void nrf_drv_usbd_start ( bool enable_sof )

Start USB functionality.

After calling this function USBD peripheral should be fully functional and all new incoming events / interrupts would be processed by the library.

Also only after calling this function host sees new connected device.

Call this function when USBD power LDO regulator is ready - on USBPWRRDY event from POWER peripheral.

Parameters

enable_sof The flag that is used to enable SOF processing. If it is false, SOF interrupt is left disabled and will not be generated. This improves power saving if SOF is not required.

Note: If the isochronous endpoints are going to be used, it is required to enable the SOF. In other case any isochronous endpoint would stay busy after first transmission.

void nrf_drv_usbd_stop ( void )

Stop USB functionality.

This function disables USBD pull-up and interrupts.

Note: This function can also be used to logically disconnect USB from the HOST that would force it to enumerate device after calling nrf_drv_usbd_start.

void nrf_drv_usbd_transfer_out_drop ( nrf_drv_usbd_ep_t ep )

Drop transfer on OUT endpoint.

Parameters

[in] ep OUT endpoint ID

void usbd_drv_ep_abort ( nrf_drv_usbd_ep_t ep )

Note: This function locks interrupts that may be costly. It is good idea to test if the endpoint is still busy before calling this function:
(m_ep_dma_waiting & (1U << ep2bit(ep)))

This function would check it again, but it makes it inside critical section.

Data Structures

Macros

Typedefs

Enumerations

Functions

Possible schemes of DMA scheduling

Macros for creating endpoint identifiers

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation