MenuetOS System Call Documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

0. Index

        1. Version
        2. Using a System Call
        3. The System Calls (quick reference)
        4. System Call details

                Drawing
                Background
                Process Management
                Event Management
                Time
                File I/O
                Drives
                Language
                Mouse
                Sound
                CD
                Keyboard Setup
                IRQs and Devices

        5. Drives
        6. Languages
        7. Keyboard Layouts
        8. Error Codes
        9. Packed Values
        10. Work Areas
        11. How the kernel handles System Calls
        12. Declaration
        13. Redistribution
        14. Maintainer
        15. Credits
        16. ChangeLog


1. Version

 This is version 0.02 of this file. It is current as of kernel version
 0.62-pre6 (3 December 2001).
 Later versions of this file may be available from menuetos.org or
   www.geocities.com/kirkalx/menuet


2. Using a System Call

 MenuetOS application system calls are invoked by the "int 0x40"
 instruction. The particular system call required is selected by numbers
 placed in registers. All system calls have at least a function number
 (placed in eax), some have an additional command number (placed in ebx)
 and a few have a request number (placed in ecx).

 Other parameters are stored in registers also. Some don't return any
 value so the registers are preserved by the call. Others return a single
 value in eax. Others return additional values in other registers.
 Using an invalid function number returns -1 in eax. The kernel
 currently makes a few assumptions for speed so use of non-existent
 command or request numbers should be considered to produce undefined
 results (so don't do it!).


3. The System Calls (quick reference)

        NYI = not yet implemented
        DNU = do not use
        OBS = obsolete

        Function Command Request Name                   Comments
        No.      No.     No.
        --------------------------------------------------------
        0                        DefineWindow
        1                        SetPixel
        2                        GetKey
        3                        GetClock
        4                        WriteText
        5                        DelayHs
        6                        OpenRamdiskFile
        7                        PutImage
        8                        DefineButton
        9                        GetProcessInfo
        10                       WaitForEvent
        11                       CheckForEvent
        12
                1                BeginDraw
                2                EndDraw
        13                       DrawRect
        14                       GetScreenSize
        15
                1                SetBackgroundSize
                2                WriteBackgroundData
                3                DrawBackground
                4                SetBackgroundType
                5                UnknownBackgroundFunction???
        16                       FlushFloppyCache                NYI
        17                       GetButtonID
        18
                1                Shutdown
                2                KillApp
                3                WindowActivate                   UD??-VT?
                4                GetIdle
                5                GetTsc

        19                       StartApp
        20
                1                ResetMidi
                2                OutputMidi
        21
                1                SetMidiBase
                2
                        1        SetKeymap
                        2        SetShiftKeymap
                        9        SetKeyLayout
                3                SetCdBase
                4                SetSb16Base
                5                SetSysLanguage
                6                SetWssBase
                7                SetHdBase
                8                SetFat32Partition
        22                       DefineNewWindow
        23                       TimeoutWaitForEvent
        24
                1                PlayCdTrack
                2                GetCdPlaylist
                3                StopCd
        25        1              SetSb16MixerIMainVol
                2                SetSb16MixerICdVol
        26
                1                GetMidiBase
                2
                        1        GetKeymap
                        2        GetShiftKeymap
                        9        GetKeyLayout
                3                GetCdBase
                4                GetSb16Base
                5                GetSysLanguage
                6                GetWssBase
                7                GetHdBase
                8                GetFat32Partition
        27
                1                WssMainVol
                2                WssCdVol
        28
                1                SetSb16MixerIIMainVol
                2                SetSb16MixerIICdVol
        29                       GetDate
        30                       ReadHd
        31                       StartHdApp
        32                       DelRamdiskFile
        33                       WriteRamdiskFile
        34                       ReadFloppyDrive
        35                       GetPixel
        36                       ReadString                        NYI
        37
                0                GetMousePosition_ScreenRelative
                1                GetMousePosition_WindowRelative
                2                GetMouseStatus
        38                       DrawLine
        39
                1                GetBackgroundSize
                2                ReadBackgroundData
                4                GetBackgroundType
        40                       WantEvents
        41                       GetIrqOwner
        42                       ReadIrqData
        43                       SendDeviceData
        44                       ProgramIrqs
        45
                0                ReserveIrq
                1                FreeIrq
        46
                0                ReservePortArea
                1                FreePortArea
        47                       WriteNum
        48
                0                SetRedrawType
                1                SetButtonType
        49                       AppInts
        50
                0                SetRandomShapedWindow
                1                SetRandomShapedWindowScale
        0xc0000000               LoadSb16Music
        0xc0000001               PlaySb16Music
        0xd0000000               SetFat32Data
        0xd0000001               ReadFat32File
        0xd0000002               WriteFat32File
        -1                       EndApp


4. System Call details

Drawing
~~~~~~~

        - Read a string from the screen ** NYI **
        ReadString (36)
                ebx:  buffer
                ecx:  text colour
                edx:  background colour
                esi:  number of letters
                edi:  packed x, y
                returns unspecified value??

        - Define a window, standard and new styles (equivalent).
        DefineWindow (0)
        DefineNewWindow (22)
                ebx:  packed x and width
                ecx:  packed y and height
                edx:  body colour
                esi:  grab-bar colour (or with 0x80000000 for glide).
                edi:  frame colour

        - Change the shape of a window.
        SetRandomShapedWindow (50, 0)
                ecx:  pointer to data

        - Change the scale of a randomly-shaped window (default 2^0 = 1).
        SetRandomShapedWindowScale (50, 1)
                ecx:  power of scale, i.e. scale = 2^ecx 

        - Define a button.
        DefineButton (8)
                ebx:  packed x and width
                ecx:  packed y and height
                edx:  id
                esi:  colour

        - Change buttons to given type.
        SetButtonType (48, 1)
                ecx:  0 for flat, 1 for 3D.

        - Choose redraw type??.
        SetRedrawType (48, 0)
                ecx:  0 for all

        
        - Write a message to the screen.
        WriteText (4)
                ebx:  packed x, y
                ecx:  colour
                edx:  pointer to text
                esi:  text length

        - Write a number to the screen.
        WriteNum (47)
                ebx:  
                        bl = 0 (number) or 1 (pointer)
                        bh = 0 (dec), 1 (hex) or 2 (bin)
                        bits 16-21 = number of digits (0-32)
                        bits 22-31 reserved.
                ecx:  value
                edx:  packed x, y
                esi:  colour

        - Place an image on the screen.
        PutImage (7)
                ebx:  pointer to image
                ecx:  packed width, height
                edx:  packed x, y
                returns error code (1 overlapped)


        - Obtain the extent of the screen.
        GetScreenSize (14)
                returns packed width, height.

        - Changes colour of a particular pixel.
        SetPixel (1)
                ebx:  x
                ecx:  y
                edx:  colour with bit 24 set (negative) or unset (normal)

        - Returns colour of a particular pixel.
        GetPixel (35)
                ebx:  packed x, y
                returns colour

        - Call prior to drawing.
        BeginDraw (12, 1)

        - Call at end of draw.
        EndDraw (12, 2)

        - Draw a line from (x1, y1) to (x2, y2) in ?? colour.
        DrawLine (38)
                ebx:  packed x1, y1
                ecx:  packed x2, y2

        - Draw a rectangle.
        DrawRect (13)
                ebx:  packed x, width
                ecx:  packed y, height
                edx:  colour


Background
~~~~~~~~~~

        - Read data from the desktop background image.
        ReadBackgroundData (39, 2)
                ecx:  position in memory in bytes - max (0x100000-16)
                returns colour

        - Change data in the background image.
        WriteBackgroundData (15, 2)
             ecx:  position in memory in bytes - max (0x100000-16)
             edx:  colour

        - Redraw the desktop background.
        DrawBackground (15, 3)

        - Obtain the size of the background image.
        GetBackgroundSize (39, 1)
                returns packed width, height

        - Set the size of the background image.
        SetBackgroundSize (15, 1)
                ecx:  width
                edx:  height

        - Obtain the method by which the background image is drawn.
        GetBackgroundType (39, 4)
                returns type 1 (tile) or 2 (stretch)

        - Choose the method by which the background image is drawn.
        SetBackgroundType (15, 4)
                ecx:  1 (tile) or 2 (stretch)

        - Unknown Background function??.
        UnknownBackgroundFunction(15, 5)


Process Management
~~~~~~~~~~~~~~~~~~

        - ?? activate window
        WindowActivate (18, 3) ??
                returns 0.?

        - Start program from ramdisk image.
        StartApp (19)
                ebx:  pointer to 8.3 filename
                ecx:  pointer to asciiz command line - max 256 bytes
                returns error status

        - Start program from hard-drive.
        StartHdApp (31)
                ebx:  pointer to file??
                ecx:  file length
                edx:  pointer to work area

        - Obtain information about a specified process.
        ProcessInfo (9)
                ebx:  pointer to 1024 byte table
                        Table format:
                        0        dword        cpu usage
                        10       char         name (12 characters)
                        22       dword        start in memory
                        26       dword        used memory                
                ecx:  pid
                returns number of processes in system
                
        - Returns the CPU Idle time.
        GetIdle (18, 4)
                returns idle clock cycles / second.

        - Kill a specified process.
        KillApp (18, 2)
                ecx:  pid

        - Initiate system shutdown.
        Shutdown (18, 1)

        - Suspend current process for a given delay.
        DelayHs (5)
                ebx:  delay in hundredths of a second.

        - Close current process.
        EndApp (-1)

        - ???
        AppInts (49)??

        - Return the CPU task-switch count??.
        GetTsc (18, 5)
                returns time stamp counter / second - cpu speed.


Event Management
~~~~~~~~~~~~~~~~

        - Specify mask of event types the process wishes to be alerted about.
        WantEvents (40)
                ebx:  wanted event mask

                Bits are:

                0*                request for window to be redrawn
                1*                key pressed
                2*                button pressed
                3                 ??
                4                 background redrawn
                5                 mouse status changed
                16-31             irq status changed

                   Values marked * are set by default.

        - Suspend process until an event arrives. Returns type of event (not 0).
        WaitForEvent (10)
                returns event type.

        - Suspend process until an event arrives or a given delay expires.
        TimeoutWaitForEvent (23)
                ebx:  timeout in hundredths of a success
                returns type of event (0 for timeout).

        - See if any events are pending. Returns event type (0 if none).
        CheckForEvent (11)
                returns event type.

        - Obtain the value?? of a pressed key. Use when a key event arrives.
        GetKey (2)
                returns success/failure (al 0 or 1) and key (ah).

        - Obtain the id of a pressed button. Use when a button event arrives.
        GetButton (17)
                returns success/failure (al 0 or 1) and id (ah).


Time
~~~~

        - Obtain the current date.
        GetDate (29)
                returns date in form 0x00YYDDMM. Year, date and month are
                stored in BCD form.

                e.g. 12 July 2001 returns 0x00011207

        - Read system clock.
        GetClock (3)
                returns time in form 0x00SSMMHH. Seconds, minutes and hour
                stored in BCD form.

                e.g. 11:27:12pm returns 0x00122711


File I/O
~~~~~~~~

        - Set the Fat32 data.
        SetFat32Data (0xd0000000)??

        - Write a file to the Fat32 partition.
        WriteFat32File (0xd0000002)??

        OpenRamdiskFile (6)
                ebx:  pointer to filename -> 11 capital letters
                ecx:  set 0x00000000 - reserved
                edx:  set 0xffffffff - reserved
                esi:  read to mem position
                returns size of file or -1 if file not found

        - Read a file to the Fat32 partition.
        ReadFat32File (0xd0000001)??

        - Remove a file from the ramdisk image.
        DelRamdiskFile (32)
                ebx:  pointer to 8.3 filename

        - Save a file to the ramdisk image. Blocks are 512 bytes.
        WriteRamdiskFile (33)
                ebx:  pointer to 8.3 file name
                ecx:  pointer to data
                edx:  count to write in bytes
                esi:  0 create new , ( 1 append - not implemented yet )

        - Flush the floppy cache??.
        FlushFloppyCache (16)

        - Read a file from the hard-drive. Blocks are 512 bytes.
        ReadHd (30)
                ebx:  pointer to file
                ecx:  file length
                edx:  start block ,  1 block = 512 bytes
                esi:  no of blocks to read
                edi:  pointer to work area
                returns error code in eax and size of file in ebx 

        - Read a file from the floppy drive.
        ReadFloppyDrive (34)
                ebx:  pointer to file
                ecx:  file length
                edx:  start block ,  1 block = 512 bytes
                esi:  no of blocks to read
                edi:  pointer to work area
                returns error code in eax and size of file in ebx 


Drives
~~~~~~

        - Returns the drive number of the CD drive.
        GetCdBase (26, 3)
                returns number of CD device.

        - Set the drive number of the CD drive.
        SetCdBase (21, 3)
                ecx:  number of CD device.

        - Returns the drive number of the hard-drive.
        GetHdBase (26, 7)
                returns number of hard disk device.

        - Set the drive number of the hard-drive.
        SetHdBase (21, 7)
                ecx:  number of hard disk device.

        - Returns the number of the Fat32 partition on the hard-drive.
        GetFat32Partition (26, 8)
                returns number of partition on hard-drive

        - Set the number of the Fat32 partition on the hard-drive.
        SetFat32Partition (21, 8)
                ecx:  number of partition on hard-drive


Language
~~~~~~~~

        - Obtain the current system language.
        GetSysLanguage (26, 5)
                returns language id.

        - Change the current system language (default 1 i.e. English).
        SetSysLanguage (21, 5)
                ebx:  language id.


Mouse
~~~~~

        - Get mouse pointer position relative to the screen.
        GetMousePosition_ScreenRelative (37, 0)
                returns packed x, y.

        - Get mouse pointer position relative to the window.
        GetMousePosition_WinRelative (37, 1)
                returns packed x, y.

        - Obtain the current status (buttons pressed) of the mouse.
        GetMouseStatus (37, 2)
                returns bitwise OR of values ??.


Sound
~~~~~

        - Get the I/O address of the Roland MPU-401 midi chip.
        GetMidiBase (26, 1)
                returns base io address for Roland MPU-401 midi device.

        - Set the I/O address of the Roland MPU-401 midi chip.
        SetMidiBase (21, 1)
                ecx:  base io address for Roland MPU-401 midi device.

        - Reset the Roland MPU-401 midi chip.
        ResetMidi (20, 1)

        - Output data to the Roland MPU-401 midi chip.
        OutputMidi (20, 2)
                cl:  data

        - Get the I/O address of the SoundBlaster-16 chip.
        GetSb16Base (26, 4)
                returns base io address for SoundBlaster device.

        - Set the I/O address of the SoundBlaster-16 chip.
        SetSb16Base (21, 4)
                ecx:  base io address for SoundBlaster device.

        - Get the I/O address of the Windows Sound System chip.
        GetWssBase (26, 6)
                returns base io address for Windows Sound System device.

        - Set the I/O address of the Windows Sound System chip.
        SetWssBase (21, 6)
                ecx:  base io address for Windows Sound System device.

        - Set the main and CD volumes for the SoundBlaster-16 Mixer I.
        SetSb16MixerIMainVol (25, 1)
        SetSb16MixerICdVol (25, 2)
                cl: volume (left) * 16 + (right)

        - Set the main and CD volumes for the SoundBlaster-16 Mixer II.
        SetSb16MixerIIMainVol (28, 1)
        SetSb16MixerIICdVol (28, 2)
                cl: volume from 0 - 255

        - Set the main and CD volumes for the Windows Sound System chip.
        SetWssMainVol (27, 1)
        SetWssCdVol (27, 2)
                cl: volume from 0 - 255

        - Load music for the SoundBlaster-16 from a 64k buffer.
        LoadSb16Music (0xc0000000)
                ebx:  pointer to buffer

        - Play music previously loaded into the SoundBlaster-16.
        PlaySb16Music (0xc0000001)


CD
~~

        - Obtain list of songs on a CD???.
        GetCdPlaylist (24, 2)
                ecx:  size??
                edx:  pointer to buffer
                returns error code

        - Stop CD playing.
        StopCd (24, 3)
                returns error code

        - Play CD track from given start time.
        PlayCdTrack (24, 1)
                ecx:  0x00TTSSMM, track, seconds, minutes in bcd.
                returns error code


Keyboard Setup
~~~~~~~~~~~~~~

        - Obtain the current keyboard layout setting.
        GetKeyLayout (26, 2, 9)
                returns keyboard layout number.

        - Change the current keyboard layout setting.
        SetKeyLayout (21, 2, 9)
                ecx:  keyboard layout number.

        - Returns a pointer to the current base keymap.
        GetKeymap (26, 2, 1)
                returns pointer to keymap

        - Change the base keymap.
        SetKeymap (21, 2, 1)
                ecx:  pointer to keymap

        - Returns a pointer to the shifted keymap.
        GetShiftKeymap (26, 2, 2)
                returns pointer to keymap

        - Change the shifted keymap.
        SetShiftKeymap (21, 2, 2)
                ecx:  pointer to keymap


IRQs and Devices
~~~~~~~~~~~~~~~~

        - Free port area
        FreePortArea (46, 1)
                ecx:  port area start
                edx:  port area end
                returns error code

        - Reserve a port area
        ReservePortArea (46, 0)
                ecx:  first port
                edx:  last port
                returns error code

        - Free a reserved IRQ.
        FreeIrq (45, 1)
                ecx:  irq number
                returns error code

        - Reserve an IRQ.
        ReserveIrq (45, 0)
                returns ??

        - Read data from a given IRQ.
        ReadIrqData (42)
                ebx:  irq number
                returns number of bytes in buffer (eax) and data (bl) and ecx??.

        - Query owner of an IRQ.
        GetIrqOwner (41)
                returns owner??.

        - Program IRQs.
        ProgramIrqs (44)
                ebx:  pointer to table
                ecx  irq number

        - Write to a device.
        SendDeviceData (43)
                bx:  port
                cl:  data
                returns error code

5. Drives

 Drive numbers are:

        1        Primary Master
        2        Primary Slave
        3        Secondary Master
        4        Secondary Slave

6. Languages

 Current language ids are:

        1        English
        2        Finnish
        3        German
        4        Russian

7. Keyboard Layouts

 Current values are:

        1        English
        2        Finnish
        3        German
        4        Russian

8. Error Codes

 Current error codes are:

        0        No error
        1        No hard-disk drive number and/or partition defined
        2        Filesystem unsupported
        3        Unknown filesystem
        4        Bad Partition
        5        File not found


9. Packed Values

 A packed value is a 32 bit value formed from two values between
 0 and 2^16 - 1, by shifting the first left 16 bits and OR'ing it with
 the second value. For example, packed 200 and 47000 is 0xc8b798.


10. Work Areas

 Work areas are used by some functions. A work area should be a
 buffer of at least 20000 bytes.


11. How the kernel handles System Calls

 System calls execute the int 0x40, which has the interrupt handler i40.
 i40 pushes all the standard registers on the stack, then the ds register.
 The segment registers are then pointed to the os_data segment. The
 register values are then swapped around so the function number is in edi,
 and others in eax, ebx, ecx ... Once this is completed, the value to
 eventually be popped back into eax can be accessed as [esp+26].

 Control now passes to the serveapp function. This has the responsibility
 of executing the correct code for each function number (see below for how
 serveapp is implemented). Functions which must return values access the
 stack by [esp+26] for eax, etc. Obviously if stack manipulation is used
 then the offset from esp has to be adjusted.

 Once (and if) the serveapp function returns, control passed back to i40.
 The segment registers are now set back to point to the program data
 segment. Other registers are also restored then i40 executes an iret to
 return control back to the program.

 Currently serveapp does a (slow) linear search for the correct
 code to execute for a given function number so any function number can be
 used from 0 to 0xffffffff (-1) without any problems. VT is currently
 working on replacing the linear search with a fast table lookup. This has
 the effect of mandating a set of closely spaced sequences of function
 numbers. Happily the current function numbers have this property: there are
 four sequences, from 0 to 50, 0xc0000000 to 0xc0000001, 0xd0000000 to
 0xd0000002 and one solitary value 0xffffffff (-1).

 The new table look up handler (as it would hypothetically appear in C) would
 be something like:


        int serveapp (unsigned int fnumber)
        {
                if (fnumber == 0xffffffff)
                        return do_exit();
                else if (fnumber <= 50)
                        return system_call_handler_table[fnumber]();
                else {
                        switch (fnumber)
                        {
                                case 0xc0000000:
                                case 0xc0000001:
                                        return sb16music_handler(fnumber);
                                        break;
                                case 0xd0000000:
                                case 0xd0000001:
                                case 0xd0000002:
                                        return fat32file_handler(fnumber);
                                        break;
                                default:
                                        return bad_system_call();
                        }
                }
        }


12. Declaration

 This file was last modified by the maintainer.


13. Redistribution

 Redistribution of this file in any form on any media is permitted,
 provided that if you modify it you declare that you were the last person
 to modify it somewhere in the file.


14. Maintainer

 The current maintainer of this file is Kirk Alexander (kirkalx@yahoo.co.nz).
 Please direct any suggestions, comments and flames to him.
 Later versions of this file may be available from
   www.geocities.com/kirkalx/menuet

 Maintenance of this file works by a timeout-broadcast method. If it seems
 to be out of date, contact the maintainer. If the maintainer does not
 answer broadcast to check if someone is about to become the new
 maintainer. If nobody responds you become the new maintainer and broadcast
 that fact. Simple!


15. Credits

 Written by Kirk Alexander (kirkalx@yahoo.co.nz).
 Based on original documentation by VT.


16. ChangeLog
 
 3Dec2001:  Updated to 0.62-pre6.
 29Nov2001: Merged with new terminology based on libmsys.
 27Nov2001: updated VT's docs to 0.62-pre5 and fleshed it out.

