diff --git a/CI/update/README.md b/CI/update/README.md index d9950cc210..8876b1d00b 100644 --- a/CI/update/README.md +++ b/CI/update/README.md @@ -1,26 +1,73 @@ -# stm32variant - -By default, generates: - - *PeripheralPins.c* - - *PinNamesVar.h* - - *variant_generic.cpp* - - *variant_generic.h* - - *boards_entry.txt* - - *generic_clock.c* - -for all xml files description available in [STM32CubeMX](http://www.st.com/en/development-tools/stm32cubemx.html) database. -By default, the database used is the one from GitHub: - https://github.com/STMicroelectronics/STM32_open_pin_data -The internal database from STM32CubeMX directory can also be used. -The path have to be defined in `update_config.json`. - -After file generation, review them carefully and please report any issue +# Update scripts + +Run scripts from the `Arduino_Core_STM32` repository root unless noted +otherwise. Most scripts use settings in `CI/update/update_config.json`; they +create default settings when needed. + +## Generate generic variants + +`python CI/update/stm32variant.py` generates `PeripheralPins.c`, +`PinNamesVar.h`, `variant_generic.cpp`, `variant_generic.h`, `boards_entry.txt`, +and `generic_clock.c` from STM32CubeMX XML pin descriptions. By default, it +fetches the `STM32_open_pin_data` database from GitHub and processes all +available descriptions. Use `--list` to list descriptions or +`--series ` to generate a selected series. Use `--cube` to use the +STM32CubeMX database instead; set `CUBEMX_DIRECTORY` in +`CI/update/update_config.json` for that database. The configuration also uses +`STM32CUBECLT_PATH` for STM32 target information. + +`python CI/update/stm32variantv2.py` generates the same files from JSON pinout +descriptions in the newer STM32Cube device-pack repositories. Use `--list` to +list available pinout files or `--series ` to limit generation to one +supported series. The repositories are managed by `stm32cubev2.py`; their +location is configured with `REPOV2_LOCAL_PATH`. + +After generation, review the files carefully and report any issue [here](https://github.com/stm32duino/Arduino_Core_STM32/issues). +## Update STM32Cube content + +`python CI/update/stm32cube.py` manages the HAL drivers and CMSIS device files +from the STM32Cube repositories. By default, it updates all supported series. +Use `--check` to report version differences without updating, `--series +` to select a series, or `--path ` to use a local STM32Cube +repository instead of fetching from GitHub. By default, updates are prepared +in a working copy; use `--local` to update the current core repository. + +`python CI/update/stm32cubev2.py` performs the corresponding update for the +newer STM32Cube repository layout, including HAL, LL, and CMSIS files. It +supports the same `--check`, `--series`, `--path`, and `--local` options. + +## Generate support files + +`python CI/update/stm32wrapper.py` regenerates the HAL, LL, CMSIS, and related +wrapper files using content already present in the core. Optional +`--core ` and `--cmsis ` arguments select alternate core +and CMSIS directories. + +`python CI/update/stm32svd.py` updates the SVD files in the configured +STM32duino SVD repository. Set `STM32CUBECLT_PATH` to an STM32CubeCLT +installation and `STM32_SVD_PATH` to the SVD repository in +`CI/update/update_config.json`. The script replaces the repository's `svd` +directory with files selected from that CubeCLT installation. + +`python CI/update/fqbn.py` prints the STM32 board FQBNs available in an +installed Arduino core, including each board's `pnum` choices. Use `--board +` to filter the output with a regular expression and `--path +` to specify the directory containing `arduino-cli`. + +## Update ArduinoCore-API + +`python CI/update/stm32api.py` synchronizes the ArduinoCore-API submodule with +the latest upstream tag, applies eligible STM32duino pull requests and local +patches, and reshapes the tree for STM32 use. It requires the submodule to be +initialized, a clean submodule worktree, and the GitHub CLI (`gh`) to retrieve +pull-request data. + ## Update the STM32duino library list -Run `python CI/update/stm32libraries.py` from the `Arduino_Core_STM32` repository -to fetch public STM32duino repositories that contain a root-level +Run `python CI/update/stm32libraries.py` from the `Arduino_Core_STM32` +repository to fetch public STM32duino repositories that contain a root-level `library.properties` and refresh the generated section in `docs/libraries/index.md`. The script groups libraries by their declared category, puts expansion-board libraries in a separate section, includes @@ -28,9 +75,10 @@ declared dependencies (linking STM32duino dependencies when available), and sorts entries alphabetically. Review and commit the updated documentation manually; this script is not run by CI. -`REPO_STM32DUINO` in `update_config.json` selects the local directory where -library repositories are cloned or fetched. Absolute paths are used as -configured; relative paths are resolved from the `Arduino_Core_STM32` repository -root. If the file or setting is missing, the script writes the default -`REPO_STM32DUINO` path (the parent of the core repository root), asks you to check the -configuration, and exits; run it again after reviewing the generated setting. +`REPO_STM32DUINO` in `CI/update/update_config.json` selects the local directory +where library repositories are cloned or fetched. Absolute paths are used as +configured; relative paths are resolved from the `Arduino_Core_STM32` +repository root. If the file or setting is missing, the script writes the +default `REPO_STM32DUINO` path (the parent of the core repository root), asks +you to check the configuration, and exits; run it again after reviewing the +generated setting. diff --git a/CI/update/gen_wrapper.sh b/CI/update/gen_wrapper.sh deleted file mode 100644 index 0ec33fa7c3..0000000000 --- a/CI/update/gen_wrapper.sh +++ /dev/null @@ -1,210 +0,0 @@ -#!/bin/bash - -set -o nounset # Treat unset variables as an error - -# Base path -Core_path=../.. -SrcWrapper_path=$Core_path/libraries/SrcWrapper -HALDrivers_path=$Core_path/system/Drivers -CMSIS_Device_ST_path=$Core_path/system/Drivers/CMSIS/Device/ST -CMSIS_DSP_path=$Core_path/libraries/CMSIS_DSP -# CMSIS outside of the core. To be updated to match environment -CMSIS_path=$Core_path/../ArduinoModule-CMSIS/CMSIS_5 -CMSIS_DSPSrc_path=$CMSIS_path/CMSIS/DSP/Source - -# Out sources files -HALoutSrc_path=$SrcWrapper_path/src/HAL -LLoutSrc_path=$SrcWrapper_path/src/LL -CMSIS_DSP_outSrc_path=$CMSIS_DSP_path/src - -# Out include files -LLoutInc_path=$Core_path/cores/arduino/stm32/LL - -# Out startup files -CMSIS_Startupfile=$Core_path/cores/arduino/stm32/stm32_def_build.h - -# Variables -series=($(find $HALDrivers_path -maxdepth 1 -type d -name "STM32*" | sed -e "s#$HALDrivers_path/STM32##g" -e "s#xx_HAL_Driver##g" | sort)) - -all_LL_file=stm32yyxx_ll.h - -# Create the file -print_C_header() { - # if [[ $1 = *"template"* ]]; then - # echo "#if 0" > "$1" - # else - # touch "$1" - # fi - touch "$1" -} - -# Add some pragma to ll header files to avoid several warnings -# which will be corrected along Cube update -print_LL_header() { - upper=$(echo "$1" | awk '{print toupper($1)}' | sed -e "s/\./_/g") - echo "#ifndef _${upper}_ -#define _${upper}_ -/* LL raised several warnings, ignore them */ -#pragma GCC diagnostic push -#pragma GCC diagnostic ignored \"-Wunused-parameter\" -#pragma GCC diagnostic ignored \"-Wstrict-aliasing\" -" > $LLoutInc_path/"$1" -} - -print_CMSIS_Startup_header() { - echo "#ifndef _STM32_DEF_BUILD_ -#define _STM32_DEF_BUILD_ - -#if !defined(CMSIS_STARTUP_FILE) && !defined(CUSTOM_STARTUP_FILE)" > $CMSIS_Startupfile -} - -print_CMSIS_Startup_footer() { - echo " #else - #error UNKNOWN CHIP - #endif -#else - #warning \"No CMSIS startup file defined, custom one should be used\" -#endif /* !CMSIS_STARTUP_FILE && !CUSTOM_STARTUP_FILE */ -#endif /* _STM32_DEF_BUILD_ */" >> $CMSIS_Startupfile -} - -print_CMSIS_Startup_list() { - # Handle first elements - # File name - local f - local upper - f=$(echo "${list[0]}" | awk -F/ '{print $NF}') - upper=$(echo "$f" | awk -F'[_.]' '{print toupper($2)}' | tr X x) - echo " #if defined($upper) - #define CMSIS_STARTUP_FILE \"$f\"" >> $CMSIS_Startupfile - - if [ ${#list[@]} -gt 1 ]; then - for fp in "${list[@]:1}"; do - # File name - f=$(echo "$fp" | awk -F/ '{print $NF}') - upper=$(echo "$f" | awk -F'[_.]' '{print toupper($2)}' | tr X x) - upper="${upper//MP15xx/MP1xx}" - echo " #elif defined($upper) - #define CMSIS_STARTUP_FILE \"$f\"" >> $CMSIS_Startupfile - done - fi -} - -# main -# Check if this is the right place -if [ ! -d $HALDrivers_path ]; then - echo "Could not find $HALDrivers_path!" - echo "Launch $0 from scripts folder!" - exit 1 -fi - -# Remove old file -rm -f $HALoutSrc_path/* $LLoutSrc_path/* $LLoutInc_path/* $CMSIS_Startupfile - -# Search all files for each series -for serie in "${series[@]}"; do - if [ -d $HALDrivers_path/STM32"${serie}"xx_HAL_Driver/Src ]; then - lower=$(echo "$serie" | awk '{print tolower($0)}') - echo -n "Generating for $serie..." - - # Generate stm32yyxx_[hal|ll]*.c file - filelist=($(find $HALDrivers_path/STM32"${serie}"xx_HAL_Driver/Src -maxdepth 1 -name "stm32${lower}xx_*.c")) - for fp in "${filelist[@]}"; do - # No need for template - if [[ $fp = *"template"* ]]; then - continue - fi - outp=$HALoutSrc_path - # File name - f=$(echo "$fp" | awk -F/ '{print $NF}') - # Compute generic file name - g="${f//$lower/yy}" - if [[ $f = *"_ll_"* ]]; then - outp=$LLoutSrc_path - fi - if [ ! -f $outp/"$g" ]; then - print_C_header $outp/"$g" - fi - # Amend file name under serie switch - { - echo "#ifdef STM32${serie}xx" - echo " #include \"$f\"" - echo "#endif" - } >> $outp/"$g" - done - - # Generate stm32yyxx_ll_*.h file - filelist=($(find $HALDrivers_path/STM32"${serie}"xx_HAL_Driver/Inc -maxdepth 2 -name "stm32${lower}xx_ll_*.h")) - for fp in "${filelist[@]}"; do - # File name - f=$(echo "$fp" | awk -F/ '{print $NF}') - # Compute generic file name - g="${f//$lower/yy}" - - if [ ! -f $LLoutInc_path/"$g" ]; then - print_LL_header "$g" - fi - # Amend full LL header file - echo "#include \"$g\"" >> $LLoutInc_path/${all_LL_file}.tmp - # Amend file name under serie switch - { - echo "#ifdef STM32${serie}xx" - echo " #include \"$f\"" - echo "#endif" - } >> $LLoutInc_path/"$g" - done - echo "done" - fi -done - -# Filter full LL header file -if [ ! -f $LLoutInc_path/$all_LL_file ]; then - print_LL_header $all_LL_file -fi -echo "/* Include Low Layers drivers */" >> $LLoutInc_path/${all_LL_file} -sort -u $LLoutInc_path/${all_LL_file}.tmp >> $LLoutInc_path/${all_LL_file} -rm -f $LLoutInc_path/${all_LL_file}.tmp - -# Search all template file to end "#if 0" -# filelist=($(find $HALoutSrc_path -maxdepth 1 -name "stm32*_template.c")) -# for fp in "${filelist[@]}"; do -# echo "#endif /* 0 */" >> "$fp" -# done - -# Search all LL header files to end guard -filelist=($(find $LLoutInc_path -maxdepth 1 -name "stm32yyxx_ll*.h")) -for fp in "${filelist[@]}"; do - upper=$(basename "$fp" | awk '{print toupper($1)}' | sed -e "s/\./_/g") - echo "#pragma GCC diagnostic pop" >> "$fp" - echo "#endif /* _${upper}_ */" >> "$fp" -done - -# CMSIS startup files -list=($(find $CMSIS_Device_ST_path -name "startup_*.s" | grep gcc | sort -du)) -if [ ${#list[@]} -ne 0 ]; then - echo "Number of startup files: ${#list[@]}" - print_CMSIS_Startup_header - print_CMSIS_Startup_list - print_CMSIS_Startup_footer -else - echo "No startup files found!" -fi - -# CMSIS DSP C source files -if [ ! -d $CMSIS_DSPSrc_path ]; then - echo "Could not find $CMSIS_DSPSrc_path!" - echo "Update 'CMSIS_path' in $0 to point on ArduinoModule-CMSIS folder." - echo "Skip CMSIS DSP generation." -else - # Remove old file - rm -fr "${CMSIS_DSP_outSrc_path:?}"/*/ - - filelist=($(find $CMSIS_DSPSrc_path -name "*.c" | sed -e "s#$CMSIS_DSPSrc_path/##g" | sort -u)) - for fp in "${filelist[@]}"; do - # Directory name - d=$(echo "$fp" | awk -F/ '{print $(NF-1)}') - if [ ! -d $CMSIS_DSP_outSrc_path/"$d" ]; then - mkdir $CMSIS_DSP_outSrc_path/"$d" - echo "#include \"../Source/$d/$d.c\"" > $CMSIS_DSP_outSrc_path/"$d"/"$d".c - fi - done -fi diff --git a/CI/update/templates/generic_clock.c b/CI/update/templates/generic_clock.c index 10f37de526..59951ea226 100644 --- a/CI/update/templates/generic_clock.c +++ b/CI/update/templates/generic_clock.c @@ -15,9 +15,7 @@ #include "pins_arduino.h" /** - * @brief System Clock Configuration - * @param None - * @retval None + * @brief System Clock Configuration */ WEAK void SystemClock_Config(void) { diff --git a/cores/arduino/Serial.h b/cores/arduino/Serial.h index f831ce3bcc..f45b1c3625 100644 --- a/cores/arduino/Serial.h +++ b/cores/arduino/Serial.h @@ -105,6 +105,11 @@ typedef enum { #undef SERIAL_6O2 #endif +/** + * @brief STM32 hardware UART. Implements the Arduino Stream and HardwareSerial API. + * + * Use one of the constructors to bind a UART to pins or to a peripheral, then call begin(). + */ class Uart : public arduino::HardwareSerial { protected: // Has any byte been written to the UART since begin() @@ -122,88 +127,298 @@ class Uart : public arduino::HardwareSerial { serial_t _serial; public: + /** + * @brief Create a UART from Arduino digital pin numbers. + * + * @param _rx Digital pin used for RX. + * @param _tx Digital pin used for TX. + * @param _rts Digital pin used for RTS flow control, NUM_DIGITAL_PINS if unused. + * @param _cts Digital pin used for CTS flow control, NUM_DIGITAL_PINS if unused. + */ Uart(pin_size_t _rx, pin_size_t _tx, pin_size_t _rts = NUM_DIGITAL_PINS, pin_size_t _cts = NUM_DIGITAL_PINS); + /** + * @brief Create a UART from STM32 pin names. + * + * @param _rx Pin used for RX. + * @param _tx Pin used for TX. + * @param _rts Pin used for RTS flow control, NC if unused. + * @param _cts Pin used for CTS flow control, NC if unused. + */ Uart(PinName _rx, PinName _tx, PinName _rts = NC, PinName _cts = NC); + /** + * @brief Create a UART from an STM32 USART/UART peripheral. Pins are taken from the variant. + * + * @param peripheral USART/UART peripheral instance, e.g. USART1. + * @param halfDuplex HALF_DUPLEX_ENABLED to use the TX pin only. + */ Uart(void *peripheral, HalfDuplexMode_t halfDuplex = HALF_DUPLEX_DISABLED); + /** + * @brief Create a half-duplex UART on a single digital pin. The pin is used as TX and RX is NC. + * + * @param _rxtx Digital pin used for TX. + */ Uart(pin_size_t _rxtx); + /** + * @brief Create a half-duplex UART on a single STM32 pin. The pin is used as TX and RX is NC. + * + * @param _rxtx Pin used for TX. + */ Uart(PinName _rxtx); + /** + * @brief Start the UART with 8 data bits, no parity and 1 stop bit (SERIAL_8N1). + * + * @param baud Baud rate in bits per second. + */ void begin(unsigned long baud) override { begin(baud, SERIAL_8N1); } + /** + * @brief Start the UART with the given baud rate and frame format. + * + * @param baud Baud rate in bits per second. + * @param config Frame format, e.g. SERIAL_8N1 or SERIAL_8E1. + */ void begin(unsigned long baud, uint16_t config) override ; // Implement all pure virtuals + /** + * @brief Wait for pending transmission, stop the UART, release its pins and clear the receive buffer. + */ void end() override; + /** + * @brief Get the number of bytes available to read. + * + * @return Number of bytes in the receive buffer. + */ int available(void) override; + /** + * @brief Read the next byte without removing it from the receive buffer. + * + * @return Next byte, or -1 if none is available. + */ int peek(void) override; + /** + * @brief Read and remove the next byte from the receive buffer. + * + * @return Next byte, or -1 if none is available. + */ int read(void) override; + /** + * @brief Wait until all queued bytes are transmitted. + */ void flush() override; + /** + * @brief Write one byte. + * + * @param c Byte to write. + * @return Number of bytes written: 1, or 0 if the UART is not started. + */ size_t write(uint8_t) override; + /** + * @brief Check whether the UART is started. + * + * @return true if begin() was called and the UART is ready. + */ operator bool() override { return _ready; } // STM32 extension + /** + * @brief Get the number of bytes that can be written without blocking. + * + * @return Free space in the transmit buffer, in bytes. + */ int availableForWrite(void); + /** + * @brief Wait until all queued bytes are transmitted, or until a timeout elapses. + * + * @param timeout Maximum wait in milliseconds. 0 waits without limit. + * On timeout, the pending transmit data is discarded. + */ void flush(uint32_t timeout); + /** + * @brief Write one byte, truncating the value to 8 bits. + * + * @param n Value to write. + * @return Number of bytes written. + */ inline size_t write(unsigned long n) { return write((uint8_t)n); } + /** + * @brief Write one byte, truncating the value to 8 bits. + * + * @param n Value to write. + * @return Number of bytes written. + */ inline size_t write(long n) { return write((uint8_t)n); } + /** + * @brief Write one byte, truncating the value to 8 bits. + * + * @param n Value to write. + * @return Number of bytes written. + */ inline size_t write(unsigned int n) { return write((uint8_t)n); } + /** + * @brief Write one byte, truncating the value to 8 bits. + * + * @param n Value to write. + * @return Number of bytes written. + */ inline size_t write(int n) { return write((uint8_t)n); } + /** + * @brief Write a buffer of bytes. + * + * @param buffer Data to write. + * @param size Number of bytes in buffer. + * @return Number of bytes written, 0 if the UART is not started. + */ size_t write(const uint8_t *buffer, size_t size); using Print::write; // pull in write(str) from Print + /** + * @brief Set the RX pin by Arduino pin number. Call before begin(). + * + * @param _rx Digital pin used for RX. + */ void setRx(pin_size_t _rx); + /** + * @brief Set the TX pin by Arduino pin number. Call before begin(). + * + * @param _tx Digital pin used for TX. + */ void setTx(pin_size_t _tx); + /** + * @brief Set the RX pin by STM32 pin name. Call before begin(). + * + * @param _rx Pin used for RX. + */ void setRx(PinName _rx); + /** + * @brief Set the TX pin by STM32 pin name. Call before begin(). + * + * @param _tx Pin used for TX. + */ void setTx(PinName _tx); // Enable HW flow control on RTS, CTS or both + /** + * @brief Enable hardware RTS flow control on a digital pin. Call before begin(). + * + * @param _rts Digital pin used for RTS. + */ void setRts(pin_size_t _rts); + /** + * @brief Enable hardware CTS flow control on a digital pin. Call before begin(). + * + * @param _cts Digital pin used for CTS. + */ void setCts(pin_size_t _cts); + /** + * @brief Enable hardware RTS and CTS flow control on digital pins. Call before begin(). + * + * @param _rts Digital pin used for RTS. + * @param _cts Digital pin used for CTS. + */ void setRtsCts(pin_size_t _rts, pin_size_t _cts); + /** + * @brief Enable hardware RTS flow control on an STM32 pin. Call before begin(). + * + * @param _rts Pin used for RTS. + */ void setRts(PinName _rts); + /** + * @brief Enable hardware CTS flow control on an STM32 pin. Call before begin(). + * + * @param _cts Pin used for CTS. + */ void setCts(PinName _cts); + /** + * @brief Enable hardware RTS and CTS flow control on STM32 pins. Call before begin(). + * + * @param _rts Pin used for RTS. + * @param _cts Pin used for CTS. + */ void setRtsCts(PinName _rts, PinName _cts); // Enable half-duplex mode by setting the Rx pin to NC // This needs to be done before the call to begin() + /** + * @brief Enable half-duplex mode by setting the RX pin to NC. Call before begin(). + */ void setHalfDuplex(void); + /** + * @brief Check whether the UART is in half-duplex mode. + * + * @return true if the RX pin is NC. + */ bool isHalfDuplex(void) const; + /** + * @brief Enable reception in half-duplex mode after the pending transmission ends. + */ void enableHalfDuplexRx(void); // Enable HW Rx/Tx/data inversion // This needs to be done before the call to begin() + /** + * @brief Invert the RX line in hardware. Call before begin(). + */ void setRxInvert(void); + /** + * @brief Invert the TX line in hardware. Call before begin(). + */ void setTxInvert(void); + /** + * @brief Invert the data bits in hardware. Call before begin(). + */ void setDataInvert(void); friend class STM32LowPower; // Interrupt handlers + /** + * @brief RX interrupt handler. Stores the received byte in the receive buffer. + * + * @param obj UART object that received the byte. + */ static void _rx_complete_irq(serial_t *obj); + /** + * @brief TX interrupt handler. Starts the next chunk of queued data, if any. + * + * @param obj UART object whose transfer completed. + * @return -1 if a new transfer was started, 0 if the transmit buffer is empty. + */ static int _tx_complete_irq(serial_t *obj); #if defined(HAL_UART_MODULE_ENABLED) && !defined(HAL_UART_MODULE_ONLY) // Could be used to mix Arduino API and STM32Cube HAL API (ex: DMA). Use at your own risk. #if defined(USE_HALV2_DRIVER) + /** + * @brief Get the underlying HAL UART handle. + * + * @return Pointer to the HAL UART handle. + */ hal_uart_handle_t *getHandle(void) #else + /** + * @brief Get the underlying HAL UART handle. + * + * @return Pointer to the HAL UART handle. + */ UART_HandleTypeDef *getHandle(void) #endif { @@ -216,49 +431,99 @@ class Uart : public arduino::HardwareSerial { bool _rx_enabled; uint16_t _config; unsigned long _baud; + /** + * @brief Initialize the UART object with STM32 pin names. + * + * @param _rx Pin used for RX. + * @param _tx Pin used for TX. + * @param _rts Pin used for RTS, NC if unused. + * @param _cts Pin used for CTS, NC if unused. + */ void init(PinName _rx, PinName _tx, PinName _rts = NC, PinName _cts = NC); + /** + * @brief Reconfigure the UART for low-power operation. + */ void configForLowPower(void); }; #if defined(USART1) + /** + * @brief Hardware serial port 1 (USART1). + */ extern Uart Serial1; #endif #if defined(USART2) + /** + * @brief Hardware serial port 2 (USART2). + */ extern Uart Serial2; #endif #if defined(USART3) + /** + * @brief Hardware serial port 3 (USART3). + */ extern Uart Serial3; #endif #if defined(UART4) || defined(USART4) + /** + * @brief Hardware serial port 4 (UART4 or USART4). + */ extern Uart Serial4; #endif #if defined(UART5) || defined(USART5) + /** + * @brief Hardware serial port 5 (UART5 or USART5). + */ extern Uart Serial5; #endif #if defined(USART6) + /** + * @brief Hardware serial port 6 (USART6). + */ extern Uart Serial6; #endif #if defined(UART7) || defined(USART7) + /** + * @brief Hardware serial port 7 (UART7 or USART7). + */ extern Uart Serial7; #endif #if defined(UART8) || defined(USART8) + /** + * @brief Hardware serial port 8 (UART8 or USART8). + */ extern Uart Serial8; #endif #if defined(UART9) + /** + * @brief Hardware serial port 9 (UART9). + */ extern Uart Serial9; #endif #if defined(UART10) || defined(USART10) + /** + * @brief Hardware serial port 10 (UART10 or USART10). + */ extern Uart Serial10; #endif #if defined(LPUART1) + /** + * @brief Low-power serial port 1 (LPUART1). + */ extern Uart SerialLP1; #endif #if defined(LPUART2) + /** + * @brief Low-power serial port 2 (LPUART2). + */ extern Uart SerialLP2; #endif #if defined(LPUART3) + /** + * @brief Low-power serial port 3 (LPUART3). + */ extern Uart SerialLP3; #endif #endif diff --git a/cores/arduino/Server.h b/cores/arduino/Server.h index db37c0e8a1..93a286153a 100644 --- a/cores/arduino/Server.h +++ b/cores/arduino/Server.h @@ -22,8 +22,14 @@ #include "Print.h" +/** + * @brief Base class for server objects that accept client connections. + */ class Server : public Print { public: + /** + * @brief Start listening for connections. + */ virtual void begin() = 0; }; diff --git a/cores/arduino/Tone.cpp b/cores/arduino/Tone.cpp index f46fc0e9f1..4b8d1ab428 100644 --- a/cores/arduino/Tone.cpp +++ b/cores/arduino/Tone.cpp @@ -38,10 +38,8 @@ static timerPinInfo_t TimerTone_pinInfo = {NC, 0}; static HardwareTimer *TimerTone = NULL; /** - * @brief Tone Period elapsed callback in non-blocking mode - * @param htim : timer handle - * @retval None - */ + * @brief Tone Period elapsed callback in non-blocking mode. + */ static void tonePeriodElapsedCallback() { GPIO_TypeDef *port = get_GPIO_Port(STM_PORT(TimerTone_pinInfo.pin)); @@ -59,11 +57,8 @@ static void tonePeriodElapsedCallback() } /** - * @brief This function will reset the tone timer - * @param port : pointer to port - * @param pin : pin number to toggle - * @retval None - */ + * @brief Reset the tone timer and release the tone pin. + */ static void timerTonePinDeinit() { if (TimerTone != NULL) { @@ -75,6 +70,13 @@ static void timerTonePinDeinit() } } +/** + * @brief Configure the tone timer and output pin for a given frequency and duration. + * + * @param p Pin to output the tone on. + * @param frequency Tone frequency in Hertz. 0 pauses the timer, values above MAX_FREQ are ignored. + * @param duration Tone duration in milliseconds. 0 means the tone plays until noTone() is called. + */ static void timerTonePinInit(PinName p, uint32_t frequency, uint32_t duration) { uint32_t timFreq = 2 * frequency; @@ -103,7 +105,13 @@ static void timerTonePinInit(PinName p, uint32_t frequency, uint32_t duration) } } -// frequency (in hertz) and duration (in milliseconds). +/** + * @brief Generate a square wave of the given frequency on a pin. + * + * @param _pin Pin to output the tone on. + * @param frequency Frequency of the tone in Hertz. + * @param duration Duration of the tone in milliseconds. 0 plays the tone until noTone() is called. + */ void tone(uint8_t _pin, unsigned int frequency, unsigned long duration) { PinName p = digitalPinToPinName(_pin); @@ -120,6 +128,11 @@ void tone(uint8_t _pin, unsigned int frequency, unsigned long duration) } +/** + * @brief Stop tone generation on a pin, keeping the tone timer allocated. + * + * @param _pin Pin on which to stop tone generation. + */ void noTone(uint8_t _pin) { noTone(_pin, false); diff --git a/cores/arduino/WInterrupts.cpp b/cores/arduino/WInterrupts.cpp index f25ad4599a..e233842542 100644 --- a/cores/arduino/WInterrupts.cpp +++ b/cores/arduino/WInterrupts.cpp @@ -70,6 +70,13 @@ void attachInterrupt(pin_size_t interruptNumber, callback_function_t callback, P stm32_interrupt_enable(p, callback, it_mode); } #endif +/** + * @brief Attach a function to an external interrupt on a pin, using a plain function pointer. + * + * @param interruptNumber Pin to attach the interrupt to. + * @param callback Function called when the interrupt fires. + * @param mode Trigger mode: CHANGE, RISING, FALLING, LOW or HIGH. + */ void attachInterrupt(pin_size_t interruptNumber, voidFuncPtr callback, PinStatus mode) { #if !defined(HAL_EXTI_MODULE_DISABLED) @@ -82,6 +89,11 @@ void attachInterrupt(pin_size_t interruptNumber, voidFuncPtr callback, PinStatus #endif } +/** + * @brief Disable the external interrupt attached to a pin. + * + * @param interruptNumber Pin whose interrupt is disabled. + */ void detachInterrupt(pin_size_t interruptNumber) { #if !defined(HAL_EXTI_MODULE_DISABLED) diff --git a/cores/arduino/WMath.cpp b/cores/arduino/WMath.cpp index 4505c2bd54..6561d7104c 100644 --- a/cores/arduino/WMath.cpp +++ b/cores/arduino/WMath.cpp @@ -21,6 +21,13 @@ extern "C" { #include "stdint.h" } +/** + * @brief Seed the pseudo-random number generator. + * + * A seed of 0 is ignored. + * + * @param dwSeed Seed value. + */ void randomSeed(unsigned long dwSeed) { if (dwSeed != 0) { @@ -28,6 +35,12 @@ void randomSeed(unsigned long dwSeed) } } +/** + * @brief Return a pseudo-random number in the range [0, howbig). + * + * @param howbig Upper bound, exclusive. 0 returns 0. + * @return Pseudo-random number. + */ long random(long howbig) { if (howbig == 0) { @@ -37,6 +50,13 @@ long random(long howbig) return rand() % howbig; } +/** + * @brief Return a pseudo-random number in the range [howsmall, howbig). + * + * @param howsmall Lower bound, inclusive. Returned directly if it is not below howbig. + * @param howbig Upper bound, exclusive. + * @return Pseudo-random number. + */ long random(long howsmall, long howbig) { if (howsmall >= howbig) { diff --git a/cores/arduino/WSerial.cpp b/cores/arduino/WSerial.cpp index 6bb665b0d5..942626382e 100644 --- a/cores/arduino/WSerial.cpp +++ b/cores/arduino/WSerial.cpp @@ -1,5 +1,10 @@ #include "WSerial.h" +/** + * @brief Call serialEventN() for each hardware serial port that has data available. + * + * Called from main() after each loop() iteration. Weak, so a sketch can override it. + */ WEAK void serialEventRun(void) { #if defined(HAVE_HWSERIAL1) diff --git a/cores/arduino/WSerial.h b/cores/arduino/WSerial.h index 55448c1657..79331d10c0 100644 --- a/cores/arduino/WSerial.h +++ b/cores/arduino/WSerial.h @@ -23,6 +23,9 @@ #define HAVE_SERIALUSB #endif + /** + * @brief Weak USB CDC serial callback, called by serialEventRun(). Override to handle USB data. + */ extern void serialEventUSB(void) __attribute__((weak)); #endif /* USBCON && USBD_USE_CDC */ @@ -39,6 +42,9 @@ #define HAVE_SERIALVIRTIO #endif + /** + * @brief Weak VirtIO serial callback, called by serialEventRun(). Override to handle VirtIO data. + */ extern void serialEventVirtIO(void) __attribute__((weak)); #endif /* VIRTIOCON */ @@ -196,42 +202,81 @@ #endif #if defined(HAVE_HWSERIAL1) + /** + * @brief Weak callback for Serial1, called by serialEventRun(). Override to handle incoming data. + */ extern void serialEvent1(void) __attribute__((weak)); #endif #if defined(HAVE_HWSERIAL2) + /** + * @brief Weak callback for Serial2, called by serialEventRun(). Override to handle incoming data. + */ extern void serialEvent2(void) __attribute__((weak)); #endif #if defined(HAVE_HWSERIAL3) + /** + * @brief Weak callback for Serial3, called by serialEventRun(). Override to handle incoming data. + */ extern void serialEvent3(void) __attribute__((weak)); #endif #if defined(HAVE_HWSERIAL4) + /** + * @brief Weak callback for Serial4, called by serialEventRun(). Override to handle incoming data. + */ extern void serialEvent4(void) __attribute__((weak)); #endif #if defined(HAVE_HWSERIAL5) + /** + * @brief Weak callback for Serial5, called by serialEventRun(). Override to handle incoming data. + */ extern void serialEvent5(void) __attribute__((weak)); #endif #if defined(HAVE_HWSERIAL6) + /** + * @brief Weak callback for Serial6, called by serialEventRun(). Override to handle incoming data. + */ extern void serialEvent6(void) __attribute__((weak)); #endif #if defined(HAVE_HWSERIAL7) + /** + * @brief Weak callback for Serial7, called by serialEventRun(). Override to handle incoming data. + */ extern void serialEvent7(void) __attribute__((weak)); #endif #if defined(HAVE_HWSERIAL8) + /** + * @brief Weak callback for Serial8, called by serialEventRun(). Override to handle incoming data. + */ extern void serialEvent8(void) __attribute__((weak)); #endif #if defined(HAVE_HWSERIAL9) + /** + * @brief Weak callback for Serial9, called by serialEventRun(). Override to handle incoming data. + */ extern void serialEvent9(void) __attribute__((weak)); #endif #if defined(HAVE_HWSERIAL10) + /** + * @brief Weak callback for Serial10, called by serialEventRun(). Override to handle incoming data. + */ extern void serialEvent10(void) __attribute__((weak)); #endif #if defined(HAVE_HWSERIALLP1) + /** + * @brief Weak callback for SerialLP1, called by serialEventRun(). Override to handle incoming data. + */ extern void serialEventLP1(void) __attribute__((weak)); #endif #if defined(HAVE_HWSERIALLP2) + /** + * @brief Weak callback for SerialLP2, called by serialEventRun(). Override to handle incoming data. + */ extern void serialEventLP2(void) __attribute__((weak)); #endif #if defined(HAVE_HWSERIALLP3) + /** + * @brief Weak callback for SerialLP3, called by serialEventRun(). Override to handle incoming data. + */ extern void serialEventLP3(void) __attribute__((weak)); #endif #endif /* HAL_UART_MODULE_ENABLED && !HAL_UART_MODULE_ONLY */ diff --git a/cores/arduino/abi.cpp b/cores/arduino/abi.cpp index 9583f3c409..f7c0fba8de 100644 --- a/cores/arduino/abi.cpp +++ b/cores/arduino/abi.cpp @@ -21,6 +21,11 @@ extern "C" void __cxa_pure_virtual(void) __attribute__((__noreturn__)); extern "C" void __cxa_deleted_virtual(void) __attribute__((__noreturn__)); +/** + * @brief Called on a pure virtual function call. Halts the program. + * + * Does not return. + */ void __cxa_pure_virtual(void) { // We might want to write some diagnostics to uart in this case @@ -29,6 +34,11 @@ void __cxa_pure_virtual(void) ; } +/** + * @brief Called when a deleted virtual function is invoked. Halts the program. + * + * Does not return. + */ void __cxa_deleted_virtual(void) { // We might want to write some diagnostics to uart in this case diff --git a/cores/arduino/avr/dtostrf.c b/cores/arduino/avr/dtostrf.c index 6bd602d668..9f05ffd006 100644 --- a/cores/arduino/avr/dtostrf.c +++ b/cores/arduino/avr/dtostrf.c @@ -23,6 +23,17 @@ #include #include +/** + * @brief Convert a double to a string with a fixed number of decimal places. + * + * Emulation of the avr-libc dtostrf() function. + * + * @param val Value to convert. + * @param width Minimum field width of the output string. Negative for left adjustment. Range -128 to 127. + * @param prec Number of digits after the decimal point. + * @param sout Buffer to write the result to. Must be large enough for the result. + * @return Pointer to sout. + */ char *dtostrf(double val, signed char width, unsigned char prec, char *sout) { //Commented code is the original version diff --git a/cores/arduino/board.c b/cores/arduino/board.c index 0ca19be820..33568f4acd 100644 --- a/cores/arduino/board.c +++ b/cores/arduino/board.c @@ -4,8 +4,16 @@ extern "C" { #endif +/** + * @brief C library initialization. Calls the constructors of static objects. + */ void __libc_init_array(void); +/** + * @brief Board-level initialization, called once before setup(). + * + * Weak, so a variant or sketch can override it. Calls hw_config_init(). + */ WEAK void init(void) { hw_config_init(); diff --git a/cores/arduino/core_debug.h b/cores/arduino/core_debug.h index f5a74e62f3..f7e6fb6add 100644 --- a/cores/arduino/core_debug.h +++ b/cores/arduino/core_debug.h @@ -29,6 +29,11 @@ inline void core_debug(const char *format, ...) #endif /* NDEBUG */ } +/** Output a debug message from a va_list + * + * @param format printf-style format string + * @param args variable argument list matching format + */ inline void vcore_debug(const char *format, va_list args) { #if !defined(NDEBUG) diff --git a/cores/arduino/hooks.c b/cores/arduino/hooks.c index a85150bca5..18c44ea7d4 100644 --- a/cores/arduino/hooks.c +++ b/cores/arduino/hooks.c @@ -19,7 +19,7 @@ #include /** - * Empty yield() hook. + * @brief Empty yield() hook. * * This function is intended to be used by library writers to build * libraries or sketches that supports cooperative threads. @@ -35,7 +35,7 @@ void yield(void) __attribute__((weak, alias("__empty"))); #ifdef DTR_TOGGLING_SEQ /** - * Empty dtr_toggling() hook. + * @brief Empty dtr_toggling() hook. * * This function is intended to be used by library writers to build * libraries or sketches that require DTR toggling feature. diff --git a/cores/arduino/itoa.c b/cores/arduino/itoa.c index e737b6f14d..dee441ef17 100644 --- a/cores/arduino/itoa.c +++ b/cores/arduino/itoa.c @@ -22,6 +22,14 @@ extern "C" { #endif +/** + * @brief Convert a long to a null-terminated string. + * + * @param value Value to convert. Negative values are only signed for radix 10. + * @param string Buffer to write the result to. Must be large enough for the result. + * @param radix Base to use, from 2 to 36. + * @return Pointer to string, or NULL if string is NULL or radix is out of range. + */ char *ltoa(long value, char *string, int radix) { char tmp[33]; @@ -69,6 +77,14 @@ char *ltoa(long value, char *string, int radix) return string; } +/** + * @brief Convert an unsigned long to a null-terminated string. + * + * @param value Value to convert. + * @param string Buffer to write the result to. Must be large enough for the result. + * @param radix Base to use, from 2 to 36. + * @return Pointer to string, or NULL if string is NULL or radix is out of range. + */ char *ultoa(unsigned long value, char *string, int radix) { char tmp[33]; @@ -106,11 +122,27 @@ char *ultoa(unsigned long value, char *string, int radix) return string; } +/** + * @brief Convert an int to a null-terminated string. + * + * @param value Value to convert. Negative values are only signed for radix 10. + * @param string Buffer to write the result to. Must be large enough for the result. + * @param radix Base to use, from 2 to 36. + * @return Pointer to string, or NULL if string is NULL or radix is out of range. + */ char *itoa(int value, char *string, int radix) { return ltoa(value, string, radix) ; } +/** + * @brief Convert an unsigned int to a null-terminated string. + * + * @param value Value to convert. + * @param string Buffer to write the result to. Must be large enough for the result. + * @param radix Base to use, from 2 to 36. + * @return Pointer to string, or NULL if string is NULL or radix is out of range. + */ char *utoa(unsigned value, char *string, int radix) { return ultoa(value, string, radix) ; diff --git a/cores/arduino/main.cpp b/cores/arduino/main.cpp index 67dbcfc44a..8b662a4551 100644 --- a/cores/arduino/main.cpp +++ b/cores/arduino/main.cpp @@ -20,8 +20,11 @@ #define ARDUINO_MAIN #include "Arduino.h" -// Force init to be called *first*, i.e. before static object allocation. -// Otherwise, statically allocated objects that need HAL may fail. +/** + * @brief Early initialization, run before static object allocation. + * + * Sets the NVIC priority grouping, enables the caches if present, then calls init(). + */ __attribute__((constructor(101))) void premain() { @@ -42,8 +45,10 @@ __attribute__((constructor(101))) void premain() init(); } -/* - * \brief Main entry point of Arduino application +/** + * @brief Main entry point of Arduino application. Runs setup() once, then loop() forever. + * + * @return 0. Not reached in practice, the loop never ends. */ int main(void) { diff --git a/cores/arduino/pins_arduino.c b/cores/arduino/pins_arduino.c index 6f1b316956..00240bf314 100644 --- a/cores/arduino/pins_arduino.c +++ b/cores/arduino/pins_arduino.c @@ -68,11 +68,6 @@ PinName analogInputToPinName(pin_size_t pin) return pn; } -/** - * @brief Return true if a digital pin is an analog input - * @param pin Dx, x or PYn - * @retval boolean true if analog or false - */ bool digitalpinIsAnalogInput(pin_size_t pin) { bool ret = false; @@ -91,11 +86,6 @@ bool digitalpinIsAnalogInput(pin_size_t pin) return ret; } -/** - * @brief Return the analog input linked to a digital pin - * @param pin Dx, x or PYn - * @retval analogInput valid analog input or NUM_ANALOG_INPUTS - */ pin_size_t digitalPinToAnalogInput(pin_size_t pin) { pin_size_t ret = NUM_ANALOG_INPUTS; diff --git a/cores/arduino/pins_arduino.h b/cores/arduino/pins_arduino.h index 7b109e9ec8..a12e3b9478 100644 --- a/cores/arduino/pins_arduino.h +++ b/cores/arduino/pins_arduino.h @@ -115,7 +115,12 @@ extern const pin_size_t analogInputPin[]; #define digitalPinToPinName(p) ((((pin_size_t)(p) & PNUM_MASK) < NUM_DIGITAL_PINS) ? \ (PinName)(digitalPin[(pin_size_t)(p) & PNUM_MASK] | ((p) & ALTX_MASK)) : NC) #endif /* NUM_ANALOG_INPUTS > 0 */ -/* Convert a PinName PX_n to a digital pin number */ +/** + * @brief Convert a PinName (PX_n) to a digital pin number. + * + * @param p PinName to convert. + * @return Digital pin number, with the ALTX bits preserved. NUM_DIGITAL_PINS if not found. + */ pin_size_t pinNametoDigitalPin(PinName p); /* Convert an analog pin number to a digital pin number */ @@ -131,7 +136,12 @@ pin_size_t pinNametoDigitalPin(PinName p); #define analogInputToDigitalPin(p) (NUM_DIGITAL_PINS) #endif /* NUM_ANALOG_INPUTS > 0 */ -/* Convert an analog pin number Ax to a PinName PX_n */ +/** + * @brief Convert an analog pin number (Ax) to a PinName (PX_n). + * + * @param pin Analog pin number, Ax. + * @return PinName of the analog input. NC if the pin is not an analog input. + */ PinName analogInputToPinName(pin_size_t pin); /* All pins could manage EXTI */ @@ -193,7 +203,19 @@ PinName analogInputToPinName(pin_size_t pin); #endif /* Convenient macro to handle Analog for Firmata */ #define pinIsAnalogInput digitalpinIsAnalogInput +/** + * @brief Check whether a digital pin is an analog input. + * + * @param pin Dx, x or PYn. + * @return true if the pin is an analog input, false otherwise. + */ bool digitalpinIsAnalogInput(pin_size_t pin); +/** + * @brief Get the analog input linked to a digital pin. + * + * @param pin Dx, x or PYn. + * @return Valid analog input number, or NUM_ANALOG_INPUTS if none. + */ pin_size_t digitalPinToAnalogInput(pin_size_t pin); #ifdef __cplusplus diff --git a/cores/arduino/wiring.h b/cores/arduino/wiring.h index d74e8ed58f..73e2708802 100644 --- a/cores/arduino/wiring.h +++ b/cores/arduino/wiring.h @@ -37,22 +37,22 @@ #ifdef __cplusplus extern "C" { #endif -/* - * \brief Set the resolution of analogRead return values. Default is 10 bits (range from 0 to 1023). +/** + * @brief Set the resolution of analogRead return values. Default is 10 bits (range from 0 to 1023). * - * \param res + * @param res Number of bits of the resolution, from 1 to 32. */ extern void analogReadResolution(int res); -/* - * \brief Set the resolution of analogWrite parameters. Default is 8 bits (range from 0 to 255). +/** + * @brief Set the resolution of analogWrite parameters. Default is 8 bits (range from 0 to 255). * - * \param res + * @param res Number of bits of the resolution, from 1 to 32. */ extern void analogWriteResolution(int res); -/* - * \brief Set the frequency of analogWrite. Default is PWM_FREQUENCY (1000) in Hertz. +/** + * @brief Set the frequency of analogWrite. Default is PWM_FREQUENCY (1000) in Hertz. * - * \param freq + * @param freq PWM frequency in Hertz. */ extern void analogWriteFrequency(uint32_t freq); @@ -75,9 +75,9 @@ extern void analogWriteFrequency(uint32_t freq); /* wiring_digital */ /** - * \brief Toggle the value from a specified digital pin. + * @brief Toggle the value from a specified digital pin. * - * \param ulPin The number of the digital pin you want to toggle (int) + * @param pinNumber The number of the digital pin you want to toggle. */ extern void digitalToggle(pin_size_t pinNumber); @@ -86,13 +86,21 @@ extern void digitalToggle(pin_size_t pinNumber); #endif #ifdef __cplusplus - /* - * \brief Stop tone generation on pin. - * - * \param _pin - */ + /** + * @brief Stop tone generation on pin. + * + * @param _pin The pin on which to stop tone generation. + * @param destruct If true, the tone timer is deinitialized and deleted. If false, it is only paused. + */ extern void noTone(uint8_t _pin, bool destruct); #if !defined(HAL_EXTI_MODULE_DISABLED) + /** + * @brief Attach a callback function to an external interrupt on a pin. + * + * @param pin The pin to attach the interrupt to. + * @param callback Function called when the interrupt fires. It takes no arguments. + * @param mode Trigger mode: CHANGE, RISING, FALLING, LOW or HIGH. + */ extern void attachInterrupt(pin_size_t pin, callback_function_t callback, PinStatus mode); #endif #endif diff --git a/cores/arduino/wiring_analog.c b/cores/arduino/wiring_analog.c index 603e6c2680..a8152eddab 100644 --- a/cores/arduino/wiring_analog.c +++ b/cores/arduino/wiring_analog.c @@ -80,7 +80,14 @@ static int _internalReadResolution = #endif /* ADC_RESOLUTION > MAX_ADC_RESOLUTION */ ; -/* Common utility function to map a value from one resolution to another */ +/** + * @brief Map a value from one resolution to another. + * + * @param value Value to convert. + * @param from Resolution of value, in bits. + * @param to Target resolution, in bits. + * @return Value scaled to the target resolution. + */ static inline uint32_t mapResolution(uint32_t value, uint32_t from, uint32_t to) { if (from != to) { @@ -154,13 +161,22 @@ void analogReadResolution(int res) } } +/** + * @brief Set the analog reference voltage. Not supported on this core, the call has no effect. + * + * @param mode Reference mode, ignored. + */ void analogReference(uint8_t mode) { (void)mode; } -// Perform the read operation on the selected analog pin. -// the initialization of the analog PIN is done through this function +/** + * @brief Read the analog value of a pin, scaled to the resolution set by analogReadResolution(). + * + * @param pinNumber Analog pin number, e.g. A0 or PA0. + * @return Converted value, between 0 and 2^resolution - 1. 0 if the pin has no ADC. + */ int analogRead(pin_size_t pinNumber) { pin_size_t value = 0; @@ -198,8 +214,14 @@ void analogWriteFrequency(uint32_t freq) _writeFreq = freq; } -// Output only works on the pins with Hardware Timer (PWM) or DAC support. -// For the other pins, default to digital output. +/** + * @brief Write an analog value to a pin, using PWM or DAC if the pin supports it. + * + * Pins without a timer or DAC output fall back to digital output. + * + * @param pinNumber Pin number to write to. + * @param value Value to write, scaled to the resolution set by analogWriteResolution(). + */ void analogWrite(pin_size_t pinNumber, int value) { PinName p = digitalPinToPinName(pinNumber); diff --git a/cores/arduino/wiring_digital.c b/cores/arduino/wiring_digital.c index 104ce20904..9a66326743 100644 --- a/cores/arduino/wiring_digital.c +++ b/cores/arduino/wiring_digital.c @@ -26,6 +26,12 @@ extern "C" { extern pin_size_t g_anOutputPinConfigured[MAX_NB_PORT]; +/** + * @brief Set the mode of a pin. + * + * @param pinNumber Pin number, Dx or x. + * @param pinMode INPUT, INPUT_PULLUP, INPUT_PULLDOWN, INPUT_ANALOG, OUTPUT or OUTPUT_OPEN_DRAIN. + */ void pinMode(pin_size_t pinNumber, PinMode pinMode) { PinName p = digitalPinToPinName(pinNumber); @@ -79,6 +85,12 @@ void pinMode(pin_size_t pinNumber, PinMode pinMode) } } +/** + * @brief Write a HIGH or LOW value to a digital pin. + * + * @param pinNumber Pin number, Dx or x. + * @param status HIGH or LOW. + */ void digitalWrite(pin_size_t pinNumber, PinStatus status) { PinName p = digitalPinToPinName(pinNumber); @@ -87,6 +99,12 @@ void digitalWrite(pin_size_t pinNumber, PinStatus status) } } +/** + * @brief Read the value of a digital pin. + * + * @param pinNumber Pin number, Dx or x. + * @return HIGH or LOW. LOW if the pin is invalid. + */ PinStatus digitalRead(pin_size_t pinNumber) { PinName p = digitalPinToPinName(pinNumber); diff --git a/cores/arduino/wiring_pulse.cpp b/cores/arduino/wiring_pulse.cpp index fcaf974e35..0423105b18 100644 --- a/cores/arduino/wiring_pulse.cpp +++ b/cores/arduino/wiring_pulse.cpp @@ -18,13 +18,18 @@ #include "Arduino.h" -/* Measures the length (in microseconds) of a pulse on the pin; state is HIGH - * or LOW, the type of pulse to measure. Works on pulses from 2-3 microseconds - * to 3 minutes in length, but must be called at least a few dozen microseconds - * before the start of the pulse. +/** + * @brief Measures the length (in microseconds) of a pulse on the pin. * - * ATTENTION: - * This function relies on micros() so cannot be used in noInterrupt() context + * Works on pulses from 2-3 microseconds to 3 minutes in length, but must be + * called at least a few dozen microseconds before the start of the pulse. + * + * @note This function relies on micros() so cannot be used in noInterrupt() context. + * + * @param pin Pin number, Dx or x. + * @param state HIGH or LOW, the type of pulse to measure. + * @param timeout Maximum time to wait for the pulse, in microseconds. + * @return Length of the pulse in microseconds, or 0 if no pulse started before the timeout. */ unsigned long pulseIn(pin_size_t pin, uint8_t state, unsigned long timeout) { @@ -60,13 +65,17 @@ unsigned long pulseIn(pin_size_t pin, uint8_t state, unsigned long timeout) return (micros() - start); } -/* Measures the length (in microseconds) of a pulse on the pin; state is HIGH - * or LOW, the type of pulse to measure. Works on pulses from 2-3 microseconds - * to 3 minutes in length, but must be called at least a few dozen microseconds - * before the start of the pulse. +/** + * @brief Measures the length (in microseconds) of a pulse on the pin. + * + * Same as pulseIn(); provided for compatibility with the AVR core. + * + * @note This function relies on micros() so cannot be used in noInterrupt() context. * - * ATTENTION: - * This function relies on micros() so cannot be used in noInterrupt() context + * @param pin Pin number, Dx or x. + * @param state HIGH or LOW, the type of pulse to measure. + * @param timeout Maximum time to wait for the pulse, in microseconds. + * @return Length of the pulse in microseconds, or 0 if no pulse started before the timeout. */ unsigned long pulseInLong(pin_size_t pin, uint8_t state, unsigned long timeout) { diff --git a/cores/arduino/wiring_shift.c b/cores/arduino/wiring_shift.c index 84ff859cce..2c88f720f5 100644 --- a/cores/arduino/wiring_shift.c +++ b/cores/arduino/wiring_shift.c @@ -22,6 +22,14 @@ extern "C" { #endif +/** + * @brief Shift in a byte of data one bit at a time. + * + * @param dataPin Pin number to read the data from. + * @param clockPin Pin number to clock the data on. + * @param bitOrder LSBFIRST or MSBFIRST. + * @return The byte read. + */ uint8_t shiftIn(pin_size_t dataPin, pin_size_t clockPin, BitOrder bitOrder) { uint8_t value = 0 ; @@ -42,6 +50,14 @@ uint8_t shiftIn(pin_size_t dataPin, pin_size_t clockPin, BitOrder bitOrder) return value ; } +/** + * @brief Shift out a byte of data one bit at a time. + * + * @param dataPin Pin number to write the data to. + * @param clockPin Pin number to clock the data on. + * @param bitOrder LSBFIRST or MSBFIRST. + * @param val Byte to shift out. + */ void shiftOut(pin_size_t dataPin, pin_size_t clockPin, BitOrder bitOrder, uint8_t val) { uint8_t i ; diff --git a/cores/arduino/wiring_time.c b/cores/arduino/wiring_time.c index f622c7e1d7..27ff9a36dc 100644 --- a/cores/arduino/wiring_time.c +++ b/cores/arduino/wiring_time.c @@ -22,18 +22,36 @@ extern "C" { #endif +/** + * @brief Get the number of milliseconds since the board started. + * + * @return Milliseconds since startup. Overflows after about 49 days. + */ unsigned long millis(void) { // ToDo: ensure no interrupts return getCurrentMillis(); } -// Interrupt-compatible version of micros +/** + * @brief Get the number of microseconds since the board started. + * + * Interrupt-compatible version. + * + * @return Microseconds since startup. Overflows after about 70 minutes. + */ unsigned long micros(void) { return getCurrentMicros(); } +/** + * @brief Pause the program for the given number of milliseconds. + * + * Calls yield() while waiting. + * + * @param ms Number of milliseconds to pause. + */ void delay(unsigned long ms) { if (ms != 0) { @@ -45,9 +63,9 @@ void delay(unsigned long ms) } /** - * \brief Pauses the program for the amount of time (in microseconds) specified as parameter. + * @brief Pauses the program for the amount of time (in microseconds) specified as parameter. * - * \param us the number of microseconds to pause (unsigned int) + * @param us the number of microseconds to pause (unsigned int) */ void delayMicroseconds(unsigned int us) @@ -76,17 +94,16 @@ void delayMicroseconds(unsigned int us) } /** - * \brief gives the number of seconds and microseconds since the Epoch - * - * based on millisecond since last power on. + * @brief Gives the number of seconds and microseconds since the Epoch. * - * \note The function is declared as weak to be overwritten in case of other - * implementations in user file (using RTC values for example). + * Based on milliseconds since last power on. * - * \param tv argument is a struct timeval - * \param tz argument is a struct timezone (unused) + * @note The function is declared as weak to be overwritten in case of other + * implementations in user file (using RTC values for example). * - * \return 0 + * @param tv Argument is a struct timeval. + * @param tz Argument is a struct timezone (unused). + * @return 0 */ int __attribute__((weak)) _gettimeofday(struct timeval *tv, void *tz) { diff --git a/libraries/EEPROM/src/EEPROM.h b/libraries/EEPROM/src/EEPROM.h index c95cb0cdda..4c8a85d725 100644 --- a/libraries/EEPROM/src/EEPROM.h +++ b/libraries/EEPROM/src/EEPROM.h @@ -28,20 +28,26 @@ extern "C" { #if defined(USE_HALV2_DRIVER) #warning "EEPROM library is not yet compatible with HALv2 driver." #endif -/*** - EERef class. - - This object references an EEPROM cell. - Its purpose is to mimic a typical byte of RAM, however its storage is the EEPROM. - This class has an overhead of two bytes, similar to storing a pointer to an EEPROM cell. -***/ - +/** + * @brief EERef class. + * + * This object references an EEPROM cell. + * Its purpose is to mimic a typical byte of RAM, however its storage is the EEPROM. + * This class has an overhead of two bytes, similar to storing a pointer to an EEPROM cell. + */ struct EERef { + /** + * @brief Construct a reference to an EEPROM cell. + * @param idx Index of the EEPROM cell. + */ EERef(const int idx) : index(idx) {} - //Access/read members. + /** + * @brief Read the value of the referenced EEPROM cell. + * @return Value stored in the EEPROM cell. + */ uint8_t operator*() const { #if defined(USE_HALV2_DRIVER) @@ -50,16 +56,29 @@ struct EERef { return eeprom_read_byte(/*(uint8_t*)*/ index); #endif } + /** + * @brief Implicit conversion to uint8_t, reads the referenced EEPROM cell. + * @return Value stored in the EEPROM cell. + */ operator uint8_t() const { return **this; } - //Assignment/write members. + /** + * @brief Write the value of another EERef to the referenced EEPROM cell. + * @param ref Reference whose value is written. + * @return Reference to this object. + */ EERef &operator=(const EERef &ref) { return *this = *ref; } + /** + * @brief Write a byte to the referenced EEPROM cell. + * @param in Value to write. + * @return Reference to this object. + */ EERef &operator=(uint8_t in) { #if defined(USE_HALV2_DRIVER) @@ -68,69 +87,138 @@ struct EERef { return eeprom_write_byte(/*(uint8_t*)*/ index, in), *this; #endif } + /** + * @brief Add a value to the stored value and write the result back. + * @param in Operand. + * @return Reference to this object. + */ EERef &operator +=(uint8_t in) { return *this = **this + in; } + /** + * @brief Subtract a value from the stored value and write the result back. + * @param in Operand. + * @return Reference to this object. + */ EERef &operator -=(uint8_t in) { return *this = **this - in; } + /** + * @brief Multiply the stored value by a value and write the result back. + * @param in Operand. + * @return Reference to this object. + */ EERef &operator *=(uint8_t in) { return *this = **this * in; } + /** + * @brief Divide the stored value by a value and write the result back. + * @param in Operand. + * @return Reference to this object. + */ EERef &operator /=(uint8_t in) { return *this = **this / in; } + /** + * @brief Bitwise XOR the stored value with a value and write the result back. + * @param in Operand. + * @return Reference to this object. + */ EERef &operator ^=(uint8_t in) { return *this = **this ^ in; } + /** + * @brief Modulo the stored value by a value and write the result back. + * @param in Operand. + * @return Reference to this object. + */ EERef &operator %=(uint8_t in) { return *this = **this % in; } + /** + * @brief Bitwise AND the stored value with a value and write the result back. + * @param in Operand. + * @return Reference to this object. + */ EERef &operator &=(uint8_t in) { return *this = **this & in; } + /** + * @brief Bitwise OR the stored value with a value and write the result back. + * @param in Operand. + * @return Reference to this object. + */ EERef &operator |=(uint8_t in) { return *this = **this | in; } + /** + * @brief Left shift the stored value by a value and write the result back. + * @param in Number of bits to shift. + * @return Reference to this object. + */ EERef &operator <<=(uint8_t in) { return *this = **this << in; } + /** + * @brief Right shift the stored value by a value and write the result back. + * @param in Number of bits to shift. + * @return Reference to this object. + */ EERef &operator >>=(uint8_t in) { return *this = **this >> in; } + /** + * @brief Write a value only if it differs from the stored value, to reduce EEPROM wear. + * @param in Value to write. + * @return Reference to this object. + */ EERef &update(uint8_t in) { return in != *this ? *this = in : *this; } - /** Prefix increment/decrement **/ + /** + * @brief Prefix increment of the stored value. + * @return Reference to this object. + */ EERef &operator++() { return *this += 1; } + /** + * @brief Prefix decrement of the stored value. + * @return Reference to this object. + */ EERef &operator--() { return *this -= 1; } - /** Postfix increment/decrement **/ + /** + * @brief Postfix increment of the stored value. + * @return Value stored before the increment. + */ uint8_t operator++ (int) { uint8_t ret = **this; return ++(*this), ret; } + /** + * @brief Postfix decrement of the stored value. + * @return Value stored before the decrement. + */ uint8_t operator-- (int) { uint8_t ret = **this; @@ -140,51 +228,86 @@ struct EERef { int index; //Index of current EEPROM cell. }; -/*** - EEPtr class. - - This object is a bidirectional pointer to EEPROM cells represented by EERef objects. - Just like a normal pointer type, this can be dereferenced and repositioned using - increment/decrement operators. -***/ - +/** + * @brief EEPtr class. + * + * This object is a bidirectional pointer to EEPROM cells represented by EERef objects. + * Just like a normal pointer type, this can be dereferenced and repositioned using + * increment/decrement operators. + */ struct EEPtr { + /** + * @brief Construct a pointer to an EEPROM cell. + * @param idx Index of the EEPROM cell. + */ EEPtr(const int idx) : index(idx) {} + /** + * @brief Implicit conversion to the index of the pointed EEPROM cell. + * @return Index of the EEPROM cell. + */ operator int() const { return index; } + /** + * @brief Set the index of the pointed EEPROM cell. + * @param in New index. + * @return Reference to this object. + */ EEPtr &operator=(int in) { return index = in, *this; } - //Iterator functionality. + /** + * @brief Compare the index of this pointer with another pointer. + * @param ptr Pointer to compare with. + * @return true if the indices differ, false otherwise. + */ bool operator!=(const EEPtr &ptr) { return index != ptr.index; } + /** + * @brief Dereference the pointer. + * @return EERef referencing the pointed EEPROM cell. + */ EERef operator*() { return index; } - /** Prefix & Postfix increment/decrement **/ + /** + * @brief Prefix increment, move the pointer to the next EEPROM cell. + * @return Reference to this object. + */ EEPtr &operator++() { return ++index, *this; } + /** + * @brief Prefix decrement, move the pointer to the previous EEPROM cell. + * @return Reference to this object. + */ EEPtr &operator--() { return --index, *this; } + /** + * @brief Postfix increment, move the pointer to the next EEPROM cell. + * @return Copy of the pointer before the increment. + */ EEPtr operator++ (int) { return index++; } + /** + * @brief Postfix decrement, move the pointer to the previous EEPROM cell. + * @return Copy of the pointer before the decrement. + */ EEPtr operator-- (int) { return index--; @@ -193,43 +316,72 @@ struct EEPtr { int index; //Index of current EEPROM cell. }; -/*** - EEPROMClass class. - - This object represents the entire EEPROM space. - It wraps the functionality of EEPtr and EERef into a basic interface. - This class is also 100% backwards compatible with earlier Arduino core releases. -***/ - +/** + * @brief EEPROMClass class. + * + * This object represents the entire EEPROM space. + * It wraps the functionality of EEPtr and EERef into a basic interface. + * This class is also 100% backwards compatible with earlier Arduino core releases. + */ struct EEPROMClass { - //Basic user access methods. + /** + * @brief Access the EEPROM cell at an index. + * @param idx Index of the EEPROM cell. + * @return EERef referencing the EEPROM cell. + */ EERef operator[](const int idx) { return idx; } + /** + * @brief Read a byte from EEPROM. + * @param idx Index of the EEPROM cell. + * @return Value stored in the EEPROM cell. + */ uint8_t read(int idx) { return EERef(idx); } + /** + * @brief Write a byte to EEPROM. + * @param idx Index of the EEPROM cell. + * @param val Value to write. + */ void write(int idx, uint8_t val) { (EERef(idx)) = val; } + /** + * @brief Write a byte to EEPROM only if it differs from the stored value, to reduce EEPROM wear. + * @param idx Index of the EEPROM cell. + * @param val Value to write. + */ void update(int idx, uint8_t val) { EERef(idx).update(val); } - //STL and C++11 iteration capability. + /** + * @brief Get an iterator to the first EEPROM cell (STL and C++11 iteration). + * @return EEPtr pointing to index 0. + */ EEPtr begin() { return 0x00; } + /** + * @brief Get an iterator to the item after the last EEPROM cell (STL and C++11 iteration). + * @return EEPtr pointing past the last valid cell, it must not be dereferenced. + */ EEPtr end() { return length(); //Standards requires this to be the item after the last valid entry. The returned pointer is invalid. } + /** + * @brief Get the number of EEPROM bytes available. + * @return Size of the EEPROM in bytes, 0 when USE_HALV2_DRIVER is defined. + */ uint16_t length() { #if defined(USE_HALV2_DRIVER) @@ -239,7 +391,13 @@ struct EEPROMClass { #endif } - //Functionality to 'get' and 'put' objects to and from EEPROM. + /** + * @brief Read an object from EEPROM. + * @tparam T Type of the object. + * @param idx Index of the first EEPROM cell to read. + * @param t Object to fill with the values read from EEPROM. + * @return Reference to t. + */ template< typename T > T &get(int idx, T &t) { EEPtr e = idx; @@ -250,6 +408,13 @@ struct EEPROMClass { return t; } + /** + * @brief Write an object to EEPROM. Only the bytes that differ from the stored values are written. + * @tparam T Type of the object. + * @param idx Index of the first EEPROM cell to write. + * @param t Object to write. + * @return Reference to t. + */ template< typename T > const T &put(int idx, const T &t) { EEPtr e = idx; diff --git a/libraries/EEPROM/src/utility/stm32_eeprom.c b/libraries/EEPROM/src/utility/stm32_eeprom.c index 76c278dc17..20b10343cc 100644 --- a/libraries/EEPROM/src/utility/stm32_eeprom.c +++ b/libraries/EEPROM/src/utility/stm32_eeprom.c @@ -112,11 +112,6 @@ extern "C" { static uint8_t eeprom_buffer[E2END + 1] __attribute__((aligned(8))) = {0}; #endif -/** - * @brief Function reads a byte from emulated eeprom (flash) - * @param pos : address to read - * @retval byte : data read from eeprom - */ uint8_t eeprom_read_byte(const uint32_t pos) { #if defined(DATA_EEPROM_BASE) @@ -132,12 +127,6 @@ uint8_t eeprom_read_byte(const uint32_t pos) #endif /* _EEPROM_BASE */ } -/** - * @brief Function writes a byte to emulated eeprom (flash) - * @param pos : address to write - * @param value : value to write - * @retval none - */ void eeprom_write_byte(uint32_t pos, uint8_t value) { #if defined(DATA_EEPROM_BASE) @@ -156,32 +145,16 @@ void eeprom_write_byte(uint32_t pos, uint8_t value) #if !defined(DATA_EEPROM_BASE) -/** - * @brief Function reads a byte from the eeprom buffer - * @param pos : address to read - * @retval byte : data read from eeprom - */ uint8_t eeprom_buffered_read_byte(const uint32_t pos) { return eeprom_buffer[pos]; } -/** - * @brief Function writes a byte to the eeprom buffer - * @param pos : address to write - * @param value : value to write - * @retval none - */ void eeprom_buffered_write_byte(uint32_t pos, uint8_t value) { eeprom_buffer[pos] = value; } -/** - * @brief This function copies the data from flash into the buffer - * @param none - * @retval none - */ void eeprom_buffer_fill(void) { #if defined(ICACHE) && defined (HAL_ICACHE_MODULE_ENABLED) && !defined(HAL_ICACHE_MODULE_DISABLED) @@ -207,11 +180,6 @@ void eeprom_buffer_fill(void) #if defined(EEPROM_RETRAM_MODE) -/** - * @brief This function writes the buffer content into the flash - * @param none - * @retval none - */ void eeprom_buffer_flush(void) { memcpy((uint8_t *)(FLASH_BASE_ADDRESS), eeprom_buffer, E2END + 1); @@ -219,11 +187,6 @@ void eeprom_buffer_flush(void) #else /* defined(EEPROM_RETRAM_MODE) */ -/** - * @brief This function writes the buffer content into the flash - * @param none - * @retval none - */ void eeprom_buffer_flush(void) { #if defined(ICACHE) && defined (HAL_ICACHE_MODULE_ENABLED) && !defined(HAL_ICACHE_MODULE_DISABLED) diff --git a/libraries/EEPROM/src/utility/stm32_eeprom.h b/libraries/EEPROM/src/utility/stm32_eeprom.h index 995d25e6a1..80c84443d2 100644 --- a/libraries/EEPROM/src/utility/stm32_eeprom.h +++ b/libraries/EEPROM/src/utility/stm32_eeprom.h @@ -110,13 +110,39 @@ extern "C" { /* Exported macro ------------------------------------------------------------*/ /* Exported functions ------------------------------------------------------- */ +/** + * @brief Read a byte from the emulated EEPROM (flash). + * @param pos Address to read. + * @return Data read from EEPROM. + */ uint8_t eeprom_read_byte(const uint32_t pos); +/** + * @brief Write a byte to the emulated EEPROM (flash). + * @param pos Address to write. + * @param value Value to write. + */ void eeprom_write_byte(uint32_t pos, uint8_t value); #if !defined(DATA_EEPROM_BASE) +/** + * @brief Copy the data from flash into the EEPROM buffer. + */ void eeprom_buffer_fill(); +/** + * @brief Write the EEPROM buffer content into flash. + */ void eeprom_buffer_flush(); +/** + * @brief Read a byte from the EEPROM buffer. + * @param pos Address to read. + * @return Data read from the EEPROM buffer. + */ uint8_t eeprom_buffered_read_byte(const uint32_t pos); +/** + * @brief Write a byte to the EEPROM buffer, flash is not updated. + * @param pos Address to write. + * @param value Value to write. + */ void eeprom_buffered_write_byte(uint32_t pos, uint8_t value); #endif /* ! DATA_EEPROM_BASE */ diff --git a/libraries/IWatchdog/src/IWatchdog.cpp b/libraries/IWatchdog/src/IWatchdog.cpp index af2ede57b1..81460aa926 100644 --- a/libraries/IWatchdog/src/IWatchdog.cpp +++ b/libraries/IWatchdog/src/IWatchdog.cpp @@ -31,13 +31,6 @@ IWatchdogClass::IWatchdogClass() #endif } -/** - * @brief Enable IWDG, must be called once - * @param timeout: value in microseconds - * @param window: optional value in microseconds - * Default: IWDG_TIMEOUT_MAX - * @retval None - */ void IWatchdogClass::begin(uint32_t timeout, uint32_t window) { if (!IS_IWDG_TIMEOUT(timeout)) { @@ -64,13 +57,6 @@ void IWatchdogClass::begin(uint32_t timeout, uint32_t window) set(timeout, window); } -/** - * @brief Set the timeout and window values - * @param timeout: value in microseconds - * @param window: optional value in microseconds - * Default: IWDG_TIMEOUT_MAX - * @retval None - */ void IWatchdogClass::set(uint32_t timeout, uint32_t window) { if ((isEnabled()) && (!IS_IWDG_TIMEOUT(timeout))) { @@ -139,12 +125,6 @@ void IWatchdogClass::set(uint32_t timeout, uint32_t window) LL_IWDG_ReloadCounter(IWDG); } -/** - * @brief Get the current timeout and window values - * @param timeout: pointer to the get the value in microseconds - * @param window: optional pointer to the get the value in microseconds - * @retval None - */ void IWatchdogClass::get(uint32_t *timeout, uint32_t *window) { if (timeout != NULL) { @@ -172,10 +152,6 @@ void IWatchdogClass::get(uint32_t *timeout, uint32_t *window) } } -/** - * @brief Reload the counter value with IWDG_RLR (IWDG_KR = 0x0000 AAAA) - * @retval None - */ void IWatchdogClass::reload(void) { if (isEnabled()) { @@ -183,11 +159,6 @@ void IWatchdogClass::reload(void) } } -/** - * @brief Check if the system has resumed from IWDG reset - * @param clear: if true clear IWDG reset flag. Default false - * @retval return reset flag status - */ bool IWatchdogClass::isReset(bool clear) { #if defined(IWDG1) @@ -205,10 +176,6 @@ bool IWatchdogClass::isReset(bool clear) return status; } -/** - * @brief Clear IWDG reset flag - * @retval None - */ void IWatchdogClass::clearReset(void) { #if defined(USE_HALV2_DRIVER) diff --git a/libraries/IWatchdog/src/IWatchdog.h b/libraries/IWatchdog/src/IWatchdog.h index 44816e6f1e..af6b1c34a3 100644 --- a/libraries/IWatchdog/src/IWatchdog.h +++ b/libraries/IWatchdog/src/IWatchdog.h @@ -34,19 +34,55 @@ #define IS_IWDG_TIMEOUT(X) (((X) >= IWDG_TIMEOUT_MIN) &&\ ((X) <= IWDG_TIMEOUT_MAX)) +/** + * @brief Independent watchdog (IWDG) controller, exposed as the global IWatchdog object. + */ class IWatchdogClass { public: + /** + * @brief Construct the controller and enable the watchdog peripheral clock when required. + */ IWatchdogClass(); + /** + * @brief Enable the IWDG. Must be called only once. + * @param timeout Timeout in microseconds. Ignored if it is not valid (see IS_IWDG_TIMEOUT()). + * @param window Optional window in microseconds. Default: IWDG_TIMEOUT_MAX. + */ void begin(uint32_t timeout, uint32_t window = IWDG_TIMEOUT_MAX); + /** + * @brief Set the timeout and window values of the watchdog and refresh its counter. + * @param timeout Timeout in microseconds. Ignored if the watchdog is enabled and the value is not valid. + * @param window Optional window in microseconds. Default: IWDG_TIMEOUT_MAX. + */ void set(uint32_t timeout, uint32_t window = IWDG_TIMEOUT_MAX); + /** + * @brief Get the current timeout and window values of the watchdog. + * @param timeout Pointer where the timeout in microseconds is stored. Nothing is done if NULL. + * @param window Optional pointer where the window in microseconds is stored. Default: NULL. + */ void get(uint32_t *timeout, uint32_t *window = NULL); + /** + * @brief Reload the counter to prevent a watchdog reset. Does nothing if the watchdog is not enabled. + */ void reload(void); + /** + * @brief Check whether the watchdog has been enabled with begin(). + * @return true if the watchdog is enabled, false otherwise. + */ bool isEnabled(void) { return _enabled; }; + /** + * @brief Check if the system has resumed from an IWDG reset. + * @param clear If true, clear the IWDG reset flag after reading it. Default: false. + * @return true if the last reset was caused by the IWDG, false otherwise. + */ bool isReset(bool clear = false); + /** + * @brief Clear the IWDG reset flag. + */ void clearReset(void); private: diff --git a/libraries/RGB_LED_TLC59731/src/RGB_LED_TLC59731.cpp b/libraries/RGB_LED_TLC59731/src/RGB_LED_TLC59731.cpp index 9431a2a74b..5a1f077296 100644 --- a/libraries/RGB_LED_TLC59731/src/RGB_LED_TLC59731.cpp +++ b/libraries/RGB_LED_TLC59731/src/RGB_LED_TLC59731.cpp @@ -26,23 +26,11 @@ uint8_t RGB_LED_TLC59731::CYAN[3] = {0, DEFAULT_BRIGHTNESS, uint8_t RGB_LED_TLC59731::YELLOW[3] = {DEFAULT_BRIGHTNESS, DEFAULT_BRIGHTNESS, 0 }; uint8_t RGB_LED_TLC59731::WHITE[3] = {DEFAULT_BRIGHTNESS, DEFAULT_BRIGHTNESS, DEFAULT_BRIGHTNESS}; -/** - * @brief Set RGB LED color - * @param rgb[3]: red,green, blue value in range [0-255] - * @retval None - */ void RGB_LED_TLC59731::on(uint8_t rgb[3]) { on(rgb[0], rgb[1], rgb[2]); } -/** - * @brief Set RGB LED color - * @param red: red value in range [0-255] - * @param green: green value in range [0-255] - * @param blue: blue value in range [0-255] - * @retval None - */ void RGB_LED_TLC59731::on(uint8_t red, uint8_t green, uint8_t blue) { if (!_enabled) { @@ -69,11 +57,6 @@ void RGB_LED_TLC59731::on(uint8_t red, uint8_t green, uint8_t blue) delayMicroseconds(_T_GS_Lat); } -/** - * @brief Set RGB LED Off - * @param None - * @retval None - */ void RGB_LED_TLC59731::off(void) { /* Set RGB LED off value */ @@ -87,11 +70,6 @@ void RGB_LED_TLC59731::off(void) } } -/** - * @brief Set brightness value - * @param value: new brightness value - * @retval None - */ void RGB_LED_TLC59731::setBrightness(uint8_t value) { RGB_LED_TLC59731::brightness = value; diff --git a/libraries/RGB_LED_TLC59731/src/RGB_LED_TLC59731.h b/libraries/RGB_LED_TLC59731/src/RGB_LED_TLC59731.h index 44d3bde619..e82233ce58 100644 --- a/libraries/RGB_LED_TLC59731/src/RGB_LED_TLC59731.h +++ b/libraries/RGB_LED_TLC59731/src/RGB_LED_TLC59731.h @@ -20,28 +20,68 @@ #warning "LED_BUILTIN is not defined." #endif +/** + * @brief Driver for an RGB LED controlled by a TLC59731 driver through a single wire interface. + */ class RGB_LED_TLC59731 { public: + /** + * @brief Construct the driver and select the pins used to drive the LED. + * @param rgb_pin Pin connected to the TLC59731 data input. Default: LED_BUILTIN. + * @param enable_pin Pin connected to the TLC59731 enable line, NC if not used. Default: NC. + */ RGB_LED_TLC59731(pin_size_t rgb_pin = LED_BUILTIN, pin_size_t enable_pin = NC): _rgb_pin(digitalPinToPinName(rgb_pin)), _enable_pin(digitalPinToPinName(enable_pin)) {}; + /** + * @brief Set the RGB LED color. + * @param rgb Array of red, green and blue values in range [0-255]. + */ void on(uint8_t rgb[3]); + /** + * @brief Set the RGB LED color. + * @param red Red value in range [0-255]. + * @param green Green value in range [0-255]. + * @param blue Blue value in range [0-255]. + */ void on(uint8_t red, uint8_t green, uint8_t blue); + /** + * @brief Turn the RGB LED off and release its pins. + */ void off(void); + /** + * @brief Get the current brightness value. + * @return Brightness value. + */ inline uint8_t getBrightness(void) { return brightness; } + /** + * @brief Set the brightness value, applied to the predefined colors. + * @param value New brightness value. + */ void setBrightness(uint8_t value); + /** + * @brief Current brightness value, used by the predefined colors. + */ static uint8_t brightness; + /** @brief Predefined color: off (no light). */ static uint8_t OFF[3]; + /** @brief Predefined color: red. */ static uint8_t RED[3]; + /** @brief Predefined color: green. */ static uint8_t GREEN[3]; + /** @brief Predefined color: blue. */ static uint8_t BLUE[3]; + /** @brief Predefined color: magenta. */ static uint8_t MAGENTA[3]; + /** @brief Predefined color: cyan. */ static uint8_t CYAN[3]; + /** @brief Predefined color: yellow. */ static uint8_t YELLOW[3]; + /** @brief Predefined color: white. */ static uint8_t WHITE[3]; private: @@ -55,7 +95,15 @@ class RGB_LED_TLC59731 { // GS Data Latch (GSLAT) Sequence delay const uint32_t _T_GS_Lat{_T_Cycle0 * 8}; + /** + * @brief Send one bit to the TLC59731 using its pulse width timing. + * @param bit Bit value to send (0 or 1). + */ void sendBit(uint8_t bit); + /** + * @brief Send one byte to the TLC59731, most significant bit first. + * @param byte Byte value to send. + */ void senByte(uint8_t byte); }; diff --git a/libraries/SPI/src/SPI.cpp b/libraries/SPI/src/SPI.cpp index 6515471f57..4bf4fe320a 100644 --- a/libraries/SPI/src/SPI.cpp +++ b/libraries/SPI/src/SPI.cpp @@ -13,28 +13,6 @@ SPIClass SPI; -/** - * @brief Default Constructor. Uses pin configuration of default SPI - * defined in the variant*.h. - * To create another SPI instance attached to another SPI - * peripheral gave the pins as parameters to the constructor. - * @note All pins must be attached to the same SPI peripheral. - * See datasheet of the microcontroller. - * @param mosi: SPI mosi pin. Accepted format: number or Arduino format (Dx) - * or ST format (Pxy). Default is MOSI pin of the default SPI peripheral. - * @param miso: SPI miso pin. Accepted format: number or Arduino format (Dx) - * or ST format (Pxy). Default is MISO pin of the default SPI peripheral. - * @param sclk: SPI clock pin. Accepted format: number or Arduino format (Dx) - * or ST format (Pxy). Default is SCK pin of the default SPI peripheral. - * @param ssel: SPI ssel pin (optional). Accepted format: number or - * Arduino format (Dx) or ST format (Pxy). By default is set to NC. - * This pin must correspond to a hardware CS pin which can be managed - * by the SPI peripheral itself. See the datasheet of the microcontroller - * or look at PinMap_SPI_SSEL[] inside the file PeripheralPins.c - * corresponding to the board. If you configure this pin you can't use - * another CS pin and don't pass a CS pin as parameter to any functions - * of the class. - */ SPIClass::SPIClass(pin_size_t mosi, pin_size_t miso, pin_size_t sclk, pin_size_t ssel) { memset((void *)&_spi, 0, sizeof(_spi)); @@ -44,10 +22,6 @@ SPIClass::SPIClass(pin_size_t mosi, pin_size_t miso, pin_size_t sclk, pin_size_t _spi.pin_ssel = digitalPinToPinName(ssel); } -/** - * @brief Initialize the SPI instance. - * @param busMode: bus mode (optional), controller or peripheral. Default is master. - */ void SPIClass::begin(SPIBusMode busMode) { #if !defined(USE_HALV2_DRIVER) @@ -59,11 +33,6 @@ void SPIClass::begin(SPIBusMode busMode) _spiSettings.getBitOrder(), (spi_busmode_e)_spiSettings.getBusMode()); } -/** - * @brief This function should be used to configure the SPI instance in case you - * don't use the default parameters set by the begin() function. - * @param settings: SPI settings(clock speed, bit order, data mode, bus mode). - */ void SPIClass::beginTransaction(SPISettings settings) { if (_spiSettings != settings) { @@ -73,46 +42,22 @@ void SPIClass::beginTransaction(SPISettings settings) } } -/** - * @brief End the transaction after beginTransaction usage - */ void SPIClass::endTransaction(void) { } -/** - * @brief Deinitialize the SPI instance and stop it. - */ void SPIClass::end(void) { spi_deinit(&_spi); } -/** - * @brief Transfer one byte on the SPI bus. - * begin() or beginTransaction() must be called at least once before. - * @param data: byte to send. - * @param skipReceive: skip receiving data after transmit or not. - * SPI_TRANSMITRECEIVE or SPI_TRANSMITONLY. - * Optional, default: SPI_TRANSMITRECEIVE. - * @return byte received from the slave. - */ uint8_t SPIClass::transfer(uint8_t data, bool skipReceive) { spi_transfer(&_spi, &data, (!skipReceive) ? &data : NULL, sizeof(uint8_t)); return data; } -/** - * @brief Transfer two bytes on the SPI bus in 16 bits format. - * begin() or beginTransaction() must be called at least once before. - * @param data: bytes to send. - * @param skipReceive: skip receiving data after transmit or not. - * SPI_TRANSMITRECEIVE or SPI_TRANSMITONLY. - * Optional, default: SPI_TRANSMITRECEIVE. - * @return bytes received from the slave in 16 bits format. - */ uint16_t SPIClass::transfer16(uint16_t data, bool skipReceive) { uint16_t tmp; @@ -131,66 +76,33 @@ uint16_t SPIClass::transfer16(uint16_t data, bool skipReceive) return data; } -/** - * @brief Transfer several bytes. Only one buffer used to send and receive data. - * begin() or beginTransaction() must be called at least once before. - * @param buf: pointer to the bytes to send. The bytes received are copy in - * this buffer. - * @param count: number of bytes to send/receive. - * @param skipReceive: skip receiving data after transmit or not. - * SPI_TRANSMITRECEIVE or SPI_TRANSMITONLY. - * Optional, default: SPI_TRANSMITRECEIVE. - */ void SPIClass::transfer(void *buf, size_t count, bool skipReceive) { spi_transfer(&_spi, (uint8_t *)buf, (!skipReceive) ? (uint8_t *)buf : NULL, count); } -/** - * @brief Transfer several bytes. One constant buffer used to send and - * one to receive data. - * begin() or beginTransaction() must be called at least once before. - * @param tx_buf: array of Tx bytes that is filled by the user before starting - * the SPI transfer. If NULL, default dummy 0xFF bytes will be - * clocked out. - * @param rx_buf: array of Rx bytes that will be filled by the slave during - * the SPI transfer. If NULL, the received data will be discarded. - * @param count: number of bytes to send/receive. - */ void SPIClass::transfer(const void *tx_buf, void *rx_buf, size_t count) { spi_transfer(&_spi, ((const uint8_t *)tx_buf), ((uint8_t *)rx_buf), count); } -/** - * @brief Not implemented. - */ void SPIClass::usingInterrupt(int interruptNumber) { (void)interruptNumber; } -/** - * @brief Not implemented. - */ void SPIClass::notUsingInterrupt(int interruptNumber) { (void)interruptNumber; } -/** - * @brief Not implemented. - */ void SPIClass::attachInterrupt(void) { // Should be enableInterrupt() } -/** - * @brief Not implemented. - */ void SPIClass::detachInterrupt(void) { // Should be disableInterrupt() diff --git a/libraries/SPI/src/SPI.h b/libraries/SPI/src/SPI.h index 2f04e65196..4645780efd 100644 --- a/libraries/SPI/src/SPI.h +++ b/libraries/SPI/src/SPI.h @@ -24,89 +24,214 @@ extern "C" { using namespace arduino; +/** + * @brief SPI controller or peripheral instance. The default instance is SPI. + */ class SPIClass : public HardwareSPI { public: + /** + * @brief Construct an SPI instance using the given pins. + * + * Default values are the pins of the default SPI peripheral defined in the variant. + * All pins must be attached to the same SPI peripheral, see the datasheet of the microcontroller. + * @param mosi SPI MOSI pin. Accepted format: number, Arduino format (Dx) or ST format (Pxy). + * @param miso SPI MISO pin. Accepted format: number, Arduino format (Dx) or ST format (Pxy). + * @param sclk SPI clock pin. Accepted format: number, Arduino format (Dx) or ST format (Pxy). + * @param ssel Optional SPI SSEL pin, must be a hardware CS pin managed by the SPI peripheral itself + * (see PinMap_SPI_SSEL in PeripheralPins.c). If set, do not pass a CS pin to any function of the class. + * Default: not defined (no hardware SSEL). + */ SPIClass(pin_size_t mosi = MOSI, pin_size_t miso = MISO, pin_size_t sclk = SCK, pin_size_t ssel = PNUM_NOT_DEFINED); // setMISO/MOSI/SCLK/SSEL have to be called before begin() + /** + * @brief Set the MISO pin. Must be called before begin(). + * @param miso MISO pin. Accepted format: number, Arduino format (Dx) or ST format (Pxy). + */ void setMISO(pin_size_t miso) { _spi.pin_miso = digitalPinToPinName(miso); }; + /** + * @brief Set the MOSI pin. Must be called before begin(). + * @param mosi MOSI pin. Accepted format: number, Arduino format (Dx) or ST format (Pxy). + */ void setMOSI(pin_size_t mosi) { _spi.pin_mosi = digitalPinToPinName(mosi); }; + /** + * @brief Set the SCLK pin. Must be called before begin(). + * @param sclk SCLK pin. Accepted format: number, Arduino format (Dx) or ST format (Pxy). + */ void setSCLK(pin_size_t sclk) { _spi.pin_sclk = digitalPinToPinName(sclk); }; + /** + * @brief Set the SSEL pin. Must be called before begin(). + * @param ssel SSEL pin. Accepted format: number, Arduino format (Dx) or ST format (Pxy). + */ void setSSEL(pin_size_t ssel) { _spi.pin_ssel = digitalPinToPinName(ssel); }; + /** + * @brief Set the MISO pin. Must be called before begin(). + * @param miso MISO PinName. + */ void setMISO(PinName miso) { _spi.pin_miso = (miso); }; + /** + * @brief Set the MOSI pin. Must be called before begin(). + * @param mosi MOSI PinName. + */ void setMOSI(PinName mosi) { _spi.pin_mosi = (mosi); }; + /** + * @brief Set the SCLK pin. Must be called before begin(). + * @param sclk SCLK PinName. + */ void setSCLK(PinName sclk) { _spi.pin_sclk = (sclk); }; + /** + * @brief Set the SSEL pin. Must be called before begin(). + * @param ssel SSEL PinName. + */ void setSSEL(PinName ssel) { _spi.pin_ssel = (ssel); }; + /** + * @brief Initialize the SPI instance with the default parameters: 4 MHz, MSBFIRST, SPI_MODE0. + * @param busMode Bus mode: controller or peripheral. + */ void begin(SPIBusMode busMode); + /** + * @brief Initialize the SPI instance as controller with the default parameters. + */ void begin() override { begin(SPI_CONTROLLER); } + /** + * @brief Deinitialize the SPI instance and stop it. + */ void end(void) override ; - /* This function should be used to configure the SPI instance in case you - * don't use default parameters. + /** + * @brief Configure the SPI instance with the given settings, when the default parameters of begin() are not suitable. + * @param settings SPI settings (clock speed, bit order, data mode, bus mode). */ void beginTransaction(SPISettings settings) override; + /** + * @brief End the transaction started with beginTransaction(). + */ void endTransaction(void) override; - /* Transfer functions: must be called after initialization of the SPI - * instance with begin() or beginTransaction(). + /** + * @brief Transfer one byte on the SPI bus. + * + * begin() or beginTransaction() must be called at least once before. + * @param data Byte to send. + * @param skipReceive true to skip receiving data (SPI_TRANSMITONLY), false to receive (SPI_TRANSMITRECEIVE). + * @return Byte received from the peripheral. */ uint8_t transfer(uint8_t data, bool skipReceive); + /** + * @brief Transfer one byte on the SPI bus and receive data. + * + * begin() or beginTransaction() must be called at least once before. + * @param data Byte to send. + * @return Byte received from the peripheral. + */ uint8_t transfer(uint8_t data) override { return transfer(data, SPI_TRANSMITRECEIVE); } + /** + * @brief Transfer two bytes on the SPI bus in 16-bit format. + * + * begin() or beginTransaction() must be called at least once before. + * @param data Bytes to send. + * @param skipReceive true to skip receiving data (SPI_TRANSMITONLY), false to receive (SPI_TRANSMITRECEIVE). + * @return Bytes received from the peripheral in 16-bit format. + */ uint16_t transfer16(uint16_t data, bool skipReceive); + /** + * @brief Transfer two bytes on the SPI bus in 16-bit format and receive data. + * + * begin() or beginTransaction() must be called at least once before. + * @param data Bytes to send. + * @return Bytes received from the peripheral in 16-bit format. + */ uint16_t transfer16(uint16_t data) override { return transfer16(data, SPI_TRANSMITRECEIVE); } + /** + * @brief Transfer several bytes using one buffer to send and receive. + * + * begin() or beginTransaction() must be called at least once before. + * @param buf Pointer to the bytes to send. The bytes received are copied in this buffer. + * @param count Number of bytes to send/receive. + * @param skipReceive true to skip receiving data (SPI_TRANSMITONLY), false to receive (SPI_TRANSMITRECEIVE). + */ void transfer(void *buf, size_t count, bool skipReceive); + /** + * @brief Transfer several bytes using one buffer to send and receive data. + * + * begin() or beginTransaction() must be called at least once before. + * @param buf Pointer to the bytes to send. The bytes received are copied in this buffer. + * @param count Number of bytes to send/receive. + */ void transfer(void *buf, size_t count) override { transfer(buf, count, SPI_TRANSMITRECEIVE); } - /* Expand SPI API - * https://github.com/arduino/ArduinoCore-API/discussions/189 + /** + * @brief Transfer several bytes using one constant Tx buffer and one Rx buffer. + * + * begin() or beginTransaction() must be called at least once before. + * See https://github.com/arduino/ArduinoCore-API/discussions/189 + * @param tx_buf Array of Tx bytes filled by the user before the transfer. If NULL, dummy 0xFF bytes are clocked out. + * @param rx_buf Array of Rx bytes filled by the peripheral during the transfer. If NULL, the received data is discarded. + * @param count Number of bytes to send/receive. */ void transfer(const void *tx_buf, void *rx_buf, size_t count); - // Not implemented functions. Kept for compatibility. + /** + * @brief Not implemented. Kept for compatibility. + * @param interruptNumber Unused. + */ void usingInterrupt(int interruptNumber) override; + /** + * @brief Not implemented. Kept for compatibility. + * @param interruptNumber Unused. + */ void notUsingInterrupt(int interruptNumber) override; + /** + * @brief Not implemented. Kept for compatibility. + */ void attachInterrupt(void) override; + /** + * @brief Not implemented. Kept for compatibility. + */ void detachInterrupt(void) override; - // Could be used to mix Arduino API and STM32Cube HAL API (ex: DMA). Use at your own risk. + /** + * @brief Get the SPI handle to mix the Arduino API and the STM32Cube HAL API (e.g. DMA). Use at your own risk. + * @return Pointer to the SPI handle. + */ #if defined(USE_HALV2_DRIVER) hal_spi_handle_t *getHandle(void) #else @@ -116,12 +241,20 @@ class SPIClass : public HardwareSPI { return &(_spi.handle); } - // Dedicated to SPI Slave + /** + * @brief Attach a callback on the falling edge of a pin, used for SPI slave chip select. + * @param pin Pin number. + * @param callback Function called on the falling edge. + */ void attachSlaveInterrupt(uint8_t pin, voidFuncPtr callback) { ::attachInterrupt(pin, callback, FALLING); } + /** + * @brief Detach the callback attached with attachSlaveInterrupt(). + * @param pin Pin number. + */ void detachSlaveInterrupt(uint8_t pin) { ::detachInterrupt(pin); @@ -141,11 +274,21 @@ extern SPIClass SPI; #if defined(SUBGHZSPI_BASE) class SUBGHZSPIClass : public SPIClass { public: + /** + * @brief Constructor. Attaches the SPI instance to the SubGHz radio peripheral. + */ SUBGHZSPIClass(): SPIClass{NC, NC, NC, NC} { _spi.spi = SUBGHZSPI; } + /** + * @brief Route the SubGHz SPI signals to debug pins, for logic analyzer use. + * @param mosi MOSI debug pin. + * @param miso MISO debug pin. + * @param sclk SCLK debug pin. + * @param ssel SSEL debug pin. + */ void enableDebugPins(pin_size_t mosi = DEBUG_SUBGHZSPI_MOSI, pin_size_t miso = DEBUG_SUBGHZSPI_MISO, pin_size_t sclk = DEBUG_SUBGHZSPI_SCLK, pin_size_t ssel = DEBUG_SUBGHZSPI_SS); }; diff --git a/libraries/SPI/src/utility/spi_com.c b/libraries/SPI/src/utility/spi_com.c index 1778e06d80..1dc9e818eb 100644 --- a/libraries/SPI/src/utility/spi_com.c +++ b/libraries/SPI/src/utility/spi_com.c @@ -24,7 +24,7 @@ extern "C" { /** * @brief return clock freq of an SPI instance * @param spi_inst : SPI instance - * @retval clock freq of the instance else SystemCoreClock + * @return clock freq of the instance else SystemCoreClock */ uint32_t spi_getClkFreqInst(SPI_TypeDef *spi_inst) { @@ -161,11 +161,6 @@ uint32_t spi_getClkFreqInst(SPI_TypeDef *spi_inst) return spi_freq; } -/** - * @brief return clock freq of an SPI instance - * @param obj : pointer to spi_t structure - * @retval clock freq of the instance else SystemCoreClock - */ uint32_t spi_getClkFreq(spi_t *obj) { SPI_TypeDef *spi_inst = NP; @@ -194,8 +189,9 @@ uint32_t spi_getClkFreq(spi_t *obj) * @brief Compute delay before disabling SPI * See https://github.com/stm32duino/Arduino_Core_STM32/issues/1294 * Computed delay is half SPI clock - * @param obj : pointer to spi_t structure - * @retval Disable delay in microsecondes + * @param spi_freq SPI clock frequency. + * @param prescaler SPI prescaler configuration. + * @return Disable delay in microsecondes */ static uint32_t compute_disable_delay(uint32_t spi_freq, uint32_t prescaler) { @@ -206,15 +202,6 @@ static uint32_t compute_disable_delay(uint32_t spi_freq, uint32_t prescaler) } #endif -/** - * @brief SPI initialization function - * @param obj : pointer to spi_t structure - * @param speed : spi output speed - * @param dataMode : one of the spi modes - * @param msbFirst : set to true in msb first - * @param busMode : spi busMode: controller or peripheral - * @retval None - */ void spi_init(spi_t *obj, uint32_t speed, spi_mode_e dataMode, bool msbFirst, spi_busmode_e busMode) { if (obj != NULL) { @@ -461,12 +448,6 @@ void spi_init(spi_t *obj, uint32_t speed, spi_mode_e dataMode, bool msbFirst, sp } } -/** - * @brief This function is implemented to deinitialize the SPI interface - * (IOs + SPI block) - * @param obj : pointer to spi_t structure - * @retval None - */ void spi_deinit(spi_t *obj) { if (obj != NULL) { @@ -550,15 +531,6 @@ void spi_deinit(spi_t *obj) } } -/** - * @brief This function is implemented by user to send/receive data over - * SPI interface - * @param obj : pointer to spi_t structure - * @param tx_buffer : tx data to send before reception - * @param rx_buffer : rx data to receive if not numm - * @param len : length in byte of the data to send and receive - * @retval status of the send operation (0) in case of error - */ spi_status_e spi_transfer(spi_t *obj, const uint8_t *tx_buffer, uint8_t *rx_buffer, uint16_t len) { diff --git a/libraries/SPI/src/utility/spi_com.h b/libraries/SPI/src/utility/spi_com.h index 8e4fcf844d..4b5e6ad3a4 100644 --- a/libraries/SPI/src/utility/spi_com.h +++ b/libraries/SPI/src/utility/spi_com.h @@ -92,9 +92,34 @@ typedef enum { } spi_status_e; /* Exported functions ------------------------------------------------------- */ +/** + * @brief Initialize the SPI instance. + * @param obj Pointer to spi_t structure. + * @param speed Clock speed of the SPI bus in Hz. + * @param dataMode One of the SPI data modes (spi_mode_e). + * @param msbFirst true for MSB first, false for LSB first. + * @param busMode SPI bus mode: controller or peripheral. + */ void spi_init(spi_t *obj, uint32_t speed, spi_mode_e dataMode, bool msbFirst, spi_busmode_e busMode); +/** + * @brief Deinitialize the SPI interface (IOs and SPI block). + * @param obj Pointer to spi_t structure. + */ void spi_deinit(spi_t *obj); +/** + * @brief Send and receive data over the SPI interface. + * @param obj Pointer to spi_t structure. + * @param tx_buffer Data to send before reception. + * @param rx_buffer Buffer to store the received data. If NULL, the received data is discarded. + * @param len Length in bytes of the data to send and receive. + * @return SPI_OK on success, SPI_TIMEOUT or SPI_ERROR otherwise. + */ spi_status_e spi_transfer(spi_t *obj, const uint8_t *tx_buffer, uint8_t *rx_buffer, uint16_t len); +/** + * @brief Return the clock frequency of an SPI instance. + * @param obj Pointer to spi_t structure. + * @return Clock frequency of the instance, or SystemCoreClock if not found. + */ uint32_t spi_getClkFreq(spi_t *obj); #ifdef __cplusplus diff --git a/libraries/Servo/src/Servo.h b/libraries/Servo/src/Servo.h index 21e70e07bf..030c9089f0 100644 --- a/libraries/Servo/src/Servo.h +++ b/libraries/Servo/src/Servo.h @@ -84,17 +84,60 @@ typedef struct { volatile unsigned int ticks; } servo_t; +/** + * @brief Servo motor controller. Each instance drives one servo on a pin, using a shared 16 bit timer. + */ class Servo { public: + /** + * @brief Create a servo instance and assign it a channel index. If no channel is left, the instance is invalid. + */ Servo(); - uint8_t attach(pin_size_t pin, int value = DEFAULT_PULSE_WIDTH); // attach the given pin to the next free channel, sets pinMode, set angle value, returns channel number or 0 if failure - uint8_t attach(pin_size_t pin, int min, int max, int value = DEFAULT_PULSE_WIDTH); // as above but also sets min and max values for writes. + /** + * @brief Attach the servo to a pin, using the default min and max pulse widths. + * @param pin Pin number to attach the servo to. + * @param value Initial value, as an angle in degrees or a pulse width in microseconds. Default: DEFAULT_PULSE_WIDTH. + * @return Index of the channel used, or INVALID_SERVO if no channel is available. + */ + uint8_t attach(pin_size_t pin, int value = DEFAULT_PULSE_WIDTH); + /** + * @brief Attach the servo to a pin, with custom min and max pulse widths. + * @param pin Pin number to attach the servo to. + * @param min Pulse width in microseconds for 0 degrees. Default: MIN_PULSE_WIDTH. + * @param max Pulse width in microseconds for 180 degrees. Default: MAX_PULSE_WIDTH. + * @param value Initial value, as an angle in degrees or a pulse width in microseconds. Default: DEFAULT_PULSE_WIDTH. + * @return Index of the channel used, or INVALID_SERVO if no channel is available. + */ + uint8_t attach(pin_size_t pin, int min, int max, int value = DEFAULT_PULSE_WIDTH); + /** + * @brief Stop the servo from pulsing its pin. The timer is paused when no servo is active. + */ void detach(); - void write(int value); // if value is < 200 its treated as an angle, otherwise as pulse width in microseconds - void writeMicroseconds(int value); // Write pulse width in microseconds - int read(); // returns current pulse width as an angle between 0 and 180 degrees - int readMicroseconds(); // returns current pulse width in microseconds for this servo (was read_us() in first release) - bool attached(); // return true if this servo is attached, otherwise false + /** + * @brief Set the servo position. + * @param value Angle in degrees (0 to 180) if less than MIN_PULSE_WIDTH, otherwise a pulse width in microseconds. + */ + void write(int value); + /** + * @brief Set the servo pulse width. The value is clamped to the min and max pulse widths of this servo. + * @param value Pulse width in microseconds. + */ + void writeMicroseconds(int value); + /** + * @brief Get the last written position. + * @return Current position as an angle between 0 and 180 degrees. + */ + int read(); + /** + * @brief Get the last written pulse width. + * @return Current pulse width in microseconds. + */ + int readMicroseconds(); + /** + * @brief Check if the servo is attached. + * @return true if the servo is attached, false otherwise. + */ + bool attached(); private: uint8_t servoIndex; // index into the channel data for this servo int8_t min; // minimum is this value times 4 added to MIN_PULSE_WIDTH diff --git a/libraries/Servo/src/stm32/Servo.cpp b/libraries/Servo/src/stm32/Servo.cpp index daf6976ff9..1beecfee9b 100644 --- a/libraries/Servo/src/stm32/Servo.cpp +++ b/libraries/Servo/src/stm32/Servo.cpp @@ -228,6 +228,6 @@ int Servo::readMicroseconds() { return 0; } -bool Servo::attached() {} +bool Servo::attached() { return false; } #endif /* TIMER_SERVO && !HAL_TIM_MODULE_ONLY && (HAL_TIM_MODULE_ENABLED || USE_HAL_TIM_MODULE...) */ diff --git a/libraries/SoftwareSerial/src/SoftwareSerial.cpp b/libraries/SoftwareSerial/src/SoftwareSerial.cpp index daeafdbc2c..28de54e3d9 100644 --- a/libraries/SoftwareSerial/src/SoftwareSerial.cpp +++ b/libraries/SoftwareSerial/src/SoftwareSerial.cpp @@ -141,8 +141,6 @@ void SoftwareSerial::setSpeed(uint32_t speed) } } -// This function sets the current object as the "listening" -// one and returns true if it replaces another bool SoftwareSerial::listen() { if (active_listener != this) { @@ -165,7 +163,6 @@ bool SoftwareSerial::listen() return false; } -// Stop listening. Returns true if we were actually listening. bool SoftwareSerial::stopListening() { if (active_listener == this) { @@ -363,7 +360,6 @@ void SoftwareSerial::end() setSpeed(0); } -// Read data from buffer int SoftwareSerial::read() { // Empty buffer? diff --git a/libraries/SoftwareSerial/src/SoftwareSerial.h b/libraries/SoftwareSerial/src/SoftwareSerial.h index 2a677c2463..19351c3142 100644 --- a/libraries/SoftwareSerial/src/SoftwareSerial.h +++ b/libraries/SoftwareSerial/src/SoftwareSerial.h @@ -39,8 +39,15 @@ * Definitions ******************************************************************************/ -#define _SS_MAX_RX_BUFF 64 // RX buffer size +/** + * @brief Size of the receive buffer in bytes. + */ +#define _SS_MAX_RX_BUFF 64 +/** + * @brief Software serial (UART) emulation on any pair of GPIO pins, driven by a timer interrupt. + * @note When the receive and transmit pins are the same, the instance works in half-duplex mode. + */ class SoftwareSerial : public Stream { private: // per object data @@ -77,28 +84,80 @@ class SoftwareSerial : public Stream { static int32_t rx_bit_cnt; static uint32_t cur_speed; - // private methods + /** + * @brief Timer interrupt handler for the transmit side: send the next TX bit. + */ void send(); + /** + * @brief Timer interrupt handler for the receive side: sample the next RX bit. + */ void recv(); + /** + * @brief Configure the transmit pin as output, idle high (low if inverse logic is used). + */ void setTX(); + /** + * @brief Configure the receive pin as input with pull-up (pull-down if inverse logic is used). + */ void setRX(); + /** + * @brief Configure the timer for the given baud rate, or stop it when speed is 0. + * @param speed Baud rate in bits per second. 0 disables the timer interrupt. + */ void setSpeed(uint32_t speed); + /** + * @brief Switch the pin between receive and transmit in half-duplex mode. + * @param input true to switch to receive, false to switch to transmit. + */ void setRXTX(bool input); + /** + * @brief Timer interrupt handler dispatching to the active receiver and transmitter. + */ static void handleInterrupt(); public: - // public methods - + /** + * @brief Create a software serial instance on the given pins. + * @param receivePin Pin used to receive data (RX). + * @param transmitPin Pin used to transmit data (TX). Use the same pin as receivePin for half-duplex mode. + * @param inverse_logic Optional, true to invert the logic level of the data. Default: false. + */ SoftwareSerial(pin_size_t receivePin, pin_size_t transmitPin, bool inverse_logic = false); + /** + * @brief Stop this instance: stop listening and disable its timer interrupt. + */ virtual ~SoftwareSerial(); + /** + * @brief Set the baud rate and initialize the pins. Starts listening unless the instance is half-duplex. + * @param speed Baud rate in bits per second. If FORCE_BAUD_RATE is defined, its value is used instead. + */ void begin(long speed); + /** + * @brief Make this instance the active listener, stopping the previously listening instance. + * @return true if this instance was not already listening, false otherwise. + */ bool listen(); + /** + * @brief Stop this instance: stop listening and disable the timer interrupt. + */ void end(); + /** + * @brief Check if this instance is the active listener. + * @return true if this instance is listening, false otherwise. + */ bool isListening() { return active_listener == this; } + /** + * @brief Stop listening on this instance. Waits for any pending output to complete. + * @return true if this instance was listening, false otherwise. + */ bool stopListening(); + /** + * @brief Check whether a byte was dropped because the receive buffer was full. Clears the flag. + * @return true if an overflow occurred since the last call, false otherwise. + */ bool overflow() { bool ret = _buffer_overflow; @@ -107,17 +166,46 @@ class SoftwareSerial : public Stream { } return ret; } + /** + * @brief Get the next received byte without removing it from the receive buffer. + * @return The next byte, or -1 if the receive buffer is empty. + */ int peek(); + /** + * @brief Send one byte. Waits for any previous transmission to complete. + * @param byte Byte to send. + * @return Always 1. + */ virtual size_t write(uint8_t byte); + /** + * @brief Read the next byte from the receive buffer. + * @return The byte read, or -1 if the receive buffer is empty. + */ virtual int read(); + /** + * @brief Get the number of bytes in the receive buffer. + * @return Number of bytes available to read. + */ virtual int available(); + /** + * @brief Clear the receive buffer and wait for any pending transmission to complete. + */ virtual void flush(); + /** + * @brief Allow the instance to be used in a boolean context. + * @return Always true. + */ operator bool() { return true; } + /** + * @brief Set the priority of the timer interrupt shared by all software serial instances. + * @param preemptPriority Preemption priority of the interrupt. + * @param subPriority Sub-priority of the interrupt. + */ static void setInterruptPriority(uint32_t preemptPriority, uint32_t subPriority); using Print::write; diff --git a/libraries/SrcWrapper/inc/HardwareTimer.h b/libraries/SrcWrapper/inc/HardwareTimer.h index 90a6c2e27f..52a271d959 100644 --- a/libraries/SrcWrapper/inc/HardwareTimer.h +++ b/libraries/SrcWrapper/inc/HardwareTimer.h @@ -150,79 +150,348 @@ using callback_function_t = std::function; /* Class --------------------------------------------------------*/ class HardwareTimer { public: + /** + * @brief HardwareTimer constructor: make uninitialized timer + * Before calling any methods, call setup to select and setup + * the timer to be used. + */ HardwareTimer(); + /** + * @brief HardwareTimer constructor: set default configuration values + * The timer will be usable directly, there is no need to call + * setup(). Using this constructor is not recommended for + * global variables that are automatically initialized at + * startup, since this will happen to early to report any + * errors. Better use the argumentless constructor and call the + * setup() method during initialization later. + * @param instance: Timer instance ex: TIM1, ... + */ HardwareTimer(TIM_TypeDef *instance); + /** + * @brief HardwareTimer destructor + */ ~HardwareTimer(); // destructor + /** + * @brief HardwareTimer setup: configuration values. Must be called + * exactly once before any other methods, except when an instance is + * passed to the constructor. + * @param instance: Timer instance ex: TIM1, ... + */ void setup(TIM_TypeDef *instance); // Setup, only needed if no instance was passed to the constructor + /** + * @brief Pause HardwareTimer: stop timer + */ void pause(void); // Pause counter and all output channels + /** + * @brief Pause only one channel. + * Timer is still running but channel is disabled (output and interrupt) + * @param channel: Arduino channel [1..4] + */ void pauseChannel(uint32_t channel); // Timer is still running but channel (output and interrupt) is disabled + /** + * @brief Start or resume HardwareTimer: all channels are resumed, interrupts are enabled if necessary + */ void resume(void); // Resume counter and all output channels + /** + * @brief Configure specified channel and resume/start timer + * @param channel: Arduino channel [1..4] + */ void resumeChannel(uint32_t channel); // Resume only one channel + /** + * @brief Configure hardwareTimer prescaler + * @param prescaler: prescaler factor + */ void setPrescaleFactor(uint32_t prescaler); // set prescaler register (which is factor value - 1) + /** + * @brief Retrieve prescaler from hardware register + * @return prescaler factor + */ uint32_t getPrescaleFactor(); - void setOverflow(uint32_t val, TimerFormat_t format = TICK_FORMAT); // set AutoReload register depending on format provided + /** + * @brief Set overflow (rollover) + * + * Note that by default, the new value will not be applied + * immediately, but become effective at the next update event + * (usually the next timer overflow). See setPreloadEnable() + * for controlling this behaviour. + * @param overflow: depend on format parameter + * @param format: format of overflow parameter. If omitted default format is Tick + * TICK_FORMAT: overflow is the number of tick for overflow + * MICROSEC_FORMAT: overflow is the number of microsecondes for overflow + * HERTZ_FORMAT: overflow is the frequency in hertz for overflow + */ + void setOverflow(uint32_t overflow, TimerFormat_t format = TICK_FORMAT); // set AutoReload register depending on format provided + /** + * @brief Retrieve overflow (rollover) value from hardware register + * @param format: format of returned value. If omitted default format is Tick + * @return overflow depending on format value: + * TICK_FORMAT: return number of tick for overflow + * MICROSEC_FORMAT: return number of microsecondes for overflow + * HERTZ_FORMAT: return frequency in hertz for overflow + */ uint32_t getOverflow(TimerFormat_t format = TICK_FORMAT); // return overflow depending on format provided + /** + * @brief All in one function to configure PWM + * @param channel: Arduino channel [1..4] + * @param pin: pin name, ex PB_0 + * @param frequency: PWM frequency expressed in hertz + * @param dutycycle: PWM dutycycle expressed in percentage + * @param PeriodCallback: timer period callback (timer rollover upon update event) + * @param CompareCallback: timer compare callback + */ void setPWM(uint32_t channel, PinName pin, uint32_t frequency, uint32_t dutycycle, callback_function_t PeriodCallback = nullptr, callback_function_t CompareCallback = nullptr); // Set all in one command freq in HZ, Duty in percentage. Including both interrupt. + /** + * @brief All in one function to configure PWM, using an Arduino pin number + * @param channel: Arduino channel [1..4] + * @param pin: Arduino pin number, ex D1, 1 or PA1 + * @param frequency: PWM frequency expressed in hertz + * @param dutycycle: PWM dutycycle expressed in percentage + * @param PeriodCallback: timer period callback (timer rollover upon update event) + * @param CompareCallback: timer compare callback + */ void setPWM(uint32_t channel, pin_size_t pin, uint32_t frequency, uint32_t dutycycle, callback_function_t PeriodCallback = nullptr, callback_function_t CompareCallback = nullptr); - void setCount(uint32_t val, TimerFormat_t format = TICK_FORMAT); // set timer counter to value 'val' depending on format provided + /** + * @brief Set timer counter value + * @param counter: depend on format parameter + * @param format: format of counter parameter. If omitted default format is Tick + * TICK_FORMAT: counter is the number of tick + * MICROSEC_FORMAT: counter is the number of microsecondes + * HERTZ_FORMAT: counter is the frequency in hertz + */ + void setCount(uint32_t counter, TimerFormat_t format = TICK_FORMAT); // set timer counter to value 'val' depending on format provided + /** + * @brief Retrieve timer counter value + * @param format: format of returned value. If omitted default format is Tick + * @return counter value depending on format value: + * TICK_FORMAT: return number of tick for counter + * MICROSEC_FORMAT: return number of microsecondes for counter + * HERTZ_FORMAT: return frequency in hertz for counter + */ uint32_t getCount(TimerFormat_t format = TICK_FORMAT); // return current counter value of timer depending on format provided + /** + * @brief Set channel mode + * @param channel: Arduino channel [1..4] + * @param mode: mode configuration for the channel (see TimerModes_t) + * @param pin: pin name, ex: PB_0 + * @param filter: input capture filter (see ChannelInputFilter_t) + */ void setMode(uint32_t channel, TimerModes_t mode, PinName pin = NC, ChannelInputFilter_t filter = FILTER_NONE); // Configure timer channel with specified mode on specified pin if available + /** + * @brief Set channel mode + * @param channel: Arduino channel [1..4] + * @param mode: mode configuration for the channel (see TimerModes_t) + * @param pin: Arduino pin number, ex: D1, 1 or PA1 + * @param filter: input capture filter (see ChannelInputFilter_t) + */ void setMode(uint32_t channel, TimerModes_t mode, pin_size_t pin, ChannelInputFilter_t filter = FILTER_NONE); + /** + * @brief Retrieves channel mode configured + * @param channel: Arduino channel [1..4] + * @return returns configured mode + */ TimerModes_t getMode(uint32_t channel); // Retrieve configured mode + /** + * @brief Enable or disable preloading for overflow value + * When disabled, changes to the overflow value take effect + * immediately. When enabled (the default), the value takes + * effect only at the next update event (typically the next + * overflow). + * + * Note that the capture/compare register has its own preload + * enable bit, which is independent and enabled in PWM modes + * and disabled otherwise. If you need more control of that + * bit, you can use the HAL functions directly. + * @param value: true to enable preloading, false to disable + */ void setPreloadEnable(bool value); // Configure overflow preload enable setting + /** + * @brief Retrieve Capture/Compare value + * @param channel: Arduino channel [1..4] + * @param format: format of return value. If omitted default format is Tick + * TICK_FORMAT: return value is the number of tick for Capture/Compare value + * MICROSEC_FORMAT: return value is the number of microsecondes for Capture/Compare value + * HERTZ_FORMAT: return value is the frequency in hertz for Capture/Compare value + * @return Capture/Compare value + */ uint32_t getCaptureCompare(uint32_t channel, TimerCompareFormat_t format = TICK_COMPARE_FORMAT); // return Capture/Compare register value of specified channel depending on format provided + /** + * @brief Set channel Capture/Compare register + * @param channel: Arduino channel [1..4] + * @param compare: compare value depending on format + * @param format: format of compare parameter. If omitted default format is Tick + * TICK_FORMAT: compare is the number of tick + * MICROSEC_FORMAT: compare is the number of microsecondes + * HERTZ_FORMAT: compare is the frequency in hertz + */ void setCaptureCompare(uint32_t channel, uint32_t compare, TimerCompareFormat_t format = TICK_COMPARE_FORMAT); // set Compare register value of specified channel depending on format provided + /** + * @brief Set the priority of the interrupt + * @note Must be call before resume() + * @param preemptPriority: the pre-emption priority for the IRQn channel + * @param subPriority: the subpriority level for the IRQ channel. + */ void setInterruptPriority(uint32_t preemptPriority, uint32_t subPriority); // set interrupt priority //Add interrupt to period update + /** + * @brief Attach interrupt callback on update (rollover) event + * @param callback: interrupt callback + */ void attachInterrupt(callback_function_t callback); // Attach interrupt callback which will be called upon update event (timer rollover) + /** + * @brief Detach interrupt callback on update (rollover) event + */ void detachInterrupt(); // remove interrupt callback which was attached to update event + /** + * @brief Checks if there's an interrupt callback attached on Rollover event + * @return returns true if a timer rollover interrupt has already been set + */ bool hasInterrupt(); //returns true if a timer rollover interrupt has already been set //Add interrupt to capture/compare channel + /** + * @brief Attach interrupt callback on Capture/Compare event + * @param channel: Arduino channel [1..4] + * @param callback: interrupt callback + */ void attachInterrupt(uint32_t channel, callback_function_t callback); // Attach interrupt callback which will be called upon compare match event of specified channel + /** + * @brief Detach interrupt callback on Capture/Compare event + * @param channel: Arduino channel [1..4] + */ void detachInterrupt(uint32_t channel); // remove interrupt callback which was attached to compare match event of specified channel + /** + * @brief Checks if there's an interrupt callback attached on Capture/Compare event + * @param channel: Arduino channel [1..4] + * @return returns true if a channel compare match interrupt has already been set + */ bool hasInterrupt(uint32_t channel); //returns true if an interrupt has already been set on the channel compare match + /** + * @brief This function will reset the timer + */ void timerHandleDeinit(); // Timer deinitialization // Refresh() is useful while timer is running after some registers update + /** + * @brief Generate an update event to force all registers (Autoreload, prescaler, compare) to be taken into account + * @note Refresh() can only be called after timer has been initialized, + * either by calling setup() function or thanks to constructor with TIM instance parameter. + * It is useful while timer is running after some registers update + */ void refresh(void); // Generate update event to force all registers (Autoreload, prescaler, compare) to be taken into account + /** + * @brief This function return the timer clock frequency. + * @return frequency in Hz + */ uint32_t getTimerClkFreq(); // return timer clock frequency in Hz. #if defined(USE_HALV2_DRIVER) + /** + * @brief Generic Capture and Compare callback which will call user callback + * @param htim: HAL timer handle + * @param hal_channel: HAL channel which triggered the callback + */ static void captureCompareCallback(hal_tim_handle_t *htim, hal_tim_channel_t hal_channel); // Generic Capture and Compare callback which will call user callback + /** + * @brief Generic Update (rollover) callback which will call user callback + * @param htim: HAL timer handle + */ static void updateCallback(hal_tim_handle_t *htim); // Generic Update (rollover) callback which will call user callback #else + /** + * @brief Generic Capture and Compare callback which will call user callback + * @param htim: HAL timer handle + */ static void captureCompareCallback(TIM_HandleTypeDef *htim); // Generic Capture and Compare callback which will call user callback + /** + * @brief Generic Update (rollover) callback which will call user callback + * @param htim: HAL timer handle + */ static void updateCallback(TIM_HandleTypeDef *htim); // Generic Update (rollover) callback which will call user callback #endif + /** + * @brief Take into account registers update immediately if timer is not running, + * (independently from Preload setting) + * @param TIMx: Timer instance + */ void updateRegistersIfNotRunning(TIM_TypeDef *TIMx); // Take into account registers update immediately if timer is not running, + /** + * @brief Check whether HardwareTimer is running (paused or resumed). + * @return return true if the HardwareTimer is running + */ bool isRunning(); // return true if HardwareTimer is running + /** + * @brief Check whether channel is running (paused or resumed). + * @param channel: Arduino channel [1..4] + * @return return true if HardwareTimer is running and the channel is enabled + */ bool isRunningChannel(uint32_t channel); // return true if channel is running // The following function(s) are available for more advanced timer options #if defined(USE_HALV2_DRIVER) + /** + * @brief Return the timer object handle object for more advanced setup + * @note Using this function and editing the Timer handle is at own risk! No support will + * be provided whatsoever if the HardwareTimer does not work as expected when editing + * the handle using the HAL functionality or other custom coding. + * @return hal_tim_handle_t address + */ hal_tim_handle_t *getHandle(); // return the handle address for HAL related configuration + /** + * @brief Convert arduino channel into HAL channel + * @param channel: Arduino channel [1..4] + * @param complementary: true to get the complementary (N) channel, false for the regular one + * @return HAL channel. Error handler called if arduino channel is invalid + */ hal_tim_channel_t getChannel(uint32_t channel, bool complementary = false); #else + /** + * @brief Return the timer object handle object for more advanced setup + * @note Using this function and editing the Timer handle is at own risk! No support will + * be provided whatsoever if the HardwareTimer does not work as expected when editing + * the handle using the HAL functionality or other custom coding. + * @return TIM_HandleTypeDef address + */ TIM_HandleTypeDef *getHandle(); // return the handle address for HAL related configuration + /** + * @brief Convert arduino channel into HAL channel + * @param channel: Arduino channel [1..4] + * @return HAL channel. Error handler called if arduino channel is invalid + */ uint32_t getChannel(uint32_t channel); #endif + /** + * @brief Convert arduino channel into LL channels used (regular and/or complementary) + * @param channel: Arduino channel [1..4] + * @return LL channel. Error handler called if arduino channel is invalid + */ uint32_t getLLChannel(uint32_t channel); + /** + * @brief Handle itterupt based on arduino channel + * @param channel: Arduino channel [1..4] + * @param config: configuration for the interrupt (enable, disable, clear, clear and disable) + * @return true if interrupt is enabled, false otherwise + */ bool manageIT(uint32_t channel, ChannelITConfig_t config = DISABLE_IT); + /** + * @brief Get input associated channel + * Channel 1 and 2 are associated; channel 3 and 4 are associated + * @param channel: Arduino channel [1..4] + * @return associated channel [1..4]. Error handler called if arduino channel is invalid + */ uint32_t getAssociatedChannel(uint32_t channel); private: @@ -236,7 +505,12 @@ class HardwareTimer { extern timerObj_t *HardwareTimer_Handle[TIMER_NUM]; -extern timer_index_t get_timer_index(TIM_TypeDef *htim); +/** + * @brief return timer index from timer handle + * @param instance: one of the defined timer + * @return timer index + */ +extern timer_index_t get_timer_index(TIM_TypeDef *instance); #endif /* __cplusplus */ diff --git a/libraries/SrcWrapper/inc/PinAF_STM32F1.h b/libraries/SrcWrapper/inc/PinAF_STM32F1.h index 1762bc27af..2302bcd205 100644 --- a/libraries/SrcWrapper/inc/PinAF_STM32F1.h +++ b/libraries/SrcWrapper/inc/PinAF_STM32F1.h @@ -174,6 +174,10 @@ enum { #endif }; +/** + * @brief Disconnect the JTAG/SWD debug pins on STM32F1xx. + * @param pin Pin name. + */ static inline void pinF1_DisconnectDebug(PinName pin) { /** Enable this flag gives the possibility to use debug pins without any risk @@ -196,6 +200,10 @@ static inline void pinF1_DisconnectDebug(PinName pin) #endif /* STM32F1_FORCE_DEBUG */ } +/** + * @brief Enable or disable an AFIO remap, selected by an AFIO_*_ENABLE/DISABLE value. + * @param afnum AFIO remap value (AFIO_*_ENABLE or AFIO_*_DISABLE). + */ static inline void pin_SetF1AFPin(uint32_t afnum) { // Enable AFIO clock diff --git a/libraries/SrcWrapper/inc/PortNames.h b/libraries/SrcWrapper/inc/PortNames.h index 1654099134..37f6e9875e 100644 --- a/libraries/SrcWrapper/inc/PortNames.h +++ b/libraries/SrcWrapper/inc/PortNames.h @@ -80,7 +80,11 @@ typedef enum { /* Return GPIO base address */ #define get_GPIO_Port(p) ((p < MAX_NB_PORT) ? GPIOPort_list[p] : (GPIO_TypeDef *)NULL) -/* Enable GPIO clock and return GPIO base address */ +/** + * @brief Enables the clock of a GPIO port and returns its base address. + * @param port_idx Port index, one of the PortName values (PortA, PortB, ...). + * @return GPIO base address of the port, or NULL if port_idx is invalid. + */ GPIO_TypeDef *set_GPIO_Port_Clock(uint32_t port_idx); #ifdef __cplusplus diff --git a/libraries/SrcWrapper/inc/analog.h b/libraries/SrcWrapper/inc/analog.h index 42ce16f29a..3ca7c008ef 100644 --- a/libraries/SrcWrapper/inc/analog.h +++ b/libraries/SrcWrapper/inc/analog.h @@ -51,32 +51,90 @@ extern "C" { /* Exported functions ------------------------------------------------------- */ #if !defined(HAL_ADC_MODULE_ONLY) #if defined(HAL_ADC_MODULE_ENABLED) +/** + * @brief Return the ADC channel linked to a PinName. + * @param pin PinName. + * @param bank Pointer to get the ADC channel bank, if required. + * @return The ADC channel. + */ uint32_t get_adc_channel(PinName pin, uint32_t *bank); +/** + * @brief Return the ADC internal channel linked to a PinName. + * @param pin PinName, one of the ADC internal PinNames. + * @return The ADC internal channel. + */ uint32_t get_adc_internal_channel(PinName pin); #endif #if defined(USE_HAL_ADC_MODULE) && (USE_HAL_ADC_MODULE == 1) +/** + * @brief Return the ADC HAL channel linked to a PinName (HAL v2 ADC driver). + * @param pin PinName. + * @return The ADC HAL channel. + */ hal_adc_channel_t get_adc_channel(PinName pin); +/** + * @brief Return the ADC HAL internal channel linked to a PinName (HAL v2 ADC driver). + * @param pin PinName, one of the ADC internal PinNames. + * @return The ADC HAL internal channel. + */ hal_adc_channel_t get_adc_internal_channel(PinName pin); #endif #if defined(HAL_ADC_MODULE_ENABLED) || (defined(USE_HAL_ADC_MODULE) && (USE_HAL_ADC_MODULE == 1)) +/** + * @brief Read the ADC value on a pin. + * @param pin PinName to read. + * @param resolution Resolution of the converted data: 6/8/10/12/14/16. + * @return The converted ADC value. + */ uint16_t adc_read_value(PinName pin, uint32_t resolution); #endif #endif /* !HAL_ADC_MODULE_ONLY */ #if !defined(HAL_DAC_MODULE_ONLY) #if defined(HAL_DAC_MODULE_ENABLED) +/** + * @brief Return the DAC channel linked to a PinName. + * @param pin PinName. + * @return The DAC channel. + */ uint32_t get_dac_channel(PinName pin); #endif #if defined(USE_HAL_DAC_MODULE) && (USE_HAL_DAC_MODULE == 1) +/** + * @brief Return the DAC HAL channel linked to a PinName (HAL v2 DAC driver). + * @param pin PinName. + * @return The DAC HAL channel. + */ hal_dac_channel_t get_dac_channel(PinName pin); #endif #if defined(HAL_DAC_MODULE_ENABLED) || (defined(USE_HAL_DAC_MODULE) && (USE_HAL_DAC_MODULE == 1)) +/** + * @brief Set the DAC output to the required value. + * @param pin PinName to use. + * @param value Value to push on the DAC output. + * @param do_init If true, initialize the DAC before writing. + */ void dac_write_value(PinName pin, uint32_t value, bool do_init); +/** + * @brief Stop the DAC output on a pin. + * @param pin PinName to use. + */ void dac_stop(PinName pin); #endif #endif /* !HAL_DAC_MODULE_ONLY */ #if !defined(HAL_TIM_MODULE_ONLY) &&\ (defined(HAL_TIM_MODULE_ENABLED) || (defined(USE_HAL_TIM_MODULE) && (USE_HAL_TIM_MODULE == 1))) -void pwm_start(PinName pin, uint32_t clock_freq, uint32_t value, TimerCompareFormat_t resolution); +/** + * @brief Start PWM output on a pin with the required value. + * @param pin PinName to use. + * @param PWM_freq Frequency of the timer clock. + * @param value Value to push on the PWM output. + * @param resolution PWM compare resolution. + */ +void pwm_start(PinName pin, uint32_t PWM_freq, uint32_t value, TimerCompareFormat_t resolution); +/** + * @brief Stop PWM output on a pin. + * @param pin PinName to use. + */ void pwm_stop(PinName pin); #endif #ifdef __cplusplus diff --git a/libraries/SrcWrapper/inc/backup.h b/libraries/SrcWrapper/inc/backup.h index 9fc7b3a4d7..8bfee0a7da 100644 --- a/libraries/SrcWrapper/inc/backup.h +++ b/libraries/SrcWrapper/inc/backup.h @@ -59,6 +59,10 @@ extern "C" { #endif /* Exported functions ------------------------------------------------------- */ +/** + * @brief Reset the backup domain (RTC and backup registers). + * @note Backup domain write access is enabled as part of the reset. + */ static inline void resetBackupDomain(void) { #if defined(USE_HALV2_DRIVER) @@ -88,6 +92,9 @@ static inline void resetBackupDomain(void) #endif } +/** + * @brief Enable access to the backup domain and its clocks (RTC, backup registers and SRAM). + */ static inline void enableBackupDomain(void) { #if defined(USE_HALV2_DRIVER) @@ -145,6 +152,9 @@ static inline void enableBackupDomain(void) #endif /* USE_HALV2_DRIVER */ } +/** + * @brief Disable the backup domain clocks (RTC, backup registers and SRAM). + */ static inline void disableBackupDomain(void) { #if defined(USE_HALV2_DRIVER) @@ -174,6 +184,11 @@ static inline void disableBackupDomain(void) #endif /* USE_HALV2_DRIVER */ } +/** + * @brief Write a value in a backup register. + * @param index Backup register index. + * @param value Value to write. + */ static inline void setBackupRegister(uint32_t index, uint32_t value) { #if defined(USE_HALV2_DRIVER) @@ -200,6 +215,11 @@ static inline void setBackupRegister(uint32_t index, uint32_t value) #endif } +/** + * @brief Read a value from a backup register. + * @param index Backup register index. + * @return The value stored in the backup register, or 0 if backup registers are not available. + */ static inline uint32_t getBackupRegister(uint32_t index) { #if defined(USE_HALV2_DRIVER) @@ -226,6 +246,12 @@ static inline uint32_t getBackupRegister(uint32_t index) #endif } +/** + * @brief Write 32-bit words to the backup SRAM. + * @param offset Offset, in 32-bit words, from the start of the backup SRAM. + * @param data Pointer to the data to write. + * @param length Number of 32-bit words to write. + */ static inline void writeBackupSRAM(uint32_t offset, uint32_t *data, uint32_t length) { #if defined(BKPSRAM_BASE) @@ -241,6 +267,12 @@ static inline void writeBackupSRAM(uint32_t offset, uint32_t *data, uint32_t len #endif } +/** + * @brief Read 32-bit words from the backup SRAM. + * @param offset Offset, in 32-bit words, from the start of the backup SRAM. + * @param data Pointer to the buffer receiving the data. + * @param length Number of 32-bit words to read. + */ static inline void readBackupSRAM(uint32_t offset, uint32_t *data, uint32_t length) { #if defined(BKPSRAM_BASE) diff --git a/libraries/SrcWrapper/inc/clock.h b/libraries/SrcWrapper/inc/clock.h index a91434a15b..d540ad07a3 100644 --- a/libraries/SrcWrapper/inc/clock.h +++ b/libraries/SrcWrapper/inc/clock.h @@ -34,11 +34,34 @@ typedef enum { /* Exported constants --------------------------------------------------------*/ /* Exported macro ------------------------------------------------------------*/ /* Exported functions ------------------------------------------------------- */ +/** + * @brief Returns the time elapsed since startup, in milliseconds. + * @return Milliseconds since startup, from the HAL tick. Wraps after about 49.7 days. + */ uint32_t getCurrentMillis(void); + +/** + * @brief Returns the time elapsed since startup, in microseconds. + * @return Microseconds since startup, refined with the SysTick counter. Wraps after about 71.6 minutes. + */ uint32_t getCurrentMicros(void); +/** + * @brief Enables the clocks of the system IPs (HSEM, PWR, SYSCFG, CRC) used by the core. + */ void configIPClock(void); + +/** + * @brief Enables the specified clock source if it is not already ready. + * @param source Clock source to enable: LSE_CLOCK, LSI_CLOCK, HSI_CLOCK or HSE_CLOCK. + * @note The backup domain is enabled first. Error_Handler() is called on failure. + */ void enableClock(sourceClock_t source); + +/** + * @brief Applies the HSE capacitor tuning value stored in OTP. + * @note Only effective on STM32WB series when HSE is not already ready. + */ void configHSECapacitorTuning(void); #ifdef __cplusplus diff --git a/libraries/SrcWrapper/inc/core_callback.h b/libraries/SrcWrapper/inc/core_callback.h index 798bc466df..ee06126ad7 100644 --- a/libraries/SrcWrapper/inc/core_callback.h +++ b/libraries/SrcWrapper/inc/core_callback.h @@ -54,8 +54,25 @@ extern "C" { #endif /* Exported functions ------------------------------------------------------- */ +/** + * @brief Adds a callback function to the list called from the main loop. + * @param func Callback function pointer to add. Ignored if NULL. + * @note Up to CALLBACK_LIST_SIZE callbacks can be registered. Extra + * registrations are silently dropped when the list is full. + */ void registerCoreCallback(void (*func)(void)); + +/** + * @brief Removes a callback function from the list. + * @param func Callback function pointer to remove. Ignored if NULL. + */ void unregisterCoreCallback(void (*func)(void)); + +/** + * @brief Calls every registered callback, in the order they were added. + * @note There is no priority: first added is first called. Must be called + * only from the main() loop. + */ void CoreCallback(void); #ifdef __cplusplus diff --git a/libraries/SrcWrapper/inc/digital_io.h b/libraries/SrcWrapper/inc/digital_io.h index 6ec34ebd61..eddd6e039b 100644 --- a/libraries/SrcWrapper/inc/digital_io.h +++ b/libraries/SrcWrapper/inc/digital_io.h @@ -48,12 +48,11 @@ extern "C" { /* Exported functions ------------------------------------------------------- */ /** - * @brief This function set a value to an IO - * @param port : one of the gpio port - * @param pin : one of the gpio pin - * @param val : 0 to set to low, any other value to set to high - * @retval None - */ + * @brief Set a value to an IO. + * @param port One of the GPIO ports. + * @param pin One of the GPIO pins. + * @param val 0 to set to low, any other value to set to high. + */ static inline void digital_io_write(GPIO_TypeDef *port, uint32_t pin, uint32_t val) { if (val) { @@ -64,43 +63,41 @@ static inline void digital_io_write(GPIO_TypeDef *port, uint32_t pin, uint32_t v } /** - * @brief This function read the value of an IO - * @param port : one of the gpio port - * @param pin : one of the gpio pin - * @retval The pin state (LOW or HIGH) - */ + * @brief Read the value of an IO. + * @param port One of the GPIO ports. + * @param pin One of the GPIO pins. + * @return The pin state (LOW or HIGH). + */ static inline uint32_t digital_io_read(GPIO_TypeDef *port, uint32_t pin) { return LL_GPIO_IsInputPinSet(port, pin); } /** - * @brief This function toggle value of an IO - * @param port : one of the gpio port - * @param pin : one of the gpio pin - * @retval None - */ + * @brief Toggle the value of an IO. + * @param port One of the GPIO ports. + * @param pin One of the GPIO pins. + */ static inline void digital_io_toggle(GPIO_TypeDef *port, uint32_t pin) { LL_GPIO_TogglePin(port, pin); } /** - * @brief This function set a value to an IO - * @param pn : Pin name - * @param val : 0 to set to low, any other value to set to high - * @retval None - */ + * @brief Set a value to an IO. + * @param pn Pin name. + * @param ulVal 0 to set to low, any other value to set to high. + */ static inline void digitalWriteFast(PinName pn, uint32_t ulVal) { digital_io_write(get_GPIO_Port(STM_PORT(pn)), STM_LL_GPIO_PIN(pn), ulVal); } /** - * @brief This function read the value of an IO - * @param pn : Pin name - * @retval The pin state (LOW or HIGH) - */ + * @brief Read the value of an IO. + * @param pn Pin name. + * @return The pin state (LOW or HIGH). + */ static inline PinStatus digitalReadFast(PinName pn) { uint8_t level = 0; @@ -109,11 +106,9 @@ static inline PinStatus digitalReadFast(PinName pn) } /** - * @brief This function toggle value of an IO - * @param port : one of the gpio port - * @param pin : one of the gpio pin - * @retval None - */ + * @brief Toggle the value of an IO. + * @param pn Pin name. + */ static inline void digitalToggleFast(PinName pn) { digital_io_toggle(get_GPIO_Port(STM_PORT(pn)), STM_LL_GPIO_PIN(pn)); diff --git a/libraries/SrcWrapper/inc/dwt.h b/libraries/SrcWrapper/inc/dwt.h index f519f6e278..3dd37a2f91 100644 --- a/libraries/SrcWrapper/inc/dwt.h +++ b/libraries/SrcWrapper/inc/dwt.h @@ -30,24 +30,49 @@ extern "C" { #endif +/** + * @brief Initialize the DWT cycle counter and check that it runs. + * @return 0 if the cycle counter started, 1 otherwise. + */ uint32_t dwt_init(void); + +/** + * @brief Unlock or lock access to the DWT registers (Cortex-M7 only, no-op otherwise). + * @param ena true to unlock the DWT registers, false to lock them. + */ void dwt_access(bool ena); +/** + * @brief Get the maximum duration the cycle counter can measure before wrapping. + * @return Maximum duration in seconds. + */ static inline uint32_t dwt_max_sec(void) { return (UINT32_MAX / SystemCoreClock); }; +/** + * @brief Get the maximum duration the cycle counter can measure before wrapping. + * @return Maximum duration in milliseconds. + */ static inline uint32_t dwt_max_msec(void) { return (UINT32_MAX / (SystemCoreClock / 1000)); }; +/** + * @brief Get the maximum duration the cycle counter can measure before wrapping. + * @return Maximum duration in microseconds. + */ static inline uint32_t dwt_max_usec(void) { return (UINT32_MAX / (SystemCoreClock / 1000000)); }; +/** + * @brief Get the current value of the DWT cycle counter. + * @return Number of CPU cycles (DWT CYCCNT register). + */ static inline uint32_t dwt_getCycles(void) { return (DWT->CYCCNT); diff --git a/libraries/SrcWrapper/inc/hw_config.h b/libraries/SrcWrapper/inc/hw_config.h index 269465c222..d15d60abcd 100644 --- a/libraries/SrcWrapper/inc/hw_config.h +++ b/libraries/SrcWrapper/inc/hw_config.h @@ -51,6 +51,10 @@ extern "C" { /* Exported macro ------------------------------------------------------------*/ /* Exported functions ------------------------------------------------------- */ +/** + * @brief Performs the global initialization of the system (HAL, IOs...). + * @note Called once at startup, before setup(). + */ void hw_config_init(void); #ifdef __cplusplus diff --git a/libraries/SrcWrapper/inc/interrupt.h b/libraries/SrcWrapper/inc/interrupt.h index 5a3420ccbf..7f51f4178e 100644 --- a/libraries/SrcWrapper/inc/interrupt.h +++ b/libraries/SrcWrapper/inc/interrupt.h @@ -64,10 +64,22 @@ #include typedef std::function callback_function_t; + /** + * @brief Enable the EXTI interrupt on a pin and register its callback. + * @param pn Pin name (e.g. PA_0) to attach the interrupt to. + * @param callback Function called when the interrupt fires. + * @param mode Trigger mode, e.g. GPIO_MODE_IT_RISING, GPIO_MODE_IT_FALLING + * or GPIO_MODE_IT_RISING_FALLING (hal_exti_trigger_t when USE_HALV2_DRIVER). + */ void stm32_interrupt_enable(PinName pn, callback_function_t callback, uint32_t mode); #endif /* Exported functions ------------------------------------------------------- */ + /** + * @brief Disable the EXTI interrupt on a pin and clear its callback. + * @param port GPIO port of the pin (unused, kept for API compatibility). + * @param pin GPIO pin mask (e.g. GPIO_PIN_0) to disable. + */ void stm32_interrupt_disable(GPIO_TypeDef *port, uint16_t pin); #endif /* !HAL_EXTI_MODULE_DISABLED */ diff --git a/libraries/SrcWrapper/inc/lock_resource.h b/libraries/SrcWrapper/inc/lock_resource.h index 09f5382264..814d9db2c4 100644 --- a/libraries/SrcWrapper/inc/lock_resource.h +++ b/libraries/SrcWrapper/inc/lock_resource.h @@ -178,14 +178,13 @@ typedef enum { #define HSEM_LOCK_DEFAULT_RETRY 0xFFFFU #endif -/* - * @brief hsem_lock function is used for register protection of shared Peripheral - * and shall be called before accessing registers of this shared Peripheral - * If Semaphore id is already taken, the function will busy loop waiting for it to - * be released, but give up after @retry downcounter have elapsed - * @param semID: Semaphore id used to identify which peripheral to protect - * @param retry: number of retry - * @retval None +/** + * @brief Acquire a hardware semaphore to protect a shared peripheral. + * Call this before accessing registers of the shared peripheral. + * If the semaphore is already taken, the function busy-waits for it to + * be released, but gives up after the retry down-counter has elapsed. + * @param semID Semaphore ID used to identify which peripheral to protect. + * @param retry Number of retries (HSEM_LOCK_WAIT_FOREVER to wait indefinitely). */ static inline void hsem_lock(uint32_t semID, uint32_t retry) { @@ -206,10 +205,9 @@ static inline void hsem_lock(uint32_t semID, uint32_t retry) #endif /* STM32MP1xx || STM32WBxx */ } -/* - * @brief hsem_unlock released a previously-acquired semaphore - * @param semID Semaphore id used to identify which peripheral to release - * @retval None +/** + * @brief Release a previously acquired hardware semaphore. + * @param semID Semaphore ID used to identify which peripheral to release. */ static inline void hsem_unlock(uint32_t semID) { diff --git a/libraries/SrcWrapper/inc/otp.h b/libraries/SrcWrapper/inc/otp.h index 0826098a84..692c9c7532 100644 --- a/libraries/SrcWrapper/inc/otp.h +++ b/libraries/SrcWrapper/inc/otp.h @@ -47,8 +47,8 @@ typedef struct __packed { * | 8bits | 58bits | * | MSB | LSB | * - * @param id: ID of the parameter to read from OTP - * @retval Address of the ID in the OTP - returns 0 when no ID found + * @param id ID of the parameter to read from OTP. + * @return Address of the ID in the OTP, or 0 when no ID is found. */ uint8_t *OTP_Read(uint8_t id); diff --git a/libraries/SrcWrapper/inc/pinconfig.h b/libraries/SrcWrapper/inc/pinconfig.h index 59f63b0c7c..b4d9cff08a 100644 --- a/libraries/SrcWrapper/inc/pinconfig.h +++ b/libraries/SrcWrapper/inc/pinconfig.h @@ -19,6 +19,11 @@ #include "lock_resource.h" #include "stm32yyxx_ll_gpio.h" +/** + * @brief Disconnect the debug pins (JTAG/SWD) so they can be used as GPIO. + * @param pin Pin name. + * Only acts on STM32F1xx; no-op on other families. + */ static inline void pin_DisconnectDebug(PinName pin) { #ifdef STM32F1xx @@ -28,6 +33,13 @@ static inline void pin_DisconnectDebug(PinName pin) #endif /* STM32F1xx */ } +/** + * @brief Set the pull configuration of a GPIO pin. + * @param gpio GPIO port of the pin. + * @param ll_pin LL GPIO pin mask (see STM_LL_GPIO_PIN). + * @param pull_config LL_GPIO_PULL_NO, LL_GPIO_PULL_UP or LL_GPIO_PULL_DOWN. + * On STM32F1xx, a pin without pull is set to floating input. + */ static inline void pin_PullConfig(GPIO_TypeDef *gpio, uint32_t ll_pin, uint32_t pull_config) { #ifdef STM32F1xx @@ -51,6 +63,12 @@ static inline void pin_PullConfig(GPIO_TypeDef *gpio, uint32_t ll_pin, uint32_t #endif } +/** + * @brief Set the alternate function number of a GPIO pin. + * @param gpio GPIO port of the pin. + * @param pin Pin name. + * @param afnum Alternate function number (AFIO remap value on STM32F1xx). + */ static inline void pin_SetAFPin(GPIO_TypeDef *gpio, PinName pin, uint32_t afnum) { #ifdef STM32F1xx diff --git a/libraries/SrcWrapper/inc/pinmap.h b/libraries/SrcWrapper/inc/pinmap.h index 60ff991c0b..56d4db10c1 100644 --- a/libraries/SrcWrapper/inc/pinmap.h +++ b/libraries/SrcWrapper/inc/pinmap.h @@ -43,21 +43,94 @@ typedef struct { int function; } PinMap; +/** + * @brief Check whether a pin is present in a pinmap. + * @param pin Pin name to look for. + * @param map PinMap array, terminated by an entry with pin NC. + * @return true if the pin is found in the map, false otherwise. + */ bool pin_in_pinmap(PinName pin, const PinMap *map); + +/** + * @brief Configure a pin: mode, speed, output type, pull-up/pull-down and AF. + * @param pin Pin name. + * @param function Pin function, encoded with the STM_PIN_* macros. + * Calls Error_Handler if the pin is NC or the mode is unknown. + */ void pin_function(PinName pin, int function); +/** + * @brief Get the pin name of a PinMap entry. + * @param map PinMap entry. + * @return Pin name stored in the entry. + */ static inline PinName pin_pinName(const PinMap *map) { return map->pin; } +/** + * @brief Configure a pin from a pinmap entry matching the pin. + * @param pin Pin name. + * @param map PinMap array, terminated by an entry with pin NC. + * Calls Error_Handler if the pin is not found in the map. + */ void pinmap_pinout(PinName pin, const PinMap *map); + +/** + * @brief Find the peripheral associated with a pin. + * @param pin Pin name. + * @param map PinMap array, terminated by an entry with pin NC. + * @return Peripheral pointer, or NP if not found. + */ void *pinmap_find_peripheral(PinName pin, const PinMap *map); + +/** + * @brief Find the peripheral associated with a pin, ignoring NC pins. + * @param pin Pin name. + * @param map PinMap array, terminated by an entry with pin NC. + * @return Peripheral pointer, or NP if the pin is NC or not found. + */ void *pinmap_peripheral(PinName pin, const PinMap *map); + +/** + * @brief Find the pin associated with a peripheral. + * @param peripheral Peripheral pointer. + * @param map PinMap array, terminated by an entry with peripheral NP. + * @return Pin name, or NC if not found. + */ PinName pinmap_find_pin(void *peripheral, const PinMap *map); + +/** + * @brief Find the pin associated with a peripheral, ignoring NP peripherals. + * @param peripheral Peripheral pointer. + * @param map PinMap array, terminated by an entry with peripheral NP. + * @return Pin name, or NC if the peripheral is NP or not found. + */ PinName pinmap_pin(void *peripheral, const PinMap *map); + +/** + * @brief Find the function associated with a pin. + * @param pin Pin name. + * @param map PinMap array, terminated by an entry with pin NC. + * @return Function value, or NC cast to uint32_t if not found. + */ uint32_t pinmap_find_function(PinName pin, const PinMap *map); + +/** + * @brief Find the function associated with a pin, ignoring NC pins. + * @param pin Pin name. + * @param map PinMap array, terminated by an entry with pin NC. + * @return Function value, or NC cast to uint32_t if the pin is NC or not found. + */ uint32_t pinmap_function(PinName pin, const PinMap *map); + +/** + * @brief Merge two peripheral pointers that may be NP. + * @param a First peripheral pointer. + * @param b Second peripheral pointer. + * @return The peripheral that is set, or a if both are the same. NP if they conflict. + */ void *pinmap_merge_peripheral(void *a, void *b); #ifdef __cplusplus diff --git a/libraries/SrcWrapper/inc/stm32_def.h b/libraries/SrcWrapper/inc/stm32_def.h index f63b83de26..b791c5f783 100644 --- a/libraries/SrcWrapper/inc/stm32_def.h +++ b/libraries/SrcWrapper/inc/stm32_def.h @@ -149,54 +149,51 @@ #endif /** - * @brief Get Binary mode (Sub Second Register) - * @rmtoll RTC_ICSR BIN LL_RTC_GetBinaryMode - * @param RTCx RTC Instance - * @retval This parameter can be one of the following values: - * @arg @ref LL_RTC_BINARY_NONE - * @arg @ref LL_RTC_BINARY_ONLY - * @arg @ref LL_RTC_BINARY_MIX - * @retval None - */ + * @brief Get Binary mode (Sub Second Register) + * @rmtoll RTC_ICSR BIN LL_RTC_GetBinaryMode + * @param RTCx RTC Instance + * @return Binary mode, one of the following values: + * @arg @ref LL_RTC_BINARY_NONE + * @arg @ref LL_RTC_BINARY_ONLY + * @arg @ref LL_RTC_BINARY_MIX + */ __STATIC_INLINE uint32_t LL_RTC_GetBinaryMode(const RTC_TypeDef *RTCx) { return (uint32_t)(READ_BIT(RTCx->ICSR, RTC_ICSR_BIN)); } /** - * @brief Set Binary mode (Sub Second Register) - * @note Bit is write-protected. @ref LL_RTC_DisableWriteProtection function should be called before. - * @note It can be written in initialization mode only (@ref LL_RTC_EnableInitMode function). - * @rmtoll RTC_ICSR BIN LL_RTC_SetBinaryMode - * @param RTCx RTC Instance - * @param BinaryMode can be one of the following values: - * @arg @ref LL_RTC_BINARY_NONE - * @arg @ref LL_RTC_BINARY_ONLY - * @arg @ref LL_RTC_BINARY_MIX - * @retval None - */ + * @brief Set Binary mode (Sub Second Register) + * @note Bit is write-protected. @ref LL_RTC_DisableWriteProtection function should be called before. + * @note It can be written in initialization mode only (@ref LL_RTC_EnableInitMode function). + * @rmtoll RTC_ICSR BIN LL_RTC_SetBinaryMode + * @param RTCx RTC Instance + * @param BinaryMode can be one of the following values: + * @arg @ref LL_RTC_BINARY_NONE + * @arg @ref LL_RTC_BINARY_ONLY + * @arg @ref LL_RTC_BINARY_MIX + */ __STATIC_INLINE void LL_RTC_SetBinaryMode(RTC_TypeDef *RTCx, uint32_t BinaryMode) { MODIFY_REG(RTCx->ICSR, RTC_ICSR_BIN, BinaryMode); } /** - * @brief Set Binary Mix mode BCDU - * @note Bit is write-protected. @ref LL_RTC_DisableWriteProtection function should be called before. - * @note It can be written in initialization mode only (@ref LL_RTC_EnableInitMode function). - * @rmtoll RTC_ICSR BCDU LL_RTC_SetBinMixBCDU - * @param RTCx RTC Instance - * @param BinMixBcdU can be one of the following values: - * @arg @ref LL_RTC_BINARY_MIX_BCDU_0 - * @arg @ref LL_RTC_BINARY_MIX_BCDU_1 - * @arg @ref LL_RTC_BINARY_MIX_BCDU_2 - * @arg @ref LL_RTC_BINARY_MIX_BCDU_3 - * @arg @ref LL_RTC_BINARY_MIX_BCDU_4 - * @arg @ref LL_RTC_BINARY_MIX_BCDU_5 - * @arg @ref LL_RTC_BINARY_MIX_BCDU_6 - * @arg @ref LL_RTC_BINARY_MIX_BCDU_7 - * @retval None - */ + * @brief Set Binary Mix mode BCDU + * @note Bit is write-protected. @ref LL_RTC_DisableWriteProtection function should be called before. + * @note It can be written in initialization mode only (@ref LL_RTC_EnableInitMode function). + * @rmtoll RTC_ICSR BCDU LL_RTC_SetBinMixBCDU + * @param RTCx RTC Instance + * @param BinMixBcdU can be one of the following values: + * @arg @ref LL_RTC_BINARY_MIX_BCDU_0 + * @arg @ref LL_RTC_BINARY_MIX_BCDU_1 + * @arg @ref LL_RTC_BINARY_MIX_BCDU_2 + * @arg @ref LL_RTC_BINARY_MIX_BCDU_3 + * @arg @ref LL_RTC_BINARY_MIX_BCDU_4 + * @arg @ref LL_RTC_BINARY_MIX_BCDU_5 + * @arg @ref LL_RTC_BINARY_MIX_BCDU_6 + * @arg @ref LL_RTC_BINARY_MIX_BCDU_7 + */ __STATIC_INLINE void LL_RTC_SetBinMixBCDU(RTC_TypeDef *RTCx, uint32_t BinMixBcdU) { MODIFY_REG(RTCx->ICSR, RTC_ICSR_BCDU, BinMixBcdU); @@ -251,6 +248,9 @@ extern "C" { #endif // __cplusplus // weaked functions declaration +/** + * @brief Configure the system clock. Overridable by the board variant. + */ void SystemClock_Config(void); #if defined(NDEBUG) @@ -267,6 +267,11 @@ void SystemClock_Config(void); } #endif #else +/** + * @brief Report a fatal error and halt execution. + * @param msg Error message (typically __FILE__). + * @param val Error value (typically __LINE__). + */ void _Error_Handler(const char *, int); #define Error_Handler() _Error_Handler(__FILE__, __LINE__) diff --git a/libraries/SrcWrapper/inc/timer.h b/libraries/SrcWrapper/inc/timer.h index 3e484accc5..ab4434ae5f 100644 --- a/libraries/SrcWrapper/inc/timer.h +++ b/libraries/SrcWrapper/inc/timer.h @@ -293,20 +293,66 @@ typedef struct { } timerObj_t; /* Exported functions ------------------------------------------------------- */ +/** + * @brief Get the timerObj_t that embeds a HAL timer handle. + * @param htim HAL timer handle stored inside a timerObj_t. + * @return Pointer to the enclosing timerObj_t. + */ #if defined(USE_HALV2_DRIVER) timerObj_t *get_timer_obj(hal_tim_handle_t *htim); #else timerObj_t *get_timer_obj(TIM_HandleTypeDef *htim); #endif + +/** + * @brief Enable the clock of a timer instance. + * @param instance Timer instance (e.g. TIM1). + */ void enableTimerClock(TIM_TypeDef *instance); + +/** + * @brief Disable the clock of a timer instance. + * @param instance Timer instance (e.g. TIM1). + */ void disableTimerClock(TIM_TypeDef *instance); +/** + * @brief Get the IRQ number of a timer instance. + * @param tim Timer instance. + * @return IRQ number of the timer. + * This function is declared but has no definition in SrcWrapper. + */ uint32_t getTimerIrq(TIM_TypeDef *tim); + +/** + * @brief Get the clock source of a timer instance. + * @param tim Timer instance. + * @return 1 for PCLK1, 2 for PCLK2. + */ uint8_t getTimerClkSrc(TIM_TypeDef *tim); +/** + * @brief Get the IRQ number of the update interrupt of a timer instance. + * @param tim Timer instance. + * @return IRQ number of the update interrupt. + * Calls _Error_Handler if the instance is unknown. + */ IRQn_Type getTimerUpIrq(TIM_TypeDef *tim); + +/** + * @brief Get the IRQ number of the capture/compare interrupt of a timer instance. + * @param tim Timer instance. + * @return IRQ number of the capture/compare interrupt. + * Calls _Error_Handler if the instance is unknown. + */ IRQn_Type getTimerCCIrq(TIM_TypeDef *tim); +/** + * @brief Get the HAL timer channel linked to a pin. + * @param pin PinName with a timer function. + * @return HAL channel. Inverted pins map to the complementary (N) channel. + * Calls _Error_Handler if the pin channel is unknown. + */ #if defined(USE_HALV2_DRIVER) hal_tim_channel_t getTimerChannel(PinName pin); #else diff --git a/libraries/SrcWrapper/inc/uart.h b/libraries/SrcWrapper/inc/uart.h index de8fb0e20e..de05da546a 100644 --- a/libraries/SrcWrapper/inc/uart.h +++ b/libraries/SrcWrapper/inc/uart.h @@ -260,28 +260,95 @@ struct serial_s { /* Exported macro ------------------------------------------------------------*/ /* Exported functions ------------------------------------------------------- */ +/** + * @brief Initialize the UART interface. + * @param obj Pointer to serial_t structure. + * @param baudrate Baud rate. + * @param databits Word length. + * @param parity Parity configuration. + * @param stopbits Number of stop bits. + * @param rx_invert Invert the RX line. + * @param tx_invert Invert the TX line. + * @param data_invert Invert the data bits. + * @return true on success, false otherwise. + */ #if defined(USE_HALV2_DRIVER) bool uart_init(serial_t *obj, uint32_t baudrate, hal_uart_word_length_t databits, hal_uart_parity_t parity, hal_uart_stop_bits_t stopbits, bool rx_invert, bool tx_invert, bool data_invert); #else bool uart_init(serial_t *obj, uint32_t baudrate, uint32_t databits, uint32_t parity, uint32_t stopbits, bool rx_invert, bool tx_invert, bool data_invert); #endif +/** + * @brief Deinitialize the UART interface. + * @param obj Pointer to serial_t structure. + */ void uart_deinit(serial_t *obj); +/** + * @brief Configure the UART interface for low power operation. + * @param obj Pointer to serial_t structure. + */ #if defined(HAL_PWR_MODULE_ENABLED) && (defined(UART_IT_WUF) || defined(LPUART1_BASE)) void uart_config_lowpower(serial_t *obj); #endif +/** + * @brief Read the last received byte from the UART. + * @param obj Pointer to serial_t structure. + * @param c Pointer where the received character is stored. + * @return 0 on success, -1 if obj is NULL or a reception is ongoing. + */ int uart_getc(serial_t *obj, unsigned char *c); +/** + * @brief Begin an asynchronous RX transfer (enable interrupt for data collecting). + * @param obj Pointer to serial_t structure. + * @param callback Function called at the end of reception. + */ void uart_attach_rx_callback(serial_t *obj, void (*callback)(serial_t *)); +/** + * @brief Begin an asynchronous TX transfer. + * @param obj Pointer to serial_t structure. + * @param callback Function called at the end of transmission. + * @param size Number of bytes to transmit. + */ void uart_attach_tx_callback(serial_t *obj, int (*callback)(serial_t *), size_t size); +/** + * @brief Determine if the serial peripheral is already in use for TX. + * @param obj The serial object. + * @return Non-zero if the TX transaction is ongoing, 0 otherwise. + */ uint8_t serial_tx_active(serial_t *obj); +/** + * @brief Determine if the serial peripheral is already in use for RX. + * @param obj The serial object. + * @return Non-zero if the RX transaction is ongoing, 0 otherwise. + */ uint8_t serial_rx_active(serial_t *obj); +/** + * @brief Enable the transmitter for half-duplex mode. No-op in full-duplex mode. + * @param obj Pointer to serial_t structure. + */ void uart_enable_tx(serial_t *obj); +/** + * @brief Enable the receiver for half-duplex mode. No-op in full-duplex mode. + * @param obj Pointer to serial_t structure. + */ void uart_enable_rx(serial_t *obj); +/** + * @brief Write data on the UART, used by printf for debug only (syscalls). + * @param data Bytes to write. + * @param size Number of bytes to write. + * @return The number of bytes written. + */ size_t uart_debug_write(uint8_t *data, uint32_t size); #if defined(LPUART1_BASE) || defined(LPUART2_BASE) +/** + * @brief Configure the LPUART stop mode according to the baud rate. + * LPUART clock source must be in the range [3 x baud rate, 4096 x baud rate]. + * @param huart uart handle structure. + * @param baudrate Baud rate (HALv2 driver only). + */ #if defined(USE_HALV2_DRIVER) void uart_init_lpuart(hal_uart_handle_t *huart, uint32_t baudrate); #else @@ -289,11 +356,27 @@ void uart_init_lpuart(UART_HandleTypeDef *huart); #endif #endif +/** + * @brief Compute the UART clock prescaler. + * @param huart uart handle structure. + * @param config uart configuration structure (HALv2 driver only). + * @return The clock prescaler. + */ #if defined(USE_HALV2_DRIVER) hal_uart_prescaler_t uart_compute_prescaler(hal_uart_handle_t *huart, hal_uart_config_t *config); #endif #if defined(UART_PRESCALER_DIV1) +/** + * @brief Compute the UART clock prescaler. + * @param huart uart handle structure. + * @return The clock prescaler. + */ uint32_t uart_compute_prescaler(UART_HandleTypeDef *huart); +/** + * @brief Get the clock source frequency of the UART. + * @param huart uart handle structure. + * @return The clock source frequency in Hz. + */ uint32_t uart_get_clock_source_freq(UART_HandleTypeDef *huart); #endif #endif /* HAL_UART_MODULE_ENABLED && !HAL_UART_MODULE_ONLY */ diff --git a/libraries/SrcWrapper/src/HardwareTimer.cpp b/libraries/SrcWrapper/src/HardwareTimer.cpp index 9bb50bee23..1b23614688 100644 --- a/libraries/SrcWrapper/src/HardwareTimer.cpp +++ b/libraries/SrcWrapper/src/HardwareTimer.cpp @@ -50,41 +50,17 @@ timerObj_t *HardwareTimer_Handle[TIMER_NUM] = {NULL}; #endif #endif -/** - * @brief HardwareTimer constructor: make uninitialized timer - * Before calling any methods, call setup to select and setup - * the timer to be used. - * @retval None - */ HardwareTimer::HardwareTimer() { _timerObj.instance = nullptr; } -/** - * @brief HardwareTimer constructor: set default configuration values - * The timer will be usable directly, there is no need to call - * setup(). Using this constructor is not recommended for - * global variables that are automatically initialized at - * startup, since this will happen to early to report any - * errors. Better use the argumentless constructor and call the - * setup() method during initialization later. - * @param Timer instance ex: TIM1, ... - * @retval None - */ HardwareTimer::HardwareTimer(TIM_TypeDef *instance) { _timerObj.instance = nullptr; setup(instance); } -/** - * @brief HardwareTimer setup: configuration values. Must be called - * exactly once before any other methods, except when an instance is - * passed to the constructor. - * @param Timer instance ex: TIM1, ... - * @retval None - */ void HardwareTimer::setup(TIM_TypeDef *instance) { uint32_t index = get_timer_index(instance); @@ -168,11 +144,6 @@ void HardwareTimer::setup(TIM_TypeDef *instance) #endif } -/** - * @brief Pause HardwareTimer: stop timer - * @param None - * @retval None - */ void HardwareTimer::pause() { // Disable all IT @@ -202,12 +173,6 @@ void HardwareTimer::pause() #endif } -/** - * @brief Pause only one channel. - * Timer is still running but channel is disabled (output and interrupt) - * @param Arduino channel [1..4] - * @retval None - */ void HardwareTimer::pauseChannel(uint32_t channel) { if ((channel < 1) || (channel > TIMER_CHANNELS)) { @@ -256,11 +221,6 @@ void HardwareTimer::pauseChannel(uint32_t channel) } } -/** - * @brief Start or resume HardwareTimer: all channels are resumed, interrupts are enabled if necessary - * @param None - * @retval None - */ void HardwareTimer::resume(void) { bool baseStart = true; @@ -285,11 +245,6 @@ void HardwareTimer::resume(void) } } -/** - * @brief Convert arduino channel into HAL channel - * @param Arduino channel [1..4] - * @retval HAL channel. Error handler called if arduino channel is invalid - */ #if defined(USE_HALV2_DRIVER) hal_tim_channel_t HardwareTimer::getChannel(uint32_t channel, bool complementary) { @@ -354,11 +309,6 @@ uint32_t HardwareTimer::getChannel(uint32_t channel) } #endif -/** - * @brief Convert arduino channel into LL channels used (regular and/or complementary) - * @param Arduino channel [1..4] - * @retval LL channel. Error handler called if arduino channel is invalid - */ uint32_t HardwareTimer::getLLChannel(uint32_t channel) { bool error = false; @@ -420,12 +370,6 @@ uint32_t HardwareTimer::getLLChannel(uint32_t channel) return ll_channel; } -/** - * @brief Handle itterupt based on arduino channel - * @param Arduino channel [1..4] - * @param config: configuration for the interrupt (enable, disable, clear, clear and disable) - * @retval true if interrupt is enabled, false otherwise - */ bool HardwareTimer::manageIT(uint32_t channel, ChannelITConfig_t config) { bool isEnabled = false; @@ -485,12 +429,6 @@ bool HardwareTimer::manageIT(uint32_t channel, ChannelITConfig_t config) return isEnabled; } -/** - * @brief Get input associated channel - * Channel 1 and 2 are associated; channel 3 and 4 are associated - * @param Arduino channel [1..4] - * @retval HAL channel. Error handler called if arduino channel is invalid - */ uint32_t HardwareTimer::getAssociatedChannel(uint32_t channel) { uint32_t timAssociatedInputChannel = 0; @@ -514,11 +452,6 @@ uint32_t HardwareTimer::getAssociatedChannel(uint32_t channel) return timAssociatedInputChannel; } -/** - * @brief Configure specified channel and resume/start timer - * @param Arduino channel [1..4] - * @retval None - */ void HardwareTimer::resumeChannel(uint32_t channel) { #if defined(USE_HALV2_DRIVER) @@ -623,22 +556,12 @@ void HardwareTimer::resumeChannel(uint32_t channel) } } -/** - * @brief Retrieve prescaler from hardware register - * @param None - * @retval prescaler factor - */ uint32_t HardwareTimer::getPrescaleFactor() { // Hardware register correspond to prescaler-1. Example PSC register value 0 means divided by 1 return (LL_TIM_GetPrescaler(_timerObj.instance) + 1); } -/** - * @brief Configure hardwareTimer prescaler - * @param prescaler factor - * @retval None - */ void HardwareTimer::setPrescaleFactor(uint32_t prescaler) { // Hardware register correspond to prescaler-1. Example PSC register value 0 means divided by 1 @@ -647,14 +570,6 @@ void HardwareTimer::setPrescaleFactor(uint32_t prescaler) updateRegistersIfNotRunning(_timerObj.instance); } -/** - * @brief Retrieve overflow (rollover) value from hardware register - * @param format of returned value. If omitted default format is Tick - * @retval overflow depending on format value: - * TICK_FORMAT: return number of tick for overflow - * MICROSEC_FORMAT: return number of microsecondes for overflow - * HERTZ_FORMAT: return frequency in hertz for overflow - */ uint32_t HardwareTimer::getOverflow(TimerFormat_t format) { // Hardware register correspond to period count-1. Example ARR register value 9 means period of 10 timer cycle @@ -676,20 +591,6 @@ uint32_t HardwareTimer::getOverflow(TimerFormat_t format) return return_value; } -/** - * @brief Set overflow (rollover) - * - * Note that by default, the new value will not be applied - * immediately, but become effective at the next update event - * (usually the next timer overflow). See setPreloadEnable() - * for controlling this behaviour. - * @param overflow: depend on format parameter - * @param format of overflow parameter. If omitted default format is Tick - * TICK_FORMAT: overflow is the number of tick for overflow - * MICROSEC_FORMAT: overflow is the number of microsecondes for overflow - * HERTZ_FORMAT: overflow is the frequency in hertz for overflow - * @retval None - */ void HardwareTimer::setOverflow(uint32_t overflow, TimerFormat_t format) { uint32_t ARR_RegisterValue; @@ -728,14 +629,6 @@ void HardwareTimer::setOverflow(uint32_t overflow, TimerFormat_t format) updateRegistersIfNotRunning(_timerObj.instance); } -/** - * @brief Retrieve timer counter value - * @param format of returned value. If omitted default format is Tick - * @retval overflow depending on format value: - * TICK_FORMAT: return number of tick for counter - * MICROSEC_FORMAT: return number of microsecondes for counter - * HERTZ_FORMAT: return frequency in hertz for counter - */ uint32_t HardwareTimer::getCount(TimerFormat_t format) { uint32_t CNT_RegisterValue = LL_TIM_GetCounter(_timerObj.instance); @@ -759,15 +652,6 @@ uint32_t HardwareTimer::getCount(TimerFormat_t format) return return_value; } -/** - * @brief Set timer counter value - * @param counter: depend on format parameter - * @param format of overflow parameter. If omitted default format is Tick - * TICK_FORMAT: counter is the number of tick - * MICROSEC_FORMAT: counter is the number of microsecondes - * HERTZ_FORMAT: counter is the frequency in hertz - * @retval None - */ void HardwareTimer::setCount(uint32_t counter, TimerFormat_t format) { uint32_t CNT_RegisterValue; @@ -787,25 +671,11 @@ void HardwareTimer::setCount(uint32_t counter, TimerFormat_t format) LL_TIM_SetCounter(_timerObj.instance, CNT_RegisterValue); } -/** - * @brief Set channel mode - * @param channel: Arduino channel [1..4] - * @param mode: mode configuration for the channel (see TimerModes_t) - * @param pin: Arduino pin number, ex: D1, 1 or PA1 - * @retval None - */ void HardwareTimer::setMode(uint32_t channel, TimerModes_t mode, pin_size_t pin, ChannelInputFilter_t filter) { setMode(channel, mode, digitalPinToPinName(pin), filter); } -/** - * @brief Set channel mode - * @param channel: Arduino channel [1..4] - * @param mode: mode configuration for the channel (see TimerModes_t) - * @param pin: pin name, ex: PB_0 - * @retval None - */ void HardwareTimer::setMode(uint32_t channel, TimerModes_t mode, PinName pin, ChannelInputFilter_t filter) { uint32_t timAssociatedInputChannel; @@ -1059,30 +929,11 @@ void HardwareTimer::setMode(uint32_t channel, TimerModes_t mode, PinName pin, Ch } } -/** - * @brief Retrieves channel mode configured - * @param channel: Arduino channel [1..4] - * @retval returns configured mode - */ TimerModes_t HardwareTimer::getMode(uint32_t channel) { return ((1 <= channel) && (channel <= TIMER_CHANNELS)) ? _ChannelMode[channel - 1] : TIMER_OUTPUT_DISABLED; } -/** - * @brief Enable or disable preloading for overflow value - * When disabled, changes to the overflow value take effect - * immediately. When enabled (the default), the value takes - * effect only at the next update event (typically the next - * overflow). - * - * Note that the capture/compare register has its own preload - * enable bit, which is independent and enabled in PWM modes - * and disabled otherwise. If you need more control of that - * bit, you can use the HAL functions directly. - * @param value: true to enable preloading, false to disable - * @retval None - */ void HardwareTimer::setPreloadEnable(bool value) { if (value) { @@ -1092,16 +943,6 @@ void HardwareTimer::setPreloadEnable(bool value) } } -/** - * @brief Set channel Capture/Compare register - * @param channel: Arduino channel [1..4] - * @param compare: compare value depending on format - * @param format of compare parameter. If omitted default format is Tick - * TICK_FORMAT: compare is the number of tick - * MICROSEC_FORMAT: compare is the number of microsecondes - * HERTZ_FORMAT: compare is the frequency in hertz - * @retval None - */ void HardwareTimer::setCaptureCompare(uint32_t channel, uint32_t compare, TimerCompareFormat_t format) { uint32_t Prescalerfactor = LL_TIM_GetPrescaler(_timerObj.instance) + 1; @@ -1169,15 +1010,6 @@ void HardwareTimer::setCaptureCompare(uint32_t channel, uint32_t compare, TimerC updateRegistersIfNotRunning(_timerObj.instance); } -/** - * @brief Retrieve Capture/Compare value - * @param channel: Arduino channel [1..4] - * @param format of return value. If omitted default format is Tick - * TICK_FORMAT: return value is the number of tick for Capture/Compare value - * MICROSEC_FORMAT: return value is the number of microsecondes for Capture/Compare value - * HERTZ_FORMAT: return value is the frequency in hertz for Capture/Compare value - * @retval Capture/Compare value - */ uint32_t HardwareTimer::getCaptureCompare(uint32_t channel, TimerCompareFormat_t format) { uint32_t CCR_RegisterValue = 0; @@ -1245,30 +1077,11 @@ uint32_t HardwareTimer::getCaptureCompare(uint32_t channel, TimerCompareFormat_ return return_value; } -/** - * @param channel: Arduino channel [1..4] - * @param pin: Arduino pin number, ex D1, 1 or PA1 - * @param frequency: PWM frequency expressed in hertz - * @param dutycycle: PWM dutycycle expressed in percentage - * @param PeriodCallback: timer period callback (timer rollover upon update event) - * @param CompareCallback: timer compare callback - * @retval None - */ void HardwareTimer::setPWM(uint32_t channel, pin_size_t pin, uint32_t frequency, uint32_t dutycycle, callback_function_t PeriodCallback, callback_function_t CompareCallback) { setPWM(channel, digitalPinToPinName(pin), frequency, dutycycle, PeriodCallback, CompareCallback); } -/** - * @brief All in one function to configure PWM - * @param channel: Arduino channel [1..4] - * @param pin: pin name, ex PB_0 - * @param frequency: PWM frequency expressed in hertz - * @param dutycycle: PWM dutycycle expressed in percentage - * @param PeriodCallback: timer period callback (timer rollover upon update event) - * @param CompareCallback: timer compare callback - * @retval None - */ void HardwareTimer::setPWM(uint32_t channel, PinName pin, uint32_t frequency, uint32_t dutycycle, callback_function_t PeriodCallback, callback_function_t CompareCallback) { TimerModes_t previousMode = getMode(channel); @@ -1288,13 +1101,6 @@ void HardwareTimer::setPWM(uint32_t channel, PinName pin, uint32_t frequency, ui } } -/** - * @brief Set the priority of the interrupt - * @note Must be call before resume() - * @param preemptPriority: the pre-emption priority for the IRQn channel - * @param subPriority: the subpriority level for the IRQ channel. - * @retval None - */ void HardwareTimer::setInterruptPriority(uint32_t preemptPriority, uint32_t subPriority) { // Set Update interrupt priority for immediate use @@ -1321,11 +1127,6 @@ void HardwareTimer::setInterruptPriority(uint32_t preemptPriority, uint32_t subP _timerObj.subPriority = subPriority; } -/** - * @brief Attach interrupt callback on update (rollover) event - * @param callback: interrupt callback - * @retval None - */ void HardwareTimer::attachInterrupt(callback_function_t callback) { if (callbacks[0]) { @@ -1342,10 +1143,6 @@ void HardwareTimer::attachInterrupt(callback_function_t callback) } } -/** - * @brief Detach interrupt callback on update (rollover) event - * @retval None - */ void HardwareTimer::detachInterrupt() { // Disable update interrupt and clear callback @@ -1353,12 +1150,6 @@ void HardwareTimer::detachInterrupt() callbacks[0] = NULL; } -/** - * @brief Attach interrupt callback on Capture/Compare event - * @param channel: Arduino channel [1..4] - * @param callback: interrupt callback - * @retval None - */ void HardwareTimer::attachInterrupt(uint32_t channel, callback_function_t callback) { if ((channel == 0) || (channel > (TIMER_CHANNELS + 1))) { @@ -1376,11 +1167,6 @@ void HardwareTimer::attachInterrupt(uint32_t channel, callback_function_t callba } } -/** - * @brief Detach interrupt callback on Capture/Compare event - * @param channel: Arduino channel [1..4] - * @retval None - */ void HardwareTimer::detachInterrupt(uint32_t channel) { if ((channel == 0) || (channel > (TIMER_CHANNELS + 1))) { @@ -1391,20 +1177,11 @@ void HardwareTimer::detachInterrupt(uint32_t channel) callbacks[channel] = NULL; } -/** - * @brief Checks if there's an interrupt callback attached on Rollover event - * @retval returns true if a timer rollover interrupt has already been set - */ bool HardwareTimer::hasInterrupt() { return callbacks[0] != NULL; } -/** - * @brief Checks if there's an interrupt callback attached on Capture/Compare event - * @param channel: Arduino channel [1..4] - * @retval returns true if a channel compare match interrupt has already been set - */ bool HardwareTimer::hasInterrupt(uint32_t channel) { if ((channel == 0) || (channel > (TIMER_CHANNELS + 1))) { @@ -1413,13 +1190,6 @@ bool HardwareTimer::hasInterrupt(uint32_t channel) return callbacks[channel] != NULL; } -/** - * @brief Generate an update event to force all registers (Autoreload, prescaler, compare) to be taken into account - * @note @note Refresh() can only be called after timer has been initialized, - either by calling setup() function or thanks to constructor with TIM instance parameter. - * It is useful while timer is running after some registers update - * @retval None - */ void HardwareTimer::refresh() { #if defined(USE_HALV2_DRIVER) @@ -1429,13 +1199,6 @@ void HardwareTimer::refresh() #endif } -/** - * @brief Return the timer object handle object for more advanced setup - * @note Using this function and editing the Timer handle is at own risk! No support will - * be provided whatsoever if the HardwareTimer does not work as expected when editing - * the handle using the HAL functionality or other custom coding. - * @retval TIM_HandleTypeDef or hal_tim_handle_t address - */ #if defined(USE_HALV2_DRIVER) hal_tim_handle_t *HardwareTimer::getHandle() #else @@ -1445,11 +1208,6 @@ void HardwareTimer::refresh() return &_timerObj.handle; } -/** - * @brief Generic Update (rollover) callback which will call user callback - * @param htim: HAL timer handle - * @retval None - */ #if defined(USE_HALV2_DRIVER) void HardwareTimer::updateCallback(hal_tim_handle_t *htim) #else @@ -1468,11 +1226,6 @@ void HardwareTimer::refresh() } } -/** - * @brief Generic Capture and Compare callback which will call user callback - * @param htim: HAL timer handle - * @retval None - */ #if defined(USE_HALV2_DRIVER) void HardwareTimer::captureCompareCallback(hal_tim_handle_t *htim, hal_tim_channel_t hal_channel) #else @@ -1536,20 +1289,11 @@ void HardwareTimer::refresh() } } -/** - * @brief Check whether HardwareTimer is running (paused or resumed). - * @retval return true if the HardwareTimer is running - */ bool HardwareTimer::isRunning() { return LL_TIM_IsEnabledCounter(_timerObj.instance); } -/** - * @brief Check whether channel is running (paused or resumed). - * @param channel: Arduino channel [1..4] - * @retval return true if HardwareTimer is running and the channel is enabled - */ bool HardwareTimer::isRunningChannel(uint32_t channel) { uint32_t LLChannel = getLLChannel(channel); @@ -1562,12 +1306,6 @@ bool HardwareTimer::isRunningChannel(uint32_t channel) return (isRunning() && ret); } -/** - * @brief Take into account registers update immediately if timer is not running, - * (independently from Preload setting) - * @param TIMx Timer instance - * @retval None - */ void HardwareTimer::updateRegistersIfNotRunning(TIM_TypeDef *TIMx) { if (!isRunning()) { @@ -1583,10 +1321,6 @@ void HardwareTimer::updateRegistersIfNotRunning(TIM_TypeDef *TIMx) } } -/** - * @brief HardwareTimer destructor - * @retval None - */ HardwareTimer::~HardwareTimer() { uint32_t index = get_timer_index(_timerObj.instance); @@ -1595,11 +1329,6 @@ HardwareTimer::~HardwareTimer() _timerObj.__this = NULL; } -/** - * @brief return timer index from timer handle - * @param htim : one of the defined timer - * @retval timer index - */ timer_index_t get_timer_index(TIM_TypeDef *instance) { timer_index_t index = UNKNOWN_TIMER; @@ -1720,11 +1449,6 @@ timer_index_t get_timer_index(TIM_TypeDef *instance) return index; } -/** - * @brief This function return the timer clock frequency. - * @param None - * @retval frequency in Hz - */ uint32_t HardwareTimer::getTimerClkFreq() { #if defined(STM32MP1xx) @@ -1856,11 +1580,6 @@ uint32_t HardwareTimer::getTimerClkFreq() #endif /* STM32MP1xx */ } -/** - * @brief This function will reset the timer - * @param None - * @retval None - */ void HardwareTimer::timerHandleDeinit() { #if defined(USE_HALV2_DRIVER) @@ -1914,8 +1633,6 @@ extern "C" { #if defined(TIM1_BASE) /** * @brief TIM1 IRQHandler common with TIM10 and TIM16 on some STM32F1xx - * @param None - * @retval None */ void TIM1_IRQHandler(void) { @@ -1954,8 +1671,6 @@ extern "C" { #if defined(TIM2_BASE) /** * @brief TIM2 IRQHandler - * @param None - * @retval None */ void TIM2_IRQHandler(void) { @@ -1968,8 +1683,6 @@ extern "C" { #if defined(TIM3_BASE) /** * @brief TIM3 IRQHandler - * @param None - * @retval None */ void TIM3_IRQHandler(void) { @@ -1987,8 +1700,6 @@ extern "C" { #if defined(TIM4_BASE) /** * @brief TIM4 IRQHandler - * @param None - * @retval None */ void TIM4_IRQHandler(void) { @@ -2001,8 +1712,6 @@ extern "C" { #if defined(TIM5_BASE) /** * @brief TIM5 IRQHandler - * @param None - * @retval None */ void TIM5_IRQHandler(void) { @@ -2015,8 +1724,6 @@ extern "C" { #if defined(TIM6_BASE) /** * @brief TIM6 IRQHandler - * @param None - * @retval None */ void TIM6_IRQHandler(void) { @@ -2029,8 +1736,6 @@ extern "C" { #if defined(TIM7_BASE) /** * @brief TIM7 IRQHandler - * @param None - * @retval None */ void TIM7_IRQHandler(void) { @@ -2043,8 +1748,6 @@ extern "C" { #if defined(TIM8_BASE) /** * @brief TIM8 IRQHandler - * @param None - * @retval None */ void TIM8_IRQHandler(void) { @@ -2072,8 +1775,6 @@ extern "C" { #if defined(TIM9_BASE) /** * @brief TIM9 IRQHandler - * @param None - * @retval None */ void TIM9_IRQHandler(void) { @@ -2087,8 +1788,6 @@ extern "C" { #if !defined(STM32F1xx) && !defined(STM32F2xx) && !defined(STM32F4xx) && !defined(STM32F7xx) /** * @brief TIM10 IRQHandler - * @param None - * @retval None */ void TIM10_IRQHandler(void) { @@ -2102,8 +1801,6 @@ extern "C" { #if defined(TIM11_BASE) /** * @brief TIM11 IRQHandler - * @param None - * @retval None */ void TIM11_IRQHandler(void) { @@ -2116,8 +1813,6 @@ extern "C" { #if defined(TIM12_BASE) /** * @brief TIM12 IRQHandler - * @param None - * @retval None */ void TIM12_IRQHandler(void) { @@ -2131,8 +1826,6 @@ extern "C" { #if !defined(STM32F1xx) && !defined(STM32F2xx) && !defined(STM32F4xx) && !defined(STM32F7xx) && !defined(STM32H7xx) /** * @brief TIM13 IRQHandler - * @param None - * @retval None */ void TIM13_IRQHandler(void) { @@ -2146,8 +1839,6 @@ extern "C" { #if defined(TIM14_BASE) /** * @brief TIM14 IRQHandler - * @param None - * @retval None */ void TIM14_IRQHandler(void) { @@ -2160,8 +1851,6 @@ extern "C" { #if defined(TIM15_BASE) /** * @brief TIM15 IRQHandler - * @param None - * @retval None */ void TIM15_IRQHandler(void) { @@ -2175,8 +1864,6 @@ extern "C" { #if !defined(STM32F1xx) && !defined(STM32F3xx) && !defined(STM32G4xx) && !defined(STM32L4xx) /** * @brief TIM16 IRQHandler - * @param None - * @retval None */ void TIM16_IRQHandler(void) { @@ -2201,8 +1888,6 @@ extern "C" { #if defined(TIM17_BASE) /** * @brief TIM17 IRQHandler - * @param None - * @retval None */ void TIM17_IRQHandler(void) { @@ -2226,8 +1911,6 @@ extern "C" { #if defined(TIM18_BASE) /** * @brief TIM18 IRQHandler - * @param None - * @retval None */ void TIM18_IRQHandler(void) { @@ -2248,8 +1931,6 @@ extern "C" { #if defined(TIM19_BASE) /** * @brief TIM19 IRQHandler - * @param None - * @retval None */ void TIM19_IRQHandler(void) { @@ -2262,8 +1943,6 @@ extern "C" { #if defined(TIM20_BASE) /** * @brief TIM20 IRQHandler - * @param None - * @retval None */ void TIM20_IRQHandler(void) { @@ -2283,8 +1962,6 @@ extern "C" { #if defined(TIM21_BASE) /** * @brief TIM21 IRQHandler - * @param None - * @retval None */ void TIM21_IRQHandler(void) { @@ -2297,8 +1974,6 @@ extern "C" { #if defined(TIM22_BASE) /** * @brief TIM22 IRQHandler - * @param None - * @retval None */ void TIM22_IRQHandler(void) { diff --git a/libraries/SrcWrapper/src/new.cpp b/libraries/SrcWrapper/src/new.cpp index 3d12cf0aa6..7f390babd3 100644 --- a/libraries/SrcWrapper/src/new.cpp +++ b/libraries/SrcWrapper/src/new.cpp @@ -24,31 +24,59 @@ */ #include +/** + * @brief Allocate memory for a single object (C++ new). + * @param size Number of bytes to allocate. + * @return Pointer to the allocated memory, or NULL on failure. + */ void *operator new (size_t size) { return malloc(size); } +/** + * @brief Allocate memory for an array (C++ new[]). + * @param size Number of bytes to allocate. + * @return Pointer to the allocated memory, or NULL on failure. + */ void *operator new[](size_t size) { return malloc(size); } +/** + * @brief Free memory allocated by operator new. + * @param ptr Pointer to the memory to free. + */ void operator delete (void *ptr) { free(ptr); } +/** + * @brief Free memory allocated by operator new[]. + * @param ptr Pointer to the memory to free. + */ void operator delete[](void *ptr) { free(ptr); } +/** + * @brief Free memory allocated by sized operator new. + * @param ptr Pointer to the memory to free. + * @param size Size of the allocation (unused). + */ void operator delete (void *ptr, size_t /*size*/) { free(ptr); } +/** + * @brief Free memory allocated by sized operator new[]. + * @param ptr Pointer to the memory to free. + * @param size Size of the allocation (unused). + */ void operator delete[](void *ptr, size_t /*size*/) { free(ptr); diff --git a/libraries/SrcWrapper/src/stm32/PortNames.c b/libraries/SrcWrapper/src/stm32/PortNames.c index 4441e8e4c9..7bfa3d61ca 100644 --- a/libraries/SrcWrapper/src/stm32/PortNames.c +++ b/libraries/SrcWrapper/src/stm32/PortNames.c @@ -64,7 +64,6 @@ GPIO_TypeDef *GPIOPort_list[MAX_NB_PORT] = { #endif }; -/* Enable GPIO clock and return GPIO base address */ GPIO_TypeDef *set_GPIO_Port_Clock(uint32_t port_idx) { GPIO_TypeDef *gpioPort = 0; diff --git a/libraries/SrcWrapper/src/stm32/analog.cpp b/libraries/SrcWrapper/src/stm32/analog.cpp index 9ca496fe90..053fe16d32 100644 --- a/libraries/SrcWrapper/src/stm32/analog.cpp +++ b/libraries/SrcWrapper/src/stm32/analog.cpp @@ -52,13 +52,9 @@ static PinName g_current_pin = NC; #endif /** - * @brief ADC Initialization - * This function configures the hardware resources used in this example: - * - Peripheral's clock enable - * - Peripheral's GPIO Configuration - * @param instance: ADC instance - * @param pin: ADC pin - * @retval None + * @brief ADC initialization: enable the peripheral clock and configure the GPIO pin. + * @param instance ADC instance. + * @param pin ADC pin. */ void adc_init(hal_adc_t instance, PinName pin) { @@ -88,9 +84,8 @@ void adc_init(hal_adc_t instance, PinName pin) } /** - * @brief DeInitializes the ADC. - * @param instance: ADC instance - * @retval None + * @brief ADC de-initialization: disable the peripheral clock. + * @param instance ADC instance. */ void adc_deinit(hal_adc_t instance) { @@ -111,11 +106,6 @@ void adc_deinit(hal_adc_t instance) #endif } -/** - * @brief Return ADC HAL channel linked to a PinName - * @param pin: PinName - * @retval Valid HAL channel - */ hal_adc_channel_t get_adc_channel(PinName pin) { uint32_t function = pinmap_function(pin, PinMap_ADC); @@ -170,13 +160,6 @@ hal_adc_channel_t get_adc_channel(PinName pin) return channel; } -/** - * @brief Return ADC HAL internal channel linked to a PinName - * @param pin: specific PinName's for ADC internal. Value can be: - * PADC_TEMP, PADC_VREF - * Note that not all of these values ​​may be available for all series. - * @retval Valid HAL internal channel. - */ hal_adc_channel_t get_adc_internal_channel(PinName pin) { hal_adc_channel_t channel = HAL_ADC_CHANNEL_NONE; @@ -198,12 +181,6 @@ hal_adc_channel_t get_adc_internal_channel(PinName pin) return channel; } -/** - * @brief This function will set the ADC to the required value - * @param pin : the pin to use - * @param resolution : resolution for converted data: 6/8/10/12/14/16 - * @retval the value of the adc - */ uint16_t adc_read_value(PinName pin, uint32_t resolution) { hal_status_t status = HAL_OK; @@ -380,12 +357,6 @@ uint16_t adc_read_value(PinName pin, uint32_t resolution) #endif /* STM32WB0x || STM32WL3x */ /* Exported Functions */ -/** - * @brief Return ADC HAL channel linked to a PinName - * @param pin: PinName - * @param bank: pointer to get ADC channel bank if required - * @retval Valid HAL channel - */ uint32_t get_adc_channel(PinName pin, uint32_t *bank) { uint32_t function = pinmap_function(pin, PinMap_ADC); @@ -536,13 +507,6 @@ uint32_t get_adc_channel(PinName pin, uint32_t *bank) return channel; } -/** - * @brief Return ADC HAL internal channel linked to a PinName - * @param pin: specific PinName's for ADC internal. Value can be: - * PADC_TEMP, PADC_TEMP_ADC5, PADC_VREF, PADC_VBAT - * Note that not all of these values ​​may be available for all series. - * @retval Valid HAL internal channel. - */ uint32_t get_adc_internal_channel(PinName pin) { uint32_t channel = 0; @@ -580,12 +544,8 @@ uint32_t get_adc_internal_channel(PinName pin) } /** - * @brief ADC MSP Initialization - * This function configures the hardware resources used in this example: - * - Peripheral's clock enable - * - Peripheral's GPIO Configuration - * @param hadc: ADC handle pointer - * @retval None + * @brief ADC MSP initialization: enable the peripheral clock and configure the GPIO pins. + * @param hadc ADC handle pointer. */ void HAL_ADC_MspInit(ADC_HandleTypeDef *hadc) { @@ -670,9 +630,8 @@ void HAL_ADC_MspInit(ADC_HandleTypeDef *hadc) } /** - * @brief DeInitializes the ADC MSP. - * @param hadc: ADC handle - * @retval None + * @brief ADC MSP de-initialization: disable the peripheral clock. + * @param hadc ADC handle pointer. */ void HAL_ADC_MspDeInit(ADC_HandleTypeDef *hadc) { @@ -803,12 +762,6 @@ void HAL_ADC_MspDeInit(ADC_HandleTypeDef *hadc) #endif } -/** - * @brief This function will set the ADC to the required value - * @param pin : the pin to use - * @param resolution : resolution for converted data: 6/8/10/12/14/16 - * @retval the value of the adc - */ uint16_t adc_read_value(PinName pin, uint32_t resolution) { ADC_HandleTypeDef AdcHandle = {}; @@ -1178,6 +1131,11 @@ uint16_t adc_read_value(PinName pin, uint32_t resolution) #if !defined(HAL_ADC_MODULE_ONLY) /* DAC */ #if defined(USE_HAL_DAC_MODULE) && (USE_HAL_DAC_MODULE == 1) +/** + * @brief DAC initialization: enable the peripheral clock and configure the GPIO pin. + * @param instance DAC instance. + * @param pin DAC pin. + */ void dac_init(hal_dac_t instance, PinName pin) { /* DAC Periph clock enable */ @@ -1191,6 +1149,11 @@ void dac_init(hal_dac_t instance, PinName pin) pinmap_pinout(pin, PinMap_DAC); } +/** + * @brief DAC de-initialization: disable the peripheral clock and deconfigure the GPIO pin. + * @param instance DAC instance. + * @param pin DAC pin. + */ void dac_deinit(hal_dac_t instance, PinName pin) { /* DAC Periph clock disable */ @@ -1203,11 +1166,6 @@ void dac_deinit(hal_dac_t instance, PinName pin) pin_function(pin, STM_PIN_DATA(STM_MODE_ANALOG, LL_GPIO_PULL_NO, 0)); } -/** - * @brief Return DAC HAL channel linked to a PinName - * @param pin: specific PinName's for ADC internal. - * @retval Valid HAL channel - */ hal_dac_channel_t get_dac_channel(PinName pin) { uint32_t function = pinmap_function(pin, PinMap_DAC); @@ -1228,14 +1186,6 @@ hal_dac_channel_t get_dac_channel(PinName pin) return channel; } -/** - * @brief This function will set the DAC to the required value - * @param port : the gpio port to use - * @param pin : the gpio pin to use - * @param value : the value to push on the adc output - * @param do_init : if set to true the initialization of the adc is done - * @retval None - */ void dac_write_value(PinName pin, uint32_t value, bool do_init) { hal_status_t status = HAL_OK; @@ -1285,12 +1235,6 @@ void dac_write_value(PinName pin, uint32_t value, bool do_init) } } -/** - * @brief This function will stop the DAC - * @param port : the gpio port to use - * @param pin : the gpio pin to use - * @retval None - */ void dac_stop(PinName pin) { hal_dac_handle_t dac_handle; @@ -1315,11 +1259,6 @@ void dac_stop(PinName pin) #endif /* USE_HAL_DAC_MODULE && (USE_HAL_DAC_MODULE == 1) */ #if defined(HAL_DAC_MODULE_ENABLED) -/** - * @brief Return DAC HAL channel linked to a PinName - * @param pin: specific PinName's for ADC internal. - * @retval Valid HAL channel - */ uint32_t get_dac_channel(PinName pin) { uint32_t function = pinmap_function(pin, PinMap_DAC); @@ -1348,12 +1287,8 @@ uint32_t get_dac_channel(PinName pin) ////////////////////////// DAC INTERFACE FUNCTIONS ///////////////////////////// /** - * @brief DAC MSP Initialization - * This function configures the hardware resources used in this example: - * - Peripheral's clock enable - * - Peripheral's GPIO Configuration - * @param hdac: DAC handle pointer - * @retval None + * @brief DAC MSP initialization: enable the peripheral clock and configure the GPIO pins. + * @param hdac DAC handle pointer. */ void HAL_DAC_MspInit(DAC_HandleTypeDef *hdac) { @@ -1399,14 +1334,6 @@ void HAL_DAC_MspInit(DAC_HandleTypeDef *hdac) } -/** - * @brief This function will set the DAC to the required value - * @param port : the gpio port to use - * @param pin : the gpio pin to use - * @param value : the value to push on the adc output - * @param do_init : if set to true the initialization of the adc is done - * @retval None - */ void dac_write_value(PinName pin, uint32_t value, bool do_init) { DAC_HandleTypeDef DacHandle = {}; @@ -1482,10 +1409,8 @@ void dac_write_value(PinName pin, uint32_t value, bool do_init) } /** - * @brief DeInitialize the DAC MSP. - * @param hdac: pointer to a DAC_HandleTypeDef structure that contains - * the configuration information for the specified DAC. - * @retval None + * @brief DAC MSP de-initialization: disable the peripheral clock. + * @param hdac DAC handle pointer. */ void HAL_DAC_MspDeInit(DAC_HandleTypeDef *hdac) { @@ -1569,12 +1494,6 @@ void HAL_DAC_MspDeInit(DAC_HandleTypeDef *hdac) #endif } -/** - * @brief This function will stop the DAC - * @param port : the gpio port to use - * @param pin : the gpio pin to use - * @retval None - */ void dac_stop(PinName pin) { DAC_HandleTypeDef DacHandle; @@ -1606,14 +1525,6 @@ void dac_stop(PinName pin) #if !defined(HAL_TIM_MODULE_ONLY) &&\ (defined(HAL_TIM_MODULE_ENABLED) || (defined(USE_HAL_TIM_MODULE) && (USE_HAL_TIM_MODULE == 1))) /* PWM */ -/** - * @brief This function will set the PWM to the required value - * @param port : the gpio port to use - * @param pin : the gpio pin to use - * @param clock_freq : frequency of the tim clock - * @param value : the value to push on the PWM output - * @retval None - */ void pwm_start(PinName pin, uint32_t PWM_freq, uint32_t value, TimerCompareFormat_t resolution) { TIM_TypeDef *Instance = (TIM_TypeDef *)pinmap_peripheral(pin, PinMap_TIM); @@ -1638,12 +1549,6 @@ void pwm_start(PinName pin, uint32_t PWM_freq, uint32_t value, TimerCompareForma HT->resume(); } } -/** - * @brief This function will disable the PWM - * @param port : the gpio port to use - * @param pin : the gpio pin to use - * @retval None - */ void pwm_stop(PinName pin) { TIM_TypeDef *Instance = (TIM_TypeDef *)pinmap_peripheral(pin, PinMap_TIM); diff --git a/libraries/SrcWrapper/src/stm32/bootloader.c b/libraries/SrcWrapper/src/stm32/bootloader.c index d7d86e968e..793f793f5b 100644 --- a/libraries/SrcWrapper/src/stm32/bootloader.c +++ b/libraries/SrcWrapper/src/stm32/bootloader.c @@ -4,6 +4,11 @@ #include "backup.h" #ifdef BL_LEGACY_LEAF +/** + * @brief Reset into the bootloader when the "1EAF" magic packet is received on the USB CDC DTR toggle. + * @param buf Received data buffer. + * @param len Pointer to the length of the received data. + */ void dtr_togglingHook(uint8_t *buf, uint32_t *len) { /** @@ -18,6 +23,12 @@ void dtr_togglingHook(uint8_t *buf, uint32_t *len) #endif /* BL_LEGACY_LEAF */ #ifdef BL_HID +/** + * @brief Set the HID bootloader magic numbers in the backup domain and reset + * when the "1EAF" magic packet is received on the USB CDC DTR toggle. + * @param buf Received data buffer. + * @param len Pointer to the length of the received data. + */ void dtr_togglingHook(uint8_t *buf, uint32_t *len) { /** diff --git a/libraries/SrcWrapper/src/stm32/clock.c b/libraries/SrcWrapper/src/stm32/clock.c index 8043a67a72..ba76dbbc5b 100644 --- a/libraries/SrcWrapper/src/stm32/clock.c +++ b/libraries/SrcWrapper/src/stm32/clock.c @@ -21,11 +21,6 @@ extern "C" { #endif -/** - * @brief Function called to read the current micro second - * @param None - * @retval None - */ uint32_t getCurrentMicros(void) { uint32_t m0 = HAL_GetTick(); @@ -41,26 +36,27 @@ uint32_t getCurrentMicros(void) } } -/** - * @brief Function called wto read the current millisecond - * @param None - * @retval None - */ uint32_t getCurrentMillis(void) { return HAL_GetTick(); } +/** + * @brief Weak default for the OS SysTick hook, does nothing + */ void noOsSystickHandler() { } +/** + * @brief Hook called from SysTick_Handler(), aliased to noOsSystickHandler() + * unless an OS overrides it + */ void osSystickHandler() __attribute__((weak, alias("noOsSystickHandler"))); + /** - * @brief Function called when the tick interruption falls - * @param None - * @retval None + * @brief Function called when the tick interruption falls */ void SysTick_Handler(void) { @@ -73,11 +69,6 @@ void SysTick_Handler(void) osSystickHandler(); } -/** - * @brief Enable the specified clock if not already set - * @param source: clock source: LSE_CLOCK, LSI_CLOCK, HSI_CLOCK or HSE_CLOCK - * @retval None - */ void enableClock(sourceClock_t source) { #if defined(USE_HALV2_DRIVER) @@ -222,11 +213,6 @@ void configHSECapacitorTuning(void) #endif } -/** - * @brief This function enables clocks for some system IP - * @param None - * @retval None - */ void configIPClock(void) { #ifdef HSEM_BASE diff --git a/libraries/SrcWrapper/src/stm32/core_callback.c b/libraries/SrcWrapper/src/stm32/core_callback.c index 33936464c5..25972bc157 100644 --- a/libraries/SrcWrapper/src/stm32/core_callback.c +++ b/libraries/SrcWrapper/src/stm32/core_callback.c @@ -54,11 +54,6 @@ extern "C" { // List of callback to call static void (*callbackList[CALLBACK_LIST_SIZE])(void); -/** - * @brief Adds a callback pointer - * @param func: callback pointer - * @retval None - */ void registerCoreCallback(void (*func)(void)) { if (func == NULL) { @@ -73,11 +68,6 @@ void registerCoreCallback(void (*func)(void)) } } -/** - * @brief Removes a callback pointer - * @param func: callback pointer - * @retval None - */ void unregisterCoreCallback(void (*func)(void)) { if (func == NULL) { @@ -92,12 +82,6 @@ void unregisterCoreCallback(void (*func)(void)) } } -/** - * @brief Calls callback of the list. There is no priority. First added first - * called. This function must be called only in main() function loop. - * @param None - * @retval None - */ void CoreCallback(void) { for (uint8_t i = 0; i < CALLBACK_LIST_SIZE; i++) { diff --git a/libraries/SrcWrapper/src/stm32/hw_config.c b/libraries/SrcWrapper/src/stm32/hw_config.c index efeee013de..62511e671b 100644 --- a/libraries/SrcWrapper/src/stm32/hw_config.c +++ b/libraries/SrcWrapper/src/stm32/hw_config.c @@ -58,11 +58,6 @@ CRC_HandleTypeDef hcrc = {.Instance = }; #endif -/** - * @brief This function performs the global init of the system (HAL, IOs...) - * @param None - * @retval None - */ void hw_config_init(void) { configIPClock(); diff --git a/libraries/SrcWrapper/src/stm32/interrupt.cpp b/libraries/SrcWrapper/src/stm32/interrupt.cpp index a2a661ee00..ee96ba83c1 100644 --- a/libraries/SrcWrapper/src/stm32/interrupt.cpp +++ b/libraries/SrcWrapper/src/stm32/interrupt.cpp @@ -248,9 +248,9 @@ static const uint32_t ll_exti_lines[NB_EXTI] = { /* Private Functions */ /** - * @brief This function returns the pin ID function of the HAL PIN definition - * @param pin : one of the gpio pin - * @retval None + * @brief Return the ID of a GPIO pin, i.e. its bit index in the port. + * @param pin One of the GPIO pins. + * @return The bit index of the pin. */ static uint8_t get_pin_id(uint16_t pin) { @@ -314,12 +314,6 @@ void stm32_interrupt_enable(PinName pn, callback_function_t callback, uint32_t m #endif } -/** - * @brief This function disable the interruption on the selected port/pin - * @param port : one of the gpio port - * @param pin : one of the gpio pin - * @retval None - */ void stm32_interrupt_disable(GPIO_TypeDef *port, uint16_t pin) { (void)port; @@ -409,9 +403,8 @@ void HAL_EXTI_TriggerCallback(hal_exti_handle_t *hexti, hal_exti_trigger_t trigg } #else /** - * @brief This function his called by the HAL if the IRQ is valid - * @param GPIO_Pin : one of the gpio pin - * @retval None + * @brief Callback called by the HAL when a valid EXTI interrupt is detected. + * @param GPIO_Pin GPIO pin that triggered the interrupt. */ void HAL_GPIO_EXTI_Callback(uint16_t GPIO_Pin) { @@ -426,9 +419,8 @@ void HAL_GPIO_EXTI_Callback(uint16_t GPIO_Pin) defined(STM32MP1xx) || defined(STM32L5xx) || defined(STM32U0xx) || \ defined(STM32U3xx) || defined(STM32U5xx) || defined(STM32WBAxx) /** - * @brief EXTI line detection callback. - * @param GPIO_Pin Specifies the port pin connected to corresponding EXTI line. - * @retval None + * @brief EXTI line detection callback. + * @param GPIO_Pin Specifies the port pin connected to corresponding EXTI line. */ void HAL_GPIO_EXTI_Rising_Callback(uint16_t GPIO_Pin) { @@ -436,9 +428,8 @@ void HAL_GPIO_EXTI_Rising_Callback(uint16_t GPIO_Pin) } /** - * @brief EXTI line detection callback. - * @param GPIO_Pin Specifies the port pin connected to corresponding EXTI line. - * @retval None + * @brief EXTI line detection callback. + * @param GPIO_Pin Specifies the port pin connected to corresponding EXTI line. */ void HAL_GPIO_EXTI_Falling_Callback(uint16_t GPIO_Pin) { @@ -450,8 +441,6 @@ void HAL_GPIO_EXTI_Falling_Callback(uint16_t GPIO_Pin) defined(STM32L0xx) || defined(STM32U0xx) /** * @brief This function handles external line 0 to 1 interrupt request. - * @param None - * @retval None */ void EXTI0_1_IRQHandler(void) { @@ -464,8 +453,6 @@ void EXTI0_1_IRQHandler(void) /** * @brief This function handles external line 2 to 3 interrupt request. - * @param None - * @retval None */ void EXTI2_3_IRQHandler(void) { @@ -477,8 +464,6 @@ void EXTI2_3_IRQHandler(void) /** * @brief This function handles external line 4 to 15 interrupt request. - * @param None - * @retval None */ void EXTI4_15_IRQHandler(void) { @@ -555,8 +540,6 @@ void EXTI15_IRQHandler(void) #else /** * @brief This function handles external line 0 interrupt request. - * @param None - * @retval None */ void EXTI0_IRQHandler(void) { @@ -565,8 +548,6 @@ void EXTI0_IRQHandler(void) /** * @brief This function handles external line 1 interrupt request. - * @param None - * @retval None */ void EXTI1_IRQHandler(void) { @@ -575,8 +556,6 @@ void EXTI1_IRQHandler(void) /** * @brief This function handles external line 2 interrupt request. - * @param None - * @retval None */ void EXTI2_IRQHandler(void) { @@ -585,8 +564,6 @@ void EXTI2_IRQHandler(void) /** * @brief This function handles external line 3 interrupt request. - * @param None - * @retval None */ void EXTI3_IRQHandler(void) { @@ -595,8 +572,6 @@ void EXTI3_IRQHandler(void) /** * @brief This function handles external line 4 interrupt request. - * @param None - * @retval None */ void EXTI4_IRQHandler(void) { @@ -607,8 +582,6 @@ void EXTI4_IRQHandler(void) !defined(STM32U3xx) && !defined(STM32U5xx) && !defined(STM32WBAxx) /** * @brief This function handles external line 5 to 9 interrupt request. - * @param None - * @retval None */ void EXTI9_5_IRQHandler(void) { @@ -620,8 +593,6 @@ void EXTI9_5_IRQHandler(void) /** * @brief This function handles external line 10 to 15 interrupt request. - * @param None - * @retval None */ void EXTI15_10_IRQHandler(void) { @@ -634,8 +605,6 @@ void EXTI15_10_IRQHandler(void) /** * @brief This function handles external line 5 interrupt request. - * @param None - * @retval None */ void EXTI5_IRQHandler(void) { @@ -644,8 +613,6 @@ void EXTI5_IRQHandler(void) /** * @brief This function handles external line 6 interrupt request. - * @param None - * @retval None */ void EXTI6_IRQHandler(void) { @@ -654,8 +621,6 @@ void EXTI6_IRQHandler(void) /** * @brief This function handles external line 7 interrupt request. - * @param None - * @retval None */ void EXTI7_IRQHandler(void) { @@ -664,8 +629,6 @@ void EXTI7_IRQHandler(void) /** * @brief This function handles external line 8 interrupt request. - * @param None - * @retval None */ void EXTI8_IRQHandler(void) { @@ -674,8 +637,6 @@ void EXTI8_IRQHandler(void) /** * @brief This function handles external line 9 interrupt request. - * @param None - * @retval None */ void EXTI9_IRQHandler(void) { @@ -684,8 +645,6 @@ void EXTI9_IRQHandler(void) /** * @brief This function handles external line 10 interrupt request. - * @param None - * @retval None */ void EXTI10_IRQHandler(void) { @@ -694,8 +653,6 @@ void EXTI10_IRQHandler(void) /** * @brief This function handles external line 11 interrupt request. - * @param None - * @retval None */ void EXTI11_IRQHandler(void) { @@ -704,8 +661,6 @@ void EXTI11_IRQHandler(void) /** * @brief This function handles external line 12 interrupt request. - * @param None - * @retval None */ void EXTI12_IRQHandler(void) { @@ -714,8 +669,6 @@ void EXTI12_IRQHandler(void) /** * @brief This function handles external line 13 interrupt request. - * @param None - * @retval None */ void EXTI13_IRQHandler(void) { @@ -724,8 +677,6 @@ void EXTI13_IRQHandler(void) /** * @brief This function handles external line 14 interrupt request. - * @param None - * @retval None */ void EXTI14_IRQHandler(void) { @@ -734,8 +685,6 @@ void EXTI14_IRQHandler(void) /** * @brief This function handles external line 15 interrupt request. - * @param None - * @retval None */ void EXTI15_IRQHandler(void) { diff --git a/libraries/SrcWrapper/src/stm32/pinmap.c b/libraries/SrcWrapper/src/stm32/pinmap.c index faa04a8da8..873fcae857 100644 --- a/libraries/SrcWrapper/src/stm32/pinmap.c +++ b/libraries/SrcWrapper/src/stm32/pinmap.c @@ -67,8 +67,10 @@ const uint32_t pin_map_ll[16] = { #if defined(DUALPAD_ANALOG_SWITCH) /** - * Configure Analog dualpad switch if necessary - * LL_AnalogSwitch: LL define to be used to configure Analog switch + * @brief Configure the analog dualpad switch if necessary. + * @param pin Pin name. + * @param function Pin function, encoded with the STM_PIN_* macros. + * @param LL_AnalogSwitch LL define used to configure the analog switch (0 = none). */ static void configure_dualpad_switch(PinName pin, int function, uint32_t LL_AnalogSwitch) { @@ -97,10 +99,11 @@ static void configure_dualpad_switch(PinName pin, int function, uint32_t LL_Anal } /** - * In case of dual pad, determine whether gpio needs to be configured - * pLL_AnalogSwitch: pointer used to return LL define to be used to configure - * Analog switch - * return: true when gpio must be configured + * @brief Determine whether the GPIO of a dualpad pin must be configured. + * @param pin Pin name. + * @param function Pin function, encoded with the STM_PIN_* macros. + * @param pLL_AnalogSwitch Output: LL define to use to configure the analog switch. + * @return true when the GPIO must be configured, false otherwise. */ static bool is_dualpad_switch_gpio_configurable(PinName pin, int function, uint32_t *pLL_AnalogSwitch) { @@ -142,9 +145,6 @@ bool pin_in_pinmap(PinName pin, const PinMap *map) return false; } -/** - * Configure pin (mode, speed, output type and pull-up/pull-down) - */ void pin_function(PinName pin, int function) { /* Get the pin information */ diff --git a/libraries/SrcWrapper/src/stm32/stm32_def.c b/libraries/SrcWrapper/src/stm32/stm32_def.c index c53b5096dd..3dbc84eb80 100644 --- a/libraries/SrcWrapper/src/stm32/stm32_def.c +++ b/libraries/SrcWrapper/src/stm32/stm32_def.c @@ -5,11 +5,6 @@ extern "C" { #endif -/** - * @brief This function is executed in case of error occurrence. - * @param None - * @retval None - */ #if !defined(NDEBUG) __attribute__((noreturn)) WEAK void _Error_Handler(const char *msg, int val) { @@ -21,13 +16,6 @@ __attribute__((noreturn)) WEAK void _Error_Handler(const char *msg, int val) #endif #ifdef USE_FULL_ASSERT -/** - * @brief Reports the name of the source file and the source line number - * where the assert_param error has occurred. - * @param file: pointer to the source file name - * @param line: assert_param error line source number - * @retval None - */ WEAK void assert_failed(uint8_t *file, uint32_t line) { _Error_Handler((const char *)file, line); diff --git a/libraries/SrcWrapper/src/stm32/timer.c b/libraries/SrcWrapper/src/stm32/timer.c index 402aefe0dd..cc3addd0de 100644 --- a/libraries/SrcWrapper/src/stm32/timer.c +++ b/libraries/SrcWrapper/src/stm32/timer.c @@ -36,9 +36,8 @@ timerObj_t *get_timer_obj(TIM_HandleTypeDef *htim) #if !defined(USE_HALV2_DRIVER) /** - * @brief TIMER Initialization - clock init and nvic init - * @param htim_base: TIM handle - * @retval None + * @brief TIMER Initialization - clock init and nvic init + * @param htim_base TIM handle */ void HAL_TIM_Base_MspInit(TIM_HandleTypeDef *htim_base) { @@ -57,9 +56,8 @@ void HAL_TIM_Base_MspInit(TIM_HandleTypeDef *htim_base) } /** - * @brief TIMER Deinitialization - clock and nvic - * @param htim_base: TIM handle - * @retval None + * @brief TIMER Deinitialization - clock and nvic + * @param htim_base TIM handle */ void HAL_TIM_Base_MspDeInit(TIM_HandleTypeDef *htim_base) { @@ -69,9 +67,8 @@ void HAL_TIM_Base_MspDeInit(TIM_HandleTypeDef *htim_base) } /** - * @brief Initializes the TIM Output Compare MSP. - * @param htim: TIM handle - * @retval None + * @brief Initializes the TIM Output Compare MSP. + * @param htim TIM handle */ void HAL_TIM_OC_MspInit(TIM_HandleTypeDef *htim) { @@ -90,9 +87,8 @@ void HAL_TIM_OC_MspInit(TIM_HandleTypeDef *htim) } /** - * @brief DeInitialize TIM Output Compare MSP. - * @param htim: TIM handle - * @retval None + * @brief DeInitialize TIM Output Compare MSP. + * @param htim TIM handle */ void HAL_TIM_OC_MspDeInit(TIM_HandleTypeDef *htim) { @@ -102,9 +98,8 @@ void HAL_TIM_OC_MspDeInit(TIM_HandleTypeDef *htim) } /** - * @brief Initializes the TIM Input Capture MSP. - * @param htim: TIM handle - * @retval None + * @brief Initializes the TIM Input Capture MSP. + * @param htim TIM handle */ void HAL_TIM_IC_MspInit(TIM_HandleTypeDef *htim) { @@ -112,9 +107,8 @@ void HAL_TIM_IC_MspInit(TIM_HandleTypeDef *htim) } /** - * @brief DeInitialize TIM Input Capture MSP. - * @param htim: TIM handle - * @retval None + * @brief DeInitialize TIM Input Capture MSP. + * @param htim TIM handle */ void HAL_TIM_IC_MspDeInit(TIM_HandleTypeDef *htim) { @@ -122,12 +116,6 @@ void HAL_TIM_IC_MspDeInit(TIM_HandleTypeDef *htim) } #endif /* !defined(USE_HALV2_DRIVER) */ /* Exported functions */ -/** - * @brief Enable the timer clock - * @param instance: TIM instance - * @retval None - */ - void enableTimerClock(TIM_TypeDef *instance) { // Enable TIM clock @@ -291,11 +279,6 @@ void enableTimerClock(TIM_TypeDef *instance) #endif } -/** - * @brief Disable the timer clock - * @param htim: TIM handle - * @retval None - */ void disableTimerClock(TIM_TypeDef *instance) { // Disable TIM clock @@ -459,11 +442,6 @@ void disableTimerClock(TIM_TypeDef *instance) #endif } -/** - * @brief This function return IRQ number corresponding to update interrupt event of timer instance. - * @param tim: timer instance - * @retval IRQ number - */ IRQn_Type getTimerUpIrq(TIM_TypeDef *tim) { IRQn_Type IRQn = NonMaskableInt_IRQn; @@ -590,11 +568,6 @@ IRQn_Type getTimerUpIrq(TIM_TypeDef *tim) return IRQn; } -/** - * @brief This function return IRQ number corresponding to Capture or Compare interrupt event of timer instance. - * @param tim: timer instance - * @retval IRQ number - */ IRQn_Type getTimerCCIrq(TIM_TypeDef *tim) { IRQn_Type IRQn = NonMaskableInt_IRQn; @@ -721,11 +694,6 @@ IRQn_Type getTimerCCIrq(TIM_TypeDef *tim) return IRQn; } -/** - * @brief This function return the timer clock source. - * @param tim: timer instance - * @retval 1 = PCLK1 or 2 = PCLK2 - */ uint8_t getTimerClkSrc(TIM_TypeDef *tim) { uint8_t clkSrc = 0; @@ -819,11 +787,6 @@ uint8_t getTimerClkSrc(TIM_TypeDef *tim) return clkSrc; } -/** - * @brief Return HAL timer channel linked to a PinName - * @param pin: PinName - * @retval Valid HAL channel - */ #if defined(USE_HALV2_DRIVER) hal_tim_channel_t getTimerChannel(PinName pin) { diff --git a/libraries/SrcWrapper/src/stm32/uart.c b/libraries/SrcWrapper/src/stm32/uart.c index d5558f12b9..1b94211dc7 100644 --- a/libraries/SrcWrapper/src/stm32/uart.c +++ b/libraries/SrcWrapper/src/stm32/uart.c @@ -351,11 +351,6 @@ bool uart_enable_clock(serial_t *obj) return status; } -/** - * @brief Function called to initialize the uart interface - * @param obj : pointer to serial_t structure - * @retval boolean status - */ #if defined(USE_HALV2_DRIVER) bool uart_init(serial_t *obj, uint32_t baudrate, hal_uart_word_length_t databits, hal_uart_parity_t parity, hal_uart_stop_bits_t stopbits, bool rx_invert, bool tx_invert, bool data_invert) #else @@ -607,11 +602,6 @@ bool uart_init(serial_t *obj, uint32_t baudrate, uint32_t databits, uint32_t par return status; } -/** - * @brief Function called to deinitialize the uart interface - * @param obj : pointer to serial_t structure - * @retval None - */ void uart_deinit(serial_t *obj) { /* Ensure uart is set to prevent deinitializing uart at index 0 */ @@ -840,11 +830,6 @@ void uart_init_lpuart(UART_HandleTypeDef *huart) #if defined(HAL_PWR_MODULE_ENABLED) && (defined(UART_IT_WUF) || defined(LPUART1_BASE)) -/** - * @brief Function called to configure the uart interface for low power - * @param obj : pointer to serial_t structure - * @retval None - */ void uart_config_lowpower(serial_t *obj) { if (obj == NULL) { @@ -939,11 +924,11 @@ void uart_config_lowpower(serial_t *obj) #endif /** - * @brief Function called to initialize the debug uart interface + * @brief Function called to initialize the debug uart interface * @note Call only if debug U(S)ART peripheral is not already initialized * by a Serial instance * Default config: 8N1 - * @retval boolean status + * @return true on success, false otherwise */ bool uart_debug_init(void) { @@ -964,12 +949,6 @@ bool uart_debug_init(void) return status; } -/** - * @brief write the data on the uart: used by printf for debug only (syscalls) - * @param data : bytes to write - * @param size : number of data to write - * @retval The number of bytes written - */ size_t uart_debug_write(uint8_t *data, uint32_t size) { uint32_t tickstart = HAL_GetTick(); @@ -1019,12 +998,6 @@ size_t uart_debug_write(uint8_t *data, uint32_t size) return size; } -/** - * Attempts to determine if the serial peripheral is already in use for RX - * - * @param obj The serial object - * @return Non-zero if the RX transaction is ongoing, 0 otherwise - */ uint8_t serial_rx_active(serial_t *obj) { #if defined(USE_HALV2_DRIVER) @@ -1034,12 +1007,6 @@ uint8_t serial_rx_active(serial_t *obj) #endif } -/** - * Attempts to determine if the serial peripheral is already in use for TX - * - * @param obj The serial object - * @return Non-zero if the TX transaction is ongoing, 0 otherwise - */ uint8_t serial_tx_active(serial_t *obj) { #if defined(USE_HALV2_DRIVER) @@ -1049,11 +1016,6 @@ uint8_t serial_tx_active(serial_t *obj) #endif } -/** - * @brief Read receive byte from uart - * @param obj : pointer to serial_t structure - * @retval last character received - */ int uart_getc(serial_t *obj, unsigned char *c) { if (obj == NULL) { @@ -1071,13 +1033,6 @@ int uart_getc(serial_t *obj, unsigned char *c) return 0; } -/** - * Begin asynchronous RX transfer (enable interrupt for data collecting) - * - * @param obj : pointer to serial_t structure - * @param callback : function call at the end of reception - * @retval none - */ void uart_attach_rx_callback(serial_t *obj, void (*callback)(serial_t *)) { if (obj == NULL) { @@ -1107,13 +1062,6 @@ void uart_attach_rx_callback(serial_t *obj, void (*callback)(serial_t *)) #endif } -/** - * Begin asynchronous TX transfer. - * - * @param obj : pointer to serial_t structure - * @param callback : function call at the end of transmission - * @retval none - */ void uart_attach_tx_callback(serial_t *obj, int (*callback)(serial_t *), size_t size) { if (obj == NULL) { @@ -1139,12 +1087,6 @@ void uart_attach_tx_callback(serial_t *obj, int (*callback)(serial_t *), size_t #endif } -/** - * Enable transmitter for half-duplex mode. NOOP in full-fuplex mode - * - * @param obj : pointer to serial_t structure - * @retval none - */ void uart_enable_tx(serial_t *obj) { if (obj != NULL && obj->pin_rx == NC) { @@ -1156,12 +1098,6 @@ void uart_enable_tx(serial_t *obj) } } -/** - * Enable receiver for half-duplex mode. NOOP in full-fuplex mode - * - * @param obj : pointer to serial_t structure - * @retval none - */ void uart_enable_rx(serial_t *obj) { if (obj != NULL && obj->pin_rx == NC) { @@ -1174,9 +1110,9 @@ void uart_enable_rx(serial_t *obj) } /** - * @brief Return index of the serial handler - * @param UartHandle pointer on the uart reference - * @retval index + * @brief Return index of the serial handler + * @param huart Pointer on the uart reference + * @return Index of the serial handler */ /* uint8_t uart_index(UART_HandleTypeDef *huart) @@ -1197,9 +1133,8 @@ uint8_t uart_index(UART_HandleTypeDef *huart) */ /** - * @brief Rx Transfer completed callback - * @param UartHandle pointer on the uart reference - * @retval None + * @brief Rx Transfer completed callback + * @param huart Pointer on the uart reference */ #if defined(USE_HALV2_DRIVER) void HAL_UART_RxCpltCallback(hal_uart_handle_t *huart, uint32_t size_byte, hal_uart_rx_event_types_t rx_event) @@ -1218,9 +1153,8 @@ void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) } /** - * @brief Tx Transfer completed callback - * @param UartHandle pointer on the uart reference - * @retval None + * @brief Tx Transfer completed callback + * @param huart Pointer on the uart reference */ #if defined(USE_HALV2_DRIVER) void HAL_UART_TxCpltCallback(hal_uart_handle_t *huart) @@ -1235,9 +1169,8 @@ void HAL_UART_TxCpltCallback(UART_HandleTypeDef *huart) } /** - * @brief error callback from UART - * @param UartHandle pointer on the uart reference - * @retval None + * @brief Error callback from UART + * @param huart Pointer on the uart reference */ #if defined(USE_HALV2_DRIVER) void HAL_UART_ErrorCallback(hal_uart_handle_t *huart) @@ -1287,9 +1220,7 @@ void HAL_UART_ErrorCallback(UART_HandleTypeDef *huart) } /** - * @brief USART 1 IRQ handler - * @param None - * @retval None + * @brief USART 1 IRQ handler */ #if defined(USART1_BASE) void USART1_IRQHandler(void) @@ -1304,9 +1235,7 @@ void USART1_IRQHandler(void) #endif /** - * @brief USART 2 IRQ handler - * @param None - * @retval None + * @brief USART 2 IRQ handler */ #if defined(USART2_BASE) void USART2_IRQHandler(void) @@ -1328,9 +1257,7 @@ void USART2_IRQHandler(void) #endif /** - * @brief USART 3 IRQ handler - * @param None - * @retval None + * @brief USART 3 IRQ handler */ #if defined(USART3_BASE) void USART3_IRQHandler(void) @@ -1387,9 +1314,7 @@ void USART3_IRQHandler(void) #endif /** - * @brief UART 4 IRQ handler - * @param None - * @retval None + * @brief UART 4 IRQ handler */ #if defined(UART4_BASE) void UART4_IRQHandler(void) @@ -1404,9 +1329,7 @@ void UART4_IRQHandler(void) #endif /** - * @brief USART 4/5 IRQ handler - * @param None - * @retval None + * @brief USART 4/5 IRQ handler */ #if defined(STM32L0xx) #if defined(USART4_BASE) || defined(USART5_BASE) @@ -1424,9 +1347,7 @@ void USART4_5_IRQHandler(void) #endif /** - * @brief USART 4 IRQ handler - * @param None - * @retval None + * @brief USART 4 IRQ handler */ #if defined(STM32U0xx) #if defined(USART4_BASE) @@ -1446,9 +1367,7 @@ void USART4_IRQHandler(void) #endif /** - * @brief USART 5 IRQ handler - * @param None - * @retval None + * @brief USART 5 IRQ handler */ #if defined(UART5_BASE) void UART5_IRQHandler(void) @@ -1463,9 +1382,7 @@ void UART5_IRQHandler(void) #endif /** - * @brief USART 6 IRQ handler - * @param None - * @retval None + * @brief USART 6 IRQ handler */ #if defined(USART6_BASE) && !defined(STM32F0xx) && !defined(STM32G0xx) void USART6_IRQHandler(void) @@ -1480,9 +1397,7 @@ void USART6_IRQHandler(void) #endif /** - * @brief LPUART 1 IRQ handler - * @param None - * @retval None + * @brief LPUART 1 IRQ handler */ #if defined(LPUART1_BASE) void LPUART1_IRQHandler(void) @@ -1497,9 +1412,7 @@ void LPUART1_IRQHandler(void) #endif /** - * @brief UART 7 IRQ handler - * @param None - * @retval None + * @brief UART 7 IRQ handler */ #if defined(UART7_BASE) void UART7_IRQHandler(void) @@ -1514,9 +1427,7 @@ void UART7_IRQHandler(void) #endif /** - * @brief UART 8 IRQ handler - * @param None - * @retval None + * @brief UART 8 IRQ handler */ #if defined(UART8_BASE) void UART8_IRQHandler(void) @@ -1527,9 +1438,7 @@ void UART8_IRQHandler(void) #endif /** - * @brief UART 9 IRQ handler - * @param None - * @retval None + * @brief UART 9 IRQ handler */ #if defined(UART9_BASE) void UART9_IRQHandler(void) @@ -1540,9 +1449,7 @@ void UART9_IRQHandler(void) #endif /** - * @brief UART 10 IRQ handler - * @param None - * @retval None + * @brief UART 10 IRQ handler */ #if defined(UART10_BASE) void UART10_IRQHandler(void) @@ -1553,9 +1460,7 @@ void UART10_IRQHandler(void) #endif /** - * @brief USART 10 IRQ handler - * @param None - * @retval None + * @brief USART 10 IRQ handler */ #if defined(USART10_BASE) void USART10_IRQHandler(void) @@ -1566,9 +1471,7 @@ void USART10_IRQHandler(void) #endif /** - * @brief USART 11 IRQ handler - * @param None - * @retval None + * @brief USART 11 IRQ handler */ #if defined(USART11_BASE) void USART11_IRQHandler(void) @@ -1579,9 +1482,7 @@ void USART11_IRQHandler(void) #endif /** - * @brief UART 12 IRQ handler - * @param None - * @retval None + * @brief UART 12 IRQ handler */ #if defined(UART12_BASE) void UART12_IRQHandler(void) @@ -1592,9 +1493,8 @@ void UART12_IRQHandler(void) #endif /** - * @brief HAL UART Call Back - * @param UART handler - * @retval None + * @brief HAL UART wakeup callback + * @param huart UART handle */ #if defined(USE_HALV2_DRIVER) void HAL_UARTEx_WakeupCallback(hal_uart_handle_t *huart) @@ -1607,11 +1507,6 @@ void HAL_UARTEx_WakeupCallback(UART_HandleTypeDef *huart) } #if defined(USE_HALV2_DRIVER) -/** - * @brief Function called to set the uart clock prescaler - * @param huart : uart handle structure - * @retval hal_uart_prescaler_t clock prescaler - */ hal_uart_prescaler_t uart_compute_prescaler(hal_uart_handle_t *huart, hal_uart_config_t *config) { hal_uart_prescaler_t prescaler = HAL_UART_PRESCALER_DIV1; @@ -1644,11 +1539,6 @@ hal_uart_prescaler_t uart_compute_prescaler(hal_uart_handle_t *huart, hal_uart_c #endif #if defined(UART_PRESCALER_DIV1) -/** - * @brief Function called to set the uart clock prescaler - * @param huart : uart handle structure - * @retval uint32_t clock prescaler - */ uint32_t uart_compute_prescaler(UART_HandleTypeDef *huart) { uint32_t prescaler = UART_PRESCALER_DIV1; @@ -1685,11 +1575,6 @@ uint32_t uart_compute_prescaler(UART_HandleTypeDef *huart) return prescaler; } -/** - * @brief Function called to get the clock source frequency of the uart - * @param huart : uart handle structure - * @retval uint32_t clock source frequency - */ uint32_t uart_get_clock_source_freq(UART_HandleTypeDef *huart) { uint32_t freq = 0; diff --git a/libraries/SrcWrapper/src/syscalls.c b/libraries/SrcWrapper/src/syscalls.c index 15dcbdd265..2338a2f826 100644 --- a/libraries/SrcWrapper/src/syscalls.c +++ b/libraries/SrcWrapper/src/syscalls.c @@ -13,6 +13,11 @@ #undef errno extern int errno; +/** + * @brief Increase the program data space (heap) used by malloc. + * @param incr Number of bytes to add to the heap. + * @return Previous heap end on success, or (caddr_t)-1 with errno set to ENOMEM. + */ __attribute__((weak)) caddr_t _sbrk(int incr) { @@ -37,6 +42,11 @@ caddr_t _sbrk(int incr) return (caddr_t) prev_heap_end ; } +/** + * @brief Close a file. Not supported, always fails. + * @param file File descriptor to close. + * @return -1. + */ __attribute__((weak)) int _close(int file) { @@ -44,6 +54,12 @@ int _close(int file) return -1; } +/** + * @brief Get file status. Reports every file as a character device. + * @param file File descriptor. + * @param st Buffer that receives the file status. + * @return 0. + */ __attribute__((weak)) int _fstat(int file, struct stat *st) { @@ -52,6 +68,11 @@ int _fstat(int file, struct stat *st) return 0; } +/** + * @brief Check whether a file descriptor refers to a terminal. Always reports a terminal. + * @param file File descriptor. + * @return 1. + */ __attribute__((weak)) int _isatty(int file) { @@ -59,6 +80,13 @@ int _isatty(int file) return 1; } +/** + * @brief Set the file position. Not supported, always returns 0. + * @param file File descriptor. + * @param ptr Offset. + * @param dir Seek direction. + * @return 0. + */ __attribute__((weak)) int _lseek(int file, int ptr, int dir) { @@ -68,6 +96,13 @@ int _lseek(int file, int ptr, int dir) return 0; } +/** + * @brief Read from a file. Not supported, always returns 0 bytes read. + * @param file File descriptor. + * @param ptr Buffer to fill. + * @param len Maximum number of bytes to read. + * @return 0. + */ __attribute__((weak)) int _read(int file, char *ptr, int len) { @@ -88,6 +123,10 @@ int _write(int file, char *ptr, int len) } */ +/** + * @brief Terminate the program. Loops forever. + * @param status Exit status (ignored). + */ __attribute__((weak)) void _exit(int status) { @@ -95,6 +134,12 @@ void _exit(int status) for (; ;) ; } +/** + * @brief Send a signal to a process. Not supported, always fails. + * @param pid Process ID. + * @param sig Signal number. + * @return -1 with errno set to EINVAL. + */ __attribute__((weak)) int _kill(int pid, int sig) { @@ -104,6 +149,10 @@ int _kill(int pid, int sig) return -1; } +/** + * @brief Get the process ID. Always returns 1. + * @return 1. + */ __attribute__((weak)) int _getpid(void) { diff --git a/libraries/SubGhz/src/SubGhz.h b/libraries/SubGhz/src/SubGhz.h index 60bb621fad..e0465a5176 100644 --- a/libraries/SubGhz/src/SubGhz.h +++ b/libraries/SubGhz/src/SubGhz.h @@ -22,90 +22,123 @@ #error "This board does not seem to have a SubGhz radio module, cannot use this library." #endif +/** + * @brief ISR entry point for the SubGHz radio IRQ. Forwards the event to the attached callback. + */ extern "C" void SUBGHZ_Radio_IRQHandler(); /** - * Singleton class to manage the SubGHZ ISR and internal signals + * @brief Singleton class to manage the SubGHZ ISR and internal signals. */ class SubGhzClass { public: using callback_function_t = std::function; - // Attach the passed handler to be called (from ISR context) when - // the radio IRQ triggers, then clear any pending IRQs and enable - // it. - // - // Note that the radio IRQ is *level* triggered, so the callback - // should either disable directly process the IRQ and clear the IRQ - // flags in the radio (so the radio module clears its DIO lines - // before the ISR returns), or the callback should disable the IRQ - // to prevent it from being triggered over and over again. + /** + * @brief Attach the handler called from ISR context when the radio IRQ triggers, + * then clear any pending IRQs and enable the IRQ. + * + * The radio IRQ is *level* triggered, so the callback must either process the IRQ + * and clear the IRQ flags in the radio (so the radio clears its DIO lines before the + * ISR returns), or disable the IRQ to prevent it from being triggered over and over again. + * @param callback Function called from ISR context when the radio IRQ triggers. + */ void attachInterrupt(callback_function_t callback); - // Detach the interrupt handler, disabling the IRQ too. + /** + * @brief Detach the interrupt handler, disabling the IRQ too. + */ void detachInterrupt(); - // Return whether an interrupt callback is currently attached - // (regardless of whether it is enabled or not). + /** + * @brief Check whether an interrupt callback is attached, regardless of whether it is enabled. + * @return true if a callback is attached, false otherwise. + */ bool hasInterrupt(); - // Enable the interrupt again if it was previously disabled using - // disableInterrupt(). This does *not* clear any pending interrupts, - // so if the IRQ was triggered while it was disabled, this will - // cause the callback (previously registered with attachInterrupt) - // to fire directly. + /** + * @brief Enable the interrupt again if it was previously disabled using disableInterrupt(). + * + * This does *not* clear pending interrupts: if the IRQ triggered while it was disabled, + * the callback registered with attachInterrupt() fires directly. + */ void enableInterrupt(); - // Temporarily disable interrupt processing by disabling the IRQ in - // the NVIC. + /** + * @brief Temporarily disable interrupt processing by disabling the IRQ in the NVIC. + */ void disableInterrupt(); - // Clear the interrupt pending flag (to suppress an IRQs that - // happened while the interrupt was disabled). + /** + * @brief Clear the interrupt pending flag, suppressing IRQs that happened while the interrupt was disabled. + */ void clearPendingInterrupt(); - // Returns whether the interrupt is currently pending (only really - // useful when the interrupt is disabled, or while some higher - // priority interrupt is currently running). + /** + * @brief Check whether the interrupt is pending. + * + * Only really useful when the interrupt is disabled, or while a higher priority interrupt is running. + * @return true if the interrupt is pending, false otherwise. + */ bool isInterruptPending(); - // Update the NSS signal that is internally connected to the radio - // SPI block. - // This signal is active-low, so passing LOW activates the block, - // HIGH deactivates it. + /** + * @brief Update the NSS signal internally connected to the radio SPI block. + * + * The NSS signal is active-low: passing true asserts it (activates the block), + * passing false deasserts it (deactivates the block). + * @param value true to activate the NSS signal, false to deactivate it. + */ void setNssActive(bool value); - // Read back the value written to NSS + /** + * @brief Read back the value written to NSS with setNssActive(). + * @return true if the NSS signal is active, false otherwise. + */ bool isNssActive(); - // Update the RESET signal that is internally connected to the - // radio. Pass true to put the module in reset, or false to enable - // the module. + /** + * @brief Update the RESET signal internally connected to the radio. + * @param value true to put the module in reset, false to enable the module. + */ void setResetActive(bool value); - // Read back the value written to RESET + /** + * @brief Read back the value written to RESET with setResetActive(). + * @return true if the module is in reset, false otherwise. + */ bool isResetActive(); - // Return the state of busy signal exported by the radio module. - // Note that this uses the RFBUSYS flag that returns the radio busy - // signal directly, not the RFBUSYMS flag that also returns an extra - // busy period after every SPI transaction. + /** + * @brief Get the busy signal exported by the radio module. + * + * Uses the RFBUSYS flag, which returns the radio busy signal directly, + * not the RFBUSYMS flag that also returns an extra busy period after every SPI transaction. + * @return true if the radio is busy, false otherwise. + */ bool isBusy(); - // The SPI object that can be used to talk to the radio. Works - // like regular SPI objects, except that writeNSS() above must be - // used to control the (internal) NSS "pin". + /** + * @brief SPI object used to talk to the radio. + * + * Works like a regular SPI object, except that setNssActive() must be used + * to control the (internal) NSS signal. + */ SUBGHZSPIClass SPI; - // SPI settings to use for the radio. This uses the maximum speed - // supported by the radio, which should always work (no chance of - // bad wiring that requires reducing the speed). - // This value should be passed to `SubGhz.SPI.beginTransaction()`. + /** + * @brief SPI settings to use for the radio, at the maximum speed supported by the radio. + * + * Pass this value to SubGhz.SPI.beginTransaction(). + */ static constexpr SPISettings spi_settings = {16000000, MSBFIRST, SPI_MODE0}; protected: // To access handleIrq() friend void SUBGHZ_Radio_IRQHandler(); + /** + * @brief Call the attached callback. Invoked from the ISR, not meant to be called directly. + */ void handleIrq(); private: diff --git a/libraries/USBDevice/inc/USBSerial.h b/libraries/USBDevice/inc/USBSerial.h index 89b50cebcc..8dba7a9d80 100644 --- a/libraries/USBDevice/inc/USBSerial.h +++ b/libraries/USBDevice/inc/USBSerial.h @@ -27,41 +27,175 @@ // Serial over CDC class USBSerial : public Stream { public: + /** + * @brief Initialize the USB CDC serial port. + */ void begin(void); + + /** + * @brief Initialize the USB CDC serial port. The baud rate is ignored. + * @param baud_count Baud rate. Ignored by USB CDC. + */ void begin(uint32_t); + + /** + * @brief Initialize the USB CDC serial port. The baud rate and + * configuration are ignored. + * @param baud_count Baud rate. Ignored by USB CDC. + * @param config Serial configuration. Ignored by USB CDC. + */ void begin(uint32_t, uint8_t); + + /** + * @brief Stop the USB CDC serial port. + */ void end(void); + /** + * @brief Get the number of bytes available to read. + * @return Number of bytes in the receive queue. + */ virtual int available(void); + + /** + * @brief Get the number of bytes that can be written without blocking. + * @return Free space in the transmit queue, in bytes. + */ virtual int availableForWrite(void); + + /** + * @brief Get the next byte without removing it from the receive queue. + * @return The next byte, or -1 if the receive queue is empty. + */ virtual int peek(void); + + /** + * @brief Read one byte from the receive queue. + * @return The byte read, or -1 if the receive queue is empty. + */ virtual int read(void); - virtual size_t readBytes(char *buffer, size_t length); // read chars from stream into buffer + + /** + * @brief Read bytes from the stream into a buffer. Stops at the timeout + * set by setTimeout(). + * @param buffer Destination buffer. + * @param length Maximum number of bytes to read. + * @return Number of bytes read. + */ + virtual size_t readBytes(char *buffer, size_t length); + + /** + * @brief Read bytes from the stream into a buffer. Same as the char + * overload. + * @param buffer Destination buffer. + * @param length Maximum number of bytes to read. + * @return Number of bytes read. + */ size_t readBytes(uint8_t *buffer, size_t length) { return readBytes((char *)buffer, length); } - virtual size_t readBytesUntil(char terminator, char *buffer, size_t length); // as readBytes with terminator character + + /** + * @brief Read bytes from the stream into a buffer, stopping after the + * terminator character. Stops at the timeout set by setTimeout(). + * @param terminator Character that ends the read. It is included in the + * buffer. + * @param buffer Destination buffer. + * @param length Maximum number of bytes to read. + * @return Number of bytes read. + */ + virtual size_t readBytesUntil(char terminator, char *buffer, size_t length); + + /** + * @brief Read bytes until the terminator character. Same as the char + * overload. + * @param terminator Character that ends the read. It is included in the + * buffer. + * @param buffer Destination buffer. + * @param length Maximum number of bytes to read. + * @return Number of bytes read. + */ size_t readBytesUntil(char terminator, uint8_t *buffer, size_t length) { return readBytesUntil(terminator, (char *)buffer, length); } + + /** + * @brief Wait until all written bytes are sent over USB. + */ virtual void flush(void); + + /** + * @brief Write one byte. + * @param ch Byte to write. + * @return Number of bytes written: 1 on success, 0 on failure. + */ virtual size_t write(uint8_t); + + /** + * @brief Write a buffer of bytes. Blocks until all bytes are queued, or + * until the host disconnects. + * @param buffer Data to send. + * @param size Number of bytes to send. + * @return Number of bytes written. + */ virtual size_t write(const uint8_t *buffer, size_t size); using Print::write; // pull in write(str) from Print + + /** + * @brief Check whether the USB host has opened the port. + * @note Waits 10 ms before reading the DTR state. + * @return The DTR state set by the host. + */ operator bool(void); - // These return the settings specified by the USB host for the - // serial port. These aren't really used, but are offered here - // in case a sketch wants to act on these settings. + /** + * @brief Get the baud rate set by the USB host. + * @note The value is informational. It is not used by USB CDC. + * @return Baud rate. + */ uint32_t baud(); + + /** + * @brief Get the stop bits set by the USB host. + * @note The value is informational. It is not used by USB CDC. + * @return Stop bits setting, one of ONE_STOP_BIT, ONE_AND_HALF_STOP_BIT, + * or TWO_STOP_BITS. + */ uint8_t stopbits(); + + /** + * @brief Get the parity type set by the USB host. + * @note The value is informational. It is not used by USB CDC. + * @return Parity setting, one of NO_PARITY, ODD_PARITY, EVEN_PARITY, + * MARK_PARITY, or SPACE_PARITY. + */ uint8_t paritytype(); + + /** + * @brief Get the number of data bits set by the USB host. + * @note The value is informational. It is not used by USB CDC. + * @return Number of data bits. + */ uint8_t numbits(); + /** + * @brief Set the DTR line state. + * @param enable true to set DTR, false to clear it. + */ void dtr(bool enable); + + /** + * @brief Get the DTR line state. + * @return The DTR state. + */ bool dtr(); + + /** + * @brief Get the RTS line state. + * @return The RTS state set by the host. + */ bool rts(); enum { ONE_STOP_BIT = 0, diff --git a/libraries/USBDevice/inc/cdc_queue.h b/libraries/USBDevice/inc/cdc_queue.h index 1ec58d02f0..0809ff449f 100644 --- a/libraries/USBDevice/inc/cdc_queue.h +++ b/libraries/USBDevice/inc/cdc_queue.h @@ -76,21 +76,119 @@ typedef struct { volatile uint16_t length; } CDC_ReceiveQueue_TypeDef; +/** + * @brief Initialize read and write position of the transmit queue. + * @param queue transmit queue to initialize. + */ void CDC_TransmitQueue_Init(CDC_TransmitQueue_TypeDef *queue); + +/** + * @brief Get the free space available for writing into the transmit queue. + * @note One byte is always kept unused to tell a full queue from an empty one. + * @param queue transmit queue. + * @return number of bytes that can be enqueued. + */ int CDC_TransmitQueue_WriteSize(CDC_TransmitQueue_TypeDef *queue); + +/** + * @brief Get the amount of data stored in the transmit queue. + * @param queue transmit queue. + * @return number of bytes waiting to be transmitted. + */ int CDC_TransmitQueue_ReadSize(CDC_TransmitQueue_TypeDef *queue); + +/** + * @brief Copy data into the transmit queue, wrapping at the end of the buffer. + * @note The caller must check CDC_TransmitQueue_WriteSize() first. Writing more + * than the free space overwrites data not yet transmitted. + * @param queue transmit queue. + * @param buffer data to copy. + * @param size number of bytes to copy. + */ void CDC_TransmitQueue_Enqueue(CDC_TransmitQueue_TypeDef *queue, const uint8_t *buffer, uint32_t size); + +/** + * @brief Get a contiguous block of queued data to transmit. + * @note The block may be shorter than the total queued data when it wraps + * around the end of the buffer. The block is reserved until + * CDC_TransmitQueue_CommitRead() is called. + * @param queue transmit queue. + * @param size output: length of the returned block in bytes. + * @return pointer to the first byte of the block. + */ uint8_t *CDC_TransmitQueue_ReadBlock(CDC_TransmitQueue_TypeDef *queue, uint16_t *size); + +/** + * @brief Release the block returned by CDC_TransmitQueue_ReadBlock(). + * @param queue transmit queue. + */ void CDC_TransmitQueue_CommitRead(CDC_TransmitQueue_TypeDef *queue); +/** + * @brief Initialize read and write position of the receive queue. + * @param queue receive queue to initialize. + */ void CDC_ReceiveQueue_Init(CDC_ReceiveQueue_TypeDef *queue); + +/** + * @brief Get the amount of data available for reading from the receive queue. + * @param queue receive queue. + * @return number of bytes available to read. + */ int CDC_ReceiveQueue_ReadSize(CDC_ReceiveQueue_TypeDef *queue); + +/** + * @brief Read and remove one byte from the receive queue. + * @param queue receive queue. + * @return byte value (0-255), or -1 if the queue is empty. + */ int CDC_ReceiveQueue_Dequeue(CDC_ReceiveQueue_TypeDef *queue); + +/** + * @brief Read one byte from the receive queue without removing it. + * @param queue receive queue. + * @return byte value (0-255), or -1 if the queue is empty. + */ int CDC_ReceiveQueue_Peek(CDC_ReceiveQueue_TypeDef *queue); + +/** + * @brief Read and remove up to size bytes from the receive queue. + * @param queue receive queue. + * @param buffer destination buffer. + * @param size maximum number of bytes to read. + * @return number of bytes copied into buffer. + */ uint16_t CDC_ReceiveQueue_Read(CDC_ReceiveQueue_TypeDef *queue, uint8_t *buffer, uint16_t size); + +/** + * @brief Read and remove bytes from the receive queue up to a terminator. + * @note The terminator is consumed but not copied into buffer. If the + * terminator is not found, up to size bytes are read and removed. + * @param queue receive queue. + * @param terminator byte that ends the read. + * @param buffer destination buffer. + * @param size maximum number of bytes to copy into buffer. + * @param fetched output: number of bytes copied into buffer, excluding the terminator. + * @return true if the terminator was found, false otherwise. + */ bool CDC_ReceiveQueue_ReadUntil(CDC_ReceiveQueue_TypeDef *queue, uint8_t terminator, uint8_t *buffer, uint16_t size, uint16_t *fetched); + +/** + * @brief Reserve space in the receive queue for an incoming packet. + * @note Up to CDC_QUEUE_MAX_PACKET_SIZE bytes may be written to the returned + * pointer. Call CDC_ReceiveQueue_CommitBlock() with the number of bytes + * actually written. + * @param queue receive queue. + * @return pointer where the packet can be written, or NULL if there is no room. + */ uint8_t *CDC_ReceiveQueue_ReserveBlock(CDC_ReceiveQueue_TypeDef *queue); + +/** + * @brief Commit bytes written to a block returned by CDC_ReceiveQueue_ReserveBlock(). + * @param queue receive queue. + * @param size number of bytes written into the reserved block. + */ void CDC_ReceiveQueue_CommitBlock(CDC_ReceiveQueue_TypeDef *queue, uint16_t size); #ifdef __cplusplus diff --git a/libraries/USBDevice/inc/usbd_cdc.h b/libraries/USBDevice/inc/usbd_cdc.h index 8db2fbc648..981a7b6311 100644 --- a/libraries/USBDevice/inc/usbd_cdc.h +++ b/libraries/USBDevice/inc/usbd_cdc.h @@ -141,19 +141,59 @@ extern USBD_ClassTypeDef USBD_CDC; /** @defgroup USB_CORE_Exported_Functions * @{ */ +/** + * @brief Register the application callbacks for the CDC class. + * @param pdev device instance. + * @param fops pointer to the CDC interface callbacks. + * @return USBD_OK on success, USBD_FAIL if fops is NULL. + */ uint8_t USBD_CDC_RegisterInterface(USBD_HandleTypeDef *pdev, USBD_CDC_ItfTypeDef *fops); +/** + * @brief Set the buffer and length of the next data to send on the CDC IN endpoint. + * @note Does not start the transfer, call USBD_CDC_TransmitPacket() for that. + * @param pdev device instance. + * @param pbuff pointer to the Tx buffer. + * @param length length of the data to send, in bytes. + * @param ClassId class ID, used only when USE_USBD_COMPOSITE is defined. + * @return USBD_OK on success, USBD_FAIL if the class instance is not allocated. + */ #ifdef USE_USBD_COMPOSITE uint8_t USBD_CDC_SetTxBuffer(USBD_HandleTypeDef *pdev, uint8_t *pbuff, uint32_t length, uint8_t ClassId); -uint8_t USBD_CDC_TransmitPacket(USBD_HandleTypeDef *pdev, uint8_t ClassId); #else uint8_t USBD_CDC_SetTxBuffer(USBD_HandleTypeDef *pdev, uint8_t *pbuff, uint32_t length); -uint8_t USBD_CDC_TransmitPacket(USBD_HandleTypeDef *pdev); #endif /* USE_USBD_COMPOSITE */ + +/** + * @brief Set the Rx buffer used for the next packet received on the CDC OUT endpoint. + * @param pdev device instance. + * @param pbuff pointer to the Rx buffer. + * @return USBD_OK on success, USBD_FAIL if the class instance is not allocated. + */ uint8_t USBD_CDC_SetRxBuffer(USBD_HandleTypeDef *pdev, uint8_t *pbuff); + +/** + * @brief Transmit the buffer set by USBD_CDC_SetTxBuffer() on the CDC IN endpoint. + * @note Does nothing if a transfer is already in progress. + * @param pdev device instance. + * @param ClassId class ID, used only when USE_USBD_COMPOSITE is defined. + * @return USBD_OK if the transfer was started, USBD_BUSY if a transfer is in + * progress, USBD_FAIL if the class instance is not allocated. + */ +#ifdef USE_USBD_COMPOSITE +uint8_t USBD_CDC_TransmitPacket(USBD_HandleTypeDef *pdev, uint8_t ClassId); +#else +uint8_t USBD_CDC_TransmitPacket(USBD_HandleTypeDef *pdev); +#endif /* USE_USBD_COMPOSITE */ + +/** + * @brief Prepare the CDC OUT endpoint to receive the next packet into the Rx buffer. + * @param pdev device instance. + * @return USBD_OK on success, USBD_FAIL if the class instance is not allocated. + */ uint8_t USBD_CDC_ReceivePacket(USBD_HandleTypeDef *pdev); /** * @} diff --git a/libraries/USBDevice/inc/usbd_cdc_if.h b/libraries/USBDevice/inc/usbd_cdc_if.h index 1d3f8b91ff..8416063fbf 100644 --- a/libraries/USBDevice/inc/usbd_cdc_if.h +++ b/libraries/USBDevice/inc/usbd_cdc_if.h @@ -46,17 +46,70 @@ extern CDC_ReceiveQueue_TypeDef ReceiveQueue; /* Exported macro ------------------------------------------------------------*/ /* Exported functions ------------------------------------------------------- */ +/** + * @brief Resume the USB CDC transmit queue if the IN endpoint is idle. + * @note Called from USBSerial::write() and from the USB transmit complete callback. + */ void CDC_continue_transmit(void); + +/** + * @brief Re-arm the USB CDC OUT endpoint with a new receive buffer. + * @note Does nothing if a receive is already pending or the receive queue has + * no room for a full packet. + * @return true if reception was resumed, false otherwise. + */ bool CDC_resume_receive(void); + +/** + * @brief Initialize the USB CDC device and start USB enumeration. + * @note Does nothing if the device is already initialized. + */ void CDC_init(void); + +/** + * @brief Stop the USB CDC device and release its USB resources. + * @note Does nothing if the device is not initialized. + */ void CDC_deInit(void); + +/** + * @brief Check whether a host is connected and ready to receive data. + * @return true if the device is configured, DTR is asserted and the last + * transmission did not time out, false otherwise. + */ bool CDC_connected(void); + +/** + * @brief Enable or disable the use of the host DTR signal for CDC_connected(). + * @param enable true to take DTR into account, false to ignore it. + */ void CDC_enableDTR(bool enable); -// getters for CDC line codings. Do not expose struct directly +/* getters for CDC line codings. Do not expose struct directly */ + +/** + * @brief Get the baud rate set by the USB host. + * @return baud rate in bits per second. + */ uint32_t CDC_getBaudrate(void); + +/** + * @brief Get the stop bits set by the USB host. + * @return 0 for one stop bit, 1 for 1.5 stop bits, 2 for two stop bits. + * Values match USBSerial.h. + */ uint8_t CDC_getStopBits(void); + +/** + * @brief Get the parity set by the USB host. + * @return 0 none, 1 odd, 2 even, 3 mark, 4 space. Values match USBSerial.h. + */ uint8_t CDC_getParity(void); + +/** + * @brief Get the number of data bits set by the USB host. + * @return number of data bits (5, 6, 7, 8 or 16). + */ uint8_t CDC_getDataBits(void); #ifdef __cplusplus diff --git a/libraries/USBDevice/inc/usbd_conf.h b/libraries/USBDevice/inc/usbd_conf.h index 326a9e01c3..91225a1381 100644 --- a/libraries/USBDevice/inc/usbd_conf.h +++ b/libraries/USBDevice/inc/usbd_conf.h @@ -321,7 +321,17 @@ extern "C" { #endif /* (USBD_DEBUG_LEVEL > 2U) */ /* Exported functions -------------------------------------------------------*/ +/** + * @brief Allocate memory for the USB stack. + * @param size Number of bytes to allocate. + * @return Pointer to the allocated memory. + */ void *USBD_static_malloc(uint32_t size); + +/** + * @brief Free memory allocated by USBD_static_malloc(). + * @param p Pointer to the memory to free. + */ void USBD_static_free(void *p); #endif /* USBCON */ diff --git a/libraries/USBDevice/inc/usbd_hid_composite_if.h b/libraries/USBDevice/inc/usbd_hid_composite_if.h index 4f9688e716..06a880ec9f 100644 --- a/libraries/USBDevice/inc/usbd_hid_composite_if.h +++ b/libraries/USBDevice/inc/usbd_hid_composite_if.h @@ -38,10 +38,35 @@ typedef enum { ((DEVICE) == HID_MOUSE)) /* Exported functions ------------------------------------------------------- */ +/** + * @brief Initialize the USB device stack for a HID composite interface. + * @param device HID interface to enable: HID_KEYBOARD or HID_MOUSE. + * @note The USB device is started once, when the first interface is + * initialized. Calling it again for the other interface only + * marks it as active. + */ void HID_Composite_Init(HID_Interface device); + +/** + * @brief Release a HID composite interface. + * @param device HID interface to release: HID_KEYBOARD or HID_MOUSE. + * @note The USB device is stopped and de-initialized once no interface + * is active. + */ void HID_Composite_DeInit(HID_Interface device); +/** + * @brief Send a HID mouse report. + * @param report Pointer to the report data. + * @param len Length of the report, in bytes. + */ void HID_Composite_mouse_sendReport(uint8_t *report, uint16_t len); + +/** + * @brief Send a HID keyboard report. + * @param report Pointer to the report data. + * @param len Length of the report, in bytes. + */ void HID_Composite_keyboard_sendReport(uint8_t *report, uint16_t len); #ifdef __cplusplus diff --git a/libraries/USBDevice/inc/usbd_if.h b/libraries/USBDevice/inc/usbd_if.h index b21a328db0..96681e4000 100644 --- a/libraries/USBDevice/inc/usbd_if.h +++ b/libraries/USBDevice/inc/usbd_if.h @@ -23,12 +23,29 @@ extern "C" { #endif +/** + * @brief Force to re-enumerate USB. + * + * Intended to be called at startup by core code. It can also be used at + * runtime, while USB is connected, but that does not work in all cases + * (when USB is enabled on an F103C8, setting output mode on the DP pin + * no longer has any effect). + */ void USBD_reenumerate(void); + #ifdef USBD_USE_CDC +/** + * @brief Initialize the CDC interface used by the USB serial port. + */ void USBD_CDC_init(void); #endif -/* Weaked function */ +/** + * @brief Configure the system clock and system IP clocks after wake-up + * from the USB resume callback. + * @note Weak function, can be redefined by the user at the sketch level. + * By default, calls configIPClock() and SystemClock_Config(). + */ void USBD_SystemClockConfigFromResume(void); #ifdef __cplusplus diff --git a/libraries/USBDevice/src/cdc/cdc_queue.c b/libraries/USBDevice/src/cdc/cdc_queue.c index 2d2330c195..884efa284f 100644 --- a/libraries/USBDevice/src/cdc/cdc_queue.c +++ b/libraries/USBDevice/src/cdc/cdc_queue.c @@ -40,28 +40,24 @@ #include "cdc_queue.h" -// Initialize read and write position of queue void CDC_TransmitQueue_Init(CDC_TransmitQueue_TypeDef *queue) { queue->read = 0; queue->write = 0; } -// Determine size, available for write in queue int CDC_TransmitQueue_WriteSize(CDC_TransmitQueue_TypeDef *queue) { return (queue->read + CDC_TRANSMIT_QUEUE_BUFFER_SIZE - queue->write - 1) % CDC_TRANSMIT_QUEUE_BUFFER_SIZE; } -// Determine size of data, stored in queue int CDC_TransmitQueue_ReadSize(CDC_TransmitQueue_TypeDef *queue) { return (queue->write + CDC_TRANSMIT_QUEUE_BUFFER_SIZE - queue->read) % CDC_TRANSMIT_QUEUE_BUFFER_SIZE; } -// Write provided data into queue. void CDC_TransmitQueue_Enqueue(CDC_TransmitQueue_TypeDef *queue, const uint8_t *buffer, uint32_t size) { @@ -76,7 +72,6 @@ void CDC_TransmitQueue_Enqueue(CDC_TransmitQueue_TypeDef *queue, CDC_TRANSMIT_QUEUE_BUFFER_SIZE); } -// Read flat block from queue biggest as possible, but max QUEUE_MAX_PACKET_SIZE uint8_t *CDC_TransmitQueue_ReadBlock(CDC_TransmitQueue_TypeDef *queue, uint16_t *size) { @@ -95,7 +90,6 @@ void CDC_TransmitQueue_CommitRead(CDC_TransmitQueue_TypeDef *queue) CDC_TRANSMIT_QUEUE_BUFFER_SIZE; } -// Initialize read and write position of queue. void CDC_ReceiveQueue_Init(CDC_ReceiveQueue_TypeDef *queue) { queue->read = 0; @@ -103,7 +97,6 @@ void CDC_ReceiveQueue_Init(CDC_ReceiveQueue_TypeDef *queue) queue->length = CDC_RECEIVE_QUEUE_BUFFER_SIZE; } -// Reserve block in queue and return pointer to it. uint8_t *CDC_ReceiveQueue_ReserveBlock(CDC_ReceiveQueue_TypeDef *queue) { const uint16_t limit = @@ -130,7 +123,6 @@ uint8_t *CDC_ReceiveQueue_ReserveBlock(CDC_ReceiveQueue_TypeDef *queue) return 0; } -// Commits block in queue and make it available for reading void CDC_ReceiveQueue_CommitBlock(CDC_ReceiveQueue_TypeDef *queue, uint16_t size) { @@ -143,7 +135,6 @@ void CDC_ReceiveQueue_CommitBlock(CDC_ReceiveQueue_TypeDef *queue, } } -// Determine size, available for read int CDC_ReceiveQueue_ReadSize(CDC_ReceiveQueue_TypeDef *queue) { // reading length after write make guarantee, that length >= write @@ -156,7 +147,6 @@ int CDC_ReceiveQueue_ReadSize(CDC_ReceiveQueue_TypeDef *queue) return length + write - queue->read; } -// Read one byte from queue. int CDC_ReceiveQueue_Dequeue(CDC_ReceiveQueue_TypeDef *queue) { volatile uint16_t write = queue->write; @@ -174,7 +164,6 @@ int CDC_ReceiveQueue_Dequeue(CDC_ReceiveQueue_TypeDef *queue) return ch; } -// Peek byte from queue. int CDC_ReceiveQueue_Peek(CDC_ReceiveQueue_TypeDef *queue) { volatile uint16_t write = queue->write; diff --git a/libraries/USBDevice/src/cdc/usbd_cdc.c b/libraries/USBDevice/src/cdc/usbd_cdc.c index a93f45dd4f..a859551d2c 100644 --- a/libraries/USBDevice/src/cdc/usbd_cdc.c +++ b/libraries/USBDevice/src/cdc/usbd_cdc.c @@ -890,12 +890,6 @@ uint8_t *USBD_CDC_GetDeviceQualifierDescriptor(uint16_t *length) return USBD_CDC_DeviceQualifierDesc; } #endif /* USE_USBD_COMPOSITE */ -/** - * @brief USBD_CDC_RegisterInterface - * @param pdev: device instance - * @param fops: CD Interface callback - * @retval status - */ uint8_t USBD_CDC_RegisterInterface(USBD_HandleTypeDef *pdev, USBD_CDC_ItfTypeDef *fops) { @@ -908,14 +902,6 @@ uint8_t USBD_CDC_RegisterInterface(USBD_HandleTypeDef *pdev, return (uint8_t)USBD_OK; } -/** - * @brief USBD_CDC_SetTxBuffer - * @param pdev: device instance - * @param pbuff: Tx Buffer - * @param length: length of data to be sent - * @param ClassId: The Class ID - * @retval status - */ #ifdef USE_USBD_COMPOSITE uint8_t USBD_CDC_SetTxBuffer(USBD_HandleTypeDef *pdev, uint8_t *pbuff, uint32_t length, uint8_t ClassId) @@ -938,12 +924,6 @@ uint8_t USBD_CDC_SetTxBuffer(USBD_HandleTypeDef *pdev, return (uint8_t)USBD_OK; } -/** - * @brief USBD_CDC_SetRxBuffer - * @param pdev: device instance - * @param pbuff: Rx Buffer - * @retval status - */ uint8_t USBD_CDC_SetRxBuffer(USBD_HandleTypeDef *pdev, uint8_t *pbuff) { USBD_CDC_HandleTypeDef *hcdc = (USBD_CDC_HandleTypeDef *)pdev->pClassDataCmsit[pdev->classId]; @@ -957,13 +937,6 @@ uint8_t USBD_CDC_SetRxBuffer(USBD_HandleTypeDef *pdev, uint8_t *pbuff) return (uint8_t)USBD_OK; } -/** - * @brief USBD_CDC_TransmitPacket - * Transmit packet on IN endpoint - * @param pdev: device instance - * @param ClassId: The Class ID - * @retval status - */ #ifdef USE_USBD_COMPOSITE uint8_t USBD_CDC_TransmitPacket(USBD_HandleTypeDef *pdev, uint8_t ClassId) { @@ -1001,12 +974,6 @@ uint8_t USBD_CDC_TransmitPacket(USBD_HandleTypeDef *pdev) return (uint8_t)ret; } -/** - * @brief USBD_CDC_ReceivePacket - * prepare OUT Endpoint for reception - * @param pdev: device instance - * @retval status - */ uint8_t USBD_CDC_ReceivePacket(USBD_HandleTypeDef *pdev) { USBD_CDC_HandleTypeDef *hcdc = (USBD_CDC_HandleTypeDef *)pdev->pClassDataCmsit[pdev->classId]; diff --git a/libraries/USBDevice/src/cdc/usbd_cdc_if.c b/libraries/USBDevice/src/cdc/usbd_cdc_if.c index 2fe9614fb0..ef9f5841fe 100644 --- a/libraries/USBDevice/src/cdc/usbd_cdc_if.c +++ b/libraries/USBDevice/src/cdc/usbd_cdc_if.c @@ -95,7 +95,7 @@ USBD_CDC_LineCodingTypeDef linecoding = { * @brief USBD_CDC_Init * Initializes the CDC media low layer * @param None - * @retval Result of the operation: USBD_OK if all operations are OK else USBD_FAIL + * @return Result of the operation: USBD_OK if all operations are OK else USBD_FAIL */ static int8_t USBD_CDC_Init(void) { @@ -112,7 +112,7 @@ static int8_t USBD_CDC_Init(void) * @brief USBD_CDC_DeInit * DeInitializes the CDC media low layer * @param None - * @retval Result of the operation: USBD_OK if all operations are OK else USBD_FAIL + * @return Result of the operation: USBD_OK if all operations are OK else USBD_FAIL */ static int8_t USBD_CDC_DeInit(void) { @@ -126,7 +126,7 @@ static int8_t USBD_CDC_DeInit(void) * @param cmd: Command code * @param pbuf: Buffer containing command data (request parameters) * @param length: Number of data to be sent (in bytes) - * @retval Result of the operation: USBD_OK if all operations are OK else USBD_FAIL + * @return Result of the operation: USBD_OK if all operations are OK else USBD_FAIL */ static int8_t USBD_CDC_Control(uint8_t cmd, uint8_t *pbuf, uint16_t length) { @@ -225,7 +225,7 @@ static int8_t USBD_CDC_Control(uint8_t cmd, uint8_t *pbuf, uint16_t length) * * @param Buf: Buffer of data to be received * @param Len: Number of data received (in bytes) - * @retval Result of the operation: USBD_OK if all operations are OK else USBD_FAIL + * @return Result of the operation: USBD_OK if all operations are OK else USBD_FAIL */ static int8_t USBD_CDC_Receive(uint8_t *Buf, uint32_t *Len) { @@ -263,7 +263,7 @@ static int8_t USBD_CDC_Receive(uint8_t *Buf, uint32_t *Len) * * @param Buf: Buffer of data to be received * @param Len: Number of data received (in bytes) - * @retval Result of the operation: USBD_OK if all operations are OK else USBD_FAIL + * @return Result of the operation: USBD_OK if all operations are OK else USBD_FAIL */ static int8_t USBD_CDC_TransmitCplt(uint8_t *Buf, uint32_t *Len, uint8_t epnum) { @@ -390,19 +390,16 @@ uint32_t CDC_getBaudrate() return linecoding.bitrate; } -// getter for CDC stop bits. Note: CDC definition identical to USBSerial.h uint8_t CDC_getStopBits(void) { return linecoding.format; } -// getter for CDC parity. Note: CDC definition identical to USBSerial.h uint8_t CDC_getParity(void) { return linecoding.paritytype; } -// getter for CDC data bits. Note: CDC definition identical to USBSerial.h uint8_t CDC_getDataBits(void) { return linecoding.datatype; diff --git a/libraries/USBDevice/src/hid/usbd_hid_composite.c b/libraries/USBDevice/src/hid/usbd_hid_composite.c index f1fac007a5..4e3d4a79ab 100644 --- a/libraries/USBDevice/src/hid/usbd_hid_composite.c +++ b/libraries/USBDevice/src/hid/usbd_hid_composite.c @@ -520,7 +520,7 @@ static uint8_t HIDKInEpAdd = HID_KEYBOARD_EPIN_ADDR; * Initialize the HID interface * @param pdev: device instance * @param cfgidx: Configuration index - * @retval status + * @return status */ static uint8_t USBD_HID_Init(USBD_HandleTypeDef *pdev, uint8_t cfgidx) @@ -574,7 +574,7 @@ static uint8_t USBD_HID_Init(USBD_HandleTypeDef *pdev, * DeInitialize the HID layer * @param pdev: device instance * @param cfgidx: Configuration index - * @retval status + * @return status */ static uint8_t USBD_HID_DeInit(USBD_HandleTypeDef *pdev, uint8_t cfgidx) @@ -609,7 +609,7 @@ static uint8_t USBD_HID_DeInit(USBD_HandleTypeDef *pdev, * Handle the HID specific requests * @param pdev: instance * @param req: usb requests - * @retval status + * @return status */ static uint8_t USBD_COMPOSITE_HID_Setup(USBD_HandleTypeDef *pdev, USBD_SetupReqTypedef *req) @@ -627,7 +627,7 @@ static uint8_t USBD_COMPOSITE_HID_Setup(USBD_HandleTypeDef *pdev, * Handle the HID specific requests * @param pdev: instance * @param req: usb requests - * @retval status + * @return status */ static uint8_t USBD_HID_MOUSE_Setup(USBD_HandleTypeDef *pdev, USBD_SetupReqTypedef *req) @@ -736,7 +736,7 @@ static uint8_t USBD_HID_MOUSE_Setup(USBD_HandleTypeDef *pdev, * Handle the HID specific requests * @param pdev: instance * @param req: usb requests - * @retval status + * @return status */ static uint8_t USBD_HID_KEYBOARD_Setup(USBD_HandleTypeDef *pdev, USBD_SetupReqTypedef *req) @@ -839,14 +839,6 @@ static uint8_t USBD_HID_KEYBOARD_Setup(USBD_HandleTypeDef *pdev, return (uint8_t)ret; } -/** - * @brief USBD_HID_SendReport - * Send HID Report - * @param pdev: device instance - * @param buff: pointer to report - * @param ClassId: The Class ID - * @retval status - */ #ifdef USE_USBD_COMPOSITE uint8_t USBD_HID_MOUSE_SendReport(USBD_HandleTypeDef *pdev, uint8_t *report, @@ -883,14 +875,6 @@ uint8_t USBD_HID_MOUSE_SendReport(USBD_HandleTypeDef *pdev, return (uint8_t)USBD_OK; } -/** - * @brief USBD_HID_SendReport - * Send HID Report - * @param pdev: device instance - * @param buff: pointer to report - * @param ClassId: The Class ID - * @retval status - */ #ifdef USE_USBD_COMPOSITE uint8_t USBD_HID_KEYBOARD_SendReport(USBD_HandleTypeDef *pdev, uint8_t *report, @@ -927,12 +911,6 @@ uint8_t USBD_HID_KEYBOARD_SendReport(USBD_HandleTypeDef *pdev, return (uint8_t)USBD_OK; } -/** - * @brief USBD_HID_GetPollingInterval - * return polling interval from endpoint descriptor - * @param pdev: device instance - * @retval polling interval - */ uint32_t USBD_HID_GetPollingInterval(USBD_HandleTypeDef *pdev) { uint32_t polling_interval = 0U; @@ -956,9 +934,8 @@ uint32_t USBD_HID_GetPollingInterval(USBD_HandleTypeDef *pdev) /** * @brief USBD_HID_GetCfgFSDesc * return FS configuration descriptor - * @param speed : current device speed * @param length : pointer data length - * @retval pointer to descriptor buffer + * @return pointer to descriptor buffer */ static uint8_t *USBD_HID_GetFSCfgDesc(uint16_t *length) { @@ -980,9 +957,8 @@ static uint8_t *USBD_HID_GetFSCfgDesc(uint16_t *length) /** * @brief USBD_HID_GetCfgHSDesc * return HS configuration descriptor - * @param speed : current device speed * @param length : pointer data length - * @retval pointer to descriptor buffer + * @return pointer to descriptor buffer */ static uint8_t *USBD_HID_GetHSCfgDesc(uint16_t *length) { @@ -1004,9 +980,8 @@ static uint8_t *USBD_HID_GetHSCfgDesc(uint16_t *length) /** * @brief USBD_HID_GetOtherSpeedCfgDesc * return other speed configuration descriptor - * @param speed : current device speed * @param length : pointer data length - * @retval pointer to descriptor buffer + * @return pointer to descriptor buffer */ static uint8_t *USBD_HID_GetOtherSpeedCfgDesc(uint16_t *length) { @@ -1031,7 +1006,7 @@ static uint8_t *USBD_HID_GetOtherSpeedCfgDesc(uint16_t *length) * handle data IN Stage * @param pdev: device instance * @param epnum: endpoint index - * @retval status + * @return status */ static uint8_t USBD_HID_DataIn(USBD_HandleTypeDef *pdev, uint8_t epnum) @@ -1056,7 +1031,7 @@ static uint8_t USBD_HID_DataIn(USBD_HandleTypeDef *pdev, * @brief DeviceQualifierDescriptor * return Device Qualifier descriptor * @param length : pointer data length - * @retval pointer to descriptor buffer + * @return pointer to descriptor buffer */ static uint8_t *USBD_HID_GetDeviceQualifierDesc(uint16_t *length) { diff --git a/libraries/USBDevice/src/hid/usbd_hid_composite.h b/libraries/USBDevice/src/hid/usbd_hid_composite.h index c5d4aaab4c..86c1d01558 100644 --- a/libraries/USBDevice/src/hid/usbd_hid_composite.h +++ b/libraries/USBDevice/src/hid/usbd_hid_composite.h @@ -135,24 +135,56 @@ extern USBD_ClassTypeDef USBD_COMPOSITE_HID; /** @defgroup USB_CORE_Exported_Functions * @{ */ +/** + * @brief Send a HID mouse report. + * @param pdev Pointer to the device instance. + * @param report Pointer to the report data. + * @param len Length of the report, in bytes. + * @param ClassId Class instance ID. Only present when USE_USBD_COMPOSITE + * is defined. + * @return USBD_OK on success or if the device is not configured, + * USBD_BUSY if the previous report is still pending, + * USBD_FAIL if the class instance is not allocated. + */ #ifdef USE_USBD_COMPOSITE uint8_t USBD_HID_MOUSE_SendReport(USBD_HandleTypeDef *pdev, uint8_t *report, uint16_t len, uint8_t ClassId); +#else +uint8_t USBD_HID_MOUSE_SendReport(USBD_HandleTypeDef *pdev, + uint8_t *report, + uint16_t len); +#endif /* USE_USBD_COMPOSITE */ + +/** + * @brief Send a HID keyboard report. + * @param pdev Pointer to the device instance. + * @param report Pointer to the report data. + * @param len Length of the report, in bytes. + * @param ClassId Class instance ID. Only present when USE_USBD_COMPOSITE + * is defined. + * @return USBD_OK on success or if the device is not configured, + * USBD_BUSY if the previous report is still pending, + * USBD_FAIL if the class instance is not allocated. + */ +#ifdef USE_USBD_COMPOSITE uint8_t USBD_HID_KEYBOARD_SendReport(USBD_HandleTypeDef *pdev, uint8_t *report, uint16_t len, uint8_t ClassId); #else -uint8_t USBD_HID_MOUSE_SendReport(USBD_HandleTypeDef *pdev, - uint8_t *report, - uint16_t len); uint8_t USBD_HID_KEYBOARD_SendReport(USBD_HandleTypeDef *pdev, uint8_t *report, uint16_t len); #endif /* USE_USBD_COMPOSITE */ +/** + * @brief Get the polling interval from the HID endpoint descriptor. + * @param pdev Pointer to the device instance. + * @return Polling interval, computed from HID_HS_BINTERVAL when the device + * runs at high speed, or from HID_FS_BINTERVAL otherwise. + */ uint32_t USBD_HID_GetPollingInterval(USBD_HandleTypeDef *pdev); #ifdef __cplusplus diff --git a/libraries/USBDevice/src/hid/usbd_hid_composite_if.c b/libraries/USBDevice/src/hid/usbd_hid_composite_if.c index 9355bbac91..0622e2c93c 100644 --- a/libraries/USBDevice/src/hid/usbd_hid_composite_if.c +++ b/libraries/USBDevice/src/hid/usbd_hid_composite_if.c @@ -32,11 +32,6 @@ static bool HID_mouse_initialized = false; static bool icache_enabled = false; #endif -/** - * @brief Initialize USB devices - * @param HID_Interface device type: HID_KEYBOARD or HID_MOUSE - * @retval none - */ void HID_Composite_Init(HID_Interface device) { #if defined(ICACHE) && defined (HAL_ICACHE_MODULE_ENABLED) && !defined(HAL_ICACHE_MODULE_DISABLED) @@ -69,11 +64,6 @@ void HID_Composite_Init(HID_Interface device) } } -/** - * @brief DeInitialize USB devices - * @param HID_Interface device type: HID_KEYBOARD or HID_MOUSE - * @retval none - */ void HID_Composite_DeInit(HID_Interface device) { if (IS_HID_INTERFACE(device) && @@ -100,23 +90,11 @@ void HID_Composite_DeInit(HID_Interface device) } } -/** - * @brief Send HID mouse Report - * @param report pointer to report - * @param len report length - * @retval none - */ void HID_Composite_mouse_sendReport(uint8_t *report, uint16_t len) { USBD_HID_MOUSE_SendReport(&hUSBD_Device_HID, report, len); } -/** - * @brief Send HID keyboard Report - * @param report pointer to report - * @param len report length - * @retval none - */ void HID_Composite_keyboard_sendReport(uint8_t *report, uint16_t len) { USBD_HID_KEYBOARD_SendReport(&hUSBD_Device_HID, report, len); diff --git a/libraries/USBDevice/src/usbd_conf.c b/libraries/USBDevice/src/usbd_conf.c index a5f216e5a8..f207063bd1 100644 --- a/libraries/USBDevice/src/usbd_conf.c +++ b/libraries/USBDevice/src/usbd_conf.c @@ -46,7 +46,6 @@ PCD_HandleTypeDef g_hpcd; /** * @brief Initializes the PCD MSP. * @param hpcd: PCD handle - * @retval None */ void HAL_PCD_MspInit(PCD_HandleTypeDef *hpcd) { @@ -224,7 +223,6 @@ void HAL_PCD_MspInit(PCD_HandleTypeDef *hpcd) /** * @brief De-Initializes the PCD MSP. * @param hpcd: PCD handle - * @retval None */ void HAL_PCD_MspDeInit(PCD_HandleTypeDef *hpcd) { @@ -255,7 +253,6 @@ void HAL_PCD_MspDeInit(PCD_HandleTypeDef *hpcd) /** * @brief SetupStage callback. * @param hpcd: PCD handle - * @retval None */ void HAL_PCD_SetupStageCallback(PCD_HandleTypeDef *hpcd) { @@ -266,7 +263,6 @@ void HAL_PCD_SetupStageCallback(PCD_HandleTypeDef *hpcd) * @brief DataOut Stage callback. * @param hpcd: PCD handle * @param epnum: Endpoint Number - * @retval None */ void HAL_PCD_DataOutStageCallback(PCD_HandleTypeDef *hpcd, uint8_t epnum) { @@ -277,7 +273,6 @@ void HAL_PCD_DataOutStageCallback(PCD_HandleTypeDef *hpcd, uint8_t epnum) * @brief DataIn Stage callback. * @param hpcd: PCD handle * @param epnum: Endpoint Number - * @retval None */ void HAL_PCD_DataInStageCallback(PCD_HandleTypeDef *hpcd, uint8_t epnum) { @@ -287,7 +282,6 @@ void HAL_PCD_DataInStageCallback(PCD_HandleTypeDef *hpcd, uint8_t epnum) /** * @brief SOF callback. * @param hpcd: PCD handle - * @retval None */ void HAL_PCD_SOFCallback(PCD_HandleTypeDef *hpcd) { @@ -297,7 +291,6 @@ void HAL_PCD_SOFCallback(PCD_HandleTypeDef *hpcd) /** * @brief Reset callback. * @param hpcd: PCD handle - * @retval None */ void HAL_PCD_ResetCallback(PCD_HandleTypeDef *hpcd) { @@ -328,7 +321,6 @@ void HAL_PCD_ResetCallback(PCD_HandleTypeDef *hpcd) /** * @brief Suspend callback. * @param hpcd: PCD handle - * @retval None */ void HAL_PCD_SuspendCallback(PCD_HandleTypeDef *hpcd) { @@ -345,7 +337,6 @@ void HAL_PCD_SuspendCallback(PCD_HandleTypeDef *hpcd) /** * @brief Resume callback. * @param hpcd: PCD handle - * @retval None */ void HAL_PCD_ResumeCallback(PCD_HandleTypeDef *hpcd) { @@ -363,7 +354,6 @@ void HAL_PCD_ResumeCallback(PCD_HandleTypeDef *hpcd) * @brief ISOOUTIncomplete callback. * @param hpcd: PCD handle * @param epnum: Endpoint Number - * @retval None */ void HAL_PCD_ISOOUTIncompleteCallback(PCD_HandleTypeDef *hpcd, uint8_t epnum) { @@ -374,7 +364,6 @@ void HAL_PCD_ISOOUTIncompleteCallback(PCD_HandleTypeDef *hpcd, uint8_t epnum) * @brief ISOINIncomplete callback. * @param hpcd: PCD handle * @param epnum: Endpoint Number - * @retval None */ void HAL_PCD_ISOINIncompleteCallback(PCD_HandleTypeDef *hpcd, uint8_t epnum) { @@ -384,7 +373,6 @@ void HAL_PCD_ISOINIncompleteCallback(PCD_HandleTypeDef *hpcd, uint8_t epnum) /** * @brief ConnectCallback callback. * @param hpcd: PCD handle - * @retval None */ void HAL_PCD_ConnectCallback(PCD_HandleTypeDef *hpcd) { @@ -394,7 +382,6 @@ void HAL_PCD_ConnectCallback(PCD_HandleTypeDef *hpcd) /** * @brief Disconnect callback. * @param hpcd: PCD handle - * @retval None */ void HAL_PCD_DisconnectCallback(PCD_HandleTypeDef *hpcd) { @@ -404,7 +391,6 @@ void HAL_PCD_DisconnectCallback(PCD_HandleTypeDef *hpcd) /** * @brief This function handles USB-On-The-Go FS/HS global interrupt request. * @param None - * @retval None */ #ifdef USE_USB_HS void OTG_HS_IRQHandler(void) @@ -421,7 +407,6 @@ void HAL_PCD_DisconnectCallback(PCD_HandleTypeDef *hpcd) /** * @brief This function handles USB high priority interrupt. * @param None - * @retval None */ void USB_H_IRQHandler(void) { @@ -432,7 +417,6 @@ void USB_H_IRQHandler(void) /** * @brief This function handles USB Wakeup IRQ Handler. * @param None - * @retval None */ #ifdef USE_USB_HS void OTG_HS_WKUP_IRQHandler(void) @@ -471,7 +455,7 @@ void USB_H_IRQHandler(void) /** * @brief Initializes the Low Level portion of the Device driver. * @param pdev: Device handle - * @retval USBD Status + * @return USBD Status */ USBD_StatusTypeDef USBD_LL_Init(USBD_HandleTypeDef *pdev) { @@ -548,7 +532,7 @@ USBD_StatusTypeDef USBD_LL_Init(USBD_HandleTypeDef *pdev) /** * @brief De-Initializes the Low Level portion of the Device driver. * @param pdev: Device handle - * @retval USBD Status + * @return USBD Status */ USBD_StatusTypeDef USBD_LL_DeInit(USBD_HandleTypeDef *pdev) { @@ -559,7 +543,7 @@ USBD_StatusTypeDef USBD_LL_DeInit(USBD_HandleTypeDef *pdev) /** * @brief Starts the Low Level portion of the Device driver. * @param pdev: Device handle - * @retval USBD Status + * @return USBD Status */ USBD_StatusTypeDef USBD_LL_Start(USBD_HandleTypeDef *pdev) { @@ -570,7 +554,7 @@ USBD_StatusTypeDef USBD_LL_Start(USBD_HandleTypeDef *pdev) /** * @brief Stops the Low Level portion of the Device driver. * @param pdev: Device handle - * @retval USBD Status + * @return USBD Status */ USBD_StatusTypeDef USBD_LL_Stop(USBD_HandleTypeDef *pdev) { @@ -584,7 +568,7 @@ USBD_StatusTypeDef USBD_LL_Stop(USBD_HandleTypeDef *pdev) * @param ep_addr: Endpoint Number * @param ep_type: Endpoint Type * @param ep_mps: Endpoint Max Packet Size - * @retval USBD Status + * @return USBD Status */ USBD_StatusTypeDef USBD_LL_OpenEP(USBD_HandleTypeDef *pdev, uint8_t ep_addr, @@ -602,7 +586,7 @@ USBD_StatusTypeDef USBD_LL_OpenEP(USBD_HandleTypeDef *pdev, * @brief Closes an endpoint of the Low Level Driver. * @param pdev: Device handle * @param ep_addr: Endpoint Number - * @retval USBD Status + * @return USBD Status */ USBD_StatusTypeDef USBD_LL_CloseEP(USBD_HandleTypeDef *pdev, uint8_t ep_addr) { @@ -614,7 +598,7 @@ USBD_StatusTypeDef USBD_LL_CloseEP(USBD_HandleTypeDef *pdev, uint8_t ep_addr) * @brief Flushes an endpoint of the Low Level Driver. * @param pdev: Device handle * @param ep_addr: Endpoint Number - * @retval USBD Status + * @return USBD Status */ USBD_StatusTypeDef USBD_LL_FlushEP(USBD_HandleTypeDef *pdev, uint8_t ep_addr) { @@ -626,7 +610,7 @@ USBD_StatusTypeDef USBD_LL_FlushEP(USBD_HandleTypeDef *pdev, uint8_t ep_addr) * @brief Sets a Stall condition on an endpoint of the Low Level Driver. * @param pdev: Device handle * @param ep_addr: Endpoint Number - * @retval USBD Status + * @return USBD Status */ USBD_StatusTypeDef USBD_LL_StallEP(USBD_HandleTypeDef *pdev, uint8_t ep_addr) { @@ -638,7 +622,7 @@ USBD_StatusTypeDef USBD_LL_StallEP(USBD_HandleTypeDef *pdev, uint8_t ep_addr) * @brief Clears a Stall condition on an endpoint of the Low Level Driver. * @param pdev: Device handle * @param ep_addr: Endpoint Number - * @retval USBD Status + * @return USBD Status */ USBD_StatusTypeDef USBD_LL_ClearStallEP(USBD_HandleTypeDef *pdev, uint8_t ep_addr) { @@ -650,7 +634,7 @@ USBD_StatusTypeDef USBD_LL_ClearStallEP(USBD_HandleTypeDef *pdev, uint8_t ep_add * @brief Returns Stall condition. * @param pdev: Device handle * @param ep_addr: Endpoint Number - * @retval Stall (1: Yes, 0: No) + * @return Stall (1: Yes, 0: No) */ uint8_t USBD_LL_IsStallEP(USBD_HandleTypeDef *pdev, uint8_t ep_addr) { @@ -667,7 +651,7 @@ uint8_t USBD_LL_IsStallEP(USBD_HandleTypeDef *pdev, uint8_t ep_addr) * @brief Assigns a USB address to the device. * @param pdev: Device handle * @param dev_addr: Endpoint Number - * @retval USBD Status + * @return USBD Status */ USBD_StatusTypeDef USBD_LL_SetUSBAddress(USBD_HandleTypeDef *pdev, uint8_t dev_addr) @@ -682,7 +666,7 @@ USBD_StatusTypeDef USBD_LL_SetUSBAddress(USBD_HandleTypeDef *pdev, * @param ep_addr: Endpoint Number * @param pbuf: Pointer to data to be sent * @param size: Data size - * @retval USBD Status + * @return USBD Status */ USBD_StatusTypeDef USBD_LL_Transmit(USBD_HandleTypeDef *pdev, uint8_t ep_addr, uint8_t *pbuf, uint32_t size) @@ -697,7 +681,7 @@ USBD_StatusTypeDef USBD_LL_Transmit(USBD_HandleTypeDef *pdev, uint8_t ep_addr, * @param ep_addr: Endpoint Number * @param pbuf: Pointer to data to be received * @param size: Data size - * @retval USBD Status + * @return USBD Status */ USBD_StatusTypeDef USBD_LL_PrepareReceive(USBD_HandleTypeDef *pdev, uint8_t ep_addr, uint8_t *pbuf, @@ -711,7 +695,7 @@ USBD_StatusTypeDef USBD_LL_PrepareReceive(USBD_HandleTypeDef *pdev, * @brief Returns the last transferred packet size. * @param pdev: Device handle * @param ep_addr: Endpoint Number - * @retval Received Data Size + * @return Received Data Size */ uint32_t USBD_LL_GetRxDataSize(USBD_HandleTypeDef *pdev, uint8_t ep_addr) { @@ -721,7 +705,6 @@ uint32_t USBD_LL_GetRxDataSize(USBD_HandleTypeDef *pdev, uint8_t ep_addr) /** * @brief Delays routine for the USB Device Library. * @param Delay: Delay in ms - * @retval None */ void USBD_LL_Delay(uint32_t Delay) { diff --git a/libraries/USBDevice/src/usbd_confv2.c b/libraries/USBDevice/src/usbd_confv2.c index 7e135f9566..deb5c7fdfd 100644 --- a/libraries/USBDevice/src/usbd_confv2.c +++ b/libraries/USBDevice/src/usbd_confv2.c @@ -20,6 +20,10 @@ static USBD_HandleTypeDef *g_pdev; static uint8_t g_stalled_in; static uint8_t g_stalled_out; +/** + * @brief Configure the USB clock, interrupt priority, and NVIC interrupt for + * the HAL v2 USB device. + */ static void USBD_V2_ConfigPinsAndIrq(void) { /* The HAL v2 USB DRD FS PCD owns PA11/PA12 and configures these fixed USB @@ -52,27 +56,54 @@ void USBD_reenumerate(void) } #endif +/** + * @brief HAL PCD callback for a SETUP stage packet. Forwards it to the USB + * device core. + * @param hpcd PCD handle that raised the callback. + */ void HAL_PCD_SetupStageCallback(hal_pcd_handle_t *hpcd) { USBD_LL_SetupStage(g_pdev, (uint8_t *)hpcd->setup); } +/** + * @brief HAL PCD callback for the end of an OUT data stage. Forwards it to + * the USB device core. + * @param hpcd PCD handle that raised the callback. + * @param epnum Endpoint number. + */ void HAL_PCD_DataOutStageCallback(hal_pcd_handle_t *hpcd, uint8_t epnum) { USBD_LL_DataOutStage(g_pdev, epnum, hpcd->out_ep[epnum].p_xfer_buffer); } +/** + * @brief HAL PCD callback for the end of an IN data stage. Forwards it to + * the USB device core. + * @param hpcd PCD handle that raised the callback. + * @param epnum Endpoint number. + */ void HAL_PCD_DataInStageCallback(hal_pcd_handle_t *hpcd, uint8_t epnum) { USBD_LL_DataInStage(g_pdev, epnum, hpcd->in_ep[epnum].p_xfer_buffer); } +/** + * @brief HAL PCD callback for a start-of-frame event. Forwards it to the USB + * device core. + * @param hpcd PCD handle that raised the callback. + */ void HAL_PCD_SofCallback(hal_pcd_handle_t *hpcd) { (void)hpcd; USBD_LL_SOF(g_pdev); } +/** + * @brief HAL PCD callback for a bus reset. Resets the USB device core and + * sets the speed to full speed. + * @param hpcd PCD handle that raised the callback. + */ void HAL_PCD_ResetCallback(hal_pcd_handle_t *hpcd) { (void)hpcd; @@ -80,47 +111,88 @@ void HAL_PCD_ResetCallback(hal_pcd_handle_t *hpcd) USBD_LL_SetSpeed(g_pdev, USBD_SPEED_FULL); } +/** + * @brief HAL PCD callback for a suspend event. Forwards it to the USB device + * core. + * @param hpcd PCD handle that raised the callback. + */ void HAL_PCD_SuspendCallback(hal_pcd_handle_t *hpcd) { (void)hpcd; USBD_LL_Suspend(g_pdev); } +/** + * @brief HAL PCD callback for a resume event. Forwards it to the USB device + * core. + * @param hpcd PCD handle that raised the callback. + */ void HAL_PCD_ResumeCallback(hal_pcd_handle_t *hpcd) { (void)hpcd; USBD_LL_Resume(g_pdev); } +/** + * @brief HAL PCD callback for an incomplete isochronous OUT transfer. + * @param hpcd PCD handle that raised the callback. + * @param epnum Endpoint number. + */ void HAL_PCD_ISOOUTIncompleteCallback(hal_pcd_handle_t *hpcd, uint8_t epnum) { (void)hpcd; USBD_LL_IsoOUTIncomplete(g_pdev, epnum); } +/** + * @brief HAL PCD callback for an incomplete isochronous IN transfer. + * @param hpcd PCD handle that raised the callback. + * @param epnum Endpoint number. + */ void HAL_PCD_ISOINIncompleteCallback(hal_pcd_handle_t *hpcd, uint8_t epnum) { (void)hpcd; USBD_LL_IsoINIncomplete(g_pdev, epnum); } +/** + * @brief HAL PCD callback for the device connect event. Forwards it to the + * USB device core. + * @param hpcd PCD handle that raised the callback. + */ void HAL_PCD_ConnectCallback(hal_pcd_handle_t *hpcd) { (void)hpcd; USBD_LL_DevConnected(g_pdev); } +/** + * @brief HAL PCD callback for the device disconnect event. Forwards it to the + * USB device core. + * @param hpcd PCD handle that raised the callback. + */ void HAL_PCD_DisconnectCallback(hal_pcd_handle_t *hpcd) { (void)hpcd; USBD_LL_DevDisconnected(g_pdev); } +/** + * @brief USB interrupt service routine. Passes the interrupt to the HAL PCD + * driver. + */ void USB_IRQHandler(void) { HAL_PCD_IRQHandler(&g_hpcd); } +/** + * @brief Initialize the low-level USB driver: configure the PCD and endpoint + * PMA, then toggle the USB pull-up through USBD_reenumerate(). + * @note Calls Error_Handler() if the HAL PCD setup fails. + * @param pdev USB device handle. + * @return USBD_OK. + */ USBD_StatusTypeDef USBD_LL_Init(USBD_HandleTypeDef *pdev) { hal_pcd_config_t config = { @@ -161,6 +233,12 @@ USBD_StatusTypeDef USBD_LL_Init(USBD_HandleTypeDef *pdev) return USBD_OK; } +/** + * @brief De-initialize the low-level USB driver and disable its clock and + * interrupt. + * @param pdev USB device handle. + * @return USBD_OK. + */ USBD_StatusTypeDef USBD_LL_DeInit(USBD_HandleTypeDef *pdev) { (void)pdev; @@ -171,18 +249,36 @@ USBD_StatusTypeDef USBD_LL_DeInit(USBD_HandleTypeDef *pdev) return USBD_OK; } +/** + * @brief Start the USB device. + * @param pdev USB device handle. + * @return USBD_OK on success, USBD_FAIL otherwise. + */ USBD_StatusTypeDef USBD_LL_Start(USBD_HandleTypeDef *pdev) { (void)pdev; return (HAL_PCD_Start(&g_hpcd) == HAL_OK) ? USBD_OK : USBD_FAIL; } +/** + * @brief Stop the USB device. + * @param pdev USB device handle. + * @return USBD_OK on success, USBD_FAIL otherwise. + */ USBD_StatusTypeDef USBD_LL_Stop(USBD_HandleTypeDef *pdev) { (void)pdev; return (HAL_PCD_Stop(&g_hpcd) == HAL_OK) ? USBD_OK : USBD_FAIL; } +/** + * @brief Open an endpoint. + * @param pdev USB device handle. + * @param ep_addr Endpoint address, including the direction bit. + * @param ep_type Endpoint type, as a hal_pcd_ep_type_t value. + * @param ep_mps Maximum packet size, in bytes. + * @return USBD_OK on success, USBD_FAIL otherwise. + */ USBD_StatusTypeDef USBD_LL_OpenEP(USBD_HandleTypeDef *pdev, uint8_t ep_addr, uint8_t ep_type, uint16_t ep_mps) { @@ -191,18 +287,36 @@ USBD_StatusTypeDef USBD_LL_OpenEP(USBD_HandleTypeDef *pdev, uint8_t ep_addr, (hal_pcd_ep_type_t)ep_type) == HAL_OK) ? USBD_OK : USBD_FAIL; } +/** + * @brief Close an endpoint. + * @param pdev USB device handle. + * @param ep_addr Endpoint address, including the direction bit. + * @return USBD_OK on success, USBD_FAIL otherwise. + */ USBD_StatusTypeDef USBD_LL_CloseEP(USBD_HandleTypeDef *pdev, uint8_t ep_addr) { (void)pdev; return (HAL_PCD_CloseEndpoint(&g_hpcd, ep_addr) == HAL_OK) ? USBD_OK : USBD_FAIL; } +/** + * @brief Flush the buffers of an endpoint. + * @param pdev USB device handle. + * @param ep_addr Endpoint address, including the direction bit. + * @return USBD_OK on success, USBD_FAIL otherwise. + */ USBD_StatusTypeDef USBD_LL_FlushEP(USBD_HandleTypeDef *pdev, uint8_t ep_addr) { (void)pdev; return (HAL_PCD_FlushEndpoint(&g_hpcd, ep_addr) == HAL_OK) ? USBD_OK : USBD_FAIL; } +/** + * @brief Stall an endpoint. The stall state is also recorded in this module. + * @param pdev USB device handle. + * @param ep_addr Endpoint address, including the direction bit. + * @return USBD_OK on success, USBD_FAIL otherwise. + */ USBD_StatusTypeDef USBD_LL_StallEP(USBD_HandleTypeDef *pdev, uint8_t ep_addr) { uint8_t mask = (uint8_t)(1U << (ep_addr & 0x0FU)); @@ -215,6 +329,13 @@ USBD_StatusTypeDef USBD_LL_StallEP(USBD_HandleTypeDef *pdev, uint8_t ep_addr) return (HAL_PCD_SetEndpointStall(&g_hpcd, ep_addr) == HAL_OK) ? USBD_OK : USBD_FAIL; } +/** + * @brief Clear the stall of an endpoint. The stall state is also cleared in + * this module. + * @param pdev USB device handle. + * @param ep_addr Endpoint address, including the direction bit. + * @return USBD_OK on success, USBD_FAIL otherwise. + */ USBD_StatusTypeDef USBD_LL_ClearStallEP(USBD_HandleTypeDef *pdev, uint8_t ep_addr) { uint8_t mask = (uint8_t)(1U << (ep_addr & 0x0FU)); @@ -227,6 +348,12 @@ USBD_StatusTypeDef USBD_LL_ClearStallEP(USBD_HandleTypeDef *pdev, uint8_t ep_add return (HAL_PCD_ClearEndpointStall(&g_hpcd, ep_addr) == HAL_OK) ? USBD_OK : USBD_FAIL; } +/** + * @brief Check whether an endpoint is stalled. + * @param pdev USB device handle. + * @param ep_addr Endpoint address, including the direction bit. + * @return Non-zero if the endpoint is stalled, 0 otherwise. + */ uint8_t USBD_LL_IsStallEP(USBD_HandleTypeDef *pdev, uint8_t ep_addr) { uint8_t mask = (uint8_t)(1U << (ep_addr & 0x0FU)); @@ -235,12 +362,26 @@ uint8_t USBD_LL_IsStallEP(USBD_HandleTypeDef *pdev, uint8_t ep_addr) ((g_stalled_out & mask) != 0U); } +/** + * @brief Set the USB device address. + * @param pdev USB device handle. + * @param dev_addr New device address. + * @return USBD_OK on success, USBD_FAIL otherwise. + */ USBD_StatusTypeDef USBD_LL_SetUSBAddress(USBD_HandleTypeDef *pdev, uint8_t dev_addr) { (void)pdev; return (HAL_PCD_SetDeviceAddress(&g_hpcd, dev_addr) == HAL_OK) ? USBD_OK : USBD_FAIL; } +/** + * @brief Send data on an IN endpoint. + * @param pdev USB device handle. + * @param ep_addr Endpoint address, including the direction bit. + * @param pbuf Data to send. + * @param size Number of bytes to send. + * @return USBD_OK on success, USBD_FAIL otherwise. + */ USBD_StatusTypeDef USBD_LL_Transmit(USBD_HandleTypeDef *pdev, uint8_t ep_addr, uint8_t *pbuf, uint32_t size) { @@ -248,6 +389,14 @@ USBD_StatusTypeDef USBD_LL_Transmit(USBD_HandleTypeDef *pdev, uint8_t ep_addr, return (HAL_PCD_SetEndpointTransmit(&g_hpcd, ep_addr, pbuf, size) == HAL_OK) ? USBD_OK : USBD_FAIL; } +/** + * @brief Prepare an OUT endpoint to receive data. + * @param pdev USB device handle. + * @param ep_addr Endpoint address, including the direction bit. + * @param pbuf Buffer that receives the data. + * @param size Maximum number of bytes to receive. + * @return USBD_OK on success, USBD_FAIL otherwise. + */ USBD_StatusTypeDef USBD_LL_PrepareReceive(USBD_HandleTypeDef *pdev, uint8_t ep_addr, uint8_t *pbuf, uint32_t size) { @@ -255,12 +404,22 @@ USBD_StatusTypeDef USBD_LL_PrepareReceive(USBD_HandleTypeDef *pdev, uint8_t ep_a return (HAL_PCD_SetEndpointReceive(&g_hpcd, ep_addr, pbuf, size) == HAL_OK) ? USBD_OK : USBD_FAIL; } +/** + * @brief Get the number of bytes received on an endpoint. + * @param pdev USB device handle. + * @param ep_addr Endpoint address, including the direction bit. + * @return Number of received bytes. + */ uint32_t USBD_LL_GetRxDataSize(USBD_HandleTypeDef *pdev, uint8_t ep_addr) { (void)pdev; return HAL_PCD_EP_GetRxCount(&g_hpcd, ep_addr); } +/** + * @brief Delay for the USB stack. + * @param delay Delay, in milliseconds. + */ void USBD_LL_Delay(uint32_t delay) { HAL_Delay(delay); diff --git a/libraries/USBDevice/src/usbd_desc.c b/libraries/USBDevice/src/usbd_desc.c index b22655f6f5..f242f430ef 100644 --- a/libraries/USBDevice/src/usbd_desc.c +++ b/libraries/USBDevice/src/usbd_desc.c @@ -337,7 +337,7 @@ static void Get_SerialNum(void); * @brief Returns the device descriptor. * @param speed: Current device speed * @param length: Pointer to data length variable - * @retval Pointer to descriptor buffer + * @return Pointer to descriptor buffer */ uint8_t *USBD_Class_DeviceDescriptor(USBD_SpeedTypeDef speed, uint16_t *length) { @@ -350,7 +350,7 @@ uint8_t *USBD_Class_DeviceDescriptor(USBD_SpeedTypeDef speed, uint16_t *length) * @brief Returns the LangID string descriptor. * @param speed: Current device speed * @param length: Pointer to data length variable - * @retval Pointer to descriptor buffer + * @return Pointer to descriptor buffer */ uint8_t *USBD_LangIDStrDescriptor(USBD_SpeedTypeDef speed, uint16_t *length) { @@ -363,7 +363,7 @@ uint8_t *USBD_LangIDStrDescriptor(USBD_SpeedTypeDef speed, uint16_t *length) * @brief Returns the product string descriptor. * @param speed: Current device speed * @param length: Pointer to data length variable - * @retval Pointer to descriptor buffer + * @return Pointer to descriptor buffer */ uint8_t *USBD_Class_ProductStrDescriptor(USBD_SpeedTypeDef speed, uint16_t *length) { @@ -379,7 +379,7 @@ uint8_t *USBD_Class_ProductStrDescriptor(USBD_SpeedTypeDef speed, uint16_t *leng * @brief Returns the manufacturer string descriptor. * @param speed: Current device speed * @param length: Pointer to data length variable - * @retval Pointer to descriptor buffer + * @return Pointer to descriptor buffer */ uint8_t *USBD_ManufacturerStrDescriptor(USBD_SpeedTypeDef speed, uint16_t *length) { @@ -392,7 +392,7 @@ uint8_t *USBD_ManufacturerStrDescriptor(USBD_SpeedTypeDef speed, uint16_t *lengt * @brief Returns the serial number string descriptor. * @param speed: Current device speed * @param length: Pointer to data length variable - * @retval Pointer to descriptor buffer + * @return Pointer to descriptor buffer */ uint8_t *USBD_SerialStrDescriptor(USBD_SpeedTypeDef speed, uint16_t *length) { @@ -410,7 +410,7 @@ uint8_t *USBD_SerialStrDescriptor(USBD_SpeedTypeDef speed, uint16_t *length) * @brief Returns the configuration string descriptor. * @param speed: Current device speed * @param length: Pointer to data length variable - * @retval Pointer to descriptor buffer + * @return Pointer to descriptor buffer */ uint8_t *USBD_Class_ConfigStrDescriptor(USBD_SpeedTypeDef speed, uint16_t *length) { @@ -426,7 +426,7 @@ uint8_t *USBD_Class_ConfigStrDescriptor(USBD_SpeedTypeDef speed, uint16_t *lengt * @brief Returns the interface string descriptor. * @param speed: Current device speed * @param length: Pointer to data length variable - * @retval Pointer to descriptor buffer + * @return Pointer to descriptor buffer */ uint8_t *USBD_Class_InterfaceStrDescriptor(USBD_SpeedTypeDef speed, uint16_t *length) { @@ -441,7 +441,6 @@ uint8_t *USBD_Class_InterfaceStrDescriptor(USBD_SpeedTypeDef speed, uint16_t *le /** * @brief Create the serial number string descriptor * @param None - * @retval None */ static void Get_SerialNum(void) { @@ -464,7 +463,7 @@ static void Get_SerialNum(void) * return the BOS descriptor * @param speed : current device speed * @param length : pointer to data length variable - * @retval pointer to descriptor buffer + * @return pointer to descriptor buffer */ uint8_t *USBD_USR_BOSDescriptor(USBD_SpeedTypeDef speed, uint16_t *length) { @@ -481,7 +480,7 @@ uint8_t *USBD_USR_BOSDescriptor(USBD_SpeedTypeDef speed, uint16_t *length) * @param speed: Current device speed * @param idx: index of string descriptor * @param length: Pointer to data length variable - * @retval Pointer to descriptor buffer + * @return Pointer to descriptor buffer */ uint8_t *USBD_Class_UserStrDescriptor(USBD_SpeedTypeDef speed, uint8_t idx, uint16_t *length) { @@ -499,7 +498,6 @@ uint8_t *USBD_Class_UserStrDescriptor(USBD_SpeedTypeDef speed, uint8_t idx, uint * @param value: value to convert * @param pbuf: pointer to the buffer * @param len: buffer length - * @retval None */ static void IntToUnicode(uint32_t value, uint8_t *pbuf, uint8_t len) { diff --git a/libraries/USBDevice/src/usbd_if.c b/libraries/USBDevice/src/usbd_if.c index 6353c09e4f..2ae42977fe 100644 --- a/libraries/USBDevice/src/usbd_if.c +++ b/libraries/USBDevice/src/usbd_if.c @@ -116,17 +116,6 @@ #define USBD_DP_TRICK #endif -/** - * @brief Force to re-enumerate USB. - * - * This is intended to be called at startup by core code. It could be - * used at runtime, while USB is connected, to force re-enumeration - * too, but that does not work in all cases (when USB is enabled on an - * F103C8, setting output mode on the DP pin no longer has any effect). - * - * @param None - * @retval None - */ WEAK void USBD_reenumerate(void) { #if defined(USBD_PULLUP_CONTROL_PINNAME) @@ -176,14 +165,6 @@ void USBD_CDC_init(void) } #endif /* USBD_USE_CDC */ -/** - * @brief Configures system clock and system IP clocks after wake-up from USB - * resume callBack - * @note Weaked function which can be redefined by user at the sketch level. - * By default, calls 'SystemClock_Config()'. - * @param None - * @retval None - */ WEAK void USBD_SystemClockConfigFromResume(void) { configIPClock(); diff --git a/libraries/VirtIO/inc/VirtIOSerial.h b/libraries/VirtIO/inc/VirtIOSerial.h index 416ad3dc24..34fea5e327 100644 --- a/libraries/VirtIO/inc/VirtIOSerial.h +++ b/libraries/VirtIO/inc/VirtIOSerial.h @@ -47,24 +47,103 @@ typedef struct { class VirtIOSerial : public Stream { public: + /** + * @brief Start the serial link. Blocks until the Linux host sends its + * first message. + */ void begin(void); + + /** + * @brief Start the serial link. The baud rate is ignored, OpenAMP has + * no UART configuration. + */ void begin(uint32_t); + + /** + * @brief Start the serial link. The baud rate and configuration are + * ignored, OpenAMP has no UART configuration. + */ void begin(uint32_t, uint8_t); + + /** + * @brief Stop the serial link and release the OpenAMP resources. + */ void end(void); + /** + * @brief Get the number of bytes available to read. + * @return Number of bytes in the receive buffer. + */ virtual int available(void); + + /** + * @brief Get the maximum number of bytes that one write() can send. + * @return RPMSG_VRING_PAYLOAD_SIZE. + */ virtual int availableForWrite(void); + + /** + * @brief Get the next byte without removing it from the receive buffer. + * @return The next byte, or -1 if the receive buffer is empty. + */ virtual int peek(void); + + /** + * @brief Read one byte from the receive buffer. + * @return The byte read, or -1 if the receive buffer is empty. + */ virtual int read(void); - virtual size_t readBytes(char *buffer, size_t length); // read chars from stream into buffer + + /** + * @brief Read bytes from the receive buffer into a buffer. + * @param buffer Destination buffer. + * @param length Maximum number of bytes to read. + * @return Number of bytes read. + */ + virtual size_t readBytes(char *buffer, size_t length); + + /** + * @brief Write one byte. + * @return Number of bytes written: 1 on success, 0 on failure. + */ virtual size_t write(uint8_t); + + /** + * @brief Write a buffer of bytes. Blocks until all bytes are sent. + * @param buffer Data to send. + * @param size Number of bytes to send. Must not exceed + * availableForWrite(). + * @return Number of bytes written, or 0 on failure. + */ virtual size_t write(const uint8_t *buffer, size_t size); + + /** + * @brief Wait until all written bytes are sent. Does nothing, because + * write() already blocks until the data is sent. + */ virtual void flush(void); + /** + * @brief Static RX callback registered with the VIRT_UART driver. + * @param huart VIRT_UART handle that received the message. + */ static void rxGenericCallback(VIRT_UART_HandleTypeDef *huart); + + /** + * @brief RX callback for one VirtIOSerial instance. Copies the received + * data into the receive ring buffer. + * @param huart VIRT_UART handle that received the message. + * @note The first message from the Linux host is a dummy, and is + * discarded. + */ void rxCallback(VIRT_UART_HandleTypeDef *huart); using Print::write; // pull in write(str) from Print + + /** + * @brief Check whether the serial port is available. + * @return Always true. + */ operator bool(void) { return true; @@ -73,6 +152,13 @@ class VirtIOSerial : public Stream { private: static uint32_t VirtIOSerial_index; VirtIOSerialObj_t _VirtIOSerialObj; + + /** + * @brief Check if an RPMsg message arrived from the IPCC ISR. + * @note Call this as often as possible to consume the RPMsg ring + * buffers, so that the host processor can send more messages + * quickly. + */ void checkMessageFromISR(void); }; diff --git a/libraries/VirtIO/inc/openamp.h b/libraries/VirtIO/inc/openamp.h index 9e22e17f48..bdb6b57795 100644 --- a/libraries/VirtIO/inc/openamp.h +++ b/libraries/VirtIO/inc/openamp.h @@ -34,14 +34,52 @@ extern "C" { #define OPENAMP_send rpmsg_send #define OPENAMP_destroy_ept rpmsg_destroy_ept +/** + * @brief Initialize the OpenAMP framework. + * @return 0 on success, a negative or error value otherwise. + */ int OPENAMP_Init(void); + +/** + * @brief Deinitialize the OpenAMP framework. + */ void OPENAMP_DeInit(void); +/** + * @brief Create and register a name service endpoint. + * @param ept Virtio rpmsg endpoint to initialize. + * @param name Virtio rpmsg name service name. + * @param dest Message destination address. Set RPMSG_ADDR_ANY if the host + * processor decides it. + * @param cb Virtio rpmsg endpoint callback (receive). + * @param unbind_cb Virtio rpmsg endpoint destroy callback. + * @return 0 on success, a negative or error value otherwise. + */ int OPENAMP_create_endpoint(struct rpmsg_endpoint *ept, const char *name, uint32_t dest, rpmsg_ept_cb cb, rpmsg_ns_unbind_cb unbind_cb); + +/** + * @brief Check and process any received messages from the tx channel. + * @note Do not call this from an ISR. + */ void OPENAMP_check_for_tx_message(void); + +/** + * @brief Check and process any received messages from the rx channel. + * @note Do not call this from an ISR. + */ void OPENAMP_check_for_rx_message(void); + +/** + * @brief Wait until an rpmsg endpoint (VirtIOSerial) is ready to send. + * Readiness is reached when the destination address is known. + * @note Blocks until the first message arrives from the Linux host. + * Sending an rpmsg message before that fails. + * @note Do not call this from an ISR. + * @see VirtIOSerial::rxCallback + * @param rp_ept Virtio rpmsg endpoint to wait for. + */ void OPENAMP_Wait_EndPointready(struct rpmsg_endpoint *rp_ept); #ifdef __cplusplus diff --git a/libraries/VirtIO/inc/virtio_buffer.h b/libraries/VirtIO/inc/virtio_buffer.h index d88f83810c..b19b107b69 100644 --- a/libraries/VirtIO/inc/virtio_buffer.h +++ b/libraries/VirtIO/inc/virtio_buffer.h @@ -50,13 +50,56 @@ typedef struct { volatile uint16_t read_index; } virtio_buffer_t; +/** + * @brief Initialize a virtio ring buffer to empty. + * @param ring Pointer to the ring buffer to initialize. + */ void virtio_buffer_init(virtio_buffer_t *ring); +/** + * @brief Get the number of bytes available to read. + * @param ring Pointer to the ring buffer. + * @return Number of bytes that virtio_buffer_read() can return. + */ uint16_t virtio_buffer_read_available(virtio_buffer_t *ring); + +/** + * @brief Read and remove bytes from the ring buffer. + * @param ring Pointer to the ring buffer. + * @param dst Destination buffer. + * @param size Maximum number of bytes to read. + * @return Number of bytes actually read, at most size. + * @note Not protected against race conditions on read_index. Do not use + * concurrently from an interrupt and the main loop. + */ uint16_t virtio_buffer_read(virtio_buffer_t *ring, uint8_t *dst, uint16_t size); + +/** + * @brief Copy bytes from the ring buffer without removing them. + * @param ring Pointer to the ring buffer. + * @param dst Destination buffer. + * @param size Maximum number of bytes to copy. + * @return Number of bytes actually copied, at most size. + */ uint16_t virtio_buffer_peek(virtio_buffer_t *ring, uint8_t *dst, uint16_t size); +/** + * @brief Get the number of bytes that can be written. + * @param ring Pointer to the ring buffer. + * @return Number of free bytes. One byte is always kept unused to tell a + * full buffer from an empty one. + */ uint16_t virtio_buffer_write_available(virtio_buffer_t *ring); + +/** + * @brief Write bytes into the ring buffer. + * @param ring Pointer to the ring buffer. + * @param src Source data. + * @param size Maximum number of bytes to write. + * @return Number of bytes actually written, at most size. + * @note Not protected against race conditions on write_index. Do not use + * concurrently from an interrupt and the main loop. + */ uint16_t virtio_buffer_write(virtio_buffer_t *ring, uint8_t *src, uint16_t size); #ifdef __cplusplus diff --git a/libraries/VirtIO/inc/virtio_log.h b/libraries/VirtIO/inc/virtio_log.h index 6c29c1ae6a..2b2882678e 100644 --- a/libraries/VirtIO/inc/virtio_log.h +++ b/libraries/VirtIO/inc/virtio_log.h @@ -37,8 +37,8 @@ extern "C" { * @note When the buffer overflows (2kb by default, configurable.), * the buffer is cleaned by a null character. Consider increasing * VIRTIO_LOG_BUFFER_SIZE if a larger log buffer is needed. - * @param data: Data to send - * @param size: size of data + * @param data Data to send. + * @param size Size of data, in bytes. */ void virtio_log(uint8_t *data, uint32_t size); diff --git a/libraries/VirtIO/src/VirtIOSerial.cpp b/libraries/VirtIO/src/VirtIOSerial.cpp index ed7592d59d..6dce15e3cf 100644 --- a/libraries/VirtIO/src/VirtIOSerial.cpp +++ b/libraries/VirtIO/src/VirtIOSerial.cpp @@ -141,6 +141,8 @@ size_t VirtIOSerial::write(uint8_t ch) return write(&ch, 1); } +// Warning: Currently VirtIOSerial implementation is synchronous, blocking +// until all bytes are sent. But it will be fast enough. // Warning: Currently VirtIOSerial implementation is synchronous, blocking // until all bytes are sent. But it will be fast enough. size_t VirtIOSerial::write(const uint8_t *buffer, size_t size) @@ -166,9 +168,7 @@ void VirtIOSerial::flush(void) } /** - * @brief Check if RPMsg message arrived from IPCC ISR - * @note This should called as mush as possible to consume RPMsg ring buffers, - * so that the host processor can send more messages quickly. + * @brief Check if an RPMsg message arrived from the IPCC ISR. */ void VirtIOSerial::checkMessageFromISR(void) { @@ -205,8 +205,13 @@ void VirtIOSerial::rxCallback(VIRT_UART_HandleTypeDef *huart) } } -/* Aim of the function is to get _VirtIOSerialObj pointer using huart pointer */ -/* Highly inspired from magical linux kernel's "container_of" */ +/** + * @brief Get the VirtIOSerial object from a VIRT_UART handle. + * @note Uses the same offset trick as the Linux kernel's container_of() + * macro, to go from the handle field back to the enclosing object. + * @param huart VIRT_UART handle. + * @return Pointer to the enclosing VirtIOSerialObj_t. + */ VirtIOSerialObj_t *get_VirtIOSerial_obj(VIRT_UART_HandleTypeDef *huart) { VirtIOSerialObj_t *obj; diff --git a/libraries/VirtIO/src/mbox_ipcc.c b/libraries/VirtIO/src/mbox_ipcc.c index cb55eaea86..bad424dba6 100644 --- a/libraries/VirtIO/src/mbox_ipcc.c +++ b/libraries/VirtIO/src/mbox_ipcc.c @@ -59,11 +59,6 @@ mbox_status_t msg_received_ch2 = MBOX_NO_MSG; void IPCC_channel1_callback(IPCC_HandleTypeDef *hipcc, uint32_t ChannelIndex, IPCC_CHANNELDirTypeDef ChannelDir); void IPCC_channel2_callback(IPCC_HandleTypeDef *hipcc, uint32_t ChannelIndex, IPCC_CHANNELDirTypeDef ChannelDir); -/** - * @brief Initialize MAILBOX with IPCC peripheral - * @param None - * @retval : Operation result - */ int MAILBOX_Init(void) { __HAL_RCC_IPCC_CLK_ENABLE(); @@ -90,12 +85,6 @@ int MAILBOX_Init(void) return 0; } -/** - * @brief Process vring messages received from IPCC ISR - * @param vdev: virtio device - * @param vring_id: Vring ID - * @retval : Operation result - */ int MAILBOX_Poll(struct virtio_device *vdev, uint32_t vring_id) { int ret = -1; @@ -127,13 +116,6 @@ int MAILBOX_Poll(struct virtio_device *vdev, uint32_t vring_id) return ret; } -/** - * @brief Callback function called by OpenAMP MW to notify message processing (aka. kick) - * @note This callback is called by virtqueue_kick() in rpmsg_virtio_send_offchannel_raw(). - * Therefore, it is only called while tx, but not rx. - * @param Vring id - * @retval Operation result - */ int MAILBOX_Notify(void *priv, uint32_t vring_id) { (void)priv; @@ -163,7 +145,13 @@ int MAILBOX_Notify(void *priv, uint32_t vring_id) } /* Private function ---------------------------------------------------------*/ -/* Callback from IPCC Interrupt Handler: Master Processor informs that there are some free buffers */ +/** + * @brief IPCC channel 1 RX callback: the master processor reports that + * free buffers are available. + * @param hipcc IPCC handle. + * @param ChannelIndex IPCC channel index. + * @param ChannelDir Channel direction. Not used. + */ void IPCC_channel1_callback(IPCC_HandleTypeDef *hipcc, uint32_t ChannelIndex, IPCC_CHANNELDirTypeDef ChannelDir) { @@ -174,7 +162,13 @@ void IPCC_channel1_callback(IPCC_HandleTypeDef *hipcc, HAL_IPCC_NotifyCPU(hipcc, ChannelIndex, IPCC_CHANNEL_DIR_RX); } -/* Callback from IPCC Interrupt Handler: new message received from Master Processor */ +/** + * @brief IPCC channel 2 RX callback: the master processor reports a new + * message. + * @param hipcc IPCC handle. + * @param ChannelIndex IPCC channel index. + * @param ChannelDir Channel direction. Not used. + */ void IPCC_channel2_callback(IPCC_HandleTypeDef *hipcc, uint32_t ChannelIndex, IPCC_CHANNELDirTypeDef ChannelDir) { diff --git a/libraries/VirtIO/src/mbox_ipcc.h b/libraries/VirtIO/src/mbox_ipcc.h index 3d507bb695..7e9c48f711 100644 --- a/libraries/VirtIO/src/mbox_ipcc.h +++ b/libraries/VirtIO/src/mbox_ipcc.h @@ -30,9 +30,28 @@ #define IPCC_IRQ_SUBPRIO 0 #endif + /** + * @brief Initialize the mailbox with the IPCC peripheral. + * @return 0 on success, -1 on failure. + */ int MAILBOX_Init(void); + + /** + * @brief Process vring messages received from the IPCC ISR. + * @param vdev Virtio device. + * @param vring_id Vring ID. + * @return 0 if a message was processed, -1 otherwise. + */ int MAILBOX_Poll(struct virtio_device *vdev, uint32_t vring_id); - int MAILBOX_Notify(void *priv, uint32_t id); + + /** + * @brief Notify the remote processor (kick) that a message is ready. + * @note Called by OpenAMP from virtqueue_kick() during tx only, never rx. + * @param priv Private data passed by OpenAMP. Unused. + * @param vring_id Vring ID. + * @return 0 on success, -1 otherwise. + */ + int MAILBOX_Notify(void *priv, uint32_t vring_id); #endif /* VIRTIOCON */ #endif /* __OPENAMP_MBOX_IPCC_H */ diff --git a/libraries/VirtIO/src/openamp.c b/libraries/VirtIO/src/openamp.c index 8055a552d6..89a4788d22 100644 --- a/libraries/VirtIO/src/openamp.c +++ b/libraries/VirtIO/src/openamp.c @@ -57,7 +57,7 @@ struct metal_device shm_device = { * @brief Initialize OpenAMP shared memory (libmetal and resource table) * * @param RPMsgRole: RPMSG_REMOTE - Device is remote (slave) - * @retval 0 on success + * @return 0 on success */ static int OPENAMP_shmem_init(int RPMsgRole) { @@ -106,11 +106,6 @@ static int OPENAMP_shmem_init(int RPMsgRole) return 0; } -/** - * @brief Initialize the openamp framework - * - * @retval 0 when success - */ int OPENAMP_Init() { struct fw_rsc_vdev_vring *vring_rsc = NULL; @@ -154,9 +149,6 @@ int OPENAMP_Init() return 0; } -/** - * @brief Deinitialize the openamp framework - */ void OPENAMP_DeInit() { rpmsg_deinit_vdev(&rvdev); @@ -164,17 +156,6 @@ void OPENAMP_DeInit() metal_finish(); } -/** - * @brief Create and register the name service endpoint - * - * @param ept: virtio rpmsg endpoint - * @param name: virtio rpmsg name service name - * @param dest: message destination address. Set RPMSG_ADDR_ANY if - * the host processor will decide this - * @param cb: virtio rpmsg endpoint callback (receive) - * @param unbind_cb: virtio rpmsg endpoint destroy callback - * @retval 0 when success - */ int OPENAMP_create_endpoint(struct rpmsg_endpoint *ept, const char *name, uint32_t dest, rpmsg_ept_cb cb, rpmsg_ns_unbind_cb unbind_cb) @@ -183,33 +164,16 @@ int OPENAMP_create_endpoint(struct rpmsg_endpoint *ept, const char *name, unbind_cb); } -/** - * @brief Check and process any received messages from tx channel - * @note Don't call this in an ISR. - */ void OPENAMP_check_for_tx_message(void) { MAILBOX_Poll(rvdev.vdev, VRING0_ID); } -/** - * @brief Check and process any received messages from rx channel - * @note Don't call this in an ISR. - */ void OPENAMP_check_for_rx_message(void) { MAILBOX_Poll(rvdev.vdev, VRING1_ID); } -/** - * @brief Wait loop on rpmsg endpoint (VirtIOSerial) ready to send a message. - * (until message dest address is known) - * @note This will wait until the first message arrives from the Linux host. - * If we send a rpmsg message before this it will fail. - * @note Don't call this in an ISR. - * @see VirtIOSerial::rxCallback - * @param rp_ept: virtio rpmsg endpoint - */ void OPENAMP_Wait_EndPointready(struct rpmsg_endpoint *rp_ept) { while (!is_rpmsg_ept_ready(rp_ept)) { diff --git a/libraries/VirtIO/src/rsc_table.h b/libraries/VirtIO/src/rsc_table.h index 3979dc15f3..b25c81034b 100644 --- a/libraries/VirtIO/src/rsc_table.h +++ b/libraries/VirtIO/src/rsc_table.h @@ -36,6 +36,12 @@ struct shared_resource_table { struct fw_rsc_trace cm_trace; }; +/** + * @brief Initialize the resource table used by the remote processor. + * @param RPMsgRole Role of the processor. Not used. + * @param table_ptr Output: pointer to the resource table. + * @param length Output: size of the resource table, in bytes. + */ void resource_table_init(int RPMsgRole, void **table_ptr, int *length); #endif /* VIRTIOCON */ diff --git a/libraries/VirtIO/src/virtio_buffer.c b/libraries/VirtIO/src/virtio_buffer.c index cf8e90b7f2..4e435996ab 100644 --- a/libraries/VirtIO/src/virtio_buffer.c +++ b/libraries/VirtIO/src/virtio_buffer.c @@ -43,6 +43,14 @@ uint16_t virtio_buffer_read_available(virtio_buffer_t *ring) return delta; } +/** + * @brief Read or peek bytes from the ring buffer. + * @param ring Pointer to the ring buffer. + * @param dst Destination buffer. + * @param size Maximum number of bytes to read. + * @param peek If true, read_index is not advanced. + * @return Number of bytes copied, at most size. + */ /* WARNING no protection against race condition (on ring->read_index) when used in interruption */ static uint16_t read(virtio_buffer_t *ring, uint8_t *dst, uint16_t size, bool peek) { @@ -99,7 +107,6 @@ uint16_t virtio_buffer_write_available(virtio_buffer_t *ring) return delta; } -/* WARNING no protection against race condition (on ring->write_index) when used in interruption */ uint16_t virtio_buffer_write(virtio_buffer_t *ring, uint8_t *src, uint16_t size) { uint16_t write_index = ring->write_index; diff --git a/libraries/Wire/src/Wire.cpp b/libraries/Wire/src/Wire.cpp index 2802f53a1c..d4abf3d7b1 100644 --- a/libraries/Wire/src/Wire.cpp +++ b/libraries/Wire/src/Wire.cpp @@ -45,10 +45,6 @@ TwoWire::TwoWire(pin_size_t sda, pin_size_t scl) rxBufferAllocated = 0; } -/** - * @brief TwoWire destructor - * @retval None - */ TwoWire::~TwoWire() { end(); @@ -215,19 +211,6 @@ void TwoWire::beginTransmission(int address) beginTransmission((uint8_t)address); } -// -// Originally, 'endTransmission' was an f(void) function. -// It has been modified to take one parameter indicating -// whether or not a STOP should be performed on the bus. -// Calling endTransmission(false) allows a sketch to -// perform a repeated start. -// -// WARNING: Nothing in the library keeps track of whether -// the bus tenure has been properly ended with a STOP. It -// is very possible to leave the bus in a hung state if -// no call to endTransmission(true) is made. Some I2C -// devices will behave oddly if they do not see a STOP. -// uint8_t TwoWire::endTransmission(bool stopBit) { #if !defined(I2C_OTHER_FRAME) @@ -285,17 +268,11 @@ uint8_t TwoWire::endTransmission(bool stopBit) return ret; } -// This provides backwards compatibility with the original -// definition, and expected behaviour, of endTransmission -// uint8_t TwoWire::endTransmission(void) { return endTransmission(true); } -// must be called in: -// slave tx event callback -// or after beginTransmission(address) size_t TwoWire::write(uint8_t data) { size_t ret = 1; @@ -319,13 +296,6 @@ size_t TwoWire::write(uint8_t data) return ret; } -/** - * @brief This function must be called in slave Tx event callback or after - * beginTransmission() and before endTransmission(). - * @param pdata: pointer to the buffer data - * @param quantity: number of bytes to write - * @retval number of bytes ready to write. - */ size_t TwoWire::write(const uint8_t *data, size_t quantity) { size_t ret = quantity; @@ -351,17 +321,11 @@ size_t TwoWire::write(const uint8_t *data, size_t quantity) return ret; } -// must be called in: -// slave rx event callback -// or after requestFrom(address, numBytes) int TwoWire::available(void) { return rxBufferLength - rxBufferIndex; } -// must be called in: -// slave rx event callback -// or after requestFrom(address, numBytes) int TwoWire::read(void) { int value = -1; @@ -381,9 +345,6 @@ int TwoWire::read(void) return value; } -// must be called in: -// slave rx event callback -// or after requestFrom(address, numBytes) int TwoWire::peek(void) { int value = -1; @@ -403,7 +364,6 @@ void TwoWire::flush(void) resetTxBuffer(); } -// behind the scenes function that is called when data is received void TwoWire::onReceiveService(i2c_t *obj) { uint8_t *inBytes = (uint8_t *) obj->i2cTxRxBuffer; @@ -431,7 +391,6 @@ void TwoWire::onReceiveService(i2c_t *obj) } } -// behind the scenes function that is called when data is requested void TwoWire::onRequestService(i2c_t *obj) { TwoWire *TW = (TwoWire *)(obj->__this); @@ -446,7 +405,6 @@ void TwoWire::onRequestService(i2c_t *obj) } } -// sets function called on slave write void TwoWire::onReceive(cb_function_receive_t function) { user_onReceive = function; @@ -457,7 +415,6 @@ void TwoWire::onReceive(void(*function)(int)) user_onReceive = function; } -// sets function called on slave read void TwoWire::onRequest(cb_function_request_t function) { user_onRequest = function; @@ -468,11 +425,6 @@ void TwoWire::onRequest(void(*function)(void)) user_onRequest = function; } -/** - * @brief Allocate the Rx/Tx buffer to the requested length if needed - * @note Minimum allocated size is BUFFER_LENGTH) - * @param length: number of bytes to allocate - */ void TwoWire::allocateRxBuffer(size_t length) { if (rxBufferAllocated < length) { @@ -511,9 +463,6 @@ inline size_t TwoWire::allocateTxBuffer(size_t length) return ret; } -/** - * @brief Reset Rx/Tx buffer content to 0 - */ inline void TwoWire::resetRxBuffer(void) { if (rxBuffer != nullptr) { @@ -528,9 +477,7 @@ inline void TwoWire::resetTxBuffer(void) } } -// Send clear bus (clock pulse) sequence to recover bus. -// Useful in case of bus stuck after a reset for example -// a mix implementation of Clear Bus from +// Implementation based on the clear bus sequence from // https://www.nxp.com/docs/en/user-guide/UM10204.pdf // https://bits4device.wordpress.com/2017/07/28/i2c-bus-recovery/ void TwoWire::recoverBus(void) diff --git a/libraries/Wire/src/Wire.h b/libraries/Wire/src/Wire.h index ed4fb2b3a2..9adbad261f 100644 --- a/libraries/Wire/src/Wire.h +++ b/libraries/Wire/src/Wire.h @@ -41,9 +41,14 @@ extern "C" { // WIRE_HAS_END means Wire has end() #define WIRE_HAS_END 1 +/** + * @brief TWI/I2C (Wire) controller, usable as master or slave. + */ class TwoWire : public arduino::HardwareI2C { public: + /** @brief Callback type for slave receive events, called with the number of bytes received. */ typedef std::function cb_function_receive_t; + /** @brief Callback type for slave request events. */ typedef std::function cb_function_request_t; private: @@ -65,91 +70,309 @@ class TwoWire : public arduino::HardwareI2C { std::function user_onReceive; std::function user_onRequest; - static void onRequestService(i2c_t *); - static void onReceiveService(i2c_t *); + /** + * @brief Behind the scenes function called when a slave request event occurs. Calls the user onRequest callback. + * @param obj Pointer to the I2C instance of the event. + */ + static void onRequestService(i2c_t *obj); + /** + * @brief Behind the scenes function called when a slave receive event occurs. Copies the received data and calls the user onReceive callback. + * @param obj Pointer to the I2C instance of the event. + */ + static void onReceiveService(i2c_t *obj); + /** + * @brief Allocate the Rx buffer to the requested length if needed. + * @note Minimum allocated size is BUFFER_LENGTH. + * @param length Number of bytes to allocate. + */ void allocateRxBuffer(size_t length); + /** + * @brief Allocate the Tx buffer to the requested length if needed. + * @note Minimum allocated size is BUFFER_LENGTH. + * @param length Number of bytes to allocate. + * @return Number of bytes that can be stored in the Tx buffer, 0 if length is greater than WIRE_MAX_TX_BUFF_LENGTH. + */ size_t allocateTxBuffer(size_t length); + /** + * @brief Reset the Rx buffer content to 0. + */ void resetRxBuffer(void); + /** + * @brief Reset the Tx buffer content to 0. + */ void resetTxBuffer(void); + /** + * @brief Send a clear bus (clock pulse) sequence to recover the bus. + * + * Useful if the bus is stuck after a reset. Called by begin() in master mode. + */ void recoverBus(void); public: + // setSCL/SDA have to be called before begin() + /** + * @brief Construct a TwoWire instance using the given pins. + * @param sda Pin used for SDA. Default: SDA. + * @param scl Pin used for SCL. Default: SCL. + */ TwoWire(pin_size_t sda = SDA, pin_size_t scl = SCL); + /** + * @brief Destroy the instance, stopping the TWI interface and releasing its buffers (calls end()). + */ ~TwoWire(); - // setSCL/SDA have to be called before begin() + /** + * @brief Set the SCL pin. Must be called before begin(). + * @param scl Pin used for SCL. + */ void setSCL(pin_size_t scl) { _i2c.scl = digitalPinToPinName(scl); }; + /** + * @brief Set the SDA pin. Must be called before begin(). + * @param sda Pin used for SDA. + */ void setSDA(pin_size_t sda) { _i2c.sda = digitalPinToPinName(sda); }; + /** + * @brief Set the SCL pin. Must be called before begin(). + * @param scl PinName used for SCL. + */ void setSCL(PinName scl) { _i2c.scl = scl; }; + /** + * @brief Set the SDA pin. Must be called before begin(). + * @param sda PinName used for SDA. + */ void setSDA(PinName sda) { _i2c.sda = sda; }; + /** + * @brief Initialize the TWI interface as master. + * @param generalCall true to enable the general call address. Default: false. + */ void begin(bool generalCall); - void begin(pin_size_t, pin_size_t); - void begin(uint8_t, bool generalCall = false, bool NoStretchMode = false); - void begin(int, bool generalCall = false, bool NoStretchMode = false); + /** + * @brief Initialize the TWI interface as master using the given pins. + * @param sda Pin used for SDA. + * @param scl Pin used for SCL. + */ + void begin(pin_size_t sda, pin_size_t scl); + /** + * @brief Initialize the TWI interface as master or slave. + * + * The reserved address 0x01 initializes the interface as master, + * any other address initializes it as slave using this address. + * @param address 7-bit own address for slave mode, 0x01 for master mode. + * @param generalCall true to enable the general call address. Default: false. + * @param NoStretchMode true to disable clock stretching. Default: false. + */ + void begin(uint8_t address, bool generalCall = false, bool NoStretchMode = false); + /** + * @brief Initialize the TWI interface as master or slave. + * + * The reserved address 0x01 initializes the interface as master, + * any other address initializes it as slave using this address. + * @param address 7-bit own address for slave mode, 0x01 for master mode. + * @param generalCall true to enable the general call address. Default: false. + * @param NoStretchMode true to disable clock stretching. Default: false. + */ + void begin(int address, bool generalCall = false, bool NoStretchMode = false); + /** + * @brief Initialize the TWI interface as master with the default pins. + */ void begin() override { begin(false); } + /** + * @brief Initialize the TWI interface as master or slave with the default pins. + * @param address 7-bit own address for slave mode, 0x01 for master mode. + */ void begin(uint8_t address) override { begin(address, false, false); } + /** + * @brief Stop the TWI interface and free the Rx and Tx buffers. + */ void end() override; + /** + * @brief Set the TWI clock frequency. + * @param freq Clock frequency in Hz. + */ void setClock(uint32_t freq) override; + /** + * @brief Begin a transmission to a slave device. Data is stored with write() and sent by endTransmission(). + * @param address 7-bit address of the slave device. + */ void beginTransmission(uint8_t address) override; - void beginTransmission(int); + /** + * @brief Begin a transmission to a slave device. Data is stored with write() and sent by endTransmission(). + * @param address 7-bit address of the slave device. + */ + void beginTransmission(int address); + /** + * @brief Send the buffered data to the slave device, ending with a STOP. + * + * Equivalent to endTransmission(true). + * @return 0: success, 1: data too long, 2: NACK on address, 3: NACK on data, 4: other error. + */ uint8_t endTransmission(void) override; + /** + * @brief Send the buffered data to the slave device and end the transmission. + * + * Calling endTransmission(false) allows a repeated start. + * @warning Nothing keeps track of whether the bus tenure has been ended with a STOP. + * Leaving the bus without a STOP can hang it, and some I2C devices misbehave without a STOP. + * @param stopBit true to send a STOP at the end of the transmission, false to keep the bus for a repeated start. + * @return 0: success, 1: data too long, 2: NACK on address, 3: NACK on data, 4: other error. + */ uint8_t endTransmission(bool stopBit) override; + /** + * @brief Request bytes from a slave device. + * @param address 7-bit address of the slave device. + * @param len Number of bytes to request. + * @param stopBit true to send a STOP after the request, false to keep the bus for a repeated start. + * @return Number of bytes read, 0 on error. Read them with available() and read(). + */ size_t requestFrom(uint8_t address, size_t len, bool stopBit) override; + /** + * @brief Request bytes from a slave device, sending a STOP after the request. + * @param address 7-bit address of the slave device. + * @param len Number of bytes to request. + * @return Number of bytes read, 0 on error. Read them with available() and read(). + */ size_t requestFrom(uint8_t address, size_t len) override; + /** + * @brief Request bytes from a slave device after writing an internal register address. + * + * This allows a repeated start to access the internal registers of a device. + * @param address 7-bit address of the slave device. + * @param len Number of bytes to request. + * @param iaddress Internal register address to write before the request. + * @param isize Size in bytes of the internal address (most significant byte first), limited to 3. + * @param stopBit true to send a STOP after the request, false to keep the bus for a repeated start. + * @return Number of bytes read, 0 on error. Read them with available() and read(). + */ size_t requestFrom(uint8_t address, size_t len, uint32_t iaddress, uint8_t isize, bool stopBit); - size_t write(uint8_t) override; - size_t write(const uint8_t *, size_t) override; + /** + * @brief Write a byte. + * + * In master transmitter mode the byte is stored in the Tx buffer, in slave mode it is sent to the master. + * Must be called in the slave tx event callback or after beginTransmission() and before endTransmission(). + * @param data Byte to write. + * @return Number of bytes ready to write: 1 on success, 0 on error. + */ + size_t write(uint8_t data) override; + /** + * @brief Write bytes. + * + * Must be called in the slave tx event callback or after beginTransmission() and before endTransmission(). + * @param data Pointer to the buffer data. + * @param quantity Number of bytes to write. + * @return Number of bytes ready to write. + */ + size_t write(const uint8_t *data, size_t quantity) override; + /** + * @brief Get the number of bytes available for reading from the Rx buffer. + * + * Must be called in the slave rx event callback or after requestFrom(). + * @return Number of bytes available. + */ int available(void) override; + /** + * @brief Read a byte from the Rx buffer. + * + * Must be called in the slave rx event callback or after requestFrom(). + * @return Next byte, -1 if no data is available. + */ int read(void) override; + /** + * @brief Read the next byte from the Rx buffer without consuming it. + * + * Must be called in the slave rx event callback or after requestFrom(). + * @return Next byte, -1 if no data is available. + */ int peek(void) override; + /** + * @brief Discard the content of the Rx and Tx buffers. + */ void flush(void) override; - void onReceive(cb_function_receive_t callback); + /** + * @brief Register the function called when a slave receives data from a master. + * @param function Function called with the number of bytes received. + */ + void onReceive(cb_function_receive_t function); + /** + * @brief Register the function called when a slave receives data from a master. + * @param function Function called with the number of bytes received. + */ void onReceive(void (*)(int)) override; - void onRequest(cb_function_request_t callback); + /** + * @brief Register the function called when a master requests data from this slave. + * @param function Function called on request. + */ + void onRequest(cb_function_request_t function); + /** + * @brief Register the function called when a master requests data from this slave. + * @param function Function called on request. + */ void onRequest(void (*)(void)) override; + /** + * @brief Write a value as a single byte. + * @param n Value to write, truncated to a byte. + * @return Number of bytes written. + */ inline size_t write(unsigned long n) { return write((uint8_t)n); } + /** + * @brief Write a value as a single byte. + * @param n Value to write, truncated to a byte. + * @return Number of bytes written. + */ inline size_t write(long n) { return write((uint8_t)n); } + /** + * @brief Write a value as a single byte. + * @param n Value to write, truncated to a byte. + * @return Number of bytes written. + */ inline size_t write(unsigned int n) { return write((uint8_t)n); } + /** + * @brief Write a value as a single byte. + * @param n Value to write, truncated to a byte. + * @return Number of bytes written. + */ inline size_t write(int n) { return write((uint8_t)n); } using Print::write; - // Could be used to mix Arduino API and STM32Cube HAL API (ex: DMA). Use at your own risk. + /** + * @brief Get the I2C handle, to mix the Arduino API and the STM32Cube HAL API (e.g. DMA). Use at your own risk. + * @return Pointer to the I2C handle. + */ #if defined(USE_HALV2_DRIVER) hal_i2c_handle_t *getHandle(void) #else diff --git a/libraries/Wire/src/utility/twi.c b/libraries/Wire/src/utility/twi.c index 86490841d0..b59eae20f9 100644 --- a/libraries/Wire/src/utility/twi.c +++ b/libraries/Wire/src/utility/twi.c @@ -194,7 +194,7 @@ static I2C_HandleTypeDef *i2c_handles[I2C_NUM]; /** * @brief This function return the I2C clock source frequency. * @param i2c: I2C instance - * @retval frequency in Hz + * @return frequency in Hz */ static uint32_t i2c_getClkFreq(I2C_TypeDef *i2c) { @@ -537,7 +537,7 @@ static uint32_t i2c_getClkFreq(I2C_TypeDef *i2c) * @brief Calculate PRESC, SCLDEL, SDADEL, SCLL and SCLH and find best configuration. * @param clkSrcFreq I2C source clock in HZ. * @param i2c_speed I2C frequency (index). -* @retval config index (0 to I2C_VALID_TIMING_NBR], 0xFFFFFFFF for no +* @return config index (0 to I2C_VALID_TIMING_NBR], 0xFFFFFFFF for no valid config. */ static uint32_t i2c_computeTiming(uint32_t clkSrcFreq, uint32_t i2c_speed) @@ -674,7 +674,7 @@ required I2C clock. * @param obj : pointer to i2c_t structure * @param frequency Required I2C clock in Hz. -* @retval I2C timing or 0 in case of error. +* @return I2C timing or 0 in case of error. */ static uint32_t i2c_getTiming(i2c_t *obj, uint32_t frequency) { @@ -734,13 +734,6 @@ static uint32_t i2c_getTiming(i2c_t *obj, uint32_t frequency) return ret; } -/** - * @brief Initialize and setup GPIO and I2C peripheral - * @param obj : pointer to i2c_t structure - * @param timing : one of the i2c_timing_e - * @param ownAddress : device address - * @retval none - */ void i2c_init(i2c_t *obj, uint32_t timing, uint32_t ownAddress) { if (obj != NULL) { @@ -927,11 +920,6 @@ void i2c_init(i2c_t *obj, uint32_t timing, uint32_t ownAddress) } } -/** - * @brief Initialize and setup GPIO and I2C peripheral - * @param obj : pointer to i2c_t structure - * @retval none - */ void i2c_deinit(i2c_t *obj) { #if defined(USE_HALV2_DRIVER) @@ -1003,12 +991,6 @@ void i2c_deinit(i2c_t *obj) #endif // I2C6_BASE } -/** - * @brief Setup transmission speed. I2C must be configured before. - * @param obj : pointer to i2c_t structure - * @param frequency : i2c transmission speed - * @retval none - */ void i2c_setTiming(i2c_t *obj, uint32_t frequency) { uint32_t f = i2c_getTiming(obj, frequency); @@ -1033,14 +1015,6 @@ void i2c_setTiming(i2c_t *obj, uint32_t frequency) LL_I2C_Enable(obj->i2c); } -/** - * @brief Write bytes at a given address - * @param obj : pointer to i2c_t structure - * @param dev_address: specifies the address of the device. - * @param data: pointer to data to be write - * @param size: number of bytes to be write. - * @retval read status - */ i2c_status_e i2c_master_write(i2c_t *obj, uint8_t dev_address, uint8_t *data, uint16_t size) @@ -1144,13 +1118,6 @@ i2c_status_e i2c_master_write(i2c_t *obj, uint8_t dev_address, return ret; } -/** - * @brief Write bytes to master - * @param obj : pointer to i2c_t structure - * @param data: pointer to data to be write - * @param size: number of bytes to be write. - * @retval status - */ i2c_status_e i2c_slave_write_IT(i2c_t *obj, uint8_t *data, uint16_t size) { uint8_t i = 0; @@ -1170,14 +1137,6 @@ i2c_status_e i2c_slave_write_IT(i2c_t *obj, uint8_t *data, uint16_t size) return ret; } -/** - * @brief read bytes in master mode at a given address - * @param obj : pointer to i2c_t structure - * @param dev_address: specifies the address of the device. - * @param data: pointer to data to be read - * @param size: number of bytes to be read. - * @retval read status - */ i2c_status_e i2c_master_read(i2c_t *obj, uint8_t dev_address, uint8_t *data, uint16_t size) { i2c_status_e ret = I2C_OK; @@ -1273,13 +1232,6 @@ i2c_status_e i2c_master_read(i2c_t *obj, uint8_t dev_address, uint8_t *data, uin return ret; } -/** - * @brief Checks if target device is ready for communication - * @param obj : pointer to i2c_t structure - * @param devAddr: specifies the address of the device. - * @param trials : Number of trials. - * @retval status - */ i2c_status_e i2c_IsDeviceReady(i2c_t *obj, uint8_t devAddr, uint32_t trials) { i2c_status_e ret = I2C_OK; @@ -1321,6 +1273,12 @@ i2c_status_e i2c_IsDeviceReady(i2c_t *obj, uint8_t devAddr, uint32_t trials) /* Aim of the function is to get i2c_s pointer using hi2c pointer */ /* Highly inspired from magical linux kernel's "container_of" */ /* (which was not directly used since not compatible with IAR toolchain) */ +/** + * @brief Get the i2c_t object that embeds a given HAL I2C handle. + * @param hi2c Pointer to the handle member of an i2c_t object (I2C_HandleTypeDef, or hal_i2c_handle_t with USE_HALV2_DRIVER). + * @return Pointer to the i2c_t object that contains hi2c. + * @note The object is recovered by pointer arithmetic (container_of style). hi2c must point to the handle member of a valid i2c_t, otherwise the result is undefined. + */ #if defined(USE_HALV2_DRIVER) i2c_t *get_i2c_obj(hal_i2c_handle_t *hi2c) #else @@ -1336,11 +1294,6 @@ i2c_t *get_i2c_obj(I2C_HandleTypeDef *hi2c) return (obj); } -/** @brief sets function called before a slave read operation - * @param obj : pointer to i2c_t structure - * @param function: callback function to use - * @retval None - */ void i2c_attachSlaveRxEvent(i2c_t *obj, void (*function)(i2c_t *)) { if ((obj != NULL) && (function != NULL)) { @@ -1353,11 +1306,6 @@ void i2c_attachSlaveRxEvent(i2c_t *obj, void (*function)(i2c_t *)) } } -/** @brief sets function called before a slave write operation - * @param obj : pointer to i2c_t structure - * @param function: callback function to use - * @retval None - */ void i2c_attachSlaveTxEvent(i2c_t *obj, void (*function)(i2c_t *)) { if ((obj != NULL) && (function != NULL)) { @@ -1376,7 +1324,6 @@ void i2c_attachSlaveTxEvent(i2c_t *obj, void (*function)(i2c_t *)) * the configuration information for the specified I2C. * @param TransferDirection: Master request Transfer Direction (Write/Read), value of @ref I2C_XferOptions_definition * @param AddrMatchCode: Address Match Code - * @retval None */ #if defined(USE_HALV2_DRIVER) void HAL_I2C_SLAVE_AddrCallback(hal_i2c_handle_t *hi2c, hal_i2c_slave_xfer_direction_t TransferDirection, @@ -1430,7 +1377,6 @@ void HAL_I2C_AddrCallback(I2C_HandleTypeDef *hi2c, uint8_t TransferDirection, ui * @brief Listen Complete callback. * @param hi2c Pointer to a I2C_HandleTypeDef or hal_i2c_handle_t structure that contains * the configuration information for the specified I2C. - * @retval None */ #if defined(USE_HALV2_DRIVER) void HAL_I2C_SLAVE_ListenCpltCallback(hal_i2c_handle_t *hi2c) @@ -1458,7 +1404,6 @@ void HAL_I2C_ListenCpltCallback(I2C_HandleTypeDef *hi2c) * @brief Slave RX complete callback * @param hi2c Pointer to a I2C_HandleTypeDef structure that contains * the configuration information for the specified I2C. - * @retval None */ #if defined(USE_HALV2_DRIVER) void HAL_I2C_SLAVE_RxCpltCallback(hal_i2c_handle_t *hi2c) @@ -1489,7 +1434,6 @@ void HAL_I2C_SlaveRxCpltCallback(I2C_HandleTypeDef *hi2c) * @brief Slave TX complete callback * @param hi2c Pointer to a I2C_HandleTypeDef structure that contains * the configuration information for the specified I2C. - * @retval None */ #if defined(USE_HALV2_DRIVER) void HAL_I2C_SLAVE_TxCpltCallback(hal_i2c_handle_t *hi2c) @@ -1510,7 +1454,6 @@ void HAL_I2C_SlaveTxCpltCallback(I2C_HandleTypeDef *hi2c) * so the error callback forces the slave to listen again. * @param hi2c Pointer to a I2C_HandleTypeDef structure that contains * the configuration information for the specified I2C. - * @retval None */ #if defined(USE_HALV2_DRIVER) void HAL_I2C_ErrorCallback(hal_i2c_handle_t *hi2c) @@ -1533,7 +1476,6 @@ void HAL_I2C_ErrorCallback(I2C_HandleTypeDef *hi2c) /** * @brief This function handles I2C1 interrupt. * @param None -* @retval None */ void I2C1_EV_IRQHandler(void) { @@ -1553,7 +1495,6 @@ void I2C1_EV_IRQHandler(void) /** * @brief This function handles I2C1 error interrupt. * @param None -* @retval None */ void I2C1_ERR_IRQHandler(void) { @@ -1565,7 +1506,6 @@ void I2C1_ERR_IRQHandler(void) /** * @brief This function handles I2C1 error interrupt. * @param None -* @retval None */ void I2C1_ER_IRQHandler(void) { @@ -1579,7 +1519,6 @@ void I2C1_ER_IRQHandler(void) /** * @brief This function handles I2C2 interrupt. * @param None -* @retval None */ void I2C2_EV_IRQHandler(void) { @@ -1621,7 +1560,6 @@ void I2C2_EV_IRQHandler(void) /** * @brief This function handles I2C2 error interrupt. * @param None -* @retval None */ void I2C2_ERR_IRQHandler(void) { @@ -1633,7 +1571,6 @@ void I2C2_ERR_IRQHandler(void) /** * @brief This function handles I2C2 error interrupt. * @param None -* @retval None */ void I2C2_ER_IRQHandler(void) { @@ -1647,7 +1584,6 @@ void I2C2_ER_IRQHandler(void) /** * @brief This function handles I2C3 interrupt. * @param None -* @retval None */ void I2C3_EV_IRQHandler(void) { @@ -1662,7 +1598,6 @@ void I2C3_EV_IRQHandler(void) /** * @brief This function handles I2C3 interrupt. * @param None -* @retval None */ void I2C3_ER_IRQHandler(void) { @@ -1676,7 +1611,6 @@ void I2C3_ER_IRQHandler(void) /** * @brief This function handles I2C4 interrupt. * @param None -* @retval None */ void I2C4_EV_IRQHandler(void) { @@ -1688,7 +1622,6 @@ void I2C4_EV_IRQHandler(void) /** * @brief This function handles I2C4 interrupt. * @param None -* @retval None */ void I2C4_ER_IRQHandler(void) { @@ -1701,7 +1634,6 @@ void I2C4_ER_IRQHandler(void) /** * @brief This function handles I2C5 interrupt. * @param None -* @retval None */ void I2C5_EV_IRQHandler(void) { @@ -1712,7 +1644,6 @@ void I2C5_EV_IRQHandler(void) /** * @brief This function handles I2C5 interrupt. * @param None -* @retval None */ void I2C5_ER_IRQHandler(void) { @@ -1725,7 +1656,6 @@ void I2C5_ER_IRQHandler(void) /** * @brief This function handles I2C6 interrupt. * @param None -* @retval None */ void I2C6_EV_IRQHandler(void) { @@ -1736,7 +1666,6 @@ void I2C6_EV_IRQHandler(void) /** * @brief This function handles I2C6 interrupt. * @param None -* @retval None */ void I2C6_ER_IRQHandler(void) { diff --git a/libraries/Wire/src/utility/twi.h b/libraries/Wire/src/utility/twi.h index c03bb7fd81..a4e4b4deca 100644 --- a/libraries/Wire/src/utility/twi.h +++ b/libraries/Wire/src/utility/twi.h @@ -156,16 +156,73 @@ typedef enum { } i2c_status_e; /* Exported functions ------------------------------------------------------- */ +/** + * @brief Initialize and set up the GPIO pins and the I2C peripheral. + * @param obj Pointer to the i2c_t structure. + * @param timing I2C clock frequency in Hz. + * @param ownAddress Own address already shifted left by 1 (7-bit address << 1). + */ void i2c_init(i2c_t *obj, uint32_t timing, uint32_t ownAddress); +/** + * @brief Deinitialize the GPIO pins and the I2C peripheral. + * @param obj Pointer to the i2c_t structure. + */ void i2c_deinit(i2c_t *obj); +/** + * @brief Set the transmission speed. The I2C peripheral must be initialized before. + * @param obj Pointer to the i2c_t structure. + * @param frequency I2C transmission speed in Hz. + */ void i2c_setTiming(i2c_t *obj, uint32_t frequency); +/** + * @brief Write bytes to a device at a given address. + * + * A size of 0 checks whether the device is ready (scan / ping) instead of writing. + * @param obj Pointer to the i2c_t structure. + * @param dev_address 7-bit address of the device. + * @param data Pointer to the data to write. + * @param size Number of bytes to write. + * @return I2C_OK on success, otherwise the i2c_status_e error code. + */ i2c_status_e i2c_master_write(i2c_t *obj, uint8_t dev_address, uint8_t *data, uint16_t size); +/** + * @brief Buffer bytes to send to the master in slave transmit mode. + * @param obj Pointer to the i2c_t structure. + * @param data Pointer to the data to buffer. + * @param size Number of bytes to buffer, at most I2C_TXRX_BUFFER_SIZE. + * @return I2C_OK on success, I2C_DATA_TOO_LONG if size exceeds I2C_TXRX_BUFFER_SIZE. + */ i2c_status_e i2c_slave_write_IT(i2c_t *obj, uint8_t *data, uint16_t size); +/** + * @brief Read bytes from a device at a given address in master mode. + * @param obj Pointer to the i2c_t structure. + * @param dev_address 7-bit address of the device. + * @param data Pointer to the buffer receiving the data. + * @param size Number of bytes to read. + * @return I2C_OK on success, otherwise the i2c_status_e error code. + */ i2c_status_e i2c_master_read(i2c_t *obj, uint8_t dev_address, uint8_t *data, uint16_t size); +/** + * @brief Check whether the target device is ready for communication. + * @param obj Pointer to the i2c_t structure. + * @param devAddr 7-bit address of the device. + * @param trials Number of trials. + * @return I2C_OK if the device is ready, I2C_NACK_ADDR if it does not answer, otherwise the i2c_status_e error code. + */ i2c_status_e i2c_IsDeviceReady(i2c_t *obj, uint8_t devAddr, uint32_t trials); +/** + * @brief Set the function called when the slave receives data from a master. + * @param obj Pointer to the i2c_t structure. + * @param function Callback function to use, called with the i2c_t structure. + */ void i2c_attachSlaveRxEvent(i2c_t *obj, void (*function)(i2c_t *)); +/** + * @brief Set the function called when a master requests data from the slave. + * @param obj Pointer to the i2c_t structure. + * @param function Callback function to use, called with the i2c_t structure. + */ void i2c_attachSlaveTxEvent(i2c_t *obj, void (*function)(i2c_t *)); #ifdef __cplusplus diff --git a/system/STM32C0xx/stm32c0xx_hal_conf_default.h b/system/STM32C0xx/stm32c0xx_hal_conf_default.h index 421bd57e16..dc5ebbe3a5 100644 --- a/system/STM32C0xx/stm32c0xx_hal_conf_default.h +++ b/system/STM32C0xx/stm32c0xx_hal_conf_default.h @@ -327,6 +327,14 @@ in voltage and temperature.*/ */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ +/** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t *file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32F0xx/stm32f0xx_hal_conf_default.h b/system/STM32F0xx/stm32f0xx_hal_conf_default.h index b63ee5e55c..3ab95e177a 100644 --- a/system/STM32F0xx/stm32f0xx_hal_conf_default.h +++ b/system/STM32F0xx/stm32f0xx_hal_conf_default.h @@ -364,6 +364,14 @@ in voltage and temperature. */ */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ +/** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t* file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32F1xx/stm32f1xx_hal_conf_default.h b/system/STM32F1xx/stm32f1xx_hal_conf_default.h index c823b60527..62cf09b75f 100644 --- a/system/STM32F1xx/stm32f1xx_hal_conf_default.h +++ b/system/STM32F1xx/stm32f1xx_hal_conf_default.h @@ -442,6 +442,14 @@ extern "C" { */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ +/** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t *file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32F2xx/stm32f2xx_hal_conf_default.h b/system/STM32F2xx/stm32f2xx_hal_conf_default.h index f1f9963c1b..dbd31a8804 100644 --- a/system/STM32F2xx/stm32f2xx_hal_conf_default.h +++ b/system/STM32F2xx/stm32f2xx_hal_conf_default.h @@ -470,6 +470,14 @@ in voltage and temperature.*/ */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ +/** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t *file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32F3xx/stm32f3xx_hal_conf_default.h b/system/STM32F3xx/stm32f3xx_hal_conf_default.h index bd031a142a..20112cfee1 100644 --- a/system/STM32F3xx/stm32f3xx_hal_conf_default.h +++ b/system/STM32F3xx/stm32f3xx_hal_conf_default.h @@ -412,6 +412,14 @@ in voltage and temperature. */ */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ +/** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t* file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32F4xx/stm32f4xx_hal_conf_default.h b/system/STM32F4xx/stm32f4xx_hal_conf_default.h index 0f589ea521..5fb450d820 100644 --- a/system/STM32F4xx/stm32f4xx_hal_conf_default.h +++ b/system/STM32F4xx/stm32f4xx_hal_conf_default.h @@ -580,6 +580,14 @@ in voltage and temperature. */ */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ +/** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t *file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32F7xx/stm32f7xx_hal_conf_default.h b/system/STM32F7xx/stm32f7xx_hal_conf_default.h index be2245868d..873bb01a94 100644 --- a/system/STM32F7xx/stm32f7xx_hal_conf_default.h +++ b/system/STM32F7xx/stm32f7xx_hal_conf_default.h @@ -567,6 +567,14 @@ in voltage and temperature. */ */ #define assert_param(expr) ((expr) ? (void)0 : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ +/** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t *file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32G0xx/stm32g0xx_hal_conf_default.h b/system/STM32G0xx/stm32g0xx_hal_conf_default.h index f34d17ceb1..966609f486 100644 --- a/system/STM32G0xx/stm32g0xx_hal_conf_default.h +++ b/system/STM32G0xx/stm32g0xx_hal_conf_default.h @@ -398,6 +398,14 @@ in voltage and temperature.*/ */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ +/** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t *file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32G4xx/stm32g4xx_hal_conf_default.h b/system/STM32G4xx/stm32g4xx_hal_conf_default.h index 21087ff76f..ceeaaae202 100644 --- a/system/STM32G4xx/stm32g4xx_hal_conf_default.h +++ b/system/STM32G4xx/stm32g4xx_hal_conf_default.h @@ -437,6 +437,14 @@ The real value may vary depending on the variations in voltage and temperature.* */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ +/** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t *file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32H5xx/stm32h5xx_hal_conf_default.h b/system/STM32H5xx/stm32h5xx_hal_conf_default.h index 74c2fdafcb..548784af81 100644 --- a/system/STM32H5xx/stm32h5xx_hal_conf_default.h +++ b/system/STM32H5xx/stm32h5xx_hal_conf_default.h @@ -653,6 +653,14 @@ in voltage and temperature.*/ */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ----------------------------------------------------------------------------------------------- */ +/** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t *file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32H7xx/stm32h7xx_hal_conf_default.h b/system/STM32H7xx/stm32h7xx_hal_conf_default.h index 5dc9afa366..08086808dd 100644 --- a/system/STM32H7xx/stm32h7xx_hal_conf_default.h +++ b/system/STM32H7xx/stm32h7xx_hal_conf_default.h @@ -625,6 +625,14 @@ extern "C" { */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ +/** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t *file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32L0xx/stm32l0xx_hal_conf_default.h b/system/STM32L0xx/stm32l0xx_hal_conf_default.h index b8b2030634..fb53052271 100644 --- a/system/STM32L0xx/stm32l0xx_hal_conf_default.h +++ b/system/STM32L0xx/stm32l0xx_hal_conf_default.h @@ -381,6 +381,14 @@ extern "C" { */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ +/** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t *file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32L1xx/stm32l1xx_hal_conf_default.h b/system/STM32L1xx/stm32l1xx_hal_conf_default.h index 56ce325291..481423bfa6 100644 --- a/system/STM32L1xx/stm32l1xx_hal_conf_default.h +++ b/system/STM32L1xx/stm32l1xx_hal_conf_default.h @@ -363,6 +363,14 @@ in voltage and temperature.*/ */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ +/** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t *file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32L4xx/stm32l4xx_hal_conf_default.h b/system/STM32L4xx/stm32l4xx_hal_conf_default.h index 8ff6f2b862..d1bc7b945c 100644 --- a/system/STM32L4xx/stm32l4xx_hal_conf_default.h +++ b/system/STM32L4xx/stm32l4xx_hal_conf_default.h @@ -549,6 +549,14 @@ in voltage and temperature.*/ */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ +/** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t *file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32L5xx/stm32l5xx_hal_conf_default.h b/system/STM32L5xx/stm32l5xx_hal_conf_default.h index 0dee0f3ac7..9eaca1225c 100644 --- a/system/STM32L5xx/stm32l5xx_hal_conf_default.h +++ b/system/STM32L5xx/stm32l5xx_hal_conf_default.h @@ -500,6 +500,14 @@ in voltage and temperature.*/ */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ +/** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t *file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32MP1xx/stm32mp1xx_hal_conf_default.h b/system/STM32MP1xx/stm32mp1xx_hal_conf_default.h index a54cef6e56..6c99a3ada4 100644 --- a/system/STM32MP1xx/stm32mp1xx_hal_conf_default.h +++ b/system/STM32MP1xx/stm32mp1xx_hal_conf_default.h @@ -388,6 +388,14 @@ */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ + /** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t* file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32U0xx/stm32u0xx_hal_conf_default.h b/system/STM32U0xx/stm32u0xx_hal_conf_default.h index 824ee5d91d..fd2a9375e6 100644 --- a/system/STM32U0xx/stm32u0xx_hal_conf_default.h +++ b/system/STM32U0xx/stm32u0xx_hal_conf_default.h @@ -375,6 +375,14 @@ The real value may vary depending on the variations in voltage and temperature.* */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ +/** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t *file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32U3xx/stm32u3xx_hal_conf_default.h b/system/STM32U3xx/stm32u3xx_hal_conf_default.h index 036c7e1172..c7a6f9bee7 100644 --- a/system/STM32U3xx/stm32u3xx_hal_conf_default.h +++ b/system/STM32U3xx/stm32u3xx_hal_conf_default.h @@ -514,6 +514,14 @@ extern "C" { */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ +/** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t *file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32U5xx/stm32u5xx_hal_conf_default.h b/system/STM32U5xx/stm32u5xx_hal_conf_default.h index 5f089108be..e43e1f6278 100644 --- a/system/STM32U5xx/stm32u5xx_hal_conf_default.h +++ b/system/STM32U5xx/stm32u5xx_hal_conf_default.h @@ -618,6 +618,14 @@ vary depending on the variations in voltage and temperature.*/ */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ +/** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t *file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32WB0x/stm32wb0x_hal_conf_default.h b/system/STM32WB0x/stm32wb0x_hal_conf_default.h index 5a499b3e0a..4354a3d4b6 100644 --- a/system/STM32WB0x/stm32wb0x_hal_conf_default.h +++ b/system/STM32WB0x/stm32wb0x_hal_conf_default.h @@ -302,6 +302,14 @@ in voltage and temperature.*/ */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ +/** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t *file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32WBAxx/stm32wbaxx_hal_conf_default.h b/system/STM32WBAxx/stm32wbaxx_hal_conf_default.h index 34f17e1781..63bcfd5642 100644 --- a/system/STM32WBAxx/stm32wbaxx_hal_conf_default.h +++ b/system/STM32WBAxx/stm32wbaxx_hal_conf_default.h @@ -375,6 +375,14 @@ extern "C" { */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ +/** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t *file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32WBxx/stm32wbxx_hal_conf_default.h b/system/STM32WBxx/stm32wbxx_hal_conf_default.h index f07575ba3b..591528543f 100644 --- a/system/STM32WBxx/stm32wbxx_hal_conf_default.h +++ b/system/STM32WBxx/stm32wbxx_hal_conf_default.h @@ -406,6 +406,14 @@ extern "C" { */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ +/** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t *file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32WL3x/stm32wl3x_hal_conf_default.h b/system/STM32WL3x/stm32wl3x_hal_conf_default.h index 52c2cb79fe..3f8aecd19e 100644 --- a/system/STM32WL3x/stm32wl3x_hal_conf_default.h +++ b/system/STM32WL3x/stm32wl3x_hal_conf_default.h @@ -304,6 +304,14 @@ in voltage and temperature.*/ */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ +/** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t *file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/system/STM32WLxx/stm32wlxx_hal_conf_default.h b/system/STM32WLxx/stm32wlxx_hal_conf_default.h index 793c3e3156..e29bc7a537 100644 --- a/system/STM32WLxx/stm32wlxx_hal_conf_default.h +++ b/system/STM32WLxx/stm32wlxx_hal_conf_default.h @@ -383,6 +383,14 @@ */ #define assert_param(expr) ((expr) ? (void)0U : assert_failed((uint8_t *)__FILE__, __LINE__)) /* Exported functions ------------------------------------------------------- */ + /** + * @brief Reports the source file name and line number of a failed assert_param() check. + * + * Called by assert_param() when USE_FULL_ASSERT is defined. The default + * implementation is weak and can be overridden by the application. + * @param file pointer to the source file name + * @param line source line number of the failed assert_param() check + */ void assert_failed(uint8_t* file, uint32_t line); #else #define assert_param(expr) ((void)0U) diff --git a/variants/STM32H7xx/H742V(G-I)(H-T)_H743V(G-I)(H-T)_H750VBT_H753VI(H-T)/variant_DevEBoxH7xx.cpp b/variants/STM32H7xx/H742V(G-I)(H-T)_H743V(G-I)(H-T)_H750VBT_H753VI(H-T)/variant_DevEBoxH7xx.cpp index ac39df518b..ba7f4d169e 100644 --- a/variants/STM32H7xx/H742V(G-I)(H-T)_H743V(G-I)(H-T)_H750VBT_H753VI(H-T)/variant_DevEBoxH7xx.cpp +++ b/variants/STM32H7xx/H742V(G-I)(H-T)_H743V(G-I)(H-T)_H750VBT_H753VI(H-T)/variant_DevEBoxH7xx.cpp @@ -121,9 +121,7 @@ const pin_size_t analogInputPin[] = { }; /** - * @brief System Clock Configuration - * @param None - * @retval None + * @brief System Clock Configuration */ WEAK void SystemClock_Config(void) { @@ -259,10 +257,6 @@ WEAK void SystemClock_Config(void) } } -/* - * Power saving mode, mcu runs significantly cooler - * Sysclock 240 Mhz, bus clocks 120 Mhz - */ void SysClkHalfSpeed() { RCC_ClkInitTypeDef RCC_ClkInitStruct = { }; @@ -284,10 +278,6 @@ void SysClkHalfSpeed() } } -/* - * Full speed - sysclk from PLL1 P - 480 Mhz - * Sysclock 480 Mhz, bus clocks 240 Mhz - */ void SysClkFullSpeed() { RCC_ClkInitTypeDef RCC_ClkInitStruct = { }; diff --git a/variants/STM32H7xx/H742V(G-I)(H-T)_H743V(G-I)(H-T)_H750VBT_H753VI(H-T)/variant_DevEBoxH7xx.h b/variants/STM32H7xx/H742V(G-I)(H-T)_H743V(G-I)(H-T)_H750VBT_H753VI(H-T)/variant_DevEBoxH7xx.h index 10430f322d..776bcb15d9 100644 --- a/variants/STM32H7xx/H742V(G-I)(H-T)_H743V(G-I)(H-T)_H750VBT_H753VI(H-T)/variant_DevEBoxH7xx.h +++ b/variants/STM32H7xx/H742V(G-I)(H-T)_H743V(G-I)(H-T)_H750VBT_H753VI(H-T)/variant_DevEBoxH7xx.h @@ -277,15 +277,16 @@ extern "C" { #endif -/* - * Power saving mode, mcu runs significantly cooler - * Sysclock 240 Mhz, bus clocks 120 Mhz +/** + * @brief Power saving mode, the MCU runs significantly cooler. + * Sysclock 240 MHz, bus clocks 120 MHz. + * @note Uses the PLL configured by SystemClock_Config(). Calls Error_Handler() on failure. */ void SysClkHalfSpeed(); -/* - * Full speed - sysclk from PLL1 P - 480 Mhz - * Sysclock 480 Mhz, bus clocks 240 Mhz +/** + * @brief Full speed, sysclk from PLL1 P: sysclock 480 MHz, bus clocks 240 MHz. + * @note Uses the PLL configured by SystemClock_Config(). Calls Error_Handler() on failure. */ void SysClkFullSpeed(); diff --git a/variants/STM32H7xx/H742V(G-I)(H-T)_H743V(G-I)(H-T)_H750VBT_H753VI(H-T)/variant_WeActMiniH7xx.cpp b/variants/STM32H7xx/H742V(G-I)(H-T)_H743V(G-I)(H-T)_H750VBT_H753VI(H-T)/variant_WeActMiniH7xx.cpp index 9d2d574432..8d7537c6a6 100644 --- a/variants/STM32H7xx/H742V(G-I)(H-T)_H743V(G-I)(H-T)_H750VBT_H753VI(H-T)/variant_WeActMiniH7xx.cpp +++ b/variants/STM32H7xx/H742V(G-I)(H-T)_H743V(G-I)(H-T)_H750VBT_H753VI(H-T)/variant_WeActMiniH7xx.cpp @@ -121,9 +121,7 @@ const pin_size_t analogInputPin[] = { }; /** - * @brief System Clock Configuration - * @param None - * @retval None + * @brief System Clock Configuration */ WEAK void SystemClock_Config(void) { @@ -259,10 +257,6 @@ WEAK void SystemClock_Config(void) } } -/* - * Power saving mode, mcu runs significantly cooler - * Sysclock 240 Mhz, bus clocks 120 Mhz - */ void SysClkHalfSpeed() { RCC_ClkInitTypeDef RCC_ClkInitStruct = { }; @@ -284,10 +278,6 @@ void SysClkHalfSpeed() } } -/* - * Full speed - sysclk from PLL1 P - 480 Mhz - * Sysclock 480 Mhz, bus clocks 240 Mhz - */ void SysClkFullSpeed() { RCC_ClkInitTypeDef RCC_ClkInitStruct = { }; diff --git a/variants/STM32H7xx/H742V(G-I)(H-T)_H743V(G-I)(H-T)_H750VBT_H753VI(H-T)/variant_WeActMiniH7xx.h b/variants/STM32H7xx/H742V(G-I)(H-T)_H743V(G-I)(H-T)_H750VBT_H753VI(H-T)/variant_WeActMiniH7xx.h index a74c67cdd7..e8dbbd37c9 100644 --- a/variants/STM32H7xx/H742V(G-I)(H-T)_H743V(G-I)(H-T)_H750VBT_H753VI(H-T)/variant_WeActMiniH7xx.h +++ b/variants/STM32H7xx/H742V(G-I)(H-T)_H743V(G-I)(H-T)_H750VBT_H753VI(H-T)/variant_WeActMiniH7xx.h @@ -276,15 +276,16 @@ extern "C" { #endif -/* - * Power saving mode, mcu runs significantly cooler - * Sysclock 240 Mhz, bus clocks 120 Mhz +/** + * @brief Power saving mode, the MCU runs significantly cooler. + * Sysclock 240 MHz, bus clocks 120 MHz. + * @note Uses the PLL configured by SystemClock_Config(). Calls Error_Handler() on failure. */ void SysClkHalfSpeed(); -/* - * Full speed - sysclk from PLL1 P - 480 Mhz - * Sysclock 480 Mhz, bus clocks 240 Mhz +/** + * @brief Full speed, sysclk from PLL1 P: sysclock 480 MHz, bus clocks 240 MHz. + * @note Uses the PLL configured by SystemClock_Config(). Calls Error_Handler() on failure. */ void SysClkFullSpeed();