JL_MIO功能
=========================================

    | JL_MIO用于在音频文件中添加一些波形信息，我司芯片环境中可以使用这些波形信息进行相应的控制。
    | mio文件制作详情见JLmio使用说明文档，本章介绍mio在SDK中的应用。

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

JLmio原理
################################

    | mio原理是通过JLmio.exe工具将对应歌曲 自定义 对应时刻 生成对应pwm通道或者IO通道的波形信息文件。
    | 小机通过播放该歌曲的时候，读取mio文件，获取出歌曲对应位置的波形信息（如pwm通道对应时刻的周期、IO通道对应时刻的电平）
    | 获取出对应的波形信息后，通过相应的run接口去设置对应timer的pwm周期或者io的电平。

.. note::
    | mio的pwm通道默认使用timer0，且在SDK里默认限制了PWM通道（MIIO_MAX_CHL_PWM）的个数，用户可以自行调整pwm通道个数和修改初始化、run接口。
    | 同理IO通道（MIO_MAX_CHL_IO）
    | 整个mio驱动均已开放，用户可根据自身实际情况修改初始化或run函数。

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

JLmio一般流程
################################

使用JLmio.exe创建mio文件
***************************************************************

    详情见JLmio使用说明。生成的mio文件会在工具目录的Data文件夹下；

    .. image:: 1_mio_file.png
        :alt: "mio文件生成位置“
        :align: center
    .. centered:: 图1 mio文件生成位置

使用打包工具将音频文件与所制成的mio文件放于同一目录下
***************************************************************

    打包工具请参考2.3打包工具使用，注意：音频文件需要与生成的mio文件放于同一目录下；生成目录文件时，不能将mio放在目录的第一个文件位置处，否则音乐播放可能会失败！

    .. image:: 2_mio_file.png
        :alt: "mio文件打包位置顺序注意事项“
        :align: center
    .. centered:: 图2 mio文件打包位置顺序注意事项

    .. image:: 3_mio_file.png
        :alt: "mio文件正确打包位置顺序示意图“
        :align: center
    .. centered:: 图3 mio文件正确打包位置顺序示意图


在download.bat中添加相应mio文件夹
***************************************************************

    在download.bat中添加所打包的包含音频文件与mio文件的文件夹目录dir_mio，放在-res 参数后面即可；

    .. image:: 4_mio_dir.png
        :alt: "将dir_mio文件夹添加进下载目录中“
        :align: center
    .. centered:: 图4 将dir_mio文件夹添加进下载目录中

在app_music.c中添加相应mio文件夹
***************************************************************

    在app_music中添加所打包的包含音频文件与mio文件的文件夹目录，可放在任意位置并用按键进行文件夹切换；

    .. image:: 5_mio_dir_add.png
        :alt: "在app_music中添加mio文件夹“
        :align: center
    .. centered:: 图5 在app_music中添加mio文件夹

在mio_api.c中将相应宏开关打开
***************************************************************

    | 在mio_api中将MIO_EN宏定义打开即可，SDK默认使用1路PWM（PA12）以及2路IO口（PA1与PA2）作为示例，用户可自行添加并完善功能；
    | 注意：

        1. mio功能会占用相应引脚，若不用mio功能需关闭改宏开关。
        2. MIO_IO引脚 与 偏移配置 如下图意思为 PA1开始，若mio文件有3个IO通道，则从PA1开始往下设置，PA1、PA2、PA3作为MIO的IO通道输出。

    .. image:: 5_mio_pwm_io_define.png
        :alt: "mio_pwm与mio_io宏定义配置“
        :align: center
    .. centered:: 图6 mio_pwm与mio_io宏定义配置

^^^^^^^^^^^^^^^^^^^^


JLmio接口介绍
################################

u32 mio_a_pwm_init(u32 chl)
***************************************************************

    此函数实现mio_pwm通道输出的初始化，其中参数： ::

        1、chl：需要进行初始化的pwm通道编号；
        2、返回值：0：成功；其他值：errno-base.h查看

u32 mio_a_pwm_run(u32 chl， u32 pwm_var)
***************************************************************

    此函数实现mio_pwm通道输出，其中参数： ::

        1、chl：正在输出的pwm通道编号；
        2、pwm_var：mio文件中读取到的pwm数值，可用于配置pwm输出占空比；
        3、返回值：0：成功；其他值：errno-base.h查看

u32 mio_a_pwm_uninit(u32 chl)
***************************************************************

    此函数实现mio_pwm通道输出的注销，其中参数： ::

        1、chl：需要进行注销的pwm通道编号；
        2、返回值：0：成功；其他值：errno-base.h查看

u32 mio_a_io_init(u32 mask)
***************************************************************

    此函数实现mio_io通道输出的初始化，其中参数： ::

        1、mask：需要进行初始化的io通道（mio最多支持（16-pwm通道）路io通道）；
            ①　mio文件中设置的每一个io通道依次对应mask中每个位；
            ②　如单io通道mask会传入0x01，双io通道mask会传入0x3，以此类推；
        2、返回值：0：成功；其他值：errno-base.h查看

u32 mio_a_io_run(u32 mask， u32 io_ver)
***************************************************************

    此函数实现mio_io通道输出，其中参数： ::

        1、mask：需要进行初始化的io通道；
        2、io_ver：mio文件中读取到的io数值，可用于配置IO口的电平；
        3、返回值：0：成功；其他值：errno-base.h查看

u32 mio_a_io_uninit(u32 mask)
***************************************************************

    此函数实现mio_io通道输出的注销，其中参数： ::

        1、mask：需要进行注销的io通道（mio最多支持（16-pwm通道）路io通道）；
            ①　mio文件中设置的每一个io通道依次对应mask中每个位；
            ②　如单io通道mask会传入0x01，双io通道mask会传入0x3，以此类推；
        2、返回值：0：成功；其他值：errno-base.h查看