1# Emboss 2 3Emboss is a tool for generating code that reads and writes binary data 4structures. It is designed to help write code that communicates with hardware 5devices such as GPS receivers, LIDAR scanners, or actuators. 6 7## What does Emboss *do*? 8 9Emboss takes specifications of binary data structures, and produces code that 10will efficiently and safely read and write those structures. 11 12Currently, Emboss only generates C++ code, but the compiler is structured so 13that writing new back ends is relatively easy -- contact [email protected] 14if you think Emboss would be useful, but your project uses a different language. 15 16 17## When should I use Emboss? 18 19If you're sitting down with a manual that looks something like 20[this](https://hexagondownloads.blob.core.windows.net/public/Novatel/assets/Documents/Manuals/om-20000094/om-20000094.pdf) or 21[this](https://www.u-blox.com/sites/default/files/products/documents/u-blox6_ReceiverDescrProtSpec_%28GPS.G6-SW-10018%29_Public.pdf), 22Emboss is meant for you. 23 24 25## When should I not use Emboss? 26 27Emboss is not designed to handle text-based protocols; if you can use minicom or 28telnet to connect to your device, and manually enter commands and see responses, 29Emboss probably won't help you. 30 31Emboss is intended for cases where you do not control the data format. If you 32are defining your own format, you may be better off using [Protocol 33Buffers](https://developers.google.com/protocol-buffers/) or [Cap'n 34Proto](https://capnproto.org/) or [BSON](http://bsonspec.org/) or some similar 35system. 36 37 38## Why not just use packed structs? 39 40In C++, packed structs are most common method of dealing with these kinds of 41structures; however, they have a number of drawbacks compared to Emboss views: 42 431. Access to packed structs is not checked. Emboss (by default) ensures that 44 you do not read or write out of bounds. 452. It is easy to accidentally trigger C++ undefined behavior using packed 46 structs, for example by not respecting the struct's alignment restrictions 47 or by running afoul of strict aliasing rules. Emboss is designed to work 48 with misaligned data, and is careful to use strict-aliasing-safe constructs. 493. Packed structs do not handle variable-size arrays, nor arrays of 50 sub-byte-size fields, such as boolean flags. 514. Packed structs do not handle endianness; your code must be very careful to 52 correctly convert stored endianness to native. 535. Packed structs do not handle variable-sized fields, such as embedded 54 substructs with variable length. 556. Although unions can sometimes help, packed structs do not handle overlapping 56 fields well. 577. Although unions can sometimes help, packed structs do not handle optional 58 fields well. 598. Certain aspects of bitfields in C++, such as their exact placement within 60 the larger containing block, are implementation-defined. Emboss always 61 reads and writes bitfields in a portable way. 629. Packed structs do not have support for conversion to human-readable text 63 format. 6410. It is difficult to read the definition of a packed struct in order to 65 generate documentation, alternate representations, or support in languages 66 other than C and C++. 67 68 69## What does Emboss *not* do? 70 71Emboss does not help you transmit data over a wire -- you must use something 72else to actually transmit bytes back and forth. This is partly because there 73are too many possible ways of communicating with devices, but also because it 74allows you to manipulate structures independently of where they came from or 75where they are going. 76 77Emboss does not help you interpret your data, or implement any kind of 78higher-level logic. It is strictly meant to help you turn bit patterns into 79something suitable for your programming language to handle. 80 81 82## What state is Emboss in? 83 84Emboss is currently under development. While it should be entirely ready for 85many data formats, it may still be missing features. If you find something that 86Emboss can't handle, please contact `[email protected]` to see if and when 87support can be added. 88 89Emboss is not an officially supported Google product: while the Emboss authors 90will try to answer feature requests, bug reports, and questions, there is no SLA 91(service level agreement). 92 93 94## Getting Started 95 96Head over to the [User Guide](doc/guide.md) to get started. 97