"Fossies" - the Fresh Open Source Software Archive

Member "ffmpeg-3.4.2/doc/tablegen.txt" (29 Mar 2016, 2793 Bytes) of package /linux/misc/ffmpeg-3.4.2.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    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.