From 5b09774ae05d15cb18ff9920864535b8444a1c3c Mon Sep 17 00:00:00 2001 From: hathach Date: Thu, 6 Dec 2018 21:46:34 +0700 Subject: clean up usbh, rename doxygen folder to docs --- docs/getting_started.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 docs/getting_started.md (limited to 'docs/getting_started.md') diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 000000000..6d6091c03 --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,63 @@ +# Getting Started # + + + +**Table of Contents** + +- [Download](#download) +- [Add tinyusb to your project](#add-tinyusb-to-your-project) + + + +## Download + +tinyusb uses github as online repository https://github.com/hathach/tinyusb since it is the best place for open source project. + +If you are using Linux, you already know how to what to do. But If Windows is your OS, I would suggest to install [git](http://git-scm.com/) and front-end gui such as [tortoisegit](http://code.google.com/p/tortoisegit) to begin with. + +After downloading/cloning, the code base is composed of + +Folder | Description +----- | ------------- +doxygen | Documentation +examples| Folder where test examples are kept with Makefile and Segger Embedded build support +hw/bsp | Source files of supported boards +hw/mcu | Low level mcu core & peripheral drivers (e.g CMSIS ) +lib | Source files from 3rd party such as freeRTOS, fatfs etc ... +src | All sources files for tinyusb stack itself. +tests | Unit tests for the stack +tools | Files used internally + +*examples* is the folder where all the application & project files are located. There are demos for both device and hosts. For each, there are different projects for each of supported RTOS. Click to have more information on how to [build](../examples/readme.md) and run [device](../examples/device/readme.md) demos. + +## Add tinyusb to your project + +It is relatively simple to incorporate tinyusb to your (existing) project + +1. Copy or `git submodule` this repo into your project in a subfolder. Let's say it is *your_project/tinyusb* +2. Add all the .c in the src folder to your project settings (uvproj, ewp, makefile) +3. Add *your_project/tinysb* to your include path. Also make sure your current include path also contains the configuration file tusb_config.h. Or you could simply put the tusb_config.h into the tinyusb folder as well. +4. Make sure all required macros are all defined properly in tusb_config.h (configure file in demo application is sufficient, but you need to add a few more such as CFG_TUSB_MCU, CFG_TUSB_OS, CFG_TUD_TASK_PRIO since they are passed by IDE/compiler to maintain a unique configure for all demo projects). +5. If you use the device stack, make sure you have created/modified usb descriptors for your own need. Ultimately you need to fill out required pointers in tusbd_descriptor_pointers for that stack to work. +6. Add tusb_init() call to your reset initialization code. +7. Implement all enabled classes's callbacks. +8. If you don't use any RTOSes at all, you need to continuously and/or periodically call tusb_task() function. Most of the callbacks and functionality are handled and invoke within the call of that task runner. + +~~~{.c} +int main(void) +{ + your_init_code(); + tusb_init(); // initialize tinyusb stack + + while(1) // the mainloop + { + your_application_code(); + + tusb_task(); // handle tinyusb event, task etc ... + } +} +~~~ + +[//]: # (\subpage md_boards_readme) +[//]: # (\subpage md_doxygen_started_demo) +[//]: # (\subpage md_tools_readme) -- cgit v1.3.1 From bc46dc6edf3ff4bb72fb36e74b8a7d3da447d2d4 Mon Sep 17 00:00:00 2001 From: hathach Date: Thu, 13 Dec 2018 13:49:09 +0700 Subject: osal clean up remove OSAL_TASK_DEF, osal_task_create. Applicaton should create a task and call tinyusb_task(). This make API consistent with NO OS. --- docs/configuration.txt | 1 - docs/getting_started.md | 2 +- examples/device/cdc_msc_hid/src/main.c | 39 ++----------- .../cdc_msc_hid_freertos/ses/nrf5x/nrf5x.emProject | 3 +- examples/device/cdc_msc_hid_freertos/src/main.c | 65 +++++++++++----------- .../device/cdc_msc_hid_freertos/src/tusb_config.h | 8 +-- examples/host/cdc_msc_hid/src/tusb_config.h | 16 +++--- examples/obsolete/device/src/tusb_config.h | 3 - lib/FreeRTOS/freertos_hook.c | 11 ++-- src/common/tusb_fifo.c | 4 +- src/device/usbd.c | 46 +++------------ src/host/usbh.c | 44 ++++----------- src/osal/osal.h | 2 - src/osal/osal_freertos.h | 21 ------- src/osal/osal_mynewt.h | 21 ------- src/osal/osal_none.h | 10 ---- src/tusb.c | 3 - src/tusb.h | 11 ++-- src/tusb_option.h | 5 -- 19 files changed, 76 insertions(+), 239 deletions(-) (limited to 'docs/getting_started.md') diff --git a/docs/configuration.txt b/docs/configuration.txt index 49061a4a0..7850827f6 100644 --- a/docs/configuration.txt +++ b/docs/configuration.txt @@ -20,7 +20,6 @@ #define CFG_TUSB_MCU ///< Select one of the supported MCU, the value must be from \ref group_mcu #define CFG_TUSB_OS ///< Select one of the supported RTOS, the value must be from \ref group_supported_os. -#define CFG_TUD_TASK_PRIO ///< If \ref CFG_TUSB_OS is configured to use a real RTOS (other than OPT_OS_NONE). This determines the priority of the usb stack task. //--------------------------------------------------------------------+ // HOST CONFIGURATION diff --git a/docs/getting_started.md b/docs/getting_started.md index 6d6091c03..268811ff4 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -37,7 +37,7 @@ It is relatively simple to incorporate tinyusb to your (existing) project 1. Copy or `git submodule` this repo into your project in a subfolder. Let's say it is *your_project/tinyusb* 2. Add all the .c in the src folder to your project settings (uvproj, ewp, makefile) 3. Add *your_project/tinysb* to your include path. Also make sure your current include path also contains the configuration file tusb_config.h. Or you could simply put the tusb_config.h into the tinyusb folder as well. -4. Make sure all required macros are all defined properly in tusb_config.h (configure file in demo application is sufficient, but you need to add a few more such as CFG_TUSB_MCU, CFG_TUSB_OS, CFG_TUD_TASK_PRIO since they are passed by IDE/compiler to maintain a unique configure for all demo projects). +4. Make sure all required macros are all defined properly in tusb_config.h (configure file in demo application is sufficient, but you need to add a few more such as CFG_TUSB_MCU, CFG_TUSB_OS since they are passed by IDE/compiler to maintain a unique configure for all demo projects). 5. If you use the device stack, make sure you have created/modified usb descriptors for your own need. Ultimately you need to fill out required pointers in tusbd_descriptor_pointers for that stack to work. 6. Add tusb_init() call to your reset initialization code. 7. Implement all enabled classes's callbacks. diff --git a/examples/device/cdc_msc_hid/src/main.c b/examples/device/cdc_msc_hid/src/main.c index bc260fdfa..178609e1e 100644 --- a/examples/device/cdc_msc_hid/src/main.c +++ b/examples/device/cdc_msc_hid/src/main.c @@ -46,7 +46,6 @@ //--------------------------------------------------------------------+ // MACRO CONSTANT TYPEDEF PROTYPES //--------------------------------------------------------------------+ -void print_greeting(void); void led_blinking_task(void); extern void virtual_com_task(void); @@ -56,7 +55,6 @@ extern void usb_hid_task(void); int main(void) { board_init(); - print_greeting(); tusb_init(); @@ -84,9 +82,9 @@ int main(void) #if CFG_TUD_CDC void virtual_com_task(void) { - // connected and there are data available if ( tud_cdc_connected() ) { + // connected and there are data available if ( tud_cdc_available() ) { uint8_t buf[64]; @@ -98,11 +96,7 @@ void virtual_com_task(void) { tud_cdc_write_char(buf[i]); - if ( buf[i] == '\r' ) - { - tud_cdc_write_char('\n'); - tud_cdc_write_str("tinyusb cdc: "); - } + if ( buf[i] == '\r' ) tud_cdc_write_char('\n'); } tud_cdc_write_flush(); @@ -117,8 +111,8 @@ void tud_cdc_line_state_cb(uint8_t itf, bool dtr, bool rts) // connected if ( dtr && rts ) { - // print greeting - tud_cdc_write_str("tinyusb cdc: "); + // print initial message when connected + tud_cdc_write_str("\r\nTinyUSB CDC MSC HID device example\r\n"); } } #endif @@ -213,28 +207,3 @@ void led_blinking_task(void) board_led_control(led_state); led_state = 1 - led_state; // toggle } - -//--------------------------------------------------------------------+ -// HELPER FUNCTION -//--------------------------------------------------------------------+ -void print_greeting(void) -{ - char const * const rtos_name[] = - { - [OPT_OS_NONE] = "None", - [OPT_OS_FREERTOS] = "FreeRTOS", - }; - - printf("\n--------------------------------------------------------------------\n"); - printf("- Device Demo (a tinyusb example)\n"); - printf("- if you find any bugs or get any questions, feel free to file an\n"); - printf("- issue at https://github.com/hathach/tinyusb\n"); - printf("--------------------------------------------------------------------\n\n"); - - printf("This DEVICE demo is configured to support:"); - printf(" - RTOS = %s\n", rtos_name[CFG_TUSB_OS]); - if (CFG_TUD_CDC ) puts(" - Communication Device Class"); - if (CFG_TUD_MSC ) puts(" - Mass Storage"); - if (CFG_TUD_HID_KEYBOARD ) puts(" - HID Keyboard"); - if (CFG_TUD_HID_MOUSE ) puts(" - HID Mouse"); -} diff --git a/examples/device/cdc_msc_hid_freertos/ses/nrf5x/nrf5x.emProject b/examples/device/cdc_msc_hid_freertos/ses/nrf5x/nrf5x.emProject index 76615bf5b..ea4950682 100644 --- a/examples/device/cdc_msc_hid_freertos/ses/nrf5x/nrf5x.emProject +++ b/examples/device/cdc_msc_hid_freertos/ses/nrf5x/nrf5x.emProject @@ -18,11 +18,12 @@ arm_target_debug_interface_type="ADIv5" arm_target_device_name="nRF52840_xxAA" arm_target_interface_type="SWD" - build_treat_warnings_as_errors="Yes" + build_treat_warnings_as_errors="No" c_preprocessor_definitions="NRF52840_XXAA;__nRF_FAMILY;ARM_MATH_CM4;FLASH_PLACEMENT=1;BOARD_PCA10056;CFG_TUSB_MCU=OPT_MCU_NRF5X" c_user_include_directories="./;../../src;$(rootDir)/hw/cmsis/Include;$(rootDir)/hw;$(rootDir)/src;$(nrfxDir)/..;$(nrfxDir);$(nrfxDir)/mdk;$(nrfxDir)/hal;$(nrfxDir)/drivers/include;$(freertosDir)/Source/include;$(freertosDir)/Source/portable/GCC/ARM_CM4F" debug_register_definition_file="nrf52840_Registers.xml" debug_target_connection="J-Link" + gcc_enable_all_warnings="Yes" gcc_entry_point="Reset_Handler" link_use_linker_script_file="No" linker_memory_map_file="nRF52840_xxAA_MemoryMap.xml" diff --git a/examples/device/cdc_msc_hid_freertos/src/main.c b/examples/device/cdc_msc_hid_freertos/src/main.c index fbe1ec93e..843b2b077 100644 --- a/examples/device/cdc_msc_hid_freertos/src/main.c +++ b/examples/device/cdc_msc_hid_freertos/src/main.c @@ -59,14 +59,13 @@ //--------------------------------------------------------------------+ // INTERNAL OBJECT & FUNCTION DECLARATION //--------------------------------------------------------------------+ -void print_greeting(void); void led_blinky_cb(TimerHandle_t xTimer); +void usb_device_task(void* param); /*------------- MAIN -------------*/ int main(void) { board_init(); - print_greeting(); // soft timer for blinky TimerHandle_t tm_hdl = xTimerCreate(NULL, pdMS_TO_TICKS(1000), true, NULL, led_blinky_cb); @@ -74,10 +73,13 @@ int main(void) tusb_init(); + // Create a task for tinyusb device stack + xTaskCreate( usb_device_task, "usbd", 150, NULL, configMAX_PRIORITIES-1, NULL); + // Create task #if CFG_TUD_CDC extern void cdc_task(void* params); - xTaskCreate( cdc_task, "cdc", 256, NULL, 2, NULL); + xTaskCreate( cdc_task, "cdc", 256, NULL, configMAX_PRIORITIES-2, NULL); #endif #if CFG_TUD_HID @@ -90,6 +92,19 @@ int main(void) return 0; } +// USB Device Driver task +// This top level thread process all usb events and invoke callbacks +void usb_device_task(void* param) +{ + (void) param; + + // RTOS forever loop + while (1) + { + tusb_task(); + } +} + //--------------------------------------------------------------------+ // USB CDC //--------------------------------------------------------------------+ @@ -98,11 +113,12 @@ void cdc_task(void* params) { (void) params; + // RTOS forever loop while ( 1 ) { - // connected and there are data available if ( tud_cdc_connected() ) { + // connected and there are data available if ( tud_cdc_available() ) { uint8_t buf[64]; @@ -110,10 +126,15 @@ void cdc_task(void* params) // read and echo back uint32_t count = tud_cdc_read(buf, sizeof(buf)); - tud_cdc_write(buf, count); - } + for(uint32_t i=0; imutex) { - uint32_t err; - (void) err; - osal_mutex_lock(f->mutex, OSAL_TIMEOUT_WAIT_FOREVER, &err); + osal_mutex_lock(f->mutex, OSAL_TIMEOUT_WAIT_FOREVER); } } diff --git a/src/device/usbd.c b/src/device/usbd.c index 8c685d5b3..a0ff96e8e 100644 --- a/src/device/usbd.c +++ b/src/device/usbd.c @@ -36,8 +36,6 @@ */ /**************************************************************************/ -// This top level class manages the bus state and delegates events to class-specific drivers. - #include "tusb_option.h" #if TUSB_OPT_DEVICE_ENABLED @@ -52,15 +50,6 @@ #define CFG_TUD_TASK_QUEUE_SZ 16 #endif -#ifndef CFG_TUD_TASK_STACK_SZ -#define CFG_TUD_TASK_STACK_SZ 150 -#endif - -#ifndef CFG_TUD_TASK_PRIO -#define CFG_TUD_TASK_PRIO 0 -#endif - - //--------------------------------------------------------------------+ // Device Data //--------------------------------------------------------------------+ @@ -153,16 +142,14 @@ static usbd_class_driver_t const usbd_class_drivers[] = #endif }; -enum { USBD_CLASS_DRIVER_COUNT = sizeof(usbd_class_drivers) / sizeof(usbd_class_driver_t) }; - +enum { USBD_CLASS_DRIVER_COUNT = TU_ARRAY_SZIE(usbd_class_drivers) }; //--------------------------------------------------------------------+ // DCD Event //--------------------------------------------------------------------+ -OSAL_TASK_DEF(_usbd_task_def, "usbd", usbd_task, CFG_TUD_TASK_PRIO, CFG_TUD_TASK_STACK_SZ); // Event queue -// role device/host is used by OS NONE for mutex (disable usb isr) only +// OPT_MODE_DEVICE is used by OS NONE for mutex (disable usb isr) OSAL_QUEUE_DEF(OPT_MODE_DEVICE, _usbd_qdef, CFG_TUD_TASK_QUEUE_SZ, dcd_event_t); static osal_queue_t _usbd_q; @@ -195,8 +182,6 @@ bool usbd_init (void) _usbd_q = osal_queue_create(&_usbd_qdef); TU_ASSERT(_usbd_q != NULL); - osal_task_create(&_usbd_task_def); - // Init class drivers for (uint8_t i = 0; i < USBD_CLASS_DRIVER_COUNT; i++) usbd_class_drivers[i].init(); @@ -221,9 +206,13 @@ static void usbd_reset(uint8_t rhport) } } -// Main device task implementation -static void usbd_task_body(void) +/* USB Device Driver task + * This top level thread manages all device controller event and delegates events to class-specific drivers. + */ +void usbd_task( void* param) { + (void) param; + // Loop until there is no more events in the queue while (1) { @@ -297,25 +286,6 @@ static void usbd_task_body(void) } } -/* USB device task - * Thread that handles all device events. With an real RTOS, the task must be a forever loop and never return. - * For coding convenience with no RTOS, we use wrapped sub-function for processing to easily return at any time. - */ -void usbd_task( void* param) -{ - (void) param; - -#if CFG_TUSB_OS != OPT_OS_NONE - while (1) { -#endif - - usbd_task_body(); - -#if CFG_TUSB_OS != OPT_OS_NONE - } -#endif -} - //--------------------------------------------------------------------+ // Control Request Parser & Handling //--------------------------------------------------------------------+ diff --git a/src/host/usbh.c b/src/host/usbh.c index 39de4f7e7..7bcf7aaaf 100644 --- a/src/host/usbh.c +++ b/src/host/usbh.c @@ -46,15 +46,6 @@ #define CFG_TUH_TASK_QUEUE_SZ 16 #endif -#ifndef CFG_TUH_TASK_STACK_SZ -#define CFG_TUH_TASK_STACK_SZ 200 -#endif - -#ifndef CFG_TUH_TASK_PRIO -#define CFG_TUH_TASK_PRIO 0 -#endif - - //--------------------------------------------------------------------+ // INCLUDE //--------------------------------------------------------------------+ @@ -123,9 +114,9 @@ enum { USBH_CLASS_DRIVER_COUNT = TU_ARRAY_SZIE(usbh_class_drivers) }; //--------------------------------------------------------------------+ // INTERNAL OBJECT & FUNCTION DECLARATION //--------------------------------------------------------------------+ -CFG_TUSB_MEM_SECTION usbh_device_t _usbh_devices[CFG_TUSB_HOST_DEVICE_MAX+1]; // including zero-address -OSAL_TASK_DEF(_usbh_task_def, "usbh", usbh_task, CFG_TUH_TASK_PRIO, CFG_TUH_TASK_STACK_SZ); +// including zero-address +CFG_TUSB_MEM_SECTION usbh_device_t _usbh_devices[CFG_TUSB_HOST_DEVICE_MAX+1]; // Event queue // role device/host is used by OS NONE for mutex (disable usb isr) only @@ -161,8 +152,6 @@ bool usbh_init(void) _usbh_q = osal_queue_create( &_usbh_qdef ); TU_ASSERT(_usbh_q != NULL); - osal_task_create(&_usbh_task_def); - //------------- Semaphore, Mutex for Control Pipe -------------// for(uint8_t i=0; ifunc, taskdef->strname, taskdef->stack_sz, NULL, taskdef->prio, (StackType_t*) taskdef->buf, &taskdef->stask); -} - static inline void osal_task_delay(uint32_t msec) { vTaskDelay( pdMS_TO_TICKS(msec) ); diff --git a/src/osal/osal_mynewt.h b/src/osal/osal_mynewt.h index 62b5b45e8..d63ea731d 100644 --- a/src/osal/osal_mynewt.h +++ b/src/osal/osal_mynewt.h @@ -46,27 +46,6 @@ //--------------------------------------------------------------------+ // TASK API //--------------------------------------------------------------------+ -#define OSAL_TASK_DEF(_name, _str, _func, _prio, _stack_sz) \ - static os_stack_t _name##_##buf[_stack_sz]; \ - osal_task_def_t _name = { .func = _func, .prio = _prio, .stack_sz = _stack_sz, .buf = _name##_##buf, .strname = _str }; - -typedef struct -{ - struct os_task mynewt_task; - osal_task_func_t func; - - uint16_t prio; - uint16_t stack_sz; - void* buf; - const char* strname; -}osal_task_def_t; - -static inline bool osal_task_create(osal_task_def_t* taskdef) -{ - return OS_OK == os_task_init(&taskdef->mynewt_task, taskdef->strname, taskdef->func, NULL, taskdef->prio, OS_WAIT_FOREVER, - (os_stack_t*) taskdef->buf, taskdef->stack_sz); -} - static inline void osal_task_delay(uint32_t msec) { os_time_delay( os_time_ms_to_ticks32(msec) ); diff --git a/src/osal/osal_none.h b/src/osal/osal_none.h index ff37113c6..55db674ce 100644 --- a/src/osal/osal_none.h +++ b/src/osal/osal_none.h @@ -51,17 +51,7 @@ //--------------------------------------------------------------------+ // TASK API -// Virtually do nothing in osal none //--------------------------------------------------------------------+ -#define OSAL_TASK_DEF(_name, _str, _func, _prio, _stack_sz) osal_task_def_t _name; -typedef uint8_t osal_task_def_t; - -static inline bool osal_task_create(osal_task_def_t* taskdef) -{ - (void) taskdef; - return true; -} - static inline void osal_task_delay(uint32_t msec) { uint32_t start = tusb_hal_millis(); diff --git a/src/tusb.c b/src/tusb.c index 4f7996664..fd390722b 100644 --- a/src/tusb.c +++ b/src/tusb.c @@ -68,7 +68,6 @@ bool tusb_init(void) return TUSB_ERROR_NONE; } -#if CFG_TUSB_OS == OPT_OS_NONE void tusb_task(void) { #if TUSB_OPT_HOST_ENABLED @@ -79,8 +78,6 @@ void tusb_task(void) usbd_task(NULL); #endif } -#endif - /*------------------------------------------------------------------*/ /* Debug diff --git a/src/tusb.h b/src/tusb.h index 4d65c80e1..e4393d067 100644 --- a/src/tusb.h +++ b/src/tusb.h @@ -105,11 +105,9 @@ // return true if success bool tusb_init(void); -#if CFG_TUSB_OS == OPT_OS_NONE -/** \brief Run all tinyusb's internal tasks (e.g host task, device task). - * \note This function is only required when using no RTOS (\ref CFG_TUSB_OS == OPT_OS_NONE). All the stack functions - * & callback are invoked within this function. This should be called periodically within the mainloop - * +/** Run all tinyusb's internal tasks (e.g host task, device task) and invoke callback + * This should be called periodically within the mainloop. + @code int main(void) { @@ -126,10 +124,9 @@ bool tusb_init(void); } } @endcode - * + */ void tusb_task(void); -#endif /** @} */ diff --git a/src/tusb_option.h b/src/tusb_option.h index 8b2e59b17..07d8387e3 100644 --- a/src/tusb_option.h +++ b/src/tusb_option.h @@ -224,11 +224,6 @@ //------------------------------------------------------------------ // Configuration Validation //------------------------------------------------------------------ - -#if (CFG_TUSB_OS != OPT_OS_NONE) && !defined (CFG_TUD_TASK_PRIO) - #error CFG_TUD_TASK_PRIO need to be defined (hint: use the highest if possible) -#endif - #if CFG_TUD_ENDOINT0_SIZE > 64 #error Control Endpoint Max Packet Size cannot be larger than 64 #endif -- cgit v1.3.1 From 1c49c479cabf1be9b1c22017c42a8480b26cebcb Mon Sep 17 00:00:00 2001 From: hathach Date: Thu, 13 Dec 2018 14:51:37 +0700 Subject: seperate tusb_task() to tud_task() and tuh_task() tusb_task() still exists for backward compatible --- docs/getting_started.md | 5 ++-- docs/porting.md | 4 +-- examples/device/cdc_msc_hid/src/main.c | 3 ++- examples/device/cdc_msc_hid_freertos/src/main.c | 3 ++- examples/host/cdc_msc_hid/src/main.c | 3 ++- src/class/hid/hid_device.c | 2 +- src/device/usbd.c | 18 ++++++++++++- src/device/usbd.h | 1 + src/device/usbd_pvt.h | 2 -- src/host/usbh.c | 18 ++++++++++++- src/host/usbh.h | 9 +++---- src/tusb.c | 11 -------- src/tusb.h | 34 ++++++++++--------------- 13 files changed, 64 insertions(+), 49 deletions(-) (limited to 'docs/getting_started.md') diff --git a/docs/getting_started.md b/docs/getting_started.md index 268811ff4..723e6d862 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -41,7 +41,7 @@ It is relatively simple to incorporate tinyusb to your (existing) project 5. If you use the device stack, make sure you have created/modified usb descriptors for your own need. Ultimately you need to fill out required pointers in tusbd_descriptor_pointers for that stack to work. 6. Add tusb_init() call to your reset initialization code. 7. Implement all enabled classes's callbacks. -8. If you don't use any RTOSes at all, you need to continuously and/or periodically call tusb_task() function. Most of the callbacks and functionality are handled and invoke within the call of that task runner. +8. If you don't use any RTOSes at all, you need to continuously and/or periodically call tud_task()/tuh_task() function. Most of the callbacks and functionality are handled and invoke within the call of that task runner. ~~~{.c} int main(void) @@ -53,7 +53,8 @@ int main(void) { your_application_code(); - tusb_task(); // handle tinyusb event, task etc ... + tud_task(); // tinyusb device task + tuh_task(); // tinyusb host task } } ~~~ diff --git a/docs/porting.md b/docs/porting.md index 040112d9c..f5af82800 100644 --- a/docs/porting.md +++ b/docs/porting.md @@ -61,7 +61,7 @@ The OPT_OS_NONE option is the only option which requires an MCU specific functio ### Device API -After the USB device is setup, the USB device code works by processing events on the main thread (by calling `tusb_task`). These events are queued by the USB interrupt handler. So, there are three parts to the device low-level API: device setup, endpoint setup and interrupt processing. +After the USB device is setup, the USB device code works by processing events on the main thread (by calling `tud_task`). These events are queued by the USB interrupt handler. So, there are three parts to the device low-level API: device setup, endpoint setup and interrupt processing. All of the code for the low-level device API is in `src/portable///dcd_.c`. @@ -164,4 +164,4 @@ At this point you should have everything working! ;-) Of course, you may not wri Use [WireShark](https://www.wireshark.org/) or [a Beagle](https://www.totalphase.com/protocols/usb/) to sniff the USB traffic. When things aren't working its likely very early in the USB enumeration process. Figuring out where can help clue in where the issue is. For example: * If the host sends a SETUP packet and its not ACKed then your USB peripheral probably isn't started correctly. * If the peripheral is started correctly but it still didn't work, then verify your usb clock is correct. (You did output a PWM based on it right? ;-) ) -* If the SETUP packet is ACKed but nothing is sent back then you interrupt handler isn't queueing the setup packet correctly. (Also, if you are using your own code instead of an example `tusb_task` may not be called.) If thats OK, the `dcd_xfer_complete` may not be setting up the next transaction correctly. +* If the SETUP packet is ACKed but nothing is sent back then you interrupt handler isn't queueing the setup packet correctly. (Also, if you are using your own code instead of an example `tud_task` may not be called.) If thats OK, the `dcd_xfer_complete` may not be setting up the next transaction correctly. diff --git a/examples/device/cdc_msc_hid/src/main.c b/examples/device/cdc_msc_hid/src/main.c index 178609e1e..a9d1f1618 100644 --- a/examples/device/cdc_msc_hid/src/main.c +++ b/examples/device/cdc_msc_hid/src/main.c @@ -60,7 +60,8 @@ int main(void) while (1) { - tusb_task(); + // tinyusb device task + tud_task(); led_blinking_task(); diff --git a/examples/device/cdc_msc_hid_freertos/src/main.c b/examples/device/cdc_msc_hid_freertos/src/main.c index 843b2b077..946972c16 100644 --- a/examples/device/cdc_msc_hid_freertos/src/main.c +++ b/examples/device/cdc_msc_hid_freertos/src/main.c @@ -101,7 +101,8 @@ void usb_device_task(void* param) // RTOS forever loop while (1) { - tusb_task(); + // tinyusb device task + tud_task(); } } diff --git a/examples/host/cdc_msc_hid/src/main.c b/examples/host/cdc_msc_hid/src/main.c index ebb540782..f1139974d 100644 --- a/examples/host/cdc_msc_hid/src/main.c +++ b/examples/host/cdc_msc_hid/src/main.c @@ -62,7 +62,8 @@ int main(void) while (1) { - tusb_task(); + // tinyusb host task + tuh_task(); led_blinking_task(); diff --git a/src/class/hid/hid_device.c b/src/class/hid/hid_device.c index bd49c157a..70aa7370d 100644 --- a/src/class/hid/hid_device.c +++ b/src/class/hid/hid_device.c @@ -340,7 +340,7 @@ bool hidd_open(uint8_t rhport, tusb_desc_interface_t const * desc_itf, uint16_t /*------------- Boot protocol only keyboard & mouse -------------*/ if (desc_itf->bInterfaceSubClass == HID_SUBCLASS_BOOT) { - TU_ASSERT(desc_itf->bInterfaceProtocol == HID_PROTOCOL_KEYBOARD || desc_itf->bInterfaceProtocol == HID_PROTOCOL_MOUSE, ERR_TUD_INVALID_DESCRIPTOR); + TU_ASSERT(desc_itf->bInterfaceProtocol == HID_PROTOCOL_KEYBOARD || desc_itf->bInterfaceProtocol == HID_PROTOCOL_MOUSE); #if CFG_TUD_HID_KEYBOARD && CFG_TUD_HID_KEYBOARD_BOOT if (desc_itf->bInterfaceProtocol == HID_PROTOCOL_KEYBOARD) diff --git a/src/device/usbd.c b/src/device/usbd.c index aa81cb118..a3fbfdff9 100644 --- a/src/device/usbd.c +++ b/src/device/usbd.c @@ -208,8 +208,24 @@ static void usbd_reset(uint8_t rhport) /* USB Device Driver task * This top level thread manages all device controller event and delegates events to class-specific drivers. + * This should be called periodically within the mainloop or rtos thread. + * + @code + int main(void) + { + application_init(); + tusb_init(); + + while(1) // the mainloop + { + application_code(); + + tud_task(); // tinyusb device task + } + } + @endcode */ -void usbd_task (void) +void tud_task (void) { // Loop until there is no more events in the queue while (1) diff --git a/src/device/usbd.h b/src/device/usbd.h index f9e0d8f4d..f9e7368ce 100644 --- a/src/device/usbd.h +++ b/src/device/usbd.h @@ -81,6 +81,7 @@ extern tud_desc_set_t tud_desc_set; // APPLICATION API //--------------------------------------------------------------------+ bool tud_mounted(void); +void tud_task (void); //--------------------------------------------------------------------+ // APPLICATION CALLBACK (WEAK is optional) diff --git a/src/device/usbd_pvt.h b/src/device/usbd_pvt.h index d1fccd9e0..06951673f 100644 --- a/src/device/usbd_pvt.h +++ b/src/device/usbd_pvt.h @@ -52,8 +52,6 @@ extern tud_desc_set_t const* usbd_desc_set; // INTERNAL API for stack management //--------------------------------------------------------------------+ bool usbd_init (void); -void usbd_task (void); - // Carry out Data and Status stage of control transfer // - If len = 0, it is equivalent to sending status only diff --git a/src/host/usbh.c b/src/host/usbh.c index 27d32330a..d0b5edb63 100644 --- a/src/host/usbh.c +++ b/src/host/usbh.c @@ -601,8 +601,24 @@ bool enum_task(hcd_event_t* event) /* USB Host Driver task * This top level thread manages all host controller event and delegates events to class-specific drivers. + * This should be called periodically within the mainloop or rtos thread. + * + @code + int main(void) + { + application_init(); + tusb_init(); + + while(1) // the mainloop + { + application_code(); + + tuh_task(); // tinyusb host task + } + } + @endcode */ -void usbh_task(void) +void tuh_task(void) { // Loop until there is no more events in the queue while (1) diff --git a/src/host/usbh.h b/src/host/usbh.h index 8009c5080..fee1235f4 100644 --- a/src/host/usbh.h +++ b/src/host/usbh.h @@ -78,9 +78,9 @@ typedef struct { //--------------------------------------------------------------------+ // APPLICATION API //--------------------------------------------------------------------+ -//tusb_error_t tusbh_configuration_set (uint8_t dev_addr, uint8_t configure_number) ATTR_WARN_UNUSED_RESULT; -tusb_device_state_t tuh_device_get_state (uint8_t dev_addr) ATTR_WARN_UNUSED_RESULT ATTR_PURE; -static inline bool tuh_device_is_configured(uint8_t dev_addr) ATTR_ALWAYS_INLINE ATTR_WARN_UNUSED_RESULT ATTR_PURE; +void tuh_task(void); + +tusb_device_state_t tuh_device_get_state (uint8_t dev_addr); static inline bool tuh_device_is_configured(uint8_t dev_addr) { return tuh_device_get_state(dev_addr) == TUSB_DEVICE_STATE_CONFIGURED; @@ -89,7 +89,7 @@ static inline bool tuh_device_is_configured(uint8_t dev_addr) //--------------------------------------------------------------------+ // APPLICATION CALLBACK //--------------------------------------------------------------------+ -ATTR_WEAK uint8_t tuh_device_attached_cb (tusb_desc_device_t const *p_desc_device) ATTR_WARN_UNUSED_RESULT; +ATTR_WEAK uint8_t tuh_device_attached_cb (tusb_desc_device_t const *p_desc_device); /** Callback invoked when device is mounted (configured) */ ATTR_WEAK void tuh_mount_cb (uint8_t dev_addr); @@ -103,7 +103,6 @@ ATTR_WEAK void tuh_umount_cb(uint8_t dev_addr); #ifdef _TINY_USB_SOURCE_FILE_ bool usbh_init(void); -void usbh_task(void); bool usbh_control_xfer (uint8_t dev_addr, tusb_control_request_t* request, uint8_t* data); diff --git a/src/tusb.c b/src/tusb.c index 253adc59c..ad2dcbfd3 100644 --- a/src/tusb.c +++ b/src/tusb.c @@ -68,17 +68,6 @@ bool tusb_init(void) return TUSB_ERROR_NONE; } -void tusb_task(void) -{ - #if TUSB_OPT_HOST_ENABLED - usbh_task(); - #endif - - #if TUSB_OPT_DEVICE_ENABLED - usbd_task(); - #endif -} - /*------------------------------------------------------------------*/ /* Debug *------------------------------------------------------------------*/ diff --git a/src/tusb.h b/src/tusb.h index e4393d067..3a13bbecc 100644 --- a/src/tusb.h +++ b/src/tusb.h @@ -101,32 +101,24 @@ /** \ingroup group_application_api * @{ */ -// Initialize device/host stack according to tusb_config.h -// return true if success +// Initialize device/host stack bool tusb_init(void); -/** Run all tinyusb's internal tasks (e.g host task, device task) and invoke callback - * This should be called periodically within the mainloop. +// TODO +// bool tusb_teardown(void); - @code - int main(void) - { - your_init_code(); - tusb_init(); - // other config code - - while(1) // the mainloop - { - your_application_code(); - - tusb_task(); // handle tinyusb event, task etc ... - } - } - @endcode +// backward compatible only. TODO remove later +static inline void tusb_task(void) +{ + #if TUSB_OPT_HOST_ENABLED + tuh_task(); + #endif - */ -void tusb_task(void); + #if TUSB_OPT_DEVICE_ENABLED + tud_task(); + #endif +} /** @} */ -- cgit v1.3.1 From 455da57f9d66a342383334f3af82c27b57feb6cd Mon Sep 17 00:00:00 2001 From: hathach Date: Mon, 17 Dec 2018 12:08:11 +0700 Subject: docs clean up --- docs/changelog.md | 1 - docs/coding_standard.md | 80 ------------------------------------------------- docs/configuration.txt | 76 ---------------------------------------------- docs/getting_started.md | 38 ++++++----------------- docs/group_def.txt | 22 -------------- docs/header.html | 58 ----------------------------------- docs/started_demo.md | 48 ----------------------------- 7 files changed, 9 insertions(+), 314 deletions(-) delete mode 100644 docs/changelog.md delete mode 100644 docs/coding_standard.md delete mode 100644 docs/configuration.txt delete mode 100644 docs/group_def.txt delete mode 100644 docs/header.html delete mode 100644 docs/started_demo.md (limited to 'docs/getting_started.md') diff --git a/docs/changelog.md b/docs/changelog.md deleted file mode 100644 index 420e6f23d..000000000 --- a/docs/changelog.md +++ /dev/null @@ -1 +0,0 @@ -# Change Log diff --git a/docs/coding_standard.md b/docs/coding_standard.md deleted file mode 100644 index 3eb3c0d7d..000000000 --- a/docs/coding_standard.md +++ /dev/null @@ -1,80 +0,0 @@ -# Coding Standards # - -C is a dangerous language by itself, plus tinyusb make use of goodies features of C99, which saves a tons of code lines (also means save a tons of bugs). However, those features can be misused and pave the way for bugs sneaking into. Therefore, to minimize bugs, the author try to comply with published Coding Standards like: - -- [MISRA-C](http://www.misra-c.com/Activities/MISRAC/tabid/160/Default.aspx) -- [Power of 10](http://spinroot.com/p10/) -- [Jet Propulsion Laboratory (JPL) for C](http://lars-lab.jpl.nasa.gov) - -Where is possible, standards are followed but it is almost impossible to follow all of these without making some exceptions. I am pretty sure this code base violates more than what are described below, if you can find any, please report it to me or file an issue on github. - -## MISRA-C 2004 Exceptions ## - -MISRA-C is well respected & a bar for industrial coding standard. - -- **Rule 2.2: use only** - - It has long passed the day that C99 comment style // will cause any issues, especially compiler's C99 mode is required to build tinyusb. - -- **Rule 8.5: No definitions of objects or function in a header file** - - function definitions in header files are used to allow 'inlining' - -- **Rule 14.7: A function shall have a single point of exit at the end of the function** - - Unfortunately, following this rule will have a lot of nesting if-else, I prefer to exit as soon as possible with assert style and flatten if-else. - -- **Rule 18.4: Unions shall not be used** - - sorry MISRA, union is required to effectively mapped to MCU's registers - -- expect to have more & more exceptions. - -## Power of 10 ## - -is a small & easy to remember but yet powerful coding guideline. Most (if not all) of the rules here are included in JPL. Because it is very small, all the rules will be listed here, those with *italic* are compliant, **bold** are violated. - -1. *Restrict to simple control flow constructs* - - yes, I hate goto statement, therefore there is none of those here - -2. *Give all loops a fixed upper-bound* - - one of my favorite rule - -3. *Do not use dynamic memory allocation after initialization* - - the tinyusb uses the static memory for all of its data. - -4. **Limit functions to no more than 60 lines of text** - - 60 is a little bit too strict, I will update the relaxing number later - -5. *Use minimally two assertions per function on average* - - not sure the exact number, but I use a tons of those assert - -6. *Declare data objects at the smallest possible level of scope* - - one of the best & easiest rule to follow - -7. *Check the return value of non-void functions, and check the validity of function parameters* - - I did check all of the public application API's parameters. For internal API, calling function needs to trust their caller to reduce duplicated check. - -8. **Limit the use of the preprocessor to file inclusion and simple macros** - - Although I prefer inline function, however C macros are far powerful than that. I simply cannot hold myself to use, for example X-Macro technique to simplify code. - -9. *Limit the use of pointers. Use no more than two levels of dereferencing per expression* - - never intend to get in trouble with complex pointer dereferencing. - -10. *Compile with all warnings enabled, and use one or more source code analyzers* - - I try to use all the defensive options of gnu, let me know if I miss some. - >-Wextra -Wswitch-default -Wunsafe-loop-optimizations -Wcast-align -Wlogical-op -Wpacked-bitfield-compat -Wnested-externs -Wredundant-decls -Winline - -## JPL ## - -coming soon ... diff --git a/docs/configuration.txt b/docs/configuration.txt deleted file mode 100644 index 7850827f6..000000000 --- a/docs/configuration.txt +++ /dev/null @@ -1,76 +0,0 @@ -/** \addtogroup group_configuration - * @{ */ - -//--------------------------------------------------------------------+ -// COMMON CONFIGURATION -//--------------------------------------------------------------------+ - -/// \brief tell the stack which mode (host/device/otg) the usb controller0 will be operated on. Possible value is -/// from \ref group_mode. Note the hardware usb controller must support the selected mode. -#define CFG_TUSB_RHPORT0_MODE - -/** USB controller in MCU often has limited access to specific RAM section. The Stack will use this macro to place internal variables - into the USB RAM section as follows. if your mcu's usb controller has no such limit, define CFG_TUSB_MEM_SECTION as empty macro. - - @code - CFG_TUSB_MEM_SECTION uint8_t usb_xfer_buffer[10]; - @endcode - */ -#define CFG_TUSB_MEM_SECTION - -#define CFG_TUSB_MCU ///< Select one of the supported MCU, the value must be from \ref group_mcu -#define CFG_TUSB_OS ///< Select one of the supported RTOS, the value must be from \ref group_supported_os. - -//--------------------------------------------------------------------+ -// HOST CONFIGURATION -//--------------------------------------------------------------------+ -/** \defgroup CFG_TUSB_HOST Host Options - * @{ */ - -/** \brief Maximum number of device host stack can manage - * \n If hub class is not enabled, set this equal to number of controllers in host mode - * \n If hub class is enabled, make sure hub is also counted */ -#define CFG_TUSB_HOST_DEVICE_MAX - -/// \brief Buffer size used for getting device configuration descriptor. You may want to increase this from default (256) -/// to support lengthy composite device especially with Audio or Video class -#define CFG_TUSB_HOST_ENUM_BUFFER_SIZE - -/** \defgroup config_host_class Class Driver - * \brief For each Class Driver a value of 1 means enable, value of 0 mean disable - * @{ */ -#define CFG_TUH_HUB ///< Enable Hub Class -#define CFG_TUH_HID_KEYBOARD ///< Enable HID Class for Keyboard -#define CFG_TUH_HID_MOUSE ///< Enable HID Class for Mouse -#define CFG_TUSB_HOST_HID_GENERIC ///< Enable HID Class for Generic (not supported yet) -#define CFG_TUH_MSC ///< Enable Mass Storage Class (SCSI subclass only) -#define CFG_TUH_CDC ///< Enable Virtual Serial (Communication Device Class) -/** @} */ - -/** @} */ // group Host - -//--------------------------------------------------------------------+ -// DEVICE CONFIGURATION -//--------------------------------------------------------------------+ -/** \defgroup CFG_TUSB_DEVICE Device Options - * @{ */ - -#define CFG_TUD_ENDOINT0_SIZE ///< Max packet size of Cotnrol Endpoint, default is 64 - -/// Application MUST define this variable and initialize its pointers's member to all required USB descriptors including -/// Device Descriptor, Configuration Descriptor, String Descriptors, HID Report Descriptors etc ... -tud_desc_init_t tusbd_descriptor_pointers; - -/** \defgroup config_device_class Class Driver - * \brief For each Class Driver a value of 1 means enable, value of 0 mean disable - * @{ */ -#define CFG_TUD_HID_KEYBOARD ///< Enable HID Class for Keyboard -#define CFG_TUD_HID_MOUSE ///< Enable HID Class for Mouse -#define CFG_TUD_HID_GENERIC ///< Enable HID Class for Generic (not supported yet) -#define CFG_TUD_MSC ///< Enable Mass Storage Class (SCSI subclass only) -#define CFG_TUD_CDC ///< Enable Virtual Serial (Communication Device Class) -/** @} */ - -/** @} */ // group Device - -/** @} */ diff --git a/docs/getting_started.md b/docs/getting_started.md index 723e6d862..123a9d2ab 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -1,32 +1,12 @@ # Getting Started # - - -**Table of Contents** +## Get -- [Download](#download) -- [Add tinyusb to your project](#add-tinyusb-to-your-project) - - - -## Download - -tinyusb uses github as online repository https://github.com/hathach/tinyusb since it is the best place for open source project. - -If you are using Linux, you already know how to what to do. But If Windows is your OS, I would suggest to install [git](http://git-scm.com/) and front-end gui such as [tortoisegit](http://code.google.com/p/tortoisegit) to begin with. - -After downloading/cloning, the code base is composed of - -Folder | Description ------ | ------------- -doxygen | Documentation -examples| Folder where test examples are kept with Makefile and Segger Embedded build support -hw/bsp | Source files of supported boards -hw/mcu | Low level mcu core & peripheral drivers (e.g CMSIS ) -lib | Source files from 3rd party such as freeRTOS, fatfs etc ... -src | All sources files for tinyusb stack itself. -tests | Unit tests for the stack -tools | Files used internally +``` +git clone git@github.com:hathach/tinyusb.git tinyusb +cd tinyusb +git submodule update --init +``` *examples* is the folder where all the application & project files are located. There are demos for both device and hosts. For each, there are different projects for each of supported RTOS. Click to have more information on how to [build](../examples/readme.md) and run [device](../examples/device/readme.md) demos. @@ -59,6 +39,6 @@ int main(void) } ~~~ -[//]: # (\subpage md_boards_readme) -[//]: # (\subpage md_doxygen_started_demo) -[//]: # (\subpage md_tools_readme) +[//]: # "\subpage md_boards_readme" +[//]: # "\subpage md_doxygen_started_demo" +[//]: # "\subpage md_tools_readme" diff --git a/docs/group_def.txt b/docs/group_def.txt deleted file mode 100644 index 0f5419810..000000000 --- a/docs/group_def.txt +++ /dev/null @@ -1,22 +0,0 @@ -// define all the modules group to have the desired ordering since doxygen order module group by -// the order of files it is feed - -/// \defgroup group_demo Demos - -/// \defgroup group_class Application - Class Driver API - -/// \defgroup group_application_api Application - Stack API -/// \brief Non-Class driver API - -/// \defgroup group_configuration Configuration tusb_config.h - -/// \defgroup group_usbd USB Device Core (USBD) - -/// \defgroup group_usbh USB Host Core (USBH) - -/// \defgroup group_osal OS Abstraction Layer (OSAL) - -/// \defgroup group_usb_definitions USB Definitions - -/// \defgroup Group_Common Common Files - diff --git a/docs/header.html b/docs/header.html deleted file mode 100644 index e75be44de..000000000 --- a/docs/header.html +++ /dev/null @@ -1,58 +0,0 @@ - - - - - - - -$projectname: $title -$title - - - -$treeview -$search -$mathjax - -$extrastylesheet - - -
- - -
- - - - - - - - - - - - - - - - - - - - - - -
-
$projectname -  $projectnumber -
-
$projectbrief
- 		- Click here to lend your support to tinyusb donation and make a donation at pledgie.com - -
$projectbrief
- 		$searchbox
-
- - diff --git a/docs/started_demo.md b/docs/started_demo.md deleted file mode 100644 index 7e82596f5..000000000 --- a/docs/started_demo.md +++ /dev/null @@ -1,48 +0,0 @@ -# Demos # - -For simplicity and user's convenience, there are only 2 basic application demos which are *Device* and *Host* respectively. Each application demo, however, has a few projects, each for its supported RTOS. For instance, in addition to the *src* folder, you will also find in the /demo/device - -- device\_os\_none for no RTOS -- device\_freertos for freeRTOS -- device\_cmsis_rtx for ARM CMSIS with RTX implemenation - -To be able to have the same application code running across RTOSes, the application make use of the "internal" **OSAL layer**. Thus this makes the application code a bit weird and over-complicated than it should be in some (many) cases. This is absolutely not necessary in product development. User can just use the native API function of supported RTOS or a state machine or blocking wait in case of none OS. For example, instead of the blinking task in application - -~~~{.c} -OSAL_TASK_FUNCTION( led_blinking_task , p_task_para) -{ - OSAL_TASK_LOOP_BEGIN - - static uint32_t led_on_mask = 0; - - osal_task_delay(led_blink_interval_ms); - - board_leds(led_on_mask, 1 - led_on_mask); - led_on_mask = 1 - led_on_mask; // toggle - - OSAL_TASK_LOOP_END -} -~~~ - -can be written in FreeRTOS's native API - -~~~{.c} -void led_blinking_task( void * p_task_para ) -{ - while(1) - { - static uint32_t led_on_mask = 0; - - // FreeRTOS API's vTaskDelay is used in place of osal_task_delay. Note it takes input parameter in tick - vTaskDelay( (led_blink_interval_ms * CFG_TUSB_TICKS_HZ) / 1000); - - board_leds(led_on_mask, 1 - led_on_mask); - led_on_mask = 1 - led_on_mask; // toggle - } -} -~~~ - - -[//]: # (\subpage md_demos_readme) -[//]: # (\subpage md_demos_device_readme) -[//]: # (\subpage md_demos_host_readme) \ No newline at end of file -- cgit v1.3.1