Merge branch 'master' into refactor-irqhandler

docs/boards.md

@@ -9,6 +9,10 @@ The board support code is only used for self-contained examples and testing. It
 
 This code base already had supported for a handful of following boards (sorted alphabetically)
 
+### Espressif ESP32-S2
+
+- [ESP32-S2-Saola-1](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/hw-reference/esp32s2/user-guide-saola-1-v1.2.html)
+
 ### MicroChip SAMD
 
 - [Adafruit Circuit Playground Express](https://www.adafruit.com/product/3333)

docs/getting_started.md

@@ -17,11 +17,11 @@ 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 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.
+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 boards).
+5. If you use the device stack, make sure you have created/modified usb descriptors for your own need. Ultimately you need to implement all **tud_descriptor_** callbacks 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 tud_task()/tuh_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. All of the callbacks and functionality are handled and invoke within the call of that task runner.
 
 ~~~{.c}
 int main(void)

docs/porting.md

@@ -6,7 +6,7 @@ data transactions on different endpoints. Porting is the process of adding low-l
 the rest of the common stack. Once the low-level is implemented, it is very easy to add USB support
 for the microcontroller to other projects, especially those already using TinyUSB such as CircuitPython.
 
-Below are instructions on how to get the cdc_msc_hid device example running on a new microcontroller. Doing so includes adding the common code necessary for other uses while minimizing other extra code. Whenever you see a phrase or word in <> it should be replaced.
+Below are instructions on how to get the cdc_msc device example running on a new microcontroller. Doing so includes adding the common code necessary for other uses while minimizing other extra code. Whenever you see a phrase or word in <> it should be replaced.
 
 ## Register defs
 
@@ -19,7 +19,7 @@ Once this is done, create a directory in `hw/bsp/<your board name>` for the spec
 ## Build
 Now that those directories are in place, we can start our iteration process to get the example building successfully. To build, run from the root of TinyUSB:
 
-`make -C examples/device/cdc_msc_hid BOARD=<board>`
+`make -C examples/device/cdc_msc BOARD=<board>`
 
 Unless, you've read ahead, this will fail miserably. Now, lets get it to fail less by updating the files in the board directory. The code in the board's directory is responsible for setting up the microcontroller's clocks and pins so that USB works. TinyUSB itself only operates on the USB peripheral. The board directory also includes information what files are needed to build the example.
 
@@ -62,6 +62,7 @@ All of the code for the low-level device API is in `src/portable/<vendor>/<chip
 ##### dcd_init
 
 Initializes the USB peripheral for device mode and enables it.
+This function should leave an internal D+/D- pull-up in its default power-on state. `dcd_connect` will be called by the USBD core following `dcd_init`.
 
 ##### dcd_int_enable / dcd_int_disable
 
@@ -85,6 +86,10 @@ Called when the device received SET_CONFIG request, you can leave this empty if
 
 Called to remote wake up host when suspended (e.g hid keyboard)
 
+##### dcd_connect / dcd_disconnect
+
+Connect or disconnect the data-line pull-up resistor. Define only if MCU has an internal pull-up. (BSP may define for MCU without internal pull-up.)
+
 #### Special events
 
 You must let TinyUSB know when certain events occur so that it can continue its work. There are a few methods you can call to queue events for TinyUSB to process.