sysm68k(2) — SYSTEM CALLS
NAME
sysm68k − machine-specific functions
SYNOPSIS
#include <sys/types.h>
#include <sys/sysm68k.h>
int sysm68k(int cmd, . . .);
DESCRIPTION
sysm68k implements machine-specific functions. The cmd argument determines the function performed. The type and number of arguments expected depends on the function.
Command RTODC
When cmd is RTODC, an argument of type time_t ∗ is expected.
This function reads the hardware time-of-day clock and returns the number of seconds since midnight, January 1, 1970, in the time_t structure referred to by the argument. This command is available only to the super-user.
Command SM68KSYM
When cmd is SM68KSYM, the symbol table created when a new bootable operating system is configured may be accessed. The symbols available via this command are defined in one of two places: the driver routines loaded or the variable specifications in the files in the /etc/master.d directory. Two arguments are expected: the first must be a pointer to a buffer into which the symbol table is copied, and the second must be an integer containing the total size of the buffer. The format of the symbol table is:
int size; /∗ symbol size in bytes ∗/
int count; /∗ total number of symbols ∗/
/∗ Each symbol is stored as: ∗/
/∗ char name[]; (padded ∗/
/∗ with ’\0’ to next ∗/
/∗ sizeof(long) boundary ∗/
/∗ long value; the symbol’s value ∗/
The SM68KSVAL macro in sys/sysm68k.h takes a pointer to a symbol name in the table and returns its value. The SM68KNXTSYM macro takes a pointer to a symbol name in the table and returns a pointer to the next entry.
Typically, the symbol table would be retrieved with two calls to sysm68k. First, the size of the symbol table is obtained by calling sysm68k with a buffer of one integer. This integer is then used to obtain a buffer large enough to contain the entire symbol table. The second invocation of sysm68k with this newly obtained buffer retrieves the entire symbol table.
#include <sys/sysm68k.h>
int size; /∗ size of buffer needed ∗/
struct sm68ksym ∗buffer; /∗ buffer pointer ∗/
sysm68k( SM68KSYM, (struct sm68ksym ∗) &size, sizeof(size) );
buffer = (struct sm68ksym ∗) malloc( size );
sysm68k( SM68KSYM, buffer, size );
Command SMCONF
When cmd is SMCONF, the configuration table created during the configuration of a new bootable operating system may be accessed. This table contains the names and locations of the devices supported by the currently running UNIX system, the names of all software modules included in the system, and the names of all devices in the EDT that were ignored. Two arguments are expected: the first must be a pointer to a buffer into which the configuration table is copied, and the second must be an integer containing the total size of the buffer. The format of the configuration table is:
intcount;/∗ total number of entries ∗/
/∗ for each entry ... ∗/
time_ttimestamp;/∗ f_timdat from file header ∗/
charname[DIRSIZ]; /∗ name of device/module ∗/
unsigned char flag; /∗ configuration information ∗/
/∗ 0x80: device ignored ∗/
/∗ 0x40: name[] is a driver ∗/
/∗ 0x20: name[] is a software module ∗/
unsigned char mmajor; /∗ external major device number∗/
Typically, the configuration table would be retrieved with two calls to sysm68k. First, the number of entries is obtained by calling sysm68k with a buffer of one integer. This integer is then used to calculate and obtain a buffer large enough to contain the entire configuration table. The second invocation of sysm68k with this newly obtained buffer retrieves the configuration table.
#include <sys/sysm68k.h>
intcount;/∗ total number of devices ∗/
intsize;/∗ size of buffer needed ∗/
structsmconf ∗buffer;/∗ buffer pointer ∗/
sysm68k( SMCONF, (struct smconf ∗)&count, sizeof(count));
size = sizeof(int);
size += count ∗ sizeof(struct smc);
buffer = (struct smconf ∗)malloc(size);
sysm68k(SMCONF, buffer, size);
Command XGETEDT
When cmd is XGETEDT, the extended EDT table (XEDT) for a specified device controller is returned. This table contains the names and locations of the devices attached to the argument controller. Three arguments are expected: the first must be a dev_t that specifies the controller to be accessed, the second is a pointer to a buffer into which the extended EDT table is copied, and the third must be an
integer containing the total size of the buffer. The format of the extended EDT table is:
intcount;/∗ total number of entries ∗/
/∗ for each entry ... ∗/
charx_name[X_XNAMLEN}; /∗ device name/information ∗/
intx_unit;/∗ unit number on controller ∗/
u_intx_ksize;/∗ size in kbytes ∗/
Typically, the extended EDT table would be retrieved with two calls to sysm68k. First, the number of extended EDT entries for the controller specified by the device argument is obtained by calling sysm68k with a buffer of one integer. This integer is then used to calculate how large a buffer is needed to contain the entire extended EDT table for the controller, and that buffer is then obtained. The second invocation of sysm68k with this newly obtained buffer retrieves the extended EDT table.
#include <sys/sysm68k.h>
#include <sys/edt.h>
intcount;/∗ total number of devices ∗/
intsize;/∗ size of buffer needed ∗/
structkxedt ∗buffer;/∗ buffer pointer ∗/
sysm68k( XGETEDT, dev, &count, sizeof(count) );
size = sizeof(int);
size += count ∗ sizeof(struct xedt);
buffer = (struct kxedt ∗)malloc(size);
sysm68k( XGETEDT, dev, buffer, size);
Command GET_MR_TBL
When cmd is XGET_MR_TBL, the memory region table for the kernel is returned. This table contains the names, location, ID, and attribute IDs for each memory region configured into the kernel. Two arguments are expected: the first is a pointer to a buffer into which the memory region table is copied, and the second must be an
integer containing the total size of the buffer.
Typically, the memory region table would be retrieved with two calls to sysm68k. First, the number of memory regions is obtained by calling sysm68k with a buffer of one integer. This integer is then used to calculate how large a buffer is needed to contain the entire memory region table, and that buffer is then obtained. The second invocation of sysm68k with this newly obtained buffer retrieves the memory region table.
#include <sys/mrt.h>
#include <sys/sysm68k.h>
intcount;/∗ total number of entries ∗/
intsize;/∗ size of buffer needed ∗/
structmrt_x∗buffer;/∗ buffer pointer ∗/
sysm68k( GET_MR_TBL, &count, sizeof(count) );
size = sizeof(int);
size += count ∗ sizeof(struct mrt);
buffer = (struct mrt_x ∗)malloc(size);
sysm68k( GET_MR_TBL, buffer, size);
Command GET_MA_TBL
When cmd is XGET_MA_TBL, the memory attribute table for the kernel is returned. This table contains the attributes associated with the memory regions configured into the kernel. Two arguments are expected: the first is a pointer to a buffer into which the memory attribute table is copied, and the second must be an
integer containing the total size of the buffer.
Typically, the memory attribute table would be retrieved with two calls to sysm68k. First, the number of attributes is obtained by calling sysm68k with a buffer of one integer. This integer is then used to calculate how large a buffer is needed to contain the entire memory attribute table, and that buffer is then obtained. The second invocation of sysm68k with this newly obtained buffer retrieves the memory attribute table.
#include <sys/mrt.h>
#include <sys/sysm68k.h>
intcount;/∗ total number of entries ∗/
intsize;/∗ size of buffer needed ∗/
structmatr_x∗buffer;/∗ buffer pointer ∗/
sysm68k( GET_MA_TBL, &count, sizeof(count) );
size = sizeof(int);
size += count ∗ sizeof(struct mrt);
buffer = (struct matr_x ∗)malloc(size);
sysm68k( GET_MA_TBL, buffer, size);
Command MDRVRINFO
When cmd is MDRVRINFO, a command may be issued directly to a device driver. Three arguments are expected: the first must be a dev_t that specifies the device the command is for, second is the command to send to the device driver, and the third is command specific.
Command SM68KBOOT
When cmd is SM68KBOOT, the timestamp and path name of the program last used to bootstrap the machine may be accessed. The path name of the a.out format file which was booted, and the timestamp from the file header [see a.out(4)] are saved. One argument is expected: a pointer to a buffer into which the information is copied. The format of this information is:
time_ttimestamp;/∗ f_timdat from file header ∗/
charpath[100];/∗ path name ∗/
This information would be retrieved with a single call to sysm68k.
#include <sys/sysm68k.h>
struct sm68kboot buffer; /∗ buffer ∗/
sysm68k(SM68KBOOT, &buffer);
Command SM68KAUTO
When cmd is SM68KAUTO, no arguments are expected. This function returns a boolean value in answer to the question, “Was the operating system reconfigured during the last boot, or was an existing bootable operating system booted?” The value returned is zero if an existing bootable (such as /stand/stand/unix or /stand/unix) was booted. The integer value 1 is returned if the bootable operating system was configured during the preceding boot process. This command is available only to the super-user.
Command SM68KSWPI
NOTE: This cmd is compatible with UNIX System V Release 2.1 and Release 3 software. Its function is subsumed by the swap command; see swap(1M).
When cmd is SM68KSWPI, individual swapping areas may be added, deleted or the current areas determined. The address of an appropriately primed swap buffer is passed as the only argument. (Refer to the sys/swap.h header file for details of loading the buffer.)
The format of the swap buffer is:
struct swapint {
charsi_cmd;/∗command: list, add, delete∗/
char∗si_buf;/∗swap file path pointer∗/
intsi_swplo; /∗start block∗/
intsi_nblks;/∗swap size∗/
}
Note that the add and delete options of the command may be exercised only by the super-user.
Typically, a swap area is added by a single call to sysm68k. First, the swap buffer is primed with appropriate entries for the structure members. Then sysm68k is invoked.
#include <sys/sysm68k.h>
#include <sys/swap.h>
struct swapint swapbuf;/∗swap into buffer ptr∗/
sysm68k(SM68KSWPI, &swapbuf);
If this command succeeds, it returns 0 to the calling process. It fails and returns −1 if one or more of the following is true:
EFAULT swapbuf points to an invalid address.
EFAULT swapbuf.si_buf points to an invalid address.
ENOTBLK The swap area specified is not a block special device.
EEXIST The swap area specified has already been added.
ENOSPC Too many swap areas are in use (if adding).
ENOMEM The swap area specified is the last remaining swap area.
ENOMEM There is no place to put swapped pages when deleting a swap area.
EINVAL An argument is invalid.
Command STIME
When cmd is STIME, an argument of type long is expected. This function sets the system time and date. The argument contains the time as measured in seconds from 00:00:00 UTC January 1, 1970. This command is available only to the super-user.
Command SM68KTRAPLOCORE
Prior to release 4.0, user processes could read low memory (for example, read accesses using NULL pointers were permitted from user programs). When cmd is SM68KTRAPLOCORE, user level access permission on low core memory can be changed and user accesses of low core memory can be trapped. Only read access is affected; user level write access to low core is not allowed under any circumstances.
A single argument of type int is expected. This argument may have one of the following five values, defined in <sys/sysm68k.h>:
SM68KTLC_DISABLE
Disable low core trapping. Read accesses to low core are allowed from user processes.
SM68KTLC_SIGNAL
Trap low core accesses. Any user process which attempts to read low core will be sent a SIGSEGV signal with si_code set to SEGV_MAPERR.
SM68KTLC_PRINT
Trap low core accesses. Any user process which attempts to read low core will be sent a SIGSEGV signal with si_code set to SEGV_MAPERR. In addition, a message will be printed on the system console each time a process attempts to read low core.
SM68KTLC_WARN
Trap low core accesses and print a message on the system console identifying the process and the address accessed. Do not send signals to the process.
SM68KTLC_STATUS
Return current state of low core trapping. The state of low core trapping is unchanged.
If this command succeeds, it returns one of SM68KTLC_DISABLE, SM68KTLC_SIGNAL, SM68KTLC_PRINT, to indicate the setting of low core protection prior to the call. NOTE: this command changes behavior for all processes, not just for the current process. The command fails and returns −1 if one or more of the following is true:
EPERM The caller is not super-user (not required for SM68KTLC_STATUS).
EINVAL An argument is invalid.
Command CRASHDUMP
When cmd is CRASHDUMP, two arguments are expected - pathname and flag. This function enables crash dumps to the special device defined by the pathname and sets the mode of crash dumps per the value of the flag. If pathname is NULL, then crash dumps are disabled.
The flag must be 0 or joined by an “or” with any of the following values (defined in crash.h): CRASH_DUMPS_ASK - the crash dump system prompts the user for preparing the dump device and to resolve errors
The default action unless modified by one of the above is that the crash dump system does not prompt the user to prepare the dump device and fails if an error occurs.
The special device used for crash dumps must have sufficient room to hold an image of physical memory or not all of the crash dump will be saved. If the device is a disk-drive slice, it must be tagged with V_SWAP. If the device is currently used for swapping, it must have sufficient room to allow the system to be rebooted and the crash dump to be retrieved before it is corrupted. The crash dump is stored at the rear of a slice if possible to facilitate some swapping.
Command SETNAME
When cmd is SETNAME, an argument of type char ∗ is expected. This function sets the new node name and can consist of alphanumeric and the special characters dash, underbar, and dollar sign. The node name argument is restricted to SYS_NMLN characters. SYS_NMLN is an implementation specific value defined in <sys/utsname.h>. This command is available only to the superuser.
Command SETSYSNAME
When cmd is SETSYSNAME, an argument of type char ∗ is expected. This function sets the new system name and can consist of alphanumeric and the special characters dash, underbar, and dollar sign. The system name argument is restricted to SYS_NMLN characters. SYS_NMLN is an implementation specific value defined in <sys/utsname.h>. This command is available only to the superuser.
Command SERIALIZE_MEMORY_ACCESS
Many processors execute and complete load and store instructions in the order in which they are encountered. Some processors, for efficiency reasons, overlap instruction executions and do not This command is intended to force the processor to access all hardware addresses in the exact order specified by the program.
Currently, the calling this command is supported, but it has no effect. It returns a value of zero.
Command DESERIALIZE_MEMORY_ACCESS
This command is intended to restore the processor to concurrent memory access, after it has been serialized with the DESERIALIZE_MEMORY_ACCESS command. Calling this command is supported, but in the current implementation it has no effect. It returns a value of zero.
DIAGNOSTICS
On success, sysm68k returns a value that depends on cmd as follows:
SM68KSYM A value of zero.
SM68KCONF
A value of zero.
SM68KBOOT
A value of zero.
CRASHDUMP
A value of zero.
SM68KAUTO
A value of zero if an existing bootable operating system (such as /stand/stand/unix or /stand/unix) was last booted. A value of one if a new bootable operating system was configured during the last boot process.
SM68KTRAPLOCORE
Returns the setting of low core protection prior to the call.
Otherwise, a value of −1 is returned and errno is set to indicate the error. When cmd is invalid, errno is set to EINVAL on return.