STM32F1 HAL

https://github.com/xywml/stm32f1_hal_doc
Admin
This repository provides the complete STM32F1 series HAL (Hardware Abstraction Layer) library...
Tokens:12,998,170
Snippets:53,837
Trust Score:5.2
License:BSD-3-Clause
Update:5 months ago
Show doc for...
Tokens:
Raw
### STM32 IRDA HAL Driver Initialization and Configuration Guide

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F100xE_User_Manual/stm32f1xx__hal__irda_8c.html

A step-by-step guide on how to initialize and configure the STM32 IRDA HAL driver. This includes declaring the handle, implementing HAL_IRDA_MspInit for low-level resource setup (GPIO, NVIC, DMA), programming IRDA parameters, and finally calling HAL_IRDA_Init.

```APIDOC
(#) Declare a IRDA_HandleTypeDef handle structure (eg. IRDA_HandleTypeDef hirda).
(#) Initialize the IRDA low level resources by implementing the HAL_IRDA_MspInit() API:
    (##) Enable the USARTx interface clock.
    (##) IRDA pins configuration:
        (+++) Enable the clock for the IRDA GPIOs.
        (+++) Configure IRDA pins as alternate function pull-up.
    (##) NVIC configuration if you need to use interrupt process (HAL_IRDA_Transmit_IT() and HAL_IRDA_Receive_IT() APIs):
        (+++) Configure the USARTx interrupt priority.
        (+++) Enable the NVIC USART IRQ handle.
    (##) DMA Configuration if you need to use DMA process (HAL_IRDA_Transmit_DMA() and HAL_IRDA_Receive_DMA() APIs):
        (+++) Declare a DMA handle structure for the Tx/Rx channel.
        (+++) Enable the DMAx interface clock.
        (+++) Configure the declared DMA handle structure with the required Tx/Rx parameters.
        (+++) Configure the DMA Tx/Rx channel.
        (+++) Associate the initialized DMA handle to the IRDA DMA Tx/Rx handle.
        (+++) Configure the priority and enable the NVIC for the transfer complete interrupt on the DMA Tx/Rx channel.
        (+++) Configure the IRDAx interrupt priority and enable the NVIC USART IRQ handle (used for last byte sending completion detection in DMA non circular mode)
(#) Program the Baud Rate, Word Length, Parity, IrDA Mode, Prescaler and Mode(Receiver/Transmitter) in the hirda Init structure.
(#) Initialize the IRDA registers by calling the HAL_IRDA_Init() API:
    (++) This API configures also the low level Hardware GPIO, CLOCK, CORTEX...etc) by calling the customized HAL_IRDA_MspInit() API.
     -@@- The specific IRDA interrupts (Transmission complete interrupt, RXNE interrupt and Error Interrupts) will be managed using the macros __HAL_IRDA_ENABLE_IT() and __HAL_IRDA_DISABLE_IT() inside the transmit and receive process.
```

--------------------------------

### PCD Initialization and Usage Example

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F107xC_User_Manual/stm32f1xx__hal__pcd_8c.html

Provides a step-by-step guide on how to initialize and use the PCD HAL driver, including low-level resource configuration and peripheral activation.

```APIDOC
##### How to use this driver #####

  The PCD HAL driver can be used as follows:

  (#) Declare a PCD_HandleTypeDef handle structure, for example:
      PCD_HandleTypeDef  hpcd;

  (#) Fill parameters of Init structure in HCD handle

  (#) Call HAL_PCD_Init() API to initialize the PCD peripheral (Core, Device core, ...)

  (#) Initialize the PCD low level resources through the HAL_PCD_MspInit() API:
      (##) Enable the PCD/USB Low Level interface clock using
           (+++) __HAL_RCC_USB_CLK_ENABLE(); For USB Device FS peripheral
           (+++) __HAL_RCC_USB_OTG_FS_CLK_ENABLE();

      (##) Initialize the related GPIO clocks
      (##) Configure PCD pin-out
      (##) Configure PCD NVIC interrupt

  (#)Associate the Upper USB device stack to the HAL PCD Driver:
      (##) hpcd.pData = pdev;

  (#)Enable PCD transmission and reception:
      (##) HAL_PCD_Start();
```

--------------------------------

### STM32F1xx HAL PCD Driver Usage Guide

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F103xG_User_Manual/stm32f1xx__hal__pcd_8c_source.html

Provides a step-by-step guide on how to use the STM32F1xx HAL PCD driver. It covers initialization, low-level resource configuration, and starting the PCD peripheral. Key functions include HAL_PCD_Init, HAL_PCD_MspInit, and HAL_PCD_Start.

```APIDOC
STM32F1xx HAL PCD Driver Usage:

1. Declare a PCD_HandleTypeDef handle structure (e.g., PCD_HandleTypeDef hpcd;).
2. Fill parameters of the Init structure in the HCD handle.
3. Call HAL_PCD_Init() API to initialize the PCD peripheral (Core, Device core, ...).
4. Initialize the PCD low level resources through the HAL_PCD_MspInit() API:
   - Enable the PCD/USB Low Level interface clock using __HAL_RCC_USB_CLK_ENABLE() or __HAL_RCC_USB_OTG_FS_CLK_ENABLE().
   - Initialize the related GPIO clocks.
   - Configure PCD pin-out.
   - Configure PCD NVIC interrupt.
5. Associate the Upper USB device stack to the HAL PCD Driver (e.g., hpcd.pData = pdev;).
6. Enable PCD transmission and reception using HAL_PCD_Start().
```

--------------------------------

### STM32F1xx HAL UART Driver Usage Guide

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F107xC_User_Manual/stm32f1xx__hal__uart_8c_source.html

A comprehensive guide on how to use the STM32F1xx HAL UART driver. It covers the necessary steps for initialization, low-level resource configuration, peripheral parameter setup, and usage in different modes.

