Update info

BUILD.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-You have two options to get a working compilation environment for HydraUSB3 : the Docker way or the native way.
+You have two options to get a working compilation environment for Hydradancer : the Docker way or the native way.
 
 
 ### The Docker way (Linux/Windows)
@@ -28,9 +28,9 @@ from the command line. Then go back to the top folder and execute
 docker run --mount type=bind,source=.,target=/home/user/mounted -it hydradancer_compile
 ```
 
-The working directory will be the current folder, so you have to be in the top folder.
+The working directory will be the current folder, so you have to be in the folder you want to be mounted inside your Docker instance (for example, the top folder of Hydradancer).
 
-from the folder you want to be mounted inside your Docker instance (for example, the top folder of wch-ch56x-lib). The two scripts `tools/Docker/build.sh` and `tools/Docker/run.sh` respectively will run the same commands on Linux.
+The two scripts `tools/Docker/build.sh` and `tools/Docker/run.sh` respectively will run the same commands on Linux.
 
 ### Native way (Linux only)
 
@@ -49,18 +49,18 @@ To use it, add it to your path.
 export PATH="$PATH:$(pwd)/xpack-riscv-none-elf-gcc-12.2.0-1/bin"
 ```
 
-## Test firmwares compilation
+## Firmware compilation
 
 1. Clone the project with all its submodules
 
 ```shell
-git clone --recurse-submodules https://github.com/hydrausb3/wch-ch56x-lib
+git clone --recurse-submodules https://github.com/hydrausb3/HydraDancer.git
 ```
 
 2. From the top folder, execute
 
 ```shell
-cmake --toolchain ../cmake/wch-ch56x-toolchain.cmake -DCMAKE_BUILD_TYPE=release -DBUILD_TESTS=1 -DBUILD_TOOLS=1 -B build .
+cmake --toolchain ../cmake/wch-ch56x-toolchain.cmake -DCMAKE_BUILD_TYPE=release -B build .
 ```
 
 Then
@@ -75,24 +75,26 @@ And finally
 cmake --install build/
 ```
 
-3. You should find the compilation artefacts in `out/`
+3. You should find the different test firmwares in `out/`.
 
-# Configuring the HydraUSB3 boards and flashing the firmware
+# Configuring the boards and flashing the firmware(s)
 
-## Physical configuration
+## Physical configuration of the dual-HydraUSB3 configuration
 
-Currently, you need two HydraUSB3 boards connected together via HSPI and SerDes.
+Currently, you need two HydraUSB3 boards connected together via HSPI. You just need to plug the boards together.
 
 - Optional : Add a jumper on PB24 on the top board (might be used by the firmware to determine if it is top or bottom board)
 
 ## Permissions
 
-To be able to access the HydraUSB3 boards and flash them, root privileges may be required, or you can provide them to your regular user, e.g. with the creation of a file `/etc/udev/rules.d/99-hydrausb3.rules` with
+To be able to access the HydraDancer boards and flash them, root privileges may be required, or you can provide them to your regular user, e.g. with the creation of a file `/etc/udev/rules.d/99-hydrausb3.rules` with
+
 ```
 # UDEV Rules for HydraUSB3 boards, https://github.com/hydrausb3
 # WinChipHead CH569W Bootloader
 SUBSYSTEMS=="usb", ATTRS{idVendor}=="4348", ATTRS{idProduct}=="55e0", MODE="0664", GROUP="plugdev"
 ```
+
 and having your user as member of the group `plugdev`.
 
 
@@ -102,7 +104,7 @@ and having your user as member of the group `plugdev`.
 
 Clone https://github.com/hydrausb3/wch-ch56x-isp and follow the instructions.
 
-### Flashing
+### Flashing for the dual-HydraUSB3 configuration
 
 Set top board in Flash Mode.
 With a jumper on P3:
@@ -119,14 +121,78 @@ Or with a button or momentary short on P3:
 Warning! You have 10 seconds to flash the board! Note: root privileges may be required, see above.
 
 ```shell
-wch-ch56x-isp -vf flash out/x/board1.bin
+wch-ch56x-isp -vf out/testfolder/firmware.bin
 ```
 
 Press & release reset button of the top board again to leave Flash Mode. If you used a jumper, don't forget to remove it before resetting the board!
 
 Repeat the same procedure with the bottom board but press the bottom board reset button and flash the proper firmware.
 
 ```shell
