doc/tablegen.txt

   1 Writing a table generator
   2
   3 This documentation is preliminary.
   4 Parts of the API are not good and should be changed.
   5
   6 Basic concepts
   7
   8 A table generator consists of two files, *_tablegen.c and *_tablegen.h.
   9 The .h file will provide the variable declarations and initialization
  10 code for the tables, the .c calls the initialization code and then prints
  11 the tables as a header file using the tableprint.h helpers.
  12 Both of these files will be compiled for the host system, so to avoid
  13 breakage with cross-compilation neither of them may include, directly
  14 or indirectly, config.h or avconfig.h.
  15 This means that e.g. libavutil/mathematics.h is ok but libavutil/libm.h is not.
  16 Due to this, the .c file or Makefile may have to provide additional defines
  17 or stubs, though if possible this should be avoided.
  18 In particular, CONFIG_HARDCODED_TABLES should always be defined to 0.
  19
  20 The .c file
  21
  22 This file should include the *_tablegen.h and tableprint.h files and
  23 anything else it needs as long as it does not depend on config.h or
  24 avconfig.h.
  25 In addition to that it must contain a main() function which initializes
  26 all tables by calling the init functions from the .h file and then prints
  27 them.
  28 The printing code typically looks like this:
  29     write_fileheader();
  30     printf("static const uint8_t my_array[100] = {\n");
  31     write_uint8_t_array(my_array, 100);
  32     printf("};\n");
  33
  34 This is the more generic form, in case you need to do something special.
  35 Usually you should instead use the short form:
  36     write_fileheader();
  37     WRITE_ARRAY("static const", uint8_t, my_array);
  38
  39 write_fileheader() adds some minor things like a "this is a generated file"
  40 comment and some standard includes.
  41 tablegen.h defines some write functions for one- and two-dimensional arrays
  42 for standard types - they print only the "core" parts so they are easier
  43 to reuse for multi-dimensional arrays so the outermost {} must be printed
  44 separately.
  45 If there's no standard function for printing the type you need, the
  46 WRITE_1D_FUNC_ARGV macro is a very quick way to create one.
  47 See libavcodec/dv_tablegen.c for an example.
  48
  49
  50 The .h file
  51
  52 This file should contain:
  53  - one or more initialization functions
  54  - the table variable declarations
  55 If CONFIG_HARDCODED_TABLES is set, the initialization functions should
  56 not do anything, and instead of the variable declarations the
  57 generated *_tables.h file should be included.
  58 Since that will be generated in the build directory, the path must be
  59 included, i.e.
  60 #include "libavcodec/example_tables.h"
  61 not
  62 #include "example_tables.h"
  63
  64 Makefile changes
  65
  66 To make the automatic table creation work, you must manually declare the
  67 new dependency.
  68 For this add a line similar to this:
  69 $(SUBDIR)example.o: $(SUBDIR)example_tables.h
  70 under the "ifdef CONFIG_HARDCODED_TABLES" section in the Makefile.