Introduction

The hal_gigadevice is a set of both standard firmware library and ARM CMSIS configurations for GigaDevice MCUs. The HAL is organized following the directory structure detailed below.

Directory Structure

The directory is composed by three parts:

• SoC specific libraries.
• ZephyrRTOS module directory (zephyr).
• This README file.

ARM

Each ARM firmware library is organized in the following structure:

.
└── gd32xxx
    ├── cmsis
    │   └── gd
    │       └── gd32xxx
    ├── standard_peripheral
    │   ├── include
    │   └── source
    └── support (optional)
        └── GigaDevice.GD32xxx_DFP.1.0.0.pack (Only for packs not in [Keil MDK5 Software Packs](https://www.keil.com/dd2/pack/))

RISC-V

The RISC-V structure is not defined yet. The riscv sub-directory will change based on how NMSIS library will be integrated in Zephyr. At present date, the structure only reflects current manufacturer version.

└── gd32bf103
    ├── riscv
    │   ├── drivers
    │   ├── include
    │   ├── source
    │   └── stubs
    └── standard_peripheral
        ├── include
        └── source

Any contribution should follow the How to submit code using as premisses the Zephyr Contribution Guidelines.

How to submit code

• When submiting an updated firmware library version, it is important to make sure that the last firmware version will be merged. The library version is used to be checked at GigaDevice MCU Site.
• This repository is managed mainly on Linux. This means that changes should be submited using Linux LF format. Usually running a similar command to find * type f -print0 | xargs -0 dos2unix -k should be enough.
• Make sure directory structure is respected.
• Directory names should be converted to lowercase.
• Exceptions should be discussed at review phase.

The gd32 standard peripheral API

The gd32 standard peripheral API define all information to access GigaDevice peripherals. The firmware library does not have namespaces and prefixes which easily results in name collision with ZephyrRTOS core and libraries. To avoid that situation, macros, enum values and function names should follow two general rules:

• Public API funtions must be prefixed with gd32_.
• Public defines and enum values must be uppercase and prefixed with GD32_.

The cmsis and riscv contents are not part of standard peripheral library and changes are treated as exceptions. This means that <firmware_library>.h> and system_<firmware_library>.h> files should reside on their own respective places instead in standard peripheral library directory.

Grace Period

Rework gd32 standard peripheral API is a huge step. To allow developers move forward a grace period was created. The grace period is available until gd32_api_convert script be available. When the script be available any new firmware library must be converted. The main objective of the script is to automate conversion process of all gd32 standard peripheral API.

Besides there is a grace period developers are obligated to solve any existent conflict. The conflict should follow gd32 standard peripheral API rules.

Current known conflict list

The conflicts at gd32 standard peripheral API are listed by the afected file(s). In general, a name is the conflict itself and that whould be reworked following the gd32 standard peripheral API rules.

• <firmware_library>_timer.h/c: timer_init() should be prefixed with gd32_ and become gd32_timer_init().
• <firmware_library>_can.h/c: all CAN_ macros that collide with any macro defined at /include/drivers/can.h should be prefixed with GD32_ and become GD32_CAN_*.

Exceptions

The exception list define macros and enum values that may have a different conflict resolution. See below list with the proposed solution:

• The BIT macro is already define in Zephyr. Fix using #ifndef: ```review

+#ifndef BIT #define BIT(x) ((uint32_t)((uint32_t)0x01U<<(x))) +#endif

- i2c-gd32 driver needs to know the clock frequency boundary. Fix it with
  two step work. First move I2CCLK_MAX and I2CCLK_MIN marco from i2c source
  file to header file. Then split the I2CCLK_MIN for each supported transfer
  mode.

- gd32l23x

  - `SystemInit` function in `system_gd32l23x.c` contain an invalid usage of
    `nvic_vector_table_set` function, just remove it.

  - `gd32l23x_libopt.h` file not exist, add it manually.

  - i2c have different implement than current gd32 i2c driver. no need to patch
    upper i2c speed requirement.

- gd32a50x

  - `SystemCoreClockUpdate` function contain an `pllmf` calculate error.  
    Fix by change `0xFU` to `RCU_CFG0_PLLMF`:
    ``` diff
      /* PLL multiplication factor */
      pllmf = GET_BITS(RCU_CFG0, 18, 21);
      pllmf += ((RCU_CFG0 & RCU_CFG0_PLLMF_4) ? 15U : 0U);
    - pllmf += ((0xFU == (RCU_CFG0 & RCU_CFG0_PLLMF)) ? 1U : 2U);
    + pllmf += ((RCU_CFG0_PLLMF == (RCU_CFG0 & RCU_CFG0_PLLMF)) ? 1U : 2U);
    ```
  - For debug this board, `pyocd` need a pack file from Gigadevice,
    But Gigadevice don't upload pack file to [keil packs repo](https://www.keil.com/dd2/pack/).
    Fix: Storage pack as `gd32a50x/support/GigaDevice.GD32A50x_DFP.1.0.0.pack`
    (Download from https://gd32mcu.com/cn/download/7?kw=GD32A5 -> GD32A50x AddOn)