document-memory.c

/*
  Automatically generate documentation about memory addresses of the MEGA65.

  The idea is that it scans the VHDL source for the @IO: magic comments that
  we already have everywhere, and generates register tables from those.

  To do this in a really nice way, it needs to not only do the C64/C65/M65
  differentiation, but also have some kind of convention for indicating which
  table each should appear in, names for the signals for showing in the
  compact register table, and then a mechanism for allowing longer blocks
  of documentation to follow, that can be put in the signal explanations
  below the table.

  The overall goal is to produce the sections of the User's Guide that
  mirror the chip information chapters of the C64 Programmer's Reference Guide,
  in a way that pulls directly from the source code, so that it never goes out
  of date, and removes the need to separately maintain the two, which is of
  course simply a recipe for neglect.  It's "creative laziness" or "work smarter,
  not harder" thinking at work.

  So, the key changes we need are to have a more structured approach to the @IO:
  comment lines to indicate which table they should appear in. To appear in multiple
  tables, just have multiple comments.

  The new format is:

  @IO:XX <address spec> TABLE:SIGNAL Description

  <address spec> can be $NNNN or $NNNN-$NNNN or $NNNN.B or $NNNN.B-B
  (or $NNNNNNN in place of $NNNN)

  All signals with the same TABLE will appear in the same table file, called
  reginfo_TABLE.MODE.tex
  The SIGNAL tags will be used for populating the relevant bits in the table
  rows.
  The description will then appear below the tables.

  It is possible to create condensed description lists by using signal aliases:

  @IO:XX <address spec> TABLE:SIGNAL@ALIAS Description

  defines ALIAS as the entry that will be  shown in the description list.
  Use the following format to refer to such an description:

  @IO:XX <address spec> TABLE:SIGNAL @ALIAS

  It is possible to add '!' inside a SIGNAL name. This will be converted to a
  soft word break in the LaTeX output, so the name can break in a small bit sized
  cell.

  Extended comments for SIGNALs will take the form:

  @INFO:TABLE:SIGNAL

  And all following lines of the same comment block in the VHDL will produce a
  \subsubsection{SIGNAL - Description}
  following the table, that has more in-depth information about the signal,
  possibly including examples etc. It will be treated as raw input for the
  latex.

*/

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <string.h>
#include <strings.h>

#define MODE_C64 1
#define MODE_C65 2
#define MODE_MEGA65 3

int Warn = 1; // print warnings to stderr if set

struct reg_line {
  unsigned int low_address, high_address;
  unsigned int low_bit, high_bit;
  char *signal;
  char *signal_idx;
  char *description;
  unsigned char isRef;
};

struct info_block {
  char *signal;
  char *description;
  int line_count;
#define MAX_LINES 1024
  char *lines[MAX_LINES];
};

struct reg_table {
  char *name;
  int mode;
#define MAX_ENTRIES 1024
  struct reg_line regs[MAX_ENTRIES];
  int reg_count;
  struct info_block info_blocks[MAX_ENTRIES];
  int info_count;
};

#define MAX_TABLES 1024
struct reg_table* reg_tables[MAX_TABLES];
int table_count = 0;

struct table_output_line {
  int low_addr, high_addr;
  char *bit_signals[8];
  char *bit_signals_idx[8];
  char *descriptions[8];
};

struct table_output_line table_stuff[MAX_ENTRIES];
int table_len = 0;
int table_uses_bits = 0;

char *table_signals[MAX_ENTRIES];
char *table_descriptions[MAX_ENTRIES];
int table_sigcount = 0;

void clear_table_output(void)
{
  table_len = 0;
  table_uses_bits = 0;
  table_sigcount = 0;
}