```APIDOC
STM32F1xx HAL UART Driver Usage Guide:

  ==============================================================================
                          ##### How to use this driver #####
  ==============================================================================

  The UART HAL driver can be used as follows:

  1. Declare a UART_HandleTypeDef handle structure (e.g. UART_HandleTypeDef huart).

  2. Initialize the UART low level resources by implementing the HAL_UART_MspInit() API:
     - Enable the USARTx interface clock.
     - UART pins configuration:
       - Enable the clock for the UART GPIOs.
       - Configure the UART TX/RX pins as alternate function pull-up.
     - NVIC configuration if interrupt process is needed (HAL_UART_Transmit_IT() and HAL_UART_Receive_IT()):
       - Configure the USARTx interrupt priority.
       - Enable the NVIC USART IRQ handle.
     - DMA Configuration if DMA process is needed (HAL_UART_Transmit_DMA() and HAL_UART_Receive_DMA()):
       - Declare a DMA handle structure for the Tx/Rx channel.
       - Enable the DMAx interface clock.
       - Configure the declared DMA handle structure with the required Tx/Rx parameters.
       - Configure the DMA Tx/Rx channel.
       - Associate the initialized DMA handle to the UART DMA Tx/Rx handle.
       - Configure the priority and enable the NVIC for the transfer complete interrupt on the DMA Tx/Rx channel.
       - Configure the USARTx interrupt priority and enable the NVIC USART IRQ handle (for last byte sending completion detection in DMA non circular mode).

  3. Program the Baud Rate, Word Length, Stop Bit, Parity, Hardware flow control and Mode (Receiver/Transmitter) in the huart Init structure.

  4. Initialize the UART registers:
     - For asynchronous mode: call HAL_UART_Init().
     - For Half duplex mode: call HAL_HalfDuplex_Init().
     - For LIN mode: call HAL_LIN_Init().
     - For Multi-Processor mode: call HAL_MultiProcessor_Init().

  5. Manage UART interrupts:
     - The specific UART interrupts (Transmission complete, RXNE, Error) will be managed using macros.
```

--------------------------------

### STM32 I2C HAL Driver Initialization and Usage Guide

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F100xE_User_Manual/stm32f1xx__hal__i2c_8c.html

Comprehensive guide on initializing the STM32 I2C HAL driver, including handle declaration, low-level resource setup (MspInit), configuration, and various polling mode IO and IO MEM operations.

```APIDOC
##### How to use this driver #####

The I2C HAL driver can be used as follows:

1. Declare an I2C_HandleTypeDef handle structure, for example:
   I2C_HandleTypeDef  hi2c;

2. Initialize the I2C low level resources by implementing the HAL_I2C_MspInit() API:
   - Enable the I2Cx interface clock
   - I2C pins configuration
     - Enable the clock for the I2C GPIOs
     - Configure I2C pins as alternate function open-drain
   - NVIC configuration if you need to use interrupt process
     - Configure the I2Cx interrupt priority
     - Enable the NVIC I2C IRQ Channel
   - DMA Configuration if you need to use DMA process
     - Declare a DMA_HandleTypeDef handle structure for the transmit or receive channel
     - Enable the DMAx interface clock
     - Configure the DMA handle parameters
     - Configure the DMA Tx or Rx channel
     - Associate the initialized DMA handle to the hi2c DMA Tx or Rx handle
     - Configure the priority and enable the NVIC for the transfer complete interrupt on
       the DMA Tx or Rx channel

3. Configure the Communication Speed, Duty cycle, Addressing mode, Own Address1,
   Dual Addressing mode, Own Address2, General call and Nostretch mode in the hi2c Init structure.

4. Initialize the I2C registers by calling the HAL_I2C_Init(), which also configures the low level Hardware
   (GPIO, CLOCK, NVIC...etc) by calling the customized HAL_I2C_MspInit() API.

5. To check if target device is ready for communication, use the function HAL_I2C_IsDeviceReady()

6. For I2C IO and IO MEM operations, three operation modes are available within this driver:

   *** Polling mode IO operation ***
   - Transmit in master mode an amount of data in blocking mode using HAL_I2C_Master_Transmit()
   - Receive in master mode an amount of data in blocking mode using HAL_I2C_Master_Receive()
   - Transmit in slave mode an amount of data in blocking mode using HAL_I2C_Slave_Transmit()
   - Receive in slave mode an amount of data in blocking mode using HAL_I2C_Slave_Receive()

   *** Polling mode IO MEM operation ***
   - Write an amount of data in blocking mode to a specific memory address using HAL_I2C_Mem_Write()
```

--------------------------------

### STM32F1xx HAL UART Driver Usage Guide

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F103xG_User_Manual/stm32f1xx__hal__uart_8c_source.html

Step-by-step guide on how to use the STM32F1xx HAL UART driver for initialization and operation, covering low-level setup, parameter configuration, and different communication modes.

```APIDOC
==============================================================================
                        ##### How to use this driver #####
==============================================================================

  The UART HAL driver can be used as follows:

  (#) Declare a UART_HandleTypeDef handle structure (eg. UART_HandleTypeDef huart).
  (#) Initialize the UART low level resources by implementing the HAL_UART_MspInit() API:
      (##) Enable the USARTx interface clock.
      (##) UART pins configuration:
          (+++) Enable the clock for the UART GPIOs.
          (+++) Configure the UART TX/RX pins as alternate function pull-up.
      (##) NVIC configuration if you need to use interrupt process (HAL_UART_Transmit_IT()
           and HAL_UART_Receive_IT() APIs):
          (+++) Configure the USARTx interrupt priority.
          (+++) Enable the NVIC USART IRQ handle.
      (##) DMA Configuration if you need to use DMA process (HAL_UART_Transmit_DMA()
           and HAL_UART_Receive_DMA() APIs):
          (+++) Declare a DMA handle structure for the Tx/Rx channel.
          (+++) Enable the DMAx interface clock.
          (+++) Configure the declared DMA handle structure with the required
                Tx/Rx parameters.
          (+++) Configure the DMA Tx/Rx channel.
          (+++) Associate the initialized DMA handle to the UART DMA Tx/Rx handle.
          (+++) Configure the priority and enable the NVIC for the transfer complete
                interrupt on the DMA Tx/Rx channel.
          (+++) Configure the USARTx interrupt priority and enable the NVIC USART IRQ handle
                (used for last byte sending completion detection in DMA non circular mode)

  (#) Program the Baud Rate, Word Length, Stop Bit, Parity, Hardware
      flow control and Mode(Receiver/Transmitter) in the huart Init structure.

  (#) For the UART asynchronous mode, initialize the UART registers by calling
      the HAL_UART_Init() API.

  (#) For the UART Half duplex mode, initialize the UART registers by calling
      the HAL_HalfDuplex_Init() API.

  (#) For the LIN mode, initialize the UART registers by calling the HAL_LIN_Init() API.

  (#) For the Multi-Processor mode, initialize the UART registers by calling
      the HAL_MultiProcessor_Init() API.

  (@) The specific UART interrupts (Transmission complete interrupt,
      RXNE interrupt and Error Interrupts) will be managed using the macros
```

