[igt-dev] [PATCH i-g-t v2] docs/cross-building.txt: add documentation about cross-builds

[igt-dev] [PATCH i-g-t v2] docs/cross-building.txt: add documentation about cross-builds

[Mauro Carvalho Chehab]

From: Mauro Carvalho Chehab <mchehab@kernel.org>

Cross-building IGT is not too trivial, as one needs to prepare
a sysroot directory containing not only glibc but also other
libraries. Document how to do it for IGT.

Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---
 docs/cross-building.txt | 122 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 122 insertions(+)
 create mode 100644 docs/cross-building.txt

diff --git a/docs/cross-building.txt b/docs/cross-building.txt
new file mode 100644
index 000000000000..2c0e3caf30e9
--- /dev/null
+++ b/docs/cross-building.txt
@@ -0,0 +1,122 @@
+Producing an IGT for another architecture
+=========================================
+
+Cross-build toolchain
+---------------------
+
+Producing cross-builds require installing a toolchain with support
+to the target architecture, or a toolchain built for the target,
+plus an emulator (like qemu). In the case of IGT, the minimal toolchain
+is GCC and binutils. For instance, on Fedora, to cross-build with arm64
+as the target architecture, those packages are needed:
+
+	binutils-aarch64-linux-gnu
+	gcc-aarch64-linux-gnu
+
+There are also tarballs with cross-compiler chains that can be used
+instead, like:
+
+	https://toolchains.bootlin.com/
+
+System root directory (sysroot)
+-------------------------------
+
+Besides a toolchain, a system root directory containing the libraries
+used by IGT pre-compiled to the target architecture is required.
+
+This can be obtained by either cross-building a distribution using
+Yocto, buildroot or similar, or by copying the system root from
+an existing installation for the desired architecture, containing
+the IGT needed build time and runtime library dependencies.
+
+Please notice that cross-build toolchains may require some
+dependent object files and libraries used by it to also be copied
+to the system root directory. For instance, in the case of Fedora,
+the files are located  under /usr/aarch64-linux-gnu/sys-root/
+(for aarch64 architecture) shall also be stored at the sysroot
+directory used by Meson, as otherwise the preparation step will fail.
+
+Meson preparation
+-----------------
+
+Meson requires an extra configuration file to be used for
+non-native builds. This is passed via --cross-file parameter to it.
+
+Such file contains details about the target OS/architecture, about
+the host (native) OS/architecture and declares the location of
+sysroot:
+
+- the [host_machine] section defines the system and architecture from
+  the native OS;
+  At the example below, the native OS is Linux x86_64 architecture.
+- the [target_machine] section contains details about the target
+  OS/architecture.
+  At the example below, the target is aarch64 (arm 64 bits architecture).
+- the [constants] section is optional, but it helps to use the sysroot
+  path directory on multiple keys at the [properties] section;
+- the [properties] section contains arguments to be used by the
+  the binaries;
+- the [binaries] section contains the binaries to be used during the
+  build. It can either be a native or a target toolchain.
+  If a target toolchan is used, an exe_wrapper key pointing to an arch
+  emulalor like qemu-arm is needed.
+
+The sysroot directory is where IGT dependent libraries and header
+files, compiled for a given architecture, are stored. At the example
+below, the sysroot is /aarch64-sysroot.
+
+Preparing for cross compilation is done by calling meson with the
+cross-compilation config file name, plus a build directory:
+
+	meson --cross-file arm64_cross.txt build
+
+The actual compilation can then be done using ninja:
+
+	ninja -C build
+
+Please notice that some parts of the IGT build are disabled during
+cross-compilation, like testlist file creation and documentation,
+as such steps depend on running the generated code at the native
+machine.
+
+The IGT root directory has already 3 examples that uses qemu to
+run a target-OS machine toolchain:
+
+	meson-cross-arm64.txt
+	meson-cross-armhf.txt
+	meson-cross-mips.txt
+
+The example below contains cross-build instructions when using
+a native cross-build toolchain.
+
+Example: arm64_cross.txt with a native cross-builder toolchain
+--------------------------------------------------------------
+
+[constants]
+sysroot = '/aarch64-sysroot'
+common_args = ['--sysroot=' + sysroot]
+
+[properties]
+sys_root = sysroot
+c_args = common_args
+c_link_args = common_args
+pkg_config_libdir = [sysroot + '/usr/lib64/pkgconfig', sysroot +'/usr/share/pkgconfig', sysroot +'/usr/local/lib/pkgconfig']
+
+[binaries]
+c = '/usr/bin/aarch64-linux-gnu-gcc'
+ar = '/usr/bin/aarch64-linux-gnu-gcc-ar'
+ld = '/usr/bin/aarch64-linux-gnu-ld'
+strip = '/usr/bin/aarch64-linux-gnu-strip'
+pkgconfig = 'pkg-config'
+
+[host_machine]
+system = 'linux'
+cpu_family = 'x86_64'
+cpu = 'x86_64'
+endian = 'little'
+
+[target_machine]
+system = 'linux'
+cpu_family = 'aarch64'
+cpu = 'aarch64'
+endian = 'little'
-- 
2.41.0

