USB Component  Version 6.0
MDK-Professional Middleware for USB Device and Host
 All Data Structures Functions Variables Enumerations Enumerator Groups Pages
Differences to RL-USB

The following table is an overview of the changes to the API functions of the USB Component compared to RL-USB, the Real-Time Library provided with MDK Version 4. The MDK-ARM Version 5 USB Component requires CMSIS-RTOS functionality. Events are no longer called by interrupt service routines which makes the timing of the overall system more predictable.

The API functions along with the differences are shown in the order:


RL-USB: MDK-ARM Version 4 with links to the RL-ARM online manual.
USB Component: MDK-ARM Version 5.

Description of the difference.


Note
  • The API function names have been modified to unify the namespace of Software Components.

Header File

Difference of the header file for API function definition of the USB Device and USB Host component.


rtl.h         // definitions for all RL-ARM middleware components
rl_usb.h      // definitions for USB Component

MDK Middleware Component now uses a header file for each of the components.


USB Device Functions

Differences of the USB Device API functions.


void       usbd_init                      (void)
usbStatus  USBD_Initialize                (int8_t device)
  • Return code changed to usbStatus.
  • Argument device represents index of USB Device controller.

did not exist
usbStatus  USBD_Uninitialize              (int8_t device)

In RL-USB it was impossible to stop an USB Device.


void       usbd_connect                   (BOOL con)
usbStatus  USBD_Connect                   (int8_t device)
  • Return code changed to usbStatus.
  • Argument con is removed and complementary function USBD_Disconnect is introduced.
  • Argument device represents index of USB Device controller.

did not exist
usbStatus  USBD_Disconnect                (int8_t device)
  • RL-USB used usbd_connect with con=0.
  • Argument device represents index of USB Device controller.

void       usbd_reset_core                (void)
removed 

Use instead the de-initialization function USBD_Uninitialize.


BOOL       usbd_configured                (void)
bool       USBD_Configured                (int8_t device)

Argument device represents index of USB Device controller.


void       usbd_hid_init                  (void)
void       USBD_HIDn_Initialize           (void)

Identical functionality.


did not exist
void       USBD_HIDn_Uninitialize         (void)

BOOL       usbd_hid_get_report_trigger    (                 U8      rid,         U8      *buf, int     len)
usbStatus  USBD_HID_GetReportTrigger      (int8_t instance, uint8_t rid,   const uint8_t *buf, int32_t len)

Return code changed to usbStatus.


int        usbd_hid_get_report            (U8      rtype, U8      rid, U8      *buf, U8       req)
int32_t    USBD_HIDn_GetReport            (uint8_t rtype, uint8_t req, uint8_t  rid, uint8_t *buf)

Identical functionality, but function parameter order was changed.


void       usbd_hid_set_report            (U8      rtype, U8      rid, U8      *buf,       int      len, U8      req)
BOOL       USBD_HIDn_SetReport            (uint8_t rtype, uint8_t req, uint8_t  rid, const uint8_t *buf, int32_t len)

Identical functionality, but function parameter order was changed.


U8         usbd_hid_get_protocol          (void)

removed


void       usbd_hid_set_protocol          (U8 protocol)

removed


void       usbd_msc_init                  (void)
void       USBD_MSCn_Initialize           (void)

Identical functionality.


did not exist
void       USBD_MSCn_Uninitialize         (void)

void       usbd_msc_read_sect             (U32      block, U8       *buf, U32      num_of_blocks)
bool       USBD_MSCn_Read                 (uint32_t   lba, uint16_t  cnt, uint8_t *buf)

Identical functionality, but function parameter names and order was changed.


void       usbd_msc_write_sect            (U32      block, U8       *buf,       U32      num_of_blocks)
bool       USBD_MSCn_Write                (uint32_t   lba, uint16_t  cnt, const uint8_t *buf)

Identical functionality, but function parameter names and order was changed.


void       usbd_msc_start_stop            (BOOL start)
removed 

void       usbd_adc_init                  (void)
void       USBD_ADCn_Initialize           (void)

Identical functionality.


did not exist
void       USBD_ADCn_Uninitialize         (void)

int32_t    USBD_CDC_ACM_PortInitialize    (void)
void       USBD_CDCn_ACM_Initialize       (void)

Return code change to void.


int32_t    USBD_CDC_ACM_PortUninitialize  (void)
void       USBD_CDCn_ACM_Uninitialize     (void)

Return code change to void.


int32_t    USBD_CDC_ACM_PortReset         (void)
void       USBD_CDCn_ACM_Reset            (void)

Return code change to void.


int32_t    USBD_CDC_ACM_PortSetLineCoding (CDC_LINE_CODING *line_coding)
bool       USBD_CDCn_ACM_SetLineCoding    (CDC_LINE_CODING *line_coding)

