Sysclk LWLA1034/Protocol

FPGA Configuration

The FPGA bitstream is loaded via bulk transfer to USB end point 4. Each firmware transfer starts with a 4-byte header to announce the transfer size. The payload appears to be a Raw Binary File (.rbf) with compression enabled.

Length	Payload...
nnnn-nnnn	dd...

Unlike the control commands, the firmware transfer is apparently byte-based. The length is a byte count encoded in big endian (1-2-3-4) byte order, and includes the size of the length field (4 bytes) itself.

Application Behavior

The vendor software transfers a new bitstream to the FPGA

1. on application start,
2. when switching clocking mode between internal, external/rising or external/falling,
3. on application exit.

The size of the bitstream varies due to compression, but is in the order of 50kB to 80kB. The firmware transfer is split by the vendor software into packets with 15 byte payload each and thus takes quite a bit of time inside VirtualBox. Testing with a libusb-based tool for issuing USB bulk transfers has shown that this does not appear to be necessary: Transferring even the entire firmware blob in a single bulk transfer appears to work without error.

Firmware Extraction

The firmware blobs can be extracted directly from the Windows installer executable located on the CD-ROM that ships with the device. The file lwla1034_EN_setup.exe on the CD-ROM from 2012-07-12 has the firmware blobs located at the following offsets:

Offset	Length	Mode
34110338	78398	Internal clock
34266237	78247	External clock (rising edge)
34344484	79145	External clock (falling edge)
34578631	48525	Shutdown

Both offsets and lengths are in bytes. The extracted blobs already include the header with the 32-bit length field.

Control Commands

Control commands are sent via bulk transfer to USB end point 2, with the response (if any) coming in from end point 6.

Command messages sent to the device appear to be a sequence of 16-bit words with little endian byte order. The first word in a message identifies the command type. Different command types have different message lengths. Some command types include a length field and allow for messages of variable length, others are of fixed size.

There are read commands which trigger an immediate response from the device, and write commands without a response.

Command 0001: Read Register

This command appears to read a 32-bit wide control register.

Command

Fixed length of 2 words (4 bytes).

ID	Address
0001	aaaa

Response

The response has a fixed length of 4 bytes. It is the content of a 32-bit register in mixed endian (2-1-4-3) byte order.

Registers

Address	Value
10C0	Channel 1 frequency counter
10C4	Channel 2 frequency counter
10C8	Channel 3 frequency counter
10CC	Channel 4 frequency counter

These registers apparently count the number of rising (or falling?) clock edges on channels 1 to 4. The vendor software polls these counters every second to display a live frequency count for the first four channels.

It is not clear yet what time base is being used for those counters: The large error (sometimes by more than 20%, especially for CH1) hints at I/O latency. However, manual testing of single register reads has shown that the values do not seem to scale with the time between reads. This would mean the device is using an internal time base after all, but that makes the large error a bit hard to explain, especially since the error is different for each channel despite being driven by the same signal source.

Address	Selftest value
10B0	12345678
10BC	12345678
10B8	87654321

These three registers assume the values listed here after writing 100 (decimal) to register 10B4. This is apparently an identification and self-test sequence, which is performed twice in a row during initialization.

Address	Value
1078	Capture size (number of 36-bit words)

This register appears to contain the size of the captured data. The vendor software retrieves this just before fetching the SRAM content.

Command 0002: Write Register

This command appears to write a 32-bit value to a control register.

Command

Fixed length of 4 words (8 bytes).

ID	Address	Data
0002	aaaa	dddd-dddd

The data is encoded in mixed endian (2-1-4-3) byte order.

Registers

Address	Init value
10B4	00000064

The vendor software writes the value 100 (decimal) to this register during initialization into order to start the self test sequence. After that, the magic register values listed in the table for command 0001 become available. So this is kind of a command-triggering register, and there are other command codes, too.

Address	Purpose
1094	Bypass clock divider
10B4	???
10B8	???
10BC	???

These are written to when a capture is initiated. Register 1094 is set to 0 when using the internal clock with sampling rates of 100 MHz and below. For 125MHz internal clock or the external clock modes, it is set to 1.

