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.01 of this file. It is current as of kernel version
 0.62-pre5 (29 November 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 a
 function number placed in the eax register. Some system calls
 require a sub-function number and even a subsub-function number
 (place in ebx and ecx respectively). 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. Executing a non-existent system
 call returns -1 in eax. The kernel currently makes a few assumptions for
 speed so use of non-existent sub-function or subsub-function 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

	Fun.	SubFn. SubSubFn. Name			Comments
	--------------------------------------------------------
	0			DefineWindow
	1			SetPixel
	2			GetKey
	3			GetClock
	4			WriteText
	5			DelayHs
	6			OpenRamdiskFile
	7			PutImage
	8			DefineButton
	9			ProcessInfo
	10			WaitForEvent
	11			CheckForEvent
	12
		1		BeginRedraw
		2		EndRedraw
	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		CdPlayTrack
		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			SaveRamdiskFile
	34			ReadFloppyDir
	35			GetPixel
	36			ReadString			NYI
	37			ReadMouse
	38			DrawLine
	39
		1		GetBackgroundSize
		2		GetBackgroundData
		4		GetBackgroundType
	40			WantEvents
	41			GetIrqOwner
	42			GetIrqData
	43			SendDeviceData
	44			ProgramIrqs
	45
		0		ReserveIrq
		1		FreeIrq
	46
		0		ReservePortArea
		1		FreePortArea
	47			WriteNum
	48
		0		SetRedrawType
		1		SetButtonType
	49			AppInts
	50			SetRandomShapedWindow
	0xc0000000		Sb16LoadMusic
	0xc0000001		Sb16PlayMusic
	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 redrawing.
	BeginRedraw (12, 1)

	- Call at end of redraw.
	EndRedraw (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.
	GetBackgroundData (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) ??

	- 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
		   (4 bytes cpu usage & 1020 reserved).
		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.
	SaveRamdiskFile (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.
	Sb16LoadMusic (0xc0000000)
		ebx:  pointer to buffer

	- Play music previously loaded into the SoundBlaster-16.
	Sb16PlayMusic (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, 0)
		ecx:  port area start
		edx:  port area end
		returns error code

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

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

	- Reserve an IRQ.
	ReserveIrq (45, 0)

	- Read data from a given IRQ.
	GetIrqData (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 (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
 
 29Nov2001: Merged with new terminology based on libmsys.
 27Nov2001: updated VT's docs to 0.62-pre5 and fleshed it out.


