cy_usbfs_dev_drv_8h

Provides API declarations of the USBFS driver.

Version

2.20.2

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0
Copyright

Copyright 2018-2020 Cypress Semiconductor Corporation SPDX-License-Identifier: Apache-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Defines

CY_USBFS_VERSION_MAJOR

USBFS Driver major version.

CY_USBFS_VERSION_MINOR

USBFS Driver minor version.

CY_USBFS_ID

USBFS Driver identifier.

CY_USBFS_MODE_POS

USBFS Driver mode position in STATUS CODE: 0 - Device, 1 - Host.

CY_USBFS_DEV_DRV_STATUS_CODE

USBFS Driver status code Device.

CY_USBFS_DEV_DRV_ALLOC_ENDPOINT_BUFFER(buf, size)

Allocates a static buffer for the data endpoint.

The size parameter must be a constant. The allocated buffer is aligned to a 2-byte boundary. An odd buffer size is converted to even, consuming 1 extra byte. The application must discard this extra byte to support different 8-bit and 16-bit hardware buffer access types in the driver. For more detail, refer to Hardware Buffer Access.

CY_USBFS_DEV_DRV_LVL_HIGH

The interrupt source is assigned to a trigger High interrupt.

CY_USBFS_DEV_DRV_LVL_MEDIUM

The interrupt source is assigned to a trigger Medium interrupt.

CY_USBFS_DEV_DRV_LVL_LOW

The interrupt source is assigned to a trigger Low interrupt.

CY_USBFS_DEV_DRV_SET_SOF_LVL(level)

Assigns the SOF interrupt source to a trigger interrupt: Low, Medium, or High.

CY_USBFS_DEV_DRV_SET_BUS_RESET_LVL(level)

Assigns the Bus Reset interrupt source to a trigger interrupt: Low, Medium, or High.

CY_USBFS_DEV_DRV_SET_EP0_LVL(level)

Assigns the Endpoint 0 interrupt source to a trigger interrupt Low, Medium, or High.

CY_USBFS_DEV_DRV_SET_LPM_LVL(level)

Assigns the LPM interrupt source to a trigger interrupt: Low, Medium, or High.

CY_USBFS_DEV_DRV_SET_RESUME_LVL(level)

Assigns the Resume interrupt source to a trigger interrupt: Low, Medium, or High.

CY_USBFS_DEV_DRV_SET_ARB_EP_LVL(level)

Assigns the Arbiter interrupt source to a trigger interrupt: Low, Medium, or High.

CY_USBFS_DEV_DRV_SET_EP1_LVL(level)

Assigns the Endpoint 1 interrupt source to a trigger interrupt: Low, Medium, or High.

CY_USBFS_DEV_DRV_SET_EP2_LVL(level)

Assigns the Endpoint 2 interrupt source to a trigger interrupt: Low, Medium, or High.

CY_USBFS_DEV_DRV_SET_EP3_LVL(level)

Assigns the Endpoint 3 interrupt source to a trigger interrupt: Low, Medium, or High.

CY_USBFS_DEV_DRV_SET_EP4_LVL(level)

Assigns the Endpoint 4 interrupt source to a trigger interrupt: Low, Medium, or High.

CY_USBFS_DEV_DRV_SET_EP5_LVL(level)

Assigns the Endpoint 5 interrupt source to a trigger interrupt: Low, Medium, or High.

CY_USBFS_DEV_DRV_SET_EP6_LVL(level)

Assigns the Endpoint 6 interrupt source to a trigger interrupt: Low, Medium, or High.

CY_USBFS_DEV_DRV_SET_EP7_LVL(level)

Assigns the Endpoint 7 interrupt source to a trigger interrupt: Low, Medium, or High.

CY_USBFS_DEV_DRV_SET_EP8_LVL(level)

Assigns the Endpoint 8 interrupt source to a trigger interrupt: Low, Medium, or High.

CY_USBFS_DEV_DRV_LPM_INTR

Link Power Management request interrupt.

CY_USBFS_DEV_DRV_ARBITER_INTR

Arbiter interrupt.

CY_USBFS_DEV_DRV_EP0_INTR

Endpoint 0 interrupt.

CY_USBFS_DEV_DRV_SOF_INTR

SOF interrupt.

CY_USBFS_DEV_DRV_BUS_RESET_INTR

Bus Reset interrupt.

CY_USBFS_DEV_DRV_EP1_INTR

Data endpoint 1 interrupt.

CY_USBFS_DEV_DRV_EP2_INTR

Data endpoint 2 interrupt.

CY_USBFS_DEV_DRV_EP3_INTR

Data endpoint 3 interrupt.

CY_USBFS_DEV_DRV_EP4_INTR

Data endpoint 4 interrupt.

CY_USBFS_DEV_DRV_EP5_INTR

Data endpoint 5 interrupt.

CY_USBFS_DEV_DRV_EP6_INTR

