1 _____  _____  _____  _____  __  __  _____
2/  _  \/   __\/  _  \|  _  \/  \/  \/   __\
3|  _  <|   __||  _  ||  |  ||  \/  ||   __|
4\__|\_/\_____/\__|__/|_____/\__ \__/\_____/
5
6The fs_config_generator.py tool uses the platform android_filesystem_config.h and the
7TARGET_FS_CONFIG_GEN files to generate the fs_config_dirs and fs_config_files files for each
8partition, as well as passwd and group files, and the generated_oem_aid.h header.
9
10The fs_config_dirs and fs_config_files binary files are interpreted by the libcutils fs_config()
11function, along with the built-in defaults, to serve as overrides to complete the results. The
12Target files are used by filesystem and adb tools to ensure that the file and directory properties
13are preserved during runtime operations. The host files in the ${OUT} directory are used in the
14final stages when building the filesystem images to set the file and directory properties.
15
16See ./fs_config_generator.py fsconfig --help for how these files are generated.
17
18The passwd and group files are formatted as documented in man pages passwd(5) and group(5) and used
19by bionic for implementing getpwnam() and related functions.
20
21See ./fs_config_generator.py passwd --help and ./fs_config_generator.py group --help for how these
22files are generated.
23
24The generated_oem_aid.h creates identifiers for non-platform AIDs for developers wishing to use them
25in their native code.  To do so, include the oemaids_headers header library in the corresponding
26makefile and #include "generated_oem_aid.h" in the code wishing to use these identifiers.
27
28See ./fs_config_generator.py oemaid --help for how this file is generated.
29
30The parsing of the TARGET_FS_CONFIG_GEN files follows the Python ConfigParser specification, with
31the sections and fields as defined below. There are two types of sections, both sections require all
32options to be specified. The first section type is the "caps" section.
33
34The "caps" section follows the following syntax:
35
36[path]
37mode: Octal file mode
38user: AID_<user>
39group: AID_<group>
40caps: cap*
41
42Where:
43
44[path]
45  The filesystem path to configure. A path ending in / is considered a dir,
46  else its a file.
47
48mode:
49  A valid octal file mode of at least 3 digits. If 3 is specified, it is
50  prefixed with a 0, else mode is used as is.
51
52user:
53  Either the C define for a valid AID or the friendly name. For instance both
54  AID_RADIO and radio are acceptable. Note custom AIDs can be defined in the
55  AID section documented below.
56
57group:
58  Same as user.
59
60caps:
61  The name as declared in
62  system/core/include/private/android_filesystem_capability.h without the
63  leading CAP_. Mixed case is allowed. Caps can also be the raw:
64   * binary (0b0101)
65   * octal (0455)
66   * int (42)
67   * hex (0xFF)
68  For multiple caps, just separate by whitespace.
69
70It is an error to specify multiple sections with the same [path] in different
71files. Note that the same file may contain sections that override the previous
72section in Python versions <= 3.2. In Python 3.2 it's set to strict mode.
73
74
75The next section type is the "AID" section, for specifying OEM specific AIDS.
76
77The AID section follows the following syntax:
78
79[AID_<name>]
80value: <number>
81
82Where:
83
84[AID_<name>]
85  The <name> can contain characters in the set uppercase, numbers
86  and underscores.
87
88value:
89  A valid C style number string. Hex, octal, binary and decimal are supported.
90  See "caps" above for more details on number formatting.
91
92It is an error to specify multiple sections with the same [AID_<name>]. With
93the same constraints as [path] described above. It is also an error to specify
94multiple sections with the same value option. It is also an error to specify a
95value that is outside of the inclusive OEM ranges:
96 * AID_OEM_RESERVED_START(2900) - AID_OEM_RESERVED_END(2999)
97 * AID_OEM_RESERVED_2_START(5000) - AID_OEM_RESERVED_2_END(5999)
98
99as defined by system/core/include/private/android_filesystem_config.h.
100
101Ordering within the TARGET_FS_CONFIG_GEN files is not relevant. The paths for files are sorted
102like so within their respective array definition:
103 * specified path before prefix match
104 ** ie foo before f*
105 * lexicographical less than before other
106 ** ie boo before foo
107
108Given these paths:
109
110paths=['ac', 'a', 'acd', 'an', 'a*', 'aa', 'ac*']
111
112The sort order would be:
113paths=['a', 'aa', 'ac', 'acd', 'an', 'ac*', 'a*']
114
115Thus the fs_config tools will match on specified paths before attempting prefix, and match on the
116longest matching prefix.
117
118The declared AIDS are sorted in ascending numerical order based on the option "value". The string
119representation of value is preserved. Both choices were made for maximum readability of the generated
120file and to line up files. Sync lines are placed with the source file as comments in the generated
121header file.
122
123Unit Tests:
124
125From within the fs_config directory, unit tests can be executed like so:
126$ python -m unittest test_fs_config_generator.Tests
127.............
128----------------------------------------------------------------------
129Ran 13 tests in 0.004s
130
131OK
132
133One could also use nose if they would like:
134$ nose2
135
136To add new tests, simply add a test_<xxx> method to the test class. It will automatically
137get picked up and added to the test suite.
138