Documentation file for Ssystem(), the new kernel call

last update: 1998-10-06

I. Introduction

The Ssystem() call has been designed to make your life easier. Using this you can get some closer control on the system and the kernel itself. Via this call the kernel now supports e.g. an easy Cookie Jar management and provides a safe access to supervisor memory. It's strictly encouraged to access GEMDOS variables and system vectors via the Ssystem(), because this way is considered safe for multiuser setups.

II. Definition

C:

long Ssystem(short mode, long arg1, long arg2);

Assembler:

move.l  #arg2,-(sp)
move.l  #arg1,-(sp)
move.w  #mode,-(sp)
move.w  #$0154,-(sp)
trap    #1
lea $0c(sp),sp

III. Caveats

• a) Prior to any further Ssystem() usage, your application should first check if the kernel supports this call. If it does, the following statement:

  Ssystem(-1, 0L, 0L);

should return a zero. You can expect the function to be present if MiNT version at least 1.15 is detected.

• b) the Ssystem() does NOT depend on the SECURELEVEL.
• c) any values returned by the kernel on 'reserved' fields should be considered undocumented and no software should rely on them.

IV. Available modes

Kernel information

OSNAME identifies the operating system type. Returned longword contains a 32-bit number, which interpreted as an ASCII string gives a 4-character ID. For MiNT the returned value is 0x4d694e54 ('MiNT').

OSXNAME identifies the subtype of the operating system. If this call returns a zero, that means, that no subtype is available. Otherwise the returned value, when interpreted as an ASCII string gives a 4-character sub-ID. For FreeMiNT, being a derivative of the MiNT, the returned value is 0x46726565 ('Free').

OSVERSION identifies the exact operating system version. Returned longword contains a 32 bit version number encoded as follows:

bits    meaning
----    -------
0-7 some printable character to characterize the
        current version eg.
            0x61 ('a') if alpha release,
            0x62 ('b') if beta release.
        For `official' FreeMiNT releases you will
        always find a value of 0 here.  (Definition of
        an `official' FreeMiNT release:  Every
        release for which in bits 0-7 a value of 0
        is returned...)
8-15    patchlevel (0x55 for pl 88)
16-23   minor version number (0x0e for x.14)
24-31   major version number ($01 for 1.xx)

TOSHEADER allows to access the TOS header in order to get some information from. Current implementation allows to access the first 1024 longwords of the header. The address of the required longword, relative to the beginning of the TOS header, has to be specified as arg1. Only even values are allowed (bit 0 of the arg1 is masked out by the kernel). Always a whole longword is returned.

OS_BUILD_DATE returns a 32 bit value with the build date encoded as follows:

bits    meaning
----    -------
0-15    binary year ($07dd for 1998)
16-23   binary month ($0c for the December)
24-31   binary day of the month

OS_BUILD_TIME returns a 32 bit value with the build time encoded as follows:

bits    meaning
----    -------
0-7 binary seconds
8-15    binary minutes
16-23   binary hours
24-31   day of week (1 for monday, 2 for tuesday ... 7 for sunday)

COMPILE_TYPE returns a 32-bit value specifying the CPU type the kernel has been compiled for. Encoding:

bits    meaning
----    -------
0-15    binary CPU ID ($001e = 68030)
16-31   reserved for FPU ID (currently not implemented)

FEATURES returns a 32-bit value specifying the state of memory management features. Encoding:

bits    meaning
----    -------
0   memory protection (1 = turned on)
1   virtual memory (1 = turned on)
2-31    reserved for future usage

Cookie Jar management