--------------------------------

### STM32F1 HAL SMARTCARD Driver Usage Guide

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F107xC_User_Manual/stm32f1xx__hal__smartcard_8c.html

Detailed guide on initializing and using the SMARTCARD HAL driver, covering low-level resource setup, peripheral configuration, and different IO operation modes (Polling, Interrupt, and DMA).

```APIDOC
##### How to use this driver #####

1. Declare a SMARTCARD_HandleTypeDef handle structure.
2. Initialize low-level resources by implementing HAL_SMARTCARD_MspInit() API:
   - Enable the interface clock of the USARTx associated to the SMARTCARD.
   - SMARTCARD pins configuration:
     - Enable the clock for the SMARTCARD GPIOs.
     - Configure SMARTCARD pins as alternate function pull-up.
   - NVIC configuration (if you need to use interrupt process, e.g., HAL_SMARTCARD_Transmit_IT(), HAL_SMARTCARD_Receive_IT()):
     - Configure the USARTx interrupt priority.
     - Enable the NVIC USART IRQ handle.
   - DMA Configuration (if you need to use DMA process, e.g., HAL_SMARTCARD_Transmit_DMA(), HAL_SMARTCARD_Receive_DMA()):
     - Declare a DMA handle structure for the Tx/Rx channel.
     - Enable the DMAx interface clock.
     - Configure the declared DMA handle structure with the required Tx/Rx parameters.
     - Configure the DMA Tx/Rx channel.
     - Associate the initialized DMA handle to the SMARTCARD DMA Tx/Rx handle.
     - Configure the priority and enable the NVIC for the transfer complete interrupt on the DMA Tx/Rx channel.
     - Configure the USARTx interrupt priority and enable the NVIC USART IRQ handle (used for last byte sending completion detection in DMA non circular mode).
3. Program the Baud Rate, Word Length, Stop Bit, Parity, Hardware flow control and Mode (Receiver/Transmitter) in the SMARTCARD Init structure.
4. Initialize the SMARTCARD registers by calling the HAL_SMARTCARD_Init() API:
   - These APIs configure also the low level Hardware (GPIO, CLOCK, CORTEX, etc.) by calling the customized HAL_SMARTCARD_MspInit() API.


*** Operation Modes ***

Polling mode IO operation:
- Send an amount of data in blocking mode using HAL_SMARTCARD_Transmit()
- Receive an amount of data in blocking mode using HAL_SMARTCARD_Receive()

Interrupt mode IO operation:
- Send an amount of data in non blocking mode using HAL_SMARTCARD_Transmit_IT()
- At transmission end of transfer HAL_SMARTCARD_TxCpltCallback is executed and user can add his own code by customization of function pointer HAL_SMARTCARD_TxCpltCallback.
- Receive an amount of data in non blocking mode using HAL_SMARTCARD_Receive_IT()
- At reception end of transfer HAL_SMARTCARD_RxCpltCallback is executed and user can add his own code by customization of function pointer HAL_SMARTCARD_RxCpltCallback.
- In case of transfer Error, HAL_SMARTCARD_ErrorCallback() function is executed and user can add his own code by customization of function pointer HAL_SMARTCARD_ErrorCallback.

DMA mode IO operation:
- Send an amount of data in non blocking mode (DMA) using HAL_SMARTCARD_Transmit_DMA()
- At transmission end of transfer HAL_SMARTCARD_TxCpltCallback is executed and user can add his own code by customization of function pointer HAL_SMARTCARD_TxCpltCallback.
- Receive an amount of data in non blocking mode (DMA) using HAL_SMARTCARD_Receive_DMA()
- At reception end of transfer HAL_SMARTCARD_RxCpltCallback is executed and user can add his own code by customization of function pointer HAL_SMARTCARD_RxCpltCallback.
```

--------------------------------

### STM32F1 IRDA HAL Driver Usage Guide

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F103xG_User_Manual/stm32f1xx__hal__irda_8c.html

A comprehensive guide on how to initialize and use the IRDA HAL driver, covering low-level resource configuration, NVIC setup for interrupts, DMA configuration, and programming of IRDA parameters.

```APIDOC
The IRDA HAL driver can be used as follows:
1. Declare an IRDA_HandleTypeDef handle structure (e.g., IRDA_HandleTypeDef hirda).
2. Initialize the IRDA low-level resources by implementing the HAL_IRDA_MspInit() API:
   - Enable the USARTx interface clock.
   - IRDA pins configuration:
     - Enable the clock for the IRDA GPIOs.
     - Configure IRDA pins as alternate function pull-up.
   - NVIC configuration if you need to use interrupt process (HAL_IRDA_Transmit_IT() and HAL_IRDA_Receive_IT() APIs):
     - Configure the USARTx interrupt priority.
     - Enable the NVIC USART IRQ handle.
   - DMA Configuration if you need to use DMA process (HAL_IRDA_Transmit_DMA() and HAL_IRDA_Receive_DMA() APIs):
     - Declare a DMA handle structure for the Tx/Rx channel.
     - Enable the DMAx interface clock.
     - Configure the declared DMA handle structure with the required Tx/Rx parameters.
     - Configure the DMA Tx/Rx channel.
     - Associate the initialized DMA handle to the IRDA DMA Tx/Rx handle.
     - Configure the priority and enable the NVIC for the transfer complete interrupt on the DMA Tx/Rx channel.
     - Configure the IRDAx interrupt priority and enable the NVIC USART IRQ handle (used for last byte sending completion detection in DMA non circular mode).
3. Program the Baud Rate, Word Length, Parity, IrDA Mode, Prescaler and Mode (Receiver/Transmitter) in the hirda Init structure.
4. Initialize the IRDA registers by calling the HAL_IRDA_Init() API:
   - This API also configures the low-level Hardware (GPIO, CLOCK, CORTEX, etc.) by calling the customized HAL_IRDA_MspInit() API.
   - The specific IRDA interrupts (Transmission complete interrupt, RXNE interrupt and Error Interrupts) will be managed using the macros __HAL_IRDA_ENABLE_IT() and __HAL_IRDA_DISABLE_IT() inside the transmit and receive process.
```

