doc.txt

wm PNE 3.3 source code, running at more than vxworks6.x version.

BNF for layout language:

  <file> := <definition>*

  <definition> := (define-layout <name> <form>)
                | (define-layout-macro <pattern> <Scheme-procedure>)
                | (define-rcs-info <RCS-keyword-string>)
                | (use-layouts <pathname-string>)
                | (C-include <test> <path>)

  <form> := <type>
  <form> := <expression>

  <expression> := <name>
                | <constant>
                | (<op> <expression>*)
                | (sizeof <type>)

  <op> := + | - | * | octets

  <type> := <name>
          | (<type-constructor> <expression>*)
          | (enum <enumeration-clause>*)
          | (struct <aggregate-clause>*)
          | (union <aggregate-clause>*)
          | (array <array-clause>*)

  <type-constructor> := opaque | boolean | signed | unsigned |
                      | signed-8bit-little | unsigned-8bit-little

  <enumeration-clause> := (type <type>)
                        | (value <name> <expression>)

  <aggregate-clause> := (field <name> <type>)
                      | (fill <expression>?)
                      | (union <aggregate-clause>*)
                      | (struct <aggregate-clause>*)
                      | (size <expression>)
                      | (align <expression>)

  <array-clause> := (count <expression>)
                  | (type <type>)
                  | (size <expression>)
                  | (align <expression>)
                  | (spacing <expression>)

  <constant> := ... any scheme constant ...

  <name> := ... sequence of letters, digits and underscores ...

-----

Macros generated by `-makeh':

    (Note that if it is impossible for some reason to generate a macro that
    performs as expected, a comment will be generated explaining why.  For
    example, since C doesn't support pointers to single bits, we can't
    generate `PTR_...' macros for boolean fields!)

  SIZEOF_<type>

    The size in bytes of the type <type>.

  PTR_<type>_<field>(p)
  GET_<type>_<field>(p)
  SET_<type>_<field>(p, v)

    p should be a pointer.  v will be cast to the appropriate type.

    Operate on the <field> field of the type <type> -- returning a pointer
    to it or reading or writing its contents.

  <type>_is_<name>

    The constants in the enumeration type <type>.  (Yes the word "is"
    really is in lower case -- I'm open to alternate suggestions, but I
    really like the look of `IP_PORT_is_DOMAIN'.)

-----

GLUE macros expected by `-makeh':
  
  GLUE_CAST_PTR(p)

    Convert p to bits8_t *.  This could be a cast, or it could expand into
    a call to a prototyped procedure if you wanted to enforce some type
    safety.

  GLUE_Gennh(p)

    (Specifically:
      GLUE_GB08, GLUE_GB16, GLUE_GB32, GLUE_GB32LS24, GLUE_GB32MS24,
      GLUE_GL08, GLUE_GL16, GLUE_GL32, GLUE_GL32LS24, GLUE_GL32MS24,
      GLUE_GU08, GLUE_GU16, GLUE_GU32, GLUE_GU32LS24, GLUE_GU32MS24.)

    p is of type bits8_t *.  Returns the appropriate type for nn bit bytes.
    e is B for big endian, L for little endian, or U for un-endian.

    h is LS24 or MS24 if the caller is only going to manipulate the least
    significant 24 bits or most significant 24 bits.  The macro may or may
    not return the other byte in the 32 bit word.

  GLUE_Sennh(p, v)

    (Specifically:
      GLUE_SB08, GLUE_SB16, GLUE_SB32, GLUE_SB32LS24, GLUE_SB32MS24,
      GLUE_SL08, GLUE_SL16, GLUE_SL32, GLUE_SL32LS24, GLUE_SL32MS24,
      GLUE_SU08, GLUE_SU16, GLUE_SU32, GLUE_SU32LS24, GLUE_SU32MS24.)

    p is of type bits8_t *.  v is of the appropriate type for nn bit bytes.
    e is B for big endian, L for little endian, or U for un-endian.

    h is LS24 or MS24 if the caller is only going to manipulate the least
    significant 24 bits or most significant 24 bits.  The macro may or may
    not store the other byte in the 32 bit word.  (But it -must- behave
    consistent with the corresponding GLUE_G... macro!)

  GLUE_CASTnn(v)

    (Specifically: GLUE_CAST08, GLUE_CAST16, GLUE_CAST32.)

    Cast v to be the appropriate unsigned scalar type for nn bit bytes.

  GLUE_OPAQUEnn(v)

    (Specifically: GLUE_OPAQUE08, GLUE_OPAQUE16, GLUE_OPAQUE32.)

    These could be defined as:
    
      #define GLUE_OPAQUE08(v) (GLUE_SB08(scratch, v), GLUE_GU08(scratch))
      #define GLUE_OPAQUE16(v) (GLUE_SB16(scratch, v), GLUE_GU16(scratch))
      #define GLUE_OPAQUE32(v) (GLUE_SB32(scratch, v), GLUE_GU32(scratch))

    Assuming scratch is a bits8_t * pointer to 4 bytes of temporary storage.

-----

Command line interface:

  ldbcomp [-define <defs>]      -- Obsolete!
          [-makesch <schfile>]
          [-makeh <hfile>]
          [-include-check <prefix>]
          [-unique-names <length>]
          <file> ...

    First all the <defs> files are loaded in the order they appeared in the
    command line.  Definitions made in these files are added to the
    built-in definitions.  No output will be generated for the definitions
    made in any <defs> file.  (Note that the `-define' option can usefully
    be used multiple times.)  NOTE: The `-define' option has been made
    obsolete by the new `use-layouts' top-level form.

    Second, each <file> is loaded.

    Third, if the `-makesch' option was specified, a Scheme->C header file
    is generated named <schfile>.

    Forth, if the `-makeh' option was specified, a C header file is
    generated named <hfile>.

    If `-include-check' was specified, the C header file will include code
    to prevent multiple inclusion.  <prefix> is the prefix to use for the
    macro that will be tested to perform this check.

    
    `-unique-names' controls how many characters in an identifier are
    significant to the pre-processor.  By default, ldbcomp checks to be
    certain that the first 31 characters of all macro names are unique.

    Example:

      ldbcomp -include-check "LAYOUT_" -define ip.ldb -makeh tcp.h tcp.ldb

    Loads `ip.ldb' and `tcp.ldb' and then writes `tcp.h'.  `tcp.h' will
    contain macro definitions for objects defined in `tcp.ldb'.

    `tcp.h' will test `#ifndef LAYOUT_TCP_H' to prevent multiple inclusion.

-----

  $Source: /usr/cvsroot/target/h/wrn/wm/util/layout/doc.txt,v $
  $Id: doc.txt,v 1.1.1.1 2001/11/05 17:47:20 tneale Exp $