Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/zephyrproject-rtos/hal_gigadevice

HAL for GigaDevice devices
https://github.com/zephyrproject-rtos/hal_gigadevice

hal module

Last synced: about 2 months ago
JSON representation

HAL for GigaDevice devices

Awesome Lists containing this project

README 

        
# 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](https://github.com/Nuclei-Software/NMSIS/) 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](https://docs.zephyrproject.org/latest/contribute/index.html).



# 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](http://www.gd32mcu.com/en/download/).

 - 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 `.h>` and

`system_.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.



 - `_timer.h/c`: `timer_init()` should be prefixed with

   `gd32_` and become `gd32_timer_init()`.

 - `_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)