工作原理
===================================

    在编写解码器之前我们肯定先要了解协议解码器是如何工作的, 这对编写解码器是非常有帮助的。

    由于本文的重点是教大家写一个解码器, 所以这里只是简单梳理一下解码器的工作原理, 让大家在编写解码器时逻辑更加清楚。
    如果想要详细了解内部工作原理, 可以参考以下官方文档说明, 链接如下：

        - `https://sigrok.org/wiki/Protocol_decoder_API   <https://sigrok.org/wiki/Protocol_decoder_API>`_
        - `http://sigrok.org/wiki/Protocol_decoder_HOWTO  <http://sigrok.org/wiki/Protocol_decoder_HOWTO>`_

    ``libsigrokdecode`` 原理是将 ``python脚本`` 嵌入到代码中, 使底层C库可以调用 ``python 脚本``, ``python 脚本`` 同时也可以调用C库提供的函数、变量等等。

    **libsigrokdecode** 库可以分为以下两层 :

    - 底层 C 库
    - 上层 协议解码器 (python 脚本)

    **底层 C 库** 是整个解码器的核心, 提供 ``python`` 运行环境, 可以让 ``python 脚本`` 和 ``C库`` 之间相互调用。
    最重要的就是提供一个 ``sigrokdecode`` 模块, 所有协议解码器都是基于这个模块而创建。
    当然这个模块还为我们提供了一些其他的函数和变量, 在下面章节会详细介绍。

    **协议解码器** 其实就是 ``python 脚本文件``, 也就是我们即将编写的 ``解码器``。
    正点原子逻辑分析仪的协议分析和处理都是由 ``解码器 (python 脚本)`` 去做的, 我们本文最终的目的就是为了编写这个 ``python 脚本文件`` 。

    .. include:: style.rst 

    :blue:`这里简单梳理一下解码器 ( python 脚本) 函数的调用流程, 当正点原子上位机开始解码样本数据时, 解码器函数调用流程如下:`

    #. 实例化解码器中的 ``Decoder类``  , 如果解码器中提供了 ``__init__(self)`` 函数,  将会自动被调用
    #. 调用解码器中的 ``metadata(self, key, value)`` 函数, 如果解码器存在这个函数, 就会被调用
    #. 调用解码器中的 ``start(self)`` 函数
    #. 调用解码器中的 ``decode(self)`` 函数, 开始解码样本数据
    #. 当上位机重置当前解码器,重新开始解码时, ``reset(self)`` 函数将会被调用