docs/chamelium.txt

@@ -47,15 +47,16 @@ Chamelium V2 Documentation
 --------------------------
 
 Documentation about the Chamelium is made available by Google through the
-ChromiumOS projet wiki: https://www.chromium.org/chromium-os/testing/chamelium
+ChromiumOS projet wiki:
+https://www.chromium.org/chromium-os/developer-library/guides/hardware-schematics/chamelium/
 
 Setting up Chamelium V2
 -----------------------
 
 Instructions from the ChromiumOS wiki detail how to setup the Chamelium:
-https://www.chromium.org/chromium-os/testing/chamelium#TOC-Setting-up-Chamelium
+https://www.chromium.org/chromium-os/developer-library/guides/hardware-schematics/chamelium/#setting-up-chamelium
 
-The should be followed up until the "Setup your Linux host, DUT and the FPGA"
+It should be followed up until the "Setup your Linux host, DUT and the FPGA"
 section. At this point, IGT has to be configured to connect to the Chamelium.
 
 It may be necessary to give the Chamelium a static IP address, depending on
@@ -241,7 +242,7 @@ Current Support in IGT
 
 Support for the Chamelium platform in IGT is found in the following places:
 * lib/igt_chamelium.c: library with Chamelium-related helpers
-* tests/kms_chamelium.c: sub-tests using the Chamelium
+* tests/kms_chamelium_*.c: sub-tests using the Chamelium
 
 As of early April 2019, the following features are tested by IGT:
 * Pixel-by-pixel frame integrity tests for DP and HDMI

docs/cross-building.txt

+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'

docs/meson.build

 subdir('reference')
+
+if igt_doc_script.found()
+	subdir('testplan')
+endif

docs/reference/igt-gpu-tools/igt-gpu-tools-docs.xml

@@ -15,6 +15,7 @@
 
   <chapter>
     <title>API Reference</title>
+    <xi:include href="xml/dmabuf_sync_file.xml"/>
     <xi:include href="xml/drmtest.xml"/>
     <xi:include href="xml/igt_alsa.xml"/>
     <xi:include href="xml/igt_audio.xml"/>
@@ -31,12 +32,14 @@
     <xi:include href="xml/igt_fb.xml"/>
     <xi:include href="xml/igt_frame.xml"/>
     <xi:include href="xml/igt_gt.xml"/>
+    <xi:include href="xml/igt_hook.xml"/>
     <xi:include href="xml/igt_io.xml"/>
     <xi:include href="xml/igt_kmod.xml"/>
     <xi:include href="xml/igt_kms.xml"/>
     <xi:include href="xml/igt_list.xml"/>
     <xi:include href="xml/igt_map.xml"/>
     <xi:include href="xml/igt_msm.xml"/>
+    <xi:include href="xml/igt_pipe_crc.xml"/>
     <xi:include href="xml/igt_pm.xml"/>
     <xi:include href="xml/igt_primes.xml"/>
     <xi:include href="xml/igt_rand.xml"/>
@@ -62,7 +65,7 @@
     <xi:include href="xml/gem_engine_topology.xml"/>
     <xi:include href="xml/gem_scheduler.xml"/>
     <xi:include href="xml/gem_submission.xml"/>
-    <xi:include href="xml/i915_blt.xml"/>
+    <xi:include href="xml/intel_blt.xml"/>
     <xi:include href="xml/i915_crc.xml"/>
     <xi:include href="xml/intel_ctx.xml"/>
   </chapter>

docs/reference/igt-gpu-tools/meson.build