char *latex_escape(char *source)
{
  char prev = '\0';
  int len = strlen(source) << 2;
  char *the_target = malloc(len < 256 ? 256 : len), *target; // quadrupling should be enough

  if (!the_target) {
    fprintf(stderr, "[ERROR] failed to allocate enough memory to latex escape string!\n");
    exit(1);
  }

  target = the_target;
  while (*source) {
    // escape dollar sign if not already escaped or math mode

    if (*source == '$' && prev != '\\') {
      if (*(source + 1) == '\\') // check for $\...$
      {
        *target++ = *source++; // copy initial $
        while (*source && *source != '$')
          *target++ = *source++; // copy math expression
        if (*source)
          *target++ = *source; // copy ending $
      }
      else // escape $
      {
        *target++ = '\\';
        *target++ = *source;
      }
    }

    // escape underline or at sign or hash sign

    else if (*source == '_' || *source == '@' || *source == '#') {
      if (prev != '\\')
        *target++ = '\\';
      *target++ = *source;
    }

    // replace tilde with middle tilde in math mode

    else if (*source == '~') {
      strcpy(target, "$\\sim$");
      target += strlen(target);
    }

    // else just copy

    else
      *target++ = *source;

    // remember previous char and advance

    prev = *source++;
  }
  *target = '\0';

  return the_target;
}

// converts ! in signal names to a word break \-
// allocates new memory for generated string and returns this much like strdup
char *latex_add_break(char *signal)
{
  char *result = NULL, *s, *n;
  int chars = 0;

  for (s=signal; *s; s++)
    if (*s == '!')
      chars++;

  result = malloc(strlen(signal) + chars + 1);
  for (s=signal, n=result; *s; s++, n++) {
    if (*s == '!') {
      *n = '\\';
      n++;
      *n = '-';
    } else
      *n = *s;
  }

  return result;
}

// strip those ! pseudo breaks for index use
// also strdups!
char *latex_strip_break(char *signal)
{
  char *result = NULL, *s, *n;

  result = malloc(strlen(signal) + 1);
  for (s=signal, n=result; *s; s++)
    if (*s != '!') {
      *n = *s;
      n++;
    }

  return result;
}

void table_output_add_reg(struct reg_line* r)
{
  int l = 0;
  int insert_point = -1;

  if (0)
    printf("Adding $%04X -- $%04X bits %d..%d : %s = %s\n", r->low_address, r->high_address, r->low_bit, r->high_bit,
        r->signal, r->description);

  // Have we already seen this register?
  for (l = 0; l < table_len; l++) {
    if ((table_stuff[l].low_addr == r->low_address) && (table_stuff[l].high_addr == r->high_address)) {
      // It is this register
      break;
    }
    // Remember where we should insert the register, if required
    if (table_stuff[l].low_addr < r->low_address) {
      // printf("  stored $%04X > this $%04X, setting insert_point to here.\n",table_stuff[l].low_addr,r->low_address);
      insert_point = l;
    }
  }
  // Is a new table entry required?
  if (l == table_len) {
    // Too many?
    if (l >= MAX_ENTRIES) {
      fprintf(stderr, "ERROR: Too many register lines when building table output.  This probably indicates a bug.\n");
      return;
    }
    // Not too many, so setup the next one
    // First, shuffle space
    for (int m = table_len; m > insert_point; m--)
      table_stuff[m] = table_stuff[m - 1];
    // Now setup entry
    l = insert_point;
    if (l == -1)
      l = 0;
    else if (table_stuff[l].low_addr < r->low_address)
      l++;
    // if (l) printf("  inserting after $%04X\n",table_stuff[l-1].low_addr);
    // if (l<(table_len-1)) printf("  inserting before $%04X\n",table_stuff[l+1].low_addr);
    memset(&table_stuff[l], 0, sizeof(struct table_output_line));
    table_stuff[l].low_addr = r->low_address;
    table_stuff[l].high_addr = r->high_address;
    table_len++;
  }

  // Update entry
  for (int bit = r->low_bit; bit <= r->high_bit; bit++) {
    table_stuff[l].bit_signals[bit] = r->signal;
    table_stuff[l].bit_signals_idx[bit] = r->signal_idx;
    table_stuff[l].descriptions[bit] = r->description;
  }

  // Note if this table addresses signals by bit, so we can format it appropriately
  if (r->low_bit || (r->high_bit < 7)) {
    // Register table uses bits
    table_uses_bits = 1;
  }

  // Now do the same for the signal list, for those tables that are bit-addressed
  if (!r->isRef) {
    int signum = 0;
    insert_point = -1;
    for (signum = 0; signum < table_sigcount; signum++) {
      if (!strcmp(table_signals[signum], r->signal_idx)) {
        insert_point = signum;
        break;
      }
      else if (strcmp(table_signals[signum], r->signal_idx) > 0) {
        if (insert_point < 0) {
          insert_point = signum;
        }
      }
    }
    if (insert_point < 0)
      insert_point = table_sigcount;
    if (signum == table_sigcount) {
      // New signal.

      if (table_sigcount >= MAX_ENTRIES) {
        fprintf(stderr, "ERROR: Too many unique signal names in table. Fix or increase MAX_ENTRIES.\n");
        return;
      }

      // Shuffle to make space
      for (int m = table_sigcount; m > insert_point; m--) {
        table_signals[m] = table_signals[m - 1];
        table_descriptions[m] = table_descriptions[m - 1];
      }
      table_signals[insert_point] = r->isRef?r->description:r->signal_idx;
      table_descriptions[insert_point] = r->description;
      table_sigcount++;
    }
  }
}