--------------------------------

### STM32F1xx HAL ETH Driver Usage Guide

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F107xC_User_Manual/stm32f1xx__hal__eth_8c_source.html

This section outlines the step-by-step process to initialize and use the Ethernet peripheral (MAC, DMA) with the STM32F1xx HAL driver. It covers handle declaration, initialization, low-level resource configuration, DMA descriptor setup for transmission and reception, and starting the Ethernet interface. It also details functions for frame transmission, reception (polling and interrupt modes), and communication with external PHY devices.

```APIDOC
==============================================================================
                    ##### How to use this driver #####
==============================================================================
  [..]
    (#)Declare a ETH_HandleTypeDef handle structure, for example:
       ETH_HandleTypeDef  heth;

    (#)Fill parameters of Init structure in heth handle

    (#)Call HAL_ETH_Init() API to initialize the Ethernet peripheral (MAC, DMA, ...)

    (#)Initialize the ETH low level resources through the HAL_ETH_MspInit() API:
        (##) Enable the Ethernet interface clock using
             (+++) __HAL_RCC_ETHMAC_CLK_ENABLE();
             (+++) __HAL_RCC_ETHMACTX_CLK_ENABLE();
             (+++) __HAL_RCC_ETHMACRX_CLK_ENABLE();

        (##) Initialize the related GPIO clocks
        (##) Configure Ethernet pin-out
        (##) Configure Ethernet NVIC interrupt (IT mode)

    (#)Initialize Ethernet DMA Descriptors in chain mode and point to allocated buffers:
        (##) HAL_ETH_DMATxDescListInit(); for Transmission process
        (##) HAL_ETH_DMARxDescListInit(); for Reception process

    (#)Enable MAC and DMA transmission and reception:
        (##) HAL_ETH_Start();

    (#)Prepare ETH DMA TX Descriptors and give the hand to ETH DMA to transfer
       the frame to MAC TX FIFO:
       (##) HAL_ETH_TransmitFrame();

    (#)Poll for a received frame in ETH RX DMA Descriptors and get received
       frame parameters
       (##) HAL_ETH_GetReceivedFrame(); (should be called into an infinite loop)

    (#) Get a received frame when an ETH RX interrupt occurs:
       (##) HAL_ETH_GetReceivedFrame_IT(); (called in IT mode only)

    (#) Communicate with external PHY device:
       (##) Read a specific register from the PHY
            HAL_ETH_ReadPHYRegister();
       (##) Write data to a specific RHY register:
            HAL_ETH_WritePHYRegister();

    (#) Configure the Ethernet MAC after ETH peripheral initialization
        HAL_ETH_ConfigMAC(); all MAC parameters should be filled.

    (#) Configure the Ethernet DMA after ETH peripheral initialization
        HAL_ETH_ConfigDMA(); all DMA parameters should be filled.

    -@- The PTP protocol and the DMA descriptors ring mode are not supported
        in this driver
*** Callback registration ***
=============================================

The compilation define  USE_HAL_ETH_REGISTER_CALLBACKS when set to 1
```

--------------------------------

### HCD HAL Driver Usage Guide

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F103xB_User_Manual/stm32f1xx__hal__hcd_8c.html

Provides a guide on how to use the HCD HAL module driver for the STM32F1xx series. It outlines the steps for initializing the HCD peripheral, configuring low-level resources, associating the host stack, and starting transmissions.

```APIDOC
HCD HAL Driver Usage:

1. Declare a HCD_HandleTypeDef handle structure:
   HCD_HandleTypeDef  hhcd;

2. Fill parameters of Init structure in HCD handle.

3. Call HAL_HCD_Init() API to initialize the HCD peripheral (Core, Host core, ...).

4. Initialize the HCD low level resources through the HAL_HCD_MspInit() API:
   - Enable the HCD/USB Low Level interface clock using the following macros:
     - __HAL_RCC_USB_OTG_FS_CLK_ENABLE();
   - Initialize the related GPIO clocks.
   - Configure HCD pin-out.
   - Configure HCD NVIC interrupt.

5. Associate the Upper USB Host stack to the HAL HCD Driver:
   hhcd.pData = phost;

6. Enable HCD transmission and reception:
   HAL_HCD_Start();
```

--------------------------------

### STM32F1xx HAL I2S Driver Usage Guide

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F100xE_User_Manual/stm32f1xx__hal__i2s_8c_source.html

This section provides a guide on how to use the I2S HAL driver. It covers the necessary steps for initialization, including low-level resource setup (MSP initialization), configuring pins, NVIC, and DMA. It also details how to program the I2S mode, standard, data format, MCLK output, audio frequency, and polarity using HAL_I2S_Init(). Finally, it describes the available IO operation modes: polling and interrupt-driven.

