From 1fe530431cc6045bbbc35c81df6346980ca1fa8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vin=C3=ADcius=20Ferr=C3=A3o?= <2031761+viniciusferrao@users.noreply.github.com> Date: Fri, 4 Sep 2026 00:54:19 -0300 Subject: [PATCH] docs(genesis): document s390x target --- .../code/dhcp_backend_validation_matrix.rst | 7 +++++ .../guides/code/genesis_openembedded_plan.rst | 29 ++++++++++++++----- .../admin-guides/references/man8/mknb.8.rst | 6 +++- xCAT-client/pods/man8/mknb.8.pod | 6 +++- xCAT-genesis-builder/README.md | 3 +- 5 files changed, 40 insertions(+), 11 deletions(-) diff --git a/docs/source/developers/guides/code/dhcp_backend_validation_matrix.rst b/docs/source/developers/guides/code/dhcp_backend_validation_matrix.rst index dbcf15339..364ff63a2 100644 --- a/docs/source/developers/guides/code/dhcp_backend_validation_matrix.rst +++ b/docs/source/developers/guides/code/dhcp_backend_validation_matrix.rst @@ -129,6 +129,13 @@ The following matrix is the default live validation gate for DHCP backend work. - ``makedhcp -n``; ``kea-dhcp4 -t``; reservation add/query/delete; xNBA shell boot; stateful subiquity and stateless compute-image handoff through kernel, initrd, and root image when image validation is in scope + * - QEMU ``s390-ccw`` + - ``s390x`` + - ``ISC`` and ``Kea`` + - ``s390-ccw BIOS network IPL`` + - ``makedhcp -n``; backend parser; architecture ``0x001f``; DHCP options + 209 and 210; TFTP fetch of the generated ``pxelinux.cfg``-style configuration, + Genesis kernel, and initramfs Kea Boot and Reservation Regression Matrix ------------------------------------------ diff --git a/docs/source/developers/guides/code/genesis_openembedded_plan.rst b/docs/source/developers/guides/code/genesis_openembedded_plan.rst index 92472c44e..2c39585d7 100644 --- a/docs/source/developers/guides/code/genesis_openembedded_plan.rst +++ b/docs/source/developers/guides/code/genesis_openembedded_plan.rst @@ -57,6 +57,9 @@ Supported architectures * - ``riscv64`` - RV64GC with OpenSBI - QEMU ``virt`` + * - ``s390x`` + - 64-bit z/Architecture, z10 or later + - QEMU ``s390-ccw-virtio`` ``x86_64`` is the first release target and ``ppc64le`` is the second because both have physical test systems. The other targets have the same software @@ -66,7 +69,7 @@ trees, or controllers. Architecture names are exact. In particular, ``ppc64`` and ``ppc64le`` are different artifacts. The build does not preserve the old xCAT alias between them. ``riscv32``, pre-ARMv7 processors, and i586-only x86 processors are not -supported. +supported. The ``s390x`` target does not support the 31-bit ``s390`` ABI. Networking ---------- @@ -90,6 +93,14 @@ IPv6-only deployment also needs matching support in xCAT server code, DHCP, boot firmware, and boot configuration. Those changes are outside this layer and must not be hidden inside the Genesis image. +The ``s390x`` image uses virtio networking under QEMU. QEMU does not emulate +qeth, and Genesis does not yet configure qeth channel groups. Physical LPAR +and z/VM Genesis networking therefore remain unvalidated. +Genesis does not use the shared CEC serial as an s390x node identifier. +QEMU validation covers network IPL, DHCP options 209 and 210, TFTP, and the +network-specific PXELINUX configuration written by ``mknb``. Existing xCAT +s390x operating-system provisioning remains unchanged. + xCAT protocol ------------- @@ -234,12 +245,13 @@ checksums, reports, and optional signed extensions. Packages install each export under ``genesis-openembedded/ARCH``. ``mknb`` verifies and publishes that export when present, while retaining the old Genesis path as a fallback. -The management-node and service-node packages recommend the ``x86_64`` and -``ppc64le`` images. These are weak dependencies so an older or partial mirror -does not block an xCAT upgrade. Other target images can be installed from the -same common repository before running ``mknb ARCH``. RPM builds based on RPM -4.11 omit the recommendations because that version cannot parse weak dependency -tags. Install the required image package explicitly on those systems. +The management-node and service-node packages recommend the ``x86_64``, +``ppc64le``, ``riscv64``, and ``s390x`` images. These are weak dependencies so +an older or partial mirror does not block an xCAT upgrade. Other target images +can be installed from the same common repository before running ``mknb ARCH``. +RPM builds based on RPM 4.11 omit the recommendations because that version +cannot parse weak dependency tags. Install the required image package +explicitly on those systems. Server integration should be reviewed separately from the image. Independent bugs found while testing Genesis, such as TFTP path handling or Kea policy, @@ -259,7 +271,8 @@ actions. ``x86_64`` and ``ppc64le`` require physical tests before release. VM tests cannot certify platform firmware, BMC behavior, storage-controller tools, RDMA firmware operations, GPUs, Secure Boot on vendor firmware, or -board-specific device trees. +board-specific device trees. Physical ``s390x`` support also requires a qeth +activation path and IBM Z LPAR or z/VM validation. References ---------- diff --git a/docs/source/guides/admin-guides/references/man8/mknb.8.rst b/docs/source/guides/admin-guides/references/man8/mknb.8.rst index acb753076..975e9a8f0 100644 --- a/docs/source/guides/admin-guides/references/man8/mknb.8.rst +++ b/docs/source/guides/admin-guides/references/man8/mknb.8.rst @@ -42,12 +42,16 @@ An export is identified by \ ``xcat-genesis.manifest``\ , which records its form When multiple IPv4 addresses are configured for the same network, \ **mknb**\ uses a locally assigned \ ``site.master``\ for the xcatd endpoint, or the first address reported by the operating system when \ ``site.master``\ is not local. POWER discovery configurations also use this address for their kernel and initrd URLs. -OpenEmbedded images use the exact architecture names \ ``x86``\ , \ ``x86_64``\ , \ ``ppc64``\ , \ ``ppc64le``\ , \ ``armv7hf``\ , \ ``aarch64``\ , and \ ``riscv64``\ . If an OpenEmbedded \ ``ppc64le``\ image is not installed, \ **mknb**\ keeps the old behavior and uses the legacy \ ``ppc64``\ image. +OpenEmbedded images use the exact architecture names \ ``x86``\ , \ ``x86_64``\ , \ ``ppc64``\ , \ ``ppc64le``\ , \ ``armv7hf``\ , \ ``aarch64``\ , \ ``riscv64``\ , and \ ``s390x``\ . If an OpenEmbedded \ ``ppc64le``\ image is not installed, \ **mknb**\ keeps the old behavior and uses the legacy \ ``ppc64``\ image. Canonical \ ``ppc64``\ images are big-endian. xCAT marks them so \ ``ppc64le``\ nodes do not use them as a legacy little-endian fallback. \ **mknb**\ also refuses to replace a marked \ ``ppc64``\ image with that fallback. riscv64 nodes boot through UEFI firmware and grub2. For riscv64, \ **mknb**\ publishes the Genesis kernel and initramfs and writes one grub2 configuration per network under ``/tftpboot/boot/grub2``, named ``grub.cfg-`` followed by the network hex prefix, so that ``grub2.riscv64`` loaded by the firmware can start node discovery. The per-node files written by \ **nodeset**\ take priority over these network files. Networks served by a ``:noboot`` interface in ``site.dhcpinterfaces`` get no discovery configuration. +QEMU s390-ccw guests receive a network-specific ``pxelinux.cfg`` -style configuration through DHCP options 209 and 210. s390x Genesis does not use the shared IBM Z machine serial as a node identifier. This target supports Genesis discovery under QEMU. Existing s390x operating-system provisioning remains unchanged. Physical LPAR and z/VM Genesis networking remain unvalidated because QEMU does not emulate qeth and Genesis does not yet configure qeth channel groups. + +Run \ **makedhcp -n**\ after installing the s390x image and before booting s390x nodes. This adds the required DHCP options to existing configurations. + ******* OPTIONS diff --git a/xCAT-client/pods/man8/mknb.8.pod b/xCAT-client/pods/man8/mknb.8.pod index 6ffa74517..c1f01c3f4 100644 --- a/xCAT-client/pods/man8/mknb.8.pod +++ b/xCAT-client/pods/man8/mknb.8.pod @@ -24,12 +24,16 @@ An export is identified by C, which records its format ve When multiple IPv4 addresses are configured for the same network, B uses a locally assigned C for the xcatd endpoint, or the first address reported by the operating system when C is not local. POWER discovery configurations also use this address for their kernel and initrd URLs. -OpenEmbedded images use the exact architecture names C, C, C, C, C, C, and C. If an OpenEmbedded C image is not installed, B keeps the old behavior and uses the legacy C image. +OpenEmbedded images use the exact architecture names C, C, C, C, C, C, C, and C. If an OpenEmbedded C image is not installed, B keeps the old behavior and uses the legacy C image. Canonical C images are big-endian. xCAT marks them so C nodes do not use them as a legacy little-endian fallback. B also refuses to replace a marked C image with that fallback. riscv64 nodes boot through UEFI firmware and grub2. For riscv64, B publishes the Genesis kernel and initramfs and writes one grub2 configuration per network under C, named C followed by the network hex prefix, so that C loaded by the firmware can start node discovery. The per-node files written by B take priority over these network files. Networks served by a C<:noboot> interface in C get no discovery configuration. +QEMU s390-ccw guests receive a network-specific C-style configuration through DHCP options 209 and 210. s390x Genesis does not use the shared IBM Z machine serial as a node identifier. This target supports Genesis discovery under QEMU. Existing s390x operating-system provisioning remains unchanged. Physical LPAR and z/VM Genesis networking remain unvalidated because QEMU does not emulate qeth and Genesis does not yet configure qeth channel groups. + +Run B after installing the s390x image and before booting s390x nodes. This adds the required DHCP options to existing configurations. + =head1 OPTIONS =over 12 diff --git a/xCAT-genesis-builder/README.md b/xCAT-genesis-builder/README.md index fd6b56d4d..cd7324825 100644 --- a/xCAT-genesis-builder/README.md +++ b/xCAT-genesis-builder/README.md @@ -16,7 +16,8 @@ xCAT-genesis-builder/oe/build x86_64 ``` The build command accepts `x86`, `x86_64`, `ppc64`, `ppc64le`, `armv7hf`, -`aarch64`, and `riscv64`. Multiple architectures are built in the order given. +`aarch64`, `riscv64`, and `s390x`. Multiple architectures are built in the +order given. Artifacts are written below `xCAT-genesis-builder/oe/.work/build/tmp/deploy/images`. The `x86` artifact uses an i686 CPU baseline. The build carries the reviewed Yocto release key in `oe/keys` and verifies its fingerprint locally.