andy/tinyUSB
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

move doxygen folder outside

Browse Source
This commit is contained in:
hathach
2014-03-31 16:34:23 +07:00
parent c939c11248
commit 2c9b134699
5 changed files with 79 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
doxygen/coding_standard.md Normal file
View File

@@ -0,0 +1,80 @@
# 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 ...

78
doxygen/configuration.txt Normal file
View File

@@ -0,0 +1,78 @@
/** \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 TUSB_CFG_CONTROLLER_0_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 TUSB_CFG_ATTR_USBRAM as empty macro.
@code
TUSB_CFG_ATTR_USBRAM uint8_t usb_xfer_buffer[10];
@endcode
*/
#define TUSB_CFG_ATTR_USBRAM
#define TUSB_CFG_MCU ///< Select one of the supported MCU, the value must be from \ref group_mcu
#define TUSB_CFG_OS ///< Select one of the supported RTOS, the value must be from \ref group_supported_os.
#define TUSB_CFG_OS_TASK_PRIO ///< If \ref TUSB_CFG_OS is configured to use a real RTOS (other than TUSB_OS_NONE). This determines the priority of the usb stack task.
#define TUSB_CFG_TICKS_HZ ///< The rate ticks in hert. This is used in conjunction with \ref tusb_tick_get to calculate timing.
//--------------------------------------------------------------------+
// HOST CONFIGURATION
//--------------------------------------------------------------------+
/** \defgroup TUSB_CFG_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 TUSB_CFG_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 TUSB_CFG_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 TUSB_CFG_HOST_HUB ///< Enable Hub Class
#define TUSB_CFG_HOST_HID_KEYBOARD ///< Enable HID Class for Keyboard
#define TUSB_CFG_HOST_HID_MOUSE ///< Enable HID Class for Mouse
#define TUSB_CFG_HOST_HID_GENERIC ///< Enable HID Class for Generic (not supported yet)
#define TUSB_CFG_HOST_MSC ///< Enable Mass Storage Class (SCSI subclass only)
#define TUSB_CFG_HOST_CDC ///< Enable Virtual Serial (Communication Device Class)
/** @} */
/** @} */ // group Host
//--------------------------------------------------------------------+
// DEVICE CONFIGURATION
//--------------------------------------------------------------------+
/** \defgroup TUSB_CFG_DEVICE Device Options
* @{ */
#define TUSB_CFG_DEVICE_CONTROL_ENDOINT_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 ...
tusbd_descriptor_pointer_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 TUSB_CFG_DEVICE_HID_KEYBOARD ///< Enable HID Class for Keyboard
#define TUSB_CFG_DEVICE_HID_MOUSE ///< Enable HID Class for Mouse
#define TUSB_CFG_DEVICE_HID_GENERIC ///< Enable HID Class for Generic (not supported yet)
#define TUSB_CFG_DEVICE_MSC ///< Enable Mass Storage Class (SCSI subclass only)
#define TUSB_CFG_DEVICE_CDC ///< Enable Virtual Serial (Communication Device Class)
/** @} */
/** @} */ // group Device
/** @} */

95
doxygen/get_started.md Normal file
View File

@@ -0,0 +1,95 @@
# Get Started #
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**
- [Download](#download)
- [Import and Build](#import-and-build)
- [Prerequisites](#prerequisites)
- [LPCXpresso](#lpcxpresso)
- [Keil](#keil)
- [IAR](#iar)
- [Configure demo](#configure-demo)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## 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
----- | -------------
boards | Source files of supported boards
demos | Source & project files for demonstration application
mcu | Low level mcu core & peripheral drivers (e.g CMSIS )
tests | Unit tests for the stack
tinyusb | All sources files for tinyusb stack itself.
vendor | Source files from 3rd party such as freeRTOS, fatfs etc ...
## Import and Build ##
*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 ###
In order to build and run application demo, you would need
- A [supported development board](../../boards/readme.md)
- A supported toolchain: LPCXpresso, Keil, IAR.
### LPCXpresso ###
To prevent any sort of problems, it is recommended to do **EXACTLY** as follows (esp the item 4)
1. Copy the whole repo folder to your lpcxpresso's workspace.
2. Click *File->Import*, then expand the *General* folder and select **Existing Projects into Workspace** and click Next.
![lpcxpresso_import.png](http://docs.tinyusb.org/images/lpcxpresso_import.png)
3. On the next dialog, Click *Browse* and choose the **repo/demos** folder inside the repo. You should see a list of all demo applications.
![lpcxpresso_import2.png](http://docs.tinyusb.org/images/lpcxpresso_import2.png)
4. **IMPORTANT** make sure the option **Copy projects into workspace** is **CLEAR**. As demo application uses link folders and this option may cause problem for the import.
5. Choose any of the demo application and click *Finish*.
6. Select the configure corresponding to your development board.
![lpcxpresso_select_board.png](http://docs.tinyusb.org/images/lpcxpresso_select_board.png)
7. Then select the correct MCU option from project properties then you are ready to go.
![lpcxpresso_mcu.png](http://docs.tinyusb.org/images/lpcxpresso_mcu.png)
### Keil ###
It is relatively simple for Keil
1. Open the desired demo project e.g *demos/host/host_freertos/host_freertos.uvproj*
2. Select the configure corresponding to your development board and build it.
![keil_select_board.png](http://docs.tinyusb.org/images/keil_select_board.png)
### IAR ###
IAR is just as easy as Keil
1. Open the desired demo project e.g *demos/host/host_freertos/host_freertos.eww*
2. Again select the configure corresponding to your development board and build it.
![iar_select_board.png](http://docs.tinyusb.org/images/iar_select_board.png)
## Configure demo ##
Application demo is written to have the code excluded if its required option is not enabled in [tusb_config.h](). Some of combination may exceed the 32KB limit of IAR/Keil so you may want to re-configure to disable some class support, decrease TUSB_CFG_DEBUG or increase the compiler optimization level.
In addition, there are some configuration you can change such as
- CFG_UART_BAUDRATE in board.h
- CFG_PRINTF_TARGET in the specific board header (e.g board_ea4357.h) to either Semihost, Uart, or SWO.
\subpage md_boards_readme

22
doxygen/group_def.txt Normal file
View File

@@ -0,0 +1,22 @@
// 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