From 4c3b1846c9c307c1c35f86d259ddb968ed92718d Mon Sep 17 00:00:00 2001 From: Uwe Hermann Date: Wed, 22 Jan 2014 22:43:21 +0100 Subject: [PATCH] All PDs: Improve/fix descriptions. --- decoders/avr_isp/__init__.py | 10 ++-------- decoders/can/__init__.py | 15 +++++---------- decoders/dcf77/__init__.py | 3 ++- decoders/ds1307/__init__.py | 6 ++---- decoders/i2c/__init__.py | 4 +--- decoders/i2cdemux/__init__.py | 6 +++--- decoders/i2cfilter/__init__.py | 4 ++-- decoders/i2s/__init__.py | 5 +++-- decoders/jtag/__init__.py | 24 ------------------------ decoders/jtag/pd.py | 22 ++++++++++++++++++++++ decoders/jtag_stm32/__init__.py | 5 ++--- decoders/lm75/__init__.py | 11 ++--------- decoders/lpc/__init__.py | 3 ++- decoders/maxim_ds28ea00/__init__.py | 9 ++------- decoders/midi/__init__.py | 8 ++++---- decoders/mlx90614/__init__.py | 6 ++---- decoders/mx25lxx05d/__init__.py | 7 +++---- decoders/mxc6225xu/__init__.py | 8 ++------ decoders/nunchuk/__init__.py | 5 ++--- decoders/onewire_link/__init__.py | 4 +--- decoders/onewire_network/__init__.py | 8 ++------ decoders/pan1321/__init__.py | 6 ++---- decoders/rtc8564/__init__.py | 6 ++---- decoders/sdcard_spi/__init__.py | 8 ++------ decoders/spi/__init__.py | 8 +++----- decoders/tlc5620/__init__.py | 2 +- decoders/uart/__init__.py | 6 ++---- decoders/usb_packet/__init__.py | 6 ++---- decoders/usb_signalling/__init__.py | 5 +---- decoders/xfp/__init__.py | 2 +- 30 files changed, 82 insertions(+), 140 deletions(-) diff --git a/decoders/avr_isp/__init__.py b/decoders/avr_isp/__init__.py index ff689df..4c4a900 100644 --- a/decoders/avr_isp/__init__.py +++ b/decoders/avr_isp/__init__.py @@ -19,14 +19,8 @@ ## ''' -AVR ISP protocol decoder. - -TODO: Description. - -TODO: SPI is MSB-first. - -Details: -TODO +This decoder stacks on top of the 'spi' PD and decodes the In-System +Programming (ISP) protocol of some Atmel AVR 8-bit microcontrollers. ''' from .pd import * diff --git a/decoders/can/__init__.py b/decoders/can/__init__.py index fac4f6c..38731c2 100644 --- a/decoders/can/__init__.py +++ b/decoders/can/__init__.py @@ -19,17 +19,12 @@ ## ''' -CAN protocol decoder. - -TODO: Description. - -Details: -TODO - -Protocol output format: - -TODO. +CAN (Controller Area Network) is a field bus protocol for distributed +real-time control. +This decoder assumes that a single CAN_RX line is sampled (e.g. on +the digital output side of a CAN transceiver IC such as the Microchip +MCP-2515DM-BM). ''' from .pd import * diff --git a/decoders/dcf77/__init__.py b/decoders/dcf77/__init__.py index 71828e2..04805c2 100644 --- a/decoders/dcf77/__init__.py +++ b/decoders/dcf77/__init__.py @@ -19,7 +19,8 @@ ## ''' -TODO. +This PD decodes the DCF77 protocol (a European long-wave time signal that +uses a 77.5kHz carrier frequency). Details: http://en.wikipedia.org/wiki/DCF77 diff --git a/decoders/ds1307/__init__.py b/decoders/ds1307/__init__.py index 04db184..5bc28c3 100644 --- a/decoders/ds1307/__init__.py +++ b/decoders/ds1307/__init__.py @@ -19,10 +19,8 @@ ## ''' -Dallas DS1307 RTC protocol decoder. - -Details: -TODO +This decoder stacks on top of the 'i2c' PD and decodes the Dallas DS1307 +real-time clock (RTC) specific registers and commands. ''' from .pd import * diff --git a/decoders/i2c/__init__.py b/decoders/i2c/__init__.py index 95d9e18..ba40245 100644 --- a/decoders/i2c/__init__.py +++ b/decoders/i2c/__init__.py @@ -19,9 +19,7 @@ ## ''' -I²C protocol decoder. - -The Inter-Integrated Circuit (I²C) bus is a bidirectional, multi-master +I²C (Inter-Integrated Circuit) is a bidirectional, multi-master bus using two signals (SCL = serial clock line, SDA = serial data line). ''' diff --git a/decoders/i2cdemux/__init__.py b/decoders/i2cdemux/__init__.py index 93f6c34..c5202c5 100644 --- a/decoders/i2cdemux/__init__.py +++ b/decoders/i2cdemux/__init__.py @@ -19,10 +19,10 @@ ## ''' -Generic I²C demultiplexing protocol decoder. +This is a generic I²C demultiplexing protocol decoder. -Takes an I²C stream as input and outputs multiple I²C streams, each stream -containing only I²C packets for one specific I²C slave. +It takes an I²C stream as input and outputs multiple I²C streams, each +stream containing only I²C packets for one specific I²C slave. ''' from .pd import * diff --git a/decoders/i2cfilter/__init__.py b/decoders/i2cfilter/__init__.py index 31c3c6b..6cbab8a 100644 --- a/decoders/i2cfilter/__init__.py +++ b/decoders/i2cfilter/__init__.py @@ -18,9 +18,9 @@ ## ''' -Generic I²C filtering protocol decoder. +This is a generic I²C filtering protocol decoder. -Takes input from the I²C protocol decoder and removes all traffic +It takes input from the I²C protocol decoder and removes all traffic except that from/to the specified slave address and/or direction. It then outputs the filtered data again as OUTPUT_PROTO of type/format 'i2c' diff --git a/decoders/i2s/__init__.py b/decoders/i2s/__init__.py index e59ca96..b9c0ed7 100644 --- a/decoders/i2s/__init__.py +++ b/decoders/i2s/__init__.py @@ -19,9 +19,10 @@ ## ''' -I²S protocol decoder. +I²S (Integrated Interchip Sound) is a serial bus for connecting digital +audio devices (usually on the same device/board). -Documentation: +Details: http://www.nxp.com/acrobat_download/various/I2SBUS.pdf http://en.wikipedia.org/wiki/I2s ''' diff --git a/decoders/jtag/__init__.py b/decoders/jtag/__init__.py index 16cf6c6..047e54a 100644 --- a/decoders/jtag/__init__.py +++ b/decoders/jtag/__init__.py @@ -19,34 +19,10 @@ ## ''' -JTAG protocol decoder. - JTAG (Joint Test Action Group), a.k.a. "IEEE 1149.1: Standard Test Access Port and Boundary-Scan Architecture", is a protocol used for testing, debugging, and flashing various digital ICs. -TODO: Protocol details. - -Protocol output format (WORK IN PROGRESS!): - -JTAG packet: -[, ] - - is one of: - - 'NEW STATE': is the new state of the JTAG state machine. - Valid values: 'TEST-LOGIC-RESET', 'RUN-TEST/IDLE', 'SELECT-DR-SCAN', - 'CAPTURE-DR', 'SHIFT-DR', 'EXIT1-DR', 'PAUSE-DR', 'EXIT2-DR', 'UPDATE-DR', - 'SELECT-IR-SCAN', 'CAPTURE-IR', 'SHIFT-IR', 'EXIT1-IR', 'PAUSE-IR', - 'EXIT2-IR', 'UPDATE-IR'. - - 'IR TDI': Bitstring that was clocked into the IR register. - - 'IR TDO': Bitstring that was clocked out of the IR register. - - 'DR TDI': Bitstring that was clocked into the DR register. - - 'DR TDO': Bitstring that was clocked out of the DR register. - - ... - -All bitstrings are a sequence of '1' and '0' characters. The right-most -character in the bitstring is the LSB. Example: '01110001' (1 is LSB). - Details: https://en.wikipedia.org/wiki/Joint_Test_Action_Group http://focus.ti.com/lit/an/ssya002c/ssya002c.pdf diff --git a/decoders/jtag/pd.py b/decoders/jtag/pd.py index 55a9a1f..ea6887b 100644 --- a/decoders/jtag/pd.py +++ b/decoders/jtag/pd.py @@ -22,6 +22,28 @@ import sigrokdecode as srd +''' +Protocol output format: + +JTAG packet: +[, ] + + is one of: + - 'NEW STATE': is the new state of the JTAG state machine. + Valid values: 'TEST-LOGIC-RESET', 'RUN-TEST/IDLE', 'SELECT-DR-SCAN', + 'CAPTURE-DR', 'SHIFT-DR', 'EXIT1-DR', 'PAUSE-DR', 'EXIT2-DR', 'UPDATE-DR', + 'SELECT-IR-SCAN', 'CAPTURE-IR', 'SHIFT-IR', 'EXIT1-IR', 'PAUSE-IR', + 'EXIT2-IR', 'UPDATE-IR'. + - 'IR TDI': Bitstring that was clocked into the IR register. + - 'IR TDO': Bitstring that was clocked out of the IR register. + - 'DR TDI': Bitstring that was clocked into the DR register. + - 'DR TDO': Bitstring that was clocked out of the DR register. + - ... + +All bitstrings are a sequence of '1' and '0' characters. The right-most +character in the bitstring is the LSB. Example: '01110001' (1 is LSB). +''' + jtag_states = [ # Intro "tree" 'TEST-LOGIC-RESET', 'RUN-TEST/IDLE', diff --git a/decoders/jtag_stm32/__init__.py b/decoders/jtag_stm32/__init__.py index 7618666..8a28528 100644 --- a/decoders/jtag_stm32/__init__.py +++ b/decoders/jtag_stm32/__init__.py @@ -19,9 +19,8 @@ ## ''' -ST STM32 JTAG protocol decoder. - -TODO. +This decoder stacks on top of the 'jtag' PD and decodes JTAG data specific to +the STM32 microcontroller series. Details: https://en.wikipedia.org/wiki/STM32 diff --git a/decoders/lm75/__init__.py b/decoders/lm75/__init__.py index 213e0ec..d096418 100644 --- a/decoders/lm75/__init__.py +++ b/decoders/lm75/__init__.py @@ -19,15 +19,8 @@ ## ''' -National LM75 (and compatibles) temperature sensor protocol decoder. - -TODO: Description. - -Protocol output format: -TODO. - -Details: -TODO. +This decoder stacks on top of the 'i2c' PD and decodes the National LM75 +(and compatibles) temperature sensor protocol. ''' from .pd import * diff --git a/decoders/lpc/__init__.py b/decoders/lpc/__init__.py index e03c27e..62a4307 100644 --- a/decoders/lpc/__init__.py +++ b/decoders/lpc/__init__.py @@ -19,7 +19,8 @@ ## ''' -Low-Pin Count protocol decoder. +LPC (Low-Pin Count) is a protocol for low-bandwidth devices used on +some PC mainboards, such as the "BIOS chip" or the so-called "Super I/O". ''' from .pd import * diff --git a/decoders/maxim_ds28ea00/__init__.py b/decoders/maxim_ds28ea00/__init__.py index c5d3ca5..34d1d08 100644 --- a/decoders/maxim_ds28ea00/__init__.py +++ b/decoders/maxim_ds28ea00/__init__.py @@ -19,13 +19,8 @@ ## ''' -Maxim DS28EA00 protocol decoder. - -The Maxim DS28EA00 is a 1-Wire digital thermometer with Sequence Detect -and PIO functionality. - -Details: -TODO +This decoder stacks on top of the 'onewire_network' PD and decodes the +Maxim DS28EA00 1-Wire digital thermometer protocol. ''' from .pd import * diff --git a/decoders/midi/__init__.py b/decoders/midi/__init__.py index 029cfc0..a453346 100644 --- a/decoders/midi/__init__.py +++ b/decoders/midi/__init__.py @@ -19,11 +19,11 @@ ## ''' -MIDI protocol decoder. +This decoder stacks on top of the 'uart' PD and decodes the MIDI +(Musical Instrument Digital Interface) protocol. -The MIDI protocol is layered on top of the UART (async serial) protocol, -with a fixed baud rate of 31250 baud (+/- 1%) and 8n1 settings. Bytes are -sent LSB-first. +MIDI is layered on top of the UART (async serial) protocol, with a fixed +baud rate of 31250 baud (+/- 1%) and 8n1 settings. Bytes are sent LSB-first. ''' from .pd import * diff --git a/decoders/mlx90614/__init__.py b/decoders/mlx90614/__init__.py index d0c6293..29cb2a9 100644 --- a/decoders/mlx90614/__init__.py +++ b/decoders/mlx90614/__init__.py @@ -19,10 +19,8 @@ ## ''' -Melexis MLX90614 protocol decoder. - -Details: -TODO +This decoder stacks on top of the 'i2c' PD and decodes the Melexis MLX90614 +infrared thermometer protocol. ''' from .pd import * diff --git a/decoders/mx25lxx05d/__init__.py b/decoders/mx25lxx05d/__init__.py index 047be0e..71d7b3c 100644 --- a/decoders/mx25lxx05d/__init__.py +++ b/decoders/mx25lxx05d/__init__.py @@ -19,11 +19,10 @@ ## ''' -Macronix MX25Lxx05D SPI (NOR) flash chip protocol decoder. +This decoder stacks on top of the 'spi' PD and decodes the Macronix +MX25Lxx05D SPI (NOR) flash chip protocol. -Works for MX25L1605D/MX25L3205D/MX25L6405D. - -TODO: Description. +It works for the MX25L1605D/MX25L3205D/MX25L6405D. Details: http://www.macronix.com/QuickPlace/hq/PageLibrary4825740B00298A3B.nsf/h_Index/3F21BAC2E121E17848257639003A3146/$File/MX25L1605D-3205D-6405D-1.5.pdf diff --git a/decoders/mxc6225xu/__init__.py b/decoders/mxc6225xu/__init__.py index 783be19..c4209c8 100644 --- a/decoders/mxc6225xu/__init__.py +++ b/decoders/mxc6225xu/__init__.py @@ -19,15 +19,11 @@ ## ''' -MEMSIC MXC6225XU protocol decoder. - -The MEMSIC MXC6225XU is a Digital Thermal Orientation Sensor (DTOS). +This decoder stacks on top of the 'i2c' PD and decodes the MEMSIC MXC6225XU +digital thermal orientation sensor (DTOS) protocol. The chip's I²C interface supports standard mode and fast mode (max. 400kHz). Its I²C slave address is 0x2a. - -Details: -TODO ''' from .pd import * diff --git a/decoders/nunchuk/__init__.py b/decoders/nunchuk/__init__.py index 41bc2ea..2fdaaeb 100644 --- a/decoders/nunchuk/__init__.py +++ b/decoders/nunchuk/__init__.py @@ -19,9 +19,8 @@ ## ''' -Nintendo Wii Nunchuk protocol decoder. - -TODO: Description. +This decoder stacks on top of the 'i2c' PD and decodes the Nintendo Wii +Nunchuk controller protocol. Details: http://wiibrew.org/wiki/Wiimote/Extension_Controllers/Nunchuck diff --git a/decoders/onewire_link/__init__.py b/decoders/onewire_link/__init__.py index f55b998..5bd6c55 100644 --- a/decoders/onewire_link/__init__.py +++ b/decoders/onewire_link/__init__.py @@ -19,7 +19,7 @@ ## ''' -1-Wire protocol decoder (link layer). +This protocol decoder handles the 1-Wire link layer. The 1-Wire protocol enables bidirectional communication over a single wire (and ground) between a single master and one or multiple slaves. The protocol @@ -29,8 +29,6 @@ is layered: - Network layer (skip/search/match device ROM addresses) - Transport layer (transport data between 1-Wire master and device) -This protocol decoder handles the 1-Wire link layer. - Sample rate: A sufficiently high samplerate is required to properly detect all the elements of the protocol. A lower samplerate can be used if the master does not use diff --git a/decoders/onewire_network/__init__.py b/decoders/onewire_network/__init__.py index f184a3d..31e9134 100644 --- a/decoders/onewire_network/__init__.py +++ b/decoders/onewire_network/__init__.py @@ -19,7 +19,8 @@ ## ''' -1-Wire protocol decoder (network layer). +This decoder stacks on top of the 'onewire_link' PD and decodes the +1-Wire protocol (network layer). The 1-Wire protocol enables bidirectional communication over a single wire (and ground) between a single master and one or multiple slaves. The protocol @@ -31,11 +32,6 @@ is layered: Network layer: -Protocol output format: -TODO. - -Annotations: - The following link layer annotations are shown: - RESET/PRESENCE True/False diff --git a/decoders/pan1321/__init__.py b/decoders/pan1321/__init__.py index 02e2da5..9bda523 100644 --- a/decoders/pan1321/__init__.py +++ b/decoders/pan1321/__init__.py @@ -19,10 +19,8 @@ ## ''' -Panasonic PAN1321 protocol decoder. - -Details: -TODO +This decoder stacks on top of the 'uart' PD and decodes the Panasonic PAN1321 +Bluetooth module Serial Port Profile (SPP) protocol. ''' from .pd import * diff --git a/decoders/rtc8564/__init__.py b/decoders/rtc8564/__init__.py index 6e67fe9..9a397b1 100644 --- a/decoders/rtc8564/__init__.py +++ b/decoders/rtc8564/__init__.py @@ -19,10 +19,8 @@ ## ''' -Epson RTC-8564 JE/NB protocol decoder. - -Details: -TODO +This decoder stacks on top of the 'i2c' PD and decodes the Epson +RTC-8564 JE/NB real-time clock (RTC) protocol. ''' from .pd import * diff --git a/decoders/sdcard_spi/__init__.py b/decoders/sdcard_spi/__init__.py index 18f9c9a..293b654 100644 --- a/decoders/sdcard_spi/__init__.py +++ b/decoders/sdcard_spi/__init__.py @@ -19,9 +19,8 @@ ## ''' -SD card (SPI mode) low-level protocol decoder. - -TODO: Description. +This decoder stacks on top of the 'spi' PD and decodes the SD card +(SPI mode) low-level protocol. Most SD cards can be accessed via two different protocols/modes: SD mode or SPI mode. @@ -65,9 +64,6 @@ SPI mode properties (differences to SD mode): * In SPI mode cards cannot guarantee their speed class (the host should assume class 0, no matter what the card indicates). * The RCA register is not accessible in SPI mode. - -Details: -TODO ''' from .pd import * diff --git a/decoders/spi/__init__.py b/decoders/spi/__init__.py index 582891a..a65f167 100644 --- a/decoders/spi/__init__.py +++ b/decoders/spi/__init__.py @@ -19,11 +19,9 @@ ## ''' -Serial Peripheral Interface protocol decoder. - -This protocol decoder supports synchronous SPI(-like) protocols with a -clock line, a MISO and MOSI line for data transfer in two directions, -and an optional CS# pin. +The SPI (Serial Peripheral Interface) protocol decoder supports synchronous +SPI(-like) protocols with a clock line, a MISO and MOSI line for data +transfer in two directions, and an optional CS# pin. If CS# is supplied, data is only decoded when CS# is asserted (clock transitions where CS# is not asserted are ignored). If CS# is not supplied, diff --git a/decoders/tlc5620/__init__.py b/decoders/tlc5620/__init__.py index 6cf3401..c615760 100644 --- a/decoders/tlc5620/__init__.py +++ b/decoders/tlc5620/__init__.py @@ -19,7 +19,7 @@ ## ''' -Texas Instruments TLC5620 protocol decoder. +The Texas Instruments TLC5620 is an 8-bit quad DAC. ''' from .pd import * diff --git a/decoders/uart/__init__.py b/decoders/uart/__init__.py index a0c9cef..f3c0693 100644 --- a/decoders/uart/__init__.py +++ b/decoders/uart/__init__.py @@ -19,13 +19,11 @@ ## ''' -UART protocol decoder. - -Universal Asynchronous Receiver Transmitter (UART) is a simple serial +UART (Universal Asynchronous Receiver Transmitter) is a simple serial communication protocol which allows two devices to talk to each other. This decoder should work on all "UART-like" async protocols with one -start bit (0), 7-9 databits, an (optional) parity bit, and one or more +start bit (0), 5-9 databits, an (optional) parity bit, and one or more stop bits (1), in this order. It can be run on one signal line (RX or TX) only, or on two lines (RX + TX). diff --git a/decoders/usb_packet/__init__.py b/decoders/usb_packet/__init__.py index 555dc7f..06b67b9 100644 --- a/decoders/usb_packet/__init__.py +++ b/decoders/usb_packet/__init__.py @@ -19,7 +19,8 @@ ## ''' -USB (low-speed and full-speed) packet protocol decoder. +This decoder stacks on top of the 'usb_signalling' PD and decodes the USB +(low-speed and full-speed) packet protocol. Protocol layer (USB spec, chapter 8): @@ -35,9 +36,6 @@ PID: A PID (packet identifier) follows the SYNC field of every packet. A PID consists of a 4-bit packet type field, and a 4 bit check field. The check field is the one's complement of the packet type field. -Protocol output format: -TODO - Details: https://en.wikipedia.org/wiki/USB http://www.usb.org/developers/docs/ diff --git a/decoders/usb_signalling/__init__.py b/decoders/usb_signalling/__init__.py index 32902e4..2311b1f 100644 --- a/decoders/usb_signalling/__init__.py +++ b/decoders/usb_signalling/__init__.py @@ -19,7 +19,7 @@ ## ''' -USB (low-speed and full-speed) signalling protocol decoder. +This PD decodes the USB (low-speed and full-speed) signalling protocol. Electrical/signalling layer (USB spec, chapter 7): @@ -43,9 +43,6 @@ Data is transferred at a rate of 1.5Mbit/s (low-speed) / 12Mbit/s (full-speed). The SE0 transmitted to signal an end-of-packet is two bit intervals long (low-speed: 1.25uS - 1.50uS, full-speed: 160ns - 175ns). -Protocol output format: -TODO - Details: https://en.wikipedia.org/wiki/USB http://www.usb.org/developers/docs/ diff --git a/decoders/xfp/__init__.py b/decoders/xfp/__init__.py index 627f07b..fa4e8a2 100644 --- a/decoders/xfp/__init__.py +++ b/decoders/xfp/__init__.py @@ -19,7 +19,7 @@ ## ''' -XFP I²C management interface structure decoder. +This PD decodes the XFP I²C management interface structures/protocol. XFP modules include an I²C interface, used to monitor and control various aspects of the module. The specification defines an I²C slave at address -- 2.30.2