docs/PORTING_TO_NEW_ARCHITECTURES.md

   1 ---
   2 title: Porting to New Architectures
   3 category: Contributing
   4 layout: default
   5 SPDX-License-Identifier: LGPL-2.1-or-later
   6 ---
   7
   8 # Porting systemd to New Architectures
   9
  10 Here's a brief checklist of things to implement when porting systemd to a new
  11 architecture.
  12
  13 1. Patch
  14    [src/basic/architecture.h](https://github.com/systemd/systemd/blob/main/src/basic/architecture.h)
  15    and
  16    [src/basic/architecture.c](https://github.com/systemd/systemd/blob/main/src/basic/architecture.c)
  17    to make your architecture known to systemd. Besides an `ARCHITECTURE_XYZ`
  18    enumeration entry you need to provide an implementation of
  19    `native_architecture()` and `uname_architecture()`.
  20
  21 2. Patch
  22    [src/shared/gpt.h](https://github.com/systemd/systemd/blob/main/src/shared/gpt.h)
  23    and
  24    [src/shared/gpt.c](https://github.com/systemd/systemd/blob/main/src/shared/gpt.c)
  25    and define a new set of GPT partition type UUIDs for the root file system,
  26    `/usr/` file system, and the matching Verity and Verity signature
  27    partitions. Use `systemd-id128 new -p` to generate new suitable UUIDs you
  28    can use for this. Make sure to register your new types in the various
  29    functions in `gpt.c`. Also make sure to update the tables in
  30    [Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification)
  31    and `man/systemd-gpt-auto-generator.xml` accordingly.
  32
  33 3. If your architecture supports UEFI, make sure to update the `efi_arch`
  34    variable logic in `meson.build` to be set to the right architecture string
  35    as defined by the UEFI specification. (This ensures that `systemd-boot` will
  36    be built as the appropriately named `BOOT<arch>.EFI` binary.) Also, if your
  37    architecture uses a special boot protocol for the Linux kernel, make sure to
  38    implement it in `src/boot/efi/linux*.c`, so that the `systemd-stub` EFI stub
  39    can work.
  40
  41 4. Make sure to register the right system call numbers for your architecture in
  42    `src/basic/missing_syscall_def.h`. systemd uses various system calls the
  43    Linux kernel provides that are currently not wrapped by glibc (or are only
  44    in very new glibc), and we need to know the right numbers for them. It might
  45    also be necessary to tweak `src/basic/raw-clone.h`.
  46
  47 5. Make sure the code in `src/shared/seccomp-util.c` properly understands the
  48    local architecture and its system call quirks.
  49
  50 6. If your architecture uses a `/lib64/` library directory, then make sure that
  51    the `BaseFilesystem` table in `src/shared/base-filesystem.c` has an entry
  52    for it so that it can be set up automatically if missing. This is useful to
  53    support booting into OS trees that have an empty root directory with only
  54    `/usr/` mounted in.
  55
  56 7. If your architecture supports VM virtualization and provides CPU opcodes
  57    similar to x86' CPUID, consider adding native support for detecting VMs this
  58    way to `src/basic/virt.c`.