void emit_table_output(FILE* f)
{
  char *buftxt; // used to convert special chars to latex
  int omit_dec_address = 0;

  for (int row = 0; row < table_len; row++) {
    if (table_stuff[row].low_addr > 65535) {
      omit_dec_address = 1;
      break;
    }
  }

  if (table_uses_bits) {
    // Table has 10 columns: HEX addr, DEC addr, 8 x signal names
    fprintf(f, "\\setlength{\\tabcolsep}{0pt}\n"
               "\\begin{longtable}{|%s%sC{12.5mm}|C{12.5mm}|C{12.5mm}|C{12.5mm}|C{12.5mm}|C{12.5mm}|C{12.5mm}|C{12.5mm}|}\n"
               "\\hline\n"
               "{\\bf{HEX}} & %s{\\bf{DB7}} & {\\bf{DB6}} & {\\bf{DB5}} & {\\bf{DB4}} & {\\bf{DB3}} & "
               "{\\bf{DB2}} & {\\bf{DB1}} & {\\bf{DB0}} \\\\\n"
               "\\hline\n"
               "\\endfirsthead\n"
               "\\multicolumn{3}{l@{}}{\\ldots continued}\\\\\n"
               "\\hline\n"
               "{\\bf{HEX}} & %s{\\bf{DB7}} & {\\bf{DB6}} & {\\bf{DB5}} & {\\bf{DB4}} & {\\bf{DB3}} & "
               "{\\bf{DB2}} & {\\bf{DB1}} & {\\bf{DB0}} \\\\\n",
               (omit_dec_address ? "C{16.5mm}|" : "C{12.5mm}|"),
               (omit_dec_address ? "" : "C{12.5mm}|"),
               (omit_dec_address ? "" : "{\\bf{DEC}} & "),
               (omit_dec_address ? "" : "{\\bf{DEC}} & "));
  }
  else {
    // Table has 4 columns: HEX addr, DEC addr, signal name, description
    fprintf(f, "\\setlength{\\tabcolsep}{3pt}\n"
               "\\begin{longtable}{|%s%sC{2cm}|L{6cm}|}\n"
               "\\hline\n"
               "{\\bf{HEX}} & %s{\\bf{Signal}} & {\\bf{Description}} \\\\\n"
               "\\hline\n"
               "\\endfirsthead\n"
               "\\multicolumn{3}{l@{}}{\\ldots continued}\\\\\n"
               "\\hline\n"
               "{\\bf{HEX}} & %s{\\bf{Signal}} & {\\bf{Description}} \\\\\n"
               "\\hline\n",
               (omit_dec_address ? "L{1.6cm}|" : "L{1.2cm}|"),
               (omit_dec_address ? "" : "L{1.1cm}|"),
               (omit_dec_address ? "" : "{\\bf{DEC}} & "),
               (omit_dec_address ? "" : "{\\bf{DEC}} & "));
  }

  fprintf(f, "\\endhead\n"
             "\\multicolumn{3}{l@{}}{continued \\ldots}\\\\\n"
             "\\endfoot\n"
             "\\hline\n"
             "\\endlastfoot\n");

  for (int row = 0; row < table_len; row++) {
    fprintf(f, "\\footnotesize ");
    if (table_stuff[row].low_addr < 0x0100) {
      if (table_stuff[row].low_addr != table_stuff[row].high_addr) {
        fprintf(f, " %02X -- %02X\\index{\\$%02X (%s)}\\index{%s} ",
            table_stuff[row].low_addr, table_stuff[row].high_addr,
            table_stuff[row].low_addr, table_stuff[row].bit_signals_idx[0],
            table_stuff[row].bit_signals_idx[0]);
        if (!omit_dec_address) {
          fprintf(f, "& \\footnotesize %d -- %d ",
            table_stuff[row].low_addr, table_stuff[row].high_addr);
        }
      } else {
        fprintf(f, " %02X\\index{\\$%02X (%s)}\\index{%s} ", table_stuff[row].low_addr,
            table_stuff[row].low_addr, table_stuff[row].bit_signals_idx[0], table_stuff[row].bit_signals_idx[0]);
        if (!omit_dec_address) {
          fprintf(f, "& \\footnotesize %d ",
            table_stuff[row].low_addr);
        }
      }
    }
    else {
      if (table_stuff[row].low_addr != table_stuff[row].high_addr) {
        fprintf(f, " %04X -- %04X\\index{Registers!\\$%04X -- \\$%04X} ",
            table_stuff[row].low_addr, table_stuff[row].high_addr, table_stuff[row].low_addr, table_stuff[row].high_addr);
        if (!omit_dec_address) {
          fprintf(f, "\\index{Registers!%d -- %d} & \\footnotesize %d -- %d ",
            table_stuff[row].low_addr, table_stuff[row].high_addr, table_stuff[row].low_addr, table_stuff[row].high_addr);
        }
      } else {
        fprintf(f, " %04X\\index{Registers!\\$%04X} ", table_stuff[row].low_addr,
            table_stuff[row].low_addr);
        if (!omit_dec_address) {
          fprintf(f, "\\index{Registers!%d} & \\footnotesize %d ",
            table_stuff[row].low_addr, table_stuff[row].low_addr);
        }
      }
    }

    if (table_uses_bits) {
      // Table is address + signal name of each bit,
      // followed by signal name glossary

      for (int bit = 7; bit >= 0;) {
        // Check for signals that span multiple bits
        int bit_count = 1;
        for (int b = bit - 1; b >= 0; b--) {
          if (table_stuff[row].bit_signals_idx[bit] == table_stuff[row].bit_signals_idx[b])
            bit_count++;
          else
            break;
        }
        if (bit_count == 1) {
          fprintf(f, "& \\footnotesize %s ", table_stuff[row].bit_signals[bit] ? table_stuff[row].bit_signals[bit] : "--");
        }
        else {
          fprintf(f, "& \\multicolumn{%d}{c|}{\\footnotesize %s", bit_count,
              table_stuff[row].bit_signals[bit] ? table_stuff[row].bit_signals[bit] : "--");
          if (table_stuff[row].bit_signals[bit])
            fprintf(f, "\\index{Registers!%s}", table_stuff[row].bit_signals_idx[bit]);
          fprintf(f, "}");
        }

        bit -= bit_count;
      }
      fprintf(f, "\\\\\n");
      fprintf(f, "\\hline\n");
    }
    else {
      // Table is address + signal name + description
      if (table_stuff[row].low_addr < 0x0100) {
        fprintf(f, "& %s\\index{%s} & %s \\\\\n", table_stuff[row].bit_signals[0], table_stuff[row].bit_signals_idx[0],
            table_stuff[row].descriptions[0]);
      }
      else {
        fprintf(f, "& %s\\index{Registers!%s} & %s \\\\\n", table_stuff[row].bit_signals[0], table_stuff[row].bit_signals_idx[0],
            table_stuff[row].descriptions[0]);
      }
      fprintf(f, "\\hline\n");
    }
  }
  // fprintf(f,"\\normal\n");

  fprintf(f, "\\end{longtable}\n");

  // If table uses bits, then we need to produce the table of signal descriptions
  if (table_uses_bits) {
    fprintf(f, "\\begin{itemize}\n");
    for (int s = 0; s < table_sigcount; s++) {
      // XXX - Replace with contents of appropriate info block if one exists!
      //    fprintf(f,"\\item{\\bf{%s}} %s\n",table_signals[s],table_descriptions[s]);
      buftxt = latex_escape(table_descriptions[s]);
      fprintf(f, "\\item{\\bf{%s}\\index{Registers!%s}} %s\n", table_signals[s], table_signals[s], buftxt);
      free(buftxt);
    }
    fprintf(f, "\\end{itemize}\n");
  }
}

