Systemcalls

Systemcalls

To call the kernel and execute a function, one must load the function number into the AH register and call interupt 0x21.

For example, the system call to exit the programm could look like this (Intel Assembler Style):

mov bx, 0x0000 ; return code 0 indicates no error

mov ax, 0x0000 ; function 0 is exit

int 0x21 ; call the kernel

Register	Purpose
AH	function number
(E)BX, (E)CX, (E)DX	parameters
(E)SI, (E)DI, (E)BP	parameters
(E)AX	return value
FLAGS	carry flag indicates error on some legacy functions

function number	name	parameters	returns	description	macro
0x00	exit	BX = Exitcode	nothing	terminates process and starts command.bin (back to shell)	EXIT [retcode]
0x01	print	ES:EDX = pointer to string BL = color	nothing	Prints the \0 terminated string from ES:EDX with color BL at the current cursor positon	PRINT [string] PRINT [string], [color]
0x02	strcmp	ES:ESI = pointer to first string DS:EDI = pointer to second string	AL = boolean	Compares the two \0 terminated strings If they are equal AL = 0	STRCMP [str1], [str2]
0x03	shortToString	EDX = pointer to string buffer CX = short to convert	nothing	Converts the integer from cx into a string and saves it in the buffer. The string has leading zeros if the integer has less than 5 digits.	STOSTR [buffer], [short]
0x04	readline	ES:EDX = pointer to string buffer CX = length of buffer	CX = number of chars read	Reads a string from the keyboard and saves it in the buffer.	READLINE [buffer], [maxlength]
0x05	loadfile	EDX = pointer to filename string BP:EBX = pointer to destination buffer	ECX = filesize AX = errorcode	Loads the file with the filename in DX into the memory at address BP:EBX and saves the filesize reported from the filesystem in ECX.	LOADFILE [filename], [address] LOADFILE [filename], [address], [segment]
0x06	getTimeString	none	EDX = pointer to string with time	Returns a pointer to string with the current time in EDX.	TIME
0x07	getDateString	none	EDX = pointer to string with time	Returns a pointer to string with the current date in EDX.	DATE
0x08	getVersion	none	AH = Majorversion AL = Minorversion	Returns the version in AX.	VERSION
0x09	stringToInt	DS:EDX = pointer to string	ECX = converted integer AX = errorcode carryflag indicates error	Tries to convert the string in DS:EDX into an integer in ECX. If an error occours, the errorcode is in AX, ECX = 0 and the carry flag is set.	STRTOL [string]
0x0A	deletefile	none	nothing	Function currently not implemented.
0x0B	random	none	ECX = random integer	Calculates a pseudorandom number and returns it in ECX.	RANDOM
0x0B	getCPUInfo	none	AX = string pointer to CPU vendor BX = string pointer to CPU model	Returns stringpointer to CPU vendor in AX. Returns stringpointer to CPU model in BX.
0x0D	hexstrToByte	EDX = pointer to hexstring	CL = converted byte	Assumes that EDX points to a string and interprets the first two characters as hexadecimal digits. These two digits get converted into a byte. Warning: No error detection!	HEXTOSTR [str]
0x0E	setCursorPosition	DH = rownumber DL = columnnumber	nothing	Moves the cursor to the position DH:DL. If DH:DL are bigger than the screen would allow, they get clamped to the biggest possible value.	MOVECUR [x], [y]
0x0F	getCursorPosition	none	DH = rownumber DL = columnnumber	Returns the current cursor position.	READCUR
0x10	printChar	DH = character to print DL = color to print in	none	Prints a single character in DH with the color from DL to the current cursor position.	PRINTCHAR [char] PRINTCHAR [char], [color]
0x11	loadroot	none	CX = number of files in root dir	Loads the root directory from the current drive into the directory cache.
0x12	saveroot	none	nothing	Currently not implemented
0x13	findfile	DX = pointer to filename string	AX = index of file in directory	Returns the index of the file in the directory in AX. If the file was not found, AX = -1.	FINDFILE [filename]
0x14	writefile	none	nothing	Currently not implemented
0x15	byteToHexstr	CL = integer byte	DX = pointer to 3 character string with hexdecimals	Converts the byte in CL into a hexstring that is \0 terminated.	ITOHEX [byte]
0x16	bcdToInt	AL = byte in BCD	AX = integer	Converts the binary coded decimal in AL into an integer in AX.	BCDTOINT [byte]
0x17	execute	DX = pointer to filename string ES:DI = pointer to argument string	nothing	Tries to launch the programm with the given filename and passes the given argument string to it.	EXECUTE [filename], [arguments]
0x18	initSleep	none	nothing	Initalizes the programmable interupt timer. Gets called by sysinit.sys to allow for sleep() to work.
0x19	sleep	EBX = time to sleep (in blocks of 10ms)	nothing	Sleeps for the given amount of time. To sleep for one second, one would call sleep(100)	SLEEP [time]
0x1A	loadDirectory	DS:EDX = pointer to directory name	Carryflag indicates error	Tries to change the current working directory to the directory specified by the name. The directory to change to has to be in the current working directory.	LOADDIRECTORY [str]
0x1C	floatToString	DS:EDX = pointer to string buffer ECX = precision (number of decimals) EBX = Single Precision Float	nothing	Converts the float from ebx into a string and saves it in the buffer. ECX will get clamped to between 0 and 7. If the macro is used with no precision argument, then precision is set to 3.	FTOSTR [str], [float] FTOSTR [str], [float], [precision]
0x1D	stringToFloat	DS:EDX = pointer to string buffer	EAX = Single Precision Float Carryflag indicates an error	Tries to convert the string pointed to by DS:EDX into a single precision float. On success, the float is in the EAX register. (requires x87)	STRTOF [str], [float]
0xAA	intToString	EDX = pointer to string buffer ECX = integer to convert	nothing	Converts the integer from ecx into a string and saves it in the buffer.	ITOSTR [str], [integer 16 Bit] LTOSTR [str], [integer 32 Bit]
0xAC	readChar	none	AL = ASCII Code 0 AH = Keyboard scancode	Uses IO ports to read a character from the Intel 8042 keyboard controller without interrupts.	none
0xE1	com1_sendByte	AL = Byte to send	none	Sends byte in al on the COM1 port.	SERIAL_WRITE
0xE2	com1_sendMessage	DS:SI = String to send	none	Sends string in DS:SI on COM1 port.	none
0xF0	initMemory (1)	none	none	Initialises the upper memory to allow for alloc/free calls.	none
0xF1	allocPage (1)	none	GS:BP = far pointer to the allocated page. The page is 512 Bytes in size.	Finds the first free page in the high memory area. If no page is found the carry flag is set.	ALLOC
0xF2	freePage (1)	BP = Page to free	none	Frees the page with the address (GS:)BP, the method only needs the base pointer here.	FREE [addr]
0xFF	debug1	EDX = any value	nothing	Prints the value in EDX interpreted as integer to the current cursor position.	DEBUG1 [value]

(1) Only available when compiled with enabled A20 gate. (H switch in build.sh)

(2) Only available when compiled with debug features. (D switch in build.sh)

Macros

The files in the include/ directory can be used in any program. I do not recommend including include/fat12/ or include/floppy16/ directly, as they mostly provide low level file access which is mapped into the int 0x21 API anyway.

Very useful includes are defines.asm and functions.asm.

defines.asm

Defines some useful values, such as colours, addresses, TRUE/FALSE and some macros to make assembler easier.

functions.asm

Contains macros, which can be used to access the int 0x21 API in a more readable away. Instead of having random function numbers in the AH register, its clearly visible what happens with the help of those macros.