Data endpoint 6 interrupt.

CY_USBFS_DEV_DRV_EP7_INTR

Data endpoint 7 interrupt.

CY_USBFS_DEV_DRV_EP8_INTR

Data endpoint 8 interrupt.

CY_USBFS_DEV_ENDPOINT_TRANSFER_ERROR

An error occurred during a USB transfer.

For an IN transaction, this indicates a “no response” from the HOST scenario. For an OUT transaction, this represents a “PID or CRC error” or the bit-stuff error scenario.

CY_USBFS_DEV_ENDPOINT_SAME_DATA_TOGGLE

The data toggle bit remains the same.

The received OUT packet has the same data toggle bit that the previous packet had. This indicates that the Host retransmitted the packet.

Typedefs

typedef void (*cy_cb_usbfs_dev_drv_callback_t)(USBFS_Type *base, struct cy_stc_usbfs_dev_drv_context *context)

Provides the typedef for the callback function called in the Cy_USBFS_Dev_Drv_Interrupt to notify the user interrupt events.

typedef void (*cy_cb_usbfs_dev_drv_ep_callback_t)(USBFS_Type *base, uint32_t endpointAddr, uint32_t errorType, struct cy_stc_usbfs_dev_drv_context *context)

Provides the typedef for the callback function called in the Cy_USBFS_Dev_Drv_Interrupt to notify the user about endpoint transfer completion event.

typedef uint8_t *(*cy_fn_usbfs_dev_drv_memcpy_ptr_t)(uint8_t *dest, const uint8_t *src, uint32_t size)

Provides the typedef for the user defined function to replace library provided memcpy function to copy data from endpoint buffer to the user buffer.

Enums

enum cy_en_usbfs_dev_drv_status_t

cy_en_usbfs_dev_drv_status_t: USBFS Device Driver return codes.

Values:

enumerator CY_USBFS_DEV_DRV_SUCCESS

Operation completed successfully.

enumerator CY_USBFS_DEV_DRV_BAD_PARAM

One or more input parameters are invalid.

enumerator CY_USBFS_DEV_DRV_BUF_ALLOC_FAILED

There is not enough space in the buffer to be allocated for the endpoint (hardware or RAM)

enumerator CY_USBFS_DEV_DRV_DMA_CFG_FAILED

Failure during DMA configuration.

enumerator CY_USBFS_DEV_DRV_EP_DYN_RECONFIG_TIMEOUT

Timeout during dynamic reconfiguration.

enumerator CY_USBFS_DEV_DRV_EP_DMA_READ_TIMEOUT

Timeout during execution of the DMA read request for the OUT endpoint (only applicable in Manual DMA mode (Mode 2))

enumerator CY_USBFS_DEV_DRV_EP_DMA_WRITE_TIMEOUT

Timeout during execution of the DMA read request for the OUT endpoint (only applicable in Manual DMA mode (Mode 2))

enum cy_en_usbfs_dev_drv_ep_management_mode_t

cy_en_usbfs_dev_drv_ep_management_mode_t: Data Endpoints Buffer Management Mode.

Values:

enumerator CY_USBFS_DEV_DRV_EP_MANAGEMENT_CPU

CPU manages a data transfer between the hardware endpoints buffer and the user SRAM.

enumerator CY_USBFS_DEV_DRV_EP_MANAGEMENT_DMA

DMA manages data transfer between the hardware endpoints buffer and the user SRAM.

enumerator CY_USBFS_DEV_DRV_EP_MANAGEMENT_DMA_AUTO

The DMA automatically manages a data transfer between the hardware endpoints FIFO buffer and the user SRAM.

enum cy_en_usbfs_dev_ep_access_t

cy_en_usbfs_dev_ep_access_t: Data Endpoint Register Access Type.

Values:

enumerator CY_USBFS_DEV_DRV_USE_8_BITS_DR

Use 8-bits registers to access the data endpoints.

enumerator CY_USBFS_DEV_DRV_USE_16_BITS_DR

Use 16-bits registers to access the data endpoints.

enum cy_en_usb_dev_service_cb_t

cy_en_usb_dev_service_cb_t: Service Callback Events (this enumerated type is used by middleware)

Values:

enumerator CY_USB_DEV_BUS_RESET

Callback hooked to the bus reset interrupt.

enumerator CY_USB_DEV_EP0_SETUP

Callback hooked to the endpoint 0 SETUP packet interrupt.

enumerator CY_USB_DEV_EP0_IN

Callback hooked to the endpoint 0 IN packet interrupt.

enumerator CY_USB_DEV_EP0_OUT

Callback hooked to the endpoint 0 OUT packet interrupt.

enum cy_en_usbfs_dev_drv_cb_source_t

cy_en_usbfs_dev_drv_cb_source_t: Callback Sources.

Values:

enumerator CY_USBFS_DEV_DRV_EP1