Return code change to bool.


int32_t    USBD_CDC_ACM_PortGetLineCoding (CDC_LINE_CODING *line_coding)
bool       USBD_CDCn_ACM_GetLineCoding    (CDC_LINE_CODING *line_coding)

Return code change to bool.


int32_t    USBD_CDC_ACM_PortSetControlLineState   (uint16_t ctrl_bmp)
bool       USBD_CDCn_ACM_SetControlLineState      (uint16_t state)

Return code change to bool.


int32_t    USBD_CDC_ACM_GetChar           (void)
int        USBD_CDC_ACM_GetChar           (int8_t instance)

Argument instance specifies the device instance of the CDC class.


int32_t    USBD_CDC_ACM_PutChar           (                 const uint8_t ch)
int        USBD_CDC_ACM_PutChar           (int8_t instance,       int     ch)

Argument instance specifies the device instance of the CDC class.


int32_t    USBD_CDC_ACM_DataRead          (                 uint8_t *buf, int32_t len)
int32_t    USBD_CDC_ACM_ReadData          (int8_t instance, uint8_t *buf, int32_t len)

Argument instance specifies the device instance of the CDC class.


int32_t    USBD_CDC_ACM_DataSend          (                 const uint8_t *buf, int32_t len)
int32_t    USBD_CDC_ACM_WriteData         (int8_t instance, const uint8_t *buf, int32_t len)

Argument instance specifies the device instance of the CDC class.


int32_t    USBD_CDC_ACM_DataAvailable     (void)
int32_t    USBD_CDC_ACM_DataAvailable     (int8_t instance)

Argument instance specifies the device instance of the CDC class.


int32_t    USBD_CDC_ACM_Notify            (                 uint16_t stat)
usbStatus  USBD_CDC_ACM_Notify            (int8_t instance, uint16_t state)
  • Return code changed to usbStatus.
  • Argument instance specifies the device instance of the CDC class.

did not exist
void       USBD_CDC_ACM_DataReceived      (int8_t instance, int32_t len)

did not exist
usbStatus  USBD_EndpointRead              (int8_t device, uint8_t ep_addr, uint8_t *buf, uint32_t len)

did not exist
uint32_t   USBD_EndpointReadGetResult     (int8_t device, const uint8_t ep_addr)

did not exist
usbStatus  USBD_EndpointWrite             (int8_t device, uint8_t ep_addr, const uint8_t *buf, uint32_t len)

did not exist
uint32_t   USBD_EndpointWriteGetResult    (int8_t device, const uint8_t ep_addr)

did not exist
int32_t    USBD_EndpointStall             (int8_t device, uint8_t ep_addr, bool stall)

did not exist
usbStatus  USBD_EndpointAbort             (int8_t device, uint8_t ep_addr)

USB Host Functions

Differences of the USB Host API functions.


BOOL       usbh_mem_init                  (U8      ctrl, U32      *ptr_pool, U32 pool_sz)
removed 

The memory is initialized with USBH_Initialize.


BOOL       usbh_mem_alloc                 (U8      ctrl, U8      **ptr, U32      sz)
usbStatus  USBH_MemoryAllocate            (uint8_t ctrl, uint8_t **ptr, uint32_t size)

Allocate a piece of memory from the memory pool.


BOOL       usbh_mem_free                  (U8      ctrl, U8      *ptr)
usbStatus  usbStatus USBH_MemoryFree      (uint8_t ctrl, uint8_t *ptr)

Release a piece of memory back to the memory pool.


BOOL       usbh_init                      (U8      ctrl)
usbStatus  USBH_Initialize                (uint8_t ctrl)

BOOL       usbh_init_all                  (void)
removed 

Replaced by USBH_Initialize.


BOOL       usbh_uninit                    (U8      ctrl)
usbStatus  USBH_Uninitialize              (uint8_t ctrl)

Return code changed to usbStatus.


did not exist
usbStatus  USBH_GetDeviceStatus           (int8_t instance)
  • Return code changed to usbStatus.
  • Get connection and operation status of the device.

BOOL       usbh_uninit_all                (void)
removed 

Replaced by USBH_Initialize.


BOOL       usbh_engine                    (U8     ctrl)
removed 

USB events are now schedule with CMSIS-RTOS threads. Threads are started with USBH_Initialize.


BOOL       usbh_engine_all                (void)
removed 

USB events are now schedule with CMSIS-RTOS threads. Threads are started with USBH_Initialize.


BOOL       usbh_transfer                  (U8 ctrl, USBH_EP *ptr_ep, USBH_URB *ptr_urb, U16 tout);
removed 

U32        usbh_get_last_error            (U8     ctrl)
removed 

