xdrgen Documentation

Purpose of xdrgen

Automating this process helps to avoid inconsistencies between the C data structure and the IPC format string. In our experience, inconsistencies are often introduced when the data structure is changed, but the person modifying the code is not aware that the format string must also be changed. These inconsistencies can lead to garbled binary messages, which are sometimes very difficult to track down.

Running xdrgen for the first time

xdrgen example.xdr example.xdr.h

This will output the C header file example.xdr.h, based on the XDR specification in example.xdr. You can compare the two to get a quick idea of the relationship between XDR and C.

xdrgen command-line options

usage: xdrgen OPTIONS <xdrFile> [outputHeaderFile]
 -h or --help        Print this help
 --lang=[c,c++]      Change language for header output
                     (default: c++)
 --directives=[portable,gcc,none]
                     Control syntax of #line directives
                     that help to trace location of errors
                     (default: portable)
 -Dname=value, -Idirectory
                     These options are passed on to the C
                     pre-processor before xdrgen parses the
                     input file (see cpp(1) or 'info cpp')

Basic xdrgen type declarations

typedef int foo;

generates a typedef and a macro in the output header file:

typedef int foo;
#define foo_IPC_FORMAT "int"

The second kind of declaration is a struct. The declaration

struct Zoo {
  int foo;
  int goo;
};

typedef struct _Zoo {
  int foo;
  int goo;
} Zoo;
#define Zoo_IPC_FORMAT "{int,int}"

struct Zoo {
  int foo;
  int goo;
#define Zoo_IPC_FORMAT "{int,int}"
  static const char *getIPCFormat(void) {
    return Zoo_IPC_FORMAT;
  }
};

If you are using a C++ compiler, the C++ output has the following advantages:

• As we will see later, xdrgen allows arbitrary code to be inserted at the end of a struct definition. In C++, this can be used to define member functions. Defining the struct starting with struct Zoo instead of typedef struct _Zoo allows us to define constructors for Zoo in the arbitrary code section.
• Code which requires the IPC format can access either the macro Zoo_IPC_FORMAT or the member function Zoo::getIPCFormat(), which may enable you to write cleaner code.

You may nest struct declarations to arbitrary depths, and use previously defined types in declarations of new types, as in the following:

struct MyIncludableStruct {
  int foo;
  struct { int a; } goo;
};

struct MyNestedStruct {
  MyIncludableStruct b;
  struct {
    char a;
    MyIncludableStruct b2;
  } roo;
};

You may not declare multiple fields of the same type in one line, so the C construction int a, b; must be replaced with int a; int b;.

Primitive types

struct PrimitiveTypes {
  string a<>;
  unsigned char b;
  char c;
  unsigned int d;
  int e;
  bool f;
  float g;
  double h;
};

• The string field is followed by <> because strings are always variable-length arrays in XDR. This will be discussed more later.
• The bool type isn't defined by default in C. Therefore, whenever xdrgen creates C-language output, it includes a definition for bool as an enumerated type compatible with the built-in C++ definition. In C++, a bool is a 4-byte data structure which takes on the values false=0 or true=1. In the IPC format string, the bool field is represented as "int"
• For the other types, there is a straightforward mapping both to C datatypes and to IPC format strings (see the Defining Message Data Formats section).

Fixed-length arrays

typedef unsigned char ImagePixel[3];

struct Transform {
  double mat[4][4];
};

we get the following header output (abbreviated for clarity):

typedef unsigned char ImagePixel[3];
#define ImagePixel_IPC_FORMAT "[uchar:3]"

struct Transform {
  double mat[4][4];
};
#define Transform_IPC_FORMAT "{[double:4,4]}"

Variable-length arrays

struct Image {
  int rows;
  int cols;
  unsigned char data<><>;
};

we get the following header output (abbreviated for clarity):

struct Image {
  int rows;
  int cols;
  unsigned char *data;
};
#define Image_IPC_FORMAT "{int,int,<uchar:1,2>}"

Variable-length array fields in IPC must be inside a struct, and the length in each dimension of the array must correspond to an int or unsigned int field of the struct. Which fields of the struct are used for each dimension is controlled by the format string. xdrgen has the following stricter requirements:

• If the variable-length array has n dimensions, the struct must have exactly n+1 fields.
• The first n fields of the struct must have type int or unsigned int
• The int fields of the struct correspond to dimensions of the array in order from left to right (most significant dimension to least significant).

Fixed and variable-length array dimensions cannot be mixed, so the following declaration is illegal:

