This directory contains 3d specifications for various packet formats
around the TCP/IP protocol.

1. Contents: EverParse/3d data format specifications.

   We are parsing packets mostly in a layered fashion, so we have one
   specification per layer.

   Ethernet.3d: Ethernet II frames as used in vxlan (RFC 7348)
   IPV4.3d:     Internet Datagram Header for IPv4 (RFC 791)
   IPV6.3d:     IPv6 header (RFC 2460)
   ICMP.3d:     ICMP message (RFC 792).
                Includes an IPv4 header, so we reuse the corresponding
                specification.
   TCP.3d:      TCP header (RFC 793)
   UDP.3d:      UDP header (RFC 768)
   VXLAN.3d:    VXLAN header (RFC 7348)

2. How to build:

   After building EverParse, just run `make`.

3. Produced code:

   .c and .h files, as well as intermediate files, are produced in the
   interpret.out/ subdirectory, one for each source .3d
   specification.

   The C code for the verified implementation of the data format
   validator for, say, UDP headers is generated in UDP.c and
   UDP.h. However, these functions should not be directly called by
   client code: instead, client code should call functions defined in
   the generated UDPWrapper.c and UDPWrapper.h.

   (In particular, although input lengths in UDP.c and UDP.h are
   declared as uint64_t integers, they are assumed to be 32-bit
   integers, which is enforced by the user-facing functions generated
   in UDPWrapper.c and UDPWrapper.h, which take uint32_t input
   lengths. This is to reduce the number of integer casts in the
   generated validators.)

   Generated intermediate files (say for UDP):

   * UDP.fst: the F* definition of the data format for UDP headers in
     the 3D AST, and the corresponding interpreter invocations and
     partial evaluation directives for the data type, the parser
     specification and the validator implementation.

   * UDP.fsti: the corresponding F* interface, to mark which
     validators should be exposed to the final .h 

   * UDP.fst.checked, UDP.fsti.checked: binary intermediate files
     recording object cache for F* verification

   * UDP.krml: binary intermediate file recording KaRaMeL intermediate
     AST code for extraction from F* to C

   For TCP, where the validator for TCP options populates a parse tree
   with C data structures, we also generate the following additional
   files:

   * TCP_OutputTypesDefs.h: the C type definition for the TCP options

   * TCP.ExternalAPI.fsti: F* function signatures to write into fields
     of those C types from F* code

   * TCP_ExternalAPI.h: the generated C function prototypes for those
     functions, declared `extern`

   * TCP_OutputTypes.c: the generated C implementations for those
     functions

   * TCP_ExternalTypeDefs.h: a stub between TCP_ExternalAPI.h and
     TCP_OutputTypesDefs.h

   For those data formats that do not use the field_ptr action, we
   also generate a verified implementation of validators from
   non-contiguous input data. Such code is generated into
   extern.out. It has the same structure as interpret.out. The
   generated C code there can compile and link with any handwritten
   implementation for non-contiguous streams. Such an implementation
   is provided in the extern/ subdirectory.
