Contributing new ports to glibc

This page discusses issues relating to contributing new ports to glibc (oriented to ports to new CPU architectures using the Linux kernel, rather than to new operating system ports). It should be read together with the general Contribution checklist, Style_and_Conventions and the GNU Coding Standards.

Before posting patches to add a new port, make sure that the code is covered by an FSF copyright assignment. Reviewers are unlikely to look in detail at any substantial code not covered by such an assignment.

Being a port maintainer

If your port is accepted for inclusion in glibc, you (or other people nominated in the submission) will become maintainers of the port. You'll need wiki accounts with write access; if you don't have write access, create an account and post the name to libc-alpha to ask someone to add you to EditorGroup. You'll also need editbugs access in Bugzilla, which is automatic for accounts with an / address; if you want to use another address in Bugzilla, ask on libc-alpha for someone to give that account editbugs access.

Being a maintainer is an individual responsibility, not linked to a particular employment, although maintainers can step down at any time. To contribute to glibc you need to be covered by an FSF copyright assignment that covers future changes (either a corporate assignment, or an individual assignment together with any employer disclaimer needed in your circumstances). If you cease to be covered by an assignment, you cannot contribute further changes until you are covered by another assignment, but can still review other people's patches.

When adding a port, you need to update MAINTAINERS to list the maintainers for that port. You need to update ABIList to list the ABIs and dynamic linker names for the port. You need to update PortStatus to reflect whether the port supports features listed there as only supported by some ports. You need to update the template Release/X.Y to include a section where test results for this port would be reported in the copy of that page for each subsequent release, and, likewise, update the copy of that page (as linked from Release) for the current release cycle.

During each release's freeze period (January and July each year) you'll need to report test results for the port in that section on that release's wiki page.

It is not yet necessary to have a build slave for the glibc Buildbot to run tests for the port, although having one, or otherwise testing frequently enough that problems aren't detected only during the release freeze periods, is certainly helpful.

As a maintainer, you need to be familiar with the Committer checklist and the rules for determining Consensus. You will commit most of your own patches without review, but they are still subject to the usual coding standards. Committed patches still need to be posted to libc-alpha. Once the port has been released, port-specific bug fixes are subject to the usual rule that you create a bug report in Bugzilla for any bug that was user-visible in a release, before fixing it, then mark the bug FIXED with target milestone set to the next release version once a fix has been checked in to master.

Contents of a port submission

When submitting a new port, the submission will include a summary message describing the port as a whole, as well as a patch or patches that serve to add the port to glibc. Various information should be included in the summary message.

For a port to go into glibc, the corresponding GCC, binutils and Linux kernel ports must be upstream first. This means upstream in the development mainlines of the respective components (possibly in linux-next with an expressed intent to go into Linus's tree in the next merge window, in the case of Linux kernel ports, but not at any earlier stage of being contributed upstream), not necessarily in any release branches. Ports may be considered on libc-alpha before the upstream contribution of GCC, binutils and the Linux kernel has reached that point, but cannot be checked into the master branch of the glibc repository until those other pieces are upstream. If not yet upstream, the summary message should give details of the status of contribution work for those components.

The upstream versions of those components need to be sufficient to build a working glibc, with the testsuite results given; the kernel/userspace ABI used by the upstream Linux kernel port must match that expected by the glibc port. If patches required for those purposes are not in the respective upstream development mainlines, that's equivalent to the ports not being upstream: detailed information should be given in the summary message and the port can't go into glibc until the required patches to the other components have gone upstream.

Although the GCC and binutils ports need not be in upstream release branches, if they are, it is helpful to backport any required patches to those branches, to facilitate people testing building the glibc port and to help GNU/Linux distributors who may wish to build distributions for the new architecture.

There is no requirement for a CPU simulator (free software, e.g. QEMU, or otherwise) to be available, but if one is available, it is useful to mention in the summary message (along with any information on available OS etc. that might help people set up an environment for testing things about the port).

The summary message should include pointers to manuals documenting the instruction set (instruction semantics for userspace instructions, not necessarily microarchitectural performance details or instructions that can only be used in the kernel) and ABI used by the port. Direct URLs to the manuals in question are preferred if available. If pointing to a page with many different manuals, indicate which are the relevant instruction set and ABI manuals.

You need to have run the full glibc testsuite for the new port (if there are multiple different configurations, e.g. different endianness or hard and soft float, it should be run for the different configurations). This means the execution tests as well as the compilation tests. This may be run either natively, or in cross testing with test-wrapper set accordingly to execute tests on a different system from the glibc build. For a configuration to be considered in reasonable shape for inclusion in glibc, there should be at most 20 architecture-specific FAILs (refer to the per-release wiki pages to see what known non-architecture-specific FAILs for some kinds of build and test configurations are).

The summary message should include the summary of test results from the end of make check output. In addition, include a pointer to where more detailed test results can be downloaded (at least the full make check output, and the .out and .test-result files for all tests that did not PASS).

The results of the compilation parts of the testsuite, as run by for the new configurations added to it, must be completely clean; no failures are permitted there for new ports.

If you need to update scripts/config.sub or scripts/config.guess from git://, that should be posted as a separate patch, outside of the main patch series adding the port. The update should update both those files to the latest versions from that repository, with no glibc-local changes; do not just patch those files for your architecture. Likewise if you need to update stdlib/longlong.h from GCC, but in that case make sure there are no glibc-local changes being lost as a result of copying in the latest version from GCC, as sometimes changes may have been applied just to glibc.

Sometimes a port may need bug fixes or new features in files not in architecture-specific directories, other than the cases noted below where this is generally expected. This is most likely to apply because of changes to the preferred asm-generic syscall interface for new architectures in the Linux kernel. For example, the C-SKY port required support for implementing stat-family functions using the statx syscall, because the Linux kernel stopped providing the separate stat syscalls for new ports. In such a case, do not add the new support in architecture-specific files, because it should actually apply for all new Linux kernel architectures (and one architecture including files from another is now deprecated in glibc). Rather, add the support in architecture-independent files, with whatever conditionals are appropriate to avoid affecting any existing architectures for which the change is inappropriate. Such architecture-independent changes should be separate patches, not part of the main patch series adding the port.

Contents of an architecture port

Most of a new port is new files in the directories sysdeps/<arch> and sysdeps/unix/sysv/linux/<arch>. However, a few pieces involve changes to architecture-independent files:

When a new port is added to glibc, there is no expectation that it needs to be ABI-compatible with any version of the port that was previously being used. In particular, the architecture's shlib-versions file should set the DEFAULT ABI to the symbol version of the first glibc release to get the port (if the port doesn't get into the first release for which it is submitted, this version needs updating again). No older symbol versions should appear in any Versions files for the port. No port-specific files should have any SHLIB_COMPAT conditionals when first added to glibc; those are only relevant once symbols become compat symbols after the first release with the port has been made.

