Gidl (for Galois Interface Description Language) is a simple IDL for describing structured types and RPC-style interfaces.
Jump right to an example of gidl.
Gidl has a type language which permits the user to define types using the following primitives:
- Atomic types:
- Signed integers of 8, 16, 32, 64 bit width
- Unsigned integers of 8, 16, 32, 64 bit width
- IEEE 754 single and double precision floating point numbers
- Boolean values
- User-defined Enum types:
- Pairs of names and values, where names and values must have a one-to-one correspondence
- User specified representation width (8, 16, 32, or 64 bits)
- User-defined Newtypes:
- Wraps an existing atomic or enum type with a new type
- User-defined Structures:
- Set of named fields. Corresponds to a record or a C struct.
- Fields may be of any other user-defined type
Gidl does not have any sort of sum types (tagged unions) because the Ivory language does not have support for sum types.
Gidl interfaces are composed of the following primitives:
- Attributes, which are read and written according to requests by the client. Attributes have a user defined read/writable permissions.
- Streams, which are sent from server to client whenever the server wants. Streams were never really thought through all the way, and no Gidl implementation is expected to handle streams. They're still here because we have not made time to remove them.
Interfaces can be composed by subtyping. We regret this choice and should have known better. We would find a better way to compose interfaces if resources permitted.
Protocol drift is detected by identifying each stream and attribute message on the wire by a hash of its name, its type, and all child types.
The gidl IDL uses a s-expression based format. The IDL format currently is
documented in tests/example.gidl
Gidl currently has backends for:
- Haskell backend: translates types to algebraic datatypes, creates
cereal
instances for serialization. - Haskell-RPC backend: all of the features of the Haskell backend, and also creates an HTTP server that exposes a JSON RPC-style interface for gidl interfaces.
- Ivory backend: translates types to Ivory types, creates
ivory-serialize
instances for serialization. - Tower backend: all of the features of the Ivory backend, and also creates datatypes of tower channels for interface streams and attributes, and a tower monitor which implements a server for a given interface.
Gidl requires the stack
build tool; it will download and
configure appropriate versions of Haskell tools automatically.
In order to build the code generated by the the Ivory and Tower backends, we require the Ivory, Tower, and ivory-tower-stm32 repositories. These should also be found, by default, in the parent directory, but alternate locations can be specified when running Gidl.
git clone https://github.com/galoisinc/ivory
git clone https://github.com/galoisinc/tower
git clone https://github.com/galoisinc/ivory-tower-stm32
The stack.yaml
file assumes you have checked out this repository as
a submodule of smaccmpilot-build
. For a
standalone build, edit the relative paths for the prerequisite
packages in stack.yaml
.
The default target builds the gidl library. You can then use stack exec gidl -- <OPTIONS>
to run the code generator. Use the --help
option to get usage information.
Use the test
target in the Makefile to generate and test each backend
implementation. The tests/example.gidl
file is used as the input language.
You may then browse generated code for each implementation, which is generated
and built in subdirectories of the tests
directory.
There is a vim-mode available at pchickey/vim-gidl
.
If you use the vundle package manager, add the line Package 'pchickey/vim-gidl'
to your .vimrc
, then run :BundleInstall
.
If you use the Pathogen package manager, clone the vim-gidl
repo into your
~/.vim/bundle
directory.
There is an emacs-mode available at aisamanra/gidl-mode
and through an elisp archive at http://gelpa.gdritter.com
.
If an emacs user uses the emacs package manager, they can just add a line to
their .emacs
and then install it either interactively with M-x package-list
or automatically with (use-package gidl-mode :ensure t)
Gidl was created at Galois by Pat Hickey, with help from Getty Ritter and Trevor Elliott, as part of the SMACCMPilot project.
Gidl was inspired in part by John Van Enk's excellent Cauterize tools. If engineering resources and time had permitted, we would have added unions to the Ivory language, so that we could make a Cauterize backend for Ivory. Instead, we got Gidl.
If you find yourself making serious use of Gidl, please get in touch so we may apologize for its many shortcomings, and recommend that you use Cauterize instead.
This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unaccpetable behavior to [email protected].