USB Component  Version 6.3
MDK-Professional Middleware for USB Device and Host
 All Data Structures Functions Variables Enumerations Enumerator Groups Pages
rl_usb.h
1 /*------------------------------------------------------------------------------
2  * MDK Middleware - Component ::USB
3  * Copyright (c) 2004-2015 ARM Germany GmbH. All rights reserved.
4  *------------------------------------------------------------------------------
5  * Name: rl_usb.h
6  * Purpose: USB User API
7  * Rev.: V6.3
8  *----------------------------------------------------------------------------*/
9 
10 #ifndef __RL_USB_H__
11 #define __RL_USB_H__
12 
13 
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17 
18 #include <stdint.h>
19 #include <stdbool.h>
20 #include "cmsis_os.h"
21 #include "usb_def.h"
22 #include "usb_cdc.h"
23 #include "usb_hid.h"
24 #include "usb_msc.h"
25 
26 
27 // ==== USB Constants and Defines ====
28 
30 typedef enum {
31  usbOK = 0,
32 
33  usbTimeout,
34  usbInvalidParameter,
35 
36  usbThreadError = 0x10,
37  usbTimerError,
38  usbSemaphoreError,
39 
40  usbControllerError = 0x20,
41  usbDeviceError,
42  usbDriverError,
43  usbDriverBusy,
44  usbMemoryError,
45  usbNotConfigured,
46  usbClassErrorADC,
47  usbClassErrorCDC,
48  usbClassErrorHID,
49  usbClassErrorMSC,
50  usbClassErrorCustom,
51  usbUnsupportedClass,
52 
53  usbTransferStall = 0x40,
54 
55  usbUnknownError = 0xFF
56 } usbStatus;
57 
59 #ifdef __BIG_ENDIAN
60  #define U32_LE(v) (uint32_t)(__rev(v))
61  #define U16_LE(v) (uint16_t)(__rev(v) >> 16)
62  #define U32_BE(v) (uint32_t)(v)
63  #define U16_BE(v) (uint16_t)(v)
64 #else
65  #define U32_BE(v) (uint32_t)(__rev(v))
66  #define U16_BE(v) (uint16_t)(__rev(v) >> 16)
67  #define U32_LE(v) (uint32_t)(v)
68  #define U16_LE(v) (uint16_t)(v)
69 #endif
70 
71 // ==== USB Device Constants and Defines ====
72 
74 typedef enum {
75  usbdRequestNotProcessed = 0,
76  usbdRequestOK,
77  usbdRequestStall,
78  usbdRequestNAK
79 } usbdRequestStatus;
80 
82 #define USBD_MSC_MEDIA_READY (1U)
83 #define USBD_MSC_MEDIA_PROTECTED (1U<<1)
84 
85 
86 typedef enum {
87  USBD_HID_REQ_EP_CTRL = 0,
88  USBD_HID_REQ_EP_INT,
89  USBD_HID_REQ_PERIOD_UPDATE
90 } USBD_HID_REQ_t;
91 
93 typedef struct _usbd_msc_data_t {
94  MSC_CBW cbw;
95  MSC_CSW csw;
96  uint32_t block;
97  uint32_t offset;
98  uint32_t length;
99  bool mem_ok;
100  uint8_t bulk_stage;
101  uint32_t bulk_len;
102  uint32_t bulk_req_len;
103  bool media_ready;
104  uint32_t memory_size;
105  uint32_t block_size;
106  uint32_t block_group;
107  uint32_t block_count;
108  uint8_t *block_buf;
109  uint8_t request_sense;
110 } usbd_msc_data_t;
111 
114 typedef struct _usbd_msc_t {
115  uint8_t *bulk_buf;
116  usbd_msc_data_t *data_ptr;
117  uint8_t dev_num;
118  uint8_t if_num;
119  uint8_t ep_bulk_in;
120  uint8_t ep_bulk_out;
121  uint32_t bulk_buf_sz;
122  uint16_t max_packet_size[2];
123  uint8_t *inquiry_data;
124 } const usbd_msc_t;
126 
127 // ==== USB Host Constants and Defines ====
128 
131 typedef struct {
132  uint32_t hw_handle;
133  uint8_t dev_addr;
134  uint8_t dev_speed;
135  uint8_t hub_addr;
136  uint8_t hub_port;
137  uint8_t bEndpointAddress;
138  uint8_t bmAttributes;
139  uint16_t wMaxPacketSize;
140  uint8_t bInterval;
141  uint32_t transferred;
142  uint8_t active;
143 } USBH_PIPE;
145 
148 typedef struct {
149  uint8_t ctrl;
150  uint8_t dev_addr;
151  uint8_t dev_speed;
152  uint8_t hub_addr;
153  uint8_t hub_port;
154  struct {
155  uint8_t configured : 1;
156  uint8_t initialized : 1;
157  } state;
158  uint8_t max_packet_size;
159  uint8_t vid;
160  uint8_t pid;
161 
162  uint8_t class_custom;
163  uint8_t class_instance;
164  uint8_t class_driver;
165  uint8_t dev_desc_len;
166  uint8_t cfg_desc_len;
167  osThreadId recovery_thread_id;
168 } USBH_DEV;
170 
171 
172 // ==== USB Host externally defined variables ====
173 
176 extern const uint8_t usbh_cls_num;
178 
179 
180 // ==== USB Device Functions ====
181 
182 
186 extern usbStatus USBD_Initialize (uint8_t device);
187 
191 extern usbStatus USBD_Uninitialize (uint8_t device);
192 
196 extern usbStatus USBD_Connect (uint8_t device);
197 
201 extern usbStatus USBD_Disconnect (uint8_t device);
202 
207 extern bool USBD_Configured (uint8_t device);
208 
209 
210 // ==== USB Device Audio Device Functions ====
211 
212 #ifdef __DOXYGEN__
213 
214 // following functions are available for each instance of a ADC class.
215 // generic prefix USBD_ADCn is USBD_ADC0 for ADC class instance 0.
216 
219 void USBD_ADCn_Initialize (void);
220 
223 void USBD_ADCn_Uninitialize (void);
224 
228 void USBD_ADCn_SpeakerStatusEvent (bool active);
229 
237 void USBD_ADCn_SpeakerMuteEvent (uint8_t ch, bool cur);
238 
246 void USBD_ADCn_SpeakerVolumeEvent (uint8_t ch, uint16_t cur);
247 
251 void USBD_ADCn_MicrophoneStatusEvent (bool active);
252 
260 void USBD_ADCn_MicrophoneMuteEvent (uint8_t ch, bool cur);
261 
269 void USBD_ADCn_MicrophoneVolumeEvent (uint8_t ch, uint16_t cur);
270 
271 #endif // __DOXYGEN
272 
284 extern usbStatus USBD_ADC_SpeakerSetVolumeRange (uint8_t instance, uint8_t ch, uint16_t min, uint16_t max, uint16_t res, uint16_t cur);
285 
297 extern usbStatus USBD_ADC_MicrophoneSetVolumeRange (uint8_t instance, uint8_t ch, uint16_t min, uint16_t max, uint16_t res, uint16_t cur);
298 
302 extern uint32_t USBD_ADC_ReceivedSamplesAvailable (uint8_t instance);
303 
307 extern uint32_t USBD_ADC_WrittenSamplesPending (uint8_t instance);
308 
316 extern int32_t USBD_ADC_ReadSamples (uint8_t instance, void *buf, int32_t num);
317 
325 extern int32_t USBD_ADC_WriteSamples (uint8_t instance, const void *buf, int32_t num);
326 
327 
328 // ==== USB Device Communication Device (Abstract Control Model) Functions ====
329 
330 #ifdef __DOXYGEN__
331 
332 // following functions are available for each instance of a CDC class.
333 // generic prefix USBD_CDCn is USBD_CDC0 for CDC class instance 0.
334 
337 void USBD_CDCn_ACM_Initialize (void);
338 
341 void USBD_CDCn_ACM_Uninitialize (void);
342 
345 void USBD_CDCn_ACM_Reset (void);
346 
351 bool USBD_CDCn_ACM_SetLineCoding (CDC_LINE_CODING *line_coding);
352 
357 bool USBD_CDCn_ACM_GetLineCoding (CDC_LINE_CODING *line_coding);
358 
365 bool USBD_CDCn_ACM_SetControlLineState (uint16_t state);
366 
370 void USBD_CDCn_ACM_DataReceived (uint32_t len);
371 
374 void USBD_CDCn_ACM_DataSent (void);
375 
376 #endif // __DOXYGEN
377 
383 extern int USBD_CDC_ACM_GetChar (uint8_t instance);
384 
391 extern int USBD_CDC_ACM_PutChar (uint8_t instance, int ch);
392 
400 extern int32_t USBD_CDC_ACM_ReadData (uint8_t instance, uint8_t *buf, int32_t len);
401 
409 extern int32_t USBD_CDC_ACM_WriteData (uint8_t instance, const uint8_t *buf, int32_t len);
410 
415 extern int32_t USBD_CDC_ACM_DataAvailable (uint8_t instance);
416 
428 extern usbStatus USBD_CDC_ACM_Notify (uint8_t instance, uint16_t state);
429 
430 
431 // ==== USB Device Human Interface Device Functions ====
432 
433 #ifdef __DOXYGEN__
434 
435 // following functions are available for each instance of a HID class.
436 // generic prefix USBD_HIDn is USBD_HID0 for HID class instance 0.
437 
440 void USBD_HIDn_Initialize (void);
441 
444 void USBD_HIDn_Uninitialize (void);
445 
459 int32_t USBD_HIDn_GetReport (uint8_t rtype, uint8_t req, uint8_t rid, uint8_t *buf);
460 
473 bool USBD_HIDn_SetReport (uint8_t rtype, uint8_t req, uint8_t rid, const uint8_t *buf, int32_t len);
474 
475 #endif // __DOXYGEN
476 
483 extern usbStatus USBD_HID_GetReportTrigger (uint8_t instance, uint8_t rid, const uint8_t *buf, int32_t len);
484 
485 
486 #ifdef __DOXYGEN__
487 
488 // ==== USB Device Mass Storage Device Functions ====
489 
490 // following functions are available for each instance of a MSC class.
491 // generic prefix USBD_MSCn is USBD_MSC0 for MSC class instance 0.
492 
495 void USBD_MSCn_Initialize (void);
496 
499 void USBD_MSCn_Uninitialize (void);
500 
506 bool USBD_MSCn_GetCacheInfo (uint32_t *buffer, uint32_t *size);
507 
513 bool USBD_MSCn_GetMediaCapacity (uint32_t *block_count, uint32_t *block_size);
514 
521 bool USBD_MSCn_Read (uint32_t lba, uint32_t cnt, uint8_t *buf);
522 
529 bool USBD_MSCn_Write (uint32_t lba, uint32_t cnt, const uint8_t *buf);
530 
539 uint32_t USBD_MSCn_CheckMedia (void);
540 
541 #endif // __DOXYGEN
542 
543 
544 // ==== USB Device Custom Class Functions ====
545 
546 #ifdef __DOXYGEN__
547 
548 // following functions are available for each instance of a Custom class.
549 // generic prefix USBD_CustomClassn is USBD_CustomClassn for Custom class instance 0.
550 
553 void USBD_CustomClassn_Initialize (void);
554 
557 void USBD_CustomClassn_Uninitialize (void);
558 
561 void USBD_CustomClassn_EventReset (void);
562 
568 void USBD_CustomClassn_EventEndpointStart (uint8_t ep_addr);
569 
575 void USBD_CustomClassn_EventEndpointStop (uint8_t ep_addr);
576 
585 usbdRequestStatus USBD_CustomClassn_Endpoint0_SetupPacketReceived (const USB_SETUP_PACKET *setup_packet, uint8_t **buf, uint32_t *len);
586 
590 void USBD_CustomClassn_Endpoint0_SetupPacketProcessed (const USB_SETUP_PACKET *setup_packet);
591 
599 usbdRequestStatus USBD_CustomClassn_Endpoint0_OutDataReceived (uint32_t len);
600 
608 usbdRequestStatus USBD_CustomClassn_Endpoint0_InDataSent (uint32_t len);
609 
614 void USBD_CustomClassn_Endpoint1_Event (uint32_t event);
615 void USBD_CustomClassn_Endpoint2_Event (uint32_t event);
616 void USBD_CustomClassn_Endpoint3_Event (uint32_t event);
617 void USBD_CustomClassn_Endpoint4_Event (uint32_t event);
618 void USBD_CustomClassn_Endpoint5_Event (uint32_t event);
619 void USBD_CustomClassn_Endpoint6_Event (uint32_t event);
620 void USBD_CustomClassn_Endpoint7_Event (uint32_t event);
621 void USBD_CustomClassn_Endpoint8_Event (uint32_t event);
622 void USBD_CustomClassn_Endpoint9_Event (uint32_t event);
623 void USBD_CustomClassn_Endpoint10_Event (uint32_t event);
624 void USBD_CustomClassn_Endpoint11_Event (uint32_t event);
625 void USBD_CustomClassn_Endpoint12_Event (uint32_t event);
626 void USBD_CustomClassn_Endpoint13_Event (uint32_t event);
627 void USBD_CustomClassn_Endpoint14_Event (uint32_t event);
628 void USBD_CustomClassn_Endpoint15_Event (uint32_t event);
629 
630 #endif // __DOXYGEN
631 
640 extern usbStatus USBD_EndpointRead (uint8_t device, uint8_t ep_addr, uint8_t *buf, uint32_t len);
641 
648 extern uint32_t USBD_EndpointReadGetResult (uint8_t device, uint8_t ep_addr);
649 
658 extern usbStatus USBD_EndpointWrite (uint8_t device, uint8_t ep_addr, const uint8_t *buf, uint32_t len);
659 
666 extern uint32_t USBD_EndpointWriteGetResult (uint8_t device, uint8_t ep_addr);
667 
675 extern usbStatus USBD_EndpointStall (uint8_t device, uint8_t ep_addr, bool stall);
676 
683 extern usbStatus USBD_EndpointAbort (uint8_t device, uint8_t ep_addr);
684 
685 
686 // ==== USB Host Functions ====
687 
691 extern usbStatus USBH_Initialize (uint8_t ctrl);
692 
696 extern usbStatus USBH_Uninitialize (uint8_t ctrl);
697 
701 extern usbStatus USBH_GetDeviceStatus (uint8_t device);
702 
703 
704 // ==== USB Host Mass Storage Functions ====
705 
709 extern usbStatus USBH_MSC_GetDeviceStatus (uint8_t instance);
710 
717 extern usbStatus USBH_MSC_Read (uint8_t instance, uint32_t lba, uint32_t cnt, uint8_t *buf);
718 
725 extern usbStatus USBH_MSC_Write (uint8_t instance, uint32_t lba, uint32_t cnt, const uint8_t *buf);
726 
732 extern usbStatus USBH_MSC_ReadCapacity (uint8_t instance, uint32_t *block_count, uint32_t *block_size);
733 
734 
735 // ==== USB Host Human Interface Device Functions ====
736 
740 extern usbStatus USBH_HID_GetDeviceStatus (uint8_t instance);
741 
749 extern int32_t USBH_HID_Read (uint8_t instance, uint8_t *buf, int32_t len);
750 
758 extern int32_t USBH_HID_Write (uint8_t instance, const uint8_t *buf, int32_t len);
759 
765 extern int USBH_HID_GetKeyboardKey (uint8_t instance);
766 
768 typedef struct _usbHID_MouseState {
769  uint8_t button;
770  int16_t x;
771  int16_t y;
772 } usbHID_MouseState;
773 
778 extern usbStatus USBH_HID_GetMouseState (uint8_t instance, usbHID_MouseState *state);
779 
784 extern void USBH_HID_ParseReportDescriptor (uint8_t instance, uint8_t *ptr_hid_report_desc);
785 
790 extern void USBH_HID_DataReceived (uint8_t instance, uint32_t len);
791 
792 
793 // ==== USB Host Communication Device Class (Abstract Control Model) Functions ====
794 
798 extern usbStatus USBH_CDC_ACM_GetDeviceStatus (uint8_t instance);
799 
805 extern usbStatus USBH_CDC_ACM_Send (uint8_t instance, const uint8_t *data, uint32_t num);
806 
810 extern uint32_t USBH_CDC_ACM_GetTxCount (uint8_t instance);
811 
817 extern usbStatus USBH_CDC_ACM_Receive (uint8_t instance, uint8_t *data, uint32_t num);
818 
822 extern uint32_t USBH_CDC_ACM_GetRxCount (uint8_t instance);
823 
828 extern usbStatus USBH_CDC_ACM_SetLineCoding (uint8_t instance, CDC_LINE_CODING *line_coding);
829 
834 extern usbStatus USBH_CDC_ACM_GetLineCoding (uint8_t instance, CDC_LINE_CODING *line_coding);
835 
842 extern usbStatus USBH_CDC_ACM_SetControlLineState (uint8_t instance, uint16_t state);
843 
856 extern void USBH_CDC_ACM_Notify (uint8_t instance, uint16_t status);
857 
864 extern usbStatus USBH_CDC_ACM_SendBreak (uint8_t instance, uint16_t duration);
865 
866 
867 // ==== USB Host Custom Class Functions ====
868 
872 extern usbStatus USBH_CustomClass_GetDeviceStatus (uint8_t instance);
873 
881 extern uint8_t USBH_CustomClass_Configure (const USBH_DEV *ptr_dev, const USB_DEVICE_DESCRIPTOR *ptr_dev_desc, const USB_CONFIGURATION_DESCRIPTOR *ptr_cfg_desc);
882 
887 extern usbStatus USBH_CustomClass_Unconfigure (uint8_t instance);
888 
893 extern usbStatus USBH_CustomClass_Initialize (uint8_t instance);
894 
899 extern usbStatus USBH_CustomClass_Uninitialize (uint8_t instance);
900 
916 extern USBH_PIPE *USBH_PipeCreate (uint8_t ctrl, uint8_t dev_addr, uint8_t dev_speed, uint8_t hub_addr, uint8_t hub_port, uint8_t ep_addr, uint8_t ep_type, uint16_t ep_max_packet_size, uint8_t ep_interval);
917 
927 extern usbStatus USBH_PipeModify (uint8_t ctrl, USBH_PIPE *ptr_pipe, uint8_t dev_addr, uint8_t dev_speed, uint8_t hub_addr, uint8_t hub_port, uint16_t ep_max_packet_size);
928 
933 extern usbStatus USBH_PipeDelete (uint8_t ctrl, USBH_PIPE *ptr_pipe);
934 
939 extern usbStatus USBH_PipeReset (uint8_t ctrl, USBH_PIPE *ptr_pipe);
940 
947 extern usbStatus USBH_PipeReceive (uint8_t ctrl, USBH_PIPE *ptr_pipe, uint8_t *buf, uint32_t len);
948 
953 extern uint32_t USBH_PipeReceiveGetResult (uint8_t ctrl, const USBH_PIPE *ptr_pipe);
954 
961 extern usbStatus USBH_PipeSend (uint8_t ctrl, USBH_PIPE *ptr_pipe, const uint8_t *buf, uint32_t len);
962 
967 extern uint32_t USBH_PipeSendGetResult (uint8_t ctrl, const USBH_PIPE *ptr_pipe);
968 
973 extern usbStatus USBH_PipeAbort (uint8_t ctrl, const USBH_PIPE *ptr_pipe);
974 
980 extern usbStatus USBH_DefaultPipeReceive (uint8_t ctrl, uint8_t *buf, uint32_t len);
981 
985 extern uint32_t USBH_DefaultPipeReceiveGetResult (uint8_t ctrl);
986 
991 extern usbStatus USBH_DefaultPipeSendSetup (uint8_t ctrl, const USB_SETUP_PACKET *setup_packet);
992 
998 extern usbStatus USBH_DefaultPipeSend (uint8_t ctrl, const uint8_t *buf, uint32_t len);
999 
1003 extern uint32_t USBH_DefaultPipeSendGetResult (uint8_t ctrl);
1004 
1008 extern usbStatus USBH_DefaultPipeAbort (uint8_t ctrl);
1009 
1016 extern usbStatus USBH_ControlTransfer (uint8_t ctrl, const USB_SETUP_PACKET *setup_packet, uint8_t *data, uint32_t len);
1017 
1024 extern usbStatus USBH_DeviceRequest_GetStatus (uint8_t ctrl, uint8_t recipient, uint8_t index, uint8_t *ptr_stat_dat);
1025 
1032 extern usbStatus USBH_DeviceRequest_ClearFeature (uint8_t ctrl, uint8_t recipient, uint8_t index, uint8_t feature_selector);
1033 
1040 extern usbStatus USBH_DeviceRequest_SetFeature (uint8_t ctrl, uint8_t recipient, uint8_t index, uint8_t feature_selector);
1041 
1046 extern usbStatus USBH_DeviceRequest_SetAddress (uint8_t ctrl, uint8_t device_address);
1047 
1057 extern usbStatus USBH_DeviceRequest_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);
1058 
1068 extern usbStatus USBH_DeviceRequest_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);
1069 
1074 extern usbStatus USBH_DeviceRequest_GetConfiguration (uint8_t ctrl, uint8_t *ptr_configuration);
1075 
1080 extern usbStatus USBH_DeviceRequest_SetConfiguration (uint8_t ctrl, uint8_t configuration);
1081 
1087 extern usbStatus USBH_DeviceRequest_GetInterface (uint8_t ctrl, uint8_t index, uint8_t *ptr_alternate);
1088 
1094 extern usbStatus USBH_DeviceRequest_SetInterface (uint8_t ctrl, uint8_t index, uint8_t alternate);
1095 
1101 extern usbStatus USBH_DeviceRequest_SynchFrame (uint8_t ctrl, uint8_t index, uint8_t *ptr_frame_number);
1102 
1103 #ifdef __cplusplus
1104 }
1105 #endif
1106 
1107 #endif