Overview

Writing decoders for binary formats is typically tedious and error prone. After reading specification documents, developers have to write code capable of decoding that particular format. This is a time consuming, frustrating, and costly process; it is also the source of many bugs when the manually written decoder fails to handle edge cases.

Bdec allows developers to write specifications for binary formats using several simple low-level constructs, which combine in powerful ways to allow many binary formats to be partially (often fully) specified. From this specification, developers can automatically generate source code for decoders and encoders.

While there are other high level specification languages (such as ASN.1, or google protocol buffers), few existing formats make use of these languages, and such specification languages cannot usually be retro-fitted to existing binary formats.

Bdec can;

• Allow specifications to be easily written and maintained.
• Decode both binary and structured text files.
• Generate portable, readable, and efficient C decoders and encoders.
• Run under Windows & Unix operating systems.

The bdec specification uses constructs based loosely on those found in ASN.1.

Getting started

1. Download the latest version.
2. Go through the tutorial.
3. Try writing a specification for your own file formats (referring to the documentation where necessary).
4. Save lots of time and pain by not writing and maintaining hand-written decoders.

Documentation

If you're just getting started, the tutorial takes you step by step through the different concepts used in bdec. Once you're writing your own specifications, refer to the rest of the documentation as required.

For convenience, pdf documentation is also available.

Support

Any comments or questions can go to the group mailing list at bdec-project@yahoogroups.com. This is a moderated list, so please be patient if your question doesn't show up immediately.

Features

• It is easy to write (and read) bdec specifications.
• No need to write a custom decoder (all error conditions are handled internally; decoding either passes or fails).
• The command line application allows visual inspection of problematic files.
• Unicode aware, little-endian / big-endian aware.
• Decode to xml for rapid development (eg: xml representation of a fat bootsector).
• Specify fields down to the bit (eg: single bit flags).
• Generated source code is human readable, easy to use, compiles without warnings, and has no dependencies.

License

The bdec library and code generated by the specification compiler are made available under the GNU Lesser General Public License (LGPL). In summary, this means;

• The software can be used free of charge in any application (including closed source applications).
• If you distribute an application using either the bdec library or code generated by the bdec library, the binary containing this code must be dynamically linked (eg: .dll in Windows, .so in Linux).
• The source code to this dynamic library must be made available to anyone you distribute the library to.

See COPYRIGHT and LICENSE for detailed copyright information.

Download

The easiest way to install bdec is to use python's easy_install application. Run:

easy_install bdec

to install the latest version of the bdec decoder and compiler.

• Version 0.7.2 (2011-07-10)

  Minor features:

  • Allow more than one child in a sequenceof.
  • Add const correctness to compiled C decoders.
  • Add the start of an Microsoft Word specification.

  Minor bugfixes:

  • Add more detailed copyright and license information.
  • Correctly escape the '&' character when printing xml.
  • Fix build warnings when compiling with gcc 4.6.

See the CHANGELOG for past releases.

Source

The source control tree is available on github at http://github.com/asdf1011/bdec.

git clone http://github.com/asdf1011/bdec.git

Dependencies that must be installed are pyparsing and mako.

Similar projects

Some other tools that perform 'generic' binary decoding include;

• TSN.1 - Commercial product with very similar decoding functionality to bdec. Can create C, C++, and Java decoders and encoders.
• Encodix - Commercial product focussed towards decoders for the telecommunications industry.
• Hachoir - Tool for inspecting many binary formats.

Projects that generate decoders from high level specifications;

• Asn1c Asn.1 compiler; generates C language encoders and decoders.
• Google protocol buffers - Define data interchange formats in an easy to read specification, and compile them to Java, C++, or Python decoders and encoders.