一、 前言

在DSView安裝目錄下，有一個(gè)decoders文件夾，里面有許多目錄是以各種協(xié)議名稱命名的。每個(gè)目錄下有至少2個(gè)擴(kuò)展名為.py的文件，這些都是python代碼文件。在linux系統(tǒng)下，decoders目錄位于”/usr/local/share/libsigrokdecode4DSL”下。
DSView通過(guò)底層python解釋器執(zhí)行python代碼，對(duì)邏輯分析儀的數(shù)據(jù)進(jìn)行解析，按各種算法得出需要的結(jié)果。每個(gè)協(xié)議目錄下必須存在兩個(gè)文件：

1. _init_.py，用于發(fā)現(xiàn)模塊，這個(gè)文件名左右兩邊各有兩個(gè)下劃線，這個(gè)細(xì)節(jié)要注意；
2. pd.py，用于編寫(xiě)主要的邏輯代碼；
   這兩個(gè)文件如何編寫(xiě)，請(qǐng)仔細(xì)閱讀下面的內(nèi)容。在1.2.0以上的新版本DSView中，decoders下的有一個(gè)名為example目錄為示例代碼。

二、python入門(mén)

python語(yǔ)言是一個(gè)解釋執(zhí)行的語(yǔ)言。在官方網(wǎng)站下載并安裝好python，就可以進(jìn)行開(kāi)發(fā)了。
新建一個(gè)文本文件，里邊輸入一行文字：
print('Hello,world!')
保存為 test.py，然后在命令行里輸入
python test.py
將會(huì)輸出“Hello,world!”
這里的python入門(mén)只是為了幫助一些讀者能夠順利閱讀部分協(xié)議代碼，它所講的python知識(shí)還不夠全面和深入，需要讀者自行通過(guò)其它方式獲得python資料，以便提升自己的python編程能力。

1. 變量定義
   age = 1
name = “Tom”
2. 數(shù)值
   1, 1.11, 1000等都屬數(shù)值型數(shù)據(jù)
3. 字符串
   以單引號(hào)或雙引號(hào)括起來(lái)的一串字符，表示字符串，如
   ’abc’
   “name”
4. 列表
   []
[1,2,3]
[1,”abc”,”name”,[7,8,9]]
   列表里的元素用逗號(hào)隔開(kāi)，上面的第一個(gè)列表是空列表，第二個(gè)列表全是數(shù)字，第三個(gè)列表有多種類型的元素，有數(shù)值、字符串、列表。
   a = [1,2,3]
   變量a是一個(gè)列表，通過(guò)a[n]方式讀取列表里的元素。n的取值從０開(kāi)始到不超過(guò)且不等于列表長(zhǎng)度的整數(shù)
   a[2] = 666
   將第３個(gè)元素設(shè)置成666，列表里的內(nèi)容可修改
   i = a[1]
   取列表a的第二個(gè)元素賦給變量i