```text
##### How to use this driver #####
===============================================================================
[..]
  The I2S HAL driver can be used as follow:

  (#) Declare a I2S_HandleTypeDef handle structure.
  (#) Initialize the I2S low level resources by implement the HAL_I2S_MspInit() API:
      (##) Enable the SPIx interface clock.
      (##) I2S pins configuration:
          (+++) Enable the clock for the I2S GPIOs.
          (+++) Configure these I2S pins as alternate function pull-up.
      (##) NVIC configuration if you need to use interrupt process (HAL_I2S_Transmit_IT()
           and HAL_I2S_Receive_IT() APIs).
          (+++) Configure the I2Sx interrupt priority.
          (+++) Enable the NVIC I2S IRQ handle.
      (##) DMA Configuration if you need to use DMA process (HAL_I2S_Transmit_DMA()
           and HAL_I2S_Receive_DMA() APIs:
          (+++) Declare a DMA handle structure for the Tx/Rx Stream/Channel.
          (+++) Enable the DMAx interface clock.
          (+++) Configure the declared DMA handle structure with the required Tx/Rx parameters.
          (+++) Configure the DMA Tx/Rx Stream/Channel.
          (+++) Associate the initialized DMA handle to the I2S DMA Tx/Rx handle.
          (+++) Configure the priority and enable the NVIC for the transfer complete interrupt on the
                DMA Tx/Rx Stream/Channel.

  (#) Program the Mode, Standard, Data Format, MCLK Output, Audio frequency and Polarity
      using HAL_I2S_Init() function.

  -@- The specific I2S interrupts (Transmission complete interrupt,
      RXNE interrupt and Error Interrupts) will be managed using the macros
      __HAL_I2S_ENABLE_IT() and __HAL_I2S_DISABLE_IT() inside the transmit and receive process.
  -@- The I2SxCLK source is the system clock (provided by the HSI, the HSE or the PLL, and sourcing the AHB clock).
      For connectivity line devices, the I2SxCLK source can be either SYSCLK or the PLL3 VCO (2 x PLL3CLK) clock
      in order to achieve the maximum accuracy.
  -@- Make sure that either:
    (+@) External clock source is configured after setting correctly
         the define constant HSE_VALUE in the stm32f1xx_hal_conf.h file.

  (#) Three mode of operations are available within this driver :

  *** Polling mode IO operation ***
  =================================
  [..]
    (+) Send an amount of data in blocking mode using HAL_I2S_Transmit()
    (+) Receive an amount of data in blocking mode using HAL_I2S_Receive()

```

--------------------------------

### Define LL_I2C_SR1_SB for Start Bit

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F100xE_User_Manual/group__I2C__LL__EC__GET__FLAG.html

Defines the Start Bit flag in the I2C Status Register 1. This flag is set when a Start condition has been detected, typically in master mode.

```C
#define LL_I2C_SR1_SB		I2C_SR1_SB
```

--------------------------------

### PCD HAL Driver Usage Example

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F103xG_User_Manual/stm32f1xx__hal__pcd_8c.html

Illustrates the typical steps to initialize and use the PCD HAL driver, including MspInit, HAL_PCD_Init, and HAL_PCD_Start.

```C
/* USER CODE BEGIN Includes */
#include "stm32f1xx_hal.h"
#include "stm32f1xx_hal_pcd.h"
/* USER CODE END Includes */

/* USER CODE BEGIN PV */
PCD_HandleTypeDef hpcd;
/* USER CODE END PV */

/* USER CODE BEGIN 0 */

/* USER CODE END 0 */

/**
  * @brief  The application entry point.
  * @retval int
  */
int main(void)
{
  /* USER CODE BEGIN 1 */

  /* USER CODE END 1 */

  /* MCU Configuration--------------------------------------------------------*/

  /* Reset all peripherals, Initializes the Flash interface and the Systick. */
  HAL_Init();

  /* USER CODE BEGIN Init */

  /* USER CODE END Init */

  /* Configure the system clock */
  SystemClock_Config();

  /* USER CODE BEGIN SysInit */

  /* USER CODE END SysInit */

  /* Initialize all configured peripherals */
  MX_GPIO_Init();
  MX_USB_PCD_Init();
  /* USER CODE BEGIN 2 */

  /* USER CODE END 2 */

  /* Infinite loop */
  /* USER CODE BEGIN WHILE */
  while (1)
  {
    /* USER CODE END WHILE */

    /* USER CODE BEGIN 3 */
  }
  /* USER CODE END 3 */
}

/**
  * @brief PCD Initialization Function
  * @param None
  * @retval None
  */
void MX_USB_PCD_Init(void)
{

  /* USER CODE BEGIN USB_PCD_Init_PreTreatment */

  /* USER CODE END USB_PCD_Init_PreTreatment */

  hpcd.Instance = USB_FS;
  hpcd.Init.devcap = USB_DEVICE_CAPABILITY_FULL_SPEED;
  hpcd.Init.speed = PCD_SPEED_FULL;
  hpcd.Init.ep0_mps = DEP0_MAX_SIZE;
  hpcd.Init.phy_itface = PCD_PHY_EMBEDDED;
  hpcd.Init.Sof_enable = DISABLE;
  hpcd.Init.low_power_enable = DISABLE;
  hpcd.Init.lpm_enable = DISABLE;
  hpcd.Init.battery_charging_enable = DISABLE;
  if (HAL_PCD_Init(&hpcd) != HAL_OK)
  {
    Error_Handler();
  }
  /* USER CODE BEGIN USB_PCD_Init */

  /* USER CODE END USB_PCD_Init */
}

/**
  * @brief  This function is executed in case of error occurrence.
  * @retval None
  */
void Error_Handler(void)
{
  /* USER CODE BEGIN Error_Handler_Debug */
  /* User can add his own implementation to report the HAL error return state */
  __disable_irq();
  while (1)
  {
  }
  /* USER CODE END Error_Handler_Debug */
}

#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 reference
  * @retval None
  */
void assert_failed(uint8_t *file, uint32_t line)
{
  /* USER CODE BEGIN 6 */
  /* User can add his own implementation to report the file name and line number, ex: printf("Wrong parameters value: file %s on line %d\r\n", file, line) */
  /* USER CODE END 6 */
}
```

--------------------------------

### Get CEC Transmission Start Flag

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F100xE_User_Manual/group__CEC__Exported__Macros.html