char *describe_mode(int m)
{
  if (m == MODE_C64)
    return "C64";
  if (m == MODE_C65)
    return "C65";
  if (m == MODE_MEGA65)
    return "MEGA65";
  return "???";
}

int parse_io_line(char *line)
{
  int low_addr = 0, high_addr = 0, low_bit = 0, high_bit = 7;
  char mode[8192];
  char table[8192];
  char signal[8192];
  char *description, *sigsplit;
  int n;
  int mode_num;

  // Get fields
  int ok = 0;

  if (sscanf(line, "-- @IO:%[^ ] $%x.%d-%d %[^:]:%[^ ] %n", mode, &low_addr, &low_bit, &high_bit, table, signal, &n) == 6) {
    ok = 1;
    high_addr = low_addr;
  }
  else if (sscanf(line, "-- @IO:%[^ ] $%x.%d %[^:]:%[^ ] %n", mode, &low_addr, &low_bit, table, signal, &n) == 5) {
    ok = 1;
    high_addr = low_addr;
    high_bit = low_bit;
  }
  else if (sscanf(line, "-- @IO:%[^ ] $%x-$%x %[^:]:%[^ ] %n", mode, &low_addr, &high_addr, table, signal, &n) == 5) {
    ok = 1;
  }
  else if (sscanf(line, "-- @IO:%[^ ] $%x - $%x %[^:]:%[^ ] %n", mode, &low_addr, &high_addr, table, signal, &n) == 5) {
    ok = 1;
  }
  else if (sscanf(line, "-- @IO:%[^ ] $%x %[^:]:%[^ ] %n", mode, &low_addr, table, signal, &n) == 4) {
    ok = 1;
    high_addr = low_addr;
  }

  // Make sure bit order is ascending, to avoid problems
  if (high_bit < low_bit) {
    int temp = low_bit;
    low_bit = high_bit;
    high_bit = temp;
  }

  if (!ok) {
    if (Warn)
      fprintf(stderr, "ERROR: @IO line missing TABLE:SIGNAL descriptor or otherwise mal-formed\n");
    return -1;
  }

  description = &line[n];

  // Make sure TABLE has no spaces, which would indicate a mal-formed entry
  for (int i = 0; table[i]; i++)
    if (table[i] == ' ') {
      if (Warn)
        fprintf(stderr, "ERROR: @IO line missing TABLE:SIGNAL descriptor\n");
      return -1;
    }

  mode_num = -1;
  if (!strcmp(mode, "C64"))
    mode_num = MODE_C64;
  if (!strcmp(mode, "C65"))
    mode_num = MODE_C65;
  if (!strcmp(mode, "GS"))
    mode_num = MODE_MEGA65;
  if (mode_num == -1) {
    fprintf(stderr, "ERROR: Could not parse machine mode '%s'\n", mode);
    return -1;
  }

  // Search for existing table
  int table_num = 0;
  for (; table_num < table_count; table_num++) {
    if ((!strcmp(reg_tables[table_num]->name, table)) && (mode_num == reg_tables[table_num]->mode)) {
      break;
    }
  }
  if (table_num >= table_count) {
    if (table_num >= MAX_TABLES) {
      fprintf(stderr, "ERROR: Too many tables. Fix or increase MAX_TABLES.\n");
      return -1;
    }
    reg_tables[table_num] = calloc(sizeof(struct reg_table), 1);
    if (!reg_tables[table_num]) {
      fprintf(stderr, "ERROR: Could not allocate new register table.\n");
      return -1;
    }
    reg_tables[table_num]->name = strdup(table);
    reg_tables[table_num]->mode = mode_num;
    table_count++;
  }

  // Add entry to table
  if (reg_tables[table_num]->reg_count >= MAX_ENTRIES) {
    fprintf(stderr, "ERROR: Too many entries in register table '%s' for mode '%s'\n", table, mode);
    return -1;
  }
  reg_tables[table_num]->regs[reg_tables[table_num]->reg_count].low_address = low_addr;
  reg_tables[table_num]->regs[reg_tables[table_num]->reg_count].high_address = high_addr;
  reg_tables[table_num]->regs[reg_tables[table_num]->reg_count].low_bit = low_bit;
  reg_tables[table_num]->regs[reg_tables[table_num]->reg_count].high_bit = high_bit;
  sigsplit = strchr(signal, '@');
  if (sigsplit != NULL) { // reference label
    *sigsplit = 0;
    sigsplit++;
    reg_tables[table_num]->regs[reg_tables[table_num]->reg_count].signal = latex_add_break(signal);
    reg_tables[table_num]->regs[reg_tables[table_num]->reg_count].signal_idx = latex_strip_break(sigsplit);
  } else {
    reg_tables[table_num]->regs[reg_tables[table_num]->reg_count].signal = latex_add_break(signal);
    reg_tables[table_num]->regs[reg_tables[table_num]->reg_count].signal_idx = latex_strip_break(signal);
  }
  if (*description == '@') { // reference label
    if (sigsplit != NULL) {
      fprintf(stderr, "WARNING: signal '%s:%s@%s' also is a reference to '%s'!", table, signal, sigsplit, description);
    }
    reg_tables[table_num]->regs[reg_tables[table_num]->reg_count].isRef = 1;
    reg_tables[table_num]->regs[reg_tables[table_num]->reg_count].description = latex_strip_break(description+1);
  } else {
    reg_tables[table_num]->regs[reg_tables[table_num]->reg_count].isRef = 0;
    reg_tables[table_num]->regs[reg_tables[table_num]->reg_count].description = strdup(description);
  }

  reg_tables[table_num]->reg_count++;

  return 0;
}

