PCOS Kernel Technical Reference
versions 1.00 - 1.42
2007 by Mercury0x000D

Index

section					title
1						Version Numbering Scheme
2						KINT Function Quick Reference
3						KINT Functions in Detail
4						Instruction Opcodes (Listed by Instruction Name)
5						Instruction Opcodes (Listed by Opcode)
6						Kernel Error Codes
7						The Kernel Command Prompt
8						Command Line Switches
9						Kernel Priority Levels

Section 1: Version Numbering Scheme

	When programming or using the PCOS Kernel, it is often helpful to understand the version numbering system used. Minor bugfixes and feature additions usually result simply in the kernel's internal revision number being incremented. For more serious bugfixes or when larger features are added, commonly the hundredths place of the version is updated. As enough of these accumulate, naturally, they will roll over into the tenths place, and eventually into the whole version number, but keep in mind that the whole part of the version number is never updated unless a truly major milestone is achieved in its features, algorithims, or underlying design.

Section 2: KINT Functions Quick Reference

	Here's a list of all the kernel interrupt (KINT) functions supported by the PCOS kernel.
number		description
01		get address of system data area
02		get thread number of calling app
03		position cursor
04		return timer value
05		clear screen
06		set video mode
07		print pascal string
08		terminate thread
09		print value
0A		copy date to pascal string
0B		copy time to pascal string
0C		open file
0D		close file
0E		get word from string
0F		write pascal string to file
10		get file position
11		set file position
12		get input
13		add function to kernel list
14		remove function from kernel list
15		get address of function in kernel list
16		return register value of other thread
17		get directory contents (initiate)
18		plot point on screen (direct screen write for non-VESA modes)
19		reboot
1A		get word count of string
1B		get file data
1C		string search function
1D		execute DOS app
1E		execute PCOS app
1F		get key press
20		get cursor position
21		get directory contentents (continue)
22		rename file
23		create directory
24		create file
25		delete directory
26		delete file
27		add resource
28		delete resource
29		set login name
2A		get login name
2B		print imbedded string
2C		get string from number
2D		get file length
2E		get APM BIOS version
2F		activate / deactivate APM
30		APM power off
31		draw line - available in version 1.35 and up
32		set thread pause state - available in version 1.40 and up
33		set thread priority - available in version 1.40 and up
34		open / close CD drive door
35		tone generator

Section 3: KINT Functions in Detail

	The PCOS kernel provides the applications programmer access to a variety of its internal routines for performing various tasks, which are detailed here. To call a kint function, set the number of the desired function in AX, then execute interrupt 0x019. If 'input' is not specified for a particular function, no data is required upon entry into the function for it to execute. Likewise, if 'output' is not specified, no data is returned upon exit from the function. Not all functions are available in all kernel versions, so the version in which a particular routine was added is noted also. Unless otherwise specified, the routine can be assumed to be available in every kernel version.

01	get address of system data area
	output:	bx = handle of system data area block
		cx = offset of system data area block

02	get thread number of calling app
	input:	none
	output:	bx = thread number of the thread which called the interrupt

03	position cursor
	input:	bx = new vertical position of cursor (0 = leave at current position)
		cx = new horizontal position of cursor (0 = leave at current position)

04	return timer value
	input:	none
	output:	bx = decimal part of system timer
		cx = fractional part of system timer

05	clear screen
	input:	none

06	set video mode
	input:	bx = video mode to set
	output:	none

07	print pascal string
	input:	bx = vertical position to print (0 = leave at current position)
		cx = horizontal position to print (0 = leave at current position)
		si = offset of string data to print (cs:si)

08	terminate thread
	input:	bx = thread number of the thread to be terminated
		(note: if bx = 0 the thread which called the interrupt will be terminated)
	output:	none

09	print value
	input:	bx = vertical position to print (0 = leave at current position)
		cx = horizontal position to print (0 = leave at current position)	
		si = value to print
	output:	none

0A	copy date to pascal string
	input:	si = offset of 10 byte string to hold date (cs:si)
	output:	none

0B	copy time to pascal string
	input:	si = offset of 8 byte string to hold time (cs:si)
	output:	none

0C	open file
	input:	si = offset of string containing filespec (cs:si)
	output:	bx = file number file was opened as

0D	close file
	input:	bx = file number of file to close
	output:	none

0E	get word from string
	input:	si = source string
		di = string to hold word specified
		bx = word to return
		cx = ASCII code of separation character
	output:	di = string containing the word specified by ax

0F	write pascal string to file
	input:	si = source string
		bx = number of the file to write string to
		cx = position in file at which to write string (0 = current position)
	output:	di = string containing the word specified by ax

10	get file position
	input:	bx = number of file of which to return length
	output:	cx = current location in the file specified