Retrieves the transmission start flag status for the CEC peripheral. This macro takes the CEC handle as input and returns a FlagStatus indicating the state of the transmission start flag.

```C
#define __HAL_CEC_GET_TRANSMISSION_START_FLAG(__HANDLE__) READ_BIT((__HANDLE__)->Instance->CSR, CEC_CSR_TSOM)
```

```APIDOC
__HAL_CEC_GET_TRANSMISSION_START_FLAG(__HANDLE__):
  Description: Retrieves the transmission start flag status for the CEC peripheral.
  Parameters:
    __HANDLE__: specifies the CEC Handle.
  Returns: FlagStatus
```

--------------------------------

### STM32F1xx HAL SDIO Driver Initialization and Usage Guide

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F103xG_User_Manual/stm32f1xx__hal__sd_8c_source.html

Detailed instructions on how to initialize and configure the STM32F1xx HAL SDIO driver. This includes enabling clocks, configuring GPIOs, setting up DMA for block transfers, and managing NVIC for interrupts, highlighting the user's responsibility in implementing the HAL_SD_MspInit() function for low-level resource setup.

```APIDOC
How to use this driver:
This driver implements a high level communication layer for read and write from/to this memory. The needed STM32 hardware resources (SDIO and GPIO) are performed by the user in HAL_SD_MspInit() function (MSP layer). Basically, the MSP layer configuration should be the same as we provide in the examples. You can easily tailor this configuration according to hardware resources.

This driver is a generic layered driver for SDIO memories which uses the HAL SDIO driver functions to interface with SD and uSD cards devices. It is used as follows:

1. Initialize the SDIO low level resources by implementing the HAL_SD_MspInit() API:
   a. Enable the SDIO interface clock using __HAL_RCC_SDIO_CLK_ENABLE();
   b. SDIO pins configuration for SD card
      i. Enable the clock for the SDIO GPIOs using the functions __HAL_RCC_GPIOx_CLK_ENABLE();
      ii. Configure these SDIO pins as alternate function pull-up using HAL_GPIO_Init() and according to your pin assignment;
   c. DMA configuration if you need to use DMA process (HAL_SD_ReadBlocks_DMA() and HAL_SD_WriteBlocks_DMA() APIs).
      i. Enable the DMAx interface clock using __HAL_RCC_DMAx_CLK_ENABLE();
      ii. Configure the DMA using the function HAL_DMA_Init() with predeclared and filled.
   d. NVIC configuration if you need to use interrupt process when using DMA transfer.
      i. Configure the SDIO and DMA interrupt priorities using functions HAL_NVIC_SetPriority(); DMA priority is superior to SDIO's priority
      ii. Enable the NVIC DMA and SDIO IRQs using function HAL_NVIC_EnableIRQ()
      iii. SDIO interrupts are managed using the macros __HAL_SD_ENABLE_IT() and __HAL_SD_DISABLE_IT() inside the communication process.
      iv. SDIO interrupts pending bits are managed using the macros __HAL_SD_GET_IT() and __HAL_SD_CLEAR_IT()
   e. NVIC configuration if you need to use interrupt process (HAL_SD_ReadBlocks_IT() and HAL_SD_WriteBlocks_IT() APIs).
      i. Configure the SDIO interrupt priorities using function HAL_NVIC_SetPriority();
      ii. Enable the NVIC SDIO IRQs using function HAL_NVIC_EnableIRQ()
```

--------------------------------

### Get CEC Transmission Start Flag Status

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F107xC_User_Manual/stm32f1xx__hal__cec_8h_source.html

This macro reads the Transmission Start of Message (TSOM) flag from the CEC Control and Status Register (CSR) to check if a transmission start is indicated. It returns a FlagStatus value.

```C
#define __HAL_CEC_GET_TRANSMISSION_START_FLAG(__HANDLE__) READ_BIT((__HANDLE__)->Instance->CSR, CEC_CSR_TSOM)
```

--------------------------------

### STM32F1 HAL DAC DMA Start Example

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F103xB_User_Manual/stm32f1xx__hal__dac_8c_source.html

This code snippet demonstrates the initialization and start of a DAC conversion using DMA for Channel 1 or Channel 2. It configures DMA settings, enables interrupts, and starts the DMA transfer.

```C
/* Enable the selected DAC channel2 DMA request */
SET_BIT(hdac->Instance->CR, DAC_CR_DMAEN2);

/* Case of use of channel 2 */
switch (Alignment)
{
  case DAC_ALIGN_12B_R:
    /* Get DHR12R2 address */
    tmpreg = (uint32_t)&hdac->Instance->DHR12R2;
    break;
  case DAC_ALIGN_12B_L:
    /* Get DHR12L2 address */
    tmpreg = (uint32_t)&hdac->Instance->DHR12L2;
    break;
  default: /* case DAC_ALIGN_8B_R */
    /* Get DHR8R2 address */
    tmpreg = (uint32_t)&hdac->Instance->DHR8R2;
    break;
}

if (Channel == DAC_CHANNEL_1)
{
#if defined(DAC_CR_DMAUDRIE1)
  /* Enable the DAC DMA underrun interrupt */
  __HAL_DAC_ENABLE_IT(hdac, DAC_IT_DMAUDR1);
#endif /* DAC_CR_DMAUDRIE1 */

  /* Enable the DMA Stream */
  status = HAL_DMA_Start_IT(hdac->DMA_Handle1, (uint32_t)pData, tmpreg, Length);
}
else
{
#if defined(DAC_CR_DMAUDRIE2)
  /* Enable the DAC DMA underrun interrupt */
  __HAL_DAC_ENABLE_IT(hdac, DAC_IT_DMAUDR2);
#endif /* DAC_CR_DMAUDRIE2 */

  /* Enable the DMA Stream */
  status = HAL_DMA_Start_IT(hdac->DMA_Handle2, (uint32_t)pData, tmpreg, Length);
}

/* Process Unlocked */
__HAL_UNLOCK(hdac);

if (status == HAL_OK)
{
  /* Enable the Peripheral */
  __HAL_DAC_ENABLE(hdac, Channel);
}
else
{
  hdac->ErrorCode |= HAL_DAC_ERROR_DMA;
}

/* Return function status */
return status;
```