Callback hooked to the Data Endpoint 1 completion interrupt.

enumerator CY_USBFS_DEV_DRV_EP2

Callback hooked to the Data Endpoint 2 completion interrupt.

enumerator CY_USBFS_DEV_DRV_EP3

Callback hooked to the Data Endpoint 3 completion interrupt.

enumerator CY_USBFS_DEV_DRV_EP4

Callback hooked to the Data Endpoint 4 completion interrupt.

enumerator CY_USBFS_DEV_DRV_EP5

Callback hooked to the Data Endpoint 5 completion interrupt.

enumerator CY_USBFS_DEV_DRV_EP6

Callback hooked to the Data Endpoint 6 completion interrupt.

enumerator CY_USBFS_DEV_DRV_EP7

Callback hooked to the Data Endpoint 7 completion interrupt.

enumerator CY_USBFS_DEV_DRV_EP8

Callback hooked to the Data Endpoint 8 completion interrupt.

enumerator CY_USBFS_DEV_DRV_SOF

Callback hooked to the SOF packet received interrupt.

enumerator CY_USBFS_DEV_DRV_LPM

Callback hooked to the LPM request received interrupt.

enum cy_en_usb_dev_ep_state_t

cy_en_usb_dev_ep_state_t: Data Endpoint States (this enumerated type is used by middleware)

Values:

enumerator CY_USB_DEV_EP_IDLE

The endpoint is in an idle state after the configuration is set.

enumerator CY_USB_DEV_EP_PENDING

The transfer targeted at an endpoint is in progress.

enumerator CY_USB_DEV_EP_COMPLETED

The transfer targeted at an endpoint is completed.

enumerator CY_USB_DEV_EP_STALLED

The endpoint is stalled.

enumerator CY_USB_DEV_EP_DISABLED

The endpoint is disabled (not used in this configuration)

enumerator CY_USB_DEV_EP_INVALID

The endpoint is not supported by the hardware.

enum cy_en_usbfs_dev_drv_force_bus_state_t

cy_en_usbfs_dev_drv_force_bus_state_t: USB Lines Control.

Values:

enumerator CY_USBFS_DEV_DRV_FORCE_STATE_J

Force a J State onto the USB lines.

enumerator CY_USBFS_DEV_DRV_FORCE_STATE_K

Force a K State onto the USB lines.

enumerator CY_USBFS_DEV_DRV_FORCE_STATE_SE0

Force a Single Ended 0 onto the USB lines.

enumerator CY_USBFS_DEV_DRV_FORCE_STATE_NONE

Return the bus to the SIE control.

enum cy_en_usbfs_dev_drv_lpm_req_t

cy_en_usbfs_dev_drv_lpm_req_t: LPM (Link Power Management) Responses.

Values:

enumerator CY_USBFS_DEV_DRV_LPM_REQ_NACK

The next LPM request will be responded with NACK.

enumerator CY_USBFS_DEV_DRV_LPM_REQ_ACK

The next LPM request will be responded with ACK.

enum cy_en_usbfs_dev_drv_ep0_ctrl_state_t

cy_en_usbfs_dev_drv_ep0_ctrl_state_t: USB Control EP0 transfer state.

Values:

enumerator CY_USBFS_DEV_DRV_EP0_CTRL_STATE_IDLE
enumerator CY_USBFS_DEV_DRV_EP0_CTRL_STATE_SETUP
enumerator CY_USBFS_DEV_DRV_EP0_CTRL_STATE_DATA
enumerator CY_USBFS_DEV_DRV_EP0_CTRL_STATE_STATUS_IN
enumerator CY_USBFS_DEV_DRV_EP0_CTRL_STATE_STATUS_OUT

Functions

cy_en_usbfs_dev_drv_status_t Cy_USBFS_Dev_Drv_Init(USBFS_Type *base, cy_stc_usbfs_dev_drv_config_t const *config, cy_stc_usbfs_dev_drv_context_t *context)

Initializes the USBFS in device mode.

If DMAs are used, initialize the DMAs.

Parameters
  • base – The pointer to the USBFS instance.

  • config – The pointer to the configuration structure cy_stc_usbfs_dev_drv_config_t.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

The status code of the function execution cy_en_usbfs_dev_drv_status_t.

void Cy_USBFS_Dev_Drv_DeInit(USBFS_Type *base, cy_stc_usbfs_dev_drv_context_t *context)

De-initializes the USBFS Device hardware (returns the register values to default) and removes all registered callbacks.

Parameters
  • base – The pointer to the USBFS instance.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

void Cy_USBFS_Dev_Drv_Enable(USBFS_Type *base, cy_stc_usbfs_dev_drv_context_t const *context)

Enables the USBFS Device operation.

Parameters
  • base – The pointer to the USBFS instance.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

void Cy_USBFS_Dev_Drv_Disable(USBFS_Type *base, cy_stc_usbfs_dev_drv_context_t *context)

