| 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. |