docs clean up
This commit is contained in:
hathach
parent
10021eda67
commit
455da57f9d
|
|
@ -1 +0,0 @@
|
|||
# Change Log
|
||||
|
|
@ -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 ...
|
||||
|
|
@ -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
|
||||
|
||||
/** @} */
|
||||
|
|
@ -1,32 +1,12 @@
|
|||
# Getting 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**
|
||||
## Get
|
||||
|
||||
- [Download](#download)
|
||||
- [Add tinyusb to your project](#add-tinyusb-to-your-project)
|
||||
|
||||
<!-- 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
|
||||
----- | -------------
|
||||
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"
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
@ -1,58 +0,0 @@
|
|||
<!-- HTML header for doxygen 1.8.6-->
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
||||
<meta name="generator" content="Doxygen $doxygenversion"/>
|
||||
<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
|
||||
<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
|
||||
<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
|
||||
<script type="text/javascript" src="$relpath^jquery.js"></script>
|
||||
<script type="text/javascript" src="$relpath^dynsections.js"></script>
|
||||
$treeview
|
||||
$search
|
||||
$mathjax
|
||||
<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
|
||||
$extrastylesheet
|
||||
</head>
|
||||
<body>
|
||||
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
||||
|
||||
<!--BEGIN TITLEAREA-->
|
||||
<div id="titlearea">
|
||||
<table width="100%" cellspacing="0" cellpadding="0">
|
||||
<tbody>
|
||||
<tr style="height: 56px;">
|
||||
<!--BEGIN PROJECT_LOGO-->
|
||||
<td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"/></td>
|
||||
<!--END PROJECT_LOGO-->
|
||||
<!--BEGIN PROJECT_NAME-->
|
||||
<td style="padding-left: 0.5em;">
|
||||
<div id="projectname">$projectname
|
||||
<!--BEGIN PROJECT_NUMBER--> <span id="projectnumber">$projectnumber</span><!--END PROJECT_NUMBER-->
|
||||
</div>
|
||||
<!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
|
||||
</td>
|
||||
<td align="right">
|
||||
<a href="https://pledgie.com/campaigns/24694"><img border="0" src="https://pledgie.com/campaigns/24694.png?skin_name=chrome" alt="Click here to lend your support to tinyusb donation and make a donation at pledgie.com"></a>
|
||||
</td>
|
||||
<!--END PROJECT_NAME-->
|
||||
<!--BEGIN !PROJECT_NAME-->
|
||||
<!--BEGIN PROJECT_BRIEF-->
|
||||
<td style="padding-left: 0.5em;">
|
||||
<div id="projectbrief">$projectbrief</div>
|
||||
</td>
|
||||
<!--END PROJECT_BRIEF-->
|
||||
<!--END !PROJECT_NAME-->
|
||||
<!--BEGIN DISABLE_INDEX-->
|
||||
<!--BEGIN SEARCHENGINE-->
|
||||
<td>$searchbox</td>
|
||||
<!--END SEARCHENGINE-->
|
||||
<!--END DISABLE_INDEX-->
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
<!--END TITLEAREA-->
|
||||
<!-- end header part -->
|
||||
|
|
@ -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)
|
||||
Loading…
Reference in New Issue