Disables the USBFS Device operation.

If DMAs are used, disables the DMAs.

Parameters
  • base – The pointer to the USBFS instance.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

__STATIC_INLINE void Cy_USBFS_Dev_Drv_SetAddress (USBFS_Type *base, uint8_t address, cy_stc_usbfs_dev_drv_context_t *context)

Posts a request to set the device address after the completion status stage of the control transfer.

This function must be used if a higher level requests to set an address before the status stage of the control transfer.

Parameters
  • base – The pointer to the USBFS instance.

  • address – The device address.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

__STATIC_INLINE void Cy_USBFS_Dev_Drv_SetDeviceAddress (USBFS_Type *base, uint8_t address)

Sets the device address (writes the address directly into the register).

Parameters
  • base – The pointer to the USBFS instance.

  • address – Device address.

__STATIC_INLINE uint32_t Cy_USBFS_Dev_Drv_GetDeviceAddress (USBFS_Type const *base)

Returns the device address (reads the address directly from the register).

Parameters

base – The pointer to the USBFS instance.

Returns

The device address. The device address is assigned by the Host during device enumeration. Zero means that the device address is not assigned.

__STATIC_INLINE void Cy_USBFS_Dev_Drv_SetDevContext (USBFS_Type const *base, void *devContext, cy_stc_usbfs_dev_drv_context_t *context)

Stores a pointer to the USB Device context in the driver context.

note

This function is intended for the USB Device middleware operation.

Parameters
  • base – The pointer to the USBFS instance

  • devContext – The pointer to the USB Device context structure.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

__STATIC_INLINE void * Cy_USBFS_Dev_Drv_GetDevContext (USBFS_Type const *base, cy_stc_usbfs_dev_drv_context_t *context)

Returns a pointer to the USB Device context.

note

This function is intended for the USB Device middleware operation.

Parameters
  • base – The pointer to the USBFS instance.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

The pointer to the USB Device context.

void Cy_USBFS_Dev_Drv_ConfigDevice(USBFS_Type *base, cy_stc_usbfs_dev_drv_context_t *context)

Sets the basic device configuration (clears previous configuration).

Call this function after the endpoints were configured to complete the device configuration.

Parameters
  • base – The pointer to the USBFS instance.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

void Cy_USBFS_Dev_Drv_UnConfigureDevice(USBFS_Type *base, cy_stc_usbfs_dev_drv_context_t *context)

Clears device configuration.

Call this function before setting a configuration or a configuration failure to set the configuration into the default state. Alternately, call Cy_USBFS_Dev_Drv_RemoveEndpoint for each active endpoint.

Parameters
  • base – The pointer to the USBFS instance.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

void Cy_USBFS_Dev_Drv_Ep0GetSetup(USBFS_Type const *base, uint8_t *buffer, cy_stc_usbfs_dev_drv_context_t const *context)

Reads the setup packed from the Endpoint 0 hardware buffer.

Parameters
  • base – The pointer to the USBFS instance.

  • buffer – The pointer to the buffer for data read from the Endpoint 0.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

uint32_t Cy_USBFS_Dev_Drv_Ep0Write(USBFS_Type *base, uint8_t const *buffer, uint32_t size, cy_stc_usbfs_dev_drv_context_t *context)

Writes data into Endpoint 0 hardware buffer and returns how many bytes were written.

Parameters
  • base – The pointer to the USBFS instance.

  • buffer – The pointer to the buffer containing data bytes to write. To switch a transfer from the data stage to status, pass NULL as a pointer.

  • size – The number of bytes to write. Setting the size to zero sends to the bus zero-length data packet.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

The number of bytes that were written.

void Cy_USBFS_Dev_Drv_Ep0Read(USBFS_Type *base, uint8_t *buffer, uint32_t size, cy_stc_usbfs_dev_drv_context_t *context)

Start receiving a packet into the Endpoint 0 hardware buffer.

Parameters
  • base – The pointer to the USBFS instance.

  • buffer – The pointer to buffer that stores data that was read.

  • size – The number of bytes to read. Reading zero bytes switch control transfer to status stage.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

uint32_t Cy_USBFS_Dev_Drv_Ep0ReadResult(USBFS_Type const *base, cy_stc_usbfs_dev_drv_context_t *context)

Reads data from the Endpoint 0 hardware and returns the number of read bytes.

Parameters
  • base – The pointer to the USBFS instance.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

The number of read bytes.

__STATIC_INLINE void Cy_USBFS_Dev_Drv_Ep0Stall (USBFS_Type *base)

Stalls endpoint 0.

Parameters

base – The pointer to the USBFS instance.

__STATIC_INLINE uint32_t Cy_USBFS_Dev_Drv_GetEp0MaxPacket (USBFS_Type const *base)

Returns the endpoint 0 maximum packet size that can be for read or write from the endpoint 0 buffer.

Parameters

