diff options
author | Michael Opdenacker <michael.opdenacker@bootlin.com> | 2023-05-10 17:31:29 +0200 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2023-05-26 17:32:50 +0100 |
commit | a95cbed77fd2fa2ec263dbdf59bb2aed359d7ce1 (patch) | |
tree | f74d1b27dfe302df26f86c9e983019bcb101f12b /documentation/ref-manual | |
parent | 4417a30196b0cac1d9dc83b23e7fd5719b8ebc2d (diff) | |
download | poky-a95cbed77fd2fa2ec263dbdf59bb2aed359d7ce1.tar.gz |
ref-manual: improve description of kernel-fitimage variables
- Mentioning that they are related to this class
(for further information about their usage)
- Replace "fitImage" by "FIT image"
- Minor formating and style fixes
(From yocto-docs rev: 07214a4ff2646efb143a02fc9381a029870e9b56)
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
CC: Jamin Lin <jamin_lin@aspeedtech.com>
Reviewed-by: Sean Anderson <sean.anderson@seco.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r-- | documentation/ref-manual/classes.rst | 4 | ||||
-rw-r--r-- | documentation/ref-manual/variables.rst | 105 |
2 files changed, 68 insertions, 41 deletions
diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst index 94b6a3ebd7..2f96ffb82f 100644 --- a/documentation/ref-manual/classes.rst +++ b/documentation/ref-manual/classes.rst | |||
@@ -1582,13 +1582,13 @@ The :ref:`ref-classes-kernel-devicetree` class, which is inherited by the | |||
1582 | =================== | 1582 | =================== |
1583 | 1583 | ||
1584 | The :ref:`ref-classes-kernel-fitimage` class provides support to pack a kernel image, | 1584 | The :ref:`ref-classes-kernel-fitimage` class provides support to pack a kernel image, |
1585 | device trees, a U-boot script, a :term:`Initramfs` bundle and a RAM disk | 1585 | device trees, a U-boot script, an :term:`Initramfs` bundle and a RAM disk |
1586 | into a single FIT image. In theory, a FIT image can support any number | 1586 | into a single FIT image. In theory, a FIT image can support any number |
1587 | of kernels, U-boot scripts, :term:`Initramfs` bundles, RAM disks and device-trees. | 1587 | of kernels, U-boot scripts, :term:`Initramfs` bundles, RAM disks and device-trees. |
1588 | However, :ref:`ref-classes-kernel-fitimage` currently only supports | 1588 | However, :ref:`ref-classes-kernel-fitimage` currently only supports |
1589 | limited usecases: just one kernel image, an optional U-boot script, | 1589 | limited usecases: just one kernel image, an optional U-boot script, |
1590 | an optional :term:`Initramfs` bundle, an optional RAM disk, and any number of | 1590 | an optional :term:`Initramfs` bundle, an optional RAM disk, and any number of |
1591 | device tree. | 1591 | device trees. |
1592 | 1592 | ||
1593 | To create a FIT image, it is required that :term:`KERNEL_CLASSES` | 1593 | To create a FIT image, it is required that :term:`KERNEL_CLASSES` |
1594 | is set to include ":ref:`ref-classes-kernel-fitimage`" and :term:`KERNEL_IMAGETYPE` | 1594 | is set to include ":ref:`ref-classes-kernel-fitimage`" and :term:`KERNEL_IMAGETYPE` |
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index 4b69843d4d..b7d3c05ce2 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst | |||
@@ -2921,9 +2921,8 @@ system and gives an overview of their function and contents. | |||
2921 | table file, examine the existing ``fs-perms.txt``. | 2921 | table file, examine the existing ``fs-perms.txt``. |
2922 | 2922 | ||
2923 | :term:`FIT_ADDRESS_CELLS` | 2923 | :term:`FIT_ADDRESS_CELLS` |
2924 | |||
2925 | Specifies the value of the ``#address-cells`` value for the | 2924 | Specifies the value of the ``#address-cells`` value for the |
2926 | description of the kernel FIT image. | 2925 | description of the FIT image. |
2927 | 2926 | ||
2928 | The default value is set to "1" by the :ref:`ref-classes-kernel-fitimage` | 2927 | The default value is set to "1" by the :ref:`ref-classes-kernel-fitimage` |
2929 | class, which corresponds to 32 bit addresses. | 2928 | class, which corresponds to 32 bit addresses. |
@@ -2941,67 +2940,82 @@ system and gives an overview of their function and contents. | |||
2941 | See `more details about #address-cells <https://elinux.org/Device_Tree_Usage#How_Addressing_Works>`__. | 2940 | See `more details about #address-cells <https://elinux.org/Device_Tree_Usage#How_Addressing_Works>`__. |
2942 | 2941 | ||
2943 | :term:`FIT_CONF_DEFAULT_DTB` | 2942 | :term:`FIT_CONF_DEFAULT_DTB` |
2944 | Specifies the default device tree binary (dtb) file for a fitImage when | 2943 | Specifies the default device tree binary (dtb) file for a FIT image |
2945 | multiple are provided. | 2944 | when multiple ones are provided. |
2945 | |||
2946 | This variable is used in the :ref:`ref-classes-kernel-fitimage` class. | ||
2946 | 2947 | ||
2947 | :term:`FIT_DESC` | 2948 | :term:`FIT_DESC` |
2948 | Specifies the description string encoded into a fitImage. The default | 2949 | Specifies the description string encoded into a FIT image. The |
2949 | value is set by the :ref:`ref-classes-kernel-fitimage` | 2950 | default value is set by the :ref:`ref-classes-kernel-fitimage` class as |
2950 | class as follows:: | 2951 | follows:: |
2951 | 2952 | ||
2952 | FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}" | 2953 | FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}" |
2953 | 2954 | ||
2954 | :term:`FIT_GENERATE_KEYS` | 2955 | :term:`FIT_GENERATE_KEYS` |
2955 | Decides whether to generate the keys for signing fitImage if they | 2956 | Decides whether to generate the keys for signing the FIT image if |
2956 | don't already exist. The keys are created in :term:`UBOOT_SIGN_KEYDIR`. | 2957 | they don't already exist. The keys are created in |
2957 | The default value is 0. | 2958 | :term:`UBOOT_SIGN_KEYDIR`. The default value is set to "0" |
2959 | by the :ref:`ref-classes-kernel-fitimage` class. | ||
2958 | 2960 | ||
2959 | :term:`FIT_HASH_ALG` | 2961 | :term:`FIT_HASH_ALG` |
2960 | Specifies the hash algorithm used in creating the FIT Image. For e.g. sha256. | 2962 | Specifies the hash algorithm used in creating the FIT Image. |
2963 | This variable is set by default to "sha256" by the | ||
2964 | :ref:`ref-classes-kernel-fitimage` class. | ||
2961 | 2965 | ||
2962 | :term:`FIT_KERNEL_COMP_ALG` | 2966 | :term:`FIT_KERNEL_COMP_ALG` |
2963 | Compression algorithm to use for the kernel image inside the FIT Image. | 2967 | The compression algorithm to use for the kernel image inside the FIT Image. |
2964 | At present, the only supported values are "gzip" (default), "lzo" or "none". | 2968 | At present, the only supported values are "gzip" (default), "lzo" or "none". |
2965 | If you set this variable to anything other than "none" you may also need | 2969 | If you set this variable to anything other than "none" you may also need |
2966 | to set :term:`FIT_KERNEL_COMP_ALG_EXTENSION`. | 2970 | to set :term:`FIT_KERNEL_COMP_ALG_EXTENSION`. |
2967 | 2971 | ||
2972 | This variable is used in the :ref:`ref-classes-kernel-uboot` class. | ||
2973 | |||
2968 | :term:`FIT_KERNEL_COMP_ALG_EXTENSION` | 2974 | :term:`FIT_KERNEL_COMP_ALG_EXTENSION` |
2969 | File extension corresponding to :term:`FIT_KERNEL_COMP_ALG`. The default | 2975 | File extension corresponding to :term:`FIT_KERNEL_COMP_ALG`. The default |
2970 | value is ".gz". If you set :term:`FIT_KERNEL_COMP_ALG` to "lzo", | 2976 | value is set ".gz" by the :ref:`ref-classes-kernel-uboot` class. If you |
2971 | you may want to set this variable to ".lzo". | 2977 | set :term:`FIT_KERNEL_COMP_ALG` to "lzo", you may want to set this |
2978 | variable to ".lzo". | ||
2972 | 2979 | ||
2973 | :term:`FIT_KEY_GENRSA_ARGS` | 2980 | :term:`FIT_KEY_GENRSA_ARGS` |
2974 | Arguments to openssl genrsa for generating RSA private key for signing | 2981 | Arguments to ``openssl genrsa`` for generating a RSA private key for |
2975 | fitImage. The default value is "-F4". i.e. the public exponent 65537 to | 2982 | signing the FIT image. The default value is set to "-F4" by the |
2976 | use. | 2983 | :ref:`ref-classes-kernel-fitimage` class. |
2977 | 2984 | ||
2978 | :term:`FIT_KEY_REQ_ARGS` | 2985 | :term:`FIT_KEY_REQ_ARGS` |
2979 | Arguments to openssl req for generating certificate for signing fitImage. | 2986 | Arguments to ``openssl req`` for generating a certificate for signing |
2980 | The default value is "-batch -new". batch for non interactive mode | 2987 | the FIT image. The default value is "-batch -new" by the |
2981 | and new for generating new keys. | 2988 | :ref:`ref-classes-kernel-fitimage` class, "batch" for |
2989 | non interactive mode and "new" for generating new keys. | ||
2982 | 2990 | ||
2983 | :term:`FIT_KEY_SIGN_PKCS` | 2991 | :term:`FIT_KEY_SIGN_PKCS` |
2984 | Format for public key certificate used in signing fitImage. | 2992 | Format for the public key certificate used for signing the FIT image. |
2985 | The default value is "x509". | 2993 | The default value is set to "x509" by the |
2994 | :ref:`ref-classes-kernel-fitimage` class. | ||
2986 | 2995 | ||
2987 | :term:`FIT_SIGN_ALG` | 2996 | :term:`FIT_SIGN_ALG` |
2988 | Specifies the signature algorithm used in creating the FIT Image. | 2997 | Specifies the signature algorithm used in creating the FIT Image. |
2989 | For e.g. rsa2048. | 2998 | This variable is set by default to "rsa2048" by the |
2999 | :ref:`ref-classes-kernel-fitimage` class. | ||
2990 | 3000 | ||
2991 | :term:`FIT_PAD_ALG` | 3001 | :term:`FIT_PAD_ALG` |
2992 | Specifies the padding algorithm used in creating the FIT Image. | 3002 | Specifies the padding algorithm used in creating the FIT Image. |
2993 | The default value is "pkcs-1.5". | 3003 | The default value is set to "pkcs-1.5" by the |
3004 | :ref:`ref-classes-kernel-fitimage` class. | ||
2994 | 3005 | ||
2995 | :term:`FIT_SIGN_INDIVIDUAL` | 3006 | :term:`FIT_SIGN_INDIVIDUAL` |
2996 | If set to "1", then the :ref:`ref-classes-kernel-fitimage` | 3007 | If set to "1", then the :ref:`ref-classes-kernel-fitimage` |
2997 | class will sign the kernel, dtb and ramdisk images individually in addition | 3008 | class will sign the kernel, dtb and ramdisk images individually in addition |
2998 | to signing the fitImage itself. This could be useful if you are | 3009 | to signing the FIT image itself. This could be useful if you are |
2999 | intending to verify signatures in another context than booting via | 3010 | intending to verify signatures in another context than booting via |
3000 | U-Boot. | 3011 | U-Boot. |
3001 | 3012 | ||
3013 | This variable is set to "0" by default. | ||
3014 | |||
3002 | :term:`FIT_SIGN_NUMBITS` | 3015 | :term:`FIT_SIGN_NUMBITS` |
3003 | Size of private key in number of bits used in fitImage. The default | 3016 | Size of the private key used in the FIT image, in number of bits. |
3004 | value is "2048". | 3017 | The default value for this variable is set to "2048" |
3018 | by the :ref:`ref-classes-kernel-fitimage` class. | ||
3005 | 3019 | ||
3006 | :term:`FONT_EXTRA_RDEPENDS` | 3020 | :term:`FONT_EXTRA_RDEPENDS` |
3007 | When inheriting the :ref:`ref-classes-fontcache` class, | 3021 | When inheriting the :ref:`ref-classes-fontcache` class, |
@@ -4396,7 +4410,7 @@ system and gives an overview of their function and contents. | |||
4396 | :ref:`ref-classes-kernel` class should inherit. You typically | 4410 | :ref:`ref-classes-kernel` class should inherit. You typically |
4397 | append this variable to enable extended image types. An example is | 4411 | append this variable to enable extended image types. An example is |
4398 | ":ref:`ref-classes-kernel-fitimage`", which enables | 4412 | ":ref:`ref-classes-kernel-fitimage`", which enables |
4399 | fitImage support and resides in ``meta/classes-recipe/kernel-fitimage.bbclass``. | 4413 | FIT image support and resides in ``meta/classes-recipe/kernel-fitimage.bbclass``. |
4400 | You can register custom kernel image types with the | 4414 | You can register custom kernel image types with the |
4401 | :ref:`ref-classes-kernel` class using this variable. | 4415 | :ref:`ref-classes-kernel` class using this variable. |
4402 | 4416 | ||
@@ -9094,6 +9108,11 @@ system and gives an overview of their function and contents. | |||
9094 | To pass a 64 bit address for FIT image creation, you will need to set | 9108 | To pass a 64 bit address for FIT image creation, you will need to set |
9095 | the :term:`FIT_ADDRESS_CELLS` variable too. | 9109 | the :term:`FIT_ADDRESS_CELLS` variable too. |
9096 | 9110 | ||
9111 | This variable is used by the :ref:`ref-classes-kernel-fitimage`, | ||
9112 | :ref:`ref-classes-kernel-uimage`, :ref:`ref-classes-kernel`, | ||
9113 | :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign` | ||
9114 | classes. | ||
9115 | |||
9097 | :term:`UBOOT_LOCALVERSION` | 9116 | :term:`UBOOT_LOCALVERSION` |
9098 | Appends a string to the name of the local version of the U-Boot | 9117 | Appends a string to the name of the local version of the U-Boot |
9099 | image. For example, assuming the version of the U-Boot image built | 9118 | image. For example, assuming the version of the U-Boot image built |
@@ -9122,11 +9141,13 @@ system and gives an overview of their function and contents. | |||
9122 | script or function if desired. The default is "uboot-mkimage". | 9141 | script or function if desired. The default is "uboot-mkimage". |
9123 | 9142 | ||
9124 | :term:`UBOOT_MKIMAGE_DTCOPTS` | 9143 | :term:`UBOOT_MKIMAGE_DTCOPTS` |
9125 | Options for the device tree compiler passed to mkimage '-D' feature while | 9144 | Options for the device tree compiler passed to ``mkimage -D`` feature |
9126 | creating FIT image in :ref:`ref-classes-kernel-fitimage` class. If | 9145 | while creating a FIT image with the :ref:`ref-classes-kernel-fitimage` |
9127 | :term:`UBOOT_MKIMAGE_DTCOPTS` is not set then | 9146 | class. If :term:`UBOOT_MKIMAGE_DTCOPTS` is not set then the |
9128 | :ref:`ref-classes-kernel-fitimage` will not pass the ``-D`` option to | 9147 | :ref:`ref-classes-kernel-fitimage` class will not pass the ``-D`` option |
9129 | mkimage. | 9148 | to ``mkimage``. |
9149 | |||
9150 | This variable is also used by the :ref:`ref-classes-uboot-sign` class. | ||
9130 | 9151 | ||
9131 | :term:`UBOOT_MKIMAGE_KERNEL_TYPE` | 9152 | :term:`UBOOT_MKIMAGE_KERNEL_TYPE` |
9132 | Specifies the type argument for the kernel as passed to ``uboot-mkimage``. | 9153 | Specifies the type argument for the kernel as passed to ``uboot-mkimage``. |
@@ -9159,15 +9180,21 @@ system and gives an overview of their function and contents. | |||
9159 | :term:`UBOOT_SIGN_ENABLE` | 9180 | :term:`UBOOT_SIGN_ENABLE` |
9160 | Enable signing of FIT image. The default value is "0". | 9181 | Enable signing of FIT image. The default value is "0". |
9161 | 9182 | ||
9183 | This variable is used by the :ref:`ref-classes-kernel-fitimage`, | ||
9184 | :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign` | ||
9185 | classes. | ||
9186 | |||
9162 | :term:`UBOOT_SIGN_KEYDIR` | 9187 | :term:`UBOOT_SIGN_KEYDIR` |
9163 | Location of the directory containing the RSA key and | 9188 | Location of the directory containing the RSA key and certificate used for |
9164 | certificate used for signing FIT image. | 9189 | signing FIT image, used by the :ref:`ref-classes-kernel-fitimage` and |
9190 | :ref:`ref-classes-uboot-sign` classes. | ||
9165 | 9191 | ||
9166 | :term:`UBOOT_SIGN_KEYNAME` | 9192 | :term:`UBOOT_SIGN_KEYNAME` |
9167 | The name of keys used for signing U-Boot FIT image stored in | 9193 | The name of keys used by the :ref:`ref-classes-kernel-fitimage` class |
9168 | :term:`UBOOT_SIGN_KEYDIR` directory. For e.g. dev.key key and dev.crt | 9194 | for signing U-Boot FIT image stored in the :term:`UBOOT_SIGN_KEYDIR` |
9169 | certificate stored in :term:`UBOOT_SIGN_KEYDIR` directory will have | 9195 | directory. If we have for example a ``dev.key`` key and a ``dev.crt`` |
9170 | :term:`UBOOT_SIGN_KEYNAME` set to "dev". | 9196 | certificate stored in the :term:`UBOOT_SIGN_KEYDIR` directory, you will |
9197 | have to set :term:`UBOOT_SIGN_KEYNAME` to ``dev``. | ||
9171 | 9198 | ||
9172 | :term:`UBOOT_SUFFIX` | 9199 | :term:`UBOOT_SUFFIX` |
9173 | Points to the generated U-Boot extension. For example, ``u-boot.sb`` | 9200 | Points to the generated U-Boot extension. For example, ``u-boot.sb`` |