11	set file position
	input:	bx = number of file of which to return length
		cx = position to which to set the file
	output:	none

12	get input
	input:	si = address of string to contain user's input
	output:	si = string contains input from the user

13	add function to kernel list
	input:	si = string containing the name of the function to add to the kernel list
		es = handle of function for use in far call
		di = pointer (offset) of function for use in far call
	output:	none

14	remove function from kernel list
	input:	si = string containing the name of the function to remove from the kernel list
		es = handle of function for use in far call
		di = pointer (offset) of function for use in far call
	output:	none

15	get address of function in kernel list
	input:	si = string containing the name of the function to return an address for
	output:	es = handle of function for use in far call
		di = pointer (offset) of function for use in far call

16	return register value of other thread
	input:	bx = numeric code representing register to return
		cx = thread number of app to get register from
	output:	dx = register value from specified thread

17	get directory contents (initiate)
	input:	di = string containing filespec to return contents of
		si = string to hold PCOS long filenames of files in the directory specified
		bx = mask of attribute bytes to return file types
		dx = recursion flag (used to control how deep the kernel looks for size info
		when a directory is found)
	output:	si = address of a string containing the first filenames which matches the
		path and attributes specified.
		cx = size of the file returned
		(Note: This KINT is used to set or change the search criteria.
		KINT 21h should be used to find the next filename which matches the current
		search settings.)

18	plot point on screen (direct screen write for non-VESA modes)

19	reboot
	input:	none
	output:	none

1A	get word count of string
	input:	si = source string
		cx = ASCII code of separation character
	output:	bx = number of words in string

1B	get file data
	input:	si = filepath string
		es = string to hold file's date
		di = string to hold file's time
		bx = file's attributes
		cx = file length
	output:	none