@@ -6,10 +6,10 @@ ignore_headers = [
 	'gen7_render.h',
 	'gen8_media.h',
 	'gen8_render.h',
+	'gen9_media.h',
 	'gpgpu_fill.h',
 	'i830_reg.h',
 	'i915_3d.h',
-	'i915_pciids.h',
 	'i915_reg.h',
 	'igt_edid_template.h',
 	'intel_reg.h',
@@ -20,6 +20,7 @@ ignore_headers = [
 	'media_spin.h',
 	'media_fill_gen9.h',
 	'gen9_render.h',
+	'pciids.h',
 	'version.h',
 ]
 

docs/reference/meson.build

-subdir('igt-gpu-tools')
+gtk_doc = dependency('gtk-doc', required : build_docs)
+if build_tests and gtk_doc.found()
+	subdir('igt-gpu-tools')
+elif build_docs.enabled()
+	error('Documentation requires building tests')
+endif
+
+build_info += 'Build reference documentation: @0@'.format(build_docs.enabled())

docs/test_documentation.md

+IGT Test documentation
+======================
+
+Legacy way
+----------
+
+IGT has been providing a way to document tests in runtime by using tree macros:
+
+    - IGT_TEST_DESCRIPTION(test_file_description)
+    - igt_describe(subtest_description) and igt_describe_f(format, args...)
+
+This is limited, as:
+    - Each test/subtest has just one “field”: description. It doesn't
+      allow specifying what features are tested and/or special requirements;
+    - It is meant to produce a very concise documentation;
+    - Integration with external platforms to group tests per category
+      is not possible, as there's no way to tell what category each test
+      belongs;
+    - Format is not easily expansible;
+    - The build system doesn’t verify if all tests are documented.
+      As time passes, documentation tends to be outdated or forgotten,
+      as new patches modify the test set.
+
+Documentation via structured comments (testplan)
+------------------------------------------------
+
+With the addition of Xe driver, a new way to document tests was added.
+It is based on special comment-like annotation inside the C code.
+
+It was written to be flexible, so the valid fields to be used by are
+described on a JSON configuration file. That makes easy to add/modify
+the fields as needed. It is also easy to use the documentation to
+integrate with external reporting tools.
+
+As an additional benefit, the documentation tags will be generating a
+Restructured Text file. It is possible to add enriched test descriptions
+if needed.
+
+The build system can also optionally enforce a check at build time to
+verify if the documentation is in place.
+
+testplan configuration file
+---------------------------
+
+The configuration file contains the fields to be used for documenting
+tests and test names. It may also mark a property as mandatory.
+
+A typical example is:
+
+```
+{
+    "description": "JSON example file",
+    "name": "Tests for XYZ Driver",
+    "files": [ "test.c" ],
+    "fields": {
+        "Feature": {
+            "_properties_": {
+                "description": "Feature to be tested"
+            }
+        },
+        "Description" : {
+            "_properties_": {
+                "mandatory": true,
+                "description": "Provides a description for the test/subtest."
+            }
+        }
+    }
+}
+```
+
+Documenting tests via testplan
+------------------------------
+
+A typical documentation markup at the test source code looks like:
+```
+/**
+ * TEST: Check if new IGT test documentation logic functionality is working
+ * Mega-feature: IGT test documentation
+ * Category: Software build block
+ * Sub-category: documentation
+ * Functionality: test documentation
+ * Issue: none
+ * Description: Complete description of this test
+ *
+ * SUBTEST: foo
+ * Description: do foo things.
+ *      Foo description continuing on another line
+ *
+ * SUBTEST: bar
+ * Description:
+ *      Do bar things.
+ *      Bar description continuing on another line
+ */
+```
+
+It is also possible to add variables to the documentation with:
+
+```
+/**
+ * SUBTEST: test-%s-binds-with-%ld-size-%s
+ * Description: Test arg[3] arg[1] binds with arg[2] size
+ *
+ * SUBTEST: test-%s-%ld-size
+ * Description: Test arg[1] with %arg[2] size
+ *
+ * arg[1]:
+ *
+ * @large:      large
+ *              something
+ * @small:      small
+ *              something
+ *
+ * arg[2]:      buffer size
+ *
+ * arg[3]:
+ *
+ * @misaligned-binds:           misaligned
+ * @userptr-binds:              user pointer
+ */
+ ```
+
+The first "%s" will be replaced by the values of arg[1] for the subtest
+name. At the description, arg[1] will be replaced by the string after
+the field description. The same applies to the subsequent wildcards.
+
+The above will produce the following output (using the example
+configuration file described at the past session:
+
+```
+``igt@test@test-large-<buffer size>-size``
+
+:Description: Test large something with <buffer size> size
+
+
+``igt@test@test-large-binds-with-<buffer size>-size-misaligned-binds``
+
+:Description: Test misaligned large something binds with <buffer size> size
+
+
+``igt@test@test-small-binds-with-<buffer size>-size-misaligned-binds``
+
+:Description: Test misaligned small something binds with <buffer size> size
+
+
+``igt@test@test-small-<buffer size>-size``
+
+:Description: Test small something with <buffer size> size
+
+
+``igt@test@test-large-binds-with-<buffer size>-size-userptr-binds``
+
+:Description: Test user pointer large something binds with <buffer size> size
+
+
+``igt@test@test-small-binds-with-<buffer size>-size-userptr-binds``
+
+:Description: Test user pointer small something binds with <buffer size> size
+```
+
+Wildcard replacement can also be used to maintain an argument with the
+same name at the replaced description. That makes easy to document
+numeric arguments with a fixed testset, like:
+
+```
+/**
+ * SUBTEST: unbind-all-%d-vmas
+ * Description: unbind all with %arg[1] VMAs
+ *
+ * arg[1].values: 2, 8
+ * arg[1].values: 16, 32
+ */
+
+/**
+ * SUBTEST: unbind-all-%d-vmas
+ * Description: unbind all with %arg[1] VMAs
+ *
+ * arg[1].values: 64, 128
+ */
+```

docs/testplan/conf.py

+# -*- coding: utf-8 -*-
+# SPDX-License-Identifier: (GPL-2.0 OR MIT)
+
+import os
+import sphinx
+import sys
+
+# Get Sphinx version
+major, minor, patch = sphinx.version_info[:3]
+
+sys.path.insert(0, os.path.abspath('sphinx'))
+
+extensions = []
+
+def which(program):
+    import os
+    def is_exe(fpath):
+        return os.path.isfile(fpath) and os.access(fpath, os.X_OK)
+
+    fpath, fname = os.path.split(program)
+    if fpath:
+        if is_exe(program):
+            return program
+    else:
+        for path in os.environ["PATH"].split(os.pathsep):
+            exe_file = os.path.join(path, program)
+            if is_exe(exe_file):
+                return exe_file
+
+    return None
+
+if which('rst2pdf'):
+    extensions.append('rst2pdf.pdfbuilder')
+
+source_suffix = '.rst'
+master_doc = 'index'
+
+project = 'IGT Test Tools'
+copyright = 'Intel'
+author = 'IGT developers'
+language = 'en'
+
+exclude_patterns = []
+todo_include_todos = False
+
+if major < 2 and minor < 6:
+    html_use_smartypants = False
+else:
+    smartquotes = False
+
+html_theme = "nature"
+
+# body_max_width causes build error with nature theme on version < 1.7
+if major < 2 and minor < 7:
+    html_theme_options = {
+        "sidebarwidth": "400px",
+    }
+else:
+    html_theme_options = {
+        "body_max_width": "1520px",
+        "sidebarwidth": "400px",
+    }
+
+html_css_files = []
+html_static_path = ['.']
+html_copy_source = False
+
+html_sidebars = { '**': ['searchbox.html', 'localtoc.html']}
+htmlhelp_basename = 'IGT'
+
+# rst2pdf
+pdf_documents = [
+    ('index', u'tests', u'IGT Xe Tests', u'IGT authors'),
+]

docs/testplan/meson.build

+testplan_title = 'IGT test plans'
+
+intel_testlist_dir = 'intel-ci-tests'
+
+sphinx = find_program('sphinx-build', required: build_sphinx)
+rst2html = find_program('rst2html-3', 'rst2html', required : false)
+rst2pdf = find_program('rst2pdf', required: false)
+
+stylesheet = join_paths(meson.current_source_dir(), 'testplan.css')
+
+xe_test_config = join_paths(source_root, 'tests', 'intel', 'xe_test_config.json')
+kms_test_config = join_paths(source_root, 'tests', 'intel', 'kms_test_config.json')
+i915_test_config = join_paths(source_root, 'tests', 'intel', 'i915_test_config.json')
+
+check_testlist = []
+kms_check_testlist = []
+if build_tests
+	doc_dependencies = testlist_files
+	# Check if documentation matches the actual tests and tests can run
+	if not meson.is_cross_build()
+		build_info += 'Will Check if documentation is in sync with testlist'
+		check_testlist = [ '--check-testlist', '--igt-build-path', build_root ]
+
+		if not chamelium.found()
+			warning('WARNING: Will not check if documentation is in sync for KMS as chamelium is disabled')
+		else
+			kms_check_testlist = check_testlist
+		endif
+	else
+		warning('WARNING: Will not check if documentation is in sync with testlist')
+	endif
+else
+	doc_dependencies = []
+endif
+
+if build_xe
+	test_dict = {
+		'i915_tests': { 'input': i915_test_config, 'extra_args': check_testlist },
+		'kms_tests': { 'input': kms_test_config, 'extra_args': kms_check_testlist },
+		'xe_tests': { 'input': xe_test_config, 'extra_args': check_testlist }
+	    }
+else
+	test_dict = {
+	      'i915_tests': { 'input': i915_test_config, 'extra_args': check_testlist },
+	      'kms_tests': { 'input': kms_test_config, 'extra_args': kms_check_testlist }
+	    }
+endif
+
+testplans = []
+
+foreach testplan, fields: test_dict
+	rst = custom_target(testplan + '.rst',
+			    build_by_default : true,
+			    command : [ igt_doc_script, '--config', '@INPUT@', '--rest', '@OUTPUT@' ] + fields['extra_args'],
+			    depends : doc_dependencies,
+			    input : fields['input'],
+			    output : testplan + '.rst'
+			   )
+
+	testplans += fields['input']
+
+	if rst2html.found()
+		custom_target(testplan + '.html',
+			      build_by_default : true,
+			      command : [ rst2html, '--stylesheet=' + stylesheet, '--field-name-limit=0', '@INPUT@', '@OUTPUT@' ],
+			      input : rst,
+			      output : testplan + '.html'
+			     )
+	endif
+endforeach
+
+custom_target(intel_testlist_dir,
+	      build_by_default : true,
+	      build_always_stale : true,
+	      command : [ igt_doc_script, '--config', '@INPUT@', '--intelci-testlist', '@OUTPUT@' ],
+	      depends : doc_dependencies,
+	      input : testplans,
+	      output : intel_testlist_dir,
+	      install : true,
+	      install_dir : libexecdir
+	     )
+
+if sphinx.found()
+	if gen_rst_index.found()
+		sphinx_out_dir = meson.current_build_dir()+ '/indexed_html'
+
+		index_rst = custom_target('index.rst',
+					  build_by_default : true,
+					  command : [ gen_rst_index, testplan_title, test_dict.keys(), meson.current_build_dir()],
+					  input : rst,
+					  output : 'index.rst'
+					 )
+
+		custom_target('index.html',
+			      build_by_default : true,
+			      command : [ 'sphinx-build', '-c', meson.current_source_dir(),
+					  meson.current_build_dir(), sphinx_out_dir],
+			      input : index_rst,
+			      output : 'index.html'
+			     )
+	endif
+
+	if rst2pdf.found()
+		sphinx_out_pdf = meson.current_build_dir() + '/pdf'
+
+		custom_target('tests.pdf',
+			      build_by_default : true,
+			      command : [ 'sphinx-build', '-c', meson.current_source_dir(),
+					  '-b', 'pdf',
+					  '-D', 'version=' + meson.project_version(),
+					  meson.current_build_dir(), sphinx_out_pdf],
+			      input : index_rst,
+			      output : 'tests.pdf'
+			     )
+	endif
+endif
+
+build_info += 'Build simple html testplan documentation: @0@'.format(rst2html.found())
+build_info += 'Build indexed html testplan documentation: @0@'.format(sphinx.found())
+build_info += 'Build pdf testplan documentation: @0@'.format(sphinx.found() and rst2pdf.found())

docs/testplan/testplan.css

+@import url(html4css1.css);
+
+.literal {
+	background: lightgrey;
+        color: darkblue;
+        font-size: 14px;
+}

include/drm-uapi-experimental/intel_drm_local.h

+/* SPDX-License-Identifier: MIT */
+/*
+ * Copyright © 2024 Intel Corporation
+ */
+#ifndef _INTEL_DRM_LOCAL_H_
+#define _INTEL_DRM_LOCAL_H_
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+/*
+ * It is necessary on occasion to add uapi declarations to IGT before they
+ * appear in imported kernel uapi headers. This header is provided for this
+ * purpose.
+
+ * Early uapi declarations should be added here exactly as they are
+ * expected to appear in the kernel uapi headers, i.e. without the LOCAL_
+ * or local_ prefix and without any #ifndef's. Attempt should be made to
+ * clean these up when kernel uapi headers are sync'd.
+ */
+
+#define DRM_XE_MMAP_OFFSET_FLAG_PCI_BARRIER	(1 << 0)
+
+#define DRM_XE_EXEC_QUEUE_LOW_LATENCY_HINT      (1 << 0)
+#define DRM_XE_QUERY_CONFIG_FLAG_HAS_LOW_LATENCY        (1 << 1)
+
+#if defined(__cplusplus)
+}
+#endif
+
+#endif /* _INTEL_DRM_LOCAL_H_ */