Implement a FreeBSD syscall layer

[andrewrk]

source: https://lobste.rs/s/yjd59n/crt_free_2023_tips_tricks#c_viakfm

The task is to change this to false for FreeBSD:

zig/lib/std/target.zig

Lines 398 to 413 in 282cb5e

	/// On Darwin, we always link libSystem which contains libc.
	/// Similarly on FreeBSD and NetBSD we always link system libc
	/// since this is the stable syscall interface.
	pub fn requiresLibC(os: Os) bool {
	return switch (os.tag) {
	.freebsd,
	.netbsd,
	.macos,
	.ios,
	.tvos,
	.watchos,
	.dragonfly,
	.openbsd,
	.haiku,
	.solaris,
	=> true,

And then go implement syscalls in the standard library via inline assembly like we already do for Linux rather than relying on libc for this target.

This is great news, hurray! We no longer need to build libc in order to cross-compile zig code for this target.

[davidchisnall]

All of the system call stubs in FreeBSD are machine generated from syscalls.master. If you want them as inline assembly, you can probably reuse the code.

Note that the syscall calling convention is a little bit interesting on FreeBSD. Arguments are passed in the same location that they are for normal function calls (just replace the call instruction with syscall), with the exception of x8-64, where the SysV ABI defines a different register for one of the arguments (the trampoline is then just a register-register move and a syscall). The return values are more complex. On sensible architectures the error state is defined by the carry bit. If the carry bit is set, the return value register contains the errno value, if it is not set then it contains the result. This lets you branch on carry to detect failure. I believe MIPS and RISC-V use the second return register.

[andrewrk]

Thanks for the tips!

[RealDeuce]

So, it's worth noting though that syscalls.master is version-specific and will change across FreeBSD major versions.
For example, swapoff() changed from 13 to 14:

424	AUE_SWAPOFF	COMPAT13 {
		int swapoff(
		    _In_z_ const char *name
		);
	}


582	AUE_SWAPOFF	STD {
		int swapoff(
		    _In_z_ const char *name,
		    u_int flags,
		);
	}

COMPATXX are optionally compiled in (IIRC, the current supported releases are included by default). I've assumed this is why FreeBSD has used libc for syscalls.

[andrewrk]

I'm feeling a bit confused about whether there is a stable syscall ABI or not. What can an application developer expect if they provide a binary to a FreeBSD OS user?

[RealDeuce]

Just looked... it appears GENERIC includes COMPATXXX all the way back to 4 when it was introduced, so less of a concern than I thought.

[RealDeuce]

So my understanding is that basically, the ABI is stable, but it's possible for the user to exclude parts of it.

I just discovered that by default, the whole thing is included... I had previously thought old syscalls were removed from the default kernel, but that's not true.

[RealDeuce]

So an application developer can expect that the binary will work for the version it was compiled for, and every version after that unless the user has built a custom kernel that removes backward compatibility.

[RealDeuce]

So the only real "gotcha" is making sure that the syscalls.master used is from the oldest supported FreeBSD, to avoid using syscalls from the future.

[mikdusan]

For our purposes, syscalls.master is lacking some information. Specifically, we need to map a syscall to the semver of FreeBSD where it was introduced. The good news is information can be gleaned from the freebsd.src repository's tagged versions of syscalls.master.

Using syscall swapoff as an example, the latest release 13.2.0 syscalls.master provides this information:

1. syscall_424 swapoff is marked with COMPAT13 meaning after 13.0.0 this became backwards compatible.
2. syscall_582 swapoff is marked with STD meaning this is current for 13.2.0. But it doesn't tell us exactly when it was introduced. We can guess it was introduced at or after 13.0.0 but "at or after" is not good enough.

Manually searching history we learn:

1. syscall_424 swapoff was introduced in 5.1.0. Interestingly, the manpage suggests 5.0.0 was the introduction.
2. syscall_582 swapoff was introduced in 13.1.0.

This looks very promising indeed!

[RealDeuce]

I'm not sure why the semver for each syscall would be needed unless the plan is to have each FreeBSD release from 4.x on be a unique target... not that I'm opposed to that, it just seems like a lot of unnecessary work, and makes targeting "FreeBSD" more complex than I would expect it to be.

[igalic]

I believe MIPS and RISC-V use the second return register.

MIPS is no longer supported.