Originally committed as revision 22722 to svn://svn.ffmpeg.org/ffmpeg/trunk
Unified · Split
| @@ -0,0 +1,57 @@ | |||
| 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. | ||