base – The pointer to the USBFS instance.

Returns

The endpoint 0 maximum packet size (endpoint 0 has a dedicated hardware buffer).

__STATIC_INLINE cy_en_usbfs_dev_drv_status_t Cy_USBFS_Dev_Drv_AddEndpoint (USBFS_Type *base, cy_stc_usb_dev_ep_config_t const *config, cy_stc_usbfs_dev_drv_context_t *context)

Configures a data endpoint for the following operation (allocates hardware resources for data endpoint).

Parameters
  • base – The pointer to the USBFS instance.

  • config – The pointer to data endpoint configuration cy_stc_usb_dev_ep_config_t.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

The status code of the function execution cy_en_usbfs_dev_drv_status_t.

cy_en_usbfs_dev_drv_status_t Cy_USBFS_Dev_Drv_RemoveEndpoint(USBFS_Type *base, uint32_t endpointAddr, cy_stc_usbfs_dev_drv_context_t *context)

Removes a data endpoint (release hardware resources allocated by data endpoint).

Parameters
  • base – The pointer to the USBFS instance.

  • endpointAddr – The data endpoint address (7 bit - direction, 3-0 bits - endpoint number).

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

Status code of the function execution cy_en_usbfs_dev_drv_status_t.

__STATIC_INLINE void Cy_USBFS_Dev_Drv_OverwriteMemcpy (USBFS_Type const *base, uint32_t endpoint, cy_fn_usbfs_dev_drv_memcpy_ptr_t memcpyFunc, cy_stc_usbfs_dev_drv_context_t *context)

Overwrites the memory copy (memcpy) function used to copy data with the user- implemented:

Parameters
  • base – The pointer to the USBFS instance.

  • endpoint – The data endpoint number.

  • memcpyFunc – The pointer to the function that copies data.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

__STATIC_INLINE cy_en_usb_dev_ep_state_t Cy_USBFS_Dev_Drv_GetEndpointState (USBFS_Type const *base, uint32_t endpoint, cy_stc_usbfs_dev_drv_context_t const *context)

Returns the state of the endpoint.

Parameters
  • base – The pointer to the USBFS instance.

  • endpoint – The data endpoint number.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

Data endpoint state cy_en_usb_dev_ep_state_t.

__STATIC_INLINE cy_en_usbfs_dev_drv_status_t Cy_USBFS_Dev_Drv_LoadInEndpoint (USBFS_Type *base, uint32_t endpoint, uint8_t const *buffer, uint32_t size, cy_stc_usbfs_dev_drv_context_t *context)

Loads data into the IN endpoint buffer.

After data loads, the endpoint is ready to be read by the host.

Parameters
  • base – The pointer to the USBFS instance.

  • endpoint – The IN data endpoint number.

  • buffer – The pointer to the buffer containing data bytes to load.

  • size – The number of bytes to load into the endpoint. This value must be less than or equal to endpoint maximum packet size.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

The status code of the function execution cy_en_usbfs_dev_drv_status_t.

void Cy_USBFS_Dev_Drv_EnableOutEndpoint(USBFS_Type *base, uint32_t endpoint, cy_stc_usbfs_dev_drv_context_t *context)

Enables the OUT data endpoint to be read by the Host.

note

The OUT endpoints are not enabled by default. The endpoints must be enabled before calling Cy_USBFS_Dev_Drv_ReadOutEndpoint to read data from an endpoint.

Parameters
  • base – The pointer to the USBFS instance.

  • endpoint – The OUT data endpoint number.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

Status code of the function execution cy_en_usbfs_dev_drv_status_t.

__STATIC_INLINE cy_en_usbfs_dev_drv_status_t Cy_USBFS_Dev_Drv_ReadOutEndpoint (USBFS_Type *base, uint32_t endpoint, uint8_t *buffer, uint32_t size, uint32_t *actSize, cy_stc_usbfs_dev_drv_context_t *context)

Reads data from the OUT endpoint buffer.

Before executing a next read, the Cy_USBFS_Dev_Drv_EnableOutEndpoint must be called to allow the Host to write data into the endpoint.

Parameters
  • base – The pointer to the USBFS instance.

  • endpoint – The OUT data endpoint number.

  • buffer – The pointer to the buffer that stores read data.

  • size – The number of bytes to read from the endpoint. This value must be less than or equal to the endpoint maximum packet size.

  • actSize – The number of actually read bytes.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

The status code of the function execution cy_en_usbfs_dev_drv_status_t.

cy_en_usbfs_dev_drv_status_t Cy_USBFS_Dev_Drv_Abort(USBFS_Type *base, uint32_t endpoint, cy_stc_usbfs_dev_drv_context_t *context)

Abort operation for data endpoint.

If there is any bus activity after the abort operation requested, the function waits for its completion or a timeout. A timeout is the time to transfer the bulk or an interrupt packet of the maximum playload size. If this bus activity is a transfer to the aborting endpoint, the received data is lost and the endpoint transfer completion callbacks are not invoked. After the function returns a new read or write, the endpoint operation can be submitted.

