[RFC] GigaDevice Vendor Support

[nandojve]

Introduction

There is community interest to add support to GigaDevice SoC Vendor in Zephyr. Community members have intentions to support both ARM and RISC-V SoC's. This RFC was opened to serve as an umbrella to help community and Zephyr members know the initiatives.

Problem description

Currently there are some attempts to introduce support in Zephyr:
#36832
#36833
#34970
#34971

The main discussion was conducted at #34971, which is TSC tagged.

Proposed change

Give an overview about all pieces required to add GigaDevice SoC Vendor in Zephyr.

Detailed RFC

In this section of the document the target audience is the dev team. Upon reading this section each engineer should have a rather clear picture of what needs to be done in order to implement the described feature.

There are two content groups that need to be addressed: hal and drivers.

Vendors HAL

There are two vendors dependencies that should be addressed: hal_gigadevice and NMSIS module.

The HAL GigaDevice

This HAL is necessary to keep tracking with manufacturer firmware versions. The vendor provide an API that abstracts registers access and it is well tested. The documentation and firmware versions can be found at gd32mcu.com web site.

Some SoC series may have aditional features. This is the reason for some series have different drivers versions. For instance, F403 series not share same drivers versions with other SoC from the same series.
To address those details a directory structure is proposed. It is composed by default Zephyr module structure plus each SoC series directory. The below example uses gd32f403 ARM series and gd32vf103 RISC-V series:

├── gd32f403
│   ├── cmsis
│   │   └── gd
│   │       └── gd32f403
│   │           ├── include
│   │           │   ├── gd32f403.h
│   │           │   └── system_gd32f403.h
│   │           └── source
│   │               └── system_gd32f403.c
│   ├── README.h
│   └── standard_peripheral
│       ├── include
│       │   ├── gd32f403_adc.h
│       │   ├── ...
│       │   └── gd32f403_wwdgt.h
│       └── source
│           ├── gd32f403_adc.c
│           ├── ...
│           └── gd32f403_wwdgt.c
├── gd32bf103
│   ├── README.h
│   ├── riscv
│   │   ├── include
│   │   │   ├── gd32vf103.h
│   │   │   └── system_gd32vf103.h
│   │   └── source
│   │       └── system_gd32vf103.c
│   └── standard_peripheral
│       ├── include
│       │   ├── gd32vf103_adc.h
│       │   ├── ...
│       │   └── gd32vf103_wwdgt.h
│       └── source
│           ├── gd32vf103_adc.c
│           ├── ...
│           └── gd32vf103_wwdgt.c
└── zephyr
    └── module.yml

The content of CMSIS and NMSIS should be replaced by proper Zephyr structure over time. In the ARM case, it is straightforward to bring up any board. The NMSIS will follow the decision of NMSIS module.

The remaining content of firmware package from vendor should not be added. The reason that is for Zephyr use case only the peripheral definitions are the essential component.

NMSIS module from Nuclei Systems

Nuclei System Technology is a RISC-V processor IP and solution provider. Nuclei Systems collaborated with GigaDevice for the first RISC-V based general-purpose MCU in the world — GD32VF103. The NMSIS is a similar core with a structure similar to ARM CMSIS. More information at www.nucleisys.com and Nuclei-Software.

It is not 100% clear yet how integrate this structure into Zephyr. The main discussion was initially made at #34971. The Nuclei Systems suggested initially that gd32vf103 drivers should be at same place of NMSIS. However, this can be a problem to share drivers and support more Nuclei Systems newer IPs. Besides GD32VF103 directory contains the RISCV directory the intention is not use that content and can be keep it for historical reasons.

Peripheral Drivers

The GD32 platform shares in many cases the same peripheral IPs. This means that community members should check for compatibility between some SoC series. The suggested list is:

• gd32e103
• gd32f403
• gd32vf103

Dependencies

The current dependencies are add module NMSIS from Nuclei Systems and HAL gigadevices. Those are the fundamental base to create the future port and Zephyr drivers.

Task List

The below task list is a suggestion plan to coordinate work to enable minimal support on Zephyr:

Essential List

• Add hal_gigadevice
  [RFC] Add hal_gigadevice to support GigaDevice SoC Vendor #38727
  west.yml: Add hal gigadevice #38658
  ARM: Introduce gigadevice gd32f403 #38661
• Add NMSIS module Add support for Nuclei ICs in the main tree, in soc/riscv/ (@soburi)
• Add GigaDevice vendor prefix
  dts: bindings: vendor-prefixes: Add gigadevice prefix #38659
  ARM: Introduce gigadevice gd32f403 #38661
