Merge pull request #365 from Dzarda7/chore/fix_msc_terminology

Fix MSC terminology and add Markdown formatter (IEC-469)

Author: tore-espressif

.github/PULL_REQUEST_TEMPLATE/new_component.md

@@ -10,4 +10,5 @@
 - [ ] CI passing
 
 # Change description
+
 _Please describe your change here_

.github/PULL_REQUEST_TEMPLATE/update_component.md

@@ -6,4 +6,5 @@
 - [ ] CI passing
 
 # Change description
+
 _Please describe your change here_

.pre-commit-config.yaml

@@ -31,19 +31,29 @@ repos:
         exclude: '.*\.uxf'
     -   id: check-yaml
 
-- repo: https://github.com/espressif/esp-idf-kconfig.git
-  rev: v2.5.0
-  hooks:
-    - id: check-kconfig-files
-    - id: check-deprecated-kconfig-options
+-   repo: https://github.com/espressif/esp-idf-kconfig.git
+    rev: v2.5.0
+    hooks:
+    -   id: check-kconfig-files
+    -   id: check-deprecated-kconfig-options
 
-- repo: local
-  hooks:
-      - id: cmake-lint
+-   repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.22
+    hooks:
+    -   id: mdformat
+        exclude: 'CHANGELOG\.md$'
+        args: [--number]
+        additional_dependencies:
+        -   mdformat-gfm  # GitHub Flavored Markdown support
+        -   mdformat-ruff  # Python code block formatting
+
+-   repo: local
+    hooks:
+    -   id: cmake-lint
         name: Check CMake Files Format
         entry: cmakelint --linelength=120 --spaces=4 --filter=-whitespace/indent
         language: python
         additional_dependencies:
-          - cmakelint==1.4.1
+        -   cmakelint==1.4.1
         files: 'CMakeLists.txt$|\.cmake$'
         exclude: '\/third_party\/'

README.md

