update doc

doxygen/getting_started.md

@@ -5,13 +5,11 @@
 **Table of Contents**
 
 - [Download](#download)
-- [Import and Build](#import-and-build)
+- [Add tinyusb to your project](#add-tinyusb-to-your-project)
-	- [Prerequisites](#prerequisites)
-- [Configure demo](#configure-demo)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-## Download ##
+## Download
 
 tinyusb uses github as online repository https://github.com/hathach/tinyusb since it is the best place for open source project. 
 
@@ -21,22 +19,28 @@ After downloading/cloning, the code base is composed of
 
 Folder  | Description
 -----   | -------------
-*boards*  | Source files of supported boards
+boards  | Source files of supported boards
-*demos*   | Source & project files for demonstration application
+demos   | Source & project files for demonstration application
-*mcu*     | Low level mcu core & peripheral drivers (e.g CMSIS )
+mcu     | Low level mcu core & peripheral drivers (e.g CMSIS )
-*tests*   | Unit tests for the stack
+tests   | Unit tests for the stack
-*tinyusb* | All sources files for tinyusb stack itself.
+tinyusb | All sources files for tinyusb stack itself.
-*vendor*  | Source files from 3rd party such as freeRTOS, fatfs etc ...
+vendor  | Source files from 3rd party such as freeRTOS, fatfs etc ...
 
 *repo/demos* 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. 
 
-## Prerequisites ##
+## Add tinyusb to your project
+
+It is relatively simple to incorporate tinyusb to your (existing) project
+
+1. Copy core folder /**tinyusb** to your project. Let's say it is *your_project/tinyusb*
+2. Add all the .c in the core 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 such as TUSB_CFG_MCU are all defined properly in tusb_config.h.
 
-In order to build and run application demo, you would need
 
-- A [supported development board](../../boards/readme.md)
-- A supported toolchain: LPCXpresso, Keil, IAR.
 
 \subpage md_boards_readme
+
 \subpage md_doxygen_started_build_demo
+
 \subpage md_doxygen_started_run_demo

doxygen/started_run_demo.md

@@ -1,23 +1,56 @@
 # Run Demos #
 
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+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 the /demo/device you will find:
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**
-
-- [LPCXpresso](#lpcxpresso)
-- [Keil](#keil)
-- [IAR](#iar)
-- [Configure demo](#configure-demo)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
-For simplicity and user's convenience, there are only 2 basic application demos which are *Device* and *Host*. Each application demo has a few projects, each for its supported RTOS. For instance in the /demo/device you will find 3 projects
 
 - 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 * TUSB_CFG_TICKS_HZ) / 1000);
+
+    board_leds(led_on_mask, 1 - led_on_mask);
+    led_on_mask = 1 - led_on_mask; // toggle
+  }
+}
+~~~
+
+## Prerequisites ##
+
+In order to run application demo, you would need
+
+- A [supported development board](../../boards/readme.md)
+- A supported toolchain: LPCXpresso, Keil, IAR.
+
 
 
 \subpage md_doxygen_started_device_demo
+
 \subpage md_doxygen_started_host_demo

tinyusb.Doxyfile

@@ -58,7 +58,7 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = ../../../web/gh_page
+OUTPUT_DIRECTORY       = ../../web/gh_page
 
 # If the CREATE_SUBDIRS tag is set to YES, then doxygen will create 4096 sub-
 # directories (in 2 levels) under the output directory of each output format and
@@ -749,11 +749,11 @@ WARN_LOGFILE           =
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../doxygen \
+INPUT                  = doxygen \
-                         ../readme.markdown \
+                         readme.markdown \
-                         ../tinyusb \
+                         tinyusb \
-                         ../boards \
+                         boards \
-                         ../tests/readme.md
+                         tests/readme.md
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1106,7 +1106,7 @@ HTML_FILE_EXTENSION    = .html
 # of the possible markers and block names see the documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_HEADER            = header.html
+HTML_HEADER            = doxygen/header.html
 
 # The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each
 # generated HTML page. If the tag is left blank doxygen will generate a standard