1C	string search function
	input:	bx = character position to begin search in string pointed to by si
		si = string to search
		di = string to match
	output:	cx = position at which match string was found in search string
		(note: cx will be 0 if match string isn't found in search string)

1D	execute DOS app
	input:	si = string containing path to a DOS EXE or COM file to be run
	output:	none

1E	execute PCOS app
	input:	si = string containing path to PCOS application to be run
	output:	none

1F	get key press
	input:	none
	output:	bx = ASCII code of the key pressed

20	get cursor position
	input:	bx = current vertical position of cursor
		cx = current horizontal position of cursor

21	get directory contentents (continue)
	input:	si = address of a string to hold returned filename
	output:	si = address of a string containing the next filename which matches the
	search criteria set by KINT 17h.
		cx = size of the file returned
		dx = recursion flag (used to control how deep the kernel looks for size info
		when a directory is found)

22	rename file
	input:	si = address of a string containing filepath to the file to rename
		di = address of a string containing new name for the file
	output:	none

23	create directory
	input:	si = address of a string containing the name for the new directory
	output:	none

24	create file
	input:	si = address of a string containing the name for the new file
	output:	none

25	delete directory
	input:	si = address of a string containing the name for the new directory
	output:	none
		(NOTE: Unlike DOS, this function will delete a directory regardless of its
		contents! The directory will be deleted as well as EVERY FILE IN IT.)

26	delete file
	input:	si = address of a string containing the name for the new directory
	output:	none

27	add resource
	input:	bx = number of the file to which the resource will be added
		cx = number of the new resource
		si = address of a string containing the name for the new resource
		di = address of a string containing the contents of the new resource
	output:	none

28	delete resource
	input:	bx = number of the file to which the resource will be deleted
		cx = number of the resource to delete
		si = address of a string containing the name of the resource to delete
		di = address of a string containing the filepath of the file containing the resource
		to delete
	output:	none

29	set login name
	input:	si = address of a string containing the new login name
	output:	none

2A	get login name
	input:	si = address of a string to containing the retreived login name
	output:	none

2B	print imbedded string
	input:	si = address of string to print
	output:	none
		(NOTE: This function pops a value off the stack every time it encounters the
		"%" symbol, and treats this value as a pointer, printing whatever it finds at
		that address as part of the string. The string passed in si must be in ASCIIZ
		format.)

2C	get string from number
	input:	bx = number
		si = address of empty string
	output:	note

2D	get file length
	input:	bx = number of file of which to return length
	output:	cx = length of file specified

2E	get APM BIOS version
	input:	none
	output:	bx = major version of APM BIOS
		cx = minor version of APM BIOS
		dx = current state of APM
			0 = APM is currently disabled
			1 = APM is currently enabled

2F	activate / deactivate APM
	input:	bx = activate flag
			0 = deactivate
			1 = activate
	output:	none

30	APM power off
	input:	none
	output:	none

31	draw line - available in version 1.35 and up
	input:	bx = horizontal position of line start
		cx = vertical position of line start
		dx = horizontal position of line end
		ex = vertical position of line end
		fx = color of line
		gx = box attribute
			0 = line is drawn
			1 = rectangle is drawn
			2 = filled rectangle is drawn

32	set thread pause state - available in version 1.40 and up
	input:	bx = thread number (if bx = 0 then the calling thread number will be used)
		cx = new pause value
			0 = not paused
			1 = paused

33	set thread priority - available in version 1.40 and up
	input:	bx = thread number (if bx = 0 then the calling thread number will be used)
		cx = new priority value

			NOTE: There are two versions of this function call. The original was
			only used in kernel 1.40, and takes its input as follows:
			0 = one instruction per cycle
			1 = timed execution: 16 instructions per second
			2 = timed execution: 32 instructions per second
			3 = timed execution: 64 instructions per second
			4 = timed execution: 16 instructions per minute
			5 = timed execution: 32 instructions per minute
			6 = timed execution: 64 instructions per minute
			7 = 16 instructions per cycle
			8 = 32 instructions per cycle
			9 = 64 instructions per cycle

			The kernel versions since 1.40 have redefined the priority levels. The
			new standard is this:
			00 = timed execution: 1 instruction per second
			01 = timed execution: 32 instructions per second
			02 = timed execution: 64 instructions per second
			03 = timed execution: 1 instruction per minute
			04 = timed execution: 32 instructions per minute
			05 = timed execution: 64 instructions per minute
			06 = 1 instruction per cycle
			07 = 32 instructions per cycle
			08 = 64 instructions per cycle

34	open / close CD drive door
	input:	bx = drive number (A = 1, B = 2, etc.)
		cx = open / close flag
			0 = door is closed
			1 = door is opened

35	tone generator
	input:	bx = pitch of the tone to make in hertz (must be between 37 and 32767)
		cx = length of tone to make in thousandths of a second

Section 4: Instruction Opcodes (Listed by Instruction Name)

	The following table is an alphabetical listing of all the assembly opcodes recognized by the PCOS kernel.

Hex Opcode	Instruction Name
06		<unused>
A0		add
01		and
25		brl
26		brr
0A		call (num)
09		call (reg)
03		dec
28		dbug
2E		div
3C		exp
02		far call
11		far ret
04		in
05		inc
07		int (num)
24		int (reg)
08		iret (currently unsupported)
3D		jmp reg
1D		jmp num
40		jmpe
42		jmpg
41		jmpl
43		jmpn
39		mov mem(num)<num
1A		mov mem(num)<reg
17		mov mem<reg
1C		mov reg<mem
27		mov reg<mem(num)
22		mov reg<num
1F		mov reg<reg
3A		movb mem(num)<num
33		movb mem(num)<reg
2F		movb mem<reg
30		movb reg<mem
34		movb reg<mem(num)
31		movb reg<num
32		movb reg<reg
3B		movw mem(num)<num
37		movw mem(num)<reg
19		movw mem<reg
20		movw reg<mem
38		movw reg<mem(num)
35		movw reg<num
36		movw reg<reg
2D		mul
00		nop
0B		not
0C		or
0D		out
0E		pop
23		push (num)
10		push (reg)
0F		ret
12		sie
13		sig
14		sil
2C		sir
21		sise
1E		sisg
18		sisl
3F		sisn
3E		sne
29		stb
2A		stn
2B		stw
15		sub
1B		test
16		xor

Section 5: Instruction Opcodes (Listed by Opcode)

	The following table is a listing of all the assembly opcodes recognized by the PCOS kernel, this time sorted by opcode name.

Hex Opcode		Instruction Name
00			nop
01			and
02			far call
03			dec
04			in
05			inc
06			<unused>
07			int (num)
08			iret (currently unsupported)
09			call (reg)
0A			call (num)
0B			not
0C			or
0D			out
0E			pop
0F			ret
10			push (reg)
11			far ret
12			sie
13			sig
14			sil
15			sub
16			xor
17			mov mem<reg
18			sisl
19			movw mem<reg
1A			mov mem[num]<reg
1B			test
1C			mov reg<mem
1D			jmp (num)
1E			sisg
1F			mov reg<reg
20			movw reg<mem
21			sise
22			mov reg<num
23			push (num)
24			int (reg)
25			brl
26			brr
27			mov reg<mem[num]
28			dbug
29			stb
2A			stn
2B			stw
2C			sir
2D			mul
2E			div
2F			movb mem<reg
30			movb reg<mem
31			movb reg<num
32			movb reg<reg
33			movb mem[num]<reg
34			movb reg<mem[num]
35			movw reg<num
36			movw reg<reg
37			movw mem[num]<reg
38			movw reg<mem[num]
39			mov mem[num]<num
3A			movb mem[num]<num
3B			movw mem[num]<num
3C			exp
3D			jmp (reg)
3E			sne
3F			sisn
40			jmpe
41			jmpl
42			jmpg
43			jmpn
A0			add

Section 6: Kernel Error Codes

	Errors can crop up in any software. The question is, how does the operating system handle them? PCOS was built upon a solid framework, therefore when a thread causes problems, you can usually just terminate the errant program and continue merrily along your way. If a thread appears to have hung, froze, or locked up, you can always go to the command prompt and use 'thread x stop' to kill the process manually.

hex		decimal		error
200		512		invalid instruction
201		513		XMS driver not installed
202		514		no XMS available
203		515		invalid XMS address
204		516		resource not found
205		517		free thread not available
206		518		invalid data in call to KINT function
207		519		XMS error- not implemented
208		520		XMS error- VDISK detected (no room left for XMS)
209		521		XMS error- A20 error
20A		522		XMS error- all allocated
20B		523		XMS error- all handles used
20C		524		XMS error- invalid handle
20D		525		XMS error- invalid source handle
20E		526		XMS error- invalid source offset
20F		527		XMS error- invalid dest handle
210		528		XMS error- invalid dest offset
211		529		XMS error- invalid length
212		530		XMS error- overlap of source and dest in copy
213		531		XMS error- hardware parity error
214		532		XMS error- block is locked
215		533		invalid string length in ReadPascalString
216		534		KINT function not supported
217		535		Resource already exists
218		536		Error loading CODE resource
219		537		XMS access error- data not even
21A		538		Instruction unsupported
21B		539		Exception
21C		540		APM error- APM functionality disabled
21D		541		APM error- Real mode connection already established
21E		542		APM error- Interface not connected
21F		543		APM error- 16-bit protected mode connection already established
220		544		APM error- 32-bit protected mode connection already established
221		545		APM error- Unrecognized device ID
222		546		APM error- Parameter out of range
223		547		APM error- APM not present
224		548		thread is locked
225		549		kernel cannot be reset

Section 7: The Kernel Command Prompt

	The PCOS kernel includes a built-in command prompt which can be accessed by pressing the F1 key at any time. The command prompt is a faithful recreation of the traditional DOS command prompt. The commands are as follows:

chdir		Changes the current directory path for the drive you are currently on. You may also
		use 'cd'.
cls		Clears the screen.
copy		Copies files from one folder to another.
debug		Toggles debug mode. (Debug mode is not available in kernel 1.34.)
delete		Or 'del', use to delete files.
dir		Use to browse through a disk's contents.
drives		Lists information about all available disk drives.
exit		Exits the command prompt.
help		Displays this help information.
login		Allows you to enter your login information.
logout		Logs you out of the system.
mkdir		Use to create a directory. You can also use 'md'.
mem		Displays memory information.
pause		Pauses the system until you press a key. For use in batch files.
reboot		Reboots the computer.
rmdir		Or 'rd', use to remove a directory.
run		Used to launch a program. (version 1.33 only)
set		Used to view or set environment variables.
shutdown	Turns off an APM enabled computer.
thread		Use with 'stop' to terminate a thread, or 'switch' to switch to a thread, with 'info' to
		display information about a thread, with ‘pause’ to toggle the paused state of a
		thread or by itself to display a summary of all running threads. As of kernel version
		1.40, thread may be used with the 'priority' keyword to set the priority level of a
		thread manually, as follows: 'thread 4 priority 2'
ver		Displays kernel version information.
quit		Ends the kernel session.
xms		Use with 'release' to dispose of an XMS handle, with 'view' to see the contents of a
		block of XMS, or use by itself to display information about a handle.

Section 8: Command Line Switches

	The following switches can be used when invoking the PCOS kernel:

Switch		Name / Description
/nhp		“No Handle Probing” Disables handle probing which can cause problems under
		Windows.

Section 9: Kernel Priority Levels

	The PCOS kernel has several priority levels available to a thread. By default, the kernel infinite loop (thread 0) is assigned priority level 6, since it doesn't need any more CPU power than that. Any other threads, whether they are launched by the user or spawned by other threads, are assigned the highest priority, level 8. If a certain thread does not need to use that much of the CPU, it can alter its priority level by calling kint 0x33. This approach is used in the kernel's clock program, so that it only updates its display as needed to save CPU time, not constantly updating the screen thereby wasting CPU cycles unneccessarily. A programmer could, for example, create a GUI which automatically changed the priority level of threads as they ran, reducing the priority of threads in the background, and raising the priority of the thread the user is actually working with.

Priority Level				Description
00					timed execution: 1 instruction per second
01					timed execution: 32 instructions per second
02					timed execution: 64 instructions per second
03					timed execution: 1 instruction per minute
04					timed execution: 32 instructions per minute
05					timed execution: 64 instructions per minute
06					1 instruction per cycle
07					32 instructions per cycle
08					64 instructions per cycle