4.2 Internal APIs

The following definitions are for advanced USB users who intend to develop a specific USB device not provided in ASF.

Figure 4-3. Internal USB Device API Overview
Table 4-3. UDI Input from UDC (1)
DeclarationDescription
bool (*enable)()Called by UDC to enable/disable a USB interface
void (*disable)()
bool (*setup)()Called when a USB setup interface request is received
uint8_t (*getsetting)()Called by UDC to obtain the current alternate setting of a USB interface
uint8_t (*sof_notify)()Called by UDC to notify a SOF event at USB interface enabled
Note: The UDI API is linked with the UDC module via the UDC descriptor configuration file.
Table 4-4. UDC Input from UDI (2)
DeclarationDescription
usb_iface_desc_t* udc_getiface()Gives the USB interface descriptor selected by UDC when UDI is called (Table 4-3)
Table 4-5. UDC Input from UDD (3)
DeclarationDescription
void udc_reset()Called when Reset bus state occurs
bool udc_process_setup()Called when a setup packet is received
Table 4-6. UDD Input (4)
DeclarationCallerDescription
void udd_enable()UDCEnables/disables the USB Device mode
void udd_disable()UDC
void udd_attach()

void udd_dettach()

UDCInserts or removes pull-up on USB line
void udd_set_address(uint8_t add)UDCChanges/returns the USB device address
uint8_t udd_getaddress()UDC
bool udd_is_high_speed()UDC/UDIIn case of USB HS device, then checks speed chosen during enumeration
uint16_t udd_get_frame_number()APPReturns the current start of frame number
udd_send_wake_up()APPThe USB driver sends a resume signal called “Upstream Resume”
bool udd_ep_alloc(usb_ep_id_t ep, uint8_t bmAttributes, uint16_t wMaxPacketSize)UDCEnables/disables endpoints
udd_ep_free(usb_ep_id_t)UDC
bool udd_ep_clear_halt(usb_ep_id_t)UDC/UDIClears/sets/gets the endpoint state (halted or not)
bool udd_ep_set_halt(usb_ep_id_t)
bool udd_ep_is_halted(usb_ep_id_t)
bool udd_ep_wait_stall_clear( udd_ep_id_t endp, udd_callback_nohalt_t callback)Registers a callback to call when endpoint halt is removed
bool udd_ep_run( usb_ep_id_t endp, bool b_shortpacket, uint8_t *buf, uint32_t u32_size_buf, udd_callback_trans_t callback)UDIStarts/stops a data transfer in or out on an endpoint 
Note:
The control endpoint is not authorized here
udd_ep_abort(usb_ep_id_t endp)UDI
Table 4-7. UDD Callback (5)
DeclarationDescription
typedef void (*udd_callback_nohalt_t) (void);Called when the halt on endpoint is removed.
This one is registered via

udd_ep_wait_stall_clear().

typedef void (*udd_callback_trans_t) (udd_ep_status_t status, iram_size_t nb_transfered)Called when a transfer request is finished or canceled.
 This one is registered via udcdrv_ep_run().
Table 4-8. UDD Input for High Speed Application Only (4)
DeclarationCallerDescription
uint16_t udd_get_microframe_number()APPReturns the current micro start of frame number
udd_test_mode_j()UDCFeatures to test the USB HS device. These are requested to run a USB certification.
udd_test_mode_k()UDC
udd_test_mode_se0_nak()UDC
udd_test_mode_packet ()UDC

The global variable udd_g_ctrlreq is declared by UDD and contains two parts:

  • Values updated by UDD and used by UDC and UDIs (Table 4-9)
  • Values updated by UDC and UDIs and used by UDD (Table 4-10)

Outside the UDD, this variable is processed by udc_process_setup() for UDC and *setup() for UDI.

Table 4-9. udd_g_ctrlreq Field Updated by UDD
DeclarationDescription
usb_setup_req_t reqValues included in SETUP packet and used to decode request.
uint8_t *payloadThe content of the buffer is sent or filled by UDD.

Can be NULL if u16_size is equal to 0.

Table 4-10. udd_g_ctrlreq Updated by UDC or UDI
DeclarationDescription
uint8_t *payloadPointer value of the buffer to send or fill
uint16_t u16_sizeBuffer size to send or fill
It can be 0 when no DATA phase is needed
bool over_under_run(void)Called by UDD when the buffer given (.payload) is full or empty. Can be NULL
void *callback(void)Called by UDD when the setup request is finished (setup+data+ZLP). Can be NULL