.\"	$NetBSD: compat_netbsd32.8,v 1.13 2019/01/17 07:05:24 gutteridge Exp $
.\"
.\" Copyright (c) 2001, 2019 Matthew R. Green
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd January 17, 2019
.Dt COMPAT_NETBSD32 8
.Os
.Sh NAME
.Nm compat_netbsd32
.Nd setup procedure for 32-bit compatibility on 64-bit platforms
.Sh DESCRIPTION
The
.Nm
module allows
.Nx Ns Tn /sparc64
to run
.Nx Ns Tn /sparc
executables,
.Nx Ns Tn /aarch64
to run
.Nx Ns Tn /arm
executables,
.Nx Ns Tn /mips64
to run
.Nx Ns Tn /mips
executables, and
.Nx Ns Tn /amd64
to run
.Nx Ns Tn /i386
executables.
On
.Nx Ns Tn /mips64
the default userland is N32 which is a handled by
.Nm
framework, and 64-bit binaries are handled similarly to the setup
for 32-bit compatibility.
It also provides compatibility between OABI and EABI binaries on 32-bit
.Nx Ns Tn /arm
ports.
.Pp
To use
.Nm ,
one must either have
.Dv COMPAT_NETBSD32
and
.Dv EXEC_ELF32
in the kernel, or load the compat_netbsd32 and exec_elf32 kernel
modules.
.Pp
Static executables typically need no additional setup.
Dynamic binaries require the dynamic linker plus shared libraries.
.Pp
Since
.Nx 5.0
the base system has directly included support for 32-bit compatibility
by installing 32-bit libraries and dynamic linker into
.Pa /usr .
This includes compiler support for compiling 32-bit applications
on platforms where this is supported.
.Pp
For a.out compatibility,
.Pa /usr/libexec/ld.so
from a 32-bit distribution is required to exist, and the a.out
shared libraries must be found in
.Pa /emul/aout
as normal for a.out compatibility.
For 32-bit (64-bit on
.Nx Ns Tn /mips64 )
ELF compatibility, the relevant
.Pa /usr/libexec/ld.elf_so
needs to be found in
.Bl -column -offset indent "powerpc64" "powerpc" ""
.It Sy Port Ta Sy Target Ta Sy Path
.It Li amd64 Ta i386 Ta /usr/libexec/ld.elf_so-i386
.It Li sparc64 Ta sparc Ta /usr/libexec/ld.elf_so-sparc
.It Li mips64 Ta O32 Ta /usr/libexec/ld.elf_so-o32
.It Li mips64 Ta N64 Ta /usr/libexec/ld.elf_so-64
.It Li powerpc64 Ta powerpc Ta /usr/libexec/ld.elf_so-powerpc
.It Li arm64 Ta eabi Ta /usr/libexec/ld.elf_so-eabi
.El
.Pp
Note that the kernel handles rewriting the builting ELF interpreter
to the above path.
.Pp
Before
.Nx 5.0
all of these files needed to be placed under
.Pa /emul/netbsd32 .
.Pp
The shared libraries for a.out binaries do not live under the
.Pa /emul/netbsd32
directory, but under the
.Pa /emul/aout
directory, where the a.out dynamic linker will find them.
.Sh BUGS
A list of things which fail to work in compatibility mode should
be here.
.Pp
.Xr aio 3
is not supported.
.Pp
Some
.Xr ioctl 2
commands are not supported, including
.Xr drm 4 .