Address	Init value
1074	00000002
107C	00000000

The vendor software writes these two registers during initialization, and also when initiating a capture.

Command 0005: Write ???

This command appears to write 16 32-bit words at once. The vendor software issues this after a transfer of captured data to the host has finished, but only for the first three captures. After that, the application needs to be restarted to ever see this command again.

The data written varies each time, but it appears that only the lowest 8 bit of each 32-bit word are ever written. No idea what this might do, or if it is even necessary at all. It could be calibration feedback or something, although it is hard to imagine how the host could help the device with that.

Command

Fixed length of 33 words (66 bytes).

ID	Data 1	Data 2	...	Data 16
0005	dddd-dddd	dddd-dddd	...	dddd-dddd

The byte order of each 32-bit word is most likely the usual 2-1-4-3 mixed endianess.

Sample capture

A sample of three such commands from an actual protocol analysis session:

10185	56.455640		Cmd 5: write ??? data C3 9A 4B 91 30 D2 98 C1 CA F2 D7 4F 82 74 C0 8B
14155	95.788766		Cmd 5: write ??? data E5 7B 2C F3 6B 06 76 4B 60 94 F3 EC C9 AA E9 35
17823	131.101569		Cmd 5: write ??? data 16 66 EA 7B 35 F6 71 A8 0A E0 D7 E7 45 E0 4F 23

Only the least significant byte is shown for each 32-bit data word, as the other bytes are always 0. The message content changes with each run of the vendor software. It's hard to make head or tail of this. However, as this command is issued after all captured data has been retrieved, it should hopefully be possible to get away without using it at all.

Command 0006: Read Memory at Address

This command appears to read a block from the device memory (probably the SRAM). It allows for random access using a 32-bit start address, and variable length via a 32-bit length field. The software uses this command to read captured data from the device's buffer.

Command

Fixed length of 5 words (10 bytes).

ID	Address	Length
0006	aaaa-aaaa	nnnn-nnnn

Both the address and the length are apparently encoded with mixed endian (2-1-4-3) byte order: MSW (16 bit) followed by LSW (16 bit), with the two bytes making up each individual 16-bit word in little endian order.

Response

The memory is apparently 36 bit wide: The size of the response in bits is 36 times the value in the length field. The software reads chunks of 120 words @ 36 bit at a time, which works out to an integer multiple of 8 (i.e. 4320 bits = 540 bytes). The final six reads are done in chunks of 8 words @ 36 bit, which works out to 36 bytes. Judging from this behavior, it seems that reading partial words is likely illegal. The overall amount of memory being read when fetching captured samples hints at the RAM size of 256k×36 bit.

Note that the software always starts reading at address 4 rather than 0. Presumably the firmware uses the first four 36-bit words for internal bookkeeping or some other purpose. Exception to the rule: For some unknown reason, the memory is also being read on start-up right after loading the firmware into the FPGA. In this case, altogether 128000 36-bit words are being read beginning at address 0.

36-to-32 Bit Mapping

The data returned by the read command consists of 32-bit words in 2-1-4-3 mixed endian byte order. Eight consecutive 36-bit words from the SRAM are mapped at a time to nine consecutive 32-bit words in the received stream. The first eight 32-bit words contain the lower 32 bit of the eight encoded 36-bit words. The ninth 32-bit word contains the four remaining high bits of all eight 36-bit words combined.

The high nibbles are shifted into the ninth word from right to left, resulting in a 1-2-3-4-5-6-7-8 order of nibbles. (This is after conversion from mixed endian byte order!)

Compression Scheme

The compression scheme is a form of run-length encoding. Very short run lengths of only one or two cycles are handled as special cases, which helps to keep the worst-case overhead of compression pretty low.

Each 36-bit word in the stream is either a data word or a repeat half-count word. The first word is a data word, with the following layout:

Bit	35	34	33	32	31	...	2	1	0
Meaning	Repeat count follows	LSB of repeat count	CH34	CH33	CH32	...	CH3	CH2	CH1