int scan_vhdl_file(char *file)
{
  int retVal = 0;
  int error_count = 0;

  struct info_block* current_info_block = NULL;

  do {
    char line[8192];
    int line_num = 0;
    FILE* f = fopen(file, "r");
    if (!f) {
      fprintf(stderr, "Could not open input file '%s' for reading.\n", file);
      perror("fopen()");
      retVal = -1;
      break;
    }
    line[0] = 0;
    fgets(line, 8192, f);
    while (line[0]) {
      int offset = 0;

      line_num++;

      // Skip over leading white space
      while (line[offset] == ' ' || line[offset] == '\t')
        offset++;
      // Trim CRLF
      while ((line[strlen(line) - 1] == '\r') || (line[strlen(line) - 1] == '\n'))
        line[strlen(line) - 1] = 0;

      // Look for comments beginning anywhere in the lin
      int is_comment = 0;
      for (; line[offset] && line[offset + 1]; offset++) {
        if (line[offset] == '-' && line[offset + 1] == '-') {
          // It's a comment, so do something!

          is_comment = 1;
          if (!strncmp(&line[offset], "-- @IO:", 7)) {
            // Register short description
            if (parse_io_line(&line[offset])) {
              if (Warn) {
                fprintf(stderr, "%s:%d: ", file, line_num);
                fprintf(stderr, "Error parsing @IO comment: '%s'\n", &line[offset]);
              }
              error_count++;
            }
          }
          else if (!strncmp(&line[offset], "-- @INFO:", 9)) {
            // Beginning of an info block
            char table[8192], signal[8192];
            int n;
            if (sscanf(&line[offset], "-- @INFO:%[^:]:%[^: ]%n", table, signal, &n) == 2) {
              if (line[offset + n]) {
                fprintf(stderr, "%s:%d: ", file, line_num);
                fprintf(stderr, "Malformed @INFO: line: '%s'\n", line);
                retVal = -1;
                break;
              }
              // We have a valid info block.
              // Check if it is a duplicate
              int info_block_num = 0;
              struct reg_table* rt = NULL;
              int table_num = 0;
              for (table_num = 0; table_num < table_count; table_num++) {
                if (!strcmp(reg_tables[table_num]->name, table))
                  break;
              }
              if (table_num >= table_count) {
                // Need to allocate new table
                if (table_count >= MAX_TABLES) {
                  fprintf(stderr, "%s:%d: ", file, line_num);
                  fprintf(stderr, "Too many register tables defined.  Fix or increase MAX_TABLES.\n");
                  retVal = -1;
                  break;
                }
                else {
                  reg_tables[table_num] = calloc(sizeof(struct reg_table), 1);
                  if (!reg_tables[table_num]) {
                    fprintf(stderr, "%s:%d: ", file, line_num);
                    fprintf(stderr, "Failed to allocate new reg_table structure\n");
                    retVal = -1;
                    break;
                  }
                  reg_tables[table_num]->name = strdup(table);
                  reg_tables[table_num]->reg_count = 0;
                  reg_tables[table_num]->info_count = 0;
                  table_count++;
                }
              }
              rt = reg_tables[table_num];

              for (info_block_num = 0; info_block_num < rt->info_count; info_block_num++) {
                if (!strcmp(signal, rt->info_blocks[info_block_num].signal)) {
                  // Found the block
                  break;
                }
              }
              if (info_block_num >= rt->info_count) {
                // New info block, so allocate it
                if (info_block_num >= MAX_ENTRIES) {
                  fprintf(stderr, "%s:%d: ", file, line_num);
                  fprintf(
                      stderr, "Too many information blocks defined in table '%s'.  Fix or increase MAX_ENTRIES.\n", table);
                  retVal = -1;
                  break;
                }
                rt->info_blocks[info_block_num].signal = strdup(signal);
                rt->info_blocks[info_block_num].line_count = 0;
                rt->info_count++;
              }
              // Set current info block to which we record comments
              current_info_block = &rt->info_blocks[info_block_num];
            }
          }
          else {
            // NOT an @IO: comment block
            if (current_info_block) {
              // Append comment line to info block
              if (current_info_block->line_count >= MAX_LINES) {
                fprintf(stderr, "%s:%d: ", file, line_num);
                fprintf(
                    stderr, "Too many lines in info block '%s'.  Fix or increase MAX_LINES.\n", current_info_block->signal);
                retVal = -1;
                break;
              }
              current_info_block->lines[current_info_block->line_count++] = strdup(&line[offset + 3]);
            }
          }
          break;
        }
      }
      if (!is_comment) {
        // It's not a comment. So do nothing, except for mark the end of
        // a multi-line info block, if required.
        current_info_block = NULL;
      }

      if (retVal)
        break;

      line[0] = 0;
      fgets(line, 8192, f);
    }

    fclose(f);

  } while (0);

  if (error_count) {
    fprintf(stderr, "WARNING: Encountered %3d errors while parsing '%s'\n", error_count, file);
  }

  return retVal;
}

