summaryrefslogtreecommitdiffstats
path: root/documentation/rmc
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/rmc')
-rw-r--r--documentation/rmc/README373
1 files changed, 0 insertions, 373 deletions
diff --git a/documentation/rmc/README b/documentation/rmc/README
deleted file mode 100644
index 2c352f29..00000000
--- a/documentation/rmc/README
+++ /dev/null
@@ -1,373 +0,0 @@
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 | |- POSTINSTALL.sh optional script hook for installer (NOTE 4)
74 | |- board_file_1 A file blob specific to the type of board
75 | |- board_file_2 An another file specific to the type of board
76 | |- ...more files
77 |- target_board_2/ subdirectory of another board.
78 |- board_2_v2.fp fingerprint file for board 2.
79 |- BOOTENTRY.CONFIG
80 |- INSTALLER.CONFIG
81 |- board_file_1
82 |- ...more files
83
84Note 0:
85Developers are expected to use variable RMC_BOARD_DATA_DIRS to specify data of
86boards packed into RMC database file generated in a build. The default value of
87the variable in meta-intel specifies a group of boards. They work as examples
88and necessary quirks for these boards to function properly. Developers can
89override, append to the default boards with data of their own boards in the
90database file, or even disable the generation of the database file.
91
92For example, in your local.conf file:
93
94This line adds your boards along with the default boards into RMC database file,
95assuming you have a directory named "rmc" which has a subdirectory for each
96board:
97
98RMC_BOARD_DATA_DIRS_append = " /path_of/rmc"
99
100This line directs RMC to pack data of your boards only, without data of the
101default boards in meta-intel:
102
103RMC_BOARD_DATA_DIRS = "/path_of/rmc"
104
105And this line disables database generation:
106
107RMC_BOARD_DATA_DIRS = ""
108
109Please also refer to the "Example 1" in this document.
110
111Subdirectory is not supported in a board's directory.
112
113Note 1:
114Fingerprint files must be provided and with ".fp" at the end of their names.
115Fingerprint can be obtained by running RMC tool on your board. An easy way is to
116live-boot USB stick flashed with any image enabled this feature on your board,
117then run this command:
118
119# rmc -F -o my_board.fp
120
121Or you will need to build RMC tool for the architecture of your board, 32 or
12264 bit x86, from RMC project.
123
124You can run RMC tool without any argument to get usage and examples.
125
126DO NOT NAME ANY FILE ENDING WITH '.fp' IF IT IS NOT A RMC FINGERPRINT FILE.
127
128If you do need a .fp file deployed onto target, please rename it in source and
129specify the real name of file on target in INSTALLER.CONFIG.
130
131Note 2:
132At runtime, RMC bootloader tries to fetch this file specific to the board at run
133time, then tries to fetch each boot entry file specified in BOOTENTRY.CONFIG and
134show them in boot menu options. The format of this file is very simple. Each
135line is the name of a boot entry file:
136
137boot.conf
138Install.conf
139myrmcboot.conf
140
141Name of a boot entry file is defined by developer so it can be anything. But the
142name of config file is what RMC bootloader looks up in RMC database, so it must
143be named BOOTENTRY.CONFIG.
144
145Bootloader skips loading entry conf files from disk once any entry is loaded
146from RMC database.
147
148Note 3:
149At runtime, RMC installer tries to fetch INSTALLER.CONFIG file specific to the
150board, then tries to fetch each file specified in this config file, and then
151deploy the file onto target with its permissions, UID, GID and other attributes
152also specified in this config file if file for the board can be retrieved from
153RMC database. The format of this file is (# is for comment line)
154
155# name:uid:gid:mode:path_on_target
156# to create a directory, add a “/” at the end of path_on_target:
157audio_policy:0:0:600:/etc/audio/
158audio_def_policy:0:0:600:/etc/audio/audio_policy
159
160The above example creates /etc/audio directory first, then fetch a file named
161“audio_def_policy” from RMC database for the board, then copy it to /etc/audio/
162with a new name “audio_policy”.
163
164If this config file is not provided, No data in RMC database is deployed to the
165target.
166
167Some steps defined by developers could not be supported on a filesystem.
168Installer simply ignores any errors in RMC deployment stage.
169
170The name of this config file is what installer looks up first, so it must be
171INSTALLER.CONFIG.
172
173Note 4:
174At the end of RMC deployment during installation, RMC installer queries a script
175file POSTINSTALL.sh from RMC database file, and execute it when query is
176successful on the running board. This hook provides developers almost ultimate
177flexibility to retouch what have been deployed on the target. There are some
178steps still can override results from this hook for boot entries and KBOOTPARAM.
179
180
181
182Enable RMC Feature
183--------------------------------------------------------------------------------
184To enable the RMC feature please add the following variables to your local.conf.
185
186DISTRO_FEATURES_append = " rmc"
187EFI_PROVIDER = "rmc-boot"
188
189The default EFI bootloader used with RMC is systemd-boot. To change the default
190bootloader please overwrite the RMC_BOOTLOADER variable in your local.conf
191
192Note:
193Image could be still bootable if you only have either of two lines, but RMC
194feature could not be fully functional, depending on the availability of the
195database file, installer and the rmc tool.
196
197Examples
198--------------------------------------------------------------------------------
199We checked in configuration data in common/recipes-bsp/rmc/boards/ for several
200boards, to help users to understand the RMC feature. These examples are also for
201validation. For any example you find not working as what this section depicts,
202it should be treated as a bug to be fixed.
203
204To test this feature with examples, enable it and build an image first, then
205boot the built image on supported boards. Examples are always built in when the
206feature is enabled, except for the EXAMPLE 1.
207
208EXAMPLE 1: Support a new board type:
209(1) enable the feature and do a build to get a live-boot image by adding these
210 lines in conf/local.conf:
211 DISTRO_FEATURES_append = " rmc"
212 EFI_PROVIDER = "rmc-boot"
213
214(2) flash the image to a USB stick and boot it on your board
215
216(3) in super user mode, run "rmc -F -o my_board.fp"
217
218(4) create directories in your host "mkdir -p my_top_dir/my_rmc/my_board"
219
220(5) copy my_board.fp from target to my_top_dir/my_rmc/my_board/ on host
221
222(6) create a file my_top_dir/my_rmc/my_board/KBOOTPARAM, put some fake
223 and harmless options in a single line, say, "loglevel=7"
224
225(7) create a file my_top_dir/rmc-db.bbappend, put this single line in it:
226 RMC_BOARD_DATA_DIRS_append := " ${THISDIR}/my_rmc"
227 From parent directory of my_top_dir, the tree should look like:
228 my_top_dir/
229 my_rmc/
230 my_board/
231 KBOOTPARAM
232 my_board.fp
233 rmc-db.bbappend
234 Later, you can add more board directories in my_rmc directory.
235
236(8) modify build configuration to add my_top_dir into build, for example, put
237 this line in a bblayers.conf:
238 BBFILES += "/full/path/of/my_top_dir/rmc-db.bbappend"
239
240(9) build image again then boot it on your board
241
242(10) Once you login to shell, new options should be effective, run this command
243 "cat /proc/cmdline" to verify the result.
244
245EXAMPLE 2: Board-specific boot entry
246MinnowBoard MAX and B3 version:
247common/recipes-bsp/rmc/boards/minnowmax
248common/recipes-bsp/rmc/boards/minnowmaxB3
249
250We have found two identities (type of board) exist for the "same" Minnow Max
251hardware, so they have to be treated as two different types of hardware. The two
252examples show you a boot entry specific to a type of board. Titles shown in boot
253menu have different names according to the type of running board, "Minnow Max
254boot" or "Minnow Max B3 boot". in /proc/cmdline, "console=ttyS0,115200n8" shall
255be there. Kernel prints logs from 6-pin FTDI serial port on Minnow Max(s). This
256console setting is in board-specific entries, so you won't see it effective if
257you select default "boot" entry to boot the device.
258
259EXAMPLE 3: Board-specific boot entry, global kernel cmdline and installer
260NUC Gen 6:
261common/recipes-bsp/rmc/boards/nucgen6
262This is a combo example with all supported configuration data for NUC Gen 6
263product. It shows two boot entries in bootloader menu when you boot image on NUC
264Gen 6 product, with "NUC Gen6" in entry titles. There shall no any "console=" in
265/proc/cmdline when you boot with either of two "NUC Gen6"entries. We designed it
266this way because there is no accessible tty port on NUC Gen 6 with housing. The
267post-install hook is also provided in this example.
268
269This example also includes a global kernel cmdline fragment KBOOTPARAM. Content
270of KBOOTPARAM shall be at the end of /proc/cmdline no matter which boot entry
271you selected to boot NUC Gen6.
272
273INSTALLER.CONFIG directs installer to create a directory and deploy a file in it
274when install the image on NUC Gen6.
275
276Choose "NUC Gen6 install" boot entry to boot shall start installation. Once
277the device reboots after installation, we can verify the configurations.
278
279The boot entry "NUC Gen6 boot" shall be shown in boot menu.
280
281The content of KBOOTPARAM shall be in /proc/cmdline too.
282
283A directory /etc/mylib/ is created and a file "mylib.conf" is there. The content
284of that file shall be what we put in mylib.conf in
285common/recipes-bsp/rmc/boards/nucgen6
286
287POSTINSTALL.sh shows how we get rid of an error message caused by no serial
288console available on NUC Gen 6, without creating another static board
289configuration.
290
291EXAMPLE 4: For validation only
292T100 (32bit):
293common/recipes-bsp/rmc/boards/T100-32bit
294This example is provided for validation on 32 bit X86 architecture. It doesn't
295provide any new function not mentioned in above examples.
296
297Troubleshooting
298--------------------------------------------------------------------------------
299Issue: Cannot obtain RMC fingerprint for a board
300
301RMC tool requires UEFI BIOS and SMBIOS support in firmware. It doesn't support
302other type of firmware, e.g. legacy BIOS. It also requires EFI driver enabled
303in Linux kernel.
304
305Issue: Configuration for a board seems not effective at runtime.
306
307Check if board is booted from the storage where the image or installation lives
308when you have multiple boot options in BIOS. On some old hardwares it is not
309that obvious as you assume. A build image can support boot from both of legacy
310and UEFI mode, but RMC only works with UEFI boot so far.
311
312Make sure configuration files (BOOTENTRY.CONFIG, INSTALLER.CONFIG and,
313KBOOTPARAM ...) are properly named in the board directory.
314
315Make sure configuration files have correct contents.
316
317Some file attributes could not be supported by targeted file system. Installer
318cannot setup file blobs as you wish. It simply move to the next step if a step
319fails.
320
321Kernel command line can be customized globally with KBOOTPARAM or just in a boot
322entry for the type of board. They have different effective scopes.
323
324If no any board-specific configuration becomes effective on your board but it
325works on other boards of same product, you can run rmc tool to obtain
326fingerprint file on your board and compare it with fingerprint of a working
327board. It is possible they have different firmware versions and unluckily, some
328information for fingerprint changes between two versions. You can update BIOS
329on every board to the same BIOS version if it is feasible. Otherwise you have
330to treat them as two different type of boards. We could extend rmc design to
331allow multiple fingerprints in a board directory as a workaround.
332
333Issue: RMC reports error because it cannot find fingerprint when building image.
334
335Make sure you have a fingerprint file. Its name must be ended with '.fp'. You
336can put a fingerprint file in a board directory and provide data later.
337
338Issue: Any problems the above troubleshooting cannot help
339
340Please report it to us. Extra information like the type of your board or a dump
341file from dmidecode tool is helpful. We will investigate the problem and keep
342improving this feature.
343
344
345
346
347When you (don't) need RMC feature
348--------------------------------------------------------------------------------
349RMC feature is designed to as generic as possible, in order to support a large
350number of types of boards. And it shall be designed not to break things when it
351is disabled. These considerations help users to decide if they really need or
352enable it.
353
354If you are satisfied with a dedicated build target and image for each board in
355your development cycle (source, build, validation, release, etc), you don't need
356this feature.
357
358If you have a generic build for multiple type of boards and features supported
359by that build meet your needs to functionality on all of boards, you don't need
360to have this feature or you can disable it until you need to check in the first
361board's data, in order to apply a quirk or customization only for that board.
362
363If you want this feature but have concerns to see more and more boards' finger-
364prints and data in a generic project, you can have another layer to hold all of
365board-specific data to split them from a generic layer at source level. Another
366suggestion is always seeking chances not to clone or copy a common configuration
367to each board's directory.
368
369
370
371Thanks
372
373Jianxun Zhang <jianxun.zhang@linux.intel.com>