If bit 35 is set, then the next 36-bit word in the stream encodes the number of cycles the previous data word is repeated, divided by two. The actual number of repeat cycles is twice that number plus the LSB of repeat count, i.e. bit 34 from the data word. If bit 35 is not set the next word is again a data word and the repeat half-count is assumed as zero. However, the LSB of repeat count bit still applies; i.e. if it is set then the repeat count would be 1.

So, to recap, repeat counts 0 to 1 are encoded as part of the channel data word, larger repeat counts use up a full extra 36-bit word. The combined repeat count is then 37 bit wide.

The next word following a repeat half-count is again a data word.

Command 0007: Capture Setup

This command prepares a capture operation. Essentially, this command appears to write a slice to an internal memory block with 64-bit granularity. Command 0008 can be used to read from the same memory.

The vendor software issues this command once during start-up, and once for each capture operation as part of the setup sequence. It is also issued when clicking the Stop button to cancel a capture in progress.

Command

Variable length of 3 words (6 bytes) plus length × 8 bytes.

ID	Address	Length	Data	...
0007	aaaa	nnnn	dddd-dddd-dddd-dddd	...

The two argument words are the start address and the length of the slice to write, in little endian byte order. Both the address and the length refer to quantities of 64 bit (8 byte). Thus, if length is 10 the payload should consist of 80 bytes.

The vendor software always writes a slice of length 10 at address 0, thus completely resetting the channel status as read by command 0008.

Command 0008: Capture Status

This command poll the current status of the input channels. Essentially, this command appears to read a slice from an internal memory block with 64-bit granularity. During idle periods, the software polls the channel state 34 times per second for its live port status display.

Command

Fixed length of 3 words (6 bytes).

ID	Address	Length
0008	aaaa	nnnn

The two argument words are the start address and the length of the slice to read, in little endian byte order. Both the address and the length refer to quantities of 64 bit (8 byte). Thus, if length is 10 the reply will consist of 80 bytes.

Response

The table below shows the response to the command as issued by the vendor software, i.e. with start address 0 and length 10. Each row is a 64-bit word in very much mixed up (6-5-8-7-2-1-4-3) byte order.

Index	Byte offset	Value
0	00	Channel enable mask
1	08	Clock divider count
2	10	Trigger level mask
3	18	Trigger edge mask
4	20	Trigger enable mask
5	28	Running capture memory size
6	30	???
7	38	Running capture cycle count × 10−5
8	40	Channel input state
9	48	Capture status flags

The channel enable mask and the input state are bit vectors, with bit 0 of the 64-bit word (after unmixing the byte order!) corresponding to CH1 and bit 33 corresponding to CH34. The enable mask shows which channels have been enabled for capturing. The bits in the input state vector signify whether the voltage at the corresponding input channels is currently low (0) or high (1).

Field 1 sets the max value of the counter which divides the internal clock to yield the sampling clock. This applies to all sample rates of 100MHz or less (125MHz is a special case: see control register 1094). The counter max value is calculated as follows: maxcount = 1 / (samplefreq * 10ns) - 1

Field 4 is the trigger enable mask. 1 enables triggering on a channel, 0 disables it. CH1 is mapped to bit 0 and CH34 to bit 33. Bits 34 and 35 are special and configure for external triggering. Bit 34 enables external triggering on the falling edge, bit 35 on the rising edge.

If a trigger channel is enabled, the corresponding bit in field 3 configures whether to trigger on level (0) or edge (1). The corresponding bit in field 2 then selects whether to trigger on low/falling (0) or high/rising (1).

Capture Status Flags

The status flag bits appear to have the following meaning:

Bit 0	Bit 1	Bit 2	Bit 3	Bit 4	Bit 5
???	Capturing	???	???	Triggered	Memory available

Task Recipes

This section lists the commands issued by the software to perform a particular task.

Initialization