note

  • This abort operation is not supported for the ISOC endpoints because these endpoints do not have a handshake and are always accessible to the USB Host. Therefore, an abort can cause unexpected behavior.

  • The function uses the critical section to protect from the endpoint transfer complete interrupt.

Parameters
  • base – The pointer to the USBFS instance.

  • endpoint – The data endpoint number.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

Data endpoint state cy_en_usb_dev_ep_state_t after abort was applied.

__STATIC_INLINE bool Cy_USBFS_Dev_Drv_GetEndpointAckState (USBFS_Type const *base, uint32_t endpoint)

Returns whether the transaction completed with ACK for a certain endpoint.

Parameters
  • base – The pointer to the USBFS instance.

  • endpoint – The data endpoint number.

Returns

ACK state: true - transaction completed with ACK, false - otherwise.

__STATIC_INLINE uint32_t Cy_USBFS_Dev_Drv_GetEndpointCount (USBFS_Type const *base, uint32_t endpoint)

Returns the number of data bytes in the transaction for a certain endpoint.

Before calling this function, ensure the Host has written data into the endpoint. The returned value is updated after the Host access to the endpoint but remains unchanged after data has been read from the endpoint buffer. A typical use case is to read the number of bytes that the Host wrote into the OUT endpoint.

Parameters
  • base – The pointer to the USBFS instance.

  • endpoint – The data endpoint number.

Returns

The number of data bytes in the transaction.

cy_en_usbfs_dev_drv_status_t Cy_USBFS_Dev_Drv_StallEndpoint(USBFS_Type *base, uint32_t endpoint, cy_stc_usbfs_dev_drv_context_t *context)

Configures data endpoint to STALL any request intended for it.

Parameters
  • base – The pointer to the USBFS instance.

  • endpoint – The data endpoint number.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

Status code of the function execution cy_en_usbfs_dev_drv_status_t.

cy_en_usbfs_dev_drv_status_t Cy_USBFS_Dev_Drv_UnStallEndpoint(USBFS_Type *base, uint32_t endpoint, cy_stc_usbfs_dev_drv_context_t *context)

Release data endpoint STALL condition and clears data toggle bit.

The endpoint is returned to the same state as it was before STALL request.

Parameters
  • base – The pointer to the USBFS instance.

  • endpoint – The data endpoint number.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

Status code of the function execution cy_en_usbfs_dev_drv_status_t.

void Cy_USBFS_Dev_Drv_Interrupt(USBFS_Type *base, uint32_t intrCause, cy_stc_usbfs_dev_drv_context_t *context)

Processes interrupt events generated by the USBFS Device.

The interrupts are mandatory for USBFS Device operation and this function must be called inside the user-defined interrupt service routine.

Parameters
__STATIC_INLINE uint32_t Cy_USBFS_Dev_Drv_GetInterruptCauseHi (USBFS_Type const *base)

Returns the mask of bits showing the source of the current triggered interrupt.

This is useful for modes of operation where an interrupt can be generated by conditions in multiple interrupt source registers.

Parameters

base – The pointer to the USBFS instance.

Returns

The mask with the OR of the following conditions that have been triggered. See Interrupt Cause for the set of constants.

__STATIC_INLINE uint32_t Cy_USBFS_Dev_Drv_GetInterruptCauseMed (USBFS_Type const *base)

Returns the mask of bits showing the source of the current triggered interrupt.

This is useful for modes of operation where an interrupt can be generated by conditions in multiple interrupt source registers.

Parameters

base – The pointer to the USBFS instance.

Returns

The mask with the OR of the following conditions that have been triggered. See Interrupt Cause for the set of constants.

__STATIC_INLINE uint32_t Cy_USBFS_Dev_Drv_GetInterruptCauseLo (USBFS_Type const *base)

Returns the mask of bits showing the source of the current triggered interrupt.

This is useful for modes of operation where an interrupt can be generated by conditions in multiple interrupt source registers.

Parameters

base – The pointer to the USBFS instance.

Returns

The mask with the OR of the following conditions that have been triggered. See Interrupt Cause for the set of constants.

void Cy_USBFS_Dev_Drv_RegisterServiceCallback(USBFS_Type const *base, cy_en_usb_dev_service_cb_t source, cy_cb_usbfs_dev_drv_callback_t callback, cy_stc_usbfs_dev_drv_context_t *context)

Registers a callback function to notify about service events (Bus Reset or Endpoint 0 communication) in Cy_USBFS_Dev_Drv_Interrupt.

To remove callback function, pass NULL as function pointer.

Parameters
  • base – The pointer to the USBFS instance.

  • source – The event that involves the callback.

  • callback – The pointer to a callback function.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

The status code of the function execution cy_en_usbfs_dev_drv_status_t.

