Если вы читали пост Знакомимся с Sigrok и логическим анализатором DSLogic , то помните, что для Sigrok можно писать декодеры протоколов (protocol decoders, в документации к Sigrok часто используется сокращение PD) на Python. Однако в посте ничего не говорится о том, как их, собственно, писать. Пришло время заполнить этот пробел.
Примечание: Если вы пропустили статью Как стать контрибьютором в open source проект — идеи для первого патча и прочие рекомендации , может быть не лишено смысла ознакомиться с ней.
Основные сведения
В этом контексте нельзя не сказать пару слов о процессе разработки Sigrok. Каким образом новые декодеры (или патчи к существующим) попадают в него? Для этого нужно предложить патчи в рассылке sigrok-devel . Притом мейнтейнеры предпочитают патчи в виде веток на GitHub, а не в файлов .patch. В качестве конкретного примера рассмотрим написанный мной декодер протокола TFT-дисплеев на базе ST7735 . Соответствующее письмо в рассылку можно найти здесь .
Вы обратили внимание, что я сказал патчи , во множественном числе? Патчей действительно нужно несколько:
- Патч для репозитория sigrok-dumps, добавляющий .sr файл с примером декодируемого протокола. Пример моего патча: 1ea7b9af .
- Патч для репозитория libsigrokdecode, добавляющий сам декодер на Python. Пример: f62e32bc .
- Наконец, патч для sigrok-test, добавляющий регрессионные тесты на написанный декодер. Пример: 4aa3a4fd .
Получить файл .sr не сложно, это делается банально с помощью sigrok-cli или PulseView. Заметьте, что пример следует сократить до минимального. Обрезать лишнее можно в PulseView с помощью курсоров. Также стоит иметь ввиду, что в идеале записанный пример должен покрывать все, или хотя бы большинство возможностей декодера (например, все декодируемые команды). В связи с этим может потребоваться написать кастомную прошивку для вашей любимой отладочной платы.
В общем, эта часть работы тривиальна. Поэтому далее мы сосредоточимся на написании декодера и тестов к нему.
Разработка декодера
На время разработки декодера нужно как-то заставить sigrok-cli и PulseView его видеть. Проще всего сделать это с помощью символьной ссылки:
sudo ln -s / path / to / libsigrokdecode / decoders / st7735 . / st7735
Декодер состоит из двух файлов. Файл __init__.py в основном содержит лицензию и краткое описание декодера:
## This file is part of the libsigrokdecode project.
##
## Copyright (C) 2018 Aleksander Alekseev <afiskon@gmail.com>
##
## This program is free software; you can redistribute it and/or modify
## it under the terms of the GNU General Public License as published by
## the Free Software Foundation; either version 2 of the License, or
## (at your option) any later version.
##
## This program is distributed in the hope that it will be useful,
## but WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
## GNU General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with this program; if not, see <http://www.gnu.org/licenses/>.
##
»’
This decoder decodes the ST7735 TFT controller protocol.
Details:
http://www.displayfuture.com/Display/datasheet/controller/ST7735.pdf
»’
from . pd import Decoder
Самое же интересное содержится в файле pd.py. Рассмотрим его по частям.
MAX_DATA_LEN = 128
# Command ID -> name, short description
META = {
0x00 : { ‘name’ : ‘NOP ‘ , ‘desc’ : ‘No operation’ } ,
0x01 : { ‘name’ : ‘SWRESET’ , ‘desc’ : ‘Software reset’ } ,
0x04 : { ‘name’ : ‘RDDID ‘ , ‘desc’ : ‘Read display ID’ } ,
# … (ПРОПУЩЕНО) …
}
Здесь просто объявляются константы, используемые далее по коду. Переменная META , как не сложно понять, служит для отображения кода команды в ее название и краткое описание. Эта информация была получена из даташита ST7735.
BITS , CMD , DATA , DESC = range ( 4 )
class Decoder ( srd. Decoder ) :
api_version = 3
id = ‘st7735’
name = ‘ST7735’
longname = ‘Sitronix ST7735’
desc = ‘Sitronix ST7735 TFT controller protocol.’
license = ‘gplv2+’
inputs = [ ‘logic’ ]
outputs = [ ‘st7735’ ]
channels = (
{ ‘id’ : ‘cs’ , ‘name’ : ‘CS#’ , ‘desc’ : ‘Chip-select’ } ,
{ ‘id’ : ‘clk’ , ‘name’ : ‘CLK’ , ‘desc’ : ‘Clock’ } ,
{ ‘id’ : ‘mosi’ , ‘name’ : ‘MOSI’ , ‘desc’ : ‘Master out, slave in’ } ,
{ ‘id’ : ‘dc’ , ‘name’ : ‘DC’ , ‘desc’ : ‘Data or command’ }
)
annotations = (
( ‘bit’ , ‘Bit’ ) ,
( ‘command’ , ‘Command’ ) ,
( ‘data’ , ‘Data’ ) ,
( ‘description’ , ‘Description’ ) ,
)
annotation_rows = (
( ‘bits’ , ‘Bits’ , ( Ann. BITS , ) ) ,
( ‘fields’ , ‘Fields’ , ( Ann. CMD , Ann. DATA ) ) ,
( ‘description’ , ‘Description’ , ( Ann. DESC , ) ) ,
)
Класс Decoder представляет собой непосредственно наш декодер. Класс должен иметь несколько обязательных полей, содержащие уникальный идентификатор протокола, его имя, краткое описание, информацию о лицензии. Поля inputs и outputs определяют, какие данные декодер принимает на вход и выдает на выход. Это нужно по той причине, что Sigrok позволяет писать декодеры, работающие поверх других декодеров. Например, нередко нужно написать декодер, работающий поверх декодера SPI или I2C. В данном примере декодер работает непосредственно с логическими сигналами, не полагаясь на другие декодеры. Поле channels определяет, какие сигналы нужны декодеру на вход. Поля annotations и annotation_rows говорят, какие данные выводит наш декодер, притом последнее поле нужно для объединения этих данных в группы.
self . reset ( )
def reset ( self ) :
self . accum_byte = 0
self . accum_bits_num = 0
self . bit_ss = — 1
self . byte_ss = — 1
self . current_bit = — 1
def start ( self ) :
self . out_ann = self . register ( srd. OUTPUT_ANN )
def put_desc ( self , ss , es , cmd , data ) :
if cmd == — 1 :
return
if META [ cmd ] :
self . put ( ss , es , self . out_ann , [ Ann. DESC ,
[ ‘%s: %s’ % ( META [ cmd ] [ ‘name’ ] . strip ( ) ,
META [ cmd ] [ ‘desc’ ] ) ] ] )
else :
# Default description:
dots = »
if len ( data ) == MAX_DATA_LEN:
data = data [ :- 1 ]
dots = ‘…’
data_str = ‘(none)’
if len ( data ) > 0 :
data_str = ‘ ‘ . join ( [ ‘%02X’ % b for b in data ] )
self . put ( ss , es , self . out_ann , [ Ann. DESC ,
[ ‘Unknown command: %02X. Data: %s%s’ % ( cmd , data_str ,
dots ) ] ] )
Имена методов __init__ , reset и start говорят сами за себя. Метод put_desc , используемый далее по коду, присваивает диапазону входных данных текстовое описание. Делается это через вызов унаследованного от родительского класса srd.Decoder метода put . Для идентификации начала и конца входных данных, которым мы хотим сопоставить какой-то выход декодера, используются целые числа, называемые start sample и end sample. В коде их часто сокращают до ss и es .
Наконец, основным методом является decode :
current_cmd = — 1
current_data = [ ]
desc_ss = — 1
desc_es = — 1
self . reset ( )
while True :
# Check data on both CLK edges.
( cs , clk , mosi , dc ) = self . wait ( { 1 : ‘e’ } )
if cs == 1 : # Wait for CS = low, ignore the rest.
self . reset ( )
continue
if clk == 1 :
# Read one bit.
self . bit_ss = self . samplenum
if self . accum_bits_num == 0 :
self . byte_ss = self . samplenum
self . current_bit = mosi
if ( clk == 0 ) and ( self . current_bit >= 0 ) :
# Process one bit.
self . put ( self . bit_ss , self . samplenum , self . out_ann ,
[ Ann. BITS , [ str ( self . current_bit ) ] ] )
# MSB-first
self . accum_byte = ( self . accum_byte << 1 ) | self . current_bit
self . accum_bits_num + = 1
if self . accum_bits_num == 8 :
# Process one byte.
# DC = low for commands.
ann = Ann. DATA if dc else Ann. CMD
self . put ( self . byte_ss , self . samplenum , self . out_ann ,
[ ann , [ ‘%02X’ % self . accum_byte ] ] )
if ann == Ann. CMD :
self . put_desc ( desc_ss , desc_es , current_cmd ,
current_data )
desc_ss = self . byte_ss
desc_es = self . samplenum # For cmds without data.
current_cmd = self . accum_byte
current_data = [ ]
else :
if len ( current_data ) < MAX_DATA_LEN:
current_data + = [ self . accum_byte ]
desc_es = self . samplenum
self . accum_bits_num = 0
self . accum_byte = 0
self . byte_ss = — 1
self . current_bit = — 1
self . bit_ss = — 1
Данные для декодирования приходят через вызов унаследованного метода wait . Притом, передав этому методу аргумент {1: 'e'} , мы говорим, что хотим получать данные только по переднему или заднему фронту на первом канале, которому у нас соответствует CLK (нумерация каналов идет с нуля). Также помимо e (edge) можно указать r (rising edge) или f (falling edge), если нас интересует не любой фронт, а только передний или только задний. В принципе, можно и не указывать ничего, получая вообще все входные данные, какие есть. Но в этом случае скорость работы декодера будет оставлять желать лучшего.
Так или иначе, благодаря вызову wait переменным cs , clk , mosi и dc присваиваются единички и нолики в соответствии со значениями на каналах. Понять, по какому смещению относительно начала данных мы находимся, можно благодаря унаследованному полю samplenump . Остальное — дело техники. Единички и нолики выводятся с аннотацией Ann.BITS , из них собираются байты, выводимые с аннотациями Ann.CMD или Ann.DATA , а байты декодируются в текстовое описание, выводимое при помощи объявленного выше метода put_desc .
Напомню, как выглядит результат:
На приведенной картинке фиолетовым цветом изображены биты (Ann.BITS). Под ними идут байты, зеленые соответствуют командам (Ann.CMD), а синие — аргументам команд (Ann.DATA). Наконец, под байтами выводится текстовое описание команды (Ann.DESC).
Вот и весь код! Стоит, впрочем, сказать пару слов об отладке. Иной раз трудно понять, какие данные приходят в тот или иной метод, особенно если вы пишете декодер, работающий поверх другого декодера. Вот, к примеру, шаблон ничего не делающего декодера, работающего поверх декодера SPI:
class Ann:
CMD , DATA , DESC = range ( 3 )
class Decoder ( srd. Decoder ) :
# see https://sigrok.org/wiki/Protocol_decoder_API
api_version = 3
id = ‘st7735’ # this is shown in `sigrok-cli -L`
name = ‘ST7735’ # this is shown in PulseView
longname = ‘ST7735 TFT controller’ # shown in `sigrok-cli -L`
desc = ‘ST7735 TFT controller protocol decoder’
license = ‘gplv2+’
inputs = [ ‘spi’ ]
outputs = [ ‘st7735’ ]
channels = ( )
optional_channels = ( )
annotations = (
( ‘command’ , ‘Command’ ) , # Ann.CMD
( ‘data’ , ‘Data’ ) , # Ann.DATA
( ‘description’ , ‘Description’ ) , # Ann.DESC
)
annotation_rows = (
( ‘fields’ , ‘Fields’ , ( Ann. CMD , Ann. DATA , ) ) ,
( ‘description’ , ‘Description’ , ( Ann. DESC , ) ) ,
)
options = ( ) # see examples in spiflash decoder
def __init__ ( self ) :
self . reset ( )
def reset ( self ) :
pass # do nothing, yet
# This function is called before the beginning of the decoding.
# This is the place to register() the output types, check the
# user-supplied PD options for validity, and so on
def start ( self ) :
self . out_ann = self . register ( srd. OUTPUT_ANN )
def putx ( self , data ) :
self . put ( self . ss , self . es , self . out_ann , data )
# This is a function that is called by the libsigrokdecode
# backend whenever it has a chunk of data for the protocol
# decoder to handle
# Arguments:
# ss = startsample, the absolute samplenumber of the
# first sample in this chunk of data
# es = endsample, the absolute samplenumber of the
# last sample in this chunk of data
# data = a list containing the data to decode. Depends on
# whether the decoder decodes raw samples or is
# stacked onto another decoder
def decode ( self , ss , es , data ) :
print ( «decode: ss = %s, es = %s, data = %s» % ( ss , es , data ) )
ptype , mosi , miso = data
self . ss , self . es = ss , es
if ptype == ‘CS-CHANGE’ :
# end_current_transaction()
pass
if ptype != ‘DATA’ :
return
# Handle commands here
self . putx ( [ Ann. DESC , [ ‘Unknown command: 0x%02X’ % mosi ] ] )
Обратите внимание на отладочный вывод с помощью print , а также на то, что данные здесь приходят не через вызов wait , а напрямую в метод decode , имеющий другую сигнатуру. Теперь можно сказать:
Отладочный вывод декодера будет виден в консоли.
Покрываем код текстами
Итак, будем считать, что с декодером мы разобрались. Осталось добавить тесты на него. На этом шаге лучше не полагаться на установленные бинарные пакеты Sigrok, а честно собрать их из веток master. Тем более, что половину репозиториев мы и так же склонировали. Делается это не сложно и занимает пару минут:
cd / home / eax / sigrok-dev / src
git clone ‘git://sigrok.org/libsigrok’
git clone ‘git://sigrok.org/sigrok-cli’
git clone ‘git://sigrok.org/libsigrokdecode’
cd libsigrok
. / autogen.sh
CFLAGS = ‘-O0 -g’ CXXFLAGS = ‘-O0 -g’ . / configure
—prefix = / home / eax / sigrok-dev / install
—disable-java —disable-python
make
make install
cd .. / libsigrokdecode
. / autogen.sh
CFLAGS = ‘-O0 -g’ CXXFLAGS = ‘-O0 -g’ . / configure
—prefix = / home / eax / sigrok-dev / install
make
make install
cd .. / sigrok-cli
. / autogen.sh
CFLAGS = ‘-O0 -g’ CXXFLAGS = ‘-O0 -g’ . / configure
—prefix = / home / eax / sigrok-dev / install
make
make install
cd ..
Fun fact! Все зависимости я лично подтянул очень просто — собрал пакеты из AUR , но не стал их устанавливать. Даже если вы пользуетесь дистрибутивом, отличным от Arch Linux, вы можете подсмотреть список зависимостей в AUR.
Собирать PulseView при разработке декодеров, строго говоря, не требуется, но если очень хочется:
cd pulseview
mkdir build
cd build
PKG_CONFIG_PATH = / home / eax / sigrok-dev / install / lib / pkgconfig /
cmake -G Ninja
-DCMAKE_INSTALL_PREFIX: PATH = / home / eax / sigrok-dev / install
-DCMAKE_BUILD_TYPE=Debug
-DCMAKE_CXX_FLAGS= ‘-O0 -g -fext-numeric-literals’ ..
ninja
ninja install
Если вы хотите использовать Sigrok и PulseView из веток master, допишите в файл ~/.bashrc:
export PATH = «~/sigrok-dev/install/bin: $PATH »
Возвращаемся к тестами:
cd sigrok-test
. / autogen.sh
PKG_CONFIG_PATH = $HOME / sigrok-dev / install / lib / pkgconfig
. / configure
—with-decodersdir = $HOME / sigrok-dev / libsigrokdecode / decoders
make
Проверяем, что тесты проходят:
. / decoder / pdtest -r -v -a
Чтобы сгенерировать ожидаемый вывод для нашего нового декодера, пишем в decoder/test/st7735/test.conf:
protocol-decoder st7735 channel cs=0 channel dc=2 channel mosi=3 ?
channel clk=4
input display/st7735/st7735.sr
output st7735 annotation match st7735_basic.output
Говорим:
. / decoder / pdtest -f st7735
Будет получен файл decoder/test/st7735/st7735_basic.output с ожидаемым выводом. Для запуска отдельного теста говорим:
. / decoder / pdtest -r st7735
Эксперимента ради можно отредактировать файл .output и убедиться, что в этом случае тесты не пройдут:
Test output mismatch:
— 24003758-24003780 st7735: command: «11»
+ 24003758-24003780 st7735: command: «01»
Заинтересованные читатели могут использовать информацию из этого раздела не только для разработки декодеров, но и для разработки кишок Sigrok и PulseView. Здесь вам также помогут заметки Памятка по отладке при помощи GDB , Краткий обзор статических анализаторов кода на C/C++ , Профилирование кода на C/C++ в Linux и FreeBSD и далее по ссылкам.
Заключение
Кое-какие дополнительные сведения можно найти на официальной wiki проекта:
Также не побрезгуйте почитать код других декодеров из libsigrokdecode , там полно примеров. За помощью всегда можно обратиться в уже упомянутую рассылку sigrok-devel . А еще сообщество разработчиков Sigrok довольно активно в IRC , на канале #sigrok во FreeNode.
Как видите, Sigrok имеет относительно невысокий порог вхождения. Стать контрибьютором в него очень просто — берете случайную железку и пишите для используемого ею протокола декодер на Python. А когда и если это перестанет быть интересным, можно заняться разработкой PulseView или драйверов для новых логических анализаторов, мультиметров и осциллографов. В общем, если вы искали открытый проект для самореализации, рекомендую.