.. _design_soc_gd32vf103:

GD32VF103 SoC
=============

GD32VF103 SoC is the first general RISC-V MCU from `GigaDevice Semiconductor`_
in the world which is based on Nuclei RISC-V Process Core.

If you want to learn more about it, please click
https://www.gigadevice.com/products/microcontrollers/gd32/risc-v/

.. _design_soc_gd32vf103_overview:

Overview
--------

The GD32VF103 device is a 32-bit general-purpose micro controller based on
the RISC-V core with best ratio in terms of processing power, reduced power
consumption and peripheral set.

The RISC-V processor core is tightly coupled with an Enhancement Core-Local
Interrupt Controller(ECLIC), SysTick timer and advanced debug support.

The GD32VF103 device incorporates the RISC-V 32-bit processor core operating at
108MHz frequency with Flash accesses zero wait states to obtain maximum efficiency.

It provides up to 128KB on-chip Flash memory and 32KB SRAM memory.

An extensive range of enhanced I/Os and peripherals connect to two APB buses.

The devices offer up to two 12-bit ADCs, up to two 12-bit DACs, up to four general
16-bit timers, two basic timers plus a PWM advanced timer, as well as standard and
advanced communication interfaces: up to three SPIs, two I2Cs, three USARTs, two UARTs,
two I2Ss, two CANs, an USBFS.

The SoC diagram can be checked as below :ref:`figure_design_soc_gd32vf103_1`

.. _figure_design_soc_gd32vf103_1:

.. figure:: /asserts/images/gd32vf103_soc_diagram.png
    :width: 80 %
    :align: center
    :alt: GD32VF103 SoC Diagram

    GD32VF103 SoC Diagram


.. _design_soc_gd32vf103_boards:

Supported Boards
----------------

In Nuclei SDK, we support the following four boards based on **GD32VF103** SoC, see:

* :ref:`design_board_gd32vf103v_rvstar`, default Board when this SoC selected.
* :ref:`design_board_gd32vf103v_eval`
* :ref:`design_board_sipeed_longan_nano`
* :ref:`design_board_ttgo_t_display`

.. _design_soc_gd32vf103_usage:

Usage
-----

If you want to use this **GD32VF103** SoC in Nuclei SDK, you need to set the
:ref:`develop_buildsystem_var_soc` Makefile variable to ``gd32vf103``.

Extra make variables supported only in this SoC:
  * **SYSCLK**: ``108000000`` by default, means 108MHz system clock will be selected during SystemInit function,
    it will define macro ``SYSTEM_CLOCK=$(SYSCLK)`` which is used in ``system_gd32vf103.c``, such as SYSTEM_CLOCK=108000000.
  * **CLKSRC**: hxtal by default, available choices are ``hxtal`` and ``irc8m``, means select to use HXTAL PLL
    or IRC8M PLL, it will define macro ``CLOCK_USING_$(CLKSRC)``, such as ``CLOCK_USING_HXTAL``
  * **USB_DRIVER**: none usb driver is selected by default. You can choose ``device`` or ``host`` or ``both``
    to select device, host or both driver source code, and in application code, user need to provide usb host
    or device initialization code and header files.

.. code-block:: shell

    # Choose SoC to be gd32vf103
    # the following command will build application
    # using default gd32vf103 SoC based board
    # defined in Build System and application Makefile
    make SOC=gd32vf103 clean
    make SOC=gd32vf103 all

.. note::

    * Since this ``gd32vf103`` SoC is a real chip, it is using Nuclei RISC-V
      N205 core, so the **CORE** is fixed to ``n205``
    * **USB_DRV_SUPPORT** make variable is no longer available, please use **USB_DRIVER** variable to select different usb driver.
    * You need to provide ``usb_conf.h/usbd_conf.h/usbh_conf.h`` file in you application code,
      if you want to use the usb driver of gd32vf103, see https://github.com/Nuclei-Software/nuclei-sdk/pull/54

.. _GigaDevice Semiconductor: https://www.gigadevice.com/