GETCOOKIE fetches required information from the Cookie Jar. If 'arg1' is a value bigger than 65535 ($ffff), it is interpreted as a tag id. The cookie jar is searched for such a tag, then if the tag is found, the corresponding slot value is returned or -1 otherwise. If 'arg1' is a value between 1 and 65535, it is interpreted as a slot number, not a tag id. Then the corresponding tag id is fetched and returned or a value of -1 if the specified slot is free or does not exist at all (a slot number past the end of the Cookie Jar was specified). The first slot in the Cookie Jar is considered number 1. If 'arg1' is equal to a zero, then the Cookie Jar is searched for the NULL cookie, then the corresponding slot value is returned. The place where the value fetched from the Cookie Jar will be returned is defined by the 'arg2'. If this is a zero, the call returns its values in the GEMDOS return value (d0). If the 'arg2' is not a zero, it is interpreted as a pointer, where the slot tag or value should be written to. The return value is 0 (E_OK) then, if everything went OK, or -1 otherwise. This behaviour (where arg2 != NULL) is new in MiNT 1.14.8.

SETCOOKIE places a tag id specified by the 'arg1' with the value of the 'arg2' in the Cookie Jar. If a slot with the specified tag id already exists, it will be replaced with the new value. NULL cookie is reallocated automatically and its value is corrected. If there are no more free slots, no action is performed and ENSMEM is returned instead. SETCOOKIE requires euid root, EACCDN is returned otherwise and no action is performed either. SETCOOKIE refuses to place a cookie (a value of -1 is returned) whose tag id contains a zero-byte.

System variables management

GET_LVAL, GET_WVAL and GET_BVAL fetch and return a longword, a word or a byte respectively from the address of supervisor area specified as a 16-bit, even integer value passed as 'arg1'. Odd numbers get decreased by 1 for GET_LVAL and GET_WVAL. Addresses from $0008 up to $ffff are allowed, the call returns a zero for addresses less than $0008.

SET_LVAL, SET_WVAL and SET_BVAL places a longword, word or byte value respectively, specified by 'arg2' at address specified by 'arg1'. Since this call is designed for manipulating operating system variables located within the supervisor area (first 32k), all SET_xVAL modes are restricted for euid root and return EACCDN if called by an unprivileged process.

Kernel management

SYS_SLEVEL resets the current security level to a value specified by 'arg1'. Only values of 0, 1 and 2 are accepted, EACCDN is returned otherwise. This mode is restricted to euid root. If 'arg1' is equal to a -1, the current security level value is returned.

TSLICE allows you to set/interrogate the timeslice value. Values are exactly the same as for SLICES keyword in MINT.CNF. 'arg1' equal to -1 returns the current global timeslice value.

FORCEFASTLOAD allows to change the interpretation of the FASTLOAD bit from the program header. On Ssystem(FORCEFASTLOAD, 0, NULL) the program header bit will be used as before, this is actually equal to FASTLOAD=NO in MINT.CNF. On Ssystem(FORCEFASTLOAD, 1, NULL), the program header bit will be ignored and fastload will be forced for all programs. arg1 = -1 allows to examinate the current state of this feature. This mode is restricted to euid root.

SYNC_TIME allows to change the time between two filesystem syncs. If you use a filesystem with write back cache like MinixFS or NEWFATFS the kernel sync automatically every filesystem in regular intervals. With SYNC_TIME you can change these time. This mode is new in FreeMiNT 1.15.

Time management

GET_CLOCK_MODE called with an ARG1 of -1 inquires the kernel's notion of the hardware system clock. If the command returns zero, the hardware clock is considered to tick in UTC, if it returns a positive non-zero value it is considered to tick in local time. Every other positive value sets the current clock mode. For 0 it is reset to UTC, or to local time otherwise. Although this call will never really change the setting of the hardware clock, due to a changed interpretation the clock seems to warp; don't play around too much with it.

For further information please see the file minttime.doc.

WARNING: modes 16-18 are new in FreeMiNT 1.14.7. Mode 100 is new in FreeMiNT 1.15. If the kernel provides Tgettimeofday and Tsettimeofday you can expect them to be supported.

Other modes

RUN_LEVEL is currently not implemented but reserved for future.

TIOCMGET is reserved for the MiNT Library and shouldn't be used by application software.

V. Implementations

Ssystem(), if supported by the kernel, is used by the MiNT Library as of patchlevel 48. The call should be considered officially supported as of FreeMiNT version 1.15.