__STATIC_INLINE void Cy_USBFS_Dev_Drv_RegisterSofCallback (USBFS_Type *base, cy_cb_usbfs_dev_drv_callback_t callback, cy_stc_usbfs_dev_drv_context_t *context)

Registers a callback function to notify about an SOF event in Cy_USBFS_Dev_Drv_Interrupt.

The SOF interrupt source is enabled after registration. To remove callback function, pass NULL as the function pointer. When the callback is removed, the interrupt source is disabled.

note

To remove the callback, pass NULL as the pointer to a callback function.

Parameters
  • base – The pointer to the USBFS instance.

  • callback – The pointer to a callback function.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

__STATIC_INLINE void Cy_USBFS_Dev_Drv_RegisterLpmCallback (USBFS_Type *base, cy_cb_usbfs_dev_drv_callback_t callback, cy_stc_usbfs_dev_drv_context_t *context)

Registers a callback function to notify about an LPM event in Cy_USBFS_Dev_Drv_Interrupt.

The LPM interrupt source is enabled after registration. To remove the callback function, pass NULL as the function pointer. When the callback is removed, the interrupt source is disabled.

note

To remove the callback, pass NULL as the pointer to the callback function.

Parameters
  • base – The pointer to the USBFS instance.

  • callback – The pointer to a callback function.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

__STATIC_INLINE void Cy_USBFS_Dev_Drv_RegisterEndpointCallback (USBFS_Type const *base, uint32_t endpoint, cy_cb_usbfs_dev_drv_ep_callback_t callback, cy_stc_usbfs_dev_drv_context_t *context)

Registers a callback function to notify of an endpoint transfer completion event in Cy_USBFS_Dev_Drv_Interrupt.

  • IN endpoint - The Host read data from the endpoint and new data can be loaded.

  • OUT endpoint - The Host has written data into the endpoint and the data is ready to be read. To remove the callback function, pass NULL as function pointer.

note

To remove the callback, pass NULL as the pointer to the callback function.

Parameters
  • base – The pointer to the USBFS instance.

  • endpoint – The data endpoint number.

  • callback – The pointer to a callback function.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

__STATIC_INLINE void Cy_USBFS_Dev_Drv_SetInterruptsLevel (USBFS_Type *base, uint32_t intrLevel)

Writes INTR_LVL_SEL register which contains groups for all interrupt sources.

Parameters
  • base – The pointer to the USBFS instance.

  • intrLevel – INTR_LVL_SEL register value.

__STATIC_INLINE uint32_t Cy_USBFS_Dev_Drv_GetInterruptsLevel (USBFS_Type const *base)

Returns the INTR_LVL_SEL register that contains groups for all interrupt sources.

Parameters

base – The pointer to the USBFS instance.

Returns

Returns the INTR_LVL_SEL register that contains groups for all interrupt sources.

__STATIC_INLINE void Cy_USBFS_Dev_Drv_DisableEp0Interrupt (USBFS_Type *base)

Enables the Control Endpoint 0 interrupt source.

Parameters

base – The pointer to the USBFS instance.

__STATIC_INLINE void Cy_USBFS_Dev_Drv_EnableEp0Interrupt (USBFS_Type *base)

Enables the Control Endpoint 0 interrupt.

Parameters

base – The pointer to the USBFS instance source.

__STATIC_INLINE bool Cy_USBFS_Dev_Drv_CheckActivity (USBFS_Type *base)

Returns the activity status of the bus.

It clears the hardware status to provide an updated status on the next call of this function. This function is useful to determine whether there is any USB bus activity between function calls. A typical use case is to determine whether the USB suspend conditions are met.

Parameters

base – The pointer to the USBFS instance.

Returns

The bus activity since the last call.

__STATIC_INLINE void Cy_USBFS_Dev_Drv_Force (USBFS_Type *base, cy_en_usbfs_dev_drv_force_bus_state_t state)

Forces a USB J, K, or SE0 state on the USB lines.

A typical use case is to signal a Remote Wakeup condition on the USB bus.

Parameters
void Cy_USBFS_Dev_Drv_Suspend(USBFS_Type *base, cy_stc_usbfs_dev_drv_context_t *context)

Prepares the USBFS component to enter Deep Sleep mode.

note

After entering low-power mode, the data that is left in the IN or OUT endpoint buffers is not restored after a wakeup, and is lost. Therefore, it should be stored in the SRAM for OUT endpoint or read by the host for the IN endpoint before entering low-power mode.

Parameters
  • base – The pointer to the USBFS instance.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

void Cy_USBFS_Dev_Drv_Resume(USBFS_Type *base, cy_stc_usbfs_dev_drv_context_t *context)

Prepares the USBFS component for operation after exiting Deep Sleep mode.