struct Alpha {
  int size;
  char beta[5]<>;
}

However, a similar effect could be achieved with the following declaration:

struct Alpha {
  int size;
  struct { char data[5]; } beta<>;
};

xdrgen allows a maximum possible length to be declared for a variable-length array, as in the following definition:

struct Gamma {
  int delta;
  float epsilon<20>;
};

However, there is no notion of a maximum length for a variable-length array in IPC, so the length doesn't currently appear in the header output.

Enumerated types

enum Color {
  RED, ORANGE, YELLOW
};

we get the following header output:

enum Color {
  RED,
  ORANGE,
  YELLOW
};
#define Color_IPC_FORMAT "{enum RED,ORANGE,YELLOW}"

Values for the named options of an enumerated type can also be specified, but IPC is only flexible enough to handle a consecutive set of options, so if any values are specified, xdrgen represents the field as "int" to IPC (with the disadvantage that IPC can't expand values to option names during data logging). For the declaration

enum Mixed {
  TWO = 2, FOUR, SIX = 6
};

we get the following header output:

enum Mixed {
  TWO = 2,
  FOUR,
  SIX = 6
};
#define Mixed_IPC_FORMAT "int"

More about the string type

• is required to be present (as specified in RFC 1014)
• is ignored in the IPC format generated by xdrgen
• does not need to appear in a struct with a corresponding int field

struct ExecCall {
  struct {
    int argc;
    string argv<>;
  } args;
  string envVars[20]<>;
};

which produces the header output (abbreviated for clarity):

struct ExecCall {
  struct {
    int argc;
    char **argv;
  } args;
  char *envVars[20];
};
#define ExecCall_IPC_FORMAT "{{int,<string:1>},[string:20]}"

Arbitrary code sections

The XDR file text

%{
#include "my_arbitrary_code.h"
#define N 3
extern int foo;
%}

typedef double Meters;

%{
extern Meters length;
%}

struct Roo {
  int a;
  char b;
%{
  Roo(int _a, char _b) { a = _a; b = _b; }
%}
};

generates the header output (abbreviated for clarity):

#include "my_arbitrary_code.h"
#define N 3
extern int foo;

typedef double Meters;
#define Meters_IPC_FORMAT "double"

extern Meters length;

struct Roo {
  int a;
  char b;
  Roo(int _a, char _b) { a = _a; b = _b; }
};
#define Roo_IPC_FORMAT "{int,char}"

External format definitions

ipc_type ExternalStruct1;

tells xdrgen to expect that the type ExternalStruct1 has an IPC format defined in the macro ExternalStruct1_IPC_FORMAT. The macro definition must appear before the generated code for any struct which includes ExternalStruct1, which means that it should either appear in an arbitrary code section of the XDR file, or it should be included via a #include directive in an arbitrary code section.

Once ExternalStruct1 is declared using ipc_type, it can be included in subsequent struct declarations without causing a warning. The declaration

struct IncExternalStruct {
  int a;
  ExternalStruct1 s1;
}

generates the header output (abbreviated for clarity):

struct IncExternalStruct {
  int a;
  ExternalStruct1 s1;
}
#define IncExternalStruct_IPC_FORMAT "{int," ExternalStruct1_IPC_FORMAT "}"

You can also manually define the IPC format for a type using ipc_type. The declaration

ipc_type ExternalStruct2 = "{char,double}";

tells xdrgen to use the given format string instead of trying to refer to the macro ExternalStruct2_IPC_FORMAT.

Formal XDR language definition

• RFC 1014 specifies a mapping between an XDR datatype specification and the binary format of the corresponding network message. Because XDR syntax is so similar to C syntax, there is also an implicit mapping between the XDR datatype and the corresponding C datatype. It is this second mapping that xdrgen tries to capture. The IPC format string for a datatype is generated from the C datatype according to the rules in the Defining Message Data Formats section. There is no reason to expect that IPC network messages will follow the XDR binary packing rules.
• Unsupported feature: union types. There are no corresponding types in IPC.
• Unsupported feature: hyper (8-byte integer) types. There are no corresponding types in IPC.
• Unsupported feature: optional data (the XDR * syntax). Supported in IPC, but not implemented by xdrgen.
• Extension: opaque replaced with char and unsigned char. A char type need not be in an array.
• Extension: arbitrary code sections.
• Extension: multi-dimensional arrays.

Those interested in a full grammar for the xdrgen input language can look at bison input file src/XDRGen/XDR.y in the IPC distribution.