1. Acquire control of USB device and select configuration 1
2. Send FPGA bitstream (default: internal clock) to EP 4 via bulk transfer
3. Device test sequence (performed twice by vendor software):
   1. Write 100 to register 0x10B4
   2. Read register 0x10B0: value should be 0x12345678
   3. Read register 0x10BC: value should be 0x12345678
   4. Read register 0x10B8: value should be 0x87654321
4. Capture setup/state test (vendor software does this, but perhaps it should be dropped):
   1. Write sequence 0..9 to capture setup fields (via command 7)
   2. Read back capture state (via command 8): 0..4 should be read back as is, 5..9 are trashed anyway
5. Memory test (vendor software does this, but perhaps it should be dropped):
   1. Write 2 to register 0x1074
   2. Write 0 to register 0x107C
   3. Read memory beginning at address 0 in chunks of 120 36-bit words, up to but not including 0x013FB0
   4. Read memory beginning at address 0x013FB0 in chunks of 8 36-bit words, up to but not including 0x014000

The chunking may not actually be necessary. As long as the memory read length is a multiple of 4, alignment to 16-bit word boundaries is guaranteed.

Poll channel state

1. Poll frequency of signal at CH1 to CH4:
   1. Read register 0x10C0: value is frequency of CH1 signal
   2. Read register 0x10C4: value is frequency of CH2 signal
   3. Read register 0x10C8: value is frequency of CH3 signal
   4. Read register 0x10CC: value is frequency of CH4 signal
2. Poll signal level of all channels:
   1. Read capture state (via command 8): the signal level of all channels is recorded in field 8

Clocking Mode Switch

1. Transfer one of three FPGA bitstreams to EP 4:
   1. Configuration for internal clock
   2. Configuration for external clock, rising edge
   3. Configuration for external clock, falling edge

Signal Capture

1. Write 2 to register 0x1074
2. Write 1 to register 0x1074 (previous write may be redundant, needs testing)
3. Write 10 to register 0x10B4
4. Write 0x74 to register 0x10B8
5. Write 0 to register 0x10BC
6. Write 0 to register 0x10B0
7. Write divider bypass flag to register 0x1094 (see description of register)
8. Write capture setup (command 7, address 0, length 10: see description of command)
9. Write 10 to register 0x10B4
10. Write 1 to register 0x10B8
11. Write 0 to register 0x10BC
12. Write 0 to register 0x10B0
13. Wait for capture to finish:
    1. Poll capture state (command 8, address 0, length 10: see description of command)
    2. Report progress information (got trigger, cycles elapsed, memory fill percentage) to user
    3. Capture has finished once the memory available flag is reset

Cancel Signal Capture

1. Write 10 to register 0x10B4
2. Write 0 to register 0x10B8
3. Write 0 to register 0x10BC
4. Write 0 to register 0x10B0
5. Write 0 to register 0x1094 (this is actually the divider bypass flag, perhaps it should be dropped here)

After that, the memory available flag in the capture state should have been cleared. Continue in the same manner as for a regularly finished capture.

Read Captured Data

1. Read register 0x1078: value is the number of 36-bit words in the capture buffer
2. Write 1 to register 0x1094 (this is actually the divider bypass flag, perhaps it should be dropped here)
3. Write 2 to register 0x1074
4. Write 4 to register 0x107C
5. Read capture buffer:
   1. Read memory beginning at address 4 in chunks of 120 36-bit words, up to but not including 0x03FFC4
   2. Read memory beginning at address 0x03FFC4 in chunks of 8 36-bit words, up to but not including 0x03FFF4
6. Write 0 to register 0x1094 (this is actually the divider bypass flag, perhaps it should be dropped here)
7. Issue mystery command 5 with mystery data, but for some mystical reason only for the first three captures after application start

The chunking may not actually be necessary. As long as the memory read length is a multiple of 4, alignment to 16-bit word boundaries is guaranteed. Note that vendor software always reads all memory from address 0 to 0x03FFF4, regardless of the capture size returned in register 0x1078. Perhaps this can be improved upon as well.

Issuing the mystery command 5 with mystery data hopefully won't be necessary either.

Shutdown

1. Transfer FPGA configuration for device shutdown to EP 4