sysm88k(2) — SYSTEM CALLS
NAME
sysm88k − machine-specific functions
SYNOPSIS
#include <sys/types.h>
#include <sys/sysm88k.h>
int sysm88k(int cmd, . . .);
DESCRIPTION
sysm88k 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 struct todc ∗ is expected.
struct todc {
short htenths;
short hsecs;
short hmins;
short hhours;
short hdays;
short hweekday;
short hmonth;
short hyear;
};
This function reads the hardware time-of-day clock and returns the number of seconds since midnight, January 1, 1970, in the todc structure referred to by the argument. This command is available only to the super-user.
Command SM88KMAXPROC
When cmd is SM88KMAXPROC, the maximum number of processes is returned. The result will be placed in the argument which must be an integer pointer.
Command SM88KSYM
When cmd is SM88KSYM, 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 SM88KSVAL macro in sys/sysm88k.h takes a pointer to a symbol name in the table and returns its value. The SM88KNXTSYM 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 sysm88k. First, the size of the symbol table is obtained by calling sysm88k 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 sysm88k with this newly obtained buffer retrieves the entire symbol table.
#include sys/sysm88k.h
int size; /∗ size of buffer needed ∗/
struct sm88ksym ∗buffer; /∗ buffer pointer ∗/
sysm88k( SM88KSYM, (struct sm88ksym ∗) &size, sizeof(size) );
buffer = (struct sm88ksym ∗) malloc( size );
sysm88k( SM88KSYM, 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 nmajor; /∗ external major device number ∗/
Typically, the configuration table would be retrieved with two calls to sysm88k. First, the number of entries is obtained by calling sysm88k 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 sysm88k with this newly obtained buffer retrieves the configuration table.
#include sys/sysm88k.h
intcount;/∗ total number of devices ∗/
intsize;/∗ size of buffer needed ∗/
structsm88kconf ∗buffer; /∗ buffer pointer ∗/
sysm88k(SMCONF, (struct sm88kconf ∗)&count, sizeof(count));
size = sizeof(int);
size += count ∗ sizeof(struct sm88kc);
buffer = (struct sm88kconf ∗)malloc(size);
sysm88k(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 sysm88k. First, the number of extended EDT entries for the controller specified by the device argument is obtained by calling sysm88k 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 sysm88k with this newly obtained buffer retrieves the extended EDT table.
#include <sys/sysm88k.h>
#include <sys/edt.h>
intcount;/∗ total number of devices ∗/
intsize;/∗ size of buffer needed ∗/
structkxedt ∗buffer;/∗ buffer pointer ∗/
sysm88k( XGETEDT, dev, &count, sizeof(count) );
size = sizeof(int);
size += count ∗ sizeof(struct xedt);
buffer = (struct kxedt ∗)malloc(size);
sysm88k( 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 sysm88k. First, the number of memory regions is obtained by calling sysm88k 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 sysm88k with this newly obtained buffer retrieves the memory region table.
#include <sys/mrt.h>
#include <sys/sysm88k.h>
intcount;/∗ total number of entries ∗/
intsize;/∗ size of buffer needed ∗/
structmrt_x∗buffer;/∗ buffer pointer ∗/
sysm88k( GET_MR_TBL, &count, sizeof(count) );
size = sizeof(int);
size += count ∗ sizeof(struct mrt);
buffer = (struct mrt_x ∗)malloc(size);
sysm88k( 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 sysm88k. First, the number of attributes is obtained by calling sysm88k 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 sysm88k with this newly obtained buffer retrieves the memory attribute table.
#include <sys/mrt.h>
#include <sys/sysm88k.h>
intcount;/∗ total number of entries ∗/
intsize;/∗ size of buffer needed ∗/
structmatr_x∗buffer;/∗ buffer pointer ∗/
sysm88k( GET_MA_TBL, &count, sizeof(count) );
size = sizeof(int);
size += count ∗ sizeof(struct mrt);
buffer = (struct matr_x ∗)malloc(size);
sysm88k( 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 SM88KBOOT
When cmd is SM88KBOOT, 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 sysm88k.
#include sys/sysm88k.h
struct sm88kboot buffer; /∗ buffer ∗/
sysm88k(SM88KBOOT, &buffer);
Command SM88KAUTO
When cmd is SM88KAUTO, 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. The value is undefined if the system was booted in “magic mode.” This command is available only to the super-user.
Command SM88KTODEBUG
When cmd is SM88KTODEBUG, no arguments are expected. This function allows entry into the kernel debugger from any port. This differs from the current use of @@P to enter the kernel debugger from the console. If no debugger exists, this function sets errno to EINVAL. This command is available only to the super-user.
Command SM88KSWPI
NOTE: This cmd is available only 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 SM88KSWPI, 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 sysm88k. First, the swap buffer is primed with appropriate entries for the structure members. Then sysm88k is invoked.
#include sys/sysm88k.h
#include sys/swap.h
struct swapint swapbuf;/∗swap into buffer ptr∗/
sysm88k(SM88KSWPI, &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 SM88KTRAPLOCORE
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 SM88KTRAPLOCORE, 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 four values, defined in sys/sysm88k.h:
SM88KTLC_DISABLE
Disable low core trapping. Read accesses to low core are allowed from user processes.
SM88KTLC_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.
SM88KTLC_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.
SM88KTLC_STATUS
Return current state of low core trapping. The state of low core trapping is unchanged.
If this command succeeds, it returns one of SM88KTLC_DISABLE, SM88KTLC_SIGNAL, SM88KTLC_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 SM88KTLC_STATUS).
EINVAL An argument is invalid.
Command SM88KBUGROMENVIRON
When cmd is SM88KBUGROMENVIRON, the system performs a BUG-ROM system call trap. This BUG-ROM trap allows superusers to read or write the BUG-ROM’s NVRAM environmental settings. The parameters arg1, arg2, and arg3 are expected to contain parameters which are passed to the BUG-ROM. Specifically, arg1 contains a pointer to a buffer that contains or will receive the environmental data. The parameter arg2 contains the size of this buffer (in bytes). The last parameter, arg3, must contain the specific BUG-ROM command to read or write the NVRAM. UNIX does not interpret arg3 or any data found in the buffer pointed to by arg1. This data is passed directly to the BUG. The return codes from the BUG are returned from this system call. It is recommended that this system call only be performed when UNIX is running in single-user mode.
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 the size of the selected dump (see DUMPSIZE below) or not all of the crash dump will be saved. If the device is a disk-drive partition, 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 partition if possible to facilitate some swapping.
Command DUMPSIZE
The cmd DUMPSIZE enables compressed crashdumps. The first argument is one of 3 values: DUMP_KMIN, DUMP_KMAX, or DUMP_ALLPHYS. DUMP_KMIN dumps all kernel virtual memory except for segmap, DUMP_KMAX dumps all kernel virtual memory and DUMP_ALLPHYS dumps all main memory. /etc/master.d/dump defines the actual parts of kernel memory dumped for DUMP_KMIN and DUMP_KMAX as well as determines the default dump size.
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 necessarily finish instructions in the same order as they begin them. This command forces the processor to synchronize before performing any load or store instruction; thus the processor will access all hardware addresses in the exact order specified by the program. Memory serialization is deactivated via the sysm88k DESERIALIZE_MEMORY_ACCESS command.
Note that the effect of this command differs from setting the "serialize bit" in an 88000 series processor’s status word. Setting the serialize bit synchronizes the processor before every instruction. This command only synchronizes the processor before load and store instructions.
Only the memory accesses of the current process are serialized; not the memory accesses for all processes. If the process makes a system call while serialized, it will be de-serialized upon entry to the kernel, but re-serialized upon re-entering user space. Any interrupts taken while this process is executing are also executed in concurrent memory access mode. A call to fork while serialized, will result in a unserialized child process. The general practice of making system calls while serialized is not recommended.
This command has no effect on systems that do not support memory (only) serialization. Because of its impact on a process’ performance, this command should be used sparingly. For the same reason, the number of instructions that are performed in serialized mode should also be made as small as possible.
This command returns the previous memory serialization setting, when logically anded with the constant PS_SRM. A 0 in the PS_SRM bit position indicates that memory access was not serialized. A 1 indicates that it was already serialized.
Command DESERIALIZE_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 necessarily finish instructions in the same order as they begin them. This function makes the processor to stop synchronizing before each load or store instruction, if it has been put into memory serialization mode by calling sysm88k with the SERIALIZE_MEMORY_ACCESS command.
If memory access was not serialized, this function has no effect.
This command returns the previous memory serialization setting, when logically anded with the constant PS_SRM. A 0 in the PS_SRM bit position indicates that memory access was not serialized. A 1 indicates that it was serialized.
Command CONSPROTOCOLINFO
When cmd is CONSPROTOCOLINFO console protocol information will be retrieved. Three arguments are expected: the first must be a dev_t that specifies the device the command is for, second is the address of an int where the command will place the result, and the third is the protocol number to be queried. For each bit n set in the result, port n is capable of running the protocol.
Command SET_CONSOLE_LEVEL
When cmd is SET_CONSOLE_LEVEL the treatment of kernel printfs (any call to printf from within the kernel, including all calls to cmn_err()) will be changed depending on the first argument. The following table describes the behavior of kernel printfs upon completion of this command.
| Argument 1 | Description |
| PRINT_TO_CONSOLE_OR_SYSLOG | If syslogd is running, kernel printfs are only sent to the logger. If syslogd is not running kernel printfs are only sent to the console. |
| PRINT_TO_CONSOLE_ALWAYS | If syslogd is running then the messages appear both on the console and in the syslogd logs. If syslogd is not running the messages appear only on the console. |
| PRINT_TO_CONSOLE_NEVER | If syslogd is running then kernel printfs appear only in the syslogd logs. If syslogd is not running, kernel printfs appear nowhere. |
In the previous table, "syslogd is running" is true if /usr/sbin/syslogd is executing and kernel messages are being logged.
PANIC messages are not affected by this command. PANIC messages are always displayed on the system console.
This command is only available to the super-user. If argument 1 is invalid, -1 is returned and errno is set to EINVAL.
DIAGNOSTICS
On success, sysm88k returns a value that depends on cmd as follows:
SM88KSYM A value of zero.
SM88KCONF A value of zero.
SM88KBOOT A value of zero.
CRASHDUMP A value of zero.
SET_CONSOLE_LEVEL
A value of zero.
SM88KAUTO 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.
SM88KTRAPLOCORE
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.
SEE ALSO
cunix(1M), swap(1M), syslogd(1M), sync(2), a.out(4), syslog.conf(4)