-wch-ch56x-isp -vf flash out/x/board2.bin
+wch-ch56x-isp -vf out/testfolder/firmware.bin
+```
+
+### Flashing for the Hydradancer dongle
+
+Set the board in Flash Mode.
+With a jumper on P3:
+
+* Put a jumper on the board
+* Press & release reset button of the top board
+
+Or with a button or momentary short on P3:
+
+* Press Flash mode button
+* Press & release reset button
+* Release Flash mode button
+
+Warning! You have 10 seconds to flash the board! Note: root privileges may be required, see above.
+
+```shell
+wch-ch56x-isp -vf out/testfolder/firmware.bin
+```
+
+Press & release reset button of the board again to leave Flash Mode. If you used a jumper, don't forget to remove it before resetting the board!
+
+# More details on compilation
+
+This project uses boards based on the WCH569 RISCV MCU. More documentation can be found on the [HydraUSB3 organization](https://github.com/hydrausb3/).
+
+## Build options
+
+Those options can be set the following way
+
+```shell
+cmake --toolchain ../cmake/wch-ch56x-toolchain.cmake -DCMAKE_BUILD_TYPE=release -DOPTION_1=1 -DOPTION_2=1 -B build .
 ```
 
+- `-DCMAKE_BUILD_TYPE=Debug` use debug optimization
+- `-DBUILD_TESTS=1` build the tests
+
+Most warnings will be considered as errors.
+
+## More options
+
+You can set different options to activate more flags, static analysis or the logging system.
+
+Those flags can either be set as build options (but they will apply to all projects) by passing a `-DOPTION=value` to CMake, or by adding a `set(option_name value)` in the project `CMakeLists.txt`.
+
+- `STATIC_ANALYSIS` : activate GCC's built-in static analysers
+- `EXTRACFLAGS` : activate -Wconversion and -Wsign-compare
+
+## Logging options
+
+Several logging options can get you infos on different parts of the library/firmwares. By default, no logs are activated so there is no impact on performances.
+
+Some logging filters might activate too much logs for the USB controllers to work properly, a balance has to be found between logging more information and keeping the board working.
+
+In this case, the `LOG` macro will bypass all filters and levels, allowing you to log just what you need.
+
+- Log methods
+    - `LOG_OUTPUT=printf`. Logs are written directly to the UART
+    - `LOG_OUTPUT=buffer`. Logs are stored in a buffer, and flushed to the UART when calling `LOG_DUMP()`
+    - `LOG_OUTPUT=serdes`. Logs are directly sent using Serdes. Might be used to share logs from one board to the other. Not very well tested.
+- Log levels
+    - `LOG_OUTPUT=x LOG_LEVEL=y`. With y=1(LOG_LEVEL_CRITICAL), y=2(LOG_LEVEL_ERROR), y=3(LOG_LEVEL_WARNING), y=4(LOG_LEVEL_INFO), y=5(LOG_LEVEL_DEBUG). All levels <=y will be displayed.
+- Log filters
+    - `LOG_OUTPUT=x LOG_FILTER_IDS=a,b,c, ...` You can set any number of filters from the following list 1(LOG_ID_USER), 2(LOG_ID_USB2), 3(LOG_ID_USB3), 4(LOG_ID_HSPI), 5(LOG_ID_SERDES), 6(LOG_ID_INTERRUPT_QUEUE), 7(LOG_ID_RAMX_ALLOC). If `LOG_LEVEL` is also defined, the logs with IDs will only be displayed if they have the right level.

README.md

@@ -10,8 +10,6 @@ This library provides USB3, USB2, HSPI and SerDes drivers that have been tested
 
 In a CMake-based project, simply use `add_subdirectory(path_to_wch-ch56x-lib)` and link to the `wch-ch56x-lib` target. `wch-ch56x-lib` is currently an INTERFACE target, meaning the source/header files will be compiled with your target, not independently.
 
-This allows configuring the library options separately for each project, for use in different firmwares. Those options are C macros and thus are fixed at compile time.
-
 Available options
 
 * LOG_LEVEL