Anubis / Anubis

/* describe.c *****************************************************************************

                                           Anubis
                                    Describing serialization. 

*****************************************************************************************/

#include <stdlib.h>   
#include "compil.h"

   
   
/* some global variables */   
static Expr already_described = nil;     // list of already described types
static Expr to_be_described = nil;       // list of types still to be described
static FILE *describe_file = NULL;       // 'serializations.txt'

   
   
/* Printing an integer in binary format with given number of binary digits */
static void print_binary(FILE *fp, 
                         int n,
                         int width)
{
 begin:
  if (width == 0) return;
  if ((n>>(width-1))&1) fprintf(fp,"1"); else fprintf(fp,"0"); 
  width--;
  goto begin; 
}
   
   
   
/* Checking if a type contains a parameter */   
static int contains_parameters(Expr e)   // a type or a list of types 
{
 begin:
  if (consp(e))
    {
      if (contains_parameters(car(e))) return 1; 
      e = cdr(e); 
      goto begin; 
    }
  else if (is_user_type_variable(e)) return 1; 
  else return 0; 
}

   
   
/* transforming a number of bits into a number of bytes (0, 1, 2 or 4 only) */   
static int round0124(int n)
{
  if (n <= 0) return 0; 
  if (n <= 8) return 1; 
  if (n <= 16) return 2; 
  return 4;
}

   
   
/* Getting the width (in bits) of a small type. */
int width_of_small_type(Expr implem)   
{
  /*
      implem = (small_type <nalt> <iw> <alt geom> ... <alt geom>)
      <alt geom> = (small_alt (<imp> <offset> . <width>) ... (<imp> <offset> . <width>))  
  */
  int iw = integer_value(third(implem)); 
  int n = 0; 
  implem = cdr3(implem);    /* implem = (<alt geom> ... <alt geom>) */
  while (consp(implem))
    {
      int alt_width = 0; 
      Expr comps = cdr(car(implem)); 
      implem = cdr(implem); 
      while (consp(comps))
        {
          alt_width += integer_value(cdr2(car(comps))); 
          comps = cdr(comps); 
        }
      n = sup(n,alt_width); 
    }
  return n + iw; 
}
   
   
   
   
   
   
/* describing a small alternative in a small type */   
static void describe_small_alt(Expr alt,   /* implementation of the alternative */
                               int iw)     /* width of index (bits) */
{
  /*
    alt = (small_alt (<imp> <offset> . <width>) ... (<imp> <offset> . <width>))
    (constructed in 'implem.c')
  */
  int cn = 0;                  /* counting components */
  //int total_width = iw;        /* computing the total width of the datum */
  alt = cdr(alt);              /* alt = ((<imp> <offset> . <width>) ...) */ 
  while(consp(alt))
    {
      /* do for each component */
      int imp = integer_value(car(car(alt)));          /* index of implementation of component */
      Expr type = implems[imp].type;                   /* type of component */
      int offset = integer_value(second(car(alt)));    /* offset of component (bits) */
      int width = integer_value(cdr2(car(alt)));       /* width of component (bits) */
      fprintf(describe_file,
              "\n      component number %d in bits %d to %d, which is of type: ",cn,offset,offset+width-1); 
      show_type(describe_file,type,nil);
      if (!member(type,already_described))
        if (!member(type,to_be_described))
          to_be_described = cons(type,to_be_described); 
      //total_width += integer_value(cdr2(car(alt))); 
      alt = cdr(alt); 
      cn++; 
    }
}
   
   
   
   
/* describing a small alternative in a mixed type */   
static void describe_small_alt_mixed(Expr alt,     /* implementation of the alternative */
                                     int alt_index)
{
  /*
    alt = (small_alt (<imp> <offset> . <width>) ... (<imp> <offset> . <width>))
  */
  int cn = 0;                  /* counting components */
  int total_width = 2;         /* computing the total width of the datum */
  alt = cdr(alt);              /* alt = ((<imp> <offset> . <width>) ...) */ 
  fprintf(describe_file,"\n   Bits 0 and 1: ");
  print_binary(describe_file,alt_index,2);
 while(consp(alt))
    {
      /* do for each component */
      int imp = integer_value(car(car(alt)));          /* index of implementation of component */
      Expr type = implems[imp].type;                   /* type of component */
      int offset = integer_value(second(car(alt)));    /* offset of component (bits) */
      int width = integer_value(cdr2(car(alt)));       /* width of component (bits) */
      fprintf(describe_file,
              "\n      component number %d in bits %d to %d, which is of type: ",cn,offset,offset+width-1); 
      show_type(describe_file,type,nil);
      if (!member(type,already_described))
        if (!member(type,to_be_described))
          to_be_described = cons(type,to_be_described); 
      total_width += integer_value(cdr2(car(alt))); 
      alt = cdr(alt); 
      cn++; 
    }
  if (total_width < 32)
    fprintf(describe_file,
            "\n   Bits %d to 31 are zeros.",total_width); 
  fprintf(describe_file,
          "\n   The serialization of a datum of this alternative occupies 5 bytes.\n\n"); 
}
    
   
   
   
   