New ports are expected to use different dynamic linker names (specified with ld= in shlib-versions) for every ABI variant supported by the port (such as big and little endian, or hard and soft float if those use different ABIs); even if only one ABI variant is supported, the dynamic linker name should be unique to that architecture; this helps distributions using Debian/Ubuntu-style multiarch directory arrangements. Note that GCC needs to know the names used, as it passes -dynamic-linker options to ld. If GCC supports more ABI variants than the glibc port does (e.g., if it supports both endiannesses but you only wish to support one for glibc), there must be configure-time or build-time errors in glibc to prevent it being built for the unsupported variants.

The sysdeps/unix/sysv/linux/<arch>/ fragment must set arch_minimum_kernel to the first upstream kernel version that has the architecture port, with the kernel/userspace ABI used by the port, sufficiently functional to use the glibc port, unless that version is older than the architecture-independent minimum for glibc (in which case do not set arch_minimum_kernel at all). If submitting a port for initial review before the kernel port is upstream, use arch_minimum_kernel=10.0.0, and change to the actual version later once known.

Since 2011 there has been substantial work in glibc on sharing more code between architectures in glibc; this goes along with the Linux kernel adoption of the asm-generic syscall interface for new Linux kernel ports, which reduces architecture differences in the kernel/userspace interface. Thus, consider carefully whether architecture-specific files in your port do actually relate to something architecture-specific, or whether a generic implementation would be fully sufficient for the port. (There are still a few cases where architectures need their own copies of files that are very similar between architectures, but we are trying to reduce the number of such cases.) It may not be necessary to have any files in sysdeps/unix/sysv/linux/<arch>/bits/ other than procfs.h, if your architecture uses the asm-generic syscall interface; if you have other files there, make sure they are indeed needed with current glibc to describe your port's kernel/userspace interface accurately.

Sharing code applies to non-OS-specific code, as well as to OS-specific code; some of the main examples follow.

Normally your atomic-machine.h should define USE_ATOMIC_COMPILER_BUILTINS to 1, and only define the limited number of macros present in headers such as sysdeps/aarch64/atomic-machine.h, avoiding use of asm for atomic operations. If you cannot do this, there should be a clear justification in comments (probably that your architecture does not support the required atomic operations so use of kernel helpers is required; dependencies on external libatomic must be avoided in glibc).

NPTL header pthreadtypes-arch.h defines the layout of pthread types. It is recommended that __PTHREAD_MUTEX_{NUSERS_AFTER_KIND,USE_UNION} be set to 0 for new ports.

For new architectures, try to configure your GCC port to use init_array unconditionally, so that you do not need crti.S or crtn.S in glibc at all and instead can use the init_array sysdeps directory.

Although benchmark results are not required for new ports, consider carefully whether architecture-specific string functions are actually required. If good generic C versions would be as good as your assembler versions, consider helping to get Richard Henderson's / Adhemerval Zanella's improved generic string functions into glibc instead of adding architecture-specific implementations.

None: NewPorts (last edited 2019-01-30 22:01:42 by VineetGupta)