int main(int argc, char** argv)
{
  int i = 1;
  if (!strcmp(argv[1], "-q")) // option -q = quiet
  {
    Warn = 0;
    i = 2;
  }
  for (; i < argc; i++)
    scan_vhdl_file(argv[i]);

  fprintf(stderr, "%d tables defined.\n", table_count);

  // Now emit the tables
  for (int t = 0; t < table_count; t++) {
    char filename[1024];
    fprintf(stderr, "(%d) writing regtable_%s.%s.tex\n", t + 1, reg_tables[t]->name, describe_mode(reg_tables[t]->mode));
    snprintf(filename, 1024, "regtable_%s.%s.tex", reg_tables[t]->name, describe_mode(reg_tables[t]->mode));
    FILE* f = fopen(filename, "w");
    if (!f) {
      fprintf(stderr, "ERROR: Could not write to latex file '%s'\n", filename);
      continue;
    }

    clear_table_output();
    for (int reg = 0; reg < reg_tables[t]->reg_count; reg++) {
      table_output_add_reg(&reg_tables[t]->regs[reg]);
    }
    emit_table_output(f);

    if (0)
      fprintf(f, "\\section{%s (%s)}\n", reg_tables[t]->name, describe_mode(reg_tables[t]->mode));
    fclose(f);
  }

  return 0;
}