/* describing a mixed alternative */   
static void describe_mixed_alt(Expr alt)    /* implementation of alternative */
{
  /*
    alt = (mixed_alt (<imp> <offset> . <width>) ... (<imp> <offset> . <width>))
  */
  int cn = 0;            /* counting components */
  alt = cdr(alt);        /* alt = ((<imp> <offset> . <width>) ...) */
  while(consp(alt))
    {
      /* do for each component */
      int imp = integer_value(car(car(alt)));     /* implementation index of component */
      Expr type = implems[imp].type;              /* type of component */
      fprintf(describe_file,
              "\n      - Component number %d, which is of type: ",
              cn);
      show_type(describe_file,type,nil);
      if (!member(type,already_described))
        if (!member(type,to_be_described))
          to_be_described = cons(type,to_be_described); 
      alt = cdr(alt); 
      cn++; 
    }
}

   
   
   
   
/* describing a large alternative */   
static void describe_large_alt(Expr alt)    /* implementation of alternative */
{
  /*
    alt = (large_alt (<imp> <offset> . <width>) ... (<imp> <offset> . <width>))
  */
  int cn = 0;            /* counting components */
  alt = cdr(alt);        /* alt = ((<imp> <offset> . <width>) ...) */
  while(consp(alt))
    {
      /* do for each component */
      int imp = integer_value(car(car(alt))); 
      Expr type = implems[imp].type; 
      fprintf(describe_file,
              "\n      - Component number %d, which is of type: ",
              cn);
      show_type(describe_file,implems[imp].type,nil);
      if (!member(type,already_described))
        if (!member(type,to_be_described))
          to_be_described = cons(type,to_be_described); 
      alt = cdr(alt); 
      cn++; 
    }
}
   
   
   

      
   
