sigrok - User contributions [en]

Link Instruments MSO-19

2012-01-22T13:08:48Z

Seventhguardian: /* Device reply description */

[[File:MSO-19.JPG|thumb|right|Link Instruments MSO-19]]
[[File:MSO-19-naked.jpg|thumb|right|PCB Front]]

The [http://www.linkinstruments.com/mso19.htm Link Instruments MSO-19] is a 2GSa/s oscilloscope, 200MSa/s logic analyzer, 100MSa/s pattern generator and a TDR. It is also extremely portable and is only $249 (including probe, clips, wires and software).

See [[Link Instruments MSO-19/Info]] for more details (such as '''lsusb -vvv''' output) about the device.

== Hardware ==

* [http://www.latticesemi.com/products/cpld/machxo/index.cfm Lattice MachXO LCMXO2280 PLD]
* [http://www.intersil.com/products/deviceinfo.asp?pn=KAD2710C-10 Kenet KAD2710C-10 10bit, 105MSPS ADC]
* [http://www.silabs.com/products/interface/usbtouart/Pages/usb-to-uart-bridge.aspx Silabs CP2103 USB to UART Bridge]

== Original software ==

Link Instruments ships the product with its ''FrontPanelTM Oscilloscope software''. Software is for Windows only. Written in .NET (C#), without any kind of obfuscation, which makes it a real breeze to reverse engineer.

== USB protocol ==

It's just serial-over-USB, supported by the Linux kernel through the '''[http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/usb/serial/cp210x.c;hb=90a4c0f51e8e44111a926be6f4c87af3938a79c3 cp210x]''' driver, though as of Kernel 3.2.1 it needs to be patched to recognize the Link Instruments Vendor/Product ID ('''3195:f190''').

iSerial was exploited by Link Instruments to store hardware type, hardware revision, calibration quirks and the actual serial number.
*for an iSerial of 4294333650260000000 we have:
**42943 336 502 6 0 000000
***vbit = 42943 / 10000
***dacoffset = 336
***offsetrange = 502
***hwmodel = 6
***hwrev = 0
***serial number = 000000

== Serial protocol ==
*Control message
**Fixed header: 0x40, 0x4c, 0x44, 0x53, 0x7e
**Variable size payload, 16bit aligned
***Looks like each 16bits of payload are a register write operation
***register writes are 4bits for addr, 8 bits for value, 2 unused bits and 2 bits im not sure what they are for :)
**** The simplest explanation for the unused bits is that the device bus width is 7 bits (being a CPLD that is very acceptable).
**** The 2 special bits seem to be synchronization bits. 0x7e violates the conversion (high byte), and that may be used to reset the CPLD parser at the end of the packet.
***.?12 AAAA .?34 5678
***Conversion is: ((v & 0x3f) | ((v & 0xc0) << 6) | ((a & 0xf) << 8) | (((v ^ 0x20) & 0x20) << 1) | (((v ^ 0x80) & 0x80) << 7))
***Byte order is big endian
**Fixed footer: 0x7e

== Registers description ==
There is no way to read from registers, only write is possible.

The purpose of registers 0 to 13 seems to depend on the value of the 2 lsbs of register 15.

===== Registers for ((R15 & 0x3) == 0x0) =====

* Read Sample buffer (1): Write 0 to this register to read the samples buffer.
* Read Trigger status (2): Write 0 to this register to read the trigger status.
* TRIGGER_CONFIG_L (3):
** lsbyte of the threshold value.
* TRIGGER_CONFIG_H (4):
** bits [1:0] hold the msbits of the threshold value
** (1 << 2): Trigger on falling edge
** (1 << 4 | 1 << 3): Select the purpose of the "Output" connector:
*** 00 : Trigger pulse output
*** 01 : PWM DAC from the pattern generator buffer.
*** 10 : (?) never seen...
*** 11 : White noise
** (1 << 6 | 1 << 5): These hold the DSO/LA trigger configuration:
*** 00 : DSO level trigger
*** 01 : DSO pulse trigger, width less than TRIGGER_WIDTH
*** 10 : DSO pulse trigger, width equal or greater than TRIGGER_WIDTH
*** 11 : LA combination trigger
* LA_TRIGGER(5): The value of the LA byte that generates a trigger event (in that mode).
* LA_TRIGGER_MASK(6): The mask for the LA_TRIGGER (bits set to 0 matter, those set to 1 are ignored).
* SCOPE_TRIGGER_HOLDOFF1 (7):
* SCOPE_TRIGGER_HOLDOFF2 (8): Store the trigger holdoff (delay between a triggering event and the trigger rearming).
* CLKRATE(9-10):
* TRIGGER_WIDTH (11): Stores the pulse width for the DSO pulse trigger, in sample units. Forced to be greater than 3 by the mso19 app.
* DAC(12-13):

===== Registers for ((R15 & 0x3) == 0x1) =====

This mode seems to be used to configure the pattern generator.

* REG_PATGEN_CLOCK1 (2) :
* REG_PATGEN_CLOCK2 (3) : Stores the sample clock configuration. Not sure how these two bytes work together...
* REG_PATGEN_START_L (4):
* REG_PATGEN_START_H (5): The start address for the pattern generator buffer (1023 samples long). When writing to the buffer, it is set to 0.
* REG_PATGEN_END_L (6):
* REG_PATGEN_END_H (7): The end address for the pattern generator buffer (1023 samples long). When writing the buffer, it is set to 0x3ff. When in normal mode (to set the end of the output) it is writen as the end address minus 2 (probably due to the actual implementation details).
* PATGEN_CFG (8): Configures the pattern generator.
** (1 << 0): Continuous mode ? (only seems to be allowed for the waveform generator, not for the pattern generator. why?)
** (1 << 1): Enter pattern write mode.
** (1 << 3 | 1 << 2):
*** 11 : Manual start (starts after a pulse in PATGEN_TRIG)
*** 10 : Start on MSO trigger
*** 01 : Start on MSO "Go" (MSO trigger arm)
*** 00 : Disabled
* PATGEN_TRIG (9): writen 0x1 and then 0x0, acts as a manual trigger to activate "stuff".
* PATGEN_WORD (10): In pattern write mode, takes the word for the current "instant".
* PATGEN_IO (11): In pattern write mode, writing 0x1 makes the instant an output one, and writing 0x0 makes it an input one (?)
* PATGEN_LOOPS (12): Stores the number of loops for the pattern generator. Set to 1 for pattern buffer writing mode.
* PATTERN_MASK (13): Stores the output bit mask (1 for enabled bits, 0 for disabled bits)

===== Registers for ((R15 & 0x3) == 0x2) =====

This mode is used to set the i2c or spi triggers.
NOTES:
* the difference between i2c and spi capture seems to be the TRIGGER_CFG_H bits (see R15 = 0)
* how does the hardware handle the start/stop conditions or the ack bit??

The protocol matcher seems to be comprised of a 4 byte shift register. The serial bits are shifted in through the last byte comparator (word 3) and exit through the first byte comparator (word 0). This is why if the trigger is set up with less than 3 words, the first bytes are the ones that end up matching everything (word set to 0x00, mask set to 0xff).

The mask bytes have their bits set to 1 for "ignore", and 0 for "match". The protocol matching block simply doing something this for every bit i:

matches[i] = (read[i] ^ word[i]) | mask[i]

The final result is the and'ing of the resulting 32 bits.

* TRIG_WORD0 (0): Hold the comparison words for the comparator.
* TRIG_WORD1 (1):
* TRIG_WORD2 (2):
* TRIG_WORD2 (3):
* TRIG_MASK0 (4): Holds the mask for the comparator (bits set at 1 always produce a positive match)
* TRIG_MASK1 (5):
* TRIG_MASK2 (6):
* TRIG_MASK3 (7):
* TRIG_SPI_MODE (8): Holds the SPI mode for triggering (valid modes 0, 1, 2, 3). Is set to 0 for I2C (not sure if mandatory)

===== Registers which don't seem to change purpose (so far) =====

*CONTROL1 (14):
**(1 << 0): Reset SFM
**(1 << 3): Force trigger
**(1 << 4): Enable ADC (?)
**(1 << 6): Reset ADC (?)
**(1 << 7): Led on/off
*CONTROL2 (15):
** (1 << 1 | 1 << 0): Control which register bank is selected for writing:
*** 00: The DSO and LA control bank is selected
*** 01: The PG (patern generator) control bank is selected
*** 10: The PT (protocol trigger) control bank is selected
** (1 << 5): Slow mode (?) (set for the low clock rates, probably enables a clock divider)

== Device reply description ==

* After writing 0x0 to the registers (1) or (2) of bank 0, the device replies with either 3072 bytes (1), or 1 byte (2).
* Only 7 bits are used from each byte.
* Bit (1 << 6) indicates which type of message this is:
** 0: This is a "status" message.
** 1: This is a "data" message.

===== STATUS ((1 << 6) == 0) =====
* The reply comprises just one byte. The lower nibble contains the trigger status (t), while the other two bits contain other status info (?)
** [ (ignored) 0 (h1) (h0) (t3) (t2) (t1) (t0) ]

Bit description:
** (1 << 5): Seems to be always set to 1 (?)
** (1 << 4): The state of the control bit (1 << 4): adc enabled (?).
** (1 << 3): Set to 1 upon successful triggering.
** (1 << 2): Set to 1 when the trigger block is armed and the adc (1 << 4) is also enabled (?)
** (1 << 1): Set to 1 when the trigger block is armed but the adc (1 << 4) is not (?)
** (1 << 0): Seems to be the oposite of bit (1 << 2) (?)

* Ususal values for t(3:0):
** 0x6: Triggered (data ready on the samples buffer).
** 0x4: Trigger armed
** 0x3: Someone messed up and armed the trigger without enabling ctl bit (1 << 4) (???)
** 0x1: Trigger not armed

===== DATA ((1 << 6) == 1) =====
* The reply is 24 bit aligned, and contains both the 10 bit analog sample data (a) and the 8 bit digital sample data (d).
* There's a total of 3072 bytes, comprising 1024 samples.
* For each group of 24 bits (a "sample"):
** (byte 0): [ (ignored) 1 (a5) (a4) (a3) (a2) (a1) (a0) ]
** (byte 1): [ (ignored) 1 (d1) (d0) (a9) (a8) (a7) (a6) ]
** (byte 2): [ (ignored) 1 (d7) (d6) (d5) (d4) (d3) (d2) ]

== Device operation ==

The trigger status must be checked periodically, by writing 0 to the "Read Status" register (address 0 of bank 0). The returned value indicates the device status.

=== Startup ===

* The MSO19 application starts by checking the device status. It accepts the values 0x21 or 0x31 as normal, before proceeding.
* It then resets the ADC, and checks for the device status again, and also accepts the values 0x21 and 0x31 as normal.
(...)

=== Capture Start ===

Upon starting a capture, by hitting the "Go" button:
* If the DSO or the DAC need to be configured, the app resets the FSM (finite state machine), and then configures them both.
* If the PG needs to be configured, the app configures it.
* The app then arms the trigger system.
* Finally the app issues a trigger check (writing 0 to the register), and waits for the serial reply.

=== Handle Serial Reply ===

* First the app checks how many bytes there are waiting on the serial port buffer. It only accepts two byte lengths, 3072 bytes and 1 byte.
* The app then checks if the first byte has bit 6 turned off ((byte & (1 << 6)) == 0), and if it is, it assumes it's a trigger status. Otherwise it assumes it's sample data.

Link Instruments MSO-19

2012-01-22T12:53:49Z

Seventhguardian: /* STATUS ((1 << 6) == 0) */

[[File:MSO-19.JPG|thumb|right|Link Instruments MSO-19]]
[[File:MSO-19-naked.jpg|thumb|right|PCB Front]]

The [http://www.linkinstruments.com/mso19.htm Link Instruments MSO-19] is a 2GSa/s oscilloscope, 200MSa/s logic analyzer, 100MSa/s pattern generator and a TDR. It is also extremely portable and is only $249 (including probe, clips, wires and software).

See [[Link Instruments MSO-19/Info]] for more details (such as '''lsusb -vvv''' output) about the device.

== Hardware ==

* [http://www.latticesemi.com/products/cpld/machxo/index.cfm Lattice MachXO LCMXO2280 PLD]
* [http://www.intersil.com/products/deviceinfo.asp?pn=KAD2710C-10 Kenet KAD2710C-10 10bit, 105MSPS ADC]
* [http://www.silabs.com/products/interface/usbtouart/Pages/usb-to-uart-bridge.aspx Silabs CP2103 USB to UART Bridge]

== Original software ==

Link Instruments ships the product with its ''FrontPanelTM Oscilloscope software''. Software is for Windows only. Written in .NET (C#), without any kind of obfuscation, which makes it a real breeze to reverse engineer.

== USB protocol ==

It's just serial-over-USB, supported by the Linux kernel through the '''[http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/usb/serial/cp210x.c;hb=90a4c0f51e8e44111a926be6f4c87af3938a79c3 cp210x]''' driver, though as of Kernel 3.2.1 it needs to be patched to recognize the Link Instruments Vendor/Product ID ('''3195:f190''').

iSerial was exploited by Link Instruments to store hardware type, hardware revision, calibration quirks and the actual serial number.
*for an iSerial of 4294333650260000000 we have:
**42943 336 502 6 0 000000
***vbit = 42943 / 10000
***dacoffset = 336
***offsetrange = 502
***hwmodel = 6
***hwrev = 0
***serial number = 000000

== Serial protocol ==
*Control message
**Fixed header: 0x40, 0x4c, 0x44, 0x53, 0x7e
**Variable size payload, 16bit aligned
***Looks like each 16bits of payload are a register write operation
***register writes are 4bits for addr, 8 bits for value, 2 unused bits and 2 bits im not sure what they are for :)
**** The simplest explanation for the unused bits is that the device bus width is 7 bits (being a CPLD that is very acceptable).
**** The 2 special bits seem to be synchronization bits. 0x7e violates the conversion (high byte), and that may be used to reset the CPLD parser at the end of the packet.
***.?12 AAAA .?34 5678
***Conversion is: ((v & 0x3f) | ((v & 0xc0) << 6) | ((a & 0xf) << 8) | (((v ^ 0x20) & 0x20) << 1) | (((v ^ 0x80) & 0x80) << 7))
***Byte order is big endian
**Fixed footer: 0x7e

== Registers description ==
There is no way to read from registers, only write is possible.

The purpose of registers 0 to 13 seems to depend on the value of the 2 lsbs of register 15.

===== Registers for ((R15 & 0x3) == 0x0) =====

* Read Sample buffer (1): Write 0 to this register to read the samples buffer.
* Read Trigger status (2): Write 0 to this register to read the trigger status.
* TRIGGER_CONFIG_L (3):
** lsbyte of the threshold value.
* TRIGGER_CONFIG_H (4):
** bits [1:0] hold the msbits of the threshold value
** (1 << 2): Trigger on falling edge
** (1 << 4 | 1 << 3): Select the purpose of the "Output" connector:
*** 00 : Trigger pulse output
*** 01 : PWM DAC from the pattern generator buffer.
*** 10 : (?) never seen...
*** 11 : White noise
** (1 << 6 | 1 << 5): These hold the DSO/LA trigger configuration:
*** 00 : DSO level trigger
*** 01 : DSO pulse trigger, width less than TRIGGER_WIDTH
*** 10 : DSO pulse trigger, width equal or greater than TRIGGER_WIDTH
*** 11 : LA combination trigger
* LA_TRIGGER(5): The value of the LA byte that generates a trigger event (in that mode).
* LA_TRIGGER_MASK(6): The mask for the LA_TRIGGER (bits set to 0 matter, those set to 1 are ignored).
* SCOPE_TRIGGER_HOLDOFF1 (7):
* SCOPE_TRIGGER_HOLDOFF2 (8): Store the trigger holdoff (delay between a triggering event and the trigger rearming).
* CLKRATE(9-10):
* TRIGGER_WIDTH (11): Stores the pulse width for the DSO pulse trigger, in sample units. Forced to be greater than 3 by the mso19 app.
* DAC(12-13):

===== Registers for ((R15 & 0x3) == 0x1) =====

This mode seems to be used to configure the pattern generator.

* REG_PATGEN_CLOCK1 (2) :
* REG_PATGEN_CLOCK2 (3) : Stores the sample clock configuration. Not sure how these two bytes work together...
* REG_PATGEN_START_L (4):
* REG_PATGEN_START_H (5): The start address for the pattern generator buffer (1023 samples long). When writing to the buffer, it is set to 0.
* REG_PATGEN_END_L (6):
* REG_PATGEN_END_H (7): The end address for the pattern generator buffer (1023 samples long). When writing the buffer, it is set to 0x3ff. When in normal mode (to set the end of the output) it is writen as the end address minus 2 (probably due to the actual implementation details).
* PATGEN_CFG (8): Configures the pattern generator.
** (1 << 0): Continuous mode ? (only seems to be allowed for the waveform generator, not for the pattern generator. why?)
** (1 << 1): Enter pattern write mode.
** (1 << 3 | 1 << 2):
*** 11 : Manual start (starts after a pulse in PATGEN_TRIG)
*** 10 : Start on MSO trigger
*** 01 : Start on MSO "Go" (MSO trigger arm)
*** 00 : Disabled
* PATGEN_TRIG (9): writen 0x1 and then 0x0, acts as a manual trigger to activate "stuff".
* PATGEN_WORD (10): In pattern write mode, takes the word for the current "instant".
* PATGEN_IO (11): In pattern write mode, writing 0x1 makes the instant an output one, and writing 0x0 makes it an input one (?)
* PATGEN_LOOPS (12): Stores the number of loops for the pattern generator. Set to 1 for pattern buffer writing mode.
* PATTERN_MASK (13): Stores the output bit mask (1 for enabled bits, 0 for disabled bits)

===== Registers for ((R15 & 0x3) == 0x2) =====

This mode is used to set the i2c or spi triggers.
NOTES:
* the difference between i2c and spi capture seems to be the TRIGGER_CFG_H bits (see R15 = 0)
* how does the hardware handle the start/stop conditions or the ack bit??

The protocol matcher seems to be comprised of a 4 byte shift register. The serial bits are shifted in through the last byte comparator (word 3) and exit through the first byte comparator (word 0). This is why if the trigger is set up with less than 3 words, the first bytes are the ones that end up matching everything (word set to 0x00, mask set to 0xff).

The mask bytes have their bits set to 1 for "ignore", and 0 for "match". The protocol matching block simply doing something this for every bit i:

matches[i] = (read[i] ^ word[i]) | mask[i]

The final result is the and'ing of the resulting 32 bits.

* TRIG_WORD0 (0): Hold the comparison words for the comparator.
* TRIG_WORD1 (1):
* TRIG_WORD2 (2):
* TRIG_WORD2 (3):
* TRIG_MASK0 (4): Holds the mask for the comparator (bits set at 1 always produce a positive match)
* TRIG_MASK1 (5):
* TRIG_MASK2 (6):
* TRIG_MASK3 (7):
* TRIG_SPI_MODE (8): Holds the SPI mode for triggering (valid modes 0, 1, 2, 3). Is set to 0 for I2C (not sure if mandatory)

===== Registers which don't seem to change purpose (so far) =====

*CONTROL1 (14):
**(1 << 0): Reset SFM
**(1 << 3): Force trigger
**(1 << 4): Enable ADC (?)
**(1 << 6): Reset ADC (?)
**(1 << 7): Led on/off
*CONTROL2 (15):
** (1 << 1 | 1 << 0): Control which register bank is selected for writing:
*** 00: The DSO and LA control bank is selected
*** 01: The PG (patern generator) control bank is selected
*** 10: The PT (protocol trigger) control bank is selected
** (1 << 5): Slow mode (?) (set for the low clock rates, probably enables a clock divider)

== Device reply description ==

* After writing 0x0 to the registers (1) or (2) of bank 0, the device replies with either 3072 bytes (1), or 1 byte (2).
* Only 7 bits are used from each byte.
* Bit (1 << 6) indicates which type of message this is:
** 0: This is a "status" message.
** 1: This is a "data" message.

===== STATUS ((1 << 6) == 0) =====
* The reply comprises just one byte. The lower nibble contains the trigger status (t), while the other two bits contain other status info (?)
** [ (ignored) 0 (h1) (h0) (t3) (t2) (t1) (t0) ]

Bit description:
** (1 << 5): Seems to be always set to 1 (?)
** (1 << 4): The state of the control bit (1 << 4): adc enabled (?).
** (1 << 3): Set to 1 by the trigger block upon successful triggering.
** (1 << 2): Set to 1 by the trigger block when it is armed.
** (1 << 1): Rare state, seems to be set to 1 when something is messed up (?)
** (1 << 0): Seems to be the oposite of bit (1 << 2) (?)

* Ususal values for t(3:0):
** 0x6: Triggered (data ready on the samples buffer).
** 0x4: Trigger armed
** 0x1: Trigger not armed

===== DATA ((1 << 6) == 1) =====
* The reply is 24 bit aligned, and contains both the 10 bit analog sample data (a) and the 8 bit digital sample data (d).
* There's a total of 3072 bytes, comprising 1024 samples.
* For each group of 24 bits (a "sample"):
** (byte 0): [ (ignored) 1 (a5) (a4) (a3) (a2) (a1) (a0) ]
** (byte 1): [ (ignored) 1 (d1) (d0) (a9) (a8) (a7) (a6) ]
** (byte 2): [ (ignored) 1 (d7) (d6) (d5) (d4) (d3) (d2) ]

== Device operation ==

The trigger status must be checked periodically, by writing 0 to the "Read Status" register (address 0 of bank 0). The returned value indicates the device status.

=== Startup ===

* The MSO19 application starts by checking the device status. It accepts the values 0x21 or 0x31 as normal, before proceeding.
* It then resets the ADC, and checks for the device status again, and also accepts the values 0x21 and 0x31 as normal.
(...)

=== Capture Start ===

Upon starting a capture, by hitting the "Go" button:
* If the DSO or the DAC need to be configured, the app resets the FSM (finite state machine), and then configures them both.
* If the PG needs to be configured, the app configures it.
* The app then arms the trigger system.
* Finally the app issues a trigger check (writing 0 to the register), and waits for the serial reply.

=== Handle Serial Reply ===

* First the app checks how many bytes there are waiting on the serial port buffer. It only accepts two byte lengths, 3072 bytes and 1 byte.
* The app then checks if the first byte has bit 6 turned off ((byte & (1 << 6)) == 0), and if it is, it assumes it's a trigger status. Otherwise it assumes it's sample data.

Link Instruments MSO-19

2012-01-22T12:53:28Z

Seventhguardian: /* Device reply description */

[[File:MSO-19.JPG|thumb|right|Link Instruments MSO-19]]
[[File:MSO-19-naked.jpg|thumb|right|PCB Front]]

The [http://www.linkinstruments.com/mso19.htm Link Instruments MSO-19] is a 2GSa/s oscilloscope, 200MSa/s logic analyzer, 100MSa/s pattern generator and a TDR. It is also extremely portable and is only $249 (including probe, clips, wires and software).

See [[Link Instruments MSO-19/Info]] for more details (such as '''lsusb -vvv''' output) about the device.

== Hardware ==

* [http://www.latticesemi.com/products/cpld/machxo/index.cfm Lattice MachXO LCMXO2280 PLD]
* [http://www.intersil.com/products/deviceinfo.asp?pn=KAD2710C-10 Kenet KAD2710C-10 10bit, 105MSPS ADC]
* [http://www.silabs.com/products/interface/usbtouart/Pages/usb-to-uart-bridge.aspx Silabs CP2103 USB to UART Bridge]

== Original software ==

Link Instruments ships the product with its ''FrontPanelTM Oscilloscope software''. Software is for Windows only. Written in .NET (C#), without any kind of obfuscation, which makes it a real breeze to reverse engineer.

== USB protocol ==

It's just serial-over-USB, supported by the Linux kernel through the '''[http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/usb/serial/cp210x.c;hb=90a4c0f51e8e44111a926be6f4c87af3938a79c3 cp210x]''' driver, though as of Kernel 3.2.1 it needs to be patched to recognize the Link Instruments Vendor/Product ID ('''3195:f190''').

iSerial was exploited by Link Instruments to store hardware type, hardware revision, calibration quirks and the actual serial number.
*for an iSerial of 4294333650260000000 we have:
**42943 336 502 6 0 000000
***vbit = 42943 / 10000
***dacoffset = 336
***offsetrange = 502
***hwmodel = 6
***hwrev = 0
***serial number = 000000

== Serial protocol ==
*Control message
**Fixed header: 0x40, 0x4c, 0x44, 0x53, 0x7e
**Variable size payload, 16bit aligned
***Looks like each 16bits of payload are a register write operation
***register writes are 4bits for addr, 8 bits for value, 2 unused bits and 2 bits im not sure what they are for :)
**** The simplest explanation for the unused bits is that the device bus width is 7 bits (being a CPLD that is very acceptable).
**** The 2 special bits seem to be synchronization bits. 0x7e violates the conversion (high byte), and that may be used to reset the CPLD parser at the end of the packet.
***.?12 AAAA .?34 5678
***Conversion is: ((v & 0x3f) | ((v & 0xc0) << 6) | ((a & 0xf) << 8) | (((v ^ 0x20) & 0x20) << 1) | (((v ^ 0x80) & 0x80) << 7))
***Byte order is big endian
**Fixed footer: 0x7e

== Registers description ==
There is no way to read from registers, only write is possible.

The purpose of registers 0 to 13 seems to depend on the value of the 2 lsbs of register 15.

===== Registers for ((R15 & 0x3) == 0x0) =====

* Read Sample buffer (1): Write 0 to this register to read the samples buffer.
* Read Trigger status (2): Write 0 to this register to read the trigger status.
* TRIGGER_CONFIG_L (3):
** lsbyte of the threshold value.
* TRIGGER_CONFIG_H (4):
** bits [1:0] hold the msbits of the threshold value
** (1 << 2): Trigger on falling edge
** (1 << 4 | 1 << 3): Select the purpose of the "Output" connector:
*** 00 : Trigger pulse output
*** 01 : PWM DAC from the pattern generator buffer.
*** 10 : (?) never seen...
*** 11 : White noise
** (1 << 6 | 1 << 5): These hold the DSO/LA trigger configuration:
*** 00 : DSO level trigger
*** 01 : DSO pulse trigger, width less than TRIGGER_WIDTH
*** 10 : DSO pulse trigger, width equal or greater than TRIGGER_WIDTH
*** 11 : LA combination trigger
* LA_TRIGGER(5): The value of the LA byte that generates a trigger event (in that mode).
* LA_TRIGGER_MASK(6): The mask for the LA_TRIGGER (bits set to 0 matter, those set to 1 are ignored).
* SCOPE_TRIGGER_HOLDOFF1 (7):
* SCOPE_TRIGGER_HOLDOFF2 (8): Store the trigger holdoff (delay between a triggering event and the trigger rearming).
* CLKRATE(9-10):
* TRIGGER_WIDTH (11): Stores the pulse width for the DSO pulse trigger, in sample units. Forced to be greater than 3 by the mso19 app.
* DAC(12-13):

===== Registers for ((R15 & 0x3) == 0x1) =====

This mode seems to be used to configure the pattern generator.

* REG_PATGEN_CLOCK1 (2) :
* REG_PATGEN_CLOCK2 (3) : Stores the sample clock configuration. Not sure how these two bytes work together...
* REG_PATGEN_START_L (4):
* REG_PATGEN_START_H (5): The start address for the pattern generator buffer (1023 samples long). When writing to the buffer, it is set to 0.
* REG_PATGEN_END_L (6):
* REG_PATGEN_END_H (7): The end address for the pattern generator buffer (1023 samples long). When writing the buffer, it is set to 0x3ff. When in normal mode (to set the end of the output) it is writen as the end address minus 2 (probably due to the actual implementation details).
* PATGEN_CFG (8): Configures the pattern generator.
** (1 << 0): Continuous mode ? (only seems to be allowed for the waveform generator, not for the pattern generator. why?)
** (1 << 1): Enter pattern write mode.
** (1 << 3 | 1 << 2):
*** 11 : Manual start (starts after a pulse in PATGEN_TRIG)
*** 10 : Start on MSO trigger
*** 01 : Start on MSO "Go" (MSO trigger arm)
*** 00 : Disabled
* PATGEN_TRIG (9): writen 0x1 and then 0x0, acts as a manual trigger to activate "stuff".
* PATGEN_WORD (10): In pattern write mode, takes the word for the current "instant".
* PATGEN_IO (11): In pattern write mode, writing 0x1 makes the instant an output one, and writing 0x0 makes it an input one (?)
* PATGEN_LOOPS (12): Stores the number of loops for the pattern generator. Set to 1 for pattern buffer writing mode.
* PATTERN_MASK (13): Stores the output bit mask (1 for enabled bits, 0 for disabled bits)

===== Registers for ((R15 & 0x3) == 0x2) =====

This mode is used to set the i2c or spi triggers.
NOTES:
* the difference between i2c and spi capture seems to be the TRIGGER_CFG_H bits (see R15 = 0)
* how does the hardware handle the start/stop conditions or the ack bit??

The protocol matcher seems to be comprised of a 4 byte shift register. The serial bits are shifted in through the last byte comparator (word 3) and exit through the first byte comparator (word 0). This is why if the trigger is set up with less than 3 words, the first bytes are the ones that end up matching everything (word set to 0x00, mask set to 0xff).

The mask bytes have their bits set to 1 for "ignore", and 0 for "match". The protocol matching block simply doing something this for every bit i:

matches[i] = (read[i] ^ word[i]) | mask[i]

The final result is the and'ing of the resulting 32 bits.

* TRIG_WORD0 (0): Hold the comparison words for the comparator.
* TRIG_WORD1 (1):
* TRIG_WORD2 (2):
* TRIG_WORD2 (3):
* TRIG_MASK0 (4): Holds the mask for the comparator (bits set at 1 always produce a positive match)
* TRIG_MASK1 (5):
* TRIG_MASK2 (6):
* TRIG_MASK3 (7):
* TRIG_SPI_MODE (8): Holds the SPI mode for triggering (valid modes 0, 1, 2, 3). Is set to 0 for I2C (not sure if mandatory)

===== Registers which don't seem to change purpose (so far) =====

*CONTROL1 (14):
**(1 << 0): Reset SFM
**(1 << 3): Force trigger
**(1 << 4): Enable ADC (?)
**(1 << 6): Reset ADC (?)
**(1 << 7): Led on/off
*CONTROL2 (15):
** (1 << 1 | 1 << 0): Control which register bank is selected for writing:
*** 00: The DSO and LA control bank is selected
*** 01: The PG (patern generator) control bank is selected
*** 10: The PT (protocol trigger) control bank is selected
** (1 << 5): Slow mode (?) (set for the low clock rates, probably enables a clock divider)

== Device reply description ==

* After writing 0x0 to the registers (1) or (2) of bank 0, the device replies with either 3072 bytes (1), or 1 byte (2).
* Only 7 bits are used from each byte.
* Bit (1 << 6) indicates which type of message this is:
** 0: This is a "status" message.
** 1: This is a "data" message.

===== STATUS ((1 << 6) == 0) =====
* The reply comprises just one byte. The lower nibble contains the trigger status (t), while the other two bits contain other status info (?)
** [ <ignored> 0 (h1) (h0) (t3) (t2) (t1) (t0) ]

Bit description:
** (1 << 5): Seems to be always set to 1 (?)
** (1 << 4): The state of the control bit (1 << 4): adc enabled (?).
** (1 << 3): Set to 1 by the trigger block upon successful triggering.
** (1 << 2): Set to 1 by the trigger block when it is armed.
** (1 << 1): Rare state, seems to be set to 1 when something is messed up (?)
** (1 << 0): Seems to be the oposite of bit (1 << 2) (?)

* Ususal values for t(3:0):
** 0x6: Triggered (data ready on the samples buffer).
** 0x4: Trigger armed
** 0x1: Trigger not armed

===== DATA ((1 << 6) == 1) =====
* The reply is 24 bit aligned, and contains both the 10 bit analog sample data (a) and the 8 bit digital sample data (d).
* There's a total of 3072 bytes, comprising 1024 samples.
* For each group of 24 bits (a "sample"):
** (byte 0): [ (ignored) 1 (a5) (a4) (a3) (a2) (a1) (a0) ]
** (byte 1): [ (ignored) 1 (d1) (d0) (a9) (a8) (a7) (a6) ]
** (byte 2): [ (ignored) 1 (d7) (d6) (d5) (d4) (d3) (d2) ]

== Device operation ==

The trigger status must be checked periodically, by writing 0 to the "Read Status" register (address 0 of bank 0). The returned value indicates the device status.

=== Startup ===

* The MSO19 application starts by checking the device status. It accepts the values 0x21 or 0x31 as normal, before proceeding.
* It then resets the ADC, and checks for the device status again, and also accepts the values 0x21 and 0x31 as normal.
(...)

=== Capture Start ===

Upon starting a capture, by hitting the "Go" button:
* If the DSO or the DAC need to be configured, the app resets the FSM (finite state machine), and then configures them both.
* If the PG needs to be configured, the app configures it.
* The app then arms the trigger system.
* Finally the app issues a trigger check (writing 0 to the register), and waits for the serial reply.

=== Handle Serial Reply ===

* First the app checks how many bytes there are waiting on the serial port buffer. It only accepts two byte lengths, 3072 bytes and 1 byte.
* The app then checks if the first byte has bit 6 turned off ((byte & (1 << 6)) == 0), and if it is, it assumes it's a trigger status. Otherwise it assumes it's sample data.

Link Instruments MSO-19

2012-01-22T12:47:27Z

Seventhguardian: /* Registers which don't seem to change purpose (so far) */

[[File:MSO-19.JPG|thumb|right|Link Instruments MSO-19]]
[[File:MSO-19-naked.jpg|thumb|right|PCB Front]]

The [http://www.linkinstruments.com/mso19.htm Link Instruments MSO-19] is a 2GSa/s oscilloscope, 200MSa/s logic analyzer, 100MSa/s pattern generator and a TDR. It is also extremely portable and is only $249 (including probe, clips, wires and software).

See [[Link Instruments MSO-19/Info]] for more details (such as '''lsusb -vvv''' output) about the device.

== Hardware ==

* [http://www.latticesemi.com/products/cpld/machxo/index.cfm Lattice MachXO LCMXO2280 PLD]
* [http://www.intersil.com/products/deviceinfo.asp?pn=KAD2710C-10 Kenet KAD2710C-10 10bit, 105MSPS ADC]
* [http://www.silabs.com/products/interface/usbtouart/Pages/usb-to-uart-bridge.aspx Silabs CP2103 USB to UART Bridge]

== Original software ==

Link Instruments ships the product with its ''FrontPanelTM Oscilloscope software''. Software is for Windows only. Written in .NET (C#), without any kind of obfuscation, which makes it a real breeze to reverse engineer.

== USB protocol ==

It's just serial-over-USB, supported by the Linux kernel through the '''[http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/usb/serial/cp210x.c;hb=90a4c0f51e8e44111a926be6f4c87af3938a79c3 cp210x]''' driver, though as of Kernel 3.2.1 it needs to be patched to recognize the Link Instruments Vendor/Product ID ('''3195:f190''').

iSerial was exploited by Link Instruments to store hardware type, hardware revision, calibration quirks and the actual serial number.
*for an iSerial of 4294333650260000000 we have:
**42943 336 502 6 0 000000
***vbit = 42943 / 10000
***dacoffset = 336
***offsetrange = 502
***hwmodel = 6
***hwrev = 0
***serial number = 000000

== Serial protocol ==
*Control message
**Fixed header: 0x40, 0x4c, 0x44, 0x53, 0x7e
**Variable size payload, 16bit aligned
***Looks like each 16bits of payload are a register write operation
***register writes are 4bits for addr, 8 bits for value, 2 unused bits and 2 bits im not sure what they are for :)
**** The simplest explanation for the unused bits is that the device bus width is 7 bits (being a CPLD that is very acceptable).
**** The 2 special bits seem to be synchronization bits. 0x7e violates the conversion (high byte), and that may be used to reset the CPLD parser at the end of the packet.
***.?12 AAAA .?34 5678
***Conversion is: ((v & 0x3f) | ((v & 0xc0) << 6) | ((a & 0xf) << 8) | (((v ^ 0x20) & 0x20) << 1) | (((v ^ 0x80) & 0x80) << 7))
***Byte order is big endian
**Fixed footer: 0x7e

== Registers description ==
There is no way to read from registers, only write is possible.

The purpose of registers 0 to 13 seems to depend on the value of the 2 lsbs of register 15.

===== Registers for ((R15 & 0x3) == 0x0) =====

* Read Sample buffer (1): Write 0 to this register to read the samples buffer.
* Read Trigger status (2): Write 0 to this register to read the trigger status.
* TRIGGER_CONFIG_L (3):
** lsbyte of the threshold value.
* TRIGGER_CONFIG_H (4):
** bits [1:0] hold the msbits of the threshold value
** (1 << 2): Trigger on falling edge
** (1 << 4 | 1 << 3): Select the purpose of the "Output" connector:
*** 00 : Trigger pulse output
*** 01 : PWM DAC from the pattern generator buffer.
*** 10 : (?) never seen...
*** 11 : White noise
** (1 << 6 | 1 << 5): These hold the DSO/LA trigger configuration:
*** 00 : DSO level trigger
*** 01 : DSO pulse trigger, width less than TRIGGER_WIDTH
*** 10 : DSO pulse trigger, width equal or greater than TRIGGER_WIDTH
*** 11 : LA combination trigger
* LA_TRIGGER(5): The value of the LA byte that generates a trigger event (in that mode).
* LA_TRIGGER_MASK(6): The mask for the LA_TRIGGER (bits set to 0 matter, those set to 1 are ignored).
* SCOPE_TRIGGER_HOLDOFF1 (7):
* SCOPE_TRIGGER_HOLDOFF2 (8): Store the trigger holdoff (delay between a triggering event and the trigger rearming).
* CLKRATE(9-10):
* TRIGGER_WIDTH (11): Stores the pulse width for the DSO pulse trigger, in sample units. Forced to be greater than 3 by the mso19 app.
* DAC(12-13):

===== Registers for ((R15 & 0x3) == 0x1) =====

This mode seems to be used to configure the pattern generator.

* REG_PATGEN_CLOCK1 (2) :
* REG_PATGEN_CLOCK2 (3) : Stores the sample clock configuration. Not sure how these two bytes work together...
* REG_PATGEN_START_L (4):
* REG_PATGEN_START_H (5): The start address for the pattern generator buffer (1023 samples long). When writing to the buffer, it is set to 0.
* REG_PATGEN_END_L (6):
* REG_PATGEN_END_H (7): The end address for the pattern generator buffer (1023 samples long). When writing the buffer, it is set to 0x3ff. When in normal mode (to set the end of the output) it is writen as the end address minus 2 (probably due to the actual implementation details).
* PATGEN_CFG (8): Configures the pattern generator.
** (1 << 0): Continuous mode ? (only seems to be allowed for the waveform generator, not for the pattern generator. why?)
** (1 << 1): Enter pattern write mode.
** (1 << 3 | 1 << 2):
*** 11 : Manual start (starts after a pulse in PATGEN_TRIG)
*** 10 : Start on MSO trigger
*** 01 : Start on MSO "Go" (MSO trigger arm)
*** 00 : Disabled
* PATGEN_TRIG (9): writen 0x1 and then 0x0, acts as a manual trigger to activate "stuff".
* PATGEN_WORD (10): In pattern write mode, takes the word for the current "instant".
* PATGEN_IO (11): In pattern write mode, writing 0x1 makes the instant an output one, and writing 0x0 makes it an input one (?)
* PATGEN_LOOPS (12): Stores the number of loops for the pattern generator. Set to 1 for pattern buffer writing mode.
* PATTERN_MASK (13): Stores the output bit mask (1 for enabled bits, 0 for disabled bits)

===== Registers for ((R15 & 0x3) == 0x2) =====

This mode is used to set the i2c or spi triggers.
NOTES:
* the difference between i2c and spi capture seems to be the TRIGGER_CFG_H bits (see R15 = 0)
* how does the hardware handle the start/stop conditions or the ack bit??

The protocol matcher seems to be comprised of a 4 byte shift register. The serial bits are shifted in through the last byte comparator (word 3) and exit through the first byte comparator (word 0). This is why if the trigger is set up with less than 3 words, the first bytes are the ones that end up matching everything (word set to 0x00, mask set to 0xff).

The mask bytes have their bits set to 1 for "ignore", and 0 for "match". The protocol matching block simply doing something this for every bit i:

matches[i] = (read[i] ^ word[i]) | mask[i]

The final result is the and'ing of the resulting 32 bits.

* TRIG_WORD0 (0): Hold the comparison words for the comparator.
* TRIG_WORD1 (1):
* TRIG_WORD2 (2):
* TRIG_WORD2 (3):
* TRIG_MASK0 (4): Holds the mask for the comparator (bits set at 1 always produce a positive match)
* TRIG_MASK1 (5):
* TRIG_MASK2 (6):
* TRIG_MASK3 (7):
* TRIG_SPI_MODE (8): Holds the SPI mode for triggering (valid modes 0, 1, 2, 3). Is set to 0 for I2C (not sure if mandatory)

===== Registers which don't seem to change purpose (so far) =====

*CONTROL1 (14):
**(1 << 0): Reset SFM
**(1 << 3): Force trigger
**(1 << 4): Enable ADC (?)
**(1 << 6): Reset ADC (?)
**(1 << 7): Led on/off
*CONTROL2 (15):
** (1 << 1 | 1 << 0): Control which register bank is selected for writing:
*** 00: The DSO and LA control bank is selected
*** 01: The PG (patern generator) control bank is selected
*** 10: The PT (protocol trigger) control bank is selected
** (1 << 5): Slow mode (?) (set for the low clock rates, probably enables a clock divider)

== Device reply description ==

* After writing 0x0 to the registers (1) or (2) of bank 0, the device replies with either 3072 bytes (1), or 1 byte (2).
* Only 7 bits are used from each byte.
* Bit (1 << 6) indicates which type of message this is:
** 0: This is a "status" message.
** 1: This is a "data" message.

===== STATUS ((1 << 6) == 0) =====
* The reply comprises just one byte. The lower nibble contains the trigger status (t), while the upper nibble contains the hardware status (h)(??):
** [ (h3) (h2) (h1) (h0) (t3) (t2) (t1) (t0) ]

* Values for h(3:0):
** 0x2: The normal value upon startup, before any initialization. This is also the end result of reseting the ADC. (?)
** 0x3: Also accepted upon initialization by the mso19 app. The end result of writing to the DAC or arming the trigger. (?)

* Values for t(3:0):
** 0x6: Triggered (data ready on the samples buffer).
** 0x4: Trigger armed
** 0x1: Trigger not armed

===== DATA ((1 << 6) == 1) =====
* The reply is 24 bit aligned, and contains both the 10 bit analog sample data (a) and the 8 bit digital sample data (d).
* There's a total of 3072 bytes, comprising 1024 samples.
* For each group of 24 bits (a "sample"):
** (byte 0): [ (ignored) 1 (a5) (a4) (a3) (a2) (a1) (a0) ]
** (byte 1): [ (ignored) 1 (d1) (d0) (a9) (a8) (a7) (a6) ]
** (byte 2): [ (ignored) 1 (d7) (d6) (d5) (d4) (d3) (d2) ]

== Device operation ==

The trigger status must be checked periodically, by writing 0 to the "Read Status" register (address 0 of bank 0). The returned value indicates the device status.

=== Startup ===

* The MSO19 application starts by checking the device status. It accepts the values 0x21 or 0x31 as normal, before proceeding.
* It then resets the ADC, and checks for the device status again, and also accepts the values 0x21 and 0x31 as normal.
(...)

=== Capture Start ===

Upon starting a capture, by hitting the "Go" button:
* If the DSO or the DAC need to be configured, the app resets the FSM (finite state machine), and then configures them both.
* If the PG needs to be configured, the app configures it.
* The app then arms the trigger system.
* Finally the app issues a trigger check (writing 0 to the register), and waits for the serial reply.

=== Handle Serial Reply ===

* First the app checks how many bytes there are waiting on the serial port buffer. It only accepts two byte lengths, 3072 bytes and 1 byte.
* The app then checks if the first byte has bit 6 turned off ((byte & (1 << 6)) == 0), and if it is, it assumes it's a trigger status. Otherwise it assumes it's sample data.

Link Instruments MSO-19

2012-01-22T12:12:54Z

Seventhguardian: /* STATUS ((1 << 6) == 0) */

[[File:MSO-19.JPG|thumb|right|Link Instruments MSO-19]]
[[File:MSO-19-naked.jpg|thumb|right|PCB Front]]

The [http://www.linkinstruments.com/mso19.htm Link Instruments MSO-19] is a 2GSa/s oscilloscope, 200MSa/s logic analyzer, 100MSa/s pattern generator and a TDR. It is also extremely portable and is only $249 (including probe, clips, wires and software).

See [[Link Instruments MSO-19/Info]] for more details (such as '''lsusb -vvv''' output) about the device.

== Hardware ==

* [http://www.latticesemi.com/products/cpld/machxo/index.cfm Lattice MachXO LCMXO2280 PLD]
* [http://www.intersil.com/products/deviceinfo.asp?pn=KAD2710C-10 Kenet KAD2710C-10 10bit, 105MSPS ADC]
* [http://www.silabs.com/products/interface/usbtouart/Pages/usb-to-uart-bridge.aspx Silabs CP2103 USB to UART Bridge]

== Original software ==

Link Instruments ships the product with its ''FrontPanelTM Oscilloscope software''. Software is for Windows only. Written in .NET (C#), without any kind of obfuscation, which makes it a real breeze to reverse engineer.

== USB protocol ==

It's just serial-over-USB, supported by the Linux kernel through the '''[http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/usb/serial/cp210x.c;hb=90a4c0f51e8e44111a926be6f4c87af3938a79c3 cp210x]''' driver, though as of Kernel 3.2.1 it needs to be patched to recognize the Link Instruments Vendor/Product ID ('''3195:f190''').

iSerial was exploited by Link Instruments to store hardware type, hardware revision, calibration quirks and the actual serial number.
*for an iSerial of 4294333650260000000 we have:
**42943 336 502 6 0 000000
***vbit = 42943 / 10000
***dacoffset = 336
***offsetrange = 502
***hwmodel = 6
***hwrev = 0
***serial number = 000000

== Serial protocol ==
*Control message
**Fixed header: 0x40, 0x4c, 0x44, 0x53, 0x7e
**Variable size payload, 16bit aligned
***Looks like each 16bits of payload are a register write operation
***register writes are 4bits for addr, 8 bits for value, 2 unused bits and 2 bits im not sure what they are for :)
**** The simplest explanation for the unused bits is that the device bus width is 7 bits (being a CPLD that is very acceptable).
**** The 2 special bits seem to be synchronization bits. 0x7e violates the conversion (high byte), and that may be used to reset the CPLD parser at the end of the packet.
***.?12 AAAA .?34 5678
***Conversion is: ((v & 0x3f) | ((v & 0xc0) << 6) | ((a & 0xf) << 8) | (((v ^ 0x20) & 0x20) << 1) | (((v ^ 0x80) & 0x80) << 7))
***Byte order is big endian
**Fixed footer: 0x7e

== Registers description ==
There is no way to read from registers, only write is possible.

The purpose of registers 0 to 13 seems to depend on the value of the 2 lsbs of register 15.

===== Registers for ((R15 & 0x3) == 0x0) =====

* Read Sample buffer (1): Write 0 to this register to read the samples buffer.
* Read Trigger status (2): Write 0 to this register to read the trigger status.
* TRIGGER_CONFIG_L (3):
** lsbyte of the threshold value.
* TRIGGER_CONFIG_H (4):
** bits [1:0] hold the msbits of the threshold value
** (1 << 2): Trigger on falling edge
** (1 << 4 | 1 << 3): Select the purpose of the "Output" connector:
*** 00 : Trigger pulse output
*** 01 : PWM DAC from the pattern generator buffer.
*** 10 : (?) never seen...
*** 11 : White noise
** (1 << 6 | 1 << 5): These hold the DSO/LA trigger configuration:
*** 00 : DSO level trigger
*** 01 : DSO pulse trigger, width less than TRIGGER_WIDTH
*** 10 : DSO pulse trigger, width equal or greater than TRIGGER_WIDTH
*** 11 : LA combination trigger
* LA_TRIGGER(5): The value of the LA byte that generates a trigger event (in that mode).
* LA_TRIGGER_MASK(6): The mask for the LA_TRIGGER (bits set to 0 matter, those set to 1 are ignored).
* SCOPE_TRIGGER_HOLDOFF1 (7):
* SCOPE_TRIGGER_HOLDOFF2 (8): Store the trigger holdoff (delay between a triggering event and the trigger rearming).
* CLKRATE(9-10):
* TRIGGER_WIDTH (11): Stores the pulse width for the DSO pulse trigger, in sample units. Forced to be greater than 3 by the mso19 app.
* DAC(12-13):

===== Registers for ((R15 & 0x3) == 0x1) =====

This mode seems to be used to configure the pattern generator.

* REG_PATGEN_CLOCK1 (2) :
* REG_PATGEN_CLOCK2 (3) : Stores the sample clock configuration. Not sure how these two bytes work together...
* REG_PATGEN_START_L (4):
* REG_PATGEN_START_H (5): The start address for the pattern generator buffer (1023 samples long). When writing to the buffer, it is set to 0.
* REG_PATGEN_END_L (6):
* REG_PATGEN_END_H (7): The end address for the pattern generator buffer (1023 samples long). When writing the buffer, it is set to 0x3ff. When in normal mode (to set the end of the output) it is writen as the end address minus 2 (probably due to the actual implementation details).
* PATGEN_CFG (8): Configures the pattern generator.
** (1 << 0): Continuous mode ? (only seems to be allowed for the waveform generator, not for the pattern generator. why?)
** (1 << 1): Enter pattern write mode.
** (1 << 3 | 1 << 2):
*** 11 : Manual start (starts after a pulse in PATGEN_TRIG)
*** 10 : Start on MSO trigger
*** 01 : Start on MSO "Go" (MSO trigger arm)
*** 00 : Disabled
* PATGEN_TRIG (9): writen 0x1 and then 0x0, acts as a manual trigger to activate "stuff".
* PATGEN_WORD (10): In pattern write mode, takes the word for the current "instant".
* PATGEN_IO (11): In pattern write mode, writing 0x1 makes the instant an output one, and writing 0x0 makes it an input one (?)
* PATGEN_LOOPS (12): Stores the number of loops for the pattern generator. Set to 1 for pattern buffer writing mode.
* PATTERN_MASK (13): Stores the output bit mask (1 for enabled bits, 0 for disabled bits)

===== Registers for ((R15 & 0x3) == 0x2) =====

This mode is used to set the i2c or spi triggers.
NOTES:
* the difference between i2c and spi capture seems to be the TRIGGER_CFG_H bits (see R15 = 0)
* how does the hardware handle the start/stop conditions or the ack bit??

The protocol matcher seems to be comprised of a 4 byte shift register. The serial bits are shifted in through the last byte comparator (word 3) and exit through the first byte comparator (word 0). This is why if the trigger is set up with less than 3 words, the first bytes are the ones that end up matching everything (word set to 0x00, mask set to 0xff).

The mask bytes have their bits set to 1 for "ignore", and 0 for "match". The protocol matching block simply doing something this for every bit i:

matches[i] = (read[i] ^ word[i]) | mask[i]

The final result is the and'ing of the resulting 32 bits.

* TRIG_WORD0 (0): Hold the comparison words for the comparator.
* TRIG_WORD1 (1):
* TRIG_WORD2 (2):
* TRIG_WORD2 (3):
* TRIG_MASK0 (4): Holds the mask for the comparator (bits set at 1 always produce a positive match)
* TRIG_MASK1 (5):
* TRIG_MASK2 (6):
* TRIG_MASK3 (7):
* TRIG_SPI_MODE (8): Holds the SPI mode for triggering (valid modes 0, 1, 2, 3). Is set to 0 for I2C (not sure if mandatory)

===== Registers which don't seem to change purpose (so far) =====

*CONTROL1 (14):
**(1 << 0): Reset SFM
**(1 << 3): Force trigger
**(1 << 4): Reset ADC (?)
**(1 << 6): Reset ADC (?)
**(1 << 7): Led on/off
*CONTROL2 (15):
** (1 << 1 | 1 << 0): Control which register bank is selected for writing:
*** 00: The DSO and LA control bank is selected
*** 01: The PG (patern generator) control bank is selected
*** 10: The PT (protocol trigger) control bank is selected
** (1 << 5): Slow mode (?) (set for the low clock rates, probably enables a clock divider)

== Device reply description ==

* After writing 0x0 to the registers (1) or (2) of bank 0, the device replies with either 3072 bytes (1), or 1 byte (2).
* Only 7 bits are used from each byte.
* Bit (1 << 6) indicates which type of message this is:
** 0: This is a "status" message.
** 1: This is a "data" message.

===== STATUS ((1 << 6) == 0) =====
* The reply comprises just one byte. The lower nibble contains the trigger status (t), while the upper nibble contains the hardware status (h)(??):
** [ (h3) (h2) (h1) (h0) (t3) (t2) (t1) (t0) ]

* Values for h(3:0):
** 0x2: The normal value upon startup, before any initialization. This is also the end result of reseting the ADC. (?)
** 0x3: Also accepted upon initialization by the mso19 app. The end result of writing to the DAC or arming the trigger. (?)

* Values for t(3:0):
** 0x6: Triggered (data ready on the samples buffer).
** 0x4: Trigger armed
** 0x1: Trigger not armed

===== DATA ((1 << 6) == 1) =====
* The reply is 24 bit aligned, and contains both the 10 bit analog sample data (a) and the 8 bit digital sample data (d).
* There's a total of 3072 bytes, comprising 1024 samples.
* For each group of 24 bits (a "sample"):
** (byte 0): [ (ignored) 1 (a5) (a4) (a3) (a2) (a1) (a0) ]
** (byte 1): [ (ignored) 1 (d1) (d0) (a9) (a8) (a7) (a6) ]
** (byte 2): [ (ignored) 1 (d7) (d6) (d5) (d4) (d3) (d2) ]

== Device operation ==

The trigger status must be checked periodically, by writing 0 to the "Read Status" register (address 0 of bank 0). The returned value indicates the device status.

=== Startup ===

* The MSO19 application starts by checking the device status. It accepts the values 0x21 or 0x31 as normal, before proceeding.
* It then resets the ADC, and checks for the device status again, and also accepts the values 0x21 and 0x31 as normal.
(...)

=== Capture Start ===

Upon starting a capture, by hitting the "Go" button:
* If the DSO or the DAC need to be configured, the app resets the FSM (finite state machine), and then configures them both.
* If the PG needs to be configured, the app configures it.
* The app then arms the trigger system.
* Finally the app issues a trigger check (writing 0 to the register), and waits for the serial reply.

=== Handle Serial Reply ===

* First the app checks how many bytes there are waiting on the serial port buffer. It only accepts two byte lengths, 3072 bytes and 1 byte.
* The app then checks if the first byte has bit 6 turned off ((byte & (1 << 6)) == 0), and if it is, it assumes it's a trigger status. Otherwise it assumes it's sample data.

Link Instruments MSO-19

2012-01-22T11:51:16Z

Seventhguardian: /* STATUS ((1 << 6) == 0) */

[[File:MSO-19.JPG|thumb|right|Link Instruments MSO-19]]
[[File:MSO-19-naked.jpg|thumb|right|PCB Front]]

The [http://www.linkinstruments.com/mso19.htm Link Instruments MSO-19] is a 2GSa/s oscilloscope, 200MSa/s logic analyzer, 100MSa/s pattern generator and a TDR. It is also extremely portable and is only $249 (including probe, clips, wires and software).

See [[Link Instruments MSO-19/Info]] for more details (such as '''lsusb -vvv''' output) about the device.

== Hardware ==

* [http://www.latticesemi.com/products/cpld/machxo/index.cfm Lattice MachXO LCMXO2280 PLD]
* [http://www.intersil.com/products/deviceinfo.asp?pn=KAD2710C-10 Kenet KAD2710C-10 10bit, 105MSPS ADC]
* [http://www.silabs.com/products/interface/usbtouart/Pages/usb-to-uart-bridge.aspx Silabs CP2103 USB to UART Bridge]

== Original software ==

Link Instruments ships the product with its ''FrontPanelTM Oscilloscope software''. Software is for Windows only. Written in .NET (C#), without any kind of obfuscation, which makes it a real breeze to reverse engineer.

== USB protocol ==

It's just serial-over-USB, supported by the Linux kernel through the '''[http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/usb/serial/cp210x.c;hb=90a4c0f51e8e44111a926be6f4c87af3938a79c3 cp210x]''' driver, though as of Kernel 3.2.1 it needs to be patched to recognize the Link Instruments Vendor/Product ID ('''3195:f190''').

iSerial was exploited by Link Instruments to store hardware type, hardware revision, calibration quirks and the actual serial number.
*for an iSerial of 4294333650260000000 we have:
**42943 336 502 6 0 000000
***vbit = 42943 / 10000
***dacoffset = 336
***offsetrange = 502
***hwmodel = 6
***hwrev = 0
***serial number = 000000

== Serial protocol ==
*Control message
**Fixed header: 0x40, 0x4c, 0x44, 0x53, 0x7e
**Variable size payload, 16bit aligned
***Looks like each 16bits of payload are a register write operation
***register writes are 4bits for addr, 8 bits for value, 2 unused bits and 2 bits im not sure what they are for :)
**** The simplest explanation for the unused bits is that the device bus width is 7 bits (being a CPLD that is very acceptable).
**** The 2 special bits seem to be synchronization bits. 0x7e violates the conversion (high byte), and that may be used to reset the CPLD parser at the end of the packet.
***.?12 AAAA .?34 5678
***Conversion is: ((v & 0x3f) | ((v & 0xc0) << 6) | ((a & 0xf) << 8) | (((v ^ 0x20) & 0x20) << 1) | (((v ^ 0x80) & 0x80) << 7))
***Byte order is big endian
**Fixed footer: 0x7e

== Registers description ==
There is no way to read from registers, only write is possible.

The purpose of registers 0 to 13 seems to depend on the value of the 2 lsbs of register 15.

===== Registers for ((R15 & 0x3) == 0x0) =====

* Read Sample buffer (1): Write 0 to this register to read the samples buffer.
* Read Trigger status (2): Write 0 to this register to read the trigger status.
* TRIGGER_CONFIG_L (3):
** lsbyte of the threshold value.
* TRIGGER_CONFIG_H (4):
** bits [1:0] hold the msbits of the threshold value
** (1 << 2): Trigger on falling edge
** (1 << 4 | 1 << 3): Select the purpose of the "Output" connector:
*** 00 : Trigger pulse output
*** 01 : PWM DAC from the pattern generator buffer.
*** 10 : (?) never seen...
*** 11 : White noise
** (1 << 6 | 1 << 5): These hold the DSO/LA trigger configuration:
*** 00 : DSO level trigger
*** 01 : DSO pulse trigger, width less than TRIGGER_WIDTH
*** 10 : DSO pulse trigger, width equal or greater than TRIGGER_WIDTH
*** 11 : LA combination trigger
* LA_TRIGGER(5): The value of the LA byte that generates a trigger event (in that mode).
* LA_TRIGGER_MASK(6): The mask for the LA_TRIGGER (bits set to 0 matter, those set to 1 are ignored).
* SCOPE_TRIGGER_HOLDOFF1 (7):
* SCOPE_TRIGGER_HOLDOFF2 (8): Store the trigger holdoff (delay between a triggering event and the trigger rearming).
* CLKRATE(9-10):
* TRIGGER_WIDTH (11): Stores the pulse width for the DSO pulse trigger, in sample units. Forced to be greater than 3 by the mso19 app.
* DAC(12-13):

===== Registers for ((R15 & 0x3) == 0x1) =====

This mode seems to be used to configure the pattern generator.

* REG_PATGEN_CLOCK1 (2) :
* REG_PATGEN_CLOCK2 (3) : Stores the sample clock configuration. Not sure how these two bytes work together...
* REG_PATGEN_START_L (4):
* REG_PATGEN_START_H (5): The start address for the pattern generator buffer (1023 samples long). When writing to the buffer, it is set to 0.
* REG_PATGEN_END_L (6):
* REG_PATGEN_END_H (7): The end address for the pattern generator buffer (1023 samples long). When writing the buffer, it is set to 0x3ff. When in normal mode (to set the end of the output) it is writen as the end address minus 2 (probably due to the actual implementation details).
* PATGEN_CFG (8): Configures the pattern generator.
** (1 << 0): Continuous mode ? (only seems to be allowed for the waveform generator, not for the pattern generator. why?)
** (1 << 1): Enter pattern write mode.
** (1 << 3 | 1 << 2):
*** 11 : Manual start (starts after a pulse in PATGEN_TRIG)
*** 10 : Start on MSO trigger
*** 01 : Start on MSO "Go" (MSO trigger arm)
*** 00 : Disabled
* PATGEN_TRIG (9): writen 0x1 and then 0x0, acts as a manual trigger to activate "stuff".
* PATGEN_WORD (10): In pattern write mode, takes the word for the current "instant".
* PATGEN_IO (11): In pattern write mode, writing 0x1 makes the instant an output one, and writing 0x0 makes it an input one (?)
* PATGEN_LOOPS (12): Stores the number of loops for the pattern generator. Set to 1 for pattern buffer writing mode.
* PATTERN_MASK (13): Stores the output bit mask (1 for enabled bits, 0 for disabled bits)

===== Registers for ((R15 & 0x3) == 0x2) =====

This mode is used to set the i2c or spi triggers.
NOTES:
* the difference between i2c and spi capture seems to be the TRIGGER_CFG_H bits (see R15 = 0)
* how does the hardware handle the start/stop conditions or the ack bit??

The protocol matcher seems to be comprised of a 4 byte shift register. The serial bits are shifted in through the last byte comparator (word 3) and exit through the first byte comparator (word 0). This is why if the trigger is set up with less than 3 words, the first bytes are the ones that end up matching everything (word set to 0x00, mask set to 0xff).

The mask bytes have their bits set to 1 for "ignore", and 0 for "match". The protocol matching block simply doing something this for every bit i:

matches[i] = (read[i] ^ word[i]) | mask[i]

The final result is the and'ing of the resulting 32 bits.

* TRIG_WORD0 (0): Hold the comparison words for the comparator.
* TRIG_WORD1 (1):
* TRIG_WORD2 (2):
* TRIG_WORD2 (3):
* TRIG_MASK0 (4): Holds the mask for the comparator (bits set at 1 always produce a positive match)
* TRIG_MASK1 (5):
* TRIG_MASK2 (6):
* TRIG_MASK3 (7):
* TRIG_SPI_MODE (8): Holds the SPI mode for triggering (valid modes 0, 1, 2, 3). Is set to 0 for I2C (not sure if mandatory)

===== Registers which don't seem to change purpose (so far) =====

*CONTROL1 (14):
**(1 << 0): Reset SFM
**(1 << 3): Force trigger
**(1 << 4): Reset ADC (?)
**(1 << 6): Reset ADC (?)
**(1 << 7): Led on/off
*CONTROL2 (15):
** (1 << 1 | 1 << 0): Control which register bank is selected for writing:
*** 00: The DSO and LA control bank is selected
*** 01: The PG (patern generator) control bank is selected
*** 10: The PT (protocol trigger) control bank is selected
** (1 << 5): Slow mode (?) (set for the low clock rates, probably enables a clock divider)

== Device reply description ==

* After writing 0x0 to the registers (1) or (2) of bank 0, the device replies with either 3072 bytes (1), or 1 byte (2).
* Only 7 bits are used from each byte.
* Bit (1 << 6) indicates which type of message this is:
** 0: This is a "status" message.
** 1: This is a "data" message.

===== STATUS ((1 << 6) == 0) =====
* The reply comprises just one byte. The lower nibble contains the trigger status (t), while the upper nibble contains the hardware status (h)(??):
** [ (h3) (h2) (h1) (h0) (t3) (t2) (t1) (t0) ]

* Values for h(3:0):
** 0x2: The normal value upon startup, before any initialization. (?)
** 0x3: Also accepted upon initialization by the mso19 app. The common value after the initialization. (?)

* Values for t(3:0):
** 0x6: Triggered (data ready on the samples buffer).
** 0x4: Trigger armed
** 0x1: Trigger not armed

===== DATA ((1 << 6) == 1) =====
* The reply is 24 bit aligned, and contains both the 10 bit analog sample data (a) and the 8 bit digital sample data (d).
* There's a total of 3072 bytes, comprising 1024 samples.
* For each group of 24 bits (a "sample"):
** (byte 0): [ (ignored) 1 (a5) (a4) (a3) (a2) (a1) (a0) ]
** (byte 1): [ (ignored) 1 (d1) (d0) (a9) (a8) (a7) (a6) ]
** (byte 2): [ (ignored) 1 (d7) (d6) (d5) (d4) (d3) (d2) ]

== Device operation ==

The trigger status must be checked periodically, by writing 0 to the "Read Status" register (address 0 of bank 0). The returned value indicates the device status.

=== Startup ===

* The MSO19 application starts by checking the device status. It accepts the values 0x21 or 0x31 as normal, before proceeding.
* It then resets the ADC, and checks for the device status again, and also accepts the values 0x21 and 0x31 as normal.
(...)

=== Capture Start ===

Upon starting a capture, by hitting the "Go" button:
* If the DSO or the DAC need to be configured, the app resets the FSM (finite state machine), and then configures them both.
* If the PG needs to be configured, the app configures it.
* The app then arms the trigger system.
* Finally the app issues a trigger check (writing 0 to the register), and waits for the serial reply.

=== Handle Serial Reply ===

* First the app checks how many bytes there are waiting on the serial port buffer. It only accepts two byte lengths, 3072 bytes and 1 byte.
* The app then checks if the first byte has bit 6 turned off ((byte & (1 << 6)) == 0), and if it is, it assumes it's a trigger status. Otherwise it assumes it's sample data.

Link Instruments MSO-19

2012-01-22T00:42:13Z

Seventhguardian: /* STATUS ((1 << 6) == 0) */

[[File:MSO-19.JPG|thumb|right|Link Instruments MSO-19]]
[[File:MSO-19-naked.jpg|thumb|right|PCB Front]]

The [http://www.linkinstruments.com/mso19.htm Link Instruments MSO-19] is a 2GSa/s oscilloscope, 200MSa/s logic analyzer, 100MSa/s pattern generator and a TDR. It is also extremely portable and is only $249 (including probe, clips, wires and software).

See [[Link Instruments MSO-19/Info]] for more details (such as '''lsusb -vvv''' output) about the device.

== Hardware ==

* [http://www.latticesemi.com/products/cpld/machxo/index.cfm Lattice MachXO LCMXO2280 PLD]
* [http://www.intersil.com/products/deviceinfo.asp?pn=KAD2710C-10 Kenet KAD2710C-10 10bit, 105MSPS ADC]
* [http://www.silabs.com/products/interface/usbtouart/Pages/usb-to-uart-bridge.aspx Silabs CP2103 USB to UART Bridge]

== Original software ==

Link Instruments ships the product with its ''FrontPanelTM Oscilloscope software''. Software is for Windows only. Written in .NET (C#), without any kind of obfuscation, which makes it a real breeze to reverse engineer.

== USB protocol ==

It's just serial-over-USB, supported by the Linux kernel through the '''[http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/usb/serial/cp210x.c;hb=90a4c0f51e8e44111a926be6f4c87af3938a79c3 cp210x]''' driver, though as of Kernel 3.2.1 it needs to be patched to recognize the Link Instruments Vendor/Product ID ('''3195:f190''').

iSerial was exploited by Link Instruments to store hardware type, hardware revision, calibration quirks and the actual serial number.
*for an iSerial of 4294333650260000000 we have:
**42943 336 502 6 0 000000
***vbit = 42943 / 10000
***dacoffset = 336
***offsetrange = 502
***hwmodel = 6
***hwrev = 0
***serial number = 000000

== Serial protocol ==
*Control message
**Fixed header: 0x40, 0x4c, 0x44, 0x53, 0x7e
**Variable size payload, 16bit aligned
***Looks like each 16bits of payload are a register write operation
***register writes are 4bits for addr, 8 bits for value, 2 unused bits and 2 bits im not sure what they are for :)
**** The simplest explanation for the unused bits is that the device bus width is 7 bits (being a CPLD that is very acceptable).
**** The 2 special bits seem to be synchronization bits. 0x7e violates the conversion (high byte), and that may be used to reset the CPLD parser at the end of the packet.
***.?12 AAAA .?34 5678
***Conversion is: ((v & 0x3f) | ((v & 0xc0) << 6) | ((a & 0xf) << 8) | (((v ^ 0x20) & 0x20) << 1) | (((v ^ 0x80) & 0x80) << 7))
***Byte order is big endian
**Fixed footer: 0x7e

== Registers description ==
There is no way to read from registers, only write is possible.

The purpose of registers 0 to 13 seems to depend on the value of the 2 lsbs of register 15.

===== Registers for ((R15 & 0x3) == 0x0) =====

* Read Sample buffer (1): Write 0 to this register to read the samples buffer.
* Read Trigger status (2): Write 0 to this register to read the trigger status.
* TRIGGER_CONFIG_L (3):
** lsbyte of the threshold value.
* TRIGGER_CONFIG_H (4):
** bits [1:0] hold the msbits of the threshold value
** (1 << 2): Trigger on falling edge
** (1 << 4 | 1 << 3): Select the purpose of the "Output" connector:
*** 00 : Trigger pulse output
*** 01 : PWM DAC from the pattern generator buffer.
*** 10 : (?) never seen...
*** 11 : White noise
** (1 << 6 | 1 << 5): These hold the DSO/LA trigger configuration:
*** 00 : DSO level trigger
*** 01 : DSO pulse trigger, width less than TRIGGER_WIDTH
*** 10 : DSO pulse trigger, width equal or greater than TRIGGER_WIDTH
*** 11 : LA combination trigger
* LA_TRIGGER(5): The value of the LA byte that generates a trigger event (in that mode).
* LA_TRIGGER_MASK(6): The mask for the LA_TRIGGER (bits set to 0 matter, those set to 1 are ignored).
* SCOPE_TRIGGER_HOLDOFF1 (7):
* SCOPE_TRIGGER_HOLDOFF2 (8): Store the trigger holdoff (delay between a triggering event and the trigger rearming).
* CLKRATE(9-10):
* TRIGGER_WIDTH (11): Stores the pulse width for the DSO pulse trigger, in sample units. Forced to be greater than 3 by the mso19 app.
* DAC(12-13):

===== Registers for ((R15 & 0x3) == 0x1) =====

This mode seems to be used to configure the pattern generator.

* REG_PATGEN_CLOCK1 (2) :
* REG_PATGEN_CLOCK2 (3) : Stores the sample clock configuration. Not sure how these two bytes work together...
* REG_PATGEN_START_L (4):
* REG_PATGEN_START_H (5): The start address for the pattern generator buffer (1023 samples long). When writing to the buffer, it is set to 0.
* REG_PATGEN_END_L (6):
* REG_PATGEN_END_H (7): The end address for the pattern generator buffer (1023 samples long). When writing the buffer, it is set to 0x3ff. When in normal mode (to set the end of the output) it is writen as the end address minus 2 (probably due to the actual implementation details).
* PATGEN_CFG (8): Configures the pattern generator.
** (1 << 0): Continuous mode ? (only seems to be allowed for the waveform generator, not for the pattern generator. why?)
** (1 << 1): Enter pattern write mode.
** (1 << 3 | 1 << 2):
*** 11 : Manual start (starts after a pulse in PATGEN_TRIG)
*** 10 : Start on MSO trigger
*** 01 : Start on MSO "Go" (MSO trigger arm)
*** 00 : Disabled
* PATGEN_TRIG (9): writen 0x1 and then 0x0, acts as a manual trigger to activate "stuff".
* PATGEN_WORD (10): In pattern write mode, takes the word for the current "instant".
* PATGEN_IO (11): In pattern write mode, writing 0x1 makes the instant an output one, and writing 0x0 makes it an input one (?)
* PATGEN_LOOPS (12): Stores the number of loops for the pattern generator. Set to 1 for pattern buffer writing mode.
* PATTERN_MASK (13): Stores the output bit mask (1 for enabled bits, 0 for disabled bits)

===== Registers for ((R15 & 0x3) == 0x2) =====

This mode is used to set the i2c or spi triggers.
NOTES:
* the difference between i2c and spi capture seems to be the TRIGGER_CFG_H bits (see R15 = 0)
* how does the hardware handle the start/stop conditions or the ack bit??

The protocol matcher seems to be comprised of a 4 byte shift register. The serial bits are shifted in through the last byte comparator (word 3) and exit through the first byte comparator (word 0). This is why if the trigger is set up with less than 3 words, the first bytes are the ones that end up matching everything (word set to 0x00, mask set to 0xff).

The mask bytes have their bits set to 1 for "ignore", and 0 for "match". The protocol matching block simply doing something this for every bit i:

matches[i] = (read[i] ^ word[i]) | mask[i]

The final result is the and'ing of the resulting 32 bits.

* TRIG_WORD0 (0): Hold the comparison words for the comparator.
* TRIG_WORD1 (1):
* TRIG_WORD2 (2):
* TRIG_WORD2 (3):
* TRIG_MASK0 (4): Holds the mask for the comparator (bits set at 1 always produce a positive match)
* TRIG_MASK1 (5):
* TRIG_MASK2 (6):
* TRIG_MASK3 (7):
* TRIG_SPI_MODE (8): Holds the SPI mode for triggering (valid modes 0, 1, 2, 3). Is set to 0 for I2C (not sure if mandatory)

===== Registers which don't seem to change purpose (so far) =====

*CONTROL1 (14):
**(1 << 0): Reset SFM
**(1 << 3): Force trigger
**(1 << 4): Reset ADC (?)
**(1 << 6): Reset ADC (?)
**(1 << 7): Led on/off
*CONTROL2 (15):
** (1 << 1 | 1 << 0): Control which register bank is selected for writing:
*** 00: The DSO and LA control bank is selected
*** 01: The PG (patern generator) control bank is selected
*** 10: The PT (protocol trigger) control bank is selected
** (1 << 5): Slow mode (?) (set for the low clock rates, probably enables a clock divider)

== Device reply description ==

* After writing 0x0 to the registers (1) or (2) of bank 0, the device replies with either 3072 bytes (1), or 1 byte (2).
* Only 7 bits are used from each byte.
* Bit (1 << 6) indicates which type of message this is:
** 0: This is a "status" message.
** 1: This is a "data" message.

===== STATUS ((1 << 6) == 0) =====
* The reply comprises just one byte. The lower nibble contains the trigger status (t), while the upper nibble contains the hardware status (h)(??):
** [ (h3) (h2) (h1) (h0) (t3) (t2) (t1) (t0) ]

* Values for h(3:0):
** 0x2: The normal value upon startup, before any initialization. (?)
** 0x3: Also accepted upon initialization by the mso19 app. The common value after the initialization. (?)

* Values for t(3:0):
** 0x6: Triggered (data ready on the samples buffer).
** 0x4: Armed but not triggered yet (?)
** 0x1: (?) That should be read on startup.. probably something like "not armed".

===== DATA ((1 << 6) == 1) =====
* The reply is 24 bit aligned, and contains both the 10 bit analog sample data (a) and the 8 bit digital sample data (d).
* There's a total of 3072 bytes, comprising 1024 samples.
* For each group of 24 bits (a "sample"):
** (byte 0): [ (ignored) 1 (a5) (a4) (a3) (a2) (a1) (a0) ]
** (byte 1): [ (ignored) 1 (d1) (d0) (a9) (a8) (a7) (a6) ]
** (byte 2): [ (ignored) 1 (d7) (d6) (d5) (d4) (d3) (d2) ]

== Device operation ==

The trigger status must be checked periodically, by writing 0 to the "Read Status" register (address 0 of bank 0). The returned value indicates the device status.

=== Startup ===

* The MSO19 application starts by checking the device status. It accepts the values 0x21 or 0x31 as normal, before proceeding.
* It then resets the ADC, and checks for the device status again, and also accepts the values 0x21 and 0x31 as normal.
(...)

=== Capture Start ===

Upon starting a capture, by hitting the "Go" button:
* If the DSO or the DAC need to be configured, the app resets the FSM (finite state machine), and then configures them both.
* If the PG needs to be configured, the app configures it.
* The app then arms the trigger system.
* Finally the app issues a trigger check (writing 0 to the register), and waits for the serial reply.

=== Handle Serial Reply ===

* First the app checks how many bytes there are waiting on the serial port buffer. It only accepts two byte lengths, 3072 bytes and 1 byte.
* The app then checks if the first byte has bit 6 turned off ((byte & (1 << 6)) == 0), and if it is, it assumes it's a trigger status. Otherwise it assumes it's sample data.

Link Instruments MSO-19

2012-01-22T00:41:56Z

Seventhguardian: /* DATA ((1 << 6) == 1) */

[[File:MSO-19.JPG|thumb|right|Link Instruments MSO-19]]
[[File:MSO-19-naked.jpg|thumb|right|PCB Front]]

The [http://www.linkinstruments.com/mso19.htm Link Instruments MSO-19] is a 2GSa/s oscilloscope, 200MSa/s logic analyzer, 100MSa/s pattern generator and a TDR. It is also extremely portable and is only $249 (including probe, clips, wires and software).

See [[Link Instruments MSO-19/Info]] for more details (such as '''lsusb -vvv''' output) about the device.

== Hardware ==

* [http://www.latticesemi.com/products/cpld/machxo/index.cfm Lattice MachXO LCMXO2280 PLD]
* [http://www.intersil.com/products/deviceinfo.asp?pn=KAD2710C-10 Kenet KAD2710C-10 10bit, 105MSPS ADC]
* [http://www.silabs.com/products/interface/usbtouart/Pages/usb-to-uart-bridge.aspx Silabs CP2103 USB to UART Bridge]

== Original software ==

Link Instruments ships the product with its ''FrontPanelTM Oscilloscope software''. Software is for Windows only. Written in .NET (C#), without any kind of obfuscation, which makes it a real breeze to reverse engineer.

== USB protocol ==

It's just serial-over-USB, supported by the Linux kernel through the '''[http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/usb/serial/cp210x.c;hb=90a4c0f51e8e44111a926be6f4c87af3938a79c3 cp210x]''' driver, though as of Kernel 3.2.1 it needs to be patched to recognize the Link Instruments Vendor/Product ID ('''3195:f190''').

iSerial was exploited by Link Instruments to store hardware type, hardware revision, calibration quirks and the actual serial number.
*for an iSerial of 4294333650260000000 we have:
**42943 336 502 6 0 000000
***vbit = 42943 / 10000
***dacoffset = 336
***offsetrange = 502
***hwmodel = 6
***hwrev = 0
***serial number = 000000

== Serial protocol ==
*Control message
**Fixed header: 0x40, 0x4c, 0x44, 0x53, 0x7e
**Variable size payload, 16bit aligned
***Looks like each 16bits of payload are a register write operation
***register writes are 4bits for addr, 8 bits for value, 2 unused bits and 2 bits im not sure what they are for :)
**** The simplest explanation for the unused bits is that the device bus width is 7 bits (being a CPLD that is very acceptable).
**** The 2 special bits seem to be synchronization bits. 0x7e violates the conversion (high byte), and that may be used to reset the CPLD parser at the end of the packet.
***.?12 AAAA .?34 5678
***Conversion is: ((v & 0x3f) | ((v & 0xc0) << 6) | ((a & 0xf) << 8) | (((v ^ 0x20) & 0x20) << 1) | (((v ^ 0x80) & 0x80) << 7))
***Byte order is big endian
**Fixed footer: 0x7e

== Registers description ==
There is no way to read from registers, only write is possible.

The purpose of registers 0 to 13 seems to depend on the value of the 2 lsbs of register 15.

===== Registers for ((R15 & 0x3) == 0x0) =====

* Read Sample buffer (1): Write 0 to this register to read the samples buffer.
* Read Trigger status (2): Write 0 to this register to read the trigger status.
* TRIGGER_CONFIG_L (3):
** lsbyte of the threshold value.
* TRIGGER_CONFIG_H (4):
** bits [1:0] hold the msbits of the threshold value
** (1 << 2): Trigger on falling edge
** (1 << 4 | 1 << 3): Select the purpose of the "Output" connector:
*** 00 : Trigger pulse output
*** 01 : PWM DAC from the pattern generator buffer.
*** 10 : (?) never seen...
*** 11 : White noise
** (1 << 6 | 1 << 5): These hold the DSO/LA trigger configuration:
*** 00 : DSO level trigger
*** 01 : DSO pulse trigger, width less than TRIGGER_WIDTH
*** 10 : DSO pulse trigger, width equal or greater than TRIGGER_WIDTH
*** 11 : LA combination trigger
* LA_TRIGGER(5): The value of the LA byte that generates a trigger event (in that mode).
* LA_TRIGGER_MASK(6): The mask for the LA_TRIGGER (bits set to 0 matter, those set to 1 are ignored).
* SCOPE_TRIGGER_HOLDOFF1 (7):
* SCOPE_TRIGGER_HOLDOFF2 (8): Store the trigger holdoff (delay between a triggering event and the trigger rearming).
* CLKRATE(9-10):
* TRIGGER_WIDTH (11): Stores the pulse width for the DSO pulse trigger, in sample units. Forced to be greater than 3 by the mso19 app.
* DAC(12-13):

===== Registers for ((R15 & 0x3) == 0x1) =====

This mode seems to be used to configure the pattern generator.

* REG_PATGEN_CLOCK1 (2) :
* REG_PATGEN_CLOCK2 (3) : Stores the sample clock configuration. Not sure how these two bytes work together...
* REG_PATGEN_START_L (4):
* REG_PATGEN_START_H (5): The start address for the pattern generator buffer (1023 samples long). When writing to the buffer, it is set to 0.
* REG_PATGEN_END_L (6):
* REG_PATGEN_END_H (7): The end address for the pattern generator buffer (1023 samples long). When writing the buffer, it is set to 0x3ff. When in normal mode (to set the end of the output) it is writen as the end address minus 2 (probably due to the actual implementation details).
* PATGEN_CFG (8): Configures the pattern generator.
** (1 << 0): Continuous mode ? (only seems to be allowed for the waveform generator, not for the pattern generator. why?)
** (1 << 1): Enter pattern write mode.
** (1 << 3 | 1 << 2):
*** 11 : Manual start (starts after a pulse in PATGEN_TRIG)
*** 10 : Start on MSO trigger
*** 01 : Start on MSO "Go" (MSO trigger arm)
*** 00 : Disabled
* PATGEN_TRIG (9): writen 0x1 and then 0x0, acts as a manual trigger to activate "stuff".
* PATGEN_WORD (10): In pattern write mode, takes the word for the current "instant".
* PATGEN_IO (11): In pattern write mode, writing 0x1 makes the instant an output one, and writing 0x0 makes it an input one (?)
* PATGEN_LOOPS (12): Stores the number of loops for the pattern generator. Set to 1 for pattern buffer writing mode.
* PATTERN_MASK (13): Stores the output bit mask (1 for enabled bits, 0 for disabled bits)

===== Registers for ((R15 & 0x3) == 0x2) =====

This mode is used to set the i2c or spi triggers.
NOTES:
* the difference between i2c and spi capture seems to be the TRIGGER_CFG_H bits (see R15 = 0)
* how does the hardware handle the start/stop conditions or the ack bit??

The protocol matcher seems to be comprised of a 4 byte shift register. The serial bits are shifted in through the last byte comparator (word 3) and exit through the first byte comparator (word 0). This is why if the trigger is set up with less than 3 words, the first bytes are the ones that end up matching everything (word set to 0x00, mask set to 0xff).

The mask bytes have their bits set to 1 for "ignore", and 0 for "match". The protocol matching block simply doing something this for every bit i:

matches[i] = (read[i] ^ word[i]) | mask[i]

The final result is the and'ing of the resulting 32 bits.

* TRIG_WORD0 (0): Hold the comparison words for the comparator.
* TRIG_WORD1 (1):
* TRIG_WORD2 (2):
* TRIG_WORD2 (3):
* TRIG_MASK0 (4): Holds the mask for the comparator (bits set at 1 always produce a positive match)
* TRIG_MASK1 (5):
* TRIG_MASK2 (6):
* TRIG_MASK3 (7):
* TRIG_SPI_MODE (8): Holds the SPI mode for triggering (valid modes 0, 1, 2, 3). Is set to 0 for I2C (not sure if mandatory)

===== Registers which don't seem to change purpose (so far) =====

*CONTROL1 (14):
**(1 << 0): Reset SFM
**(1 << 3): Force trigger
**(1 << 4): Reset ADC (?)
**(1 << 6): Reset ADC (?)
**(1 << 7): Led on/off
*CONTROL2 (15):
** (1 << 1 | 1 << 0): Control which register bank is selected for writing:
*** 00: The DSO and LA control bank is selected
*** 01: The PG (patern generator) control bank is selected
*** 10: The PT (protocol trigger) control bank is selected
** (1 << 5): Slow mode (?) (set for the low clock rates, probably enables a clock divider)

== Device reply description ==

* After writing 0x0 to the registers (1) or (2) of bank 0, the device replies with either 3072 bytes (1), or 1 byte (2).
* Only 7 bits are used from each byte.
* Bit (1 << 6) indicates which type of message this is:
** 0: This is a "status" message.
** 1: This is a "data" message.

===== STATUS ((1 << 6) == 0) =====
* The reply comprises just one byte. The lower nibble contains the trigger status (t), while the upper nibble contains the hardware status (h)(??):
** (1): [ (h3) (h2) (h1) (h0) (t3) (t2) (t1) (t0) ]

* Values for h(3:0):
** 0x2: The normal value upon startup, before any initialization. (?)
** 0x3: Also accepted upon initialization by the mso19 app. The common value after the initialization. (?)

* Values for t(3:0):
** 0x6: Triggered (data ready on the samples buffer).
** 0x4: Armed but not triggered yet (?)
** 0x1: (?) That should be read on startup.. probably something like "not armed".

===== DATA ((1 << 6) == 1) =====
* The reply is 24 bit aligned, and contains both the 10 bit analog sample data (a) and the 8 bit digital sample data (d).
* There's a total of 3072 bytes, comprising 1024 samples.
* For each group of 24 bits (a "sample"):
** (byte 0): [ (ignored) 1 (a5) (a4) (a3) (a2) (a1) (a0) ]
** (byte 1): [ (ignored) 1 (d1) (d0) (a9) (a8) (a7) (a6) ]
** (byte 2): [ (ignored) 1 (d7) (d6) (d5) (d4) (d3) (d2) ]

== Device operation ==

The trigger status must be checked periodically, by writing 0 to the "Read Status" register (address 0 of bank 0). The returned value indicates the device status.

=== Startup ===

* The MSO19 application starts by checking the device status. It accepts the values 0x21 or 0x31 as normal, before proceeding.
* It then resets the ADC, and checks for the device status again, and also accepts the values 0x21 and 0x31 as normal.
(...)

=== Capture Start ===

Upon starting a capture, by hitting the "Go" button:
* If the DSO or the DAC need to be configured, the app resets the FSM (finite state machine), and then configures them both.
* If the PG needs to be configured, the app configures it.
* The app then arms the trigger system.
* Finally the app issues a trigger check (writing 0 to the register), and waits for the serial reply.

=== Handle Serial Reply ===

* First the app checks how many bytes there are waiting on the serial port buffer. It only accepts two byte lengths, 3072 bytes and 1 byte.
* The app then checks if the first byte has bit 6 turned off ((byte & (1 << 6)) == 0), and if it is, it assumes it's a trigger status. Otherwise it assumes it's sample data.

Link Instruments MSO-19

2012-01-22T00:40:45Z

Seventhguardian: /* STATUS ((1 << 6) == 0) */

[[File:MSO-19.JPG|thumb|right|Link Instruments MSO-19]]
[[File:MSO-19-naked.jpg|thumb|right|PCB Front]]

The [http://www.linkinstruments.com/mso19.htm Link Instruments MSO-19] is a 2GSa/s oscilloscope, 200MSa/s logic analyzer, 100MSa/s pattern generator and a TDR. It is also extremely portable and is only $249 (including probe, clips, wires and software).

See [[Link Instruments MSO-19/Info]] for more details (such as '''lsusb -vvv''' output) about the device.

== Hardware ==

* [http://www.latticesemi.com/products/cpld/machxo/index.cfm Lattice MachXO LCMXO2280 PLD]
* [http://www.intersil.com/products/deviceinfo.asp?pn=KAD2710C-10 Kenet KAD2710C-10 10bit, 105MSPS ADC]
* [http://www.silabs.com/products/interface/usbtouart/Pages/usb-to-uart-bridge.aspx Silabs CP2103 USB to UART Bridge]

== Original software ==

Link Instruments ships the product with its ''FrontPanelTM Oscilloscope software''. Software is for Windows only. Written in .NET (C#), without any kind of obfuscation, which makes it a real breeze to reverse engineer.

== USB protocol ==

It's just serial-over-USB, supported by the Linux kernel through the '''[http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/usb/serial/cp210x.c;hb=90a4c0f51e8e44111a926be6f4c87af3938a79c3 cp210x]''' driver, though as of Kernel 3.2.1 it needs to be patched to recognize the Link Instruments Vendor/Product ID ('''3195:f190''').

iSerial was exploited by Link Instruments to store hardware type, hardware revision, calibration quirks and the actual serial number.
*for an iSerial of 4294333650260000000 we have:
**42943 336 502 6 0 000000
***vbit = 42943 / 10000
***dacoffset = 336
***offsetrange = 502
***hwmodel = 6
***hwrev = 0
***serial number = 000000

== Serial protocol ==
*Control message
**Fixed header: 0x40, 0x4c, 0x44, 0x53, 0x7e
**Variable size payload, 16bit aligned
***Looks like each 16bits of payload are a register write operation
***register writes are 4bits for addr, 8 bits for value, 2 unused bits and 2 bits im not sure what they are for :)
**** The simplest explanation for the unused bits is that the device bus width is 7 bits (being a CPLD that is very acceptable).
**** The 2 special bits seem to be synchronization bits. 0x7e violates the conversion (high byte), and that may be used to reset the CPLD parser at the end of the packet.
***.?12 AAAA .?34 5678
***Conversion is: ((v & 0x3f) | ((v & 0xc0) << 6) | ((a & 0xf) << 8) | (((v ^ 0x20) & 0x20) << 1) | (((v ^ 0x80) & 0x80) << 7))
***Byte order is big endian
**Fixed footer: 0x7e

== Registers description ==
There is no way to read from registers, only write is possible.

The purpose of registers 0 to 13 seems to depend on the value of the 2 lsbs of register 15.

===== Registers for ((R15 & 0x3) == 0x0) =====

* Read Sample buffer (1): Write 0 to this register to read the samples buffer.
* Read Trigger status (2): Write 0 to this register to read the trigger status.
* TRIGGER_CONFIG_L (3):
** lsbyte of the threshold value.
* TRIGGER_CONFIG_H (4):
** bits [1:0] hold the msbits of the threshold value
** (1 << 2): Trigger on falling edge
** (1 << 4 | 1 << 3): Select the purpose of the "Output" connector:
*** 00 : Trigger pulse output
*** 01 : PWM DAC from the pattern generator buffer.
*** 10 : (?) never seen...
*** 11 : White noise
** (1 << 6 | 1 << 5): These hold the DSO/LA trigger configuration:
*** 00 : DSO level trigger
*** 01 : DSO pulse trigger, width less than TRIGGER_WIDTH
*** 10 : DSO pulse trigger, width equal or greater than TRIGGER_WIDTH
*** 11 : LA combination trigger
* LA_TRIGGER(5): The value of the LA byte that generates a trigger event (in that mode).
* LA_TRIGGER_MASK(6): The mask for the LA_TRIGGER (bits set to 0 matter, those set to 1 are ignored).
* SCOPE_TRIGGER_HOLDOFF1 (7):
* SCOPE_TRIGGER_HOLDOFF2 (8): Store the trigger holdoff (delay between a triggering event and the trigger rearming).
* CLKRATE(9-10):
* TRIGGER_WIDTH (11): Stores the pulse width for the DSO pulse trigger, in sample units. Forced to be greater than 3 by the mso19 app.
* DAC(12-13):

===== Registers for ((R15 & 0x3) == 0x1) =====

This mode seems to be used to configure the pattern generator.

* REG_PATGEN_CLOCK1 (2) :
* REG_PATGEN_CLOCK2 (3) : Stores the sample clock configuration. Not sure how these two bytes work together...
* REG_PATGEN_START_L (4):
* REG_PATGEN_START_H (5): The start address for the pattern generator buffer (1023 samples long). When writing to the buffer, it is set to 0.
* REG_PATGEN_END_L (6):
* REG_PATGEN_END_H (7): The end address for the pattern generator buffer (1023 samples long). When writing the buffer, it is set to 0x3ff. When in normal mode (to set the end of the output) it is writen as the end address minus 2 (probably due to the actual implementation details).
* PATGEN_CFG (8): Configures the pattern generator.
** (1 << 0): Continuous mode ? (only seems to be allowed for the waveform generator, not for the pattern generator. why?)
** (1 << 1): Enter pattern write mode.
** (1 << 3 | 1 << 2):
*** 11 : Manual start (starts after a pulse in PATGEN_TRIG)
*** 10 : Start on MSO trigger
*** 01 : Start on MSO "Go" (MSO trigger arm)
*** 00 : Disabled
* PATGEN_TRIG (9): writen 0x1 and then 0x0, acts as a manual trigger to activate "stuff".
* PATGEN_WORD (10): In pattern write mode, takes the word for the current "instant".
* PATGEN_IO (11): In pattern write mode, writing 0x1 makes the instant an output one, and writing 0x0 makes it an input one (?)
* PATGEN_LOOPS (12): Stores the number of loops for the pattern generator. Set to 1 for pattern buffer writing mode.
* PATTERN_MASK (13): Stores the output bit mask (1 for enabled bits, 0 for disabled bits)

===== Registers for ((R15 & 0x3) == 0x2) =====

This mode is used to set the i2c or spi triggers.
NOTES:
* the difference between i2c and spi capture seems to be the TRIGGER_CFG_H bits (see R15 = 0)
* how does the hardware handle the start/stop conditions or the ack bit??

The protocol matcher seems to be comprised of a 4 byte shift register. The serial bits are shifted in through the last byte comparator (word 3) and exit through the first byte comparator (word 0). This is why if the trigger is set up with less than 3 words, the first bytes are the ones that end up matching everything (word set to 0x00, mask set to 0xff).

The mask bytes have their bits set to 1 for "ignore", and 0 for "match". The protocol matching block simply doing something this for every bit i:

matches[i] = (read[i] ^ word[i]) | mask[i]

The final result is the and'ing of the resulting 32 bits.

* TRIG_WORD0 (0): Hold the comparison words for the comparator.
* TRIG_WORD1 (1):
* TRIG_WORD2 (2):
* TRIG_WORD2 (3):
* TRIG_MASK0 (4): Holds the mask for the comparator (bits set at 1 always produce a positive match)
* TRIG_MASK1 (5):
* TRIG_MASK2 (6):
* TRIG_MASK3 (7):
* TRIG_SPI_MODE (8): Holds the SPI mode for triggering (valid modes 0, 1, 2, 3). Is set to 0 for I2C (not sure if mandatory)

===== Registers which don't seem to change purpose (so far) =====

*CONTROL1 (14):
**(1 << 0): Reset SFM
**(1 << 3): Force trigger
**(1 << 4): Reset ADC (?)
**(1 << 6): Reset ADC (?)
**(1 << 7): Led on/off
*CONTROL2 (15):
** (1 << 1 | 1 << 0): Control which register bank is selected for writing:
*** 00: The DSO and LA control bank is selected
*** 01: The PG (patern generator) control bank is selected
*** 10: The PT (protocol trigger) control bank is selected
** (1 << 5): Slow mode (?) (set for the low clock rates, probably enables a clock divider)

== Device reply description ==

* After writing 0x0 to the registers (1) or (2) of bank 0, the device replies with either 3072 bytes (1), or 1 byte (2).
* Only 7 bits are used from each byte.
* Bit (1 << 6) indicates which type of message this is:
** 0: This is a "status" message.
** 1: This is a "data" message.

===== STATUS ((1 << 6) == 0) =====
* The reply comprises just one byte. The lower nibble contains the trigger status (t), while the upper nibble contains the hardware status (h)(??):
** (1): [ (h3) (h2) (h1) (h0) (t3) (t2) (t1) (t0) ]

* Values for h(3:0):
** 0x2: The normal value upon startup, before any initialization. (?)
** 0x3: Also accepted upon initialization by the mso19 app. The common value after the initialization. (?)

* Values for t(3:0):
** 0x6: Triggered (data ready on the samples buffer).
** 0x4: Armed but not triggered yet (?)
** 0x1: (?) That should be read on startup.. probably something like "not armed".

===== DATA ((1 << 6) == 1) =====
* The reply is 24 bit aligned, and contains both the 10 bit analog sample data (a) and the 8 bit digital sample data (d).
* There's a total of 3072 bytes, comprising 1024 samples.
* For each group of 24 bits (a "sample"):
** (byte 0): [ <ignored> 1 <a5> <a4> <a3> <a2> <a1> <a0> ]
** (byte 1): [ <ignored> 1 <d1> <d0> <a9> <a8> <a7> <a6> ]
** (byte 2): [ <ignored> 1 <d7> <d6> <d5> <d4> <d3> <d2> ]

== Device operation ==

The trigger status must be checked periodically, by writing 0 to the "Read Status" register (address 0 of bank 0). The returned value indicates the device status.

=== Startup ===

* The MSO19 application starts by checking the device status. It accepts the values 0x21 or 0x31 as normal, before proceeding.
* It then resets the ADC, and checks for the device status again, and also accepts the values 0x21 and 0x31 as normal.
(...)

=== Capture Start ===

Upon starting a capture, by hitting the "Go" button:
* If the DSO or the DAC need to be configured, the app resets the FSM (finite state machine), and then configures them both.
* If the PG needs to be configured, the app configures it.
* The app then arms the trigger system.
* Finally the app issues a trigger check (writing 0 to the register), and waits for the serial reply.

=== Handle Serial Reply ===

* First the app checks how many bytes there are waiting on the serial port buffer. It only accepts two byte lengths, 3072 bytes and 1 byte.
* The app then checks if the first byte has bit 6 turned off ((byte & (1 << 6)) == 0), and if it is, it assumes it's a trigger status. Otherwise it assumes it's sample data.

Link Instruments MSO-19

2012-01-22T00:40:06Z

Seventhguardian: /* STATUS ((1 << 6) == 0) */

[[File:MSO-19.JPG|thumb|right|Link Instruments MSO-19]]
[[File:MSO-19-naked.jpg|thumb|right|PCB Front]]

The [http://www.linkinstruments.com/mso19.htm Link Instruments MSO-19] is a 2GSa/s oscilloscope, 200MSa/s logic analyzer, 100MSa/s pattern generator and a TDR. It is also extremely portable and is only $249 (including probe, clips, wires and software).

See [[Link Instruments MSO-19/Info]] for more details (such as '''lsusb -vvv''' output) about the device.

== Hardware ==

* [http://www.latticesemi.com/products/cpld/machxo/index.cfm Lattice MachXO LCMXO2280 PLD]
* [http://www.intersil.com/products/deviceinfo.asp?pn=KAD2710C-10 Kenet KAD2710C-10 10bit, 105MSPS ADC]
* [http://www.silabs.com/products/interface/usbtouart/Pages/usb-to-uart-bridge.aspx Silabs CP2103 USB to UART Bridge]

== Original software ==

Link Instruments ships the product with its ''FrontPanelTM Oscilloscope software''. Software is for Windows only. Written in .NET (C#), without any kind of obfuscation, which makes it a real breeze to reverse engineer.

== USB protocol ==

It's just serial-over-USB, supported by the Linux kernel through the '''[http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/usb/serial/cp210x.c;hb=90a4c0f51e8e44111a926be6f4c87af3938a79c3 cp210x]''' driver, though as of Kernel 3.2.1 it needs to be patched to recognize the Link Instruments Vendor/Product ID ('''3195:f190''').

iSerial was exploited by Link Instruments to store hardware type, hardware revision, calibration quirks and the actual serial number.
*for an iSerial of 4294333650260000000 we have:
**42943 336 502 6 0 000000
***vbit = 42943 / 10000
***dacoffset = 336
***offsetrange = 502
***hwmodel = 6
***hwrev = 0
***serial number = 000000

== Serial protocol ==
*Control message
**Fixed header: 0x40, 0x4c, 0x44, 0x53, 0x7e
**Variable size payload, 16bit aligned
***Looks like each 16bits of payload are a register write operation
***register writes are 4bits for addr, 8 bits for value, 2 unused bits and 2 bits im not sure what they are for :)
**** The simplest explanation for the unused bits is that the device bus width is 7 bits (being a CPLD that is very acceptable).
**** The 2 special bits seem to be synchronization bits. 0x7e violates the conversion (high byte), and that may be used to reset the CPLD parser at the end of the packet.
***.?12 AAAA .?34 5678
***Conversion is: ((v & 0x3f) | ((v & 0xc0) << 6) | ((a & 0xf) << 8) | (((v ^ 0x20) & 0x20) << 1) | (((v ^ 0x80) & 0x80) << 7))
***Byte order is big endian
**Fixed footer: 0x7e

== Registers description ==
There is no way to read from registers, only write is possible.

The purpose of registers 0 to 13 seems to depend on the value of the 2 lsbs of register 15.

===== Registers for ((R15 & 0x3) == 0x0) =====

* Read Sample buffer (1): Write 0 to this register to read the samples buffer.
* Read Trigger status (2): Write 0 to this register to read the trigger status.
* TRIGGER_CONFIG_L (3):
** lsbyte of the threshold value.
* TRIGGER_CONFIG_H (4):
** bits [1:0] hold the msbits of the threshold value
** (1 << 2): Trigger on falling edge
** (1 << 4 | 1 << 3): Select the purpose of the "Output" connector:
*** 00 : Trigger pulse output
*** 01 : PWM DAC from the pattern generator buffer.
*** 10 : (?) never seen...
*** 11 : White noise
** (1 << 6 | 1 << 5): These hold the DSO/LA trigger configuration:
*** 00 : DSO level trigger
*** 01 : DSO pulse trigger, width less than TRIGGER_WIDTH
*** 10 : DSO pulse trigger, width equal or greater than TRIGGER_WIDTH
*** 11 : LA combination trigger
* LA_TRIGGER(5): The value of the LA byte that generates a trigger event (in that mode).
* LA_TRIGGER_MASK(6): The mask for the LA_TRIGGER (bits set to 0 matter, those set to 1 are ignored).
* SCOPE_TRIGGER_HOLDOFF1 (7):
* SCOPE_TRIGGER_HOLDOFF2 (8): Store the trigger holdoff (delay between a triggering event and the trigger rearming).
* CLKRATE(9-10):
* TRIGGER_WIDTH (11): Stores the pulse width for the DSO pulse trigger, in sample units. Forced to be greater than 3 by the mso19 app.
* DAC(12-13):

===== Registers for ((R15 & 0x3) == 0x1) =====

This mode seems to be used to configure the pattern generator.

* REG_PATGEN_CLOCK1 (2) :
* REG_PATGEN_CLOCK2 (3) : Stores the sample clock configuration. Not sure how these two bytes work together...
* REG_PATGEN_START_L (4):
* REG_PATGEN_START_H (5): The start address for the pattern generator buffer (1023 samples long). When writing to the buffer, it is set to 0.
* REG_PATGEN_END_L (6):
* REG_PATGEN_END_H (7): The end address for the pattern generator buffer (1023 samples long). When writing the buffer, it is set to 0x3ff. When in normal mode (to set the end of the output) it is writen as the end address minus 2 (probably due to the actual implementation details).
* PATGEN_CFG (8): Configures the pattern generator.
** (1 << 0): Continuous mode ? (only seems to be allowed for the waveform generator, not for the pattern generator. why?)
** (1 << 1): Enter pattern write mode.
** (1 << 3 | 1 << 2):
*** 11 : Manual start (starts after a pulse in PATGEN_TRIG)
*** 10 : Start on MSO trigger
*** 01 : Start on MSO "Go" (MSO trigger arm)
*** 00 : Disabled
* PATGEN_TRIG (9): writen 0x1 and then 0x0, acts as a manual trigger to activate "stuff".
* PATGEN_WORD (10): In pattern write mode, takes the word for the current "instant".
* PATGEN_IO (11): In pattern write mode, writing 0x1 makes the instant an output one, and writing 0x0 makes it an input one (?)
* PATGEN_LOOPS (12): Stores the number of loops for the pattern generator. Set to 1 for pattern buffer writing mode.
* PATTERN_MASK (13): Stores the output bit mask (1 for enabled bits, 0 for disabled bits)

===== Registers for ((R15 & 0x3) == 0x2) =====

This mode is used to set the i2c or spi triggers.
NOTES:
* the difference between i2c and spi capture seems to be the TRIGGER_CFG_H bits (see R15 = 0)
* how does the hardware handle the start/stop conditions or the ack bit??

The protocol matcher seems to be comprised of a 4 byte shift register. The serial bits are shifted in through the last byte comparator (word 3) and exit through the first byte comparator (word 0). This is why if the trigger is set up with less than 3 words, the first bytes are the ones that end up matching everything (word set to 0x00, mask set to 0xff).

The mask bytes have their bits set to 1 for "ignore", and 0 for "match". The protocol matching block simply doing something this for every bit i:

matches[i] = (read[i] ^ word[i]) | mask[i]

The final result is the and'ing of the resulting 32 bits.

* TRIG_WORD0 (0): Hold the comparison words for the comparator.
* TRIG_WORD1 (1):
* TRIG_WORD2 (2):
* TRIG_WORD2 (3):
* TRIG_MASK0 (4): Holds the mask for the comparator (bits set at 1 always produce a positive match)
* TRIG_MASK1 (5):
* TRIG_MASK2 (6):
* TRIG_MASK3 (7):
* TRIG_SPI_MODE (8): Holds the SPI mode for triggering (valid modes 0, 1, 2, 3). Is set to 0 for I2C (not sure if mandatory)

===== Registers which don't seem to change purpose (so far) =====

*CONTROL1 (14):
**(1 << 0): Reset SFM
**(1 << 3): Force trigger
**(1 << 4): Reset ADC (?)
**(1 << 6): Reset ADC (?)
**(1 << 7): Led on/off
*CONTROL2 (15):
** (1 << 1 | 1 << 0): Control which register bank is selected for writing:
*** 00: The DSO and LA control bank is selected
*** 01: The PG (patern generator) control bank is selected
*** 10: The PT (protocol trigger) control bank is selected
** (1 << 5): Slow mode (?) (set for the low clock rates, probably enables a clock divider)

== Device reply description ==

* After writing 0x0 to the registers (1) or (2) of bank 0, the device replies with either 3072 bytes (1), or 1 byte (2).
* Only 7 bits are used from each byte.
* Bit (1 << 6) indicates which type of message this is:
** 0: This is a "status" message.
** 1: This is a "data" message.

===== STATUS ((1 << 6) == 0) =====
* The reply comprises just one byte. The lower nibble contains the trigger status (t), while the upper nibble contains the hardware status (h)(??):
** (1): [ <h3> <h2> <h1> <h0> <t3> <t2> <t1> <t0> ]

* Values for h(3:0):
** 0x2: The normal value upon startup, before any initialization. (?)
** 0x3: Also accepted upon initialization by the mso19 app. The common value after the initialization. (?)

* Values for t(3:0):
** 0x6: Triggered (data ready on the samples buffer).
** 0x4: Armed but not triggered yet (?)
** 0x1: (?) That should be read on startup.. probably something like "not armed".

===== DATA ((1 << 6) == 1) =====
* The reply is 24 bit aligned, and contains both the 10 bit analog sample data (a) and the 8 bit digital sample data (d).
* There's a total of 3072 bytes, comprising 1024 samples.
* For each group of 24 bits (a "sample"):
** (byte 0): [ <ignored> 1 <a5> <a4> <a3> <a2> <a1> <a0> ]
** (byte 1): [ <ignored> 1 <d1> <d0> <a9> <a8> <a7> <a6> ]
** (byte 2): [ <ignored> 1 <d7> <d6> <d5> <d4> <d3> <d2> ]

== Device operation ==

The trigger status must be checked periodically, by writing 0 to the "Read Status" register (address 0 of bank 0). The returned value indicates the device status.

=== Startup ===

* The MSO19 application starts by checking the device status. It accepts the values 0x21 or 0x31 as normal, before proceeding.
* It then resets the ADC, and checks for the device status again, and also accepts the values 0x21 and 0x31 as normal.
(...)

=== Capture Start ===

Upon starting a capture, by hitting the "Go" button:
* If the DSO or the DAC need to be configured, the app resets the FSM (finite state machine), and then configures them both.
* If the PG needs to be configured, the app configures it.
* The app then arms the trigger system.
* Finally the app issues a trigger check (writing 0 to the register), and waits for the serial reply.

=== Handle Serial Reply ===

* First the app checks how many bytes there are waiting on the serial port buffer. It only accepts two byte lengths, 3072 bytes and 1 byte.
* The app then checks if the first byte has bit 6 turned off ((byte & (1 << 6)) == 0), and if it is, it assumes it's a trigger status. Otherwise it assumes it's sample data.

Link Instruments MSO-19

2012-01-22T00:29:23Z

Seventhguardian: /* STATUS ((1 << 6) == 0) */

[[File:MSO-19.JPG|thumb|right|Link Instruments MSO-19]]
[[File:MSO-19-naked.jpg|thumb|right|PCB Front]]

The [http://www.linkinstruments.com/mso19.htm Link Instruments MSO-19] is a 2GSa/s oscilloscope, 200MSa/s logic analyzer, 100MSa/s pattern generator and a TDR. It is also extremely portable and is only $249 (including probe, clips, wires and software).

See [[Link Instruments MSO-19/Info]] for more details (such as '''lsusb -vvv''' output) about the device.

== Hardware ==

* [http://www.latticesemi.com/products/cpld/machxo/index.cfm Lattice MachXO LCMXO2280 PLD]
* [http://www.intersil.com/products/deviceinfo.asp?pn=KAD2710C-10 Kenet KAD2710C-10 10bit, 105MSPS ADC]
* [http://www.silabs.com/products/interface/usbtouart/Pages/usb-to-uart-bridge.aspx Silabs CP2103 USB to UART Bridge]

== Original software ==

Link Instruments ships the product with its ''FrontPanelTM Oscilloscope software''. Software is for Windows only. Written in .NET (C#), without any kind of obfuscation, which makes it a real breeze to reverse engineer.

== USB protocol ==

It's just serial-over-USB, supported by the Linux kernel through the '''[http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/usb/serial/cp210x.c;hb=90a4c0f51e8e44111a926be6f4c87af3938a79c3 cp210x]''' driver, though as of Kernel 3.2.1 it needs to be patched to recognize the Link Instruments Vendor/Product ID ('''3195:f190''').

iSerial was exploited by Link Instruments to store hardware type, hardware revision, calibration quirks and the actual serial number.
*for an iSerial of 4294333650260000000 we have:
**42943 336 502 6 0 000000
***vbit = 42943 / 10000
***dacoffset = 336
***offsetrange = 502
***hwmodel = 6
***hwrev = 0
***serial number = 000000

== Serial protocol ==
*Control message
**Fixed header: 0x40, 0x4c, 0x44, 0x53, 0x7e
**Variable size payload, 16bit aligned
***Looks like each 16bits of payload are a register write operation
***register writes are 4bits for addr, 8 bits for value, 2 unused bits and 2 bits im not sure what they are for :)
**** The simplest explanation for the unused bits is that the device bus width is 7 bits (being a CPLD that is very acceptable).
**** The 2 special bits seem to be synchronization bits. 0x7e violates the conversion (high byte), and that may be used to reset the CPLD parser at the end of the packet.
***.?12 AAAA .?34 5678
***Conversion is: ((v & 0x3f) | ((v & 0xc0) << 6) | ((a & 0xf) << 8) | (((v ^ 0x20) & 0x20) << 1) | (((v ^ 0x80) & 0x80) << 7))
***Byte order is big endian
**Fixed footer: 0x7e

== Registers description ==
There is no way to read from registers, only write is possible.

The purpose of registers 0 to 13 seems to depend on the value of the 2 lsbs of register 15.

===== Registers for ((R15 & 0x3) == 0x0) =====

* Read Sample buffer (1): Write 0 to this register to read the samples buffer.
* Read Trigger status (2): Write 0 to this register to read the trigger status.
* TRIGGER_CONFIG_L (3):
** lsbyte of the threshold value.
* TRIGGER_CONFIG_H (4):
** bits [1:0] hold the msbits of the threshold value
** (1 << 2): Trigger on falling edge
** (1 << 4 | 1 << 3): Select the purpose of the "Output" connector:
*** 00 : Trigger pulse output
*** 01 : PWM DAC from the pattern generator buffer.
*** 10 : (?) never seen...
*** 11 : White noise
** (1 << 6 | 1 << 5): These hold the DSO/LA trigger configuration:
*** 00 : DSO level trigger
*** 01 : DSO pulse trigger, width less than TRIGGER_WIDTH
*** 10 : DSO pulse trigger, width equal or greater than TRIGGER_WIDTH
*** 11 : LA combination trigger
* LA_TRIGGER(5): The value of the LA byte that generates a trigger event (in that mode).
* LA_TRIGGER_MASK(6): The mask for the LA_TRIGGER (bits set to 0 matter, those set to 1 are ignored).
* SCOPE_TRIGGER_HOLDOFF1 (7):
* SCOPE_TRIGGER_HOLDOFF2 (8): Store the trigger holdoff (delay between a triggering event and the trigger rearming).
* CLKRATE(9-10):
* TRIGGER_WIDTH (11): Stores the pulse width for the DSO pulse trigger, in sample units. Forced to be greater than 3 by the mso19 app.
* DAC(12-13):

===== Registers for ((R15 & 0x3) == 0x1) =====

This mode seems to be used to configure the pattern generator.

* REG_PATGEN_CLOCK1 (2) :
* REG_PATGEN_CLOCK2 (3) : Stores the sample clock configuration. Not sure how these two bytes work together...
* REG_PATGEN_START_L (4):
* REG_PATGEN_START_H (5): The start address for the pattern generator buffer (1023 samples long). When writing to the buffer, it is set to 0.
* REG_PATGEN_END_L (6):
* REG_PATGEN_END_H (7): The end address for the pattern generator buffer (1023 samples long). When writing the buffer, it is set to 0x3ff. When in normal mode (to set the end of the output) it is writen as the end address minus 2 (probably due to the actual implementation details).
* PATGEN_CFG (8): Configures the pattern generator.
** (1 << 0): Continuous mode ? (only seems to be allowed for the waveform generator, not for the pattern generator. why?)
** (1 << 1): Enter pattern write mode.
** (1 << 3 | 1 << 2):
*** 11 : Manual start (starts after a pulse in PATGEN_TRIG)
*** 10 : Start on MSO trigger
*** 01 : Start on MSO "Go" (MSO trigger arm)
*** 00 : Disabled
* PATGEN_TRIG (9): writen 0x1 and then 0x0, acts as a manual trigger to activate "stuff".
* PATGEN_WORD (10): In pattern write mode, takes the word for the current "instant".
* PATGEN_IO (11): In pattern write mode, writing 0x1 makes the instant an output one, and writing 0x0 makes it an input one (?)
* PATGEN_LOOPS (12): Stores the number of loops for the pattern generator. Set to 1 for pattern buffer writing mode.
* PATTERN_MASK (13): Stores the output bit mask (1 for enabled bits, 0 for disabled bits)

===== Registers for ((R15 & 0x3) == 0x2) =====

This mode is used to set the i2c or spi triggers.
NOTES:
* the difference between i2c and spi capture seems to be the TRIGGER_CFG_H bits (see R15 = 0)
* how does the hardware handle the start/stop conditions or the ack bit??

The protocol matcher seems to be comprised of a 4 byte shift register. The serial bits are shifted in through the last byte comparator (word 3) and exit through the first byte comparator (word 0). This is why if the trigger is set up with less than 3 words, the first bytes are the ones that end up matching everything (word set to 0x00, mask set to 0xff).

The mask bytes have their bits set to 1 for "ignore", and 0 for "match". The protocol matching block simply doing something this for every bit i:

matches[i] = (read[i] ^ word[i]) | mask[i]

The final result is the and'ing of the resulting 32 bits.

* TRIG_WORD0 (0): Hold the comparison words for the comparator.
* TRIG_WORD1 (1):
* TRIG_WORD2 (2):
* TRIG_WORD2 (3):
* TRIG_MASK0 (4): Holds the mask for the comparator (bits set at 1 always produce a positive match)
* TRIG_MASK1 (5):
* TRIG_MASK2 (6):
* TRIG_MASK3 (7):
* TRIG_SPI_MODE (8): Holds the SPI mode for triggering (valid modes 0, 1, 2, 3). Is set to 0 for I2C (not sure if mandatory)

===== Registers which don't seem to change purpose (so far) =====

*CONTROL1 (14):
**(1 << 0): Reset SFM
**(1 << 3): Force trigger
**(1 << 4): Reset ADC (?)
**(1 << 6): Reset ADC (?)
**(1 << 7): Led on/off
*CONTROL2 (15):
** (1 << 1 | 1 << 0): Control which register bank is selected for writing:
*** 00: The DSO and LA control bank is selected
*** 01: The PG (patern generator) control bank is selected
*** 10: The PT (protocol trigger) control bank is selected
** (1 << 5): Slow mode (?) (set for the low clock rates, probably enables a clock divider)

== Device reply description ==

* After writing 0x0 to the registers (1) or (2) of bank 0, the device replies with either 3072 bytes (1), or 1 byte (2).
* Only 7 bits are used from each byte.
* Bit (1 << 6) indicates which type of message this is:
** 0: This is a "status" message.
** 1: This is a "data" message.

===== STATUS ((1 << 6) == 0) =====
* The reply comprises just one byte. The lower nibble contains the trigger status (t), while the upper nibble contains the hardware status (??):
** (1): [ <?> <?> <?> <?> <t3> <t2> <t1> <t0> ]

* Values for t(3:0):
** 0x6: Triggered (data ready on the samples buffer).
** 0x4: Armed but not triggered yet (?)
** 0x1: (?) That should be read on startup..

===== DATA ((1 << 6) == 1) =====
* The reply is 24 bit aligned, and contains both the 10 bit analog sample data (a) and the 8 bit digital sample data (d).
* There's a total of 3072 bytes, comprising 1024 samples.
* For each group of 24 bits (a "sample"):
** (byte 0): [ <ignored> 1 <a5> <a4> <a3> <a2> <a1> <a0> ]
** (byte 1): [ <ignored> 1 <d1> <d0> <a9> <a8> <a7> <a6> ]
** (byte 2): [ <ignored> 1 <d7> <d6> <d5> <d4> <d3> <d2> ]

== Device operation ==

The trigger status must be checked periodically, by writing 0 to the "Read Status" register (address 0 of bank 0). The returned value indicates the device status.

=== Startup ===

* The MSO19 application starts by checking the device status. It accepts the values 0x21 or 0x31 as normal, before proceeding.
* It then resets the ADC, and checks for the device status again, and also accepts the values 0x21 and 0x31 as normal.
(...)

=== Capture Start ===

Upon starting a capture, by hitting the "Go" button:
* If the DSO or the DAC need to be configured, the app resets the FSM (finite state machine), and then configures them both.
* If the PG needs to be configured, the app configures it.
* The app then arms the trigger system.
* Finally the app issues a trigger check (writing 0 to the register), and waits for the serial reply.

=== Handle Serial Reply ===

* First the app checks how many bytes there are waiting on the serial port buffer. It only accepts two byte lengths, 3072 bytes and 1 byte.
* The app then checks if the first byte has bit 6 turned off ((byte & (1 << 6)) == 0), and if it is, it assumes it's a trigger status. Otherwise it assumes it's sample data.

Link Instruments MSO-19

2012-01-22T00:22:56Z

Seventhguardian: /* Device reply description */

[[File:MSO-19.JPG|thumb|right|Link Instruments MSO-19]]
[[File:MSO-19-naked.jpg|thumb|right|PCB Front]]

The [http://www.linkinstruments.com/mso19.htm Link Instruments MSO-19] is a 2GSa/s oscilloscope, 200MSa/s logic analyzer, 100MSa/s pattern generator and a TDR. It is also extremely portable and is only $249 (including probe, clips, wires and software).

See [[Link Instruments MSO-19/Info]] for more details (such as '''lsusb -vvv''' output) about the device.

== Hardware ==

* [http://www.latticesemi.com/products/cpld/machxo/index.cfm Lattice MachXO LCMXO2280 PLD]
* [http://www.intersil.com/products/deviceinfo.asp?pn=KAD2710C-10 Kenet KAD2710C-10 10bit, 105MSPS ADC]
* [http://www.silabs.com/products/interface/usbtouart/Pages/usb-to-uart-bridge.aspx Silabs CP2103 USB to UART Bridge]

== Original software ==

Link Instruments ships the product with its ''FrontPanelTM Oscilloscope software''. Software is for Windows only. Written in .NET (C#), without any kind of obfuscation, which makes it a real breeze to reverse engineer.

== USB protocol ==

It's just serial-over-USB, supported by the Linux kernel through the '''[http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/usb/serial/cp210x.c;hb=90a4c0f51e8e44111a926be6f4c87af3938a79c3 cp210x]''' driver, though as of Kernel 3.2.1 it needs to be patched to recognize the Link Instruments Vendor/Product ID ('''3195:f190''').

iSerial was exploited by Link Instruments to store hardware type, hardware revision, calibration quirks and the actual serial number.
*for an iSerial of 4294333650260000000 we have:
**42943 336 502 6 0 000000
***vbit = 42943 / 10000
***dacoffset = 336
***offsetrange = 502
***hwmodel = 6
***hwrev = 0
***serial number = 000000

== Serial protocol ==
*Control message
**Fixed header: 0x40, 0x4c, 0x44, 0x53, 0x7e
**Variable size payload, 16bit aligned
***Looks like each 16bits of payload are a register write operation
***register writes are 4bits for addr, 8 bits for value, 2 unused bits and 2 bits im not sure what they are for :)
**** The simplest explanation for the unused bits is that the device bus width is 7 bits (being a CPLD that is very acceptable).
**** The 2 special bits seem to be synchronization bits. 0x7e violates the conversion (high byte), and that may be used to reset the CPLD parser at the end of the packet.
***.?12 AAAA .?34 5678
***Conversion is: ((v & 0x3f) | ((v & 0xc0) << 6) | ((a & 0xf) << 8) | (((v ^ 0x20) & 0x20) << 1) | (((v ^ 0x80) & 0x80) << 7))
***Byte order is big endian
**Fixed footer: 0x7e

== Registers description ==
There is no way to read from registers, only write is possible.

The purpose of registers 0 to 13 seems to depend on the value of the 2 lsbs of register 15.

===== Registers for ((R15 & 0x3) == 0x0) =====

* Read Sample buffer (1): Write 0 to this register to read the samples buffer.
* Read Trigger status (2): Write 0 to this register to read the trigger status.
* TRIGGER_CONFIG_L (3):
** lsbyte of the threshold value.
* TRIGGER_CONFIG_H (4):
** bits [1:0] hold the msbits of the threshold value
** (1 << 2): Trigger on falling edge
** (1 << 4 | 1 << 3): Select the purpose of the "Output" connector:
*** 00 : Trigger pulse output
*** 01 : PWM DAC from the pattern generator buffer.
*** 10 : (?) never seen...
*** 11 : White noise
** (1 << 6 | 1 << 5): These hold the DSO/LA trigger configuration:
*** 00 : DSO level trigger
*** 01 : DSO pulse trigger, width less than TRIGGER_WIDTH
*** 10 : DSO pulse trigger, width equal or greater than TRIGGER_WIDTH
*** 11 : LA combination trigger
* LA_TRIGGER(5): The value of the LA byte that generates a trigger event (in that mode).
* LA_TRIGGER_MASK(6): The mask for the LA_TRIGGER (bits set to 0 matter, those set to 1 are ignored).
* SCOPE_TRIGGER_HOLDOFF1 (7):
* SCOPE_TRIGGER_HOLDOFF2 (8): Store the trigger holdoff (delay between a triggering event and the trigger rearming).
* CLKRATE(9-10):
* TRIGGER_WIDTH (11): Stores the pulse width for the DSO pulse trigger, in sample units. Forced to be greater than 3 by the mso19 app.
* DAC(12-13):

===== Registers for ((R15 & 0x3) == 0x1) =====

This mode seems to be used to configure the pattern generator.

* REG_PATGEN_CLOCK1 (2) :
* REG_PATGEN_CLOCK2 (3) : Stores the sample clock configuration. Not sure how these two bytes work together...
* REG_PATGEN_START_L (4):
* REG_PATGEN_START_H (5): The start address for the pattern generator buffer (1023 samples long). When writing to the buffer, it is set to 0.
* REG_PATGEN_END_L (6):
* REG_PATGEN_END_H (7): The end address for the pattern generator buffer (1023 samples long). When writing the buffer, it is set to 0x3ff. When in normal mode (to set the end of the output) it is writen as the end address minus 2 (probably due to the actual implementation details).
* PATGEN_CFG (8): Configures the pattern generator.
** (1 << 0): Continuous mode ? (only seems to be allowed for the waveform generator, not for the pattern generator. why?)
** (1 << 1): Enter pattern write mode.
** (1 << 3 | 1 << 2):
*** 11 : Manual start (starts after a pulse in PATGEN_TRIG)
*** 10 : Start on MSO trigger
*** 01 : Start on MSO "Go" (MSO trigger arm)
*** 00 : Disabled
* PATGEN_TRIG (9): writen 0x1 and then 0x0, acts as a manual trigger to activate "stuff".
* PATGEN_WORD (10): In pattern write mode, takes the word for the current "instant".
* PATGEN_IO (11): In pattern write mode, writing 0x1 makes the instant an output one, and writing 0x0 makes it an input one (?)
* PATGEN_LOOPS (12): Stores the number of loops for the pattern generator. Set to 1 for pattern buffer writing mode.
* PATTERN_MASK (13): Stores the output bit mask (1 for enabled bits, 0 for disabled bits)

===== Registers for ((R15 & 0x3) == 0x2) =====

This mode is used to set the i2c or spi triggers.
NOTES:
* the difference between i2c and spi capture seems to be the TRIGGER_CFG_H bits (see R15 = 0)
* how does the hardware handle the start/stop conditions or the ack bit??

The protocol matcher seems to be comprised of a 4 byte shift register. The serial bits are shifted in through the last byte comparator (word 3) and exit through the first byte comparator (word 0). This is why if the trigger is set up with less than 3 words, the first bytes are the ones that end up matching everything (word set to 0x00, mask set to 0xff).

The mask bytes have their bits set to 1 for "ignore", and 0 for "match". The protocol matching block simply doing something this for every bit i:

matches[i] = (read[i] ^ word[i]) | mask[i]

The final result is the and'ing of the resulting 32 bits.

* TRIG_WORD0 (0): Hold the comparison words for the comparator.
* TRIG_WORD1 (1):
* TRIG_WORD2 (2):
* TRIG_WORD2 (3):
* TRIG_MASK0 (4): Holds the mask for the comparator (bits set at 1 always produce a positive match)
* TRIG_MASK1 (5):
* TRIG_MASK2 (6):
* TRIG_MASK3 (7):
* TRIG_SPI_MODE (8): Holds the SPI mode for triggering (valid modes 0, 1, 2, 3). Is set to 0 for I2C (not sure if mandatory)

===== Registers which don't seem to change purpose (so far) =====

*CONTROL1 (14):
**(1 << 0): Reset SFM
**(1 << 3): Force trigger
**(1 << 4): Reset ADC (?)
**(1 << 6): Reset ADC (?)
**(1 << 7): Led on/off
*CONTROL2 (15):
** (1 << 1 | 1 << 0): Control which register bank is selected for writing:
*** 00: The DSO and LA control bank is selected
*** 01: The PG (patern generator) control bank is selected
*** 10: The PT (protocol trigger) control bank is selected
** (1 << 5): Slow mode (?) (set for the low clock rates, probably enables a clock divider)

== Device reply description ==

* After writing 0x0 to the registers (1) or (2) of bank 0, the device replies with either 3072 bytes (1), or 1 byte (2).
* Only 7 bits are used from each byte.
* Bit (1 << 6) indicates which type of message this is:
** 0: This is a "status" message.
** 1: This is a "data" message.

===== STATUS ((1 << 6) == 0) =====
* The reply comprises just one byte. The lower nibble contains the trigger status (t), while the upper nibble contains the hardware status (??):
** (1): [ <?> <?> <?> <?> <t3> <t2> <t1> <t0> ]

* Values for t(3:0):
** 0x6: Triggered (data ready on the samples buffer).
** (?)
** 0x1: (?) That should be read on startup..

===== DATA ((1 << 6) == 1) =====
* The reply is 24 bit aligned, and contains both the 10 bit analog sample data (a) and the 8 bit digital sample data (d).
* There's a total of 3072 bytes, comprising 1024 samples.
* For each group of 24 bits (a "sample"):
** (byte 0): [ <ignored> 1 <a5> <a4> <a3> <a2> <a1> <a0> ]
** (byte 1): [ <ignored> 1 <d1> <d0> <a9> <a8> <a7> <a6> ]
** (byte 2): [ <ignored> 1 <d7> <d6> <d5> <d4> <d3> <d2> ]

== Device operation ==

The trigger status must be checked periodically, by writing 0 to the "Read Status" register (address 0 of bank 0). The returned value indicates the device status.

=== Startup ===

* The MSO19 application starts by checking the device status. It accepts the values 0x21 or 0x31 as normal, before proceeding.
* It then resets the ADC, and checks for the device status again, and also accepts the values 0x21 and 0x31 as normal.
(...)

=== Capture Start ===

Upon starting a capture, by hitting the "Go" button:
* If the DSO or the DAC need to be configured, the app resets the FSM (finite state machine), and then configures them both.
* If the PG needs to be configured, the app configures it.
* The app then arms the trigger system.
* Finally the app issues a trigger check (writing 0 to the register), and waits for the serial reply.

=== Handle Serial Reply ===

* First the app checks how many bytes there are waiting on the serial port buffer. It only accepts two byte lengths, 3072 bytes and 1 byte.
* The app then checks if the first byte has bit 6 turned off ((byte & (1 << 6)) == 0), and if it is, it assumes it's a trigger status. Otherwise it assumes it's sample data.

Link Instruments MSO-19

2012-01-22T00:22:40Z

Seventhguardian: /* STATUS ((1 << 6) == 0) */

[[File:MSO-19.JPG|thumb|right|Link Instruments MSO-19]]
[[File:MSO-19-naked.jpg|thumb|right|PCB Front]]

The [http://www.linkinstruments.com/mso19.htm Link Instruments MSO-19] is a 2GSa/s oscilloscope, 200MSa/s logic analyzer, 100MSa/s pattern generator and a TDR. It is also extremely portable and is only $249 (including probe, clips, wires and software).

See [[Link Instruments MSO-19/Info]] for more details (such as '''lsusb -vvv''' output) about the device.

== Hardware ==

* [http://www.latticesemi.com/products/cpld/machxo/index.cfm Lattice MachXO LCMXO2280 PLD]
* [http://www.intersil.com/products/deviceinfo.asp?pn=KAD2710C-10 Kenet KAD2710C-10 10bit, 105MSPS ADC]
* [http://www.silabs.com/products/interface/usbtouart/Pages/usb-to-uart-bridge.aspx Silabs CP2103 USB to UART Bridge]

== Original software ==

Link Instruments ships the product with its ''FrontPanelTM Oscilloscope software''. Software is for Windows only. Written in .NET (C#), without any kind of obfuscation, which makes it a real breeze to reverse engineer.

== USB protocol ==

It's just serial-over-USB, supported by the Linux kernel through the '''[http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/usb/serial/cp210x.c;hb=90a4c0f51e8e44111a926be6f4c87af3938a79c3 cp210x]''' driver, though as of Kernel 3.2.1 it needs to be patched to recognize the Link Instruments Vendor/Product ID ('''3195:f190''').

iSerial was exploited by Link Instruments to store hardware type, hardware revision, calibration quirks and the actual serial number.
*for an iSerial of 4294333650260000000 we have:
**42943 336 502 6 0 000000
***vbit = 42943 / 10000
***dacoffset = 336
***offsetrange = 502
***hwmodel = 6
***hwrev = 0
***serial number = 000000

== Serial protocol ==
*Control message
**Fixed header: 0x40, 0x4c, 0x44, 0x53, 0x7e
**Variable size payload, 16bit aligned
***Looks like each 16bits of payload are a register write operation
***register writes are 4bits for addr, 8 bits for value, 2 unused bits and 2 bits im not sure what they are for :)
**** The simplest explanation for the unused bits is that the device bus width is 7 bits (being a CPLD that is very acceptable).
**** The 2 special bits seem to be synchronization bits. 0x7e violates the conversion (high byte), and that may be used to reset the CPLD parser at the end of the packet.
***.?12 AAAA .?34 5678
***Conversion is: ((v & 0x3f) | ((v & 0xc0) << 6) | ((a & 0xf) << 8) | (((v ^ 0x20) & 0x20) << 1) | (((v ^ 0x80) & 0x80) << 7))
***Byte order is big endian
**Fixed footer: 0x7e

== Registers description ==
There is no way to read from registers, only write is possible.

The purpose of registers 0 to 13 seems to depend on the value of the 2 lsbs of register 15.

===== Registers for ((R15 & 0x3) == 0x0) =====

* Read Sample buffer (1): Write 0 to this register to read the samples buffer.
* Read Trigger status (2): Write 0 to this register to read the trigger status.
* TRIGGER_CONFIG_L (3):
** lsbyte of the threshold value.
* TRIGGER_CONFIG_H (4):
** bits [1:0] hold the msbits of the threshold value
** (1 << 2): Trigger on falling edge
** (1 << 4 | 1 << 3): Select the purpose of the "Output" connector:
*** 00 : Trigger pulse output
*** 01 : PWM DAC from the pattern generator buffer.
*** 10 : (?) never seen...
*** 11 : White noise
** (1 << 6 | 1 << 5): These hold the DSO/LA trigger configuration:
*** 00 : DSO level trigger
*** 01 : DSO pulse trigger, width less than TRIGGER_WIDTH
*** 10 : DSO pulse trigger, width equal or greater than TRIGGER_WIDTH
*** 11 : LA combination trigger
* LA_TRIGGER(5): The value of the LA byte that generates a trigger event (in that mode).
* LA_TRIGGER_MASK(6): The mask for the LA_TRIGGER (bits set to 0 matter, those set to 1 are ignored).
* SCOPE_TRIGGER_HOLDOFF1 (7):
* SCOPE_TRIGGER_HOLDOFF2 (8): Store the trigger holdoff (delay between a triggering event and the trigger rearming).
* CLKRATE(9-10):
* TRIGGER_WIDTH (11): Stores the pulse width for the DSO pulse trigger, in sample units. Forced to be greater than 3 by the mso19 app.
* DAC(12-13):

===== Registers for ((R15 & 0x3) == 0x1) =====

This mode seems to be used to configure the pattern generator.

* REG_PATGEN_CLOCK1 (2) :
* REG_PATGEN_CLOCK2 (3) : Stores the sample clock configuration. Not sure how these two bytes work together...
* REG_PATGEN_START_L (4):
* REG_PATGEN_START_H (5): The start address for the pattern generator buffer (1023 samples long). When writing to the buffer, it is set to 0.
* REG_PATGEN_END_L (6):
* REG_PATGEN_END_H (7): The end address for the pattern generator buffer (1023 samples long). When writing the buffer, it is set to 0x3ff. When in normal mode (to set the end of the output) it is writen as the end address minus 2 (probably due to the actual implementation details).
* PATGEN_CFG (8): Configures the pattern generator.
** (1 << 0): Continuous mode ? (only seems to be allowed for the waveform generator, not for the pattern generator. why?)
** (1 << 1): Enter pattern write mode.
** (1 << 3 | 1 << 2):
*** 11 : Manual start (starts after a pulse in PATGEN_TRIG)
*** 10 : Start on MSO trigger
*** 01 : Start on MSO "Go" (MSO trigger arm)
*** 00 : Disabled
* PATGEN_TRIG (9): writen 0x1 and then 0x0, acts as a manual trigger to activate "stuff".
* PATGEN_WORD (10): In pattern write mode, takes the word for the current "instant".
* PATGEN_IO (11): In pattern write mode, writing 0x1 makes the instant an output one, and writing 0x0 makes it an input one (?)
* PATGEN_LOOPS (12): Stores the number of loops for the pattern generator. Set to 1 for pattern buffer writing mode.
* PATTERN_MASK (13): Stores the output bit mask (1 for enabled bits, 0 for disabled bits)

===== Registers for ((R15 & 0x3) == 0x2) =====

This mode is used to set the i2c or spi triggers.
NOTES:
* the difference between i2c and spi capture seems to be the TRIGGER_CFG_H bits (see R15 = 0)
* how does the hardware handle the start/stop conditions or the ack bit??

The protocol matcher seems to be comprised of a 4 byte shift register. The serial bits are shifted in through the last byte comparator (word 3) and exit through the first byte comparator (word 0). This is why if the trigger is set up with less than 3 words, the first bytes are the ones that end up matching everything (word set to 0x00, mask set to 0xff).

The mask bytes have their bits set to 1 for "ignore", and 0 for "match". The protocol matching block simply doing something this for every bit i:

matches[i] = (read[i] ^ word[i]) | mask[i]

The final result is the and'ing of the resulting 32 bits.

* TRIG_WORD0 (0): Hold the comparison words for the comparator.
* TRIG_WORD1 (1):
* TRIG_WORD2 (2):
* TRIG_WORD2 (3):
* TRIG_MASK0 (4): Holds the mask for the comparator (bits set at 1 always produce a positive match)
* TRIG_MASK1 (5):
* TRIG_MASK2 (6):
* TRIG_MASK3 (7):
* TRIG_SPI_MODE (8): Holds the SPI mode for triggering (valid modes 0, 1, 2, 3). Is set to 0 for I2C (not sure if mandatory)

===== Registers which don't seem to change purpose (so far) =====

*CONTROL1 (14):
**(1 << 0): Reset SFM
**(1 << 3): Force trigger
**(1 << 4): Reset ADC (?)
**(1 << 6): Reset ADC (?)
**(1 << 7): Led on/off
*CONTROL2 (15):
** (1 << 1 | 1 << 0): Control which register bank is selected for writing:
*** 00: The DSO and LA control bank is selected
*** 01: The PG (patern generator) control bank is selected
*** 10: The PT (protocol trigger) control bank is selected
** (1 << 5): Slow mode (?) (set for the low clock rates, probably enables a clock divider)

== Device reply description ==

* After writing 0x0 to the registers (1) or (2) of bank 0, the device replies with either 3072 bytes (1), or 1 byte (2).
* Only 7 bits are used from each byte.
* Bit (1 << 6) indicates which type of message this is:
** 0: This is a "status" message.
** 1: This is a "data" message.

===== STATUS ((1 << 6) == 0) =====
* The reply comprises just one byte. The lower nibble contains the trigger status (t), while the upper nibble contains the hardware status (??):
** (1): [ <?> <?> <?> <?> <t3> <t2> <t1> <t0> ]

* Values for t(3:0):
** 0x6: Triggered (data ready on the samples buffer).
(?)
** 0x1: (?) That should be read on startup..

===== DATA ((1 << 6) == 1) =====
* The reply is 24 bit aligned, and contains both the 10 bit analog sample data (a) and the 8 bit digital sample data (d).
* There's a total of 3072 bytes, comprising 1024 samples.
* For each group of 24 bits (a "sample"):
** (byte 0): [ <ignored> 1 <a5> <a4> <a3> <a2> <a1> <a0> ]
** (byte 1): [ <ignored> 1 <d1> <d0> <a9> <a8> <a7> <a6> ]
** (byte 2): [ <ignored> 1 <d7> <d6> <d5> <d4> <d3> <d2> ]

== Device operation ==

The trigger status must be checked periodically, by writing 0 to the "Read Status" register (address 0 of bank 0). The returned value indicates the device status.

=== Startup ===

* The MSO19 application starts by checking the device status. It accepts the values 0x21 or 0x31 as normal, before proceeding.
* It then resets the ADC, and checks for the device status again, and also accepts the values 0x21 and 0x31 as normal.
(...)

=== Capture Start ===

Upon starting a capture, by hitting the "Go" button:
* If the DSO or the DAC need to be configured, the app resets the FSM (finite state machine), and then configures them both.
* If the PG needs to be configured, the app configures it.
* The app then arms the trigger system.
* Finally the app issues a trigger check (writing 0 to the register), and waits for the serial reply.

=== Handle Serial Reply ===

* First the app checks how many bytes there are waiting on the serial port buffer. It only accepts two byte lengths, 3072 bytes and 1 byte.
* The app then checks if the first byte has bit 6 turned off ((byte & (1 << 6)) == 0), and if it is, it assumes it's a trigger status. Otherwise it assumes it's sample data.

Link Instruments MSO-19

2012-01-22T00:05:24Z

Seventhguardian:

[[File:MSO-19.JPG|thumb|right|Link Instruments MSO-19]]
[[File:MSO-19-naked.jpg|thumb|right|PCB Front]]

The [http://www.linkinstruments.com/mso19.htm Link Instruments MSO-19] is a 2GSa/s oscilloscope, 200MSa/s logic analyzer, 100MSa/s pattern generator and a TDR. It is also extremely portable and is only $249 (including probe, clips, wires and software).

See [[Link Instruments MSO-19/Info]] for more details (such as '''lsusb -vvv''' output) about the device.

== Hardware ==

* [http://www.latticesemi.com/products/cpld/machxo/index.cfm Lattice MachXO LCMXO2280 PLD]
* [http://www.intersil.com/products/deviceinfo.asp?pn=KAD2710C-10 Kenet KAD2710C-10 10bit, 105MSPS ADC]
* [http://www.silabs.com/products/interface/usbtouart/Pages/usb-to-uart-bridge.aspx Silabs CP2103 USB to UART Bridge]

== Original software ==

Link Instruments ships the product with its ''FrontPanelTM Oscilloscope software''. Software is for Windows only. Written in .NET (C#), without any kind of obfuscation, which makes it a real breeze to reverse engineer.

== USB protocol ==

It's just serial-over-USB, supported by the Linux kernel through the '''[http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/usb/serial/cp210x.c;hb=90a4c0f51e8e44111a926be6f4c87af3938a79c3 cp210x]''' driver, though as of Kernel 3.2.1 it needs to be patched to recognize the Link Instruments Vendor/Product ID ('''3195:f190''').

iSerial was exploited by Link Instruments to store hardware type, hardware revision, calibration quirks and the actual serial number.
*for an iSerial of 4294333650260000000 we have:
**42943 336 502 6 0 000000
***vbit = 42943 / 10000
***dacoffset = 336
***offsetrange = 502
***hwmodel = 6
***hwrev = 0
***serial number = 000000

== Serial protocol ==
*Control message
**Fixed header: 0x40, 0x4c, 0x44, 0x53, 0x7e
**Variable size payload, 16bit aligned
***Looks like each 16bits of payload are a register write operation
***register writes are 4bits for addr, 8 bits for value, 2 unused bits and 2 bits im not sure what they are for :)
**** The simplest explanation for the unused bits is that the device bus width is 7 bits (being a CPLD that is very acceptable).
**** The 2 special bits seem to be synchronization bits. 0x7e violates the conversion (high byte), and that may be used to reset the CPLD parser at the end of the packet.
***.?12 AAAA .?34 5678
***Conversion is: ((v & 0x3f) | ((v & 0xc0) << 6) | ((a & 0xf) << 8) | (((v ^ 0x20) & 0x20) << 1) | (((v ^ 0x80) & 0x80) << 7))
***Byte order is big endian
**Fixed footer: 0x7e

== Registers description ==
There is no way to read from registers, only write is possible.

The purpose of registers 0 to 13 seems to depend on the value of the 2 lsbs of register 15.

===== Registers for ((R15 & 0x3) == 0x0) =====

* Read Sample buffer (1): Write 0 to this register to read the samples buffer.
* Read Trigger status (2): Write 0 to this register to read the trigger status.
* TRIGGER_CONFIG_L (3):
** lsbyte of the threshold value.
* TRIGGER_CONFIG_H (4):
** bits [1:0] hold the msbits of the threshold value
** (1 << 2): Trigger on falling edge
** (1 << 4 | 1 << 3): Select the purpose of the "Output" connector:
*** 00 : Trigger pulse output
*** 01 : PWM DAC from the pattern generator buffer.
*** 10 : (?) never seen...
*** 11 : White noise
** (1 << 6 | 1 << 5): These hold the DSO/LA trigger configuration:
*** 00 : DSO level trigger
*** 01 : DSO pulse trigger, width less than TRIGGER_WIDTH
*** 10 : DSO pulse trigger, width equal or greater than TRIGGER_WIDTH
*** 11 : LA combination trigger
* LA_TRIGGER(5): The value of the LA byte that generates a trigger event (in that mode).
* LA_TRIGGER_MASK(6): The mask for the LA_TRIGGER (bits set to 0 matter, those set to 1 are ignored).
* SCOPE_TRIGGER_HOLDOFF1 (7):
* SCOPE_TRIGGER_HOLDOFF2 (8): Store the trigger holdoff (delay between a triggering event and the trigger rearming).
* CLKRATE(9-10):
* TRIGGER_WIDTH (11): Stores the pulse width for the DSO pulse trigger, in sample units. Forced to be greater than 3 by the mso19 app.
* DAC(12-13):

===== Registers for ((R15 & 0x3) == 0x1) =====

This mode seems to be used to configure the pattern generator.

* REG_PATGEN_CLOCK1 (2) :
* REG_PATGEN_CLOCK2 (3) : Stores the sample clock configuration. Not sure how these two bytes work together...
* REG_PATGEN_START_L (4):
* REG_PATGEN_START_H (5): The start address for the pattern generator buffer (1023 samples long). When writing to the buffer, it is set to 0.
* REG_PATGEN_END_L (6):
* REG_PATGEN_END_H (7): The end address for the pattern generator buffer (1023 samples long). When writing the buffer, it is set to 0x3ff. When in normal mode (to set the end of the output) it is writen as the end address minus 2 (probably due to the actual implementation details).
* PATGEN_CFG (8): Configures the pattern generator.
** (1 << 0): Continuous mode ? (only seems to be allowed for the waveform generator, not for the pattern generator. why?)
** (1 << 1): Enter pattern write mode.
** (1 << 3 | 1 << 2):
*** 11 : Manual start (starts after a pulse in PATGEN_TRIG)
*** 10 : Start on MSO trigger
*** 01 : Start on MSO "Go" (MSO trigger arm)
*** 00 : Disabled
* PATGEN_TRIG (9): writen 0x1 and then 0x0, acts as a manual trigger to activate "stuff".
* PATGEN_WORD (10): In pattern write mode, takes the word for the current "instant".
* PATGEN_IO (11): In pattern write mode, writing 0x1 makes the instant an output one, and writing 0x0 makes it an input one (?)
* PATGEN_LOOPS (12): Stores the number of loops for the pattern generator. Set to 1 for pattern buffer writing mode.
* PATTERN_MASK (13): Stores the output bit mask (1 for enabled bits, 0 for disabled bits)

===== Registers for ((R15 & 0x3) == 0x2) =====

This mode is used to set the i2c or spi triggers.
NOTES:
* the difference between i2c and spi capture seems to be the TRIGGER_CFG_H bits (see R15 = 0)
* how does the hardware handle the start/stop conditions or the ack bit??

The protocol matcher seems to be comprised of a 4 byte shift register. The serial bits are shifted in through the last byte comparator (word 3) and exit through the first byte comparator (word 0). This is why if the trigger is set up with less than 3 words, the first bytes are the ones that end up matching everything (word set to 0x00, mask set to 0xff).

The mask bytes have their bits set to 1 for "ignore", and 0 for "match". The protocol matching block simply doing something this for every bit i:

matches[i] = (read[i] ^ word[i]) | mask[i]

The final result is the and'ing of the resulting 32 bits.

* TRIG_WORD0 (0): Hold the comparison words for the comparator.
* TRIG_WORD1 (1):
* TRIG_WORD2 (2):
* TRIG_WORD2 (3):
* TRIG_MASK0 (4): Holds the mask for the comparator (bits set at 1 always produce a positive match)
* TRIG_MASK1 (5):
* TRIG_MASK2 (6):
* TRIG_MASK3 (7):
* TRIG_SPI_MODE (8): Holds the SPI mode for triggering (valid modes 0, 1, 2, 3). Is set to 0 for I2C (not sure if mandatory)

===== Registers which don't seem to change purpose (so far) =====

*CONTROL1 (14):
**(1 << 0): Reset SFM
**(1 << 3): Force trigger
**(1 << 4): Reset ADC (?)
**(1 << 6): Reset ADC (?)
**(1 << 7): Led on/off
*CONTROL2 (15):
** (1 << 1 | 1 << 0): Control which register bank is selected for writing:
*** 00: The DSO and LA control bank is selected
*** 01: The PG (patern generator) control bank is selected
*** 10: The PT (protocol trigger) control bank is selected
** (1 << 5): Slow mode (?) (set for the low clock rates, probably enables a clock divider)

== Device reply description ==

* After writing 0x0 to the registers (1) or (2) of bank 0, the device replies with either 3072 bytes (1), or 1 byte (2).
* Only 7 bits are used from each byte.
* Bit (1 << 6) indicates which type of message this is:
** 0: This is a "status" message.
** 1: This is a "data" message.

===== STATUS ((1 << 6) == 0) =====
* The reply comprises just one byte. The lower nibble contains the trigger status, while the upper nibble contains the hardware status (??):

** (1):

===== DATA ((1 << 6) == 1) =====
* The reply is 24 bit aligned, and contains both the 10 bit analog sample data (a) and the 8 bit digital sample data (d).
* There's a total of 3072 bytes, comprising 1024 samples.
* For each group of 24 bits (a "sample"):
** (byte 0): [ <ignored> 1 <a5> <a4> <a3> <a2> <a1> <a0> ]
** (byte 1): [ <ignored> 1 <d1> <d0> <a9> <a8> <a7> <a6> ]
** (byte 2): [ <ignored> 1 <d7> <d6> <d5> <d4> <d3> <d2> ]

== Device operation ==

The trigger status must be checked periodically, by writing 0 to the "Read Status" register (address 0 of bank 0). The returned value indicates the device status.

=== Startup ===

* The MSO19 application starts by checking the device status. It accepts the values 0x21 or 0x31 as normal, before proceeding.
* It then resets the ADC, and checks for the device status again, and also accepts the values 0x21 and 0x31 as normal.
(...)

=== Capture Start ===

Upon starting a capture, by hitting the "Go" button:
* If the DSO or the DAC need to be configured, the app resets the FSM (finite state machine), and then configures them both.
* If the PG needs to be configured, the app configures it.
* The app then arms the trigger system.
* Finally the app issues a trigger check (writing 0 to the register), and waits for the serial reply.

=== Handle Serial Reply ===

* First the app checks how many bytes there are waiting on the serial port buffer. It only accepts two byte lengths, 3072 bytes and 1 byte.
* The app then checks if the first byte has bit 6 turned off ((byte & (1 << 6)) == 0), and if it is, it assumes it's a trigger status. Otherwise it assumes it's sample data.

Link Instruments MSO-19

2012-01-21T23:38:42Z

Seventhguardian: /* Device operation */

[[File:MSO-19.JPG|thumb|right|Link Instruments MSO-19]]
[[File:MSO-19-naked.jpg|thumb|right|PCB Front]]

The [http://www.linkinstruments.com/mso19.htm Link Instruments MSO-19] is a 2GSa/s oscilloscope, 200MSa/s logic analyzer, 100MSa/s pattern generator and a TDR. It is also extremely portable and is only $249 (including probe, clips, wires and software).

See [[Link Instruments MSO-19/Info]] for more details (such as '''lsusb -vvv''' output) about the device.

== Hardware ==

* [http://www.latticesemi.com/products/cpld/machxo/index.cfm Lattice MachXO LCMXO2280 PLD]
* [http://www.intersil.com/products/deviceinfo.asp?pn=KAD2710C-10 Kenet KAD2710C-10 10bit, 105MSPS ADC]
* [http://www.silabs.com/products/interface/usbtouart/Pages/usb-to-uart-bridge.aspx Silabs CP2103 USB to UART Bridge]

== Original software ==

Link Instruments ships the product with its ''FrontPanelTM Oscilloscope software''. Software is for Windows only. Written in .NET (C#), without any kind of obfuscation, which makes it a real breeze to reverse engineer.

== USB protocol ==

It's just serial-over-USB, supported by the Linux kernel through the '''[http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/usb/serial/cp210x.c;hb=90a4c0f51e8e44111a926be6f4c87af3938a79c3 cp210x]''' driver, though as of Kernel 3.2.1 it needs to be patched to recognize the Link Instruments Vendor/Product ID ('''3195:f190''').

iSerial was exploited by Link Instruments to store hardware type, hardware revision, calibration quirks and the actual serial number.
*for an iSerial of 4294333650260000000 we have:
**42943 336 502 6 0 000000
***vbit = 42943 / 10000
***dacoffset = 336
***offsetrange = 502
***hwmodel = 6
***hwrev = 0
***serial number = 000000

== Serial protocol ==
*Control message
**Fixed header: 0x40, 0x4c, 0x44, 0x53, 0x7e
**Variable size payload, 16bit aligned
***Looks like each 16bits of payload are a register write operation
***register writes are 4bits for addr, 8 bits for value, 2 unused bits and 2 bits im not sure what they are for :)
**** The simplest explanation for the unused bits is that the device bus width is 7 bits (being a CPLD that is very acceptable).
**** The 2 special bits seem to be synchronization bits. 0x7e violates the conversion (high byte), and that may be used to reset the CPLD parser at the end of the packet.
***.?12 AAAA .?34 5678
***Conversion is: ((v & 0x3f) | ((v & 0xc0) << 6) | ((a & 0xf) << 8) | (((v ^ 0x20) & 0x20) << 1) | (((v ^ 0x80) & 0x80) << 7))
***Byte order is big endian
**Fixed footer: 0x7e

== Registers description ==
There is no way to read from registers, only write is possible.

The purpose of registers 0 to 13 seems to depend on the value of the 2 lsbs of register 15.

===== Registers for ((R15 & 0x3) == 0x0) =====

* Read Sample buffer (1): Write 0 to this register to read the samples buffer.
* Read Trigger status (2): Write 0 to this register to read the trigger status.
* TRIGGER_CONFIG_L (3):
** lsbyte of the threshold value.
* TRIGGER_CONFIG_H (4):
** bits [1:0] hold the msbits of the threshold value
** (1 << 2): Trigger on falling edge
** (1 << 4 | 1 << 3): Select the purpose of the "Output" connector:
*** 00 : Trigger pulse output
*** 01 : PWM DAC from the pattern generator buffer.
*** 10 : (?) never seen...
*** 11 : White noise
** (1 << 6 | 1 << 5): These hold the DSO/LA trigger configuration:
*** 00 : DSO level trigger
*** 01 : DSO pulse trigger, width less than TRIGGER_WIDTH
*** 10 : DSO pulse trigger, width equal or greater than TRIGGER_WIDTH
*** 11 : LA combination trigger
* LA_TRIGGER(5): The value of the LA byte that generates a trigger event (in that mode).
* LA_TRIGGER_MASK(6): The mask for the LA_TRIGGER (bits set to 0 matter, those set to 1 are ignored).
* SCOPE_TRIGGER_HOLDOFF1 (7):
* SCOPE_TRIGGER_HOLDOFF2 (8): Store the trigger holdoff (delay between a triggering event and the trigger rearming).
* CLKRATE(9-10):
* TRIGGER_WIDTH (11): Stores the pulse width for the DSO pulse trigger, in sample units. Forced to be greater than 3 by the mso19 app.
* DAC(12-13):

===== Registers for ((R15 & 0x3) == 0x1) =====

This mode seems to be used to configure the pattern generator.

* REG_PATGEN_CLOCK1 (2) :
* REG_PATGEN_CLOCK2 (3) : Stores the sample clock configuration. Not sure how these two bytes work together...
* REG_PATGEN_START_L (4):
* REG_PATGEN_START_H (5): The start address for the pattern generator buffer (1023 samples long). When writing to the buffer, it is set to 0.
* REG_PATGEN_END_L (6):
* REG_PATGEN_END_H (7): The end address for the pattern generator buffer (1023 samples long). When writing the buffer, it is set to 0x3ff. When in normal mode (to set the end of the output) it is writen as the end address minus 2 (probably due to the actual implementation details).
* PATGEN_CFG (8): Configures the pattern generator.
** (1 << 0): Continuous mode ? (only seems to be allowed for the waveform generator, not for the pattern generator. why?)
** (1 << 1): Enter pattern write mode.
** (1 << 3 | 1 << 2):
*** 11 : Manual start (starts after a pulse in PATGEN_TRIG)
*** 10 : Start on MSO trigger
*** 01 : Start on MSO "Go" (MSO trigger arm)
*** 00 : Disabled
* PATGEN_TRIG (9): writen 0x1 and then 0x0, acts as a manual trigger to activate "stuff".
* PATGEN_WORD (10): In pattern write mode, takes the word for the current "instant".
* PATGEN_IO (11): In pattern write mode, writing 0x1 makes the instant an output one, and writing 0x0 makes it an input one (?)
* PATGEN_LOOPS (12): Stores the number of loops for the pattern generator. Set to 1 for pattern buffer writing mode.
* PATTERN_MASK (13): Stores the output bit mask (1 for enabled bits, 0 for disabled bits)

===== Registers for ((R15 & 0x3) == 0x2) =====

This mode is used to set the i2c or spi triggers.
NOTES:
* the difference between i2c and spi capture seems to be the TRIGGER_CFG_H bits (see R15 = 0)
* how does the hardware handle the start/stop conditions or the ack bit??

The protocol matcher seems to be comprised of a 4 byte shift register. The serial bits are shifted in through the last byte comparator (word 3) and exit through the first byte comparator (word 0). This is why if the trigger is set up with less than 3 words, the first bytes are the ones that end up matching everything (word set to 0x00, mask set to 0xff).

The mask bytes have their bits set to 1 for "ignore", and 0 for "match". The protocol matching block simply doing something this for every bit i:

matches[i] = (read[i] ^ word[i]) | mask[i]

The final result is the and'ing of the resulting 32 bits.

* TRIG_WORD0 (0): Hold the comparison words for the comparator.
* TRIG_WORD1 (1):
* TRIG_WORD2 (2):
* TRIG_WORD2 (3):
* TRIG_MASK0 (4): Holds the mask for the comparator (bits set at 1 always produce a positive match)
* TRIG_MASK1 (5):
* TRIG_MASK2 (6):
* TRIG_MASK3 (7):
* TRIG_SPI_MODE (8): Holds the SPI mode for triggering (valid modes 0, 1, 2, 3). Is set to 0 for I2C (not sure if mandatory)

===== Registers which don't seem to change purpose (so far) =====

*CONTROL1 (14):
**(1 << 0): Reset SFM
**(1 << 3): Force trigger
**(1 << 4): Reset ADC (?)
**(1 << 6): Reset ADC (?)
**(1 << 7): Led on/off
*CONTROL2 (15):
** (1 << 1 | 1 << 0): Control which register bank is selected for writing:
*** 00: The DSO and LA control bank is selected
*** 01: The PG (patern generator) control bank is selected
*** 10: The PT (protocol trigger) control bank is selected
** (1 << 5): Slow mode (?) (set for the low clock rates, probably enables a clock divider)

== Device operation ==

The trigger status must be checked periodically, by writing 0 to the "Read Status" register (address 0 of bank 0). The returned value indicates the device status.

=== Startup ===

* The MSO19 application starts by checking the device status. It accepts the values 0x21 or 0x31 as normal, before proceeding.
* It then resets the ADC, and checks for the device status again, and also accepts the values 0x21 and 0x31 as normal.
(...)

=== Capture Start ===

Upon starting a capture, by hitting the "Go" button:
* If the DSO or the DAC need to be configured, the app resets the FSM (finite state machine), and then configures them both.
* If the PG needs to be configured, the app configures it.
* The app then arms the trigger system.
* Finally the app issues a trigger check (writing 0 to the register), and waits for the serial reply.

=== Handle Serial Reply ===

* First the app checks how many bytes there are waiting on the serial port buffer. It only accepts two byte lengths, 3072 bytes and 1 byte.
* The app then checks if the first byte has bit 6 turned off ((byte & (1 << 6)) == 0), and if it is, it assumes it's a trigger status. Otherwise it assumes it's sample data.

Link Instruments MSO-19

2012-01-21T23:04:17Z

Seventhguardian:

[[File:MSO-19.JPG|thumb|right|Link Instruments MSO-19]]
[[File:MSO-19-naked.jpg|thumb|right|PCB Front]]

The [http://www.linkinstruments.com/mso19.htm Link Instruments MSO-19] is a 2GSa/s oscilloscope, 200MSa/s logic analyzer, 100MSa/s pattern generator and a TDR. It is also extremely portable and is only $249 (including probe, clips, wires and software).

See [[Link Instruments MSO-19/Info]] for more details (such as '''lsusb -vvv''' output) about the device.

== Hardware ==

* [http://www.latticesemi.com/products/cpld/machxo/index.cfm Lattice MachXO LCMXO2280 PLD]
* [http://www.intersil.com/products/deviceinfo.asp?pn=KAD2710C-10 Kenet KAD2710C-10 10bit, 105MSPS ADC]
* [http://www.silabs.com/products/interface/usbtouart/Pages/usb-to-uart-bridge.aspx Silabs CP2103 USB to UART Bridge]

== Original software ==

Link Instruments ships the product with its ''FrontPanelTM Oscilloscope software''. Software is for Windows only. Written in .NET (C#), without any kind of obfuscation, which makes it a real breeze to reverse engineer.

== USB protocol ==

It's just serial-over-USB, supported by the Linux kernel through the '''[http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/usb/serial/cp210x.c;hb=90a4c0f51e8e44111a926be6f4c87af3938a79c3 cp210x]''' driver, though as of Kernel 3.2.1 it needs to be patched to recognize the Link Instruments Vendor/Product ID ('''3195:f190''').

iSerial was exploited by Link Instruments to store hardware type, hardware revision, calibration quirks and the actual serial number.
*for an iSerial of 4294333650260000000 we have:
**42943 336 502 6 0 000000
***vbit = 42943 / 10000
***dacoffset = 336
***offsetrange = 502
***hwmodel = 6
***hwrev = 0
***serial number = 000000

== Serial protocol ==
*Control message
**Fixed header: 0x40, 0x4c, 0x44, 0x53, 0x7e
**Variable size payload, 16bit aligned
***Looks like each 16bits of payload are a register write operation
***register writes are 4bits for addr, 8 bits for value, 2 unused bits and 2 bits im not sure what they are for :)
**** The simplest explanation for the unused bits is that the device bus width is 7 bits (being a CPLD that is very acceptable).
**** The 2 special bits seem to be synchronization bits. 0x7e violates the conversion (high byte), and that may be used to reset the CPLD parser at the end of the packet.
***.?12 AAAA .?34 5678
***Conversion is: ((v & 0x3f) | ((v & 0xc0) << 6) | ((a & 0xf) << 8) | (((v ^ 0x20) & 0x20) << 1) | (((v ^ 0x80) & 0x80) << 7))
***Byte order is big endian
**Fixed footer: 0x7e

== Registers description ==
There is no way to read from registers, only write is possible.

The purpose of registers 0 to 13 seems to depend on the value of the 2 lsbs of register 15.

===== Registers for ((R15 & 0x3) == 0x0) =====

* Read Sample buffer (1): Write 0 to this register to read the samples buffer.
* Read Trigger status (2): Write 0 to this register to read the trigger status.
* TRIGGER_CONFIG_L (3):
** lsbyte of the threshold value.
* TRIGGER_CONFIG_H (4):
** bits [1:0] hold the msbits of the threshold value
** (1 << 2): Trigger on falling edge
** (1 << 4 | 1 << 3): Select the purpose of the "Output" connector:
*** 00 : Trigger pulse output
*** 01 : PWM DAC from the pattern generator buffer.
*** 10 : (?) never seen...
*** 11 : White noise
** (1 << 6 | 1 << 5): These hold the DSO/LA trigger configuration:
*** 00 : DSO level trigger
*** 01 : DSO pulse trigger, width less than TRIGGER_WIDTH
*** 10 : DSO pulse trigger, width equal or greater than TRIGGER_WIDTH
*** 11 : LA combination trigger
* LA_TRIGGER(5): The value of the LA byte that generates a trigger event (in that mode).
* LA_TRIGGER_MASK(6): The mask for the LA_TRIGGER (bits set to 0 matter, those set to 1 are ignored).
* SCOPE_TRIGGER_HOLDOFF1 (7):
* SCOPE_TRIGGER_HOLDOFF2 (8): Store the trigger holdoff (delay between a triggering event and the trigger rearming).
* CLKRATE(9-10):
* TRIGGER_WIDTH (11): Stores the pulse width for the DSO pulse trigger, in sample units. Forced to be greater than 3 by the mso19 app.
* DAC(12-13):

===== Registers for ((R15 & 0x3) == 0x1) =====

This mode seems to be used to configure the pattern generator.

* REG_PATGEN_CLOCK1 (2) :
* REG_PATGEN_CLOCK2 (3) : Stores the sample clock configuration. Not sure how these two bytes work together...
* REG_PATGEN_START_L (4):
* REG_PATGEN_START_H (5): The start address for the pattern generator buffer (1023 samples long). When writing to the buffer, it is set to 0.
* REG_PATGEN_END_L (6):
* REG_PATGEN_END_H (7): The end address for the pattern generator buffer (1023 samples long). When writing the buffer, it is set to 0x3ff. When in normal mode (to set the end of the output) it is writen as the end address minus 2 (probably due to the actual implementation details).
* PATGEN_CFG (8): Configures the pattern generator.
** (1 << 0): Continuous mode ? (only seems to be allowed for the waveform generator, not for the pattern generator. why?)
** (1 << 1): Enter pattern write mode.
** (1 << 3 | 1 << 2):
*** 11 : Manual start (starts after a pulse in PATGEN_TRIG)
*** 10 : Start on MSO trigger
*** 01 : Start on MSO "Go" (MSO trigger arm)
*** 00 : Disabled
* PATGEN_TRIG (9): writen 0x1 and then 0x0, acts as a manual trigger to activate "stuff".
* PATGEN_WORD (10): In pattern write mode, takes the word for the current "instant".
* PATGEN_IO (11): In pattern write mode, writing 0x1 makes the instant an output one, and writing 0x0 makes it an input one (?)
* PATGEN_LOOPS (12): Stores the number of loops for the pattern generator. Set to 1 for pattern buffer writing mode.
* PATTERN_MASK (13): Stores the output bit mask (1 for enabled bits, 0 for disabled bits)

===== Registers for ((R15 & 0x3) == 0x2) =====

This mode is used to set the i2c or spi triggers.
NOTES:
* the difference between i2c and spi capture seems to be the TRIGGER_CFG_H bits (see R15 = 0)
* how does the hardware handle the start/stop conditions or the ack bit??

The protocol matcher seems to be comprised of a 4 byte shift register. The serial bits are shifted in through the last byte comparator (word 3) and exit through the first byte comparator (word 0). This is why if the trigger is set up with less than 3 words, the first bytes are the ones that end up matching everything (word set to 0x00, mask set to 0xff).

The mask bytes have their bits set to 1 for "ignore", and 0 for "match". The protocol matching block simply doing something this for every bit i:

matches[i] = (read[i] ^ word[i]) | mask[i]

The final result is the and'ing of the resulting 32 bits.

* TRIG_WORD0 (0): Hold the comparison words for the comparator.
* TRIG_WORD1 (1):
* TRIG_WORD2 (2):
* TRIG_WORD2 (3):
* TRIG_MASK0 (4): Holds the mask for the comparator (bits set at 1 always produce a positive match)
* TRIG_MASK1 (5):
* TRIG_MASK2 (6):
* TRIG_MASK3 (7):
* TRIG_SPI_MODE (8): Holds the SPI mode for triggering (valid modes 0, 1, 2, 3). Is set to 0 for I2C (not sure if mandatory)

===== Registers which don't seem to change purpose (so far) =====

*CONTROL1 (14):
**(1 << 0): Reset SFM
**(1 << 3): Force trigger
**(1 << 4): Reset ADC (?)
**(1 << 6): Reset ADC (?)
**(1 << 7): Led on/off
*CONTROL2 (15):
** (1 << 1 | 1 << 0): Control which register bank is selected for writing:
*** 00: The DSO and LA control bank is selected
*** 01: The PG (patern generator) control bank is selected
*** 10: The PT (protocol trigger) control bank is selected
** (1 << 5): Slow mode (?) (set for the low clock rates, probably enables a clock divider)

== Device operation ==

The trigger status must be checked periodically, by writing 0 to the "Read Trigger Status" register (address 0 of bank 0). The returned value indicates the trigger (device?) status.

=== Startup ===

* The MSO19 application first checks for the trigger (device?) status upon startup, and accepts the values 0x21 or 0x31 as normal, before proceeding.
* The application then resets the ADC, and checks for the trigger (device?) status again, and also accepts the values 0x21 and 0x31 as normal.

=== Capture Start ===

* If the DSO or the DAC need to be configured, the app resets the FSM (finite state machine), and then configures them (both at the same time).
* If the PG needs to be configured, the app configures it.
* The app then arms the trigger system.
All is ready now.
* Finally the app issues a trigger check (writing 0 to the register).

=== Capture Loop ===

* Every time there's data on the serial port, it can only be sampled data (3072 bytes long) or the status data (1 byte long). The app checks which kind of serial data the device sent, and acts appropriately.

Link Instruments MSO-19

2012-01-20T00:34:45Z

Seventhguardian: /* Registers for ((R15 & 0x3) == 0x0) */

[[File:MSO-19.JPG|thumb|right|Link Instruments MSO-19]]
[[File:MSO-19-naked.jpg|thumb|right|PCB Front]]

The [http://www.linkinstruments.com/mso19.htm Link Instruments MSO-19] is a 2GSa/s oscilloscope, 200MSa/s logic analyzer, 100MSa/s pattern generator and a TDR. It is also extremely portable and is only $249 (including probe, clips, wires and software).

See [[Link Instruments MSO-19/Info]] for more details (such as '''lsusb -vvv''' output) about the device.

== Hardware ==

* [http://www.latticesemi.com/products/cpld/machxo/index.cfm Lattice MachXO LCMXO2280 PLD]
* [http://www.intersil.com/products/deviceinfo.asp?pn=KAD2710C-10 Kenet KAD2710C-10 10bit, 105MSPS ADC]
* [http://www.silabs.com/products/interface/usbtouart/Pages/usb-to-uart-bridge.aspx Silabs CP2103 USB to UART Bridge]

== Original software ==

Link Instruments ships the product with its ''FrontPanelTM Oscilloscope software''. Software is for Windows only. Written in .NET (C#), without any kind of obfuscation, which makes it a real breeze to reverse engineer.

== USB protocol ==

It's just serial-over-USB, supported by the Linux kernel through the '''[http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/usb/serial/cp210x.c;hb=90a4c0f51e8e44111a926be6f4c87af3938a79c3 cp210x]''' driver, though as of Kernel 3.2.1 it needs to be patched to recognize the Link Instruments Vendor/Product ID ('''3195:f190''').

iSerial was exploited by Link Instruments to store hardware type, hardware revision, calibration quirks and the actual serial number.
*for an iSerial of 4294333650260000000 we have:
**42943 336 502 6 0 000000
***vbit = 42943 / 10000
***dacoffset = 336
***offsetrange = 502
***hwmodel = 6
***hwrev = 0
***serial number = 000000

== Serial protocol ==
*Control message
**Fixed header: 0x40, 0x4c, 0x44, 0x53, 0x7e
**Variable size payload, 16bit aligned
***Looks like each 16bits of payload are a register write operation
***register writes are 4bits for addr, 8 bits for value, 2 unused bits and 2 bits im not sure what they are for :)
**** The simplest explanation for the unused bits is that the device bus width is 7 bits (being a CPLD that is very acceptable).
**** The 2 special bits seem to be synchronization bits. 0x7e violates the conversion (high byte), and that may be used to reset the CPLD parser at the end of the packet.
***.?12 AAAA .?34 5678
***Conversion is: ((v & 0x3f) | ((v & 0xc0) << 6) | ((a & 0xf) << 8) | (((v ^ 0x20) & 0x20) << 1) | (((v ^ 0x80) & 0x80) << 7))
***Byte order is big endian
**Fixed footer: 0x7e

== Registers description ==
There is no way to read from registers, only write is possible.

The purpose of registers 0 to 13 seems to depend on the value of the 2 lsbs of register 15.

===== Registers for ((R15 & 0x3) == 0x0) =====

* Read Sample buffer (1): Write 0 to this register to read the samples buffer.
* Read Trigger status (2): Write 0 to this register to read the trigger status.
* TRIGGER_CONFIG_L (3):
** lsbyte of the threshold value.
* TRIGGER_CONFIG_H (4):
** bits [1:0] hold the msbits of the threshold value
** (1 << 2): Trigger on falling edge
** (1 << 4 | 1 << 3): Select the purpose of the "Output" connector:
*** 00 : Trigger pulse output
*** 01 : PWM DAC from the pattern generator buffer.
*** 10 : (?) never seen...
*** 11 : White noise
** (1 << 6 | 1 << 5): These hold the DSO/LA trigger configuration:
*** 00 : DSO level trigger
*** 01 : DSO pulse trigger, width less than TRIGGER_WIDTH
*** 10 : DSO pulse trigger, width equal or greater than TRIGGER_WIDTH
*** 11 : LA combination trigger
* LA_TRIGGER(5): The value of the LA byte that generates a trigger event (in that mode).
* LA_TRIGGER_MASK(6): The mask for the LA_TRIGGER (bits set to 0 matter, those set to 1 are ignored).
* SCOPE_TRIGGER_HOLDOFF1 (7):
* SCOPE_TRIGGER_HOLDOFF2 (8): Store the trigger holdoff (delay between a triggering event and the trigger rearming).
* CLKRATE(9-10):
* TRIGGER_WIDTH (11): Stores the pulse width for the DSO pulse trigger, in sample units. Forced to be greater than 3 by the mso19 app.
* DAC(12-13):

===== Registers for ((R15 & 0x3) == 0x1) =====

This mode seems to be used to configure the pattern generator.

* REG_PATGEN_CLOCK1 (2) :
* REG_PATGEN_CLOCK2 (3) : Stores the sample clock configuration. Not sure how these two bytes work together...
* REG_PATGEN_START_L (4):
* REG_PATGEN_START_H (5): The start address for the pattern generator buffer (1023 samples long). When writing to the buffer, it is set to 0.
* REG_PATGEN_END_L (6):
* REG_PATGEN_END_H (7): The end address for the pattern generator buffer (1023 samples long). When writing the buffer, it is set to 0x3ff. When in normal mode (to set the end of the output) it is writen as the end address minus 2 (probably due to the actual implementation details).
* PATGEN_CFG (8): Configures the pattern generator.
** (1 << 0): Continuous mode ? (only seems to be allowed for the waveform generator, not for the pattern generator. why?)
** (1 << 1): Enter pattern write mode.
** (1 << 3 | 1 << 2):
*** 11 : Manual start (starts after a pulse in PATGEN_TRIG)
*** 10 : Start on MSO trigger
*** 01 : Start on MSO "Go" (MSO trigger arm)
*** 00 : Disabled
* PATGEN_TRIG (9): writen 0x1 and then 0x0, acts as a manual trigger to activate "stuff".
* PATGEN_WORD (10): In pattern write mode, takes the word for the current "instant".
* PATGEN_IO (11): In pattern write mode, writing 0x1 makes the instant an output one, and writing 0x0 makes it an input one (?)
* PATGEN_LOOPS (12): Stores the number of loops for the pattern generator. Set to 1 for pattern buffer writing mode.
* PATTERN_MASK (13): Stores the output bit mask (1 for enabled bits, 0 for disabled bits)

===== Registers for ((R15 & 0x3) == 0x2) =====

This mode is used to set the i2c or spi triggers.
NOTES:
* the difference between i2c and spi capture seems to be the TRIGGER_CFG_H bits (see R15 = 0)
* how does the hardware handle the start/stop conditions or the ack bit??

The protocol matcher seems to be comprised of a 4 byte shift register. The serial bits are shifted in through the last byte comparator (word 3) and exit through the first byte comparator (word 0). This is why if the trigger is set up with less than 3 words, the first bytes are the ones that end up matching everything (word set to 0x00, mask set to 0xff).

The mask bytes have their bits set to 1 for "ignore", and 0 for "match". The protocol matching block simply doing something this for every bit i:

matches[i] = (read[i] ^ word[i]) | mask[i]

The final result is the and'ing of the resulting 32 bits.

* TRIG_WORD0 (0): Hold the comparison words for the comparator.
* TRIG_WORD1 (1):
* TRIG_WORD2 (2):
* TRIG_WORD2 (3):
* TRIG_MASK0 (4): Holds the mask for the comparator (bits set at 1 always produce a positive match)
* TRIG_MASK1 (5):
* TRIG_MASK2 (6):
* TRIG_MASK3 (7):
* TRIG_SPI_MODE (8): Holds the SPI mode for triggering (valid modes 0, 1, 2, 3). Is set to 0 for I2C (not sure if mandatory)

===== Registers which don't seem to change purpose (so far) =====

*CONTROL1 (14):
**(1 << 0): Reset SFM
**(1 << 3): Force trigger
**(1 << 4): Reset ADC (?)
**(1 << 6): Reset ADC (?)
**(1 << 7): Led on/off
*CONTROL2 (15):
** (1 << 1 | 1 << 0): Control which register bank is selected for writing:
*** 00: The DSO and LA control bank is selected
*** 01: The PG (patern generator) control bank is selected
*** 10: The PT (protocol trigger) control bank is selected
** (1 << 5): Slow mode (?) (set for the low clock rates, probably enables a clock divider)

Link Instruments MSO-19

2012-01-20T00:21:36Z

Seventhguardian: /* Registers for ((R15 & 0x3) == 0x1) */

[[File:MSO-19.JPG|thumb|right|Link Instruments MSO-19]]
[[File:MSO-19-naked.jpg|thumb|right|PCB Front]]

The [http://www.linkinstruments.com/mso19.htm Link Instruments MSO-19] is a 2GSa/s oscilloscope, 200MSa/s logic analyzer, 100MSa/s pattern generator and a TDR. It is also extremely portable and is only $249 (including probe, clips, wires and software).

See [[Link Instruments MSO-19/Info]] for more details (such as '''lsusb -vvv''' output) about the device.

== Hardware ==

* [http://www.latticesemi.com/products/cpld/machxo/index.cfm Lattice MachXO LCMXO2280 PLD]
* [http://www.intersil.com/products/deviceinfo.asp?pn=KAD2710C-10 Kenet KAD2710C-10 10bit, 105MSPS ADC]
* [http://www.silabs.com/products/interface/usbtouart/Pages/usb-to-uart-bridge.aspx Silabs CP2103 USB to UART Bridge]

== Original software ==

Link Instruments ships the product with its ''FrontPanelTM Oscilloscope software''. Software is for Windows only. Written in .NET (C#), without any kind of obfuscation, which makes it a real breeze to reverse engineer.

== USB protocol ==

It's just serial-over-USB, supported by the Linux kernel through the '''[http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/usb/serial/cp210x.c;hb=90a4c0f51e8e44111a926be6f4c87af3938a79c3 cp210x]''' driver, though as of Kernel 3.2.1 it needs to be patched to recognize the Link Instruments Vendor/Product ID ('''3195:f190''').

iSerial was exploited by Link Instruments to store hardware type, hardware revision, calibration quirks and the actual serial number.
*for an iSerial of 4294333650260000000 we have:
**42943 336 502 6 0 000000
***vbit = 42943 / 10000
***dacoffset = 336
***offsetrange = 502
***hwmodel = 6
***hwrev = 0
***serial number = 000000

== Serial protocol ==
*Control message
**Fixed header: 0x40, 0x4c, 0x44, 0x53, 0x7e
**Variable size payload, 16bit aligned
***Looks like each 16bits of payload are a register write operation
***register writes are 4bits for addr, 8 bits for value, 2 unused bits and 2 bits im not sure what they are for :)
**** The simplest explanation for the unused bits is that the device bus width is 7 bits (being a CPLD that is very acceptable).
**** The 2 special bits seem to be synchronization bits. 0x7e violates the conversion (high byte), and that may be used to reset the CPLD parser at the end of the packet.
***.?12 AAAA .?34 5678
***Conversion is: ((v & 0x3f) | ((v & 0xc0) << 6) | ((a & 0xf) << 8) | (((v ^ 0x20) & 0x20) << 1) | (((v ^ 0x80) & 0x80) << 7))
***Byte order is big endian
**Fixed footer: 0x7e

== Registers description ==
There is no way to read from registers, only write is possible.

The purpose of registers 0 to 13 seems to depend on the value of the 2 lsbs of register 15.

===== Registers for ((R15 & 0x3) == 0x0) =====

* Read Sample buffer (1): Write 0 to this register to read the samples buffer.
* Read Trigger status (2): Write 0 to this register to read the trigger status.
* TRIGGER_CONFIG_L (3):
** lsbyte of the threshold value.
* TRIGGER_CONFIG_H (4):
** bits [1:0] hold the msbits of the threshold value
** (1 << 2): Trigger on falling edge
** (1 << 6 | 1 << 5): These hold the DSO/LA trigger configuration:
*** 00 : DSO level trigger
*** 01 : DSO pulse trigger, width less than TRIGGER_WIDTH
*** 10 : DSO pulse trigger, width equal or greater than TRIGGER_WIDTH
*** 11 : LA combination trigger
* LA_TRIGGER(5): The value of the LA byte that generates a trigger event (in that mode).
* LA_TRIGGER_MASK(6): The mask for the LA_TRIGGER (bits set to 0 matter, those set to 1 are ignored).
* SCOPE_TRIGGER_HOLDOFF1 (7):
* SCOPE_TRIGGER_HOLDOFF2 (8): Store the trigger holdoff (delay between a triggering event and the trigger rearming).
* CLKRATE(9-10):
* TRIGGER_WIDTH (11): Stores the pulse width for the DSO pulse trigger, in sample units. Forced to be greater than 3 by the mso19 app.
* DAC(12-13):

===== Registers for ((R15 & 0x3) == 0x1) =====

This mode seems to be used to configure the pattern generator.

* REG_PATGEN_CLOCK1 (2) :
* REG_PATGEN_CLOCK2 (3) : Stores the sample clock configuration. Not sure how these two bytes work together...
* REG_PATGEN_START_L (4):
* REG_PATGEN_START_H (5): The start address for the pattern generator buffer (1023 samples long). When writing to the buffer, it is set to 0.
* REG_PATGEN_END_L (6):
* REG_PATGEN_END_H (7): The end address for the pattern generator buffer (1023 samples long). When writing the buffer, it is set to 0x3ff. When in normal mode (to set the end of the output) it is writen as the end address minus 2 (probably due to the actual implementation details).
* PATGEN_CFG (8): Configures the pattern generator.
** (1 << 0): Continuous mode ? (only seems to be allowed for the waveform generator, not for the pattern generator. why?)
** (1 << 1): Enter pattern write mode.
** (1 << 3 | 1 << 2):
*** 11 : Manual start (starts after a pulse in PATGEN_TRIG)
*** 10 : Start on MSO trigger
*** 01 : Start on MSO "Go" (MSO trigger arm)
*** 00 : Disabled
* PATGEN_TRIG (9): writen 0x1 and then 0x0, acts as a manual trigger to activate "stuff".
* PATGEN_WORD (10): In pattern write mode, takes the word for the current "instant".
* PATGEN_IO (11): In pattern write mode, writing 0x1 makes the instant an output one, and writing 0x0 makes it an input one (?)
* PATGEN_LOOPS (12): Stores the number of loops for the pattern generator. Set to 1 for pattern buffer writing mode.
* PATTERN_MASK (13): Stores the output bit mask (1 for enabled bits, 0 for disabled bits)

===== Registers for ((R15 & 0x3) == 0x2) =====

This mode is used to set the i2c or spi triggers.
NOTES:
* the difference between i2c and spi capture seems to be the TRIGGER_CFG_H bits (see R15 = 0)
* how does the hardware handle the start/stop conditions or the ack bit??

The protocol matcher seems to be comprised of a 4 byte shift register. The serial bits are shifted in through the last byte comparator (word 3) and exit through the first byte comparator (word 0). This is why if the trigger is set up with less than 3 words, the first bytes are the ones that end up matching everything (word set to 0x00, mask set to 0xff).

The mask bytes have their bits set to 1 for "ignore", and 0 for "match". The protocol matching block simply doing something this for every bit i:

matches[i] = (read[i] ^ word[i]) | mask[i]

The final result is the and'ing of the resulting 32 bits.

* TRIG_WORD0 (0): Hold the comparison words for the comparator.
* TRIG_WORD1 (1):
* TRIG_WORD2 (2):
* TRIG_WORD2 (3):
* TRIG_MASK0 (4): Holds the mask for the comparator (bits set at 1 always produce a positive match)
* TRIG_MASK1 (5):
* TRIG_MASK2 (6):
* TRIG_MASK3 (7):
* TRIG_SPI_MODE (8): Holds the SPI mode for triggering (valid modes 0, 1, 2, 3). Is set to 0 for I2C (not sure if mandatory)

===== Registers which don't seem to change purpose (so far) =====

*CONTROL1 (14):
**(1 << 0): Reset SFM
**(1 << 3): Force trigger
**(1 << 4): Reset ADC (?)
**(1 << 6): Reset ADC (?)
**(1 << 7): Led on/off
*CONTROL2 (15):
** (1 << 1 | 1 << 0): Control which register bank is selected for writing:
*** 00: The DSO and LA control bank is selected
*** 01: The PG (patern generator) control bank is selected
*** 10: The PT (protocol trigger) control bank is selected
** (1 << 5): Slow mode (?) (set for the low clock rates, probably enables a clock divider)

Link Instruments MSO-19

2012-01-19T23:16:53Z

Seventhguardian: /* Registers which don't seem to change purpose (so far) */

Link Instruments MSO-19

2012-01-19T23:04:17Z

Seventhguardian: /* Registers which don't seem to change purpose (so far) */

Link Instruments MSO-19

2012-01-19T22:59:56Z

Seventhguardian: /* Registers for ((R15 & 0x3) == 0x0) */

Link Instruments MSO-19

2012-01-19T10:11:59Z

Seventhguardian: /* USB protocol */

Link Instruments MSO-19

2012-01-19T10:11:13Z

Seventhguardian: /* USB protocol */

Link Instruments MSO-19

2012-01-19T10:06:19Z

Seventhguardian: /* Registers description */

Link Instruments MSO-19

2012-01-18T00:05:10Z

Seventhguardian: /* Registers for R15 == 2 */

Link Instruments MSO-19

2012-01-17T23:39:35Z

Seventhguardian: /* Registers for R15 == 2 */

Link Instruments MSO-19

2012-01-14T11:44:04Z

Seventhguardian: /* Registers for R15 == 1 */

Link Instruments MSO-19

2012-01-14T01:50:03Z

Seventhguardian: /* Registers for R15 == 1 */

Link Instruments MSO-19

2012-01-14T01:46:20Z

Seventhguardian: /* Registers for R15 == 0 */

Link Instruments MSO-19

2012-01-14T01:29:09Z

Seventhguardian: /* Registers for R15 == 1 */

Link Instruments MSO-19

2012-01-14T01:27:57Z

Seventhguardian: /* Registers for R15 == 0 */

Link Instruments MSO-19

2012-01-14T01:25:55Z

Seventhguardian: /* Registers for R15 == 2 */

Link Instruments MSO-19

2012-01-14T01:24:55Z

Seventhguardian: /* Registers for R15 == 1 */

Link Instruments MSO-19

2012-01-13T14:34:42Z

Seventhguardian: /* Registers for R15 == 1 */

Link Instruments MSO-19

2012-01-13T14:33:38Z

Seventhguardian: /* Registers for R15 == 0 */

Link Instruments MSO-19

2012-01-13T14:30:37Z

Seventhguardian: /* Registers for R15 == 0 */

Link Instruments MSO-19

2012-01-13T14:25:47Z

Seventhguardian: /* Registers for R15 == 1 */

Link Instruments MSO-19

2012-01-13T14:14:46Z

Seventhguardian: /* Registers for R15 == 1 */

Link Instruments MSO-19

2012-01-13T14:03:22Z

Seventhguardian: /* Registers description */

Link Instruments MSO-19

2012-01-13T00:31:09Z

Seventhguardian: /* Registers for R15 == 2 */

Link Instruments MSO-19

2012-01-13T00:15:44Z

Seventhguardian: /* Registers description */

Link Instruments MSO-19

2012-01-12T23:15:38Z

Seventhguardian: /* Registers description */

Link Instruments MSO-19

2012-01-12T22:42:41Z

Seventhguardian: /* Serial protocol */

Link Instruments MSO-19

2012-01-12T22:31:00Z

Seventhguardian: /* Registers description */

Link Instruments MSO-19

2012-01-12T19:18:07Z

Seventhguardian: /* Registers description */

Hardware driver API

2012-01-05T15:43:23Z

Seventhguardian: Fixed typo

Every plugin is built as a shared library, dynamically loaded by the backend at startup. The plugin must define a structure as follows:

#include "sigrok.h"

struct sr_device_plugin {
/* plugin-specific */
char *name;
char *longname;
int api_version;
int (*init) (const char *deviceinfo);
void (*cleanup) (void);

/* device-specific */
int (*opendev) (int device_index);
int (*closedev) (int device_index);
void *(*get_device_info) (int device_index, int device_info_id);
int (*get_status) (int device_index);
int *(*get_capabilities) (void);
int (*set_configuration) (int device_index, int capability, char *value);
int (*start_acquisition) (int device_index, gpointer session_device_id);
void (*stop_acquisition) (int device_index, gpointer session_device_id);
};

#define SIGROK_HARDWARE_PLUGIN struct device_plugin plugin_info

This structure is the only symbol imported into the backend namespace. The plugin's variables thus cannot conflict with the global sigrok namespace.

* '''name''' A short string describing this driver. It will be referenced in saved session files.

* '''longname''' A long string describing this driver. It will be shown to the user.

* '''api_version''' Currently defined as 1.

The other members of the structure are pointers to plugin callbacks:

* '''init(const char *deviceinfo)''' Called when the plugin is initially loading into sigrok, typically at program start. The parameter refers to a device name or special file, whichever is applicable for the plugin. Devices which don't need a supplied device, such as USB devices, can simply ignore this parameter. The function returns the number of devices found, and 0 if no suitable device was found. If a device was found, any initialization it needs must be performed here; for example, uploading firmware should be done here.

* '''cleanup()''' Called before the plugin is unloaded. Release any resources the plugin might be holding.

* '''opendev(int device_index)''' Open the specified device. The device index starts at 0. Returns SR_OK if successful, SR_ERR otherwise.

* '''closedev(int device_index)''' Close the specified device. The device index starts at 0. Returns SR_OK if successful, SR_ERR otherwise.

* '''get_device_info(int device_index, int device_info_id)''' Returns information about the given device. The type of information is given as device_info_id, one of a set of defined constants. The return value is always a pointer, which points to information specific to the id.
** SR_DI_INSTANCE: Returns a pointer to a [[Formats_and_structures#device_instances|struct sigrok_device_instance]].
** SR_DI_NUM_PROBES: The number of probes connected to this device (integer).
** SR_DI_PROBE_NAMES: The probe names on this device (array of char*).
** SR_DI_SAMPLERATES: Returns a pointer to a [[Formats_and_structures#Sample_rates|struct samplerates]].
** SR_DI_TRIGGER_TYPES: Types of trigger supported, out of "01crf" (char *).
** SR_DI_CUR_SAMPLERATE: The currently set samplerate in Hz (uint64_t).
** SR_DI_PATTERNMODES: Supported pattern generator modes (array of char*).

* '''get_status(int device_index)''' Returns an integer describing the status of the plugin's connection to a device. This may be one of the following:
** SR_ST_NOT_FOUND: The device was not found.
** SR_ST_INITIALIZING: The device was found, but is still initializing.
** SR_ST_INACTIVE: The device is live, but not in use.
** SR_ST_ACTIVE: The device is currently in use.

* '''get_capabilities()''' This function returns a zero-terminated integer array with the plugin's capabilities, in the form of a set of defined constants. Some of these are informative, and some can be used to configure the plugin (or its connected device). The capabilities tables below have an overview of all possible capabilities.

* '''set_configuration(int device_index, int capability, char *value)''' This is used to configure the plugin and/or connected device. The capability is one of the constants returned from the get_capabilities() call. The value depends on the parameter that is to be configured.

* '''start_acquisition(int device_index, gpointer session_device_id)''' Start acquisition on the specified device. The session_device_id will be passed along with the data feed of this session, as the first parameter to session bus callbacks.

* '''stop_acquisition(int device_index, gpointer session_device_id)''' Stop acquisition on the specified device. This causes a DF_END packet to be sent to the sesion bus.

== Device classes ==

* HWCAP_LOGIC_ANALYZER
: This device is a logic analyzer.

== Device options ==

* HWCAP_SAMPLERATE
: The sample rate in Hz (uint64_t *).
* HWCAP_PROBECONFIG
: Probe configuration (GSList *probes)
* HWCAP_CAPTURE_RATIO
: Pre-trigger capture ratio, as a percentage of the number of samples returned. The default is 0, meaning capturing only starts after the trigger fired (uint64_t *).
* HWCAP_PATTERN_MODE
: Pattern to generate (char **).

== Acquisition modes ==

* HWCAP_LIMIT_MSEC
: How long the acquisition should last, in ms (uint64_t).
* HWCAP_LIMIT_SAMPLES
: How many samples to acquire in the session (uint64_t).
* HWCAP_CONTINUOUS
: Device supports continuous sampling

Hardware driver API

2012-01-05T15:41:33Z

Seventhguardian: Fixed status prefix

Every plugin is built as a shared library, dynamically loaded by the backend at startup. The plugin must define a structure as follows:

#include "sigrok.h"

struct sr_device_plugin {
/* plugin-specific */
char *name;
char *longname;
int api_version;
int (*init) (const char *deviceinfo);
void (*cleanup) (void);

/* device-specific */
int (*opendev) (int device_index);
int (*closedev) (int device_index);
void *(*get_device_info) (int device_index, int device_info_id);
int (*get_status) (int device_index);
int *(*get_capabilities) (void);
int (*set_configuration) (int device_index, int capability, char *value);
int (*start_acquisition) (int device_index, gpointer session_device_id);
void (*stop_acquisition) (int device_index, gpointer session_device_id);
};

#define SIGROK_HARDWARE_PLUGIN struct device_plugin plugin_info

This structure is the only symbol imported into the backend namespace. The plugin's variables thus cannot conflict with the global sigrok namespace.

* '''name''' A short string describing this driver. It will be referenced in saved session files.

* '''longname''' A long string describing this driver. It will be shown to the user.

* '''api_version''' Currently defined as 1.

The other members of the structure are pointers to plugin callbacks:

* '''init(const char *deviceinfo)''' Called when the plugin is initially loading into sigrok, typically at program start. The parameter refers to a device name or special file, whichever is applicable for the plugin. Devices which don't need a supplied device, such as USB devices, can simply ignore this parameter. The function returns the number of devices found, and 0 if no suitable device was found. If a device was found, any initialization it needs must be performed here; for example, uploading firmware should be done here.

* '''cleanup()''' Called before the plugin is unloaded. Release any resources the plugin might be holding.

* '''opendev(int device_index)''' Open the specified device. The device index starts at 0. Returns SR_OK if successful, SR_ERR otherwise.

* '''closedev(int device_index)''' Close the specified device. The device index starts at 0. Returns SR_OK if successful, SR_ERR otherwise.

* '''get_device_info(int device_index, int device_info_id)''' Returns information about the given device. The type of information is given as device_info_id, one of a set of defined constants. The return value is always a pointer, which points to information specific to the id.
** SR_DI_INSTANCE: Returns a pointer to a [[Formats_and_structures#device_instances|struct sigrok_device_instance]].
** SR_DI_NUM_PROBES: The number of probes connected to this device (integer).
** SR_DI_PROBE_NAMES: The probe names on this device (array of char*).
** SR_DI_SAMPLERATES: Returns a pointer to a [[Formats_and_structures#Sample_rates|struct samplerates]].
** SR_DI_TRIGGER_TYPES: Types of trigger supported, out of "01crf" (char *).
** SR_DI_CUR_SAMPLERATE: The currently set samplerate in Hz (uint64_t).
** SR_DI_PATTERNMODES: Supported pattern generator modes (array ov char*).

* '''get_status(int device_index)''' Returns an integer describing the status of the plugin's connection to a device. This may be one of the following:
** SR_ST_NOT_FOUND: The device was not found.
** SR_ST_INITIALIZING: The device was found, but is still initializing.
** SR_ST_INACTIVE: The device is live, but not in use.
** SR_ST_ACTIVE: The device is currently in use.

* '''get_capabilities()''' This function returns a zero-terminated integer array with the plugin's capabilities, in the form of a set of defined constants. Some of these are informative, and some can be used to configure the plugin (or its connected device). The capabilities tables below have an overview of all possible capabilities.

* '''set_configuration(int device_index, int capability, char *value)''' This is used to configure the plugin and/or connected device. The capability is one of the constants returned from the get_capabilities() call. The value depends on the parameter that is to be configured.

* '''start_acquisition(int device_index, gpointer session_device_id)''' Start acquisition on the specified device. The session_device_id will be passed along with the data feed of this session, as the first parameter to session bus callbacks.

* '''stop_acquisition(int device_index, gpointer session_device_id)''' Stop acquisition on the specified device. This causes a DF_END packet to be sent to the sesion bus.

== Device classes ==

* HWCAP_LOGIC_ANALYZER
: This device is a logic analyzer.

== Device options ==

* HWCAP_SAMPLERATE
: The sample rate in Hz (uint64_t *).
* HWCAP_PROBECONFIG
: Probe configuration (GSList *probes)
* HWCAP_CAPTURE_RATIO
: Pre-trigger capture ratio, as a percentage of the number of samples returned. The default is 0, meaning capturing only starts after the trigger fired (uint64_t *).
* HWCAP_PATTERN_MODE
: Pattern to generate (char **).

== Acquisition modes ==

* HWCAP_LIMIT_MSEC
: How long the acquisition should last, in ms (uint64_t).
* HWCAP_LIMIT_SAMPLES
: How many samples to acquire in the session (uint64_t).
* HWCAP_CONTINUOUS
: Device supports continuous sampling

Hardware driver API

2012-01-05T15:38:16Z

Seventhguardian: Updated get_device_info

Every plugin is built as a shared library, dynamically loaded by the backend at startup. The plugin must define a structure as follows:

#include "sigrok.h"

struct sr_device_plugin {
/* plugin-specific */
char *name;
char *longname;
int api_version;
int (*init) (const char *deviceinfo);
void (*cleanup) (void);

/* device-specific */
int (*opendev) (int device_index);
int (*closedev) (int device_index);
void *(*get_device_info) (int device_index, int device_info_id);
int (*get_status) (int device_index);
int *(*get_capabilities) (void);
int (*set_configuration) (int device_index, int capability, char *value);
int (*start_acquisition) (int device_index, gpointer session_device_id);
void (*stop_acquisition) (int device_index, gpointer session_device_id);
};

#define SIGROK_HARDWARE_PLUGIN struct device_plugin plugin_info

This structure is the only symbol imported into the backend namespace. The plugin's variables thus cannot conflict with the global sigrok namespace.

* '''name''' A short string describing this driver. It will be referenced in saved session files.

* '''longname''' A long string describing this driver. It will be shown to the user.

* '''api_version''' Currently defined as 1.

The other members of the structure are pointers to plugin callbacks:

* '''init(const char *deviceinfo)''' Called when the plugin is initially loading into sigrok, typically at program start. The parameter refers to a device name or special file, whichever is applicable for the plugin. Devices which don't need a supplied device, such as USB devices, can simply ignore this parameter. The function returns the number of devices found, and 0 if no suitable device was found. If a device was found, any initialization it needs must be performed here; for example, uploading firmware should be done here.

* '''cleanup()''' Called before the plugin is unloaded. Release any resources the plugin might be holding.

* '''opendev(int device_index)''' Open the specified device. The device index starts at 0. Returns SR_OK if successful, SR_ERR otherwise.

* '''closedev(int device_index)''' Close the specified device. The device index starts at 0. Returns SR_OK if successful, SR_ERR otherwise.

* '''get_device_info(int device_index, int device_info_id)''' Returns information about the given device. The type of information is given as device_info_id, one of a set of defined constants. The return value is always a pointer, which points to information specific to the id.
** SR_DI_INSTANCE: Returns a pointer to a [[Formats_and_structures#device_instances|struct sigrok_device_instance]].
** SR_DI_NUM_PROBES: The number of probes connected to this device (integer).
** SR_DI_PROBE_NAMES: The probe names on this device (array of char*).
** SR_DI_SAMPLERATES: Returns a pointer to a [[Formats_and_structures#Sample_rates|struct samplerates]].
** SR_DI_TRIGGER_TYPES: Types of trigger supported, out of "01crf" (char *).
** SR_DI_CUR_SAMPLERATE: The currently set samplerate in Hz (uint64_t).
** SR_DI_PATTERNMODES: Supported pattern generator modes (array ov char*).

* '''get_status(int device_index)''' Returns an integer describing the status of the plugin's connection to a device. This may be one of the following:
** ST_NOT_FOUND: The device was not found.
** ST_INITIALIZING: The device was found, but is still initializing.
** ST_INACTIVE: The device is live, but not in use.
** ST_ACTIVE: The device is currently in use.

* '''get_capabilities()''' This function returns a zero-terminated integer array with the plugin's capabilities, in the form of a set of defined constants. Some of these are informative, and some can be used to configure the plugin (or its connected device). The capabilities tables below have an overview of all possible capabilities.

* '''set_configuration(int device_index, int capability, char *value)''' This is used to configure the plugin and/or connected device. The capability is one of the constants returned from the get_capabilities() call. The value depends on the parameter that is to be configured.

* '''start_acquisition(int device_index, gpointer session_device_id)''' Start acquisition on the specified device. The session_device_id will be passed along with the data feed of this session, as the first parameter to session bus callbacks.

* '''stop_acquisition(int device_index, gpointer session_device_id)''' Stop acquisition on the specified device. This causes a DF_END packet to be sent to the sesion bus.

== Device classes ==

* HWCAP_LOGIC_ANALYZER
: This device is a logic analyzer.

== Device options ==

* HWCAP_SAMPLERATE
: The sample rate in Hz (uint64_t *).
* HWCAP_PROBECONFIG
: Probe configuration (GSList *probes)
* HWCAP_CAPTURE_RATIO
: Pre-trigger capture ratio, as a percentage of the number of samples returned. The default is 0, meaning capturing only starts after the trigger fired (uint64_t *).
* HWCAP_PATTERN_MODE
: Pattern to generate (char **).

== Acquisition modes ==

* HWCAP_LIMIT_MSEC
: How long the acquisition should last, in ms (uint64_t).
* HWCAP_LIMIT_SAMPLES
: How many samples to acquire in the session (uint64_t).
* HWCAP_CONTINUOUS
: Device supports continuous sampling

Hardware driver API

2012-01-05T15:25:10Z

Seventhguardian: Updated opendev/closedev

Every plugin is built as a shared library, dynamically loaded by the backend at startup. The plugin must define a structure as follows:

#include "sigrok.h"

struct sr_device_plugin {
/* plugin-specific */
char *name;
char *longname;
int api_version;
int (*init) (const char *deviceinfo);
void (*cleanup) (void);

/* device-specific */
int (*opendev) (int device_index);
int (*closedev) (int device_index);
char *(*get_device_info) (int device_index, int device_info_id);
int (*get_status) (int device_index);
int *(*get_capabilities) (void);
int (*set_configuration) (int device_index, int capability, char *value);
int (*start_acquisition) (int device_index, gpointer session_device_id);
void (*stop_acquisition) (int device_index, gpointer session_device_id);
};

#define SIGROK_HARDWARE_PLUGIN struct device_plugin plugin_info

This structure is the only symbol imported into the backend namespace. The plugin's variables thus cannot conflict with the global sigrok namespace.

* '''name''' A short string describing this driver. It will be referenced in saved session files.

* '''longname''' A long string describing this driver. It will be shown to the user.

* '''api_version''' Currently defined as 1.

The other members of the structure are pointers to plugin callbacks:

* '''init(const char *deviceinfo)''' Called when the plugin is initially loading into sigrok, typically at program start. The parameter refers to a device name or special file, whichever is applicable for the plugin. Devices which don't need a supplied device, such as USB devices, can simply ignore this parameter. The function returns the number of devices found, and 0 if no suitable device was found. If a device was found, any initialization it needs must be performed here; for example, uploading firmware should be done here.

* '''cleanup()''' Called before the plugin is unloaded. Release any resources the plugin might be holding.

* '''opendev(int device_index)''' Open the specified device. The device index starts at 0. Returns SR_OK if successful, SR_ERR otherwise.

* '''closedev(int device_index)''' Close the specified device. The device index starts at 0. Returns SR_OK if successful, SR_ERR otherwise.

* '''get_device_info(int device_index, int device_info_id)''' Returns information about the given device. The type of information is given as device_info_id, one of a set of defined constants. The return value is always a pointer, which points to information specific to the id.
** DI_INSTANCE: Returns a pointer to a [[Formats_and_structures#device_instances|struct sigrok_device_instance]].
** DI_NUM_PROBES: The number of probes connected to this device (integer).
** DI_SAMPLERATES: Returns a pointer to a [[Formats_and_structures#Sample_rates|struct samplerates]].

* '''get_status(int device_index)''' Returns an integer describing the status of the plugin's connection to a device. This may be one of the following:
** ST_NOT_FOUND: The device was not found.
** ST_INITIALIZING: The device was found, but is still initializing.
** ST_INACTIVE: The device is live, but not in use.
** ST_ACTIVE: The device is currently in use.

* '''get_capabilities()''' This function returns a zero-terminated integer array with the plugin's capabilities, in the form of a set of defined constants. Some of these are informative, and some can be used to configure the plugin (or its connected device). The capabilities tables below have an overview of all possible capabilities.

* '''set_configuration(int device_index, int capability, char *value)''' This is used to configure the plugin and/or connected device. The capability is one of the constants returned from the get_capabilities() call. The value depends on the parameter that is to be configured.

* '''start_acquisition(int device_index, gpointer session_device_id)''' Start acquisition on the specified device. The session_device_id will be passed along with the data feed of this session, as the first parameter to session bus callbacks.

* '''stop_acquisition(int device_index, gpointer session_device_id)''' Stop acquisition on the specified device. This causes a DF_END packet to be sent to the sesion bus.

== Device classes ==

* HWCAP_LOGIC_ANALYZER
: This device is a logic analyzer.

== Device options ==

* HWCAP_SAMPLERATE
: The sample rate in Hz (uint64_t *).
* HWCAP_PROBECONFIG
: Probe configuration (GSList *probes)
* HWCAP_CAPTURE_RATIO
: Pre-trigger capture ratio, as a percentage of the number of samples returned. The default is 0, meaning capturing only starts after the trigger fired (uint64_t *).
* HWCAP_PATTERN_MODE
: Pattern to generate (char **).

== Acquisition modes ==

* HWCAP_LIMIT_MSEC
: How long the acquisition should last, in ms (uint64_t).
* HWCAP_LIMIT_SAMPLES
: How many samples to acquire in the session (uint64_t).
* HWCAP_CONTINUOUS
: Device supports continuous sampling

Hardware driver API

2012-01-05T15:19:20Z

Seventhguardian: Minor fixes

Every plugin is built as a shared library, dynamically loaded by the backend at startup. The plugin must define a structure as follows:

#include "sigrok.h"

struct sr_device_plugin {
/* plugin-specific */
char *name;
char *longname;
int api_version;
int (*init) (const char *deviceinfo);
void (*cleanup) (void);

/* device-specific */
int (*open) (int device_index);
void (*close) (int device_index);
char *(*get_device_info) (int device_index, int device_info_id);
int (*get_status) (int device_index);
int *(*get_capabilities) (void);
int (*set_configuration) (int device_index, int capability, char *value);
int (*start_acquisition) (int device_index, gpointer session_device_id);
void (*stop_acquisition) (int device_index, gpointer session_device_id);
};

#define SIGROK_HARDWARE_PLUGIN struct device_plugin plugin_info

This structure is the only symbol imported into the backend namespace. The plugin's variables thus cannot conflict with the global sigrok namespace.

* '''name''' A short string describing this driver. It will be referenced in saved session files.

* '''longname''' A long string describing this driver. It will be shown to the user.

* '''api_version''' Currently defined as 1.

The other members of the structure are pointers to plugin callbacks:

* '''init(const char *deviceinfo)''' Called when the plugin is initially loading into sigrok, typically at program start. The parameter refers to a device name or special file, whichever is applicable for the plugin. Devices which don't need a supplied device, such as USB devices, can simply ignore this parameter. The function returns the number of devices found, and 0 if no suitable device was found. If a device was found, any initialization it needs must be performed here; for example, uploading firmware should be done here.

* '''cleanup()''' Called before the plugin is unloaded. Release any resources the plugin might be holding.

* '''open(int device_index)''' Open the specified device. The device index starts at 0.

* '''close(int device_index)''' Close the specified device.

* '''get_device_info(int device_index, int device_info_id)''' Returns information about the given device. The type of information is given as device_info_id, one of a set of defined constants. The return value is always a pointer, which points to information specific to the id.
** DI_INSTANCE: Returns a pointer to a [[Formats_and_structures#device_instances|struct sigrok_device_instance]].
** DI_NUM_PROBES: The number of probes connected to this device (integer).
** DI_SAMPLERATES: Returns a pointer to a [[Formats_and_structures#Sample_rates|struct samplerates]].

* '''get_status(int device_index)''' Returns an integer describing the status of the plugin's connection to a device. This may be one of the following:
** ST_NOT_FOUND: The device was not found.
** ST_INITIALIZING: The device was found, but is still initializing.
** ST_INACTIVE: The device is live, but not in use.
** ST_ACTIVE: The device is currently in use.

* '''get_capabilities()''' This function returns a zero-terminated integer array with the plugin's capabilities, in the form of a set of defined constants. Some of these are informative, and some can be used to configure the plugin (or its connected device). The capabilities tables below have an overview of all possible capabilities.

* '''set_configuration(int device_index, int capability, char *value)''' This is used to configure the plugin and/or connected device. The capability is one of the constants returned from the get_capabilities() call. The value depends on the parameter that is to be configured.

* '''start_acquisition(int device_index, gpointer session_device_id)''' Start acquisition on the specified device. The session_device_id will be passed along with the data feed of this session, as the first parameter to session bus callbacks.

* '''stop_acquisition(int device_index, gpointer session_device_id)''' Stop acquisition on the specified device. This causes a DF_END packet to be sent to the sesion bus.

== Device classes ==

* HWCAP_LOGIC_ANALYZER
: This device is a logic analyzer.

== Device options ==

* HWCAP_SAMPLERATE
: The sample rate in Hz (uint64_t *).
* HWCAP_PROBECONFIG
: Probe configuration (GSList *probes)
* HWCAP_CAPTURE_RATIO
: Pre-trigger capture ratio, as a percentage of the number of samples returned. The default is 0, meaning capturing only starts after the trigger fired (uint64_t *).
* HWCAP_PATTERN_MODE
: Pattern to generate (char **).

== Acquisition modes ==

* HWCAP_LIMIT_MSEC
: How long the acquisition should last, in ms (uint64_t).
* HWCAP_LIMIT_SAMPLES
: How many samples to acquire in the session (uint64_t).
* HWCAP_CONTINUOUS
: Device supports continuous sampling