[igt-dev] ✓ CI.xeBAT: success for docs/cross-building.txt: add documentation about cross-builds (rev2)

[Patchwork]

[-- Attachment #1: Type: text/plain, Size: 1567 bytes --]

== Series Details ==

Series: docs/cross-building.txt: add documentation about cross-builds (rev2)
URL   : https://patchwork.freedesktop.org/series/123705/
State : success

== Summary ==

CI Bug Log - changes from XEIGT_7489_BAT -> XEIGTPW_9797_BAT
====================================================

Summary
-------

  **SUCCESS**

  No regressions found.

  

Participating hosts (4 -> 4)
------------------------------

  No changes in participating hosts

Known issues
------------

  Here are the changes found in XEIGTPW_9797_BAT that come from known issues:

### IGT changes ###

#### Possible fixes ####

  * {igt@xe_create@create-execqueues-noleak}:
    - bat-atsm-2:         [FAIL][1] ([Intel XE#524]) -> [PASS][2]
   [1]: https://intel-gfx-ci.01.org/tree/intel-xe/IGT_7489/bat-atsm-2/igt@xe_create@create-execqueues-noleak.html
   [2]: https://intel-gfx-ci.01.org/tree/intel-xe/IGTPW_9797/bat-atsm-2/igt@xe_create@create-execqueues-noleak.html

  
  {name}: This element is suppressed. This means it is ignored when computing
          the status of the difference (SUCCESS, WARNING, or FAILURE).

  [Intel XE#524]: https://gitlab.freedesktop.org/drm/xe/kernel/issues/524


Build changes
-------------

  * IGT: IGT_7489 -> IGTPW_9797

  IGTPW_9797: 9797
  IGT_7489: c31111635650e76263faee031292290b1a393f2a @ https://gitlab.freedesktop.org/drm/igt-gpu-tools.git
  xe-375-4a9681392cecd56a372d06b648f7b3a37fdd5c63: 4a9681392cecd56a372d06b648f7b3a37fdd5c63

== Logs ==

For more details see: https://intel-gfx-ci.01.org/tree/intel-xe/IGTPW_9797/index.html

[-- Attachment #2: Type: text/html, Size: 2139 bytes --]

[igt-dev] ✗ Fi.CI.BAT: failure for docs/cross-building.txt: add documentation about cross-builds (rev2)

[Patchwork]

[-- Attachment #1: Type: text/plain, Size: 3523 bytes --]

== Series Details ==

Series: docs/cross-building.txt: add documentation about cross-builds (rev2)
URL   : https://patchwork.freedesktop.org/series/123705/
State : failure

== Summary ==

CI Bug Log - changes from IGT_7489 -> IGTPW_9797
====================================================

Summary
-------

  **FAILURE**

  Serious unknown changes coming with IGTPW_9797 absolutely need to be
  verified manually.
  
  If you think the reported changes have nothing to do with the changes
  introduced in IGTPW_9797, please notify your bug team (lgci.bug.filing@intel.com) to allow them
  to document this new failure mode, which will reduce false positives in CI.

  External URL: https://intel-gfx-ci.01.org/tree/drm-tip/IGTPW_9797/index.html

Participating hosts (41 -> 38)
------------------------------

  Missing    (3): fi-kbl-soraka fi-hsw-4770 fi-snb-2520m 

Possible new issues
-------------------

  Here are the unknown changes that may have been introduced in IGTPW_9797:

### IGT changes ###

#### Possible regressions ####

  * igt@i915_selftest@live@hangcheck:
    - fi-skl-guc:         [PASS][1] -> [DMESG-FAIL][2]
   [1]: https://intel-gfx-ci.01.org/tree/drm-tip/IGT_7489/fi-skl-guc/igt@i915_selftest@live@hangcheck.html
   [2]: https://intel-gfx-ci.01.org/tree/drm-tip/IGTPW_9797/fi-skl-guc/igt@i915_selftest@live@hangcheck.html

  
Known issues
------------

  Here are the changes found in IGTPW_9797 that come from known issues:

### IGT changes ###

#### Issues hit ####

  * igt@kms_hdmi_inject@inject-audio:
    - fi-kbl-guc:         [PASS][3] -> [FAIL][4] ([IGT#3] / [i915#6121])
   [3]: https://intel-gfx-ci.01.org/tree/drm-tip/IGT_7489/fi-kbl-guc/igt@kms_hdmi_inject@inject-audio.html
   [4]: https://intel-gfx-ci.01.org/tree/drm-tip/IGTPW_9797/fi-kbl-guc/igt@kms_hdmi_inject@inject-audio.html

  
#### Possible fixes ####

  * igt@i915_selftest@live@gt_heartbeat:
    - fi-apl-guc:         [DMESG-FAIL][5] ([i915#5334]) -> [PASS][6]
   [5]: https://intel-gfx-ci.01.org/tree/drm-tip/IGT_7489/fi-apl-guc/igt@i915_selftest@live@gt_heartbeat.html
   [6]: https://intel-gfx-ci.01.org/tree/drm-tip/IGTPW_9797/fi-apl-guc/igt@i915_selftest@live@gt_heartbeat.html

  * igt@kms_pipe_crc_basic@read-crc-frame-sequence@pipe-d-edp-1:
    - bat-rplp-1:         [ABORT][7] ([i915#8668]) -> [PASS][8]
   [7]: https://intel-gfx-ci.01.org/tree/drm-tip/IGT_7489/bat-rplp-1/igt@kms_pipe_crc_basic@read-crc-frame-sequence@pipe-d-edp-1.html
   [8]: https://intel-gfx-ci.01.org/tree/drm-tip/IGTPW_9797/bat-rplp-1/igt@kms_pipe_crc_basic@read-crc-frame-sequence@pipe-d-edp-1.html

  
  {name}: This element is suppressed. This means it is ignored when computing
          the status of the difference (SUCCESS, WARNING, or FAILURE).

  [IGT#3]: https://gitlab.freedesktop.org/drm/igt-gpu-tools/issues/3
  [i915#5334]: https://gitlab.freedesktop.org/drm/intel/issues/5334
  [i915#6121]: https://gitlab.freedesktop.org/drm/intel/issues/6121
  [i915#7952]: https://gitlab.freedesktop.org/drm/intel/issues/7952
  [i915#8668]: https://gitlab.freedesktop.org/drm/intel/issues/8668


Build changes
-------------

  * CI: CI-20190529 -> None
  * IGT: IGT_7489 -> IGTPW_9797

  CI-20190529: 20190529
  CI_DRM_13635: c6b7f865a77a75af03c3b68baa4cf7eb66c1c6d5 @ git://anongit.freedesktop.org/gfx-ci/linux
  IGTPW_9797: 9797
  IGT_7489: c31111635650e76263faee031292290b1a393f2a @ https://gitlab.freedesktop.org/drm/igt-gpu-tools.git

== Logs ==

For more details see: https://intel-gfx-ci.01.org/tree/drm-tip/IGTPW_9797/index.html

[-- Attachment #2: Type: text/html, Size: 4157 bytes --]

Re: [igt-dev] [PATCH i-g-t v2] docs/cross-building.txt: add documentation about cross-builds

[Kamil Konieczny]

Hi Mauro,

thank you for documenting this.

Reviewed-by: Kamil Konieczny <kamil.konieczny@linux.intel.com>

Regards,
Kamil

On 2023-09-15 at 09:11:55 +0200, Mauro Carvalho Chehab wrote:
> From: Mauro Carvalho Chehab <mchehab@kernel.org>
> 
> Cross-building IGT is not too trivial, as one needs to prepare
> a sysroot directory containing not only glibc but also other
> libraries. Document how to do it for IGT.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> ---
>  docs/cross-building.txt | 122 ++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 122 insertions(+)
>  create mode 100644 docs/cross-building.txt
> 
> diff --git a/docs/cross-building.txt b/docs/cross-building.txt
> new file mode 100644
> index 000000000000..2c0e3caf30e9
> --- /dev/null
> +++ b/docs/cross-building.txt
> @@ -0,0 +1,122 @@
> +Producing an IGT for another architecture
> +=========================================
> +
> +Cross-build toolchain
> +---------------------
> +
> +Producing cross-builds require installing a toolchain with support
> +to the target architecture, or a toolchain built for the target,
> +plus an emulator (like qemu). In the case of IGT, the minimal toolchain
> +is GCC and binutils. For instance, on Fedora, to cross-build with arm64
> +as the target architecture, those packages are needed:
> +
> +	binutils-aarch64-linux-gnu
> +	gcc-aarch64-linux-gnu
> +
> +There are also tarballs with cross-compiler chains that can be used
> +instead, like:
> +
> +	https://toolchains.bootlin.com/
> +
> +System root directory (sysroot)
> +-------------------------------
> +
> +Besides a toolchain, a system root directory containing the libraries
> +used by IGT pre-compiled to the target architecture is required.
> +
> +This can be obtained by either cross-building a distribution using
> +Yocto, buildroot or similar, or by copying the system root from
> +an existing installation for the desired architecture, containing
> +the IGT needed build time and runtime library dependencies.
> +
> +Please notice that cross-build toolchains may require some
> +dependent object files and libraries used by it to also be copied
> +to the system root directory. For instance, in the case of Fedora,
> +the files are located  under /usr/aarch64-linux-gnu/sys-root/
> +(for aarch64 architecture) shall also be stored at the sysroot
> +directory used by Meson, as otherwise the preparation step will fail.
> +
> +Meson preparation
> +-----------------
> +
> +Meson requires an extra configuration file to be used for
> +non-native builds. This is passed via --cross-file parameter to it.
> +
> +Such file contains details about the target OS/architecture, about
> +the host (native) OS/architecture and declares the location of
> +sysroot:
> +
> +- the [host_machine] section defines the system and architecture from
> +  the native OS;
> +  At the example below, the native OS is Linux x86_64 architecture.
> +- the [target_machine] section contains details about the target
> +  OS/architecture.
> +  At the example below, the target is aarch64 (arm 64 bits architecture).
> +- the [constants] section is optional, but it helps to use the sysroot
> +  path directory on multiple keys at the [properties] section;
> +- the [properties] section contains arguments to be used by the
> +  the binaries;
> +- the [binaries] section contains the binaries to be used during the
> +  build. It can either be a native or a target toolchain.
> +  If a target toolchan is used, an exe_wrapper key pointing to an arch
> +  emulalor like qemu-arm is needed.
> +
> +The sysroot directory is where IGT dependent libraries and header
> +files, compiled for a given architecture, are stored. At the example
> +below, the sysroot is /aarch64-sysroot.
> +
> +Preparing for cross compilation is done by calling meson with the
> +cross-compilation config file name, plus a build directory:
> +
> +	meson --cross-file arm64_cross.txt build
> +
> +The actual compilation can then be done using ninja:
> +
> +	ninja -C build
> +
> +Please notice that some parts of the IGT build are disabled during
> +cross-compilation, like testlist file creation and documentation,
> +as such steps depend on running the generated code at the native
> +machine.
> +
> +The IGT root directory has already 3 examples that uses qemu to
> +run a target-OS machine toolchain:
> +
> +	meson-cross-arm64.txt
> +	meson-cross-armhf.txt
> +	meson-cross-mips.txt
> +
> +The example below contains cross-build instructions when using
> +a native cross-build toolchain.
> +
> +Example: arm64_cross.txt with a native cross-builder toolchain
> +--------------------------------------------------------------
> +
> +[constants]
> +sysroot = '/aarch64-sysroot'
> +common_args = ['--sysroot=' + sysroot]
> +
> +[properties]
> +sys_root = sysroot
> +c_args = common_args
> +c_link_args = common_args
> +pkg_config_libdir = [sysroot + '/usr/lib64/pkgconfig', sysroot +'/usr/share/pkgconfig', sysroot +'/usr/local/lib/pkgconfig']
> +
> +[binaries]
> +c = '/usr/bin/aarch64-linux-gnu-gcc'
> +ar = '/usr/bin/aarch64-linux-gnu-gcc-ar'
> +ld = '/usr/bin/aarch64-linux-gnu-ld'
> +strip = '/usr/bin/aarch64-linux-gnu-strip'
> +pkgconfig = 'pkg-config'
> +
> +[host_machine]
> +system = 'linux'
> +cpu_family = 'x86_64'
> +cpu = 'x86_64'
> +endian = 'little'
> +
> +[target_machine]
> +system = 'linux'
> +cpu_family = 'aarch64'
> +cpu = 'aarch64'
> +endian = 'little'
> -- 
> 2.41.0
>