chore(docs): enhance libraries structure

Signed-off-by: Frederic Pillon <frederic.pillon@st.com>

Author: fpistm

docs/API.md

@@ -369,268 +369,6 @@ parity bit is also inverted.
 See the [HardwareTimer library reference](HardwareTimer-library.md) for the timer API and STM32-specific timer features.
 
 
-## Built-in libraries
-
-This part describes the STM32 libraries provided with the core.
-
-### SPI
-
-STM32 SPI library has been modified with the possibility to manage hardware CS pin linked to the SPI peripheral.
-This section documents STM32-specific additions to the [standard SPI API](https://docs.arduino.cc/language-reference/en/functions/communication/SPI/).
-
-There are two ways to manage the CS pin:
-
-- the CS pin is managed directly by the user code before to transfer the data (like the Arduino SPI library)
-- the user uses a hardware CS pin linked to the SPI peripheral
-
-#### New SPISetting parameter
-
-* `noReceive`: value can be `SPI_TRANSMITRECEIVE` or `SPI_TRANSMITONLY`. It allows to skip receive data after transmitting.
-
-#### New API functions
-
-* `SPIClass::SPIClass(uint8_t mosi, uint8_t miso, uint8_t sclk, uint8_t ssel)`: alternative class constructor
-_Params_ SPI `mosi` pin
-_Params_ SPI `miso` pin
-_Params_ SPI `sclk` pin
-_Params_ (optional) SPI `ssel` pin. This pin must be an hardware CS pin. If you configure this pin, the chip select will be managed by the SPI peripheral.
-
-###### Example
-
-This is an example of the use of the hardware CS pin linked to the SPI peripheral:
-
-```C++
-#include <SPI.h>
-//            MOSI  MISO  SCLK   SSEL
-SPIClass SPI_3(PC12, PC11, PC10, PC9);
-SPISettings settings(1000000, MSBFIRST, SPI_MODE0);
-
-void setup() {
-  SPI_3.begin(); // Enable the SPI_3 instance with default SPISsettings
-  SPI_3.beginTransaction(settings); // Configure the SPI_3 instance
-  SPI_3.transfer(0x52); // Transfers data to the first device
-  SPI_3.end(); // SPI_3 instance is disabled
-}
-```
-
-##### Change default `SPI` instance pins
-It is also possible to change the default pins used by the `SPI` instance using above API:
-
-> [!WARNING]
-> Have to be called before `begin()`.
-
-* `void setMISO(uint32_t miso)`
-* `void setMOSI(uint32_t mosi)`
-* `void setSCLK(uint32_t sclk)`
-* `void setSSEL(uint32_t ssel)`
-* `void setMISO(PinName miso)`
-* `void setMOSI(PinName mosi)`
-* `void setSCLK(PinName sclk)`
-* `void setSSEL(PinName ssel)`
-
-> [!NOTE]
-> Using `setSSEL()` allows to enable hardware CS pin management linked to the SPI peripheral.
-
-###### Example:
-```C++
-    SPI.setMISO(PC_4); // using pin name PY_n
-    SPI.setMOSI(PC2); // using pin number PYn
-    SPI.begin(2);
-```
-
-### I2C
-
-By default, only one `Wire` instance is available and it uses the Arduino pins D14(SDA) and D15(SCL).
-To use a second I2C port, a `TwoWire` object should be declared in the sketch before the `setup()` function:
-```C++
-#include <Wire.h>
-//            SDA  SCL
-TwoWire Wire2(PB3, PB10);
-
-void setup() {
-  Wire2.begin();
-}
-
-void loop() {
-  Wire2.beginTransmission(0x71);
-  Wire2.write('v');
-  Wire2.endTransmission();
-  delay(1000);
-}
-```
-
-See [I2C Timing](customization/Custom-definitions.md#i2c-timing) to customize the I2C speed if needed.
-
-#### Default I2C pins
-**The default I2C interface pins are configured inside the PeripheralPins.c file.**
-
-##### Example (for Nucleo-L452RE in file PeripheralPins.c):
-```C++
-#ifdef HAL_I2C_MODULE_ENABLED
- WEAK const PinMap PinMap_I2C_SDA[] = {
-   {PA_10, I2C1, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_NOPULL, GPIO_AF4_I2C1)},
-   {PB_4,  I2C3, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_NOPULL, GPIO_AF4_I2C3)},
-   {PB_7,  I2C1, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_NOPULL, GPIO_AF4_I2C1)},
-   //  {PB_7,  I2C4, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_NOPULL, GPIO_AF5_I2C4)},
-   {PB_9,  I2C1, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_NOPULL, GPIO_AF4_I2C1)},
-   {PB_11, I2C2, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_NOPULL, GPIO_AF4_I2C2)},
-   //  {PB_11, I2C4, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_NOPULL, GPIO_AF3_I2C4)},
-   {PB_14, I2C2, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_NOPULL, GPIO_AF4_I2C2)},
-   //  {PC_1,  I2C3, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_NOPULL, GPIO_AF4_I2C3)},
-   {PC_1,  I2C4, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_NOPULL, GPIO_AF2_I2C4)},
-   {NC,    NP,    0}
- };
- #endif
-
- #ifdef HAL_I2C_MODULE_ENABLED
- WEAK const PinMap PinMap_I2C_SCL[] = {
-   {PA_7,  I2C3, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_NOPULL, GPIO_AF4_I2C3)},
-   {PA_9,  I2C1, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_NOPULL, GPIO_AF4_I2C1)},
-   //  {PB_6,  I2C1, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_NOPULL, GPIO_AF4_I2C1)},
-   {PB_6,  I2C4, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_NOPULL, GPIO_AF5_I2C4)},
-   {PB_8,  I2C1, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_NOPULL, GPIO_AF4_I2C1)},
-   {PB_10, I2C2, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_NOPULL, GPIO_AF4_I2C2)},
-   //  {PB_10, I2C4, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_NOPULL, GPIO_AF3_I2C4)},
-   {PB_13, I2C2, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_NOPULL, GPIO_AF4_I2C2)},
-   //  {PC_0,  I2C3, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_NOPULL, GPIO_AF4_I2C3)},
-   {PC_0,  I2C4, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_NOPULL, GPIO_AF2_I2C4)},
-   {NC,    NP,    0}
- };
- #endif
-```
-
-#### Redefine I2C pins
-Because they are defined as WEAK, you can redefine them in your sketch file instead of changing values in the PeripheralPins.c file.
-You can also enable/disable the internal pull-ups with the second parameter of STM_PIN_DATA().
-###### Example (inside of sketch file):
-```C++
-const PinMap PinMap_I2C_SDA[] = {
-  {PB_9,  I2C1, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_NOPULLUP, GPIO_AF4_I2C1)},
-  {PC_1,  I2C4, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_PULLUP, GPIO_AF2_I2C4)},
-  {NC,    NP,    0}
-};
-const PinMap PinMap_I2C_SCL[] = {
-  {PB_8,  I2C1, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_NOPULLUP, GPIO_AF4_I2C1)},
-  {PC_0,  I2C4, STM_PIN_DATA(STM_MODE_AF_OD, GPIO_PULLUP, GPIO_AF2_I2C4)},
-  {NC,    NP,    0}
-};
-```
-
-
-
-#### New API functions
-
-##### Change default `Wire` instance pins
-It is also possible to change the default pins used by the `Wire` instance using above API:
-
-* `void setSCL(uint32_t scl)`
-* `void setSDA(uint32_t sda)`
-* `void setSCL(PinName scl)`
-* `void setSDA(PinName sda)`
-
-> [!WARNING]
-> Have to be called before `begin()`.
-
-###### Example:
-```C++
-    Wire.setSDA(PC_4); // using pin name PY_n
-    Wire.setSCL(PC2); // using pin number PYn
-    Wire.begin();
-```
-
-##### Enable general call mode
-Available in core version greater than **1.5.0**
-
-Adding `true` as last parameters of the 3 `Wire::begin()` methods will enable the general call mode otherwise `false` per default:
-
-* `void begin(bool generalCall = false)`
-* `void begin(uint8_t, bool generalCall = false)`
-* `void begin(int, bool generalCall = false)`
-
-###### Example
-`Wire.begin(true);` or `Wire.begin(0x70,true);`
-
-#### I2C buffer management
-By default, I2C buffers are aligned with the Arduino API at **32 bytes**. Transfers of up to **255 bytes** are also possible:
-
-- In master mode: RX and TX buffers will automatically grow when needed, independently one from each other, and independently from other I2C instances. Nothing to do from application point of view. Warning: a bug in STM32 cube HAL (STM32 core v1.8.0) prevents to transfer exactly 255 bytes. (see [PR #853])
-
-- In slave mode: RX and TX buffer size can be statically redefined using [hal_conf_extra.h](customization/HAL-configuration.md) or [`build_opt.h`][build_opt.h] (at compilation time) thanks to switch `I2C_TXRX_BUFFER_SIZE` (see [PR #853]). All I2C instances are impacted by change of this compilation switch.
-
-### CMSIS-DSP
-
-Available in core version greater than **1.7.0**
-
-CMSIS-DSP is a suite of common signal-processing functions for Cortex-M devices.
-
-The library is divided into a number of functions each covering a specific category:
-
-- Basic math functions
-- Fast math functions
-- Complex math functions
-- Filters
-- Matrix functions
-- Transform functions
-- Motor control functions
-- Statistical functions
-- Support functions
-- Interpolation functions.
-
-The library has separate functions for operating on 8-bit integers, 16-bit integers, 32-bit integer and 32-bit floating-point value.
-
-More info:
-https://arm-software.github.io/CMSIS_5/DSP/html/index.html
-
-To use it, include:
-```C++
-#include <CMSIS_DSP.h>
-```
-
-`arm_math.h` is then included automatically.
-
-
-### EEPROM emulation
-
-EEPROM emulation is based on Arduino API:
-https://docs.arduino.cc/learn/built-in-libraries/eeprom/
-
-Emulation is made in Flash, with all constraints related to Flash operation:
-
-- whole sector/page erased and written for each write operation. This can be very long depending on sector/page size.
-- limited Flash life cycle write operation
-
-In addition to Arduino API, to mitigate Flash constraints, it is possible to use buffered API:
-Write operations are made in an intermediate RAM buffer, and only at the end (after writing several parameters for example) the buffer is copied in Flash. Thus only 1 write operation for a whole bunch of data.
-Example is available here: https://github.com/stm32duino/STM32Examples/tree/main/examples/NonReg/BufferedEEPROM
-```C
-void eeprom_buffer_fill(); // This function copies the data from flash into the buffer
-void eeprom_buffer_flush(); // This function writes the buffer content into the flash
-uint8_t eeprom_buffered_read_byte(const uint32_t pos); // Function reads a byte from the eeprom buffer
-void eeprom_buffered_write_byte(uint32_t pos, uint8_t value); // Function writes a byte to the eeprom buffer
-```
-By default, EEPROM emulation storage correspond to the last sector/page of Flash,
-and its size correspond to the size of the last sector/page.
-Nevertheless it is possible to customize address and size used for EEPROM.
-In this case, following switches should be defined (in variant.h or [`build_opt.h`][build_opt.h])
-
-- `FLASH_BASE_ADDRESS`
-- `FLASH_DATA_SECTOR` or `FLASH_PAGE_NUMBER` (depending on STM32 family used)
-
-see example of variant implementation: [PR #938](https://github.com/stm32duino/Arduino_Core_STM32/pull/938)
-
-> [!WARNING]
-> Single/dual bank configuration:
->
-> Default last sector used correspond to default board configuration.
->
-> For example, NUCLEO_F767ZI is by default configured in single bank. Last sector correspond to this bank configuration.
-> If this configuration is changed, it is then mandatory to customize `FLASH_BASE_ADDRESS`/`FLASH_DATA_SECTOR`,
-> even to use last sector of Flash.
-
-### Servo library
-
-See the [Servo library reference](libraries/built-in/Servo-library.md) for the supported Servo API.
-
 ## Other
 
 ### Remembering variables across resets

docs/development/Contributing.md

@@ -0,0 +1,36 @@
+# CMSIS-DSP
+
+Available in core version greater than **1.7.0**
+
+CMSIS-DSP is a suite of common signal-processing functions for Cortex-M devices.
+
+The library is divided into a number of functions each covering a specific category:
+
+- Basic math functions
+- Fast math functions
+- Complex math functions
+- Filters
+- Matrix functions
+- Transform functions
+- Motor control functions
+- Statistical functions
+- Support functions
+- Interpolation functions.
+
+The library has separate functions for operating on 8-bit integers, 16-bit integers, 32-bit integers and 32-bit floating-point values.
+
+More info:
+
+For cores based on CMSIS 6, CMSIS-DSP is provided as a separate package with its own version.
+See the [CMSIS-DSP documentation](https://arm-software.github.io/CMSIS-DSP/) and the
+[CMSIS-DSP repository](https://github.com/ARM-software/CMSIS-DSP) for package and source details.
+
+For cores based on CMSIS 5, see the legacy documentation:
+https://arm-software.github.io/CMSIS_5/DSP/html/index.html
+
+To use it, include:
+```C++
+#include <CMSIS_DSP.h>
+```
+
+`arm_math.h` is then included automatically.

docs/libraries/built-in/CMSIS-DSP-library.md

@@ -0,0 +1,39 @@
+# EEPROM emulation
+
+EEPROM emulation is based on Arduino API:
+https://docs.arduino.cc/learn/built-in-libraries/eeprom/
+
+Emulation is made in Flash, with all constraints related to Flash operation:
+
+- whole sector/page erased and written for each write operation. This can be very long depending on sector/page size.
+- limited Flash life cycle write operation
+
+In addition to Arduino API, to mitigate Flash constraints, it is possible to use buffered API:
+Write operations are made in an intermediate RAM buffer, and only at the end (after writing several parameters for example) the buffer is copied in Flash. Thus only 1 write operation for a whole bunch of data.
+Example is available here: https://github.com/stm32duino/STM32Examples/tree/main/examples/NonReg/BufferedEEPROM
+```C
+void eeprom_buffer_fill(); // This function copies the data from flash into the buffer
+void eeprom_buffer_flush(); // This function writes the buffer content into the flash
+uint8_t eeprom_buffered_read_byte(const uint32_t pos); // Function reads a byte from the eeprom buffer
+void eeprom_buffered_write_byte(uint32_t pos, uint8_t value); // Function writes a byte to the eeprom buffer
+```
+By default, EEPROM emulation storage correspond to the last sector/page of Flash,
+and its size correspond to the size of the last sector/page.
+Nevertheless it is possible to customize address and size used for EEPROM.
+In this case, following switches should be defined (in variant.h or [`build_opt.h`][build_opt.h])
+
+- `FLASH_BASE_ADDRESS`
+- `FLASH_DATA_SECTOR` or `FLASH_PAGE_NUMBER` (depending on STM32 family used)
+
+see example of variant implementation: [PR #938](https://github.com/stm32duino/Arduino_Core_STM32/pull/938)
+
+> [!WARNING]
+> Single/dual bank configuration:
+>
+> Default last sector used correspond to default board configuration.
+>
+> For example, NUCLEO_F767ZI is by default configured in single bank. Last sector correspond to this bank configuration.
+> If this configuration is changed, it is then mandatory to customize `FLASH_BASE_ADDRESS`/`FLASH_DATA_SECTOR`,
+> even to use last sector of Flash.
+
+[build_opt.h]: ../../customization/Customize-build-options-using-build_opt.h.md