Merge branch 'master' into pr/2181

1 files changed, 42 insertions, 15 deletions

diff --git a/docs/reference/getting_started.rst b/docs/reference/getting_started.rst
index 1f41cb888..3db3fa206 100644
--- a/docs/reference/getting_started.rst
+++ b/docs/reference/getting_started.rst
@@ -5,8 +5,7 @@ Getting Started
 Add TinyUSB to your project
 ---------------------------
 
-It is relatively simple to incorporate tinyusb to your (existing) project
-
+It is relatively simple to incorporate tinyusb to your project
 
 * Copy or ``git submodule`` this repo into your project in a subfolder. Let's say it is *your_project/tinyusb*
 * Add all the .c in the ``tinyusb/src`` folder to your project
@@ -46,28 +45,41 @@ For your convenience, TinyUSB contains a handful of examples for both host and d
 
 Some ports will also require a port-specific SDK (e.g. RP2040) or binary (e.g. Sony Spresense) to build examples. They are out of scope for tinyusb, you should download/install it first according to its manufacturer guide.
 
-Build
-^^^^^
+Dependencies
+^^^^^^^^^^^^
 
-To build example, first change directory to an example folder.
+The hardware code is located in ``hw/bsp`` folder, and is organized by family/boards. e.g raspberry_pi_pico is located in ``hw/bsp/rp2040/boards/raspberry_pi_pico`` where FAMILY=rp2040 and BOARD=raspberry_pi_pico. Before building, we firstly need to download dependencies such as: MCU low-level peripheral driver and external libraries e.g FreeRTOS (required by some examples). We can do that by either ways:
+
+1. Run ``tools/get_deps.py {FAMILY}`` script to download all dependencies for a family as follow. Note: For TinyUSB developer to download all dependencies, use FAMILY=all.
 
 .. code-block::
 
-   $ cd examples/device/cdc_msc
+   $ python tools/get_deps.py rp2040
 
-Before building, we firstly need to download dependencies such as: MCU low-level peripheral driver and external libraries e.g FreeRTOS (required by some examples). Run the ``get-deps`` target in one of the example folder as follow. You only need to do this once per mcu. Check out `complete list of dependencies and their designated path here <dependencies.rst>`_
+2. Or run the ``get-deps`` target in one of the example folder as follow.
 
 .. code-block::
 
+   $ cd examples/device/cdc_msc
    $ make BOARD=raspberry_pi_pico get-deps
 
-Then compile with ``make BOARD=[board_name] all``\ , for example
+You only need to do this once per family. Check out `complete list of dependencies and their designated path here <dependencies.rst>`_
+
+Build
+^^^^^
+
+To build example, first change directory to an example folder.
+
+.. code-block::
+
+   $ cd examples/device/cdc_msc
+
+Then compile with ``make BOARD={board_name} all`` , for example
 
 .. code-block::
 
    $ make BOARD=raspberry_pi_pico all
 
-Note: ``BOARD`` can be found as directory name in ``hw/bsp``\ , either in its family/boards or directly under bsp (no family).
 Note: some examples especially those that uses Vendor class (e.g webUSB) may requires udev permission on Linux (and/or macOS) to access usb device. It depends on your OS distro, typically copy ``99-tinyusb.rules`` and reload your udev is good to go
 
 .. code-block::
@@ -75,8 +87,8 @@ Note: some examples especially those that uses Vendor class (e.g webUSB) may req
    $ cp examples/device/99-tinyusb.rules /etc/udev/rules.d/
    $ sudo udevadm control --reload-rules && sudo udevadm trigger
 
-Port Selection
-~~~~~~~~~~~~~~
+RootHub Port Selection
+~~~~~~~~~~~~~~~~~~~~~~
 
 If a board has several ports, one port is chosen by default in the individual board.mk file. Use option ``PORT=x`` To choose another port. For example to select the HS port of a STM32F746Disco board, use:
 
@@ -166,7 +178,10 @@ Some board use uf2 bootloader for drag & drop in to mass storage device, uf2 can
    $ make BOARD=feather_nrf52840_express all uf2
 
 IAR Support
-^^^^^^^^^^^
+-----------
+
+Use project connection
+^^^^^^^^^^^^^^^^^^^^^^
 
 IAR Project Connection files are provided to import TinyUSB stack into your project.
 
@@ -179,19 +194,19 @@ IAR Project Connection files are provided to import TinyUSB stack into your proj
 
     - `STM32L0xx_HAL_Driver` is only needed to run examples, TinyUSB stack itself doesn't rely on MCU's SDKs.
 
-* Open `Tools -> Configure Custom Argument Variables` (Switch to `Global` tab if you want to do it for all your projects)
+* Open ``Tools -> Configure Custom Argument Variables`` (Switch to `Global` tab if you want to do it for all your projects)
    Click `New Group ...`, name it to `TUSB`, Click `Add Variable ...`, name it to `TUSB_DIR`, change it's value to the path of your TinyUSB stack,
    for example `C:\\tinyusb`
 
 Import stack only
 ~~~~~~~~~~~~~~~~~
 
-1. Open `Project -> Add project Connection ...`, click `OK`, choose `tinyusb\\tools\\iar_template.ipcf`.
+1. Open ``Project -> Add project Connection ...``, click `OK`, choose `tinyusb\\tools\\iar_template.ipcf`.
 
 Run examples
 ~~~~~~~~~~~~
 
-1. (Python3 is needed) Run `iar_gen.py` to generate .ipcf files of examples:
+1. (Python3 is needed) Run ``iar_gen.py`` to generate .ipcf files of examples:
 
    .. code-block::
 
@@ -200,3 +215,15 @@ Run examples
 
 2. Open `Project -> Add project Connection ...`, click `OK`, choose `tinyusb\\examples\\(.ipcf of example)`.
    For example `C:\\tinyusb\\examples\\device\\cdc_msc\\iar_cdc_msc.ipcf`
+
+Native CMake support (9.50.1+)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+With 9.50.1 release, IAR added experimental native CMake support (strangely not mentioned in public release note). Now it's possible to import CMakeLists.txt then build and debug as a normal project.
+
+Following these steps:
+
+1. Add IAR compiler binary path to system ``PATH`` environment variable, such as ``C:\Program Files\IAR Systems\Embedded Workbench 9.2\arm\bin``.
+2. Create new project in IAR, in Tool chain dropdown menu, choose CMake for Arm then Import ``CMakeLists.txt`` from chosen example directory.
+3. Set up board option in ``Option - CMake/CMSIS-TOOLBOX - CMake``, for example :code:`-DBOARD=stm32f439nucleo -DTOOLCHAIN=iar`, **Uncheck 'Override tools in env'**.
+4. (For debug only) Choose correct CPU model in ``Option - General Options - Target``, to profit register and memory view.