Google Git
Sign in
fuchsia/third_party/github.com/google/emboss/refs/heads/upstream/me/embedded-size-bench
commit
0479f443ef64b3595be1c17d34d11ebd53756808
[log]
author
Aaron Webster <awebster@gmail.com>
Wed Jun 03 18:34:29 2026 -0700
committer
Aaron Webster <awebster@gmail.com>
Wed Jun 03 18:34:29 2026 -0700
tree
5a15e9623d16fdf90d632e13e613b14f58d9c845
parent
47c108de75939137fec1a2c6cd8c60d6ab49feb7 [diff]
Add embedded code-size benchmarking scripts

scripts/embedded_bench.sh cross-compiles a small freestanding driver
that forces LargeConditionals::Ok() into an object file, then reports
the object's `size` totals and the Ok() symbol size on:
  * ARM Cortex-M4 Thumb-2 (arm-none-eabi-g++)
  * MicroBlaze big-endian (microblaze-buildroot-linux-gnu-g++)
  * Host x86-64 (reference)
-ffunction-sections/-fdata-sections keep the per-symbol and TU numbers
comparable across compiles; EMBOSS_BENCH_FLAGS overrides the flags and
missing toolchains are skipped with a warning. The measured header is
refreshed from the live generator via scripts/regenerate_goldens.py.

scripts/profile_tool.py drives embedded_bench.sh across multiple git
revisions and compiler configurations, pulling the schema and harness
forward from the starting revision so the comparison measures generator
output rather than the test surface. It writes a markdown report of TU
and per-symbol sizes with deltas against the baseline revision.
2 files changed
tree: 5a15e9623d16fdf90d632e13e613b14f58d9c845
  1. .github/
  2. compiler/
  3. doc/
  4. gen/
  5. integration/
  6. runtime/
  7. scripts/
  8. testdata/
  9. .bazelrc
  10. .gitignore
  11. BUILD
  12. build.json
  13. build_defs.bzl
  14. CONTRIBUTING.md
  15. emboss-format
  16. embossc
  17. LICENSE
  18. license_header
  19. MODULE.bazel
  20. pyproject.toml
  21. README.md
  22. requirements.txt
README.md

Emboss

Emboss is a tool for generating code that reads and writes binary data structures. It is designed to help write code that communicates with hardware devices such as GPS receivers, LIDAR scanners, or actuators.

What does Emboss do?

Emboss takes specifications of binary data structures, and produces code that will efficiently and safely read and write those structures.

Currently, Emboss only generates C++ code, but the compiler is structured so that writing new back ends is relatively easy -- contact emboss-dev@google.com if you think Emboss would be useful, but your project uses a different language.

When should I use Emboss?

If you're sitting down with a manual that looks something like this or this, Emboss is meant for you.

When should I not use Emboss?

Emboss is not designed to handle text-based protocols; if you can use minicom or telnet to connect to your device, and manually enter commands and see responses, Emboss probably won't help you.

Emboss is intended for cases where you do not control the data format. If you are defining your own format, you may be better off using Protocol Buffers or Cap'n Proto or BSON or some similar system.

Why not just use packed structs?

In C++, packed structs are most common method of dealing with these kinds of structures; however, they have a number of drawbacks compared to Emboss views:

  1. Access to packed structs is not checked. Emboss (by default) ensures that you do not read or write out of bounds.
  2. It is easy to accidentally trigger C++ undefined behavior using packed structs, for example by not respecting the struct's alignment restrictions or by running afoul of strict aliasing rules. Emboss is designed to work with misaligned data, and is careful to use strict-aliasing-safe constructs.
  3. Packed structs do not handle variable-size arrays, nor arrays of sub-byte-size fields, such as boolean flags.
  4. Packed structs do not handle endianness; your code must be very careful to correctly convert stored endianness to native.
  5. Packed structs do not handle variable-sized fields, such as embedded substructs with variable length.
  6. Although unions can sometimes help, packed structs do not handle overlapping fields well.
  7. Although unions can sometimes help, packed structs do not handle optional fields well.
  8. Certain aspects of bitfields in C++, such as their exact placement within the larger containing block, are implementation-defined. Emboss always reads and writes bitfields in a portable way.
  9. Packed structs do not have support for conversion to human-readable text format.
  10. It is difficult to read the definition of a packed struct in order to generate documentation, alternate representations, or support in languages other than C and C++.

What does Emboss not do?

Emboss does not help you transmit data over a wire -- you must use something else to actually transmit bytes back and forth. This is partly because there are too many possible ways of communicating with devices, but also because it allows you to manipulate structures independently of where they came from or where they are going.

Emboss does not help you interpret your data, or implement any kind of higher-level logic. It is strictly meant to help you turn bit patterns into something suitable for your programming language to handle.

What state is Emboss in?

Emboss is currently under development. While it should be entirely ready for many data formats, it may still be missing features. If you find something that Emboss can't handle, please contact emboss-dev@google.com to see if and when support can be added.

Emboss is not an officially supported Google product: while the Emboss authors will try to answer feature requests, bug reports, and questions, there is no SLA (service level agreement).

Getting Started

Head over to the User Guide to get started.