There is no error codes retrieval. Instead refer to usbStatus for a function returning of error codes.


U8         usbh_get_error_string          (U32    err)
removed 

There is no string decoding for error codes. Instead refer to usbStatus for a verbal description of error codes.


BOOL       usbh_msc_status                (U8     ctrl,     U8   dev_idx)
usbStatus  USBH_MSC_GetDeviceStatus       (int8_t instance)
  • Return code changed to usbStatus.
  • Every device has an unique instance number that is the only argument for the new version of the routine.

BOOL       usbh_msc_read                  (U8     ctrl,     U8   dev_idx, U32  blk_adr, U8 *ptr_data, U16 blk_num)
usbStatus  USBH_MSC_Read                  (int8_t instance, uint32_t lba, uint16_t cnt, uint8_t *buf)
  • Return code changed to usbStatus.
  • Every device has an unique instance number, so that the number of the USB Host controller is not required any more.

BOOL       usbh_msc_write                 (U8     ctrl,     U8   dev_idx, U32  blk_adr,       U8 *ptr_data, U16 blk_num)
usbStatus  USBH_MSC_Write                 (int8_t instance, uint32_t lba, uint16_t cnt, const uint8_t *buf)
  • Return code changed to usbStatus.
  • Every device has an unique instance number, so that the number of the USB Host controller is not required any more.

did not exist
usbStatus  USBH_MSC_ReadCapacity          (int8_t instance, uint32_t *block_count, uint32_t *block_size)

BOOL       usbh_msc_read_config           (U8     ctrl,     U8   dev_idx, U32 *tot_blk_num, U32 *blk_sz)
removed 

U32        usbh_msc_get_last_error        (U8     ctrl,     U8   dev_idx)
removed 

BOOL       usbh_hid_status                (U8     ctrl,     U8   dev_idx)
usbStatus  USBH_HID_GetDeviceStatus       (int8_t instance)
  • Return code changed to usbStatus.
  • Argument ctrl (index of the USB Host Controller) removed.

int        usbh_hid_data_in               (U8     ctrl,     U8   dev_idx, U8      *ptr_data)
int32_t    USBH_HID_Read                  (int8_t instance, uint8_t *buf, int32_t len)

Argument ctrl (index of the USB Host Controller) removed.


int        usbh_hid_data_out              (U8     ctrl,           U8    dev_idx, U8 *ptr_data, U16 data_len)
int32_t    USBH_HID_Write                 (int8_t instance, const uint8_t *buf, int32_t len)
  • Argument ctrl (index of the USB Host Controller) removed.

U32        usbh_hid_get_last_error        (U8     ctrl,     U8       dev_idx)
removed 

void       usbh_hid_parse_report_desc     (U8     ctrl,     U8       dev_idx, U8      *ptrHIDReportDesc)
void       USBH_HID_ParseReportDescriptor (int8_t instance, uint8_t *ptr_hid_report_desc)

void       usbh_hid_data_in_callback      (U8     ctrl,     U8       dev_idx, U8  *ptr_data, U16 data_len)
void       USBH_HID_DataReceived          (int8_t instance, uint16_t len)

int        usbh_hid_kbd_getkey            (U8     ctrl,    U8        dev_idx)  
int        USBH_HID_GetKeyboardKey        (int8_t instance)

Argument ctrl (index of the USB Host Controller) removed.


BOOL       usbh_hid_mouse_getdata         (U8     ctrl,     U8       dev_idx, U8 *btn, S8 *x, S8 *y, S8 *wheel)
usbStatus  USBH_HID_GetMouseState         (int8_t instance, usbHID_MouseState *state)
  • Return code changed to usbStatus.
  • Argument ctrl (index of the USB Host Controller) removed.

USB Device Custom Class Functions

Device Custom Class function differences.

Note
The placeholder n in function names represents a number. (USBD_CustomClassn_ == USBD_CustomClass0_, USBD_Customclass1_, ...)

BOOL       usbd_cls_ep_req                (BOOL setup)
removed 

BOOL       usbd_cls_dev_req               (BOOL setup)
removed 

BOOL       usbd_cls_if_req                (BOOL setup)
removed 

void       usbd_cls_sof                   (void)
removed 

void       usbd_cls_init                  (void)
void       USBD_CustomClassn_Initialize   (void)

Function name changed.


did not exist
void       USBD_CustomClassn_Uninitialize (void)

did not exist
void       USBD_CustomClassn_Endpoint(n)_Event (uint32_t event)
Note
(n) represents a number from 1..15

did not exist
void      USBD_CustomClassn_EventReset         (void)

did not exist
void      USBD_CustomClassn_EventEndpointStart (uint8_t ep_addr)