5. 字典
   d = {‘a(chǎn)ge’:20, ‘name’:’Tome’, ‘data’:[7,8,9]}
   字典里的每一項(xiàng)用一對(duì)鍵和值表示。如’age’:20
   d[‘name’] = ‘Same’
   將字典d的name值設(shè)置成’Same’
   s = d[‘name’]
   取字典d的name值賦給變量s
   字典里的鍵名可以是數(shù)字、字符串、元組等類型，如：
   {1:'張三'}
{'name':''張三"}
{(1,2,3): "張三"}
6. 元組
   ()
(1,2,3)
(2,’abc’)
   元組跟列表一樣，不同的是用()括起來(lái)，元組只能讀，不能修改。
   注意：當(dāng)元組只有一個(gè)項(xiàng)時(shí)，要多打一個(gè)逗號(hào)，如：
   (1,)
7. 函數(shù)
   def call(): #普通函數(shù)
def call(self): #類成員函數(shù)，第一個(gè)參數(shù)是必須的
def call(a,b,c): #帶三個(gè)參數(shù)的函數(shù)

三、新建協(xié)議

1. 新建協(xié)議目錄
   找到存放所有協(xié)議的decoders目錄。widnows下，它在DSView的安裝目錄里;
   在linux下,它在
   /usr/local/share/libsigrokdecode4DSL
   打開(kāi)decoders目錄，新建一個(gè)子目錄，并給目錄取名字，要求是能體現(xiàn)協(xié)議名稱的名字。這里，我們的示列協(xié)議名為”lala”。
2. __init.py文件
   在bala目錄下新建文件“__init.py”，加入一行如下代碼并保存:

from .pd import Decoder

1. pd.py文件
   在bala目錄下，建新pd.py文件，用來(lái)編寫(xiě)主要的代碼。

四、框架代碼模板

??以下是解碼協(xié)議代碼框架，寫(xiě)在pd.py文件里。所有協(xié)議的代碼核心部分是一樣的。
下面從c模塊繼承一個(gè)類：

import sigrokdecode as srd 
class Decoder(srd.Decoder): 
    api_version = 3    
    ##協(xié)議標(biāo)識(shí)，必須唯一
    id = 'bala'
    ##協(xié)議名稱, 不一定要求跟標(biāo)識(shí)一致
    name = 'bala'
    ##協(xié)議長(zhǎng)名稱
    longname = 'bala protocal'
    ##簡(jiǎn)介內(nèi)容
    desc = 'This is an example'
    ##開(kāi)源協(xié)議
    license = 'gplv2+' 

  #第一句是導(dǎo)出c底層的模塊
  #第二句是定義一個(gè)類，繼承自c底層的類

    inputs = ['logic']
    #接收的輸入的數(shù)據(jù)源，默認(rèn)是是邏輯分析儀數(shù)據(jù)
    #在多層協(xié)議模式下，可使用上層協(xié)議的輸出名

    outputs = ['bala']
    #輸出的數(shù)據(jù)源名，在多層協(xié)議模式下，
    #其它協(xié)議可以使用這個(gè)輸出名指定數(shù)據(jù)輸入來(lái)源

    tags = ['Embedded/industrial']
    #協(xié)議的適用范圍標(biāo)簽

    channels = (
        {'id': 'c1', type:0, 'name': 'c1', 'desc': 'chan1-input'}, 
    ) 
    #必須要綁定的通道
    #id:通道標(biāo)識(shí), 任意命名
    #'type':類型，有： -1:COMMON,0:SCLK,1:SDATA,2:ADATA 
    #name:標(biāo)簽名
    #desc:該通道的說(shuō)明

    optional_channels = (
        {'id': 'c2', type:0, 'name': 'c2', 'desc': 'chan２-input'}, 
    )
    #可選通道，其它跟上面的一樣

    options = (    
        {'id': 'debug_bits','desc': 'Print each bit', 'default': 'no', 'values': ('yes', 'no')},     
        {'id': 'wordsize',  'desc': 'Data wordsize',  'default': 0},
    )
    #提供給用戶通過(guò)界面設(shè)置的參數(shù)  
    #根據(jù)業(yè)務(wù)需要來(lái)定義
    #通過(guò)'self.options[id]'取值，id就是各個(gè)項(xiàng)的id值,
    #比如下面的'wordsize'
    #上面第一項(xiàng)是下拉框，第二項(xiàng)是輸入框

    annotations = (
        ('1', 'data1', 'test1'),
        ('2', 'data2', 'test2'),
        ('222', 'data3', 'test3'),
    )
    #解析結(jié)果項(xiàng)定義
    #annotations里每一項(xiàng)可以有2到3個(gè)屬性，
    #當(dāng)有３個(gè)屬性時(shí)，第一個(gè)表示類型
    #類型對(duì)應(yīng)0-16個(gè)顏色，當(dāng)類型范圍
    #在200-299時(shí)，將繪制邊沿箭頭

    annotation_rows = (    
        ('lab1', 'row1', (0,)),
        ('lab2', 'row2', (1,2)),
    )
    #解析結(jié)果行定義
    #(0,)表示可輸出第1個(gè)定義的annotations類型
    #(1,2)表示可輸出第2個(gè)和第3個(gè)定義的annotations類型

    def __init__(self):
        self.reset()
     #這里調(diào)用reset函數(shù)，完成一些變量的初始化
     #構(gòu)造函數(shù)，自動(dòng)被調(diào)用，
     #這里調(diào)用reset函數(shù)完成一個(gè)變量的初始化

    def reset(self):
        self.count = 0
    #初始化函數(shù)，這里定義類的私有變量

    def start(self):
        self.out_ann = self.register(srd.OUTPUT_ANN)
    #這里注冊(cè)消息類型
    #開(kāi)始執(zhí)行解碼任務(wù)時(shí)，由c底層代碼自動(dòng)調(diào)用一次
    #這里，完成一些解碼結(jié)果項(xiàng)annotation類型的注冊(cè)
    #有: OUTPUT_ANN、OUTPUT_PYTHON、
    #OUTPUT_BINARY、OUTPUT_META 
    #register函數(shù)是c底層類提供的

    def put_ann(self,a,b,ann,data): 
        self.put(a, b, self.out_ann, [ann, data])
    #輸出內(nèi)容
    #a,b為采樣位置的起點(diǎn)和終點(diǎn)
    #ann為annotations定義的項(xiàng)序號(hào)
    #data是一個(gè)列表，列表里有１到３個(gè)字符串，它們將顯示到屏幕
    #annotation輸出到哪一行由annotation_rows決定
    #self.out_ann就是上面注冊(cè)的消息類型了
    #self.put是c底層類提供的函數(shù)

    def decode(self):
        while True:
            (a,b)=self.wait({0:'r'})
    #一直調(diào)用，直到所有數(shù)據(jù)處理完
    #解碼任務(wù)開(kāi)始時(shí)由c底層代碼調(diào)用
    #這里不斷循環(huán)等待所有采樣數(shù)據(jù)被處理完成

    #wait函數(shù)參數(shù)詳解:
    #wait函數(shù)可帶參數(shù)，也可以不帶參數(shù)，
    #不帶參數(shù)時(shí)將返回每個(gè)采樣數(shù)據(jù)
    #參數(shù)'{0:'r'}'， 0表示匹配channels第１
    #項(xiàng)綁定的通道，r表示查找向上邊沿
    #wait函數(shù)可傳多個(gè)條件，
    #與條件：{0:'f',１:'r'}，
    #或條件：[{0:'f'},{１:'r'}]
    #h:高電平，l:低電平，r:向上邊沿，
    #f:向下邊沿，
    #e:向上沿或向下沿，
    #n:要么０，要么１
    #wait函數(shù)前的變量(a,b)，數(shù)量由定義
    #的channels里的通道數(shù)決定，包括可選通道
    #例如：共定義了４個(gè)通道，
    #則變成(a,b,c,d) = self.wait()

    #c底層提供了兩個(gè)屬性:
    self.samplenum 
    #當(dāng)前wait()調(diào)用匹配結(jié)束的采樣點(diǎn)位置

    self.matched
    #是一個(gè)uint64類型數(shù)值，
    #表示０到63個(gè)通道的匹配信息，
    #通過(guò)位運(yùn)算來(lái)獲取具體信息。

到這里，解碼協(xié)議代碼框架模板結(jié)束。

五、應(yīng)用示例

??在上面代碼框架的基礎(chǔ)上，我們接下來(lái)實(shí)現(xiàn)一個(gè)簡(jiǎn)單的例子。具體是，通過(guò)解碼某一通道的數(shù)據(jù)，從一個(gè)向上邊沿開(kāi)始到向下邊沿結(jié)束，輸出采樣點(diǎn)差值信息。奇數(shù)次輸出放在第二行，偶數(shù)次輸出放在第一行。具體編碼和說(shuō)明如下：

    def decode(self):     
        times = 0 
        rising_sample = 0 
        flag_arr = [{0:'r'}, {0:'f'}] 
        flag_dex = 0 
        while True:
            edge = flag_arr[flag_dex] 
            (a,b) = self.wait(edge)
            if flag_dex == 0:
                flag_dex = 1
                rising_sample = self.samplenum 
            else:
                flag_dex = 0                
                times += 1         
                falling_sample = self.samplenum
                v = falling_sample - rising_sample     
                s = '%02X' % v
                ann = times % 2    
                self.put_ann(rising_sample, falling_sample, ann, [s])

      #times用于輸出次數(shù)計(jì)數(shù)，偶數(shù)次輸出到第一行，奇數(shù)次輸出到第二行
      #ann = times % 2  對(duì)次數(shù)變量求余，其值在0和1中變換，調(diào)用put_ann時(shí)指定了annotation的序號(hào)
      #再根據(jù)序號(hào)由annotation_rows決定輸出在哪一行
      #邊沿條件就兩種：向上和向下，調(diào)用wait函數(shù)時(shí)，在這兩個(gè)邊沿條件中切換
      #首次是取向上邊沿，然后再換成向下邊沿
      #每次調(diào)用wait后，通過(guò)self.samplenum取采樣位置
      #求出兩次的樣品位置差后，轉(zhuǎn)換成16進(jìn)制的字符串，通過(guò)類函數(shù)put_ann輸出

六、解碼模塊工作原理

??通過(guò)c代碼和python代碼的互操作，將采樣數(shù)據(jù)交給python分析。經(jīng)過(guò)一系列的處理，最終生成解碼結(jié)果，用于顯示以及供給上層協(xié)議作為分析的數(shù)據(jù)來(lái)源。解碼模塊的核心主要由以下部分組成：

1. c底層包裝類Decoder
   在c代碼里，給python提供一個(gè)經(jīng)過(guò)包裝的基類，python可調(diào)用基類的一些方法，實(shí)現(xiàn)調(diào)用c代碼的目的。python端通過(guò)以下語(yǔ)句導(dǎo)出c代碼包裝的Decoder類：

import sigrokdecode as srd

python可訪問(wèn)的Decoder基類的方法有：

• register方法
  用于注冊(cè)python輸出到c底層的消息類型，有：
  (1) OUTPUT_ANN，數(shù)據(jù)輸出到屏幕
  (2) OUTPUT_PYTHON，數(shù)據(jù)輸出到上層協(xié)議
  (3) OUTPUT_BINARY
  (4) OUTPUT_META

python調(diào)用方式：

 self.out_ann=self.register(srd.OUTPUT_ANN)
 self.out_py=self.register(srd.OUTPUT_PYTHON)

put方法
輸出數(shù)據(jù)到屏幕或上層協(xié)議，python調(diào)用方式：

self.put(a,b,self.out_ann,[0,['abc']])

其中，a、b為采樣點(diǎn)區(qū)間值，self.out_ann為注冊(cè)的消息類型，[0,[‘a(chǎn)bc’]]， 0為消息類型序號(hào)，參考之前的內(nèi)容；[‘a(chǎn)bc’]為消息內(nèi)容了

wait方法
獲得上一次分析位置后的采樣數(shù)據(jù)，可通過(guò)參數(shù)指定邊沿查找條件。
調(diào)用方式： self.wait()
可指定參數(shù)，如：{0,’r’}表示第１個(gè)綁定的通道滿足向上邊沿的數(shù)據(jù)；{1,’f’}表示第２個(gè)綁定通道足向下邊沿的數(shù)據(jù)。其它條件標(biāo)志還有：h、l、e、n。
可通過(guò)多個(gè)條件組成并和或的條件。并條件如：{0:’f’,1:’r’}，或條件如：[{0:’f’},{1:’r’}]

• has_channel方法
  用來(lái)叛斷某個(gè)通道是否綁定，python調(diào)用方式：

  self.has_channel(0)

0是通道序號(hào)。

• 屬性
  c底層類給python提供了兩個(gè)屬性：
  a. self.samplenum，wait()調(diào)用后的采樣數(shù)據(jù)位置；
  b. self.matched，wait()調(diào)用后道通匹配信息；

1. python層包裝類Decoder
   繼承至c底層包裝的類，由c底層實(shí)例化并調(diào)用python類的方法，代碼如下：

 import sigrokdecode as srd
 class Decoder(srd.Decoder):

子類Decoder的方法有：

• reset方法
  這里做一些變量值的重置，以及類的私有變量的定義。變量的定義如：

  self.name = 'abc'

• start方法
  在解碼任務(wù)開(kāi)始執(zhí)行前，c底層代碼會(huì)調(diào)用一次start函數(shù)，這里主要是做一些初始化工作，比如注冊(cè)消息類型，如：

  self.out_ann = self.register(srd.OUTPUT_ANN)
  self.out_py = self.register(srd.OUTPUT_PYTHON)

• decode方法
  由c底層調(diào)用，在解碼任務(wù)開(kāi)始時(shí)，c底層啟動(dòng)一個(gè)線程，然后在線程里調(diào)用decode方法。
  在這個(gè)函數(shù)里，一直循環(huán)調(diào)用wait函數(shù)，不斷從c底層讀取符合邊沿條件的數(shù)據(jù)，如：

  while True:
      (a,b) = self.wait()

(a,b)元組里的變量數(shù)跟聲明的chnnaels里聲明的通道數(shù)一致，包括可選的通道上。

解碼任務(wù)執(zhí)行流程：

• (1) 解碼任務(wù)開(kāi)始啟動(dòng)；
• (2) 上層將采樣數(shù)據(jù)分批推送到底層；
• (3) 底層檢測(cè)并啟動(dòng)一個(gè)線程，該線程調(diào)用python層的decode函數(shù)，不斷處理上層推送的數(shù)據(jù)；
• (4) python層經(jīng)過(guò)一系列的計(jì)算處理，生成解碼結(jié)果，通過(guò)put函數(shù)輸出到c底層；
• (5) 當(dāng)所有數(shù)據(jù)推送完成并經(jīng)過(guò)python層處理，解碼任務(wù)結(jié)束；

七、框架升級(jí)更新記錄

??在DSView版本1.2.0以上，更新以下功能：

1. end方法
   python層的方法，當(dāng)所有數(shù)據(jù)處理完成后會(huì)被c底層觸發(fā)
2. self.last_samplenum屬性
   c底層提供的屬性，其值為所有數(shù)據(jù)推送完成后最后的數(shù)據(jù)樣位置。當(dāng)存在end方法時(shí)，該屬性將被設(shè)置
3. 數(shù)據(jù)多種顯示格式
   顯示的annotation數(shù)據(jù)部分，可以在2進(jìn)制、16進(jìn)制、8進(jìn)制、10進(jìn)制、ascii格式間轉(zhuǎn)換。

self.put(s, e, self.out_ann, [1,['%02X' % value])

put函數(shù)將數(shù)據(jù)輸出c底層，并在屏幕上顯示。其中，value為要顯示的數(shù)據(jù)。在輸出到時(shí)需要轉(zhuǎn)換為16進(jìn)制的字符串。當(dāng)需要讓數(shù)據(jù)支持在多種格式間轉(zhuǎn)換時(shí)，代碼修改如下：

self.put(s, e, self.out_ann, [1,['@' + '%02X' % value])

它是通過(guò)在數(shù)據(jù)部分前加@符號(hào)，告訴c底層這一部分內(nèi)空是數(shù)據(jù)部分，如：
'@66FB'
如果存在前綴文字，需要將格式部分和數(shù)據(jù)部分開(kāi)，如：
['Data:{$}','D:{$}', '@66FB']
{$}是占位符，系統(tǒng)將數(shù)據(jù)部分格式化后替換掉占位符，就會(huì)變成：Data:66FB