/* Describing a small type */   
static void describe_small_type(Expr implem)
{
  /*
    (small_type <nalt> <iw> <alt geom> ... <alt geom>)
   
    <alt geom> :=
    (small_alt (<imp> <offset> . <width>) ... (<imp> <offset> . <width>))
  */
  int ci = 0; 
  int nalt = integer_value(second(implem)); 
  int iw = integer_value(third(implem)); 
  int tw = width_of_small_type(implem); 
  int bw = round0124(tw);
   
  implem = cdr3(implem);
  if (nalt == 0) 
    {
      fprintf(describe_file,"\n   There is no datum of this type.");
      return;
    }
  while (consp(implem))
    {
      fprintf(describe_file,
              "\n\n   - Alternative number %d:",ci);
      if (iw) fprintf(describe_file,
                      "\n   Bits 0 to %d: ",iw-1);
      print_binary(describe_file,ci,iw); 
      describe_small_alt(car(implem),iw); 
      implem = cdr(implem); 
      ci++; 
    }
  if (tw != 0 && tw != 8 && tw != 16 && tw != 32)
      fprintf(describe_file,
              "\n\n   If this datum does not appear as a component in another small type,"
              "\n   it occupies %d byte%s, and the unused bits (bits %d to %d) must be"
              "\n   zeros."
              "\n   If this datum appears as a component in another small type, it occupies"
              "\n   a field of %d bit%s.",
              bw,tw > 8 ? "s" : "",tw,(bw*8)-1,tw,tw > 1 ? "s" : ""); 
  else
    fprintf(describe_file,
            "\n\n   The serialization of a datum of this type occupies %d byte%s (%d bit%s).",
            bw,tw > 8 ? "s" : "",tw,tw > 1 ? "s" : ""); 
}
   
   

   
   
   
/* Describing a mixed type */   
static void describe_mixed_type(Expr implem)
{
    /*
       (mixed_type <nalt> <iw> <alt geom> ... <alt geom>)
   
       <alt geom> :=
       (small_alt (<imp> <offset> . <width>) ... (<imp> <offset> . <width>))
       (mixed_alt (<imp> <offset> . <width>) ... (<imp> <offset> . <width>))
    */ 
  int ci = 0; 
  implem = cdr3(implem);
  while (consp(implem))
    {
      fprintf(describe_file,
              "\n\n   - Alternative number %d:",ci);
      fprintf(describe_file,
              "\n   First byte: %.2x",ci);
   
      if (car(car(implem)) == small_alt)
        {
          fprintf(describe_file,
                  "\n   Subsequent 4 bytes seen as a 32 bits word (with bytes in little endian order): ");
          describe_small_alt_mixed(car(implem),ci);
        }
      else
        {
          fprintf(describe_file,
                  "\n   Subsequent bytes: ");
          describe_mixed_alt(car(implem));
        }
   
      implem = cdr(implem); 
      ci++; 
    }
}
   
   
   
   
   
   
/* Describing a mixed type */   
static void describe_large_type(Expr implem)
{
    /*
       (large_type <nalt> <iw> <alt geom> ... <alt geom>)
   
       <alt geom> :=
       (large_alt (<imp> <offset> . <width>) ... (<imp> <offset> . <width>))
      
    */ 
  int ci = 0; 
  implem = cdr3(implem);
  while (consp(implem))
    {
      fprintf(describe_file,
              "\n\n   - Alternative number %d: ",ci);
      fprintf(describe_file,
              "\n   First byte: %.2x",ci);
      if (length(car(implem)) > 1) 
        fprintf(describe_file,
                "\n   Subsequent bytes: ");
      else 
        fprintf(describe_file,
                "\n   Nothing more. ");   
      describe_large_alt(car(implem)); 
      implem = cdr(implem); 
      ci++; 
    }
}
   
   
   
   
/* Describing the serialization for all sorts of types. */ 
static void describe_type(Expr lc, 
                          Expr type)
{  
  int implem_id = type_implementation_id(type,nil); 
  Expr implem = implems[implem_id].implem; 
  Expr offcode = nil; 
   
  /* check that type has no parameter */
  if (contains_parameters(type))
    {
      err_line_col(lc,"E116",str_format(msgtext_cannot_describe_schema[0]));
      show_type(errfile,type,nil); 
      return;
    }


  offcode = offline_pseudo_code(implem_id);  
  if (offcode == not_serializable)
    {
      fprintf(errfile, 
              "\n   This type is used by type:\n");
      show_type(errfile,type,nil); 
      fprintf(errfile,
              "\n   in 'describe' paragraph at line %d in %s.\n\n",
              line_in(lc),file_in(lc));
      return; 
    }
  
   
  fprintf(describe_file,"\n   *** Type: ");
  show_type(describe_file,type,nil); 
   
  if (consp(implem))
    {
      switch (car(implem))
        {
        case small_type:
          {
            //int tw = width_of_small_type(implem); 
            fprintf(describe_file,
                    "\n\n   This is a 'small' type. Number of alternatives: %d.",
                    integer_value(second(implem)));
            /*
              fprintf(describe_file,
              "\n   The datum is represented as a field of %d bit%s."
              "\n   eventually completed above by zero bits if the datum"
              "\n   does not appear as a component in another small type"
              "\n   so as to occupy %d byte%s."
              "\n   Bit number 0 is the least significant one.",
              tw,tw > 1 ? "s" : "",round0124(tw),tw > 8 ? "s" : "");
            */
            describe_small_type(implem);
          }
          break;
   
        case mixed_type:
          fprintf(describe_file,
                  "\n\n   This is a 'mixed' type. Number of alternatives: %d.",
                  integer_value(second(implem)));
          describe_mixed_type(implem); 
          break;
   
        case large_type:
          fprintf(describe_file,
                  "\n\n   This is a 'large' type. Number of alternatives: %d.",
                  integer_value(second(implem)));
          describe_large_type(implem); 
          break;
   
        default: internal_error("Unknown type implementation",implem);
        }
      fprintf(describe_file,"\n\n"); 
    }
  else
    {
      if (implem == type_String) 
        { 
          fprintf(describe_file,
                  "\n\n   Same as in C: the characters of the string followed by"
                  "\n   a right delimiting zero byte."
                  "\n\n   For example, the serialization of the string \"Anubis\" is:"
                  "\n\n   41 6e 75 62 69 73 00"
                  "\n   A  n  u  b  i  s  ^"
                  "\n                     |"
                  "\n                     `----- terminating zero byte\n\n");
        }
      else if (implem == type_Int)
        {
          fprintf(describe_file,
                  "\n\n   The first byte is the sign (0 = positive, 1 = negative)."
                  "\n   The subsequent group of 4 bytes is the number of bigits"
                  "\n   (a 'bigit', i.e. a 'big digit', is a digit in numeration basis 2^32)."
                  "\n   The subsequent groups of 4 bytes are the bigits."
                  "\n   Each group of 4 bytes is in little endian order (least significant byte first)."
                  "\n   The bigits themselves are in big endian order (most significant bigit first)."
                  "\n\n   For example, the serialization of the integer 1234567890987654321234567890 is:"
                  "\n\n   00 03 00 00 00 eb 35 fd 03 a5 b9 77 79 d2 e2 18 6a"
                  "\n   ^  ^        ^  ^        ^  ^        ^  ^        ^"
                  "\n   |  |        |  |        |  |        |  |        |"
                  "\n   |  +--------'  +--------'  +--------'  +--------'"
                  "\n   |  |           |           |           |"
                  "\n   |  |           |           |           `---- last bigit (least significant)"
                  "\n   |  |           |           `---------------- second bigit"
                  "\n   |  |           `---------------------------- first bigit (most significant)"
                  "\n   |  `----- number of bigits"
                  "\n   `-------- this number is positive"
                  "\n\n   Important note: there is always at least one bigit. Hence, the integer"
                  "\n   0 is represented by:"
                  "\n\n   00 01 00 00 00 00 00 00 00"
                  "\n\n   i.e. with one bigit whose value is 0, and with positive sign.\n\n"
                  );
        }
      else if (implem == type_Float)
        {
          fprintf(describe_file,
                  "\n\n   The datum occupies 8 bytes. These 8 bytes"
                  "\n   are the official IEEE754 representation, but the bytes themselves"
                  "\n   are in little endian order (least significant first).\n\n"); 
        }
      else if (implem == type_ByteArray)
        {
          fprintf(describe_file,
                  "\n\n   The first 4 bytes are the number of bytes in the byte array."
                  "\n   This number of bytes is in little endian order (least significant byte first)."
                  "\n   The subsequent bytes are the content of the byte array."
                  "\n   There is no right delimiting zero."
                  "\n\n   For example, the byte array 'to_byte_array(\"Anubis\") is represented by:"
   
                  "\n\n   06 00 00 00 41 6e 75 62 69 73"
                  "\n   ^        ^  A  n  u  b  i  s"
                  "\n   |        |"
                  "\n   +--------'"
                  "\n   |"
                  "\n   `------ number of bytes"
                  "\n\n   External library linking is not concerned by the following remark. This"
                  "\n   is because data are not transmitted to wrapper functions as byte arrays,"
                  "\n   but as clones of byte arrays."
                  "\n\n   Remark: there is an exception. If the byte array itself is the unique argument"
                  "\n   of 'serialize', the result does not include the number of bytes."
                  "\n   For example, 'serialize((ByteArray)to_byte_array(\"Anubis\")' yields:"
                  "\n\n   41 6e 75 62 69 73"
                  "\n\n   whilst 'serialize((Maybe(ByteArray))success(to_byte_array(\"Anubis\")))' yields:"
                  "\n\n   01 06 00 00 00 41 6e 75 62 69 73"
                  "\n\n   This is because byte arrays must be unchanged by 'serialize' (see 'predefined.anubis').\n\n"
                  );
        }
      else 
        fprintf(describe_file,"\n\n  This type is not serializable.\n"); 
    }
}


   
   