--------------------------------

### USB PCD Setup Stage Callback (STM32F1 HAL)

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F107xC_User_Manual/stm32f1xx__hal__pcd_8c.html

Setup stage callback.

```APIDOC
__weak void HAL_PCD_SetupStageCallback(
  PCD_HandleTypeDef *hpcd // Pointer to a PCD_HandleTypeDef structure
)
```

--------------------------------

### HAL_TIMEx_HallSensor_Start Function Implementation Example

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F100xE_User_Manual/stm32f1xx__hal__tim__ex_8c_source.html

Example C code snippet demonstrating the internal logic for starting the TIM Hall Sensor interface, including state checks and configuration updates.

```c
HAL_StatusTypeDef HAL_TIMEx_HallSensor_Start(TIM_HandleTypeDef *htim)
{
  uint32_t tmpsmcr;
  HAL_TIM_ChannelStateTypeDef channel_1_state = TIM_CHANNEL_STATE_GET(htim, TIM_CHANNEL_1);
  HAL_TIM_ChannelStateTypeDef channel_2_state = TIM_CHANNEL_STATE_GET(htim, TIM_CHANNEL_2);
  HAL_TIM_ChannelStateTypeDef complementary_channel_1_state = TIM_CHANNEL_N_STATE_GET(htim, TIM_CHANNEL_1);
  HAL_TIM_ChannelStateTypeDef complementary_channel_2_state = TIM_CHANNEL_N_STATE_GET(htim, TIM_CHANNEL_2);

  /* Check the parameters */
  /* ... rest of the function implementation ... */

  /* Example of internal state setting */
  TIM_CHANNEL_N_STATE_SET(htim, TIM_CHANNEL_1, HAL_TIM_CHANNEL_STATE_RESET);
  TIM_CHANNEL_N_STATE_SET(htim, TIM_CHANNEL_2, HAL_TIM_CHANNEL_STATE_RESET);
  htim->State = HAL_TIM_STATE_RESET;
  __HAL_UNLOCK(htim);
  return HAL_OK;
}
```

--------------------------------

### WWDG Initialization Example

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F103xG_User_Manual/stm32f1xx__hal__wwdg_8c.html

Demonstrates the C code structure for initializing the WWDG peripheral with specific configuration parameters like prescaler, window value, and counter value.

```c
WWDG_InitTypeDef WWDG_InitStruct;

/* Enable WWDG APB1 clock */
__HAL_RCC_WWDG_CLK_ENABLE();

/* Configure the WWDG peripheral */
WWDG_InitStruct.Prescaler = WWDG_PRESCALER_8;
WWDG_InitStruct.Window = 0x40;
WWDG_InitStruct.Counter = 0x7F;
WWDG_InitStruct.EWIMode = WWDG_EWI_ENABLE;

if (HAL_WWDG_Init(&WWDG_InitStruct) != HAL_OK) {
  /* Initialization Error */
  Error_Handler();
}
```

--------------------------------

### HAL_TIMEx_HallSensor_Start Function Implementation Example

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F103xB_User_Manual/stm32f1xx__hal__tim__ex_8c_source.html

Example C code snippet demonstrating the internal logic for starting the TIM Hall Sensor interface, including state checks and configuration updates.

```c
HAL_StatusTypeDef HAL_TIMEx_HallSensor_Start(TIM_HandleTypeDef *htim)
{
  uint32_t tmpsmcr;
  HAL_TIM_ChannelStateTypeDef channel_1_state = TIM_CHANNEL_STATE_GET(htim, TIM_CHANNEL_1);
  HAL_TIM_ChannelStateTypeDef channel_2_state = TIM_CHANNEL_STATE_GET(htim, TIM_CHANNEL_2);
  HAL_TIM_ChannelStateTypeDef complementary_channel_1_state = TIM_CHANNEL_N_STATE_GET(htim, TIM_CHANNEL_1);
  HAL_TIM_ChannelStateTypeDef complementary_channel_2_state = TIM_CHANNEL_N_STATE_GET(htim, TIM_CHANNEL_2);

  /* Check the parameters */
  /* ... rest of the function implementation ... */

  /* Example of internal state setting */
  TIM_CHANNEL_N_STATE_SET(htim, TIM_CHANNEL_1, HAL_TIM_CHANNEL_STATE_RESET);
  TIM_CHANNEL_N_STATE_SET(htim, TIM_CHANNEL_2, HAL_TIM_CHANNEL_STATE_RESET);
  htim->State = HAL_TIM_STATE_RESET;
  __HAL_UNLOCK(htim);
  return HAL_OK;
}
```

--------------------------------

### WWDG Initialization Example

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F103xB_User_Manual/stm32f1xx__hal__wwdg_8c.html

Demonstrates the C code structure for initializing the WWDG peripheral with specific configuration parameters like prescaler, window value, and counter value.

```c
WWDG_InitTypeDef WWDG_InitStruct;

/* Enable WWDG APB1 clock */
__HAL_RCC_WWDG_CLK_ENABLE();

/* Configure the WWDG peripheral */
WWDG_InitStruct.Prescaler = WWDG_PRESCALER_8;
WWDG_InitStruct.Window = 0x40;
WWDG_InitStruct.Counter = 0x7F;
WWDG_InitStruct.EWIMode = WWDG_EWI_ENABLE;

if (HAL_WWDG_Init(&WWDG_InitStruct) != HAL_OK) {
  /* Initialization Error */
  Error_Handler();
}
```

--------------------------------

### HAL_TIMEx_HallSensor_Start Function Implementation Example

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F103xG_User_Manual/stm32f1xx__hal__tim__ex_8c_source.html

Example C code snippet demonstrating the internal logic for starting the TIM Hall Sensor interface, including state checks and configuration updates.

