MenuetOS System Call Documentation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------------------------- WARNING: This file is unreliable and contains many errors. You have been warned! -------------------------------------------------- 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-pre7 (7 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 7Dec2001: Updated to 0.62-pre7 and released. 29Nov2001: Merged with new terminology based on libmsys. 27Nov2001: updated VT's docs to 0.62-pre5 and fleshed it out.