• Introduce F403 SoC and Zephyr ARM structure
  ARM: Introduce gigadevice gd32f403 #38661
• • Introduce GD32F403E-EVAL board (with Linux GD-Link Program/Debug and gd32isp flasher)
    ARM: Introduce gigadevice gd32f403 #38661
• Introduce VF103 SoC and Zephyr RISC-V structure
  boards: Add support GigaDevice GD32V SoC #34970
• • Introduce SiPeed Longan Nano/Nano Lite boards
    boards: Add support GigaDevice GD32V SoC #34970
• Add gd32_isp_console runner and update GD32F403E-EVAL board
  scripts: runner: Introduce gd32isp flash runner #38660
• USART Minimal Driver
  ARM: Introduce gigadevice gd32f403 #38661
• RCU Clock Control Driver ( @nandojve @gmarull: https://github.com/teslabs/zephyr/tree/clock-control-gd32)
• ECLIC
  boards: Add support GigaDevice GD32V SoC #34970
• GPIO Driver
  gpio: gd32: initial support #40676
• • EXTI Driver
    gpio: gd32: initial support #40676
• PINCTRL Driver
  pinctrl: initial support for GD32 #39974
• USART Driver
• • Enable RCU Support
• • Enable PINCTRL Support
    pinctrl: initial support for GD32 #39974
• • Enable Multi Instance Support
• • Add Interrupt Driven Mode
    drivers: serial: gd32: Add interrupt support #39897

Boards/SoC

• GD32A503V_EVAL
  Boards: arm: gd32a503v_eval: introduce gd32a503v_eval board #52774
• GD32E103V-EVAL
  boards: arm: Add gd32e103v_eval board #36833
• GD32E507Z_EVAL
  boards: gd32e507z_eval: add initial support #49547
• GD32E507V-START
  Add initial support for GD32E50X and GD32E507V-START #48663
• GD32F350R_EVAL
  boards: arm: Introduce gd32f350r_eval board #40283
• GD32F405i_EVAL
  Add GD32F405xx series SoCs #41156
• GD32F407V-START
  boards: arm: gd32f407v_start: Add initial support for gd32f407v_start #49085
• GD32F450I_EVAL
  Introduce GD32F4xx serial SoCs with GD32F450i_EVAL board #39909
  boards: arm: GD32F450I-EVAL: add initial support #39958
• GD32F450V-START
  boards: gd32f450v_start: add initial support #49593
• GD32F450Z_EVAL
  boards: arm: gd32f450z_eval: add initial support #45346
• GD32F470I_EVAL
  boards: arm: gigadevice: Initial support for gd32f470ik #46894
• GD32L233R-EVAL
  Add GD32L233R-EVAL board support #52654
• GD32VF103V_EVAL
  boards: riscv: gd32vf103v_eval: initial support #41483
• GD32VF103C_STARTER
  boards: riscv: introduce gd32vf103c_starter board #43439

Driver Extended List

The extended list is not limited and community is encouraged to edit and add/remove entries. It is recommended complete the essential list before start with any item from the extended list to avoid unnecessary future rework.

• ADC Driver
  Drivers: ADC: Introduce gd32 adc driver #42215
• BKP Driver
• CAN Driver
  Drivers: CAN: Introduce CAN driver for gd32 #43342
• CRC Driver
• CTC Driver
• DAC Driver
  drivers: dac: Introduce gd32 driver #41152
• DCI Driver
• DMA Driver
  drivers: dma: Add GD32 DMA driver  #47501
  dts: bindings: dma: gd32: Redesign DMA node's cell properties #48756
• ENET Driver
  drivers: ethernet: gd32: GigaDevice ENET support #47227
• EXMC Driver
• FMC Driver
  drivers: flash: Introduce gd32 flash controller driver #42809
• I2C Driver
  drivers: i2c: Introduce GD32 I2C driver #41506
• PWM Driver
  drivers: pwm: add GD32 PWM driver #41173
• RTC Driver
• SDIO Driver
• SPI Driver
  drivers: spi: Initial support for GD32 spi #40416
  drivers: spi: gd32: support interrupt-driven mode #47499
  drivers: spi: gd32: Add support DMA transfer  #47504
• Timer Driver
  drivers: counter: add support for GD32 timer #51955
• TLI Driver
• TRNG Driver
• USB Driver
  drivers: usb: Add OTGFS USB device controller #63585
• WDT Driver
  drivers: watchdog: Add support for the GD32 watchdog timers #41673

Other drivers

• Reset Driver
  drivers: reset: gd32: add initial support #49378

Enhancements

• GD32: Use clocks instead rcu-periph-clock property  #49074

Note to Community

The GigaDevice and Nuclei System community are encouraged to edit this RFC proposal.

CC: @feilongfl @soburi @fanghuaqi
Zephyr: @galak @carlescufi @olofj @cfriedt @kgugala @MaureenHelm @katsuster

[fanghuaqi]

Hi @nandojve , your RFC is very clear about this GD devices support, since this GD32VF103 device and its peripheral drivers are released before NMSIS born, and the source code about Nuclei RISC-V core drivers are using very old Nuclei RISC-V support code, @GigaDevice-Semiconductor released their source code of gd32vf103 in github https://github.com/GigaDevice-Semiconductor/GD32VF103_Firmware_Library, but it is not yet actively developed, and receiving any PR about it.

Nowadays, more and more of our customers are familiar with NMSIS, and willing to following the source code structure we present in NMSIS and Nuclei-SDK. HAL for NMSIS will be necessary for future silicon vendors to port their devices based on Nuclei RISC-V core.

Thanks
Huaqi

[soburi]

Hi, @nandojve,
Good summary about gd32, great!

Putting All SoC drivers into a single hal_gigadevice is a good suggestion.

There is various way to How to introduce NMSIS to zephyr.
I think that it is good to separate it into "hal_nuclei" as an external module.

Only GD32VF103 use NMSIS at this time, so containing NMSIS into the GD32VF103 directory in hal_gigadevice is also one possible way, I think. (I propose to the GigaDevice firmware updating with NMSIS as GigaDevice-Semiconductor/GD32VF103_Firmware_Library#2. It may be usable.)
Or it is also conceivable to place on subsys/portability like as CMSIS.

[nandojve]

Hi @fanghuaqi , @soburi ,

Thank you for your comments.

I'm favor to use nmsis and I have some doubts about create a hal_nuclei.

I'm not so sure about split peripheral drivers between two distinct projects. My concern is that any peripheral driver API changes will require modifications at both places:hal_gigadevice and hal_nuclei. The sync process can be long because can delay Zephyr code review and acceptance. Besides that it will be two distinct git history.

I'll suggest that Nuclei Systems code should be used same way ARM code is. I mean, have a nmsis module which can be sync directly from https://github.com/Nuclei-Software/NMSIS and add proper vendor specific code that follows nmsis layout. The majority of users already know about ARM code structure. This is an advantage that should be explored.

Let's assume nmsis module for instance:

• The gigadevice vf103 RISCV directory could be replaced by an NMSIS directory with SoC specific code. This add a linear path inside hal_gigadevice that any future user can understand how gigadevice was added to Zephyr.
• Any other vendor that use nmsis will benefits from a structure already in place. I mean, nmsis module will be at Zephyr main tree and it is just need add nmsis SoC vendor specific layout.
• The nmsis vendor specific code could live at <zephyr>/soc/riscv/NMSIS/gd32vf103 (just an example) too. This option can share more code between different nmsis vendors/SoC. Eventually, it can be a mix of both (hal_any-vendor + <zephyr>/soc).

Suggested layout:

  ...
   ├── modules
   │    ├── hal_gigadevice
   │    │    └── GD32VF103
   │    │         ├── RISCV
   │    │         │   └── ...
   │    │         └── NMSIS
   │    │              └── ... /* non zephyr , vendor specific code */
   │    └── nmsis
   │        └── ... /* fork from  https://github.com/Nuclei-Software/NMSIS */
   └──zephyr
         └── soc
              └── riscv
                   └── nmsis
                        ├── ... /* zephyr specific */
                        └── gd32vf103
                             └── ... /* zephyr specific */

I would like know your opinion on this topic.

[soburi]

@nandojve

I think the structure you suggested is preferable.

...
├─ modules
│      └─ nmsis
│           └─ ... /* fork from https://github.com/Nuclei-Software/NMSIS */

As you pointed out, it can be referenced from multiple vendors and is consistent.
Synching with https://github.com/Nuclei-Software/NMSIS makes it easy to maintain it.

(I thought it would be better to separate NMSIS into vendors since it is specific to nuclei.
I think this structure will allow it to be correctly sharable between multiple vendors.)

[cameled]

Add interrupt support for gd32 serial driver on #39897.
It's still in progress, suggestion are welcome.

[cameled]

GD32 Firmware library function name not have prefix or suffix to make it unique, Maybe we should use some trick to avoid name conflict.

I find hal_espressif use a link time symbol, e.g. https://github.com/zephyrproject-rtos/hal_espressif/blob/zephyr/zephyr/esp32s2/src/linker/esp32s2.rom.alias.ld