@@ -1,13 +1,11 @@
-[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
-[![Build and Run Test Application](https://github.com/espressif/esp-usb/actions/workflows/build_and_run_test_app_usb.yml/badge.svg?branch=master)](https://github.com/espressif/esp-usb/actions/workflows/build_and_run_test_app_usb.yml)
-[![Clang-Tidy](https://github.com/espressif/esp-usb/actions/workflows/clang-tidy.yml/badge.svg?branch=master)](https://github.com/espressif/esp-usb/security/code-scanning?query=is%3Aopen+branch%3Amaster)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit) [![Build and Run Test Application](https://github.com/espressif/esp-usb/actions/workflows/build_and_run_test_app_usb.yml/badge.svg?branch=master)](https://github.com/espressif/esp-usb/actions/workflows/build_and_run_test_app_usb.yml) [![Clang-Tidy](https://github.com/espressif/esp-usb/actions/workflows/clang-tidy.yml/badge.svg?branch=master)](https://github.com/espressif/esp-usb/security/code-scanning?query=is%3Aopen+branch%3Amaster)
 
 # Espressif ESP-USB
 
-This repository aims to store [ESP-IDF](https://github.com/espressif/esp-idf) USB host and device class drivers
-which have been separated and uploaded into [IDF Component Manager](https://components.espressif.com/).
+This repository aims to store [ESP-IDF](https://github.com/espressif/esp-idf) USB host and device class drivers which have been separated and uploaded into [IDF Component Manager](https://components.espressif.com/).
 
 ## Important note
+
 This repository is used only for Espressif components, it is not mean to store third party components.
 
 ## Resources

device/esp_tinyusb/Kconfig

@@ -88,7 +88,7 @@ menu "TinyUSB Stack"
                 Name of the MSC device.
     endmenu # "Descriptor configuration"
 
-    menu "Massive Storage Class (MSC)"
+    menu "Mass Storage Class (MSC)"
         config TINYUSB_MSC_ENABLED
             bool "Enable TinyUSB MSC feature"
             default n
@@ -111,7 +111,7 @@ menu "TinyUSB Stack"
             default "/data"
             help
                 MSC Mount Path of storage.
-    endmenu # "Massive Storage Class"
+    endmenu # "Mass Storage Class"
 
     menu "Communication Device Class (CDC)"
         config TINYUSB_CDC_ENABLED

device/esp_tinyusb/README.md

@@ -42,13 +42,14 @@ Configure the Device Stack using `menuconfig`:
 
 This component is distributed via [IDF component manager](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html). Just add `idf_component.yml` file to your main component with the following content:
 
-``` yaml
+```yaml
 ## IDF Component Manager Manifest File
 dependencies:
   esp_tinyusb: "~2.0.0"
 ```
 
 Or simply run:
+
 ```
 idf.py add-dependency esp_tinyusb~2.0.0
 ```
@@ -187,8 +188,7 @@ Configure USB descriptors using the `tinyusb_config_t` structure:
 - `descriptor.high_speed_config`
 - `descriptor.qualifier`
 
-If any descriptor field is set to `NULL`, default descriptor will be assigned during installation.
-Values of default descriptors could be configured via `menuconfig`.
+If any descriptor field is set to `NULL`, default descriptor will be assigned during installation. Values of default descriptors could be configured via `menuconfig`.
 
 ```c
   #include "tinyusb_default_config.h"
@@ -226,6 +226,7 @@ For self-powered devices, monitoring the VBUS voltage is required. To do this:
     tinyusb_driver_install(&tusb_cfg);
   }
 ```
+
 If external PHY is used:
 
 ```c
@@ -369,10 +370,10 @@ void main(void)
 }
 ```
 
-
 **Storage callback**
 
 Storage event callback is called, when one of the following events occurred:
+
 - `TINYUSB_MSC_EVENT_MOUNT_START`: Start mount from APP to USB or from USB to APP
 - `TINYUSB_MSC_EVENT_MOUNT_COMPLETE`: Complete mount from USB to APP or from APP to USB
 - `TINYUSB_MSC_EVENT_FORMAT_REQUIRED`: Filesystem not found, format needed
@@ -437,26 +438,27 @@ void main(void)
 **Performance Table (ESP32-S3):**
 
 | FIFO Size | Read Speed | Write Speed |
-|-----------|------------|-------------|
+| --------- | ---------- | ----------- |
 | 512 B     | 0.566 MB/s | 0.236 MB/s  |
 | 8192 B    | 0.925 MB/s | 0.928 MB/s  |
 
 **Performance Table (ESP32-P4):**
 
 | FIFO Size | Read Speed | Write Speed |
-|-----------|------------|-------------|
+| --------- | ---------- | ----------- |
 | 512 B     | 1.174 MB/s | 0.238 MB/s  |
 | 8192 B    | 4.744 MB/s | 2.157 MB/s  |
 | 32768 B   | 5.998 MB/s | 4.485 MB/s  |
 
 **Performance Table (ESP32-S2, SPI Flash):**
 
 | FIFO Size | Write Speed |
-|-----------|-------------|
+| --------- | ----------- |
 | 512 B     | 5.59 KB/s   |
 | 8192 B    | 21.54 KB/s  |
 
 **Note:** Internal SPI flash is for demonstration only; use SD cards or external flash for higher performance.
 
 ## Examples
+
 You can find examples in [ESP-IDF on GitHub](https://github.com/espressif/esp-idf/tree/master/examples/peripherals/usb/device).

device/esp_tinyusb/test_apps/README.md

@@ -1,11 +1,9 @@
 # CI target runner setup
 
-To allow a Docker container, running on a CI target runner, to access USB devices connected to the CI target runner, some modifications must be made.
-In our case, it's an `RPI` target runner.
+To allow a Docker container, running on a CI target runner, to access USB devices connected to the CI target runner, some modifications must be made. In our case, it's an `RPI` target runner.
 
 The main idea comes from this response on [stackoverflow](https://stackoverflow.com/a/66427245/19840830). The same approach is also recommended in the official Docker [documentation](https://docs.docker.com/reference/cli/docker/container/run/#device-cgroup-rule)
 
-
 ### Following changes shall be made on a CI target runner
 
 - [`UDEV rules`](#udev-rules)
@@ -21,7 +19,7 @@ The main idea comes from this response on [stackoverflow](https://stackoverflow.
 - Location: `/etc/udev/rules.d/99-docker-tty.rules`
 - `99-docker-tty.rules` file content:
 
-``` sh
+```sh
 ACTION=="add", SUBSYSTEM=="tty", RUN+="/usr/local/bin/docker_tty.sh 'added' '%E{DEVNAME}' '%M' '%m'"
 ACTION=="remove", SUBSYSTEM=="tty", RUN+="/usr/local/bin/docker_tty.sh 'removed' '%E{DEVNAME}' '%M' '%m'"
 ```
@@ -32,7 +30,7 @@ ACTION=="remove", SUBSYSTEM=="tty", RUN+="/usr/local/bin/docker_tty.sh 'removed'
 - Location: `/usr/local/bin/docker_tty.sh`
 - `docker_tty.sh` file content:
 
-``` sh
+```sh
 #!/usr/bin/env bash
 
 # Log the USB event with parameters
@@ -59,7 +57,8 @@ fi
 ### Making the script executable
 
 Don't forget to make the created script executable:
-``` sh
+
+```sh
 root@~$ chmod +x /usr/local/bin/docker_tty.sh
 ```
 
@@ -82,17 +81,18 @@ USB event: removed /dev/ttyACM1 166 1
 
 ### Check Major and Minor numbers of connected devices
 
-Check the Major and Minor numbers assigned by the Linux kernel to devices that you want the Docker container to access.
-In our case, we want to access `/dev/ttyUSB0`, `/dev/ttyACM0` and `/dev/ttyACM1`
+Check the Major and Minor numbers assigned by the Linux kernel to devices that you want the Docker container to access. In our case, we want to access `/dev/ttyUSB0`, `/dev/ttyACM0` and `/dev/ttyACM1`
 
 `/dev/ttyUSB0`: Major 188, Minor 0
-``` sh
+
+```sh
 peter@BrnoRPIG007:~ $ ls -l /dev/ttyUSB0
 crw-rw-rw- 1 root dialout 188, 0 Nov 12 11:08 /dev/ttyUSB0
 ```
 
 `/dev/ttyACM0` and `/dev/ttyACM1`: Major 166, Minor 0 (1)
-``` sh
+
+```sh
 peter@BrnoRPIG007:~ $ ls -l /dev/ttyACM0
 crw-rw---- 1 root dialout 166, 0 Nov 13 10:26 /dev/ttyACM0
 peter@BrnoRPIG007:~ $ ls -l /dev/ttyACM1
@@ -102,17 +102,19 @@ crw-rw---- 1 root dialout 166, 1 Nov 13 10:26 /dev/ttyACM1
 ### Run a docker container
 
 Run a Docker container with the following extra options:
-``` sh
+
+```sh
 docker run --device-cgroup-rule='c 188:* rmw' --device-cgroup-rule='c 166:* rmw' --privileged ..
 ```
+
 - `--device-cgroup-rule='c 188:* rmw'`: allow access to `ttyUSBx` (Major 188, all Minors)
 - `--device-cgroup-rule='c 166:* rmw'`: allow access to `ttyACMx` (Major 166, all Minors)
 
 ## GitHub CI target runner setup
 
 To apply these changes to a GitHub target runner a `.yml` file used to run a Docker container for pytest must be modified. The Docker container is then run with the following options:
 
-``` yaml
+```yaml
 container:
   image: python:3.11-bookworm
   options: --privileged --device-cgroup-rule="c 188:* rmw" --device-cgroup-rule="c 166:* rmw"
@@ -124,7 +126,7 @@ To apply these changes to a GitLab runner the `config.toml` file located at `/et
 
 According to GitLab's [documentation](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnersdocker-section) the `[runners.docker]` section of the `config.toml` file should include the `device_cgroup_rules` parameter:
 
-``` toml
+```toml
 [runners.docker]
   ...
   device_cgroup_rules = ["c 188:* rmw", "c 166:* rmw"]