Parameters
  • base – The pointer to the USBFS instance.

  • context – The pointer to the context structure cy_stc_usbfs_dev_drv_context_t allocated by the user. The structure is used during the USBFS Device operation for internal configuration and data retention. The user must not modify anything in this structure.

__STATIC_INLINE uint32_t Cy_USBFS_Dev_Drv_Lpm_GetBeslValue (USBFS_Type const *base)

Returns the Best Effort Service Latency (BESL) value sent by the host as part of the LPM token transaction.

Parameters

base – The pointer to the USBFS instance.

Returns

BESL value (4-bits)

__STATIC_INLINE bool Cy_USBFS_Dev_Drv_Lpm_RemoteWakeUpAllowed (USBFS_Type const *base)

Returns the remote wakeup permission set by the Host as part of the LPM token transaction.

Parameters

base – The pointer to the USBFS instance.

Returns

Remote wakeup permission: true - allowed, false - not allowed.

__STATIC_INLINE void Cy_USBFS_Dev_Drv_Lpm_SetResponse (USBFS_Type *base, cy_en_usbfs_dev_drv_lpm_req_t response)

Configures the response in the handshake packet that the device sends when an LPM token packet is received.

Parameters
  • base – The pointer to the USBFS instance.

  • response – The response to return for an LPM token packet. See cy_en_usbfs_dev_drv_lpm_req_t for the set of options.

__STATIC_INLINE cy_en_usbfs_dev_drv_lpm_req_t Cy_USBFS_Dev_Drv_Lpm_GetResponse (USBFS_Type const *base)

Returns the response value that the device sends as part of the handshake packet when an LPM token packet is received.

Parameters

base – The pointer to the USBFS instance.

Returns

The response to return for an LPM token packet. See cy_en_usbfs_dev_drv_lpm_req_t for the set of options.

struct cy_stc_usb_dev_ep_config_t
#include <>

Data Endpoint Configuration Structure.

Public Members

bool enableEndpoint

Defines if the endpoint becomes active after configuration.

bool allocBuffer

Defines if the endpoint needs buffer allocation.

uint16_t maxPacketSize

The endpoint max packet size.

uint16_t bufferSize

The endpoint buffer size (the biggest max packet size across all alternate for this endpoint)

uint8_t endpointAddr

The endpoint address (number plus direction bit)

uint8_t attributes

The endpoint attributes.

struct cy_stc_usbfs_dev_drv_dma_config_t
#include <>

DMA Channel Configuration Structure.

Public Members

DW_Type *base

Pointer to the DMA base.

uint32_t chNum

Channel number.

uint32_t priority

Channel’s priority.

bool preemptable

Specifies whether the channel is preempt-able by another higher-priority channel.

uint32_t outTrigMux

DMA out trigger mux (applicable only when mode is CY_USBFS_DEV_DRV_EP_MANAGEMENT_DMA_AUTO)

cy_stc_dma_descriptor_t *descr0

The pointer to the 1st allocated DMA descriptor (required for DMA operation)

cy_stc_dma_descriptor_t *descr1

The pointer to the 2nd allocated DMA descriptor (required when mode is CY_USBFS_DEV_DRV_EP_MANAGEMENT_DMA_AUTO)

struct cy_stc_usbfs_dev_drv_config_t
#include <>

Driver Configuration Structure.

Public Members

cy_en_usbfs_dev_drv_ep_management_mode_t mode

Endpoints management mode.

const cy_stc_usbfs_dev_drv_dma_config_t *dmaConfig[CY_USBFS_DEV_DRV_NUM_EPS_MAX]

DMA channels configuration for the endpoints.

Only DMChannels for active endpoints must be configured. Provide NULL pointer if endpoint is not used. Applicable when mode is CY_USBFS_DEV_DRV_EP_MANAGEMENT_DMA or CY_USBFS_DEV_DRV_EP_MANAGEMENT_DMA_AUTO.

uint8_t *epBuffer

The pointer to the buffer allocated for the OUT endpoints (applicable only when mode is CY_USBFS_DEV_DRV_EP_MANAGEMENT_DMA_AUTO)

uint16_t epBufferSize

The size of the buffer for the OUT endpoints (applicable only when mode is CY_USBFS_DEV_DRV_EP_MANAGEMENT_DMA_AUTO)

uint32_t intrLevelSel

The mask that assigns interrupt sources to trigger: Low, Medium, or High interrupt.

Use the macros provided in group_usbfs_dev_drv_macros_intr_level to initialize the intrLevelSel mask.

bool enableLpm

Enables LPM (Link Power Management) response.

cy_en_usbfs_dev_ep_access_t epAccess

Data endpoints access type.

struct cy_stc_usbfs_dev_drv_context_t
#include <>

USBFS Device context structure.

All fields for the context structure are internal. The firmware never reads or writes these values. The firmware allocates a structure and provides the address of the structure to the middleware in HID function calls. The firmware must ensure that the defined instance of this structure remains in scope while the middleware is in use.