diff options
Diffstat (limited to 'documentation/dev-manual/new-machine.rst')
-rw-r--r-- | documentation/dev-manual/new-machine.rst | 118 |
1 files changed, 118 insertions, 0 deletions
diff --git a/documentation/dev-manual/new-machine.rst b/documentation/dev-manual/new-machine.rst new file mode 100644 index 0000000000..469b2d395a --- /dev/null +++ b/documentation/dev-manual/new-machine.rst | |||
@@ -0,0 +1,118 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | ||
2 | |||
3 | Adding a New Machine | ||
4 | ******************** | ||
5 | |||
6 | Adding a new machine to the Yocto Project is a straightforward process. | ||
7 | This section describes how to add machines that are similar to those | ||
8 | that the Yocto Project already supports. | ||
9 | |||
10 | .. note:: | ||
11 | |||
12 | Although well within the capabilities of the Yocto Project, adding a | ||
13 | totally new architecture might require changes to ``gcc``/``glibc`` | ||
14 | and to the site information, which is beyond the scope of this | ||
15 | manual. | ||
16 | |||
17 | For a complete example that shows how to add a new machine, see the | ||
18 | ":ref:`bsp-guide/bsp:creating a new bsp layer using the \`\`bitbake-layers\`\` script`" | ||
19 | section in the Yocto Project Board Support Package (BSP) Developer's | ||
20 | Guide. | ||
21 | |||
22 | Adding the Machine Configuration File | ||
23 | ===================================== | ||
24 | |||
25 | To add a new machine, you need to add a new machine configuration file | ||
26 | to the layer's ``conf/machine`` directory. This configuration file | ||
27 | provides details about the device you are adding. | ||
28 | |||
29 | The OpenEmbedded build system uses the root name of the machine | ||
30 | configuration file to reference the new machine. For example, given a | ||
31 | machine configuration file named ``crownbay.conf``, the build system | ||
32 | recognizes the machine as "crownbay". | ||
33 | |||
34 | The most important variables you must set in your machine configuration | ||
35 | file or include from a lower-level configuration file are as follows: | ||
36 | |||
37 | - :term:`TARGET_ARCH` (e.g. "arm") | ||
38 | |||
39 | - ``PREFERRED_PROVIDER_virtual/kernel`` | ||
40 | |||
41 | - :term:`MACHINE_FEATURES` (e.g. "screen wifi") | ||
42 | |||
43 | You might also need these variables: | ||
44 | |||
45 | - :term:`SERIAL_CONSOLES` (e.g. "115200;ttyS0 115200;ttyS1") | ||
46 | |||
47 | - :term:`KERNEL_IMAGETYPE` (e.g. "zImage") | ||
48 | |||
49 | - :term:`IMAGE_FSTYPES` (e.g. "tar.gz jffs2") | ||
50 | |||
51 | You can find full details on these variables in the reference section. | ||
52 | You can leverage existing machine ``.conf`` files from | ||
53 | ``meta-yocto-bsp/conf/machine/``. | ||
54 | |||
55 | Adding a Kernel for the Machine | ||
56 | =============================== | ||
57 | |||
58 | The OpenEmbedded build system needs to be able to build a kernel for the | ||
59 | machine. You need to either create a new kernel recipe for this machine, | ||
60 | or extend an existing kernel recipe. You can find several kernel recipe | ||
61 | examples in the Source Directory at ``meta/recipes-kernel/linux`` that | ||
62 | you can use as references. | ||
63 | |||
64 | If you are creating a new kernel recipe, normal recipe-writing rules | ||
65 | apply for setting up a :term:`SRC_URI`. Thus, you need to specify any | ||
66 | necessary patches and set :term:`S` to point at the source code. You need to | ||
67 | create a :ref:`ref-tasks-configure` task that configures the unpacked kernel with | ||
68 | a ``defconfig`` file. You can do this by using a ``make defconfig`` | ||
69 | command or, more commonly, by copying in a suitable ``defconfig`` file | ||
70 | and then running ``make oldconfig``. By making use of ``inherit kernel`` | ||
71 | and potentially some of the ``linux-*.inc`` files, most other | ||
72 | functionality is centralized and the defaults of the class normally work | ||
73 | well. | ||
74 | |||
75 | If you are extending an existing kernel recipe, it is usually a matter | ||
76 | of adding a suitable ``defconfig`` file. The file needs to be added into | ||
77 | a location similar to ``defconfig`` files used for other machines in a | ||
78 | given kernel recipe. A possible way to do this is by listing the file in | ||
79 | the :term:`SRC_URI` and adding the machine to the expression in | ||
80 | :term:`COMPATIBLE_MACHINE`:: | ||
81 | |||
82 | COMPATIBLE_MACHINE = '(qemux86|qemumips)' | ||
83 | |||
84 | For more information on ``defconfig`` files, see the | ||
85 | ":ref:`kernel-dev/common:changing the configuration`" | ||
86 | section in the Yocto Project Linux Kernel Development Manual. | ||
87 | |||
88 | Adding a Formfactor Configuration File | ||
89 | ====================================== | ||
90 | |||
91 | A formfactor configuration file provides information about the target | ||
92 | hardware for which the image is being built and information that the | ||
93 | build system cannot obtain from other sources such as the kernel. Some | ||
94 | examples of information contained in a formfactor configuration file | ||
95 | include framebuffer orientation, whether or not the system has a | ||
96 | keyboard, the positioning of the keyboard in relation to the screen, and | ||
97 | the screen resolution. | ||
98 | |||
99 | The build system uses reasonable defaults in most cases. However, if | ||
100 | customization is necessary, you need to create a ``machconfig`` file in | ||
101 | the ``meta/recipes-bsp/formfactor/files`` directory. This directory | ||
102 | contains directories for specific machines such as ``qemuarm`` and | ||
103 | ``qemux86``. For information about the settings available and the | ||
104 | defaults, see the ``meta/recipes-bsp/formfactor/files/config`` file | ||
105 | found in the same area. | ||
106 | |||
107 | Here is an example for "qemuarm" machine:: | ||
108 | |||
109 | HAVE_TOUCHSCREEN=1 | ||
110 | HAVE_KEYBOARD=1 | ||
111 | DISPLAY_CAN_ROTATE=0 | ||
112 | DISPLAY_ORIENTATION=0 | ||
113 | #DISPLAY_WIDTH_PIXELS=640 | ||
114 | #DISPLAY_HEIGHT_PIXELS=480 | ||
115 | #DISPLAY_BPP=16 | ||
116 | DISPLAY_DPI=150 | ||
117 | DISPLAY_SUBPIXEL_ORDER=vrgb | ||
118 | |||