$NetBSD: README.syscalls,v 1.3 2000/03/13 23:52:35 soren Exp $

XXX this file should be gutted.  functions' comments should go with
XXX the functions.  Further, this file is ... very out of date.

Once the new syscall argument-handling method was implemented, most
OSF/1 syscalls boiled down to their NetBSD equivalents.  The
differences are detailed in this file.

Note that some OSF/1 syscalls, including some of those that map
directly to equivalent NetBSD syscalls, are not implemented; they
were not needed, so the effort to implement and check them was not
expended.

Finally, there are some OSF/1 syscalls which were left unimplemented,
but which seem strange enough to merit a bit more explanation.

OSF/1 compatibility is helped by the fact that the sigcontext
structure was created for NetBSD/Alpha to be the same as the OSF/1
sigcontext structure.  Because of this, only one sendsig() function is
needed, and then the NetBSD sigreturn() function can be used for OSF/1
sigreturn(), as well.

The system calls are split out among the three files:
	osf1_ioctl.c
	osf1_misc.c
	osf1_mount.c
as follows:
	osf1_ioctl.c contains all osf1_ioctl() handling code.
	osf1_mount.c contains all code dealing with mounting and
		unmounting file systems, and with mount points in
		general (e.g. osf1_getfsstat()).
	osf1_misc.c contains the rest of the emulation functions.

The emulation functions as follows:

osf1_mknod()
	dev_t's are different between OSF/1 and NetBSD.  In OSF/1 a
	dev_t has 12 bits of major number and 20 bits of minor number.
	Under NetBSD, it's 24 bits of major, 8 bits of minor (but the
	top 16 bits of the major number are unused, and may be
	rearranged later).  In any case, it was decided that the
	primary use for OSF/1 binaries would be to complement native
	NetBSD binaries, so file system dev_t's are assumed to be in
	the NetBSD format, and osf1_mknod() translates from the OSF/1
	format to the NetBSD format.

osf1_getfsstat()
	The statfs structure is different between NetBSD and OSF/1,
	and the way file system types are denoted is different, as
	well.  This routine is the same as getfsstat(), except it
	converts the statfs structures before returning them to the
	OSF/1 process.

osf1_lseek()
	To compensate for quad alignment on 32-bit machines, the
	NetBSD lseek() needs an extra argument of padding, before the
	off_t 'offset' argument.  This wrapper inserts the padding,
	and calls the NetBSD routine.

osf1_mount()
	The file system type specification and the way you specify
	mount options differs substantially between NetBSD and OSF/1.
	This routine (and its callees) fakes up NetBSD arguments, and
	calls the NetBSD routine.

osf1_unmount()
	Probably not necessary, but safe; translates flags, in case
	the NetBSD unmount flags ever change.

osf1_exec_with_loader() [UNIMPLEMENTED]
	From the description in the OSF/1 manual page, this executes a
	file with a named loader, or "/sbin/loader" if none is named.
	It appears to be used in some way, when executing dynamically
	linked binaries, but is _not_ called directly from user space
	in the normal case.  The interface by which it passes the name
	of the file to be executed, its arguments, etc., to the loader
	is unspecified, and, from experimental evidence, doesn't seem
	to be the normal UN*X argument-passing convention (i.e.
	argc/argv).  For proper dynamically linked binary support,
	this function will probably have to be implemented, but it's
	unclear how that can be done (short of disassembling a lot of
	code).

osf1_open()
	Translates OSF/1 flags to NetBSD flags.

osf1_ioctl()
	Screens out ioctl requests that aren't known to work, and
	translates those that differ between NetBSD and OSF/1.

osf1_reboot()
	Translates OSF/1 flags to NetBSD flags.

osf1_stat()
	The stat structure differs between NetBSD and OSF/1, both in
	terms of field sizes, and in the dev_t representation.
	This does a NetBSD stat(), translates the results, and returns
	them to the OSF/1 process.

osf1_lstat()
	Same as osf1_stat(), but for lstat().

osf1_mmap()
	The NetBSD version needs 4 bytes of padding before the off_t
	'pos' argument, and also uses different flags than the OSF/1
	version.  This wrapper translates the flags and deals with the
	argument struct padding differences, then calls the NetBSD
	routine.

osf1_fstat()
	Same as osf1_stat(), but for fstat().

osf1_fcntl()
	Translates OSF/1 fcntl() requests into their NetBSD
	counterparts, then calls the NetBSD fcntl() to do the
	operations.

osf1_socket()
	Makes sure that the socket type is valid for NetBSD, and if
	so, calls NetBSD's socket().

osf1_sendto()
	Makes sure that the 'flags' argument doesn't use flags that
	NetBSD can't handle, and calls NetBSD's sendto().

osf1_getrlimit()
	Makes sure that the 'which' selector is one that NetBSD can
	deal with, and calls NetBSD's getrlimit().

osf1_setrlimit()
	Same as osf1_getrlimit(), but for setrlimit().

osf1_sigaction()
	Deals with the differences in the NetBSD and OSF/1 sigaction
	structures, and calls NetBSD's sigaction with the appropriate
	arguments.  If the call requests that the old sigaction be
	passed back, osf1_sigaction() translates it back to the OSF/1
	form, and returns it appropriately.

osf1_statfs()
	Does that statfs() on the given pathname, then translates the
	NetBSD statfs structure into the one that OSF/1 uses and
	returns it.  Makes a best effort on the mount type, because
	there's not a one-to-one mapping between NetBSD and OSF/1
	mount types.

osf1_fstatfs()
	Same as osf1_statfs(), but for fstatfs().

osf1_usleep_thread()
	This function is how sleep() and usleep() (and possibly other
	functions) are implemented in OSF/1.  Its usage was discovered
	by disassembling the library routines that use it.  It takes
	two pointers to timeval structures as arguments.  The first
	contains the amount of time (in seconds and microseconds) to
	sleep.  If the second pointer is non-null, if the process
	wakes up early, the amount of time "unslept" is returned.  If
	the process doesn't wake up early, zero is returned.

osf1_setsysinfo()
	A null-op; used early on, but nothing cares that it actually
	does anything.
