summaryrefslogtreecommitdiffstats
path: root/documentation/rmc
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/rmc')
-rw-r--r--documentation/rmc/README343
1 files changed, 343 insertions, 0 deletions
diff --git a/documentation/rmc/README b/documentation/rmc/README
new file mode 100644
index 00000000..ba476b0e
--- /dev/null
+++ b/documentation/rmc/README
@@ -0,0 +1,343 @@
1Runtime Machine Configuration (RMC)
2--------------------------------------------------------------------------------
3Table of Contents
4
5Introduction
6Usage
7Enable RMC Feature
8Examples
9Troubleshooting
10When you (don't) need RMC feature
11
12
13Introduction:
14--------------------------------------------------------------------------------
15RMC Project - a light-weight project provide developers a mechanism to keep
16their software implementation board-type agnostic, yet still able to customize
17software behavior according to the type of a running board at runtime. Recipes
18and bbclasses are available for other components to reuse to construct their own
19RMC database.
20
21RMC Feature - An end-to-end solution based on RMC project to have a generic
22image capable to apply board-type-specific quirks and configurations for a board
23at runtime. It consists of a modified bootloader (systemd-boot), an updated EFI
24installer, recipes, bbclass and RMC project.
25
26RMC feature supports special customizations cannot be covered by conventional
27auto-detection features based on probing a hardware module because they happen
28at a board or a product level. For example:
29 - tty console for kernel log output in kernel cmdline
30 - default audio route configuration
31 - network configuration
32 - UI layout
33 - requirement to software driven by a mechanical design
34 - or static configuration bits for a physical bus that doesn't support to
35 identify devices or their presence at runtime
36
37An image with the feature has ability to configure supported boards with data
38associated only to a type of board to get full functionality of the target at
39runtime, yet still with a single image.
40
41Effect after installation is identical to what a conventional image specially
42customized for a type of board (depending on the way to deploy image).
43
44Main functions of RMC Feature:
45
46Show board-specific boot entries in boot menu and boot system with configuration
47(boot title, boot options, etc) in a selected boot entry.
48
49Support a "global" kernel boot command line fragment which is effective for all
50boot entries.
51
52Deploy file blobs and create directories specific to the type of running board.
53
54Beside from this document, you can also find several built-in examples in
55common/recipes-bsp/rmc/boards/. Refer to "Examples" section.
56
57You can also add new board types in your layer via a simple variable.
58
59
60
61Usage
62--------------------------------------------------------------------------------
63Developers are suggested to organize all board-specific files in their own layer
64following this example, so that RMC recipes can pick up them correctly in build.
65
66- my_top_dir/ Top directory of your board (Note 0)
67 |- rmc-db.bbappend bbappend file to rmc-db recipe at a lower level
68 |- rmc/
69 |- target_board_1/ subdirectory of a board.
70 | |- board1.fp fingerprint file must be provided (NOTE 1)
71 | |- BOOTENTRY.CONFIG optional config file for boot entries. (NOTE 2)
72 | |- INSTALLER.CONFIG optional config file for installer. (NOTE 3)
73 | |- board_file_1 A file blob specific to the type of board
74 | |- board_file_2 An another file specific to the type of board
75 | |- ...more files
76 |- target_board_2/ subdirectory of another board.
77 |- board_2_v2.fp fingerprint file for board 2.
78 |- BOOTENTRY.CONFIG
79 |- INSTALLER.CONFIG
80 |- board_file_1
81 |- ...more files
82
83Note 0:
84To add your boards into RMC feature, simply put this line in your
85rmc-db.bbappend:
86
87RMC_BOARD_DATA_DIRS_append := " ${THISDIR}/my_top_dir"
88
89RMC db recipe takes all top directories specified in RMC_BOARD_DATA_DIRS to
90construct and deploy a central RMC database inside image. The bbclass of the
91bare RMC project also provide function for other components to construct their
92own RMC database file. Please refer to rmc-db.bbclass for more information.
93
94Subdirectory is not supported in a board's directory.
95
96Note 1:
97Fingerprint files must be provided and with ".fp" at the end of their names.
98Fingerprint can be obtained by running RMC tool on your board. An easy way is to
99live-boot USB stick flashed with any image enabled this feature on your board,
100then run this command:
101
102# rmc -F -o my_board.fp
103
104Or you will need to build RMC tool for the architecture of your board, 32 or
10564 bit x86, from RMC project.
106
107You can run RMC tool without any argument to get usage and examples.
108
109DO NOT NAME ANY FILE ENDING WITH '.fp' IF IT IS NOT A RMC FINGERPRINT FILE.
110
111If you do need a .fp file deployed onto target, please rename it in source and
112specify the real name of file on target in INSTALLER.CONFIG.
113
114Note 2:
115At runtime, RMC bootloader tries to fetch this file specific to the board at run
116time, then tries to fetch each boot entry file specified in BOOTENTRY.CONFIG and
117show them in boot menu options. The format of this file is very simple. Each
118line is the name of a boot entry file:
119
120boot.conf
121Install.conf
122myrmcboot.conf
123
124Name of a boot entry file is defined by developer so it can be anything. But the
125name of config file is what RMC bootloader looks up in RMC database, so it must
126be named BOOTENTRY.CONFIG.
127
128Bootloader skips loading entry conf files from disk once any entry is loaded
129from RMC database.
130
131Note 3:
132At runtime, RMC installer tries to fetch INSTALLER.CONFIG file specific to the
133board, then tries to fetch each file specified in this config file, and then
134deploy the file onto target with its permissions, UID, GID and other attributes
135also specified in this config file if file for the board can be retrieved from
136RMC database. The format of this file is (# is for comment line)
137
138# name:uid:gid:mode:path_on_target
139# to create a directory, add a “/” at the end of path_on_target:
140audio_policy:0:0:600:/etc/audio/
141audio_def_policy:0:0:600:/etc/audio/audio_policy
142
143The above example creates /etc/audio directory first, then fetch a file named
144“audio_def_policy” from RMC database for the board, then copy it to /etc/audio/
145with a new name “audio_policy”.
146
147If this config file is not provided, No data in RMC database is deployed to the
148target.
149
150Some steps defined by developers could not be supported on a filesystem.
151Installer simply ignores any errors in RMC deployment stage.
152
153The name of this config file is what installer looks up first, so it must be
154INSTALLER.CONFIG.
155
156
157
158Enable RMC Feature
159--------------------------------------------------------------------------------
160To Enable RMC feature in build, add the below lines in a conf file:
161DISTRO_FEATURES_append = " rmc"
162EFI_PROVIDER = "rmc-systemd-boot"
163
164Note:
165Image could be still bootable if you only have either of two lines, but RMC
166feature won't be fully functional.
167
168
169
170Examples
171--------------------------------------------------------------------------------
172We checked in configuration data in common/recipes-bsp/rmc/boards/ for several
173boards, to help users to understand the RMC feature. These examples are also for
174validation. For any example you find not working as what this section depicts,
175it should be treated as a bug to be fixed.
176
177To test this feature with examples, enable it and build an image first, then
178boot the built image on supported boards. Examples are always built in when the
179feature is enabled, except for the EXAMPLE 1.
180
181EXAMPLE 1: Support a new board type:
182(1) enable the feature and do a build to get a live-boot image by adding these
183 lines in conf/local.conf:
184 DISTRO_FEATURES_append = " rmc"
185 EFI_PROVIDER = "rmc-systemd-boot"
186
187(2) flash the image to a USB stick and boot it on your board
188
189(3) in super user mode, run "rmc -F -o my_board.fp"
190
191(4) create directories in your host "mkdir -p my_top_dir/my_rmc/my_board"
192
193(5) copy my_board.fp from target to my_top_dir/my_rmc/my_board/ on host
194
195(6) create a file my_top_dir/my_rmc/my_board/KBOOTPARAM, put some fake
196 and harmless options in a single line, say, "loglevel=7"
197
198(7) create a file my_top_dir/rmc-db.bbappend, put this single line in it:
199 RMC_BOARD_DATA_DIRS_append := " ${THISDIR}/my_rmc"
200 From parent directory of my_top_dir, the tree should look like:
201 my_top_dir/
202 my_rmc/
203 my_board/
204 KBOOTPARAM
205 my_board.fp
206 rmc-db.bbappend
207 Later, you can add more board directories in my_rmc directory.
208
209(8) modify build configuration to add my_top_dir into build, for example, put
210 this line in a bblayers.conf:
211 BBFILES += "/full/path/of/my_top_dir/rmc-db.bbappend"
212
213(9) build image again then boot it on your board
214
215(10) Once you login to shell, new options should be effective, run this command
216 "cat /proc/cmdline" to verify the result.
217
218EXAMPLE 2: Board-specific boot entry
219MinnowBoard MAX and B3 version:
220common/recipes-bsp/rmc/boards/minnowmax
221common/recipes-bsp/rmc/boards/minnowmaxB3
222
223We have found two identities (type of board) exist for the "same" Minnow Max
224hardware, so they have to be treated as two different types of hardware. The two
225examples show you a boot entry specific to a type of board. Titles shown in boot
226menu have different names according to the type of running board, "Minnow Max
227boot" or "Minnow Max B3 boot". in /proc/cmdline, "console=ttyS0,115200n8" shall
228be there. Kernel prints logs from 6-pin FTDI serial port on Minnow Max(s). This
229console setting is in board-specific entries, so you won't see it effective if
230you select default "boot" entry to boot the device.
231
232EXAMPLE 3: Board-specific boot entry, global kernel cmdline and installer
233NUC Gen 6:
234common/recipes-bsp/rmc/boards/nucgen6
235This is a combo example with all supported configuration data for NUC Gen 6
236product. It shows two boot entries in bootloader menu when you boot image on NUC
237Gen 6 product, with "NUC Gen6" in entry titles. There shall no any "console=" in
238/proc/cmdline when you boot with either of two "NUC Gen6"entries. We designed it
239this way because there is no accessible tty port on NUC Gen 6 with housing.
240
241This example also includes a global kernel cmdline fragment KBOOTPARAM. Content
242of KBOOTPARAM shall be at the end of /proc/cmdline no matter which boot entry
243you selected to boot NUC Gen6.
244
245INSTALLER.CONFIG directs installer to create a directory and deploy a file in it
246when install the image on NUC Gen6.
247
248Choose "NUC Gen6 install" boot entry to boot shall start installation. Once
249the device reboots after installation, we can verify the configurations.
250
251The boot entry "NUC Gen6 boot" shall be shown in boot menu.
252
253The content of KBOOTPARAM shall be in /proc/cmdline too.
254
255A directory /etc/mylib/ is created and a file "mylib.conf" is there. The content
256of that file shall be what we put in mylib.conf in
257common/recipes-bsp/rmc/boards/nucgen6
258
259EXAMPLE 4: For validation only
260T100 (32bit):
261common/recipes-bsp/rmc/boards/T100-32bit
262This example is provided for validation on 32 bit X86 architecture. It doesn't
263provide any new function not mentioned in above examples.
264
265
266
267Troubleshooting
268--------------------------------------------------------------------------------
269Issue: Cannot obtain RMC fingerprint for a board
270
271RMC tool requires UEFI BIOS and SMBIOS support in firmware. It doesn't support
272other type of firmware, e.g. legacy BIOS. It also requires EFI driver enabled
273in Linux kernel.
274
275Issue: Configuration for a board seems not effective at runtime.
276
277Check if board is booted from the storage where the image or installation lives
278when you have multiple boot options in BIOS. On some old hardwares it is not
279that obvious as you assume. A build image can support boot from both of legacy
280and UEFI mode, but RMC only works with UEFI boot so far.
281
282Make sure configuration files (BOOTENTRY.CONFIG, INSTALLER.CONFIG and,
283KBOOTPARAM ...) are properly named in the board directory.
284
285Make sure configuration files have correct contents.
286
287Some file attributes could not be supported by targeted file system. Installer
288cannot setup file blobs as you wish. It simply move to the next step if a step
289fails.
290
291Kernel command line can be customized globally with KBOOTPARAM or just in a boot
292entry for the type of board. They have different effective scopes.
293
294If no any board-specific configuration becomes effective on your board but it
295works on other boards of same product, you can run rmc tool to obtain
296fingerprint file on your board and compare it with fingerprint of a working
297board. It is possible they have different firmware versions and unluckily, some
298information for fingerprint changes between two versions. You can update BIOS
299on every board to the same BIOS version if it is feasible. Otherwise you have
300to treat them as two different type of boards. We could extend rmc design to
301allow multiple fingerprints in a board directory as a workaround.
302
303Issue: RMC reports error because it cannot find fingerprint when building image.
304
305Make sure you have a fingerprint file. Its name must be ended with '.fp'. You
306can put a fingerprint file in a board directory and provide data later.
307
308Issue: Any problems the above troubleshooting cannot help
309
310Please report it to us. Extra information like the type of your board or a dump
311file from dmidecode tool is helpful. We will investigate the problem and keep
312improving this feature.
313
314
315
316
317When you (don't) need RMC feature
318--------------------------------------------------------------------------------
319RMC feature is designed to as generic as possible, in order to support a large
320number of types of boards. And it shall be designed not to break things when it
321is disabled. These considerations help users to decide if they really need or
322enable it.
323
324If you are satisfied with a dedicated build target and image for each board in
325your development cycle (source, build, validation, release, etc), you don't need
326this feature.
327
328If you have a generic build for multiple type of boards and features supported
329by that build meet your needs to functionality on all of boards, you don't need
330to have this feature or you can disable it until you need to check in the first
331board's data, in order to apply a quirk or customization only for that board.
332
333If you want this feature but have concerns to see more and more boards' finger-
334prints and data in a generic project, you can have another layer to hold all of
335board-specific data to split them from a generic layer at source level. Another
336suggestion is always seeking chances not to clone or copy a common configuration
337to each board's directory.
338
339
340
341Thanks
342
343Jianxun Zhang <jianxun.zhang@linux.intel.com>