/* Describing serialization for a list of types ('describe' paragraph). */
void describe_serialization(Expr lc, 
                            Expr types)    // a list of types
                           
{
  /* this is required for computing implementations */
  find_infinite_types(); 
  infinite_flags_reliable = 1; 
   
  /* open the description file (if not already done) */ 
  if (describe_file == NULL) 
    {
      describe_file = fopenz("serializations.txt","wt"); 
      /* preambule of the whole file */
      fprintf(describe_file,
              "\n   Description of some serializations."
              "\n   (generated by the Anubis compiler)"
              "\n          --------------------"
              "\n\n");
      fprintf(describe_file,
              "\n   This text describes how data of some types are represented when they"
              "\n   are serialized. A serialized datum is a sequence of bytes."
              "\n   In the examples below, bytes are represented as two digits hexadecimal numbers."
              "\n   Bits in bit fields are shown in big endian order (most significant bit at the left end)."
              "\n\n   You may also want to see these bytes on particular examples."
              "\n   In this case, complete the second paragraph below by replacing 'T'"
              "\n   by a type and 'd' by a datum of type 'T', compile"
              "\n   and execute this program.\n\n"
              "\ndefine One hexdump(ByteArray b, Int i) ="
              "\n   if nth(i,b) is"
              "\n     {"
              "\n       failure     then print(\"\\n\"),"
              "\n       success(c)  then print(to_hexa(c)+\" \");"
              "\n                        hexdump(b,i+1)"
              "\n     }."
              "\n\nglobal define One"
              "\n   show_serialization"
              "\n     ("
              "\n        List(String) args"
              "\n     ) ="
              "\n   hexdump(serialize((T)d),0).   /* replace 'T' and 'd' in this line */\n\n\n"
              ); 
   
    }
   
  /* preambule for each describe paragraph */
  fprintf(describe_file,
          "\n   *******************************************************"
          "\n   *** 'describe' paragraph at line %d in:\n   *** %s"
          "\n   *******************************************************"
          "\n   (types already described above are not described again)\n\n",
          line_in(lc),file_in(lc)); 
   
  /* describe each type */
  //already_described = nil; 
  to_be_described = types; 
  while (consp(to_be_described))
    {
      Expr type = car(to_be_described); 
      already_described = cons(type,already_described); 
      to_be_described = cdr(to_be_described); 
      describe_type(lc,type); 
      already_described = save(already_described); 
    }
}