OpenFPGA/libs/libopenfpgacapnproto/README.md

Capnproto usage in Openfpga
======================

Capnproto is a data serialization framework designed for portabliity and speed.
In Openfpga, capnproto is used to provide binary formats for internal data
structures that can be computed once, and used many times.  Specific examples:
 - preload unique blocks

What is capnproto?
==================

capnproto can be broken down into 3 parts:
 - A schema language
 - A code generator
 - A library

The schema language is used to define messages.  Each message must have an
explcit capnproto schema, which are stored in files suffixed with ".capnp".
The capnproto documentation for how to write these schema files can be found
here: https://capnproto.org/language.html

The schema by itself is not especially useful.  In order to read and write
messages defined by the schema in a target language (e.g. C++), a code
generation step is required.  Capnproto provides a cmake function for this
purpose, `capnp_generate_cpp`.  This generates C++ source and header files.
These source and header files combined with the capnproto C++ library, enables
C++ code to read and write the messages matching a particular schema.  The C++
library API can be found here: https://capnproto.org/cxx.html

Contents of libopenfpgacapnproto
===========================

libopenfpgacapnproto should contain two elements:
 - Utilities for working capnproto messages in Openfpga
 - Generate source and header files of all capnproto messages used in Openfpga

I/O Utilities
-------------

Capnproto does not provide IO support, instead it works from arrays (or file
descriptors).  To avoid re-writing this code, libopenfpgacapnproto provides two
utilities that should be used whenever reading or writing capnproto message to
disk. These two files are copied :
 - `serdes_utils.h` provides the writeMessageToFile function - Writes a
   capnproto message to disk.
 - `mmap_file.h` provides MmapFile object - Maps a capnproto message from the
   disk as a flat array.

Capnproto schemas
-----------------

libopenfpgacapnproto should contain all capnproto schema definitions used within
Openfpga.  To add a new schema:
1. Add the schema to git in `libs/libopenfpgacapnproto/`
2. Add the schema file name to `capnp_generate_cpp` invocation in
   `libs/libopenfpgacapnproto/CMakeLists.txt`.

The schema will be available in the header file `schema filename>.h`.  The
actual header file will appear in the CMake build directory
`libs/libopenfpgacapnproto` after `libopenfpgacapnproto` has been rebuilt.

Writing capnproto binary files to text
======================================

The `capnp` tool (found in the CMake build directiory
`/vtr-verilog-to-routing/libs/EXTERNAL/capnproto/c++/src/capnp`) can be used to convert from a binary
capnp message to a textual form.

Example converting UniqueBlockCompactInfo from binary to text:

```
capnp convert binary:text unique_blocks_uxsdcxx.capnp UniqueBlockCompactInfo \
  < test.bin > test.txt
```