Add some documentation about the table generation code.
[ffmpeg.git] / 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 describes the tables so they can be printed
11 as a header file.
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 Due to this, the .c file or Makefile may have to provide additional defines
16 or stubs, though if possible this should be avoided.
17
18 The .c file
19
20 This file should include the *_tablegen.h and tableprint.h files and
21 anything else it needs as long as it does not depend on config.h or
22 avconfig.h.
23 In addition to that it must contain a void tableinit(void) function
24 which initializes all tables by calling the init functions from the .h
25 file.
26 It must also contain a "const struct tabledef tables[]" array describing
27 the tables to be generated.
28 Its entries consist of (in order):
29  - a string suitable for declaring the table, up to but not including the =
30    NULL terminates the table
31  - a function to print the table - tableprint.h defines some defaults,
32    e.g. write_uint8_array to print a uint8_t array.
33  - a pointer to the table
34  - the size of the first dimension of the array
35  - if applicable, the size of the second dimension of the array
36
37 The .h file
38
39 This file should contain:
40  - one or more initialization functions
41  - the table variable declarations
42 If CONFIG_HARDCODED_TABLES is set, the initialization functions should
43 not do anything, and instead of the variable declarations the
44 generated *_tables.h file should be included.
45 Since that will be generated in the build directory, the path must be
46 included, i.e.
47 #include "libavcodec/example_tables.h"
48 not
49 #include "example_tables.h"
50
51 Makefile changes
52
53 To make the automatic table creation work, you must manually declare the
54 new dependency.
55 For this add a line similar to this:
56 $(SUBDIR)example.o: $(SUBDIR)example_tables.h
57 under the "ifdef CONFIG_HARDCODED_TABLES" section in the Makefile.