```c
HAL_StatusTypeDef HAL_TIMEx_HallSensor_Start(TIM_HandleTypeDef *htim)
{
  uint32_t tmpsmcr;
  HAL_TIM_ChannelStateTypeDef channel_1_state = TIM_CHANNEL_STATE_GET(htim, TIM_CHANNEL_1);
  HAL_TIM_ChannelStateTypeDef channel_2_state = TIM_CHANNEL_STATE_GET(htim, TIM_CHANNEL_2);
  HAL_TIM_ChannelStateTypeDef complementary_channel_1_state = TIM_CHANNEL_N_STATE_GET(htim, TIM_CHANNEL_1);
  HAL_TIM_ChannelStateTypeDef complementary_channel_2_state = TIM_CHANNEL_N_STATE_GET(htim, TIM_CHANNEL_2);

  /* Check the parameters */
  /* ... rest of the function implementation ... */

  /* Example of internal state setting */
  TIM_CHANNEL_N_STATE_SET(htim, TIM_CHANNEL_1, HAL_TIM_CHANNEL_STATE_RESET);
  TIM_CHANNEL_N_STATE_SET(htim, TIM_CHANNEL_2, HAL_TIM_CHANNEL_STATE_RESET);
  htim->State = HAL_TIM_STATE_RESET;
  __HAL_UNLOCK(htim);
  return HAL_OK;
}
```

--------------------------------

### STM32F1 HAL Driver Overview

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F107xC_User_Manual/stm32f1xx__hal_8c.html

Provides an overview of the STM32F1 HAL driver, its purpose in common initialization, and the categorization of its APIs into Common HAL APIs and Services HAL APIs. This section outlines how to start using the HAL.

```APIDOC
HAL Driver Structure:
  - Common HAL APIs
  - Services HAL APIs

Purpose:
  - Provides a set of generic and common APIs for peripheral drivers and user applications.
  - Facilitates the initialization and usage of the HAL.

Usage:
  - Start using the HAL by leveraging the Common HAL APIs and Services HAL APIs.
  - Refer to specific peripheral driver documentation for detailed API usage.
```

--------------------------------

### HAL_TIMEx_HallSensor_Start Function Implementation Example

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F107xC_User_Manual/stm32f1xx__hal__tim__ex_8c_source.html

Example C code snippet demonstrating the internal logic for starting the TIM Hall Sensor interface, including state checks and configuration updates.

```c
HAL_StatusTypeDef HAL_TIMEx_HallSensor_Start(TIM_HandleTypeDef *htim)
{
  uint32_t tmpsmcr;
  HAL_TIM_ChannelStateTypeDef channel_1_state = TIM_CHANNEL_STATE_GET(htim, TIM_CHANNEL_1);
  HAL_TIM_ChannelStateTypeDef channel_2_state = TIM_CHANNEL_STATE_GET(htim, TIM_CHANNEL_2);
  HAL_TIM_ChannelStateTypeDef complementary_channel_1_state = TIM_CHANNEL_N_STATE_GET(htim, TIM_CHANNEL_1);
  HAL_TIM_ChannelStateTypeDef complementary_channel_2_state = TIM_CHANNEL_N_STATE_GET(htim, TIM_CHANNEL_2);

  /* Check the parameters */
  /* ... rest of the function implementation ... */

  /* Example of internal state setting */
  TIM_CHANNEL_N_STATE_SET(htim, TIM_CHANNEL_1, HAL_TIM_CHANNEL_STATE_RESET);
  TIM_CHANNEL_N_STATE_SET(htim, TIM_CHANNEL_2, HAL_TIM_CHANNEL_STATE_RESET);
  htim->State = HAL_TIM_STATE_RESET;
  __HAL_UNLOCK(htim);
  return HAL_OK;
}
```

--------------------------------

### STM32 HAL ETH Initialization and DMA Setup

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F100xE_User_Manual/stm32f1xx__hal__eth_8c_source.html

This C code snippet demonstrates the initialization process for the STM32 HAL Ethernet (ETH) driver. It includes setting up DMA descriptor addresses for reception and updating the ETH HAL state to READY.

```c
/* For last descriptor, set next descriptor address register equal to the first descriptor base address */
    DMARxDesc->Buffer2NextDescAddr = (uint32_t)(DMARxDescTab);
  }

  /* Set Receive Descriptor List Address Register */
  (heth->Instance)->DMARDLAR = (uint32_t) DMARxDescTab;

  /* Set ETH HAL State to Ready */
  heth->State = HAL_ETH_STATE_READY;

  /* Process Unlocked */
  __HAL_UNLOCK(heth);

  /* Return function status */
  return HAL_OK;
}
```

--------------------------------

### WWDG Initialization Example

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F100xE_User_Manual/stm32f1xx__hal__wwdg_8c.html

Demonstrates the C code structure for initializing the WWDG peripheral with specific configuration parameters like prescaler, window value, and counter value.

```c
WWDG_InitTypeDef WWDG_InitStruct;

/* Enable WWDG APB1 clock */
__HAL_RCC_WWDG_CLK_ENABLE();

/* Configure the WWDG peripheral */
WWDG_InitStruct.Prescaler = WWDG_PRESCALER_8;
WWDG_InitStruct.Window = 0x40;
WWDG_InitStruct.Counter = 0x7F;
WWDG_InitStruct.EWIMode = WWDG_EWI_ENABLE;

if (HAL_WWDG_Init(&WWDG_InitStruct) != HAL_OK) {
  /* Initialization Error */
  Error_Handler();
}
```

--------------------------------

### Get CEC Transmission Start Flag Macro (C)

Source: https://github.com/xywml/stm32f1_hal_doc/blob/main/STM32F103xG_User_Manual/stm32f1xx__hal__cec_8h_source.html

Reads the Transmission Start of Message (TSOM) flag from the CEC control and status register. It returns a FlagStatus value and requires the CEC Handle.

```C
#define __HAL_CEC_GET_TRANSMISSION_START_FLAG(__HANDLE__) READ_BIT((__HANDLE__)->Instance->CSR, CEC_CSR_TSOM)
```
Tokens:
Raw