github.com/westcoastroms/westcoastroms-build@v0.0.0-20190928114312-2350e5a73030/build/make/tools/fs_config/README (about)

     1   _____  _____  _____  _____  __  __  _____
     2  /  _  \/   __\/  _  \|  _  \/  \/  \/   __\
     3  |  _  <|   __||  _  ||  |  ||  \/  ||   __|
     4  \__|\_/\_____/\__|__/|_____/\__ \__/\_____/
     5  
     6  Generating the android_filesystem_config.h:
     7  
     8  To generate the android_filesystem_config.h file, one can choose from
     9  one of two methods. The first method, is to declare
    10  TARGET_ANDROID_FILESYSTEM_CONFIG_H in the device BoardConfig.mk file. This
    11  variable can only have one item in it, and it is used directly as the
    12  android_filesystem_config.h header when building
    13  fs_config_generate_$(TARGET_DEVICE) which is used to generate fs_config_files
    14  and fs_config_dirs target executable.
    15  
    16  The limitation with this, is that it can only be set once, thus if the device
    17  has a make hierarchy, then each device needs its own file, and cannot share
    18  from a common source or that common source needs to include everything from
    19  both devices.
    20  
    21  The other way is to set TARGET_FS_CONFIG_GEN, which can be a list of
    22  intermediate fs configuration files. It is a build error on any one
    23  these conditions:
    24   * Specify TARGET_FS_CONFIG_GEN and TARGET_ANDROID_FILESYSTEM_CONFIG_H
    25   * Specify TARGET_FS_CONFIG_GEN and provide
    26     $(TARGET_DEVICE_DIR)/android_filesystem_config.h
    27  
    28  The parsing of the config file follows the Python ConfigParser specification,
    29  with the sections and fields as defined below. There are two types of sections,
    30  both sections require all options to be specified. The first section type is
    31  the "caps" section.
    32  
    33  The "caps" section follows the following syntax:
    34  
    35  [path]
    36  mode: Octal file mode
    37  user: AID_<user>
    38  group: AID_<group>
    39  caps: cap*
    40  
    41  Where:
    42  
    43  [path]
    44    The filesystem path to configure. A path ending in / is considered a dir,
    45    else its a file.
    46  
    47  mode:
    48    A valid octal file mode of at least 3 digits. If 3 is specified, it is
    49    prefixed with a 0, else mode is used as is.
    50  
    51  user:
    52    Either the C define for a valid AID or the friendly name. For instance both
    53    AID_RADIO and radio are acceptable. Note custom AIDs can be defined in the
    54    AID section documented below.
    55  
    56  group:
    57    Same as user.
    58  
    59  caps:
    60    The name as declared in
    61    system/core/include/private/android_filesystem_capability.h without the
    62    leading CAP_. Mixed case is allowed. Caps can also be the raw:
    63     * binary (0b0101)
    64     * octal (0455)
    65     * int (42)
    66     * hex (0xFF)
    67    For multiple caps, just separate by whitespace.
    68  
    69  It is an error to specify multiple sections with the same [path] in different
    70  files. Note that the same file may contain sections that override the previous
    71  section in Python versions <= 3.2. In Python 3.2 it's set to strict mode.
    72  
    73  
    74  The next section type is the "AID" section, for specifying OEM specific AIDS.
    75  
    76  The AID section follows the following syntax:
    77  
    78  [AID_<name>]
    79  value: <number>
    80  
    81  Where:
    82  
    83  [AID_<name>]
    84    The <name> can contain characters in the set uppercase, numbers
    85    and underscores.
    86  
    87  value:
    88    A valid C style number string. Hex, octal, binary and decimal are supported.
    89    See "caps" above for more details on number formatting.
    90  
    91  It is an error to specify multiple sections with the same [AID_<name>]. With
    92  the same constraints as [path] described above. It is also an error to specify
    93  multiple sections with the same value option. It is also an error to specify a
    94  value that is outside of the inclusive OEM ranges:
    95   * AID_OEM_RESERVED_START(2900) - AID_OEM_RESERVED_END(2999)
    96   * AID_OEM_RESERVED_2_START(5000) - AID_OEM_RESERVED_2_END(5999)
    97  
    98  as defined by system/core/include/private/android_filesystem_config.h.
    99  
   100  Ordering within the TARGET_FS_CONFIG_GEN files is not relevant. The paths for files are sorted
   101  like so within their respective array definition:
   102   * specified path before prefix match
   103   ** ie foo before f*
   104   * lexicographical less than before other
   105   ** ie boo before foo
   106  
   107  Given these paths:
   108  
   109  paths=['ac', 'a', 'acd', 'an', 'a*', 'aa', 'ac*']
   110  
   111  The sort order would be:
   112  paths=['a', 'aa', 'ac', 'acd', 'an', 'ac*', 'a*']
   113  
   114  Thus the fs_config tools will match on specified paths before attempting prefix, and match on the
   115  longest matching prefix.
   116  
   117  The declared AIDS are sorted in ascending numerical order based on the option "value". The string
   118  representation of value is preserved. Both choices were made for maximum readability of the generated
   119  file and to line up files. Sync lines are placed with the source file as comments in the generated
   120  header file.
   121  
   122  For OEMs wishing to use the define AIDs in their native code, one can access the generated header
   123  file like so:
   124    1. In your C code just #include "generated_oem_aid.h" and start using the declared identifiers.
   125    2. In your Makefile add this static library like so: LOCAL_HEADER_LIBRARIES := oemaids_headers
   126  
   127  Unit Tests:
   128  
   129  From within the fs_config directory, unit tests can be executed like so:
   130  $ python -m unittest test_fs_config_generator.Tests
   131  .............
   132  ----------------------------------------------------------------------
   133  Ran 13 tests in 0.004s
   134  
   135  OK
   136  
   137  One could also use nose if they would like:
   138  $ nose2
   139  
   140  To add new tests, simply add a test_<xxx> method to the test class. It will automatically
   141  get picked up and added to the test suite.
   142  
   143  Using the android_filesystem_config.h:
   144  
   145  The tool fs_config_generate is built as a dependency to fs_config_dirs and
   146  fs_config_files host targets, and #includes the above supplied or generated
   147  android_filesystem_config.h file, and can be instructed to generate the binary
   148  data that lands in the device target locations /system/etc/fs_config_dirs and
   149  /system/etc/fs_config_files and in the host's ${OUT} locations
   150  ${OUT}/target/product/<device>/system/etc/fs_config_dirs and
   151  ${OUT}/target/product/<device>/system/etc/fs_config_files. The binary files
   152  are interpreted by the libcutils fs_conf() function, along with the built-in
   153  defaults, to serve as overrides to complete the results. The Target files are
   154  used by filesystem and adb tools to ensure that the file and directory
   155  properties are preserved during runtime operations. The host files in the
   156  ${OUT} directory are used in the final stages when building the filesystem
   157  images to set the file and directory properties.
   158  
   159  For systems with separate partition images, such as vendor or oem,
   160  fs_config_generate can be instructed to filter the specific file references
   161  to land in each partition's etc/fs_config_dirs or etc/fs_config_files
   162  locations. The filter can be instructed to blacklist a partition's data by
   163  providing the comma separated minus sign prefixed partition names. The filter
   164  can be instructed to whitelist partition data by providing the partition name.
   165  
   166  For example:
   167  - For system.img, but not vendor, oem or odm file references:
   168        -P -vendor,-oem,-odm
   169    This makes sure the results only contain content associated with the
   170    system, and not vendor, oem or odm, blacklisting their content.
   171  - For vendor.img file references: -P vendor
   172  - For oem.img file references: -P oem
   173  - For odm.img file references: -P odm
   174  
   175  fs_config_generate --help reports:
   176  
   177  Generate binary content for fs_config_dirs (-D) and fs_config_files (-F)
   178  from device-specific android_filesystem_config.h override. Filter based
   179  on a comma separated partition list (-P) whitelist or prefixed by a
   180  minus blacklist. Partitions are identified as path references to
   181  <partition>/ or system/<partition>
   182  
   183  Usage: fs_config_generate -D|-F [-P list] [-o output-file]