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