Home | History | Annotate | Download | only in fs_config 
      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_STATIC_LIBRARIES := liboemaids
    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 fs_config_generate --help reports:
    160 
    161 Generate binary content for fs_config_dirs (-D) and fs_config_files (-F)
    162 from device-specific android_filesystem_config.h override
    163 
    164 Usage: fs_config_generate -D|-F [-o output-file]
    165