USB Device raw IP driver

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

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.

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.

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.

Number of bytes in the endpoint.

Constant that informs about endpoint size

The size of internal feeder buffer.

See Also

nrf_drv_usbd_feeder_buffer_get

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

Helper macro for declaring IN transfer description.

Normal transfer mode, no ZLP would be automatically generated.

See Also

nrf_drv_usbd_transfer_t

NRF_DRV_USBD_TRANSFER_IN_ZLP

Parameters

name	Instance name
tx_buff	Buffer to transfer
tx_size	Transfer size

Returns

Configured variable with total transfer description

Auxiliary macro for declaring IN transfer description with flags.

The base macro for creating transfers with any configuration option.

Parameters

name	Instance name.
tx_buff	Buffer to transfer.
tx_size	Transfer size.
tx_flags	Flags for the transfer (see nrf_drv_usbd_transfer_flags_t ).

Returns

Configured variable with total transfer description.

Helper macro for declaring IN transfer description.

ZLP mode - Zero Length Packet would be generated on the end of the transfer (always!).

See Also

nrf_drv_usbd_transfer_t

NRF_DRV_USBD_TRANSFER_IN

Parameters

name	Instance name
tx_buff	Buffer to transfer
tx_size	Transfer size

Returns

Configured variable with total transfer description

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

USBD transfer consumer.

Pointer for a transfer consumer. Transfer consumer is a feedback function used to prepare a single RX (Host->Device) endpoint transfer.

The transfer must provide a buffer big enough to fit the whole data from the endpoint. Otherwise, the NRF_USBD_EP_OVERLOAD event is generated.

Parameters

[out]	p_next	Structure with the data for the next transfer to be filled. Required only if the function returns true.
[in,out]	p_context	Context variable configured with the transfer.
[in]	ep_size	The endpoint size.
[in]	data_size	Number of received bytes in the endpoint buffer.

Return values

false	Current transfer is the last one - you do not need to call the function again.
true	There is more data to be prepared and when current transfer finishes, the feeder function is expected to be called again.

USBD event callback function type.

Parameters

[in]

p_event

Event information structure.

USBD transfer feeder.

Pointer for a transfer feeder. Transfer feeder is a feedback function used to prepare a single TX (Device->Host) endpoint transfer.

The transfers provided by the feeder must be simple:

• The size of the transfer provided by this function is limited to a single endpoint buffer. Bigger transfers are not handled automatically in this case.
• Flash transfers are not automatically supported- you must copy them to the RAM buffer before.

Note

This function may use nrf_drv_usbd_feeder_buffer_get to gain a temporary buffer that can be used to prepare transfer.

Parameters

[out]	p_next	Structure with the data for the next transfer to be filled. Required only if the function returns true.
[in,out]	p_context	Context variable configured with the transfer.
[in]	ep_size	The endpoint size.

Return values

false	The current transfer is the last one - you do not need to call the function again.
true	There is more data to be prepared and when the current transfer finishes, the feeder function is expected to be called again.

Possible endpoint error codes.

Error codes that may be returned with NRF_DRV_USBD_EVT_EPTRANSFER

Endpoint identifier.

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

Events generated by the library.

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

Flags for the current transfer.

Flags configured for the transfer that can be merged using the bitwise 'or' operator (|).

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.

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.

Disable selected endpoint.

This function disables endpoint itself and its interrupts.

Parameters

ep	Endpoint number to disable

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

Check if the selected endpoint is enabled.

Parameters

ep	Endpoint number to check.

Return values

true	Endpoint is enabled.
false	Endpoint is disabled.

Start sending data over the endpoint using the transfer handler function.

This function initializes an endpoint transmission. Just before data is transmitted, the transfer handler is called and it prepares a data chunk.

Parameters

[in]	ep	Endpoint number. For an IN endpoint, sending is initiated. For an OUT endpoint, receiving is initiated.
	p_handler	Transfer handler - feeder for IN direction and consumer for OUT direction.

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.

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.

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

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.

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

Check if endpoint is stalled.

This function gets stall state of selected endpoint

Parameters

ep	Endpoint number to check

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.

Get the information about last finished or current 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_size	Information about the current/last transfer size.

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.

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

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.

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

Get the temporary buffer to be used by the feeder.

This buffer is used for TX transfers and it can be reused automatically when the transfer is finished. Use it for transfer preparation.

May be used inside the feeder configured in nrf_drv_usbd_ep_handled_transfer .

Returns

Pointer to the buffer that can be used temporarily.

See Also

NRF_DRV_USBD_FEEDER_BUFFER_SIZE

Library initialization.

Parameters

[in]

event_handler

Event handler provided by the user.

Check if driver is enabled.

Return values

false	Driver is disabled
true	Driver is enabled

Check if driver is initialized.

Return values

false	Driver is not initialized
true	Driver is initialized

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

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

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.

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

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.

Stall setup endpoint.

Mark and error on setup endpoint.

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.

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 .

Drop transfer on OUT endpoint.

Parameters

[in]

ep

OUT endpoint ID

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.