Logic 2 Capture Format (.sal)

Logic 2 Software
1

We occasionally get questions about the .sal capture format, and although our usual response is that it’s not stable and shouldn’t be relied on, there have been enough requests for more information (see: Provide .sal file translation through an API - Logic 2 - Ideas and Feature Requests - Saleae) that we thought it was worth creating a dedicated post where we could answer questions.

DISCLAIMER: We do not officially support or maintain compatibility with past or future version of the .sal format. The format can and will change in breaking ways. USE AT YOUR OWN RISK

Ok, now that that is out of the way, let’s talk about the format. A .sal capture itself is a zip file - rename your capture.sal to capture.zip and open it with your favorite zip tool - you’ll find:

  • meta.json - a json file describing the capture
  • digital-#.bin - raw digital data
  • analog-#.bin - raw analog data

That’s it. meta.json is a JSON format that is (hopefully) fairly easy to reason about. The digital and analog formats are binary formats that require a little more work to understand.

On the ideas page, Dan has already done great work figuring out the digital format (again, see: Provide .sal file translation through an API - Logic 2 - Ideas and Feature Requests - Saleae). I’ll try to answer some of those questions here.

Why not the 0x80 of the first byte flagging? Good Question! And this is the easy format to reverse engineer.

The digital data is RLE encoded, using a variable number of bytes. The MSB of the first byte indicates whether this byte is an RLE entry (0) or a raw entry (1). In practice we never use the raw data mode, so this bit is never set.

Still don’t quite understand the relation between that metadata array entry count and the transitions/transitions count, but I don’t think I need to currently.

The metadata contains sample number to byte offset information. We use it at runtime to speed up cases where we need to search by sample number, but you can skip it. If you do think it would be helpful, the format is:

uint64 sample_number
uint64 byte_offset // into the RLE data
int32 bit_state

No comment on the 32 bits for the bit state :grimacing:

This is likely to change in the next year, but no short term plans to do so.

Also, I’m guessing part of the reason for the blocks is that somewhere you’re creating a separate block for each transfer up from the USB driver and you’re just serializing the list of blocks. Simple enough approach.

Yep, this is about right. The actual size and rate of the blocks will be affected by the sample rate that you are using as well.

If you have specific questions, please ask here and we’ll try to help out.

Ryan

1 Like
2

What about logic 1 file format?

There are many of us that have so many old captures and are forced to use old, unsupported software, because Logic 2 doesn’t support Logic 1 files.

So at least, could you document, unofficially, the Logic 1 file format as well, at least at the extent that we could convert one format to the other?

Otherwise, it is very possible that eventually we won’t be able to run the old software and read the old files. Or we might need to use virtualization because future operating systems might be incompatible with the old software.

Pretty please? :slight_smile:

3

@George From what I recall, our .logicdata file format (i.e. Logic 1 file format) is more complex than the newer .sal file format. The .logicdata files were generated with boost binary serialization and contains an object structure that I believe we don’t have a complete understanding of.

If we were to take this project on, I would assume we would create a tool that utilizes part of our Logic 1.x software to open the .logicdata file, export the data into a format we can parse, and convert that known file format into a .sal file.

We unfortunately don’t have this kind of tool officially on the roadmap, however, I did add a comment for you in the idea post we are tracking for it below:

It’s currently the 2nd highest voted feature so far. We initially received the majority of requests for this feature when the Logic 2 app first released, and understandably so.

4

Thanks for the detailed and honest reply, Tim.

I understand the complications, but please be aware that for some of us it is extremely important. No wonder that it received so many votes.

Note that a partial converter, such as not converting the analyzers, would be an acceptable solution.

Thanks,

5

Hi all,

Yeah, I was thinking about that though, and thought about sharing what I have so far. The below I also posted on Import .logicdata capture - Logic 2 - Ideas and Feature Requests - Saleae :

Not quite an answer to this as it does not directly deal with .logicdata (1.x) and .sal (2.x), however some 4 years ago I posted an example of how to export two mixed (analog+digital) recordings from Saleae Logic 1.x via .bin export, and import them both in a single PulseView session. Here is the link: github.com/sdbbs/sigrok_pulseview_combine_merge - maybe it helps. Though, I’d say, for me a Python converter between .logicdata and .sal (both ways); between 1.x and 2.x .bin (not sure if there is difference between them); and back and forth from these formats to (extended) Value Change Dump (.vcd) and .wav would be all I need.