.. _project_lowlevel_config:

用户工程底层配置
===============================

.. note::
  使用底层初始化和配置相关API需要在链接器中正确关联静态库 ``lowlevel``，并在用户程序(.c)中
  包含头文件 *lowlevel.h*。

本章节介绍用户工程代码需要根据实际运行场景进行配置的底层外设的设置方法(API), 一般推荐将
对应代码置于 *./src/app.c* 下属 ``app_init()`` 函数中。以下为典型的 *app_init()* 函数范例：

.. code-block::

  __attribute__((aligned(4), optimize("Os"))) void app_init(void)
  {
    /* 可选：设置系统时钟和NOR控制器时钟 */
    /* 配置和使能OSC_CORE时钟@100MHz */
    clock_osc_core_set(OSC_Core_Frequency_100MHz);
    clock_osc_core_enable();
    /* 使用OSC_CORE时钟1分频作为系统时钟源，即 System Clock = 100MHz *
    clock_sysclk_set(Sysclk_Sel_Osc_Core, Clock_Source_Div_1);
    /* 使用系统时钟2分频作为NOR控制器时钟，即 Norc Clock = 50MHz */
    clock_norclk_set(Clock_Source_Div_2);

    /* 必要：设置IOVCC电压 */
    sys_set_iovcc(__SYS_IOVCC_3v2);

    /* 可选：ADC初始化 */
    adc_sys_init(__ADC_VMIC_3v0, __ADC_Samplerate_16khz, __ADC_Gain_44db, Disable);

  }

系统时钟和NOR控制器时钟
-------------------------------

.. important::
  扩展阅读：:ref:`clock-source-module`

- 用户根据需要调用 ``clock_sysclk_set()`` 对系统时钟(System Clock)频率进行设置，从而确定CPU/SRAM/DMA的工作速度。根据用户对系统时钟频率的需求，用户可能需要首先配置和开启上游高频时钟源。
- 用户根据需要调用 ``clock_norclk_set()`` 对NOR Flash控制器速度进行设置，其来自系统时钟的直接分频。NOR速度不超过50MHz即可满足大多数场景需求。
- 若用户不调用 ``clock_sysclk_set()`` ，系统时钟由SDK默认配置为OSC_AUDIO时钟，即49.152MHz。
- 若用户不调用 ``clock_norclk_set()`` ，Nor Flash速度由SDK默认配置为系统时钟2分频。

API链接：

- :c:func:`clock_sysclk_set`
- :c:func:`clock_norclk_set`

IOVCC电压
-------------------------------

.. important::
  扩展阅读：:ref:`pmu-module`

- 用户需要根据实际方案的供电电压，调用 ``sys_set_iovcc()`` 对IOVCC进行设置，推荐配置如下：

.. image:: ../_static/kiwi-iovcc-vmic-setting.png
  :align: center

关闭IOVCC的方法：调用 :c:func:`pmu_iovcc_disable`。

ADC配置
-------------------------------

工程中若需要使用adc，必须调用 ``adc_sys_init()`` 对adc初始化。如使用gpadc或使用ADC采集mic音频。

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

API说明
----------------------

.. c:enum:: __sys_iovcc_t

  iovcc电压范围

  - *__SYS_IOVCC_2v0*: vmic电压2.0V
  - *__SYS_IOVCC_2v2*: vmic电压2.2V
  - *__SYS_IOVCC_2v4*: vmic电压2.4V
  - *__SYS_IOVCC_2v6*: vmic电压2.6V
  - *__SYS_IOVCC_2v8*: vmic电压2.8V
  - *__SYS_IOVCC_3v0*: vmic电压3.0V
  - *__SYS_IOVCC_3v2*: vmic电压3.2V
  - *__SYS_IOVCC_3v4*: vmic电压3.4V

.. c:enum:: __adc_vimc_t

  vmic电压范围

  - *__ADC_VMIC_2v0*: vmic电压2.0V
  - *__ADC_VMIC_2v2*: vmic电压2.2V
  - *__ADC_VMIC_2v4*: vmic电压2.4V
  - *__ADC_VMIC_2v6*: vmic电压2.6V
  - *__ADC_VMIC_2v8*: vmic电压2.8V
  - *__ADC_VMIC_3v0*: vmic电压3.0V
  - *__ADC_VMIC_3v2*: vmic电压3.2V
  - *__ADC_VMIC_3v4*: vmic电压3.4V

.. c:enum:: __adc_samplerate_t

  adc采样率

  - *__ADC_Samplerate_8khz*: adc采样率8khz
  - *__ADC_Samplerate_16khz*: adc采样率16khz
  - *__ADC_Samplerate_24khz*: adc采样率24khz
  - *__ADC_Samplerate_32khz*: adc采样率32khz
  - *__ADC_Samplerate_48khz*: adc采样率48khz

.. c:enum:: __adc_gain_t

  adc主通道增益

  - *__ADC_Gain_0db*: adc增益为0
  - *__ADC_Gain_17db*: adc增益为17db
  - *__ADC_Gain_20db*: adc增益为20db
  - *__ADC_Gain_24db*: adc增益为24db
  - *__ADC_Gain_28db*: adc增益为28db
  - *__ADC_Gain_32db*: adc增益为32db
  - *__ADC_Gain_36db*: adc增益为36db
  - *__ADC_Gain_40db*: adc增益为40db
  - *__ADC_Gain_44db*: adc增益为44db

.. c:function:: void adc_sys_init(__adc_vimc_t vmic,__adc_samplerate_t samplerate_khz,__adc_gain_t gain,soc_enable_t gpadc_en)

  adc初始化

  :param vmic: 指定vmic电压，__adc_vimc_t中选择。
  :param samplerate_khz: 指定主通道采样率，在__adc_samplerate_t中选择。
  :param gain: mic增益，__adc_gain_t中选择。
  :param gpadc_en: 次通道GPADC使能。Disable或Enable。
  :note: 不使用mic采集音频，只使用gpadc，对mic采样率和增益无要求

.. c:function:: void adc_sys_set_samplerate(__adc_samplerate_t samplerate_khz)

  修改adc通道采样率
  
  :param samplerate_khz: 修改采样率，在__adc_samplerate_t中选择。

.. c:function:: void adc_sys_set_gain(__adc_gain_t gain)

  adc主通道增益选择

  :param gain: 修改增益，在__adc_gain_t中选择。

.. c:function:: int32_t sys_set_iovcc(__sys_iovcc_t iovcc)

  调整iovcc电压

  :param iovcc: iovcc电压挡位，选参：__sys_iovcc_t
  :return: 0

.. c:function:: void sys_set_vmic(__adc_vimc_t vmic)

  调整iovcc电压

  :param vmic: 调整vmic电压,__adc_vimc_t中选择。
  :return: 0

.. c:function:: void sys_get_vcc()

  获取vcc电压

  :return: vcc上电压，单位毫伏（mV）
  :note: 调用改函数前必须先调用adc_sys_init(),确保adc初始化，否则函数会卡死。

.. c:function:: void adc_diff_mic_pin_init(void)

  初始化差分MIC的相关引脚(GPIO24~26)，并对外部电容进行充电。

  :return: 无。

.. c:function:: void adc_diff_mic_pin_deinit(void)

  去初始化差分MIC的相关引脚(GPIO24~26)。

  :return: 无。

.. c:function:: void adc_single_end_mic_pin_init(void)

  初始化单端MIC的相关引脚(GPIO24~25)，并对外部电容进行充电。

  :return: 无。

.. c:function:: void adc_single_end_mic_pin_deinit(void)

  去初始化单端MIC的相关引脚。

  :return: 无。