did not exist
void      USBD_CustomClassn_EventEndpointStop  (uint8_t ep_addr)

did not exist
usbdRequestStatus USBD_CustomClassn_Endpoint0_SetupPacketReceived (const USB_SETUP_PACKET *setup_packet, uint8_t **buf, int32_t *len)

did not exist
void      USBD_CustomClassn_Endpoint0_SetupPacketProcessed        (const USB_SETUP_PACKET *setup_packet)

did not exist
usbdRequestStatus USBD_CustomClassn_Endpoint0_OutDataReceived     (int32_t len)

did not exist
usbdRequestStatus USBD_CustomClassn_Endpoint0_InDataSent          (int32_t len)

Internal USB Functions

Difference of internal USB Library functions.

Note
The internal functions are not intended to be called by the user application and are here listed for completeness.

BOOL       USBH_Send_Setup                (U8      ctrl, U8 *ptr_data)
usbStatus  USBH_SendSetup                 (uint8_t ctrl, USBH_EP *ptr_ep, uint8_t *data)

BOOL       USBH_Send_Data                 (U8      ctrl, U8 *ptr_data, U16 data_len)
usbStatus  USBH_SendData                  (uint8_t ctrl, USBH_EP *ptr_ep, uint8_t *data, uint32_t num)

BOOL       USBH_Rece_Data                 (U8      ctrl, U8 *ptr_data, U16 data_len)
usbStatus  USBH_ReceiveData               (uint8_t ctrl, USBH_EP *ptr_ep, uint8_t *data, uint32_t num)

did not exist
usbStatus  USBH_AbortData                 (uint8_t ctrl, USBH_EP *ptr_ep)

BOOL       USBH_GetStatus                 (U8      ctrl, U8 rcpnt, U8 idx, U8 *stat_dat)
usbStatus  USBH_GetStatus                 (uint8_t ctrl, uint8_t recipient, uint8_t index, uint8_t *ptr_stat_dat)

BOOL       USBH_ClearFeature              (U8      ctrl, U8 rcpnt, U8 idx, U8 feat_sel)
usbStatus  USBH_ClearFeature              (uint8_t ctrl, uint8_t recipient, uint8_t index, uint8_t feature_selector)

BOOL       USBH_SetFeature                (U8      ctrl, U8 rcpnt, U8 idx, U8 feat_sel)
usbStatus  USBH_SetFeature                (uint8_t ctrl, uint8_t recipient, uint8_t index, uint8_t feature_selector)

BOOL       USBH_SetAddress                (U8      ctrl, U8 dev_adr)
usbStatus  USBH_SetAddress                (uint8_t ctrl, uint8_t device_address)

BOOL       USBH_GetDescriptor             (U8      ctrl, U8 rcpnt, U8 desc_typ, U8 desc_idx, U8 lang_id, U8 *desc_dat, U16 desc_len)
usbStatus  USBH_GetDescriptor             (uint8_t ctrl, uint8_t recipient, uint8_t descriptor_type, uint8_t descriptor_index, uint8_t language_id, uint8_t *descriptor_data, uint16_t descriptor_length)

BOOL       USBH_SetDescriptor             (U8      ctrl, U8 rcpnt, U8 desc_typ, U8 desc_idx, U8 lang_id, U8 *desc_dat, U16 desc_len)
usbStatus  USBH_SetDescriptor             (uint8_t ctrl, uint8_t recipient, uint8_t descriptor_type, uint8_t descriptor_index, uint8_t language_id, uint8_t *descriptor_data, uint16_t descriptor_length)

BOOL       USBH_GetConfiguration          (U8      ctrl, U8 *cfg_dat)
usbStatus  USBH_GetConfiguration          (uint8_t ctrl, uint8_t *ptr_configuration)

BOOL       USBH_SetConfiguration          (U8      ctrl, U8 cfg_val)
usbStatus  USBH_SetConfiguration          (uint8_t ctrl, uint8_t configuration)

BOOL       USBH_GetInterface              (U8      ctrl, U8 idx, U8 *alt_dat)
usbStatus  USBH_GetInterface              (uint8_t ctrl, uint8_t index, uint8_t *ptr_alternate)

BOOL       USBH_SetInterface              (U8      ctrl, U8 idx, U8 alt_set)
usbStatus  USBH_SetInterface              (uint8_t ctrl, uint8_t index, uint8_t alternate)

BOOL       USBH_SyncFrame                 (U8      ctrl, U8 idx, U8 *frm_num)
usbStatus  USBH_SyncFrame                 (uint8_t ctrl, uint8_t index, uint8_t *ptr_frame_number)

did not exist
usbStatus  USBH_RecoverDevice             (USBH_DEV *ptr_dev)

Used to recover mass storage device if operation fails.