BlueGreycalmElegant

Català-Valencià – Catalan中文 – Chinese (Simplified)中文 – Chinese (Traditional)Česky – CzechDansk – DanishNederlands – DutchEnglish – EnglishSuomi – FinnishFrançais – FrenchDeutsch – Germanעברית – Hebrewहिंदी – HindiMagyar – HungarianBahasa Indonesia – IndonesianItaliano – Italian日本語 – Japanese한국어 – KoreanМакедонски – Macedonianमराठी – MarathiNorsk – NorwegianPolski – PolishPortuguês – PortuguesePortuguês – Portuguese (Brazil)Русский – RussianSlovenčina – SlovakSlovenščina – SlovenianEspañol – SpanishSvenska – SwedishTürkçe – TurkishУкраїнська – UkrainianOëzbekcha – Uzbek

Compare Revisions

• This comparison shows the changes necessary to convert path

  → /kernel/branches/gfx_kernel/docs/sysfuncs.txt @ 128

  → /kernel/branches/gfx_kernel/docs/sysfuncs.txt @ 129

  ↔ Reverse comparison

• Compare Path:	Rev

  With Path:	Rev

Regard whitespace Rev 128 → Rev 129

/kernel/branches/gfx_kernel/docs/sysfuncs.txt
0,0 → 1,4423
SYSTEM FUNCTIONS of OS Kolibri 0.5.8.1
Number of the function is located in the register eax.
The call of the system function is executed by "int 0x40" command.
All registers except explicitly declared in the returned value,
including eflags, are preserved.
======================================================================
============== Function 0 - define and draw the window. ==============
======================================================================
Defines an application window. Draws a frame of the window, header and
working area. For windows with skin defines standard buttons for close
and minimize.
Parameters:
* eax = 0 - function number
* ebx = [coordinate on axis x]*65536 + [size on axis x]
* ecx = [coordinate on axis y]*65536 + [size on axis y]
* edx = 0xXYRRGGBB, where:
* Y = style of the window:
* Y=0 - type I - window of the fixed size
* Y=1 - only define window area, draw nothing
* Y=2 - type II - window of the variable size
* Y=3 - window with skin
* other possible values (from 4 up to 15) are reserved,
function call with such Y is ignored
* RR, GG, BB = accordingly red, green, blue components of a color
of the working area of the window (are ignored for style Y=2)
* X = DCBA (bits)
* A = 1 - window has caption; for style Y=3 caption string
must be passed in edi, for other styles use
subfunction 1 of function 71
* B = 1 - coordinates of all graphics primitives are relative to
window client area
* C is reserved (set to 0)
* D = 0 - normal filling of the working area, 1 - gradient
The following parameters are intended for windows
of a type I and II, and ignored for styles Y=1,3:
* esi = 0xXYRRGGBB - color of the header
* RR, GG, BB define color
* Y=0 - usual window, Y=1 - unmovable window
* X defines a gradient of header: X=0 - no gradient,
X=8 - usual gradient,
for windows of a type II X=4 - negative gradient
* other values of X and Y are reserved
* edi = 0x00RRGGBB - color of the frame
Returned value:
* function does not return value
Remarks:
* Position and sizes of the window are installed by the first
call of this function and are ignored at subsequent; to change
position and/or sizes of already created window use function 67.
* For windows with style Y=3 and caption (A=1) caption string is set
by the first call of this function and is ignored at subsequent
(strictly speaking, is ignored after a call to subfunction 2
of function 12 - end redraw); to change caption of already created
window use subfunction 1 of function 71.
* If the window has appropriate styles, position and/or sizes can be
changed by user. Current position and sizes can be obtained
by function 9.
* The window must fit on the screen. If the transferred
coordinates and sizes do not satisfy to this condition,
appropriate coordinate (or, probably, both) is considered as zero,
and if also it does not help, the appropriate size
(or, probably, both) is installed in a size of the screen.
Further we shall designate xpos,ypos,xsize,ysize - values
transmitted in ebx,ecx. The coordinates are resulted concerning
the left upper corner of the window, which, thus, is set as (0,0),
coordinates of the right lower corner essence (xsize,ysize).
* The sizes of the window are understood in sence of coordinates
of the right lower corner. This concerns all other functions too.
It means, that the real sizes are on 1 pixel more.
* The window of type I looks as follows:
* draw external frame of color indicated in edi, 1 pixel in width
* draw header - rectangle with the left upper corner (1,1) and
right lower (xsize-1,min(25,ysize)) color indicated in esi
(taking a gradient into account)
* if ysize>=26, fill the working area of the window -
rectangle with the left upper corner (1,21) and right lower
(xsize-1,ysize-1) (sizes (xsize-1)*(ysize-21)) with color
indicated in edx (taking a gradient into account)
* if A=1 and caption has been already set by subfunction 1
of function 71, it is drawn in the corresponding place of header
* The window of style Y=1 looks as follows:
* completely defined by the application
* The window of type II looks as follows:
* draw external frame of width 1 pixel with the "shaded" color
edi (all components of the color decrease twice)
* draw intermediate frame of width 3 pixels with color edi
* draw internal frame of width 1 pixel with the "shaded" color edi
* draw header - rectangle with the left upper corner (4,4)
and right lower (xsize-4,min(20,ysize)) color, indicated in esi
(taking a gradient into account)
* if ysize>=26, fill the working area of the window -
rectangle with the left upper corner (5,20) and right lower
(xsize-5,ysize-5) with color indicated in edx
(taking a gradient into account)
* if A=1 and caption has been already set by subfunction 1
of function 71, it is drawn in the corresponding place of header
* The skinned window looks as follows:
* draw external frame of width 1 pixel
with color 'outer' from the skin
* draw intermediate frame of width 3 pixel
with color 'frame' from the skin
* draw internal frame of width 1 pixel
with color 'inner' from the skin
* draw header (on bitmaps from the skin) in a rectangle
(0,0) - (xsize,_skinh-1)
* if ysize>=26, fill the working area of the window -
rectangle with the left upper corner (5,_skinh) and right lower
(xsize-5,ysize-5) with color indicated in edx
(taking a gradient into account)
* define two standard buttons: for close and minimize
(see function 8)
* if A=1 and edi contains (nonzero) pointer to caption string,
it is drawn in place in header defined in the skin
* value _skinh is accessible as the result of call
subfunction 4 of function 48
======================================================================
================ Function 1 - put pixel in the window. ===============
======================================================================
Parameters:
* eax = 1 - function number
* ebx = x-coordinate (relative to the window)
* ecx = y-coordinate (relative to the window)
* edx = 0x00RRGGBB - color of a pixel
edx = 0x01xxxxxx - invert color of a pixel
(low 24 bits are ignored)
Returned value:
* function does not return value
======================================================================
============ Function 2 - get the code of the pressed key. ===========
======================================================================
Takes away the code of the pressed key from the buffer.
Parameters:
* eax = 2 - function number
Returned value:
* if the buffer is empty, function returns eax=1
* if the buffer is not empty, function returns al=0,
ah=code of the pressed key, high word of eax is zero
* if there is "hotkey", function returns al=2,
ah=scancode of the pressed key (0 for control keys),
high word of eax contains a status of control keys at the moment
of pressing a hotkey
Remarks:
* There is a common system buffer of the pressed keys
by a size of 120 bytes, organized as queue.
* There is one more common system buffer on 120 "hotkeys".
* If the application with the inactive window calls this function,
the buffer of the pressed keys is considered to be empty.
* By default this function returns ASCII-codes; to switch
to the scancodes mode (and back) use function 66.
However, hotkeys are always notificated as scancodes.
* To find out, what keys correspond to what codes, start
the application keyascii and scancode.
* Scancodes come directly from keyboard and are fixed;
ASCII-codes turn out with usage of the conversion tables,
which can be set by subfunction 2 of function 21
and get by subfunction 2 of function 26.
* As a consequence, ASCII-codes take into account current
keyboard layout (rus/en) as opposed to scancodes.
* This function notifies only about those hotkeys, which were
defined by this thread by subfunction 4 of function 66.
======================================================================
==================== Function 3 - get system time. ===================
======================================================================
Parameters:
* eax = 3 - function number
Returned value:
* eax = 0x00SSMMHH, where HH:MM:SS = Hours:Minutes:Seconds
* each item is BCD-number, for example,
for time 23:59:59 function returns 0x00595923
Remarks:
* See also subfunction 9 of function 26 - get time from
the moment of start of the system; it is more convenient, because
returns simply DWORD-value of the time counter.
* System time can be set by function 22.
======================================================================
============ Function 4 - draw text string in the window. ============
======================================================================
Parameters:
* eax = 4 - function number
* ebx = [coordinate on axis x]*65536 + [coordinate on axis y]
* ecx = 0xX0RRGGBB, where
* RR, GG, BB specify text color
* X specifies the used font: 0=system monospaced,
1=system font of variable width
* edx = pointer to the beginning of the string
* esi = length of the string, must not exceed 255
Returned value:
* function does not return value
Remarks:
* Function outputs either first (esi and 0xFF) characters or
all characters before (but not including) terminating zero
(for ASCIIZ-strings) depending on what occurs first.
* First system font is read out at loading from the file char.mt,
second - from char2.mt.
* Both fonts have height 9 pixels, width of the monospaced font
is equal to 6 pixels.
======================================================================
========================= Function 5 - delay. ========================
======================================================================
Delays execution of the program on the given time.
Parameters:
* eax = 5 - function number
* ebx = time in the 1/100 of second
Returned value:
* function does not return value
Remarks:
* Passing ebx=0 does not transfer control to the next process
and does not make any operations at all. If it is really required
to transfer control to the next process (to complete a current
time slice), use subfunction 1 of function 68.
* At current implementation there will be an immediate return from
the function, if the addition of ebx with current value of
time counter will call 32-bit overflow.
======================================================================
============== Function 6 - read the file from ramdisk. ==============
======================================================================
Parameters:
* eax = 6 - function number
* ebx = pointer to the filename
* ecx = number of start block, beginning from 1;
ecx=0 - read from the beginning of the file (same as ecx=1)
* edx = number of blocks to read;
edx=0 - read one block (same as edx=1)
* esi = pointer to memory area for the data
Returned value:
* eax = file size in bytes, if the file was successfully read
* eax = -1, if the file was not found
Remarks:
* This function is out-of-date; function 70 allows
to fulfil the same operations with the extended possibilities.
* Block = 512 bytes.
* For reading all file you can specify the certainly large value
in edx, for example, edx = -1; but in this case be ready that
the program will "fall", if the file will appear too large and can
not be placed in the program memory.
* The filename must be either in the format 8+3 characters
(first 8 characters - name itself, last 3 - extension,
the short names and extensions are supplemented with spaces),
or in the format 8.3 characters "FILE.EXT"/"FILE.EX "
(name no more than 8 characters, dot, extension 3 characters
supplemented if necessary by spaces).
The filename must be written with capital letters. The terminating
character with code 0 is not necessary (not ASCIIZ-string).
* This function does not support folders on the ramdisk.
======================================================================
=============== Function 7 - draw image in the window. ===============
======================================================================
Paramters:
* eax = 7 - function number
* ebx = pointer to the image in the format BBGGRRBBGGRR...
* ecx = [size on axis x]*65536 + [size on axis y]
* edx = [coordinate on axis x]*65536 + [coordinate on axis y]
Returned value:
* function does not return value
Remarks:
* Coordinates of the image are coordinates of the upper left corner
of the image relative to the window.
* Size of the image in bytes is 3*xsize*ysize.
======================================================================
=============== Function 8 - define/delete the button. ===============
======================================================================
Parameters for button definition:
* eax = 8 - function number
* ebx = [coordinate on axis x]*65536 + [size on axis x]
* ecx = [coordinate on axis y]*65536 + [size on axis y]
* edx = 0xXYnnnnnn, where:
* nnnnnn = identifier of the button
* high (31st) bit of edx is cleared
* if 30th bit of edx is set - do not draw the button
* if 29th bit of edx is set - do not draw a frame
at pressing the button
* esi = 0x00RRGGBB - color of the button
Parameters for button deleting:
* eax = 8 - function number
* edx = 0x80nnnnnn, where nnnnnn - identifier of the button
Returned value:
* function does not return value
Remarks:
* Sizes of the button must be more than 0 and less than 0x8000.
* For windows with skin definition of the window
(call of 0th function) creates two standard buttons -
for close of the window with identifier 1 and
for minimize of the window with identifier 0xffff.
* The creation of two buttons with same identifiers is admitted.
* The button with the identifier 0xffff at pressing is interpreted
by the system as the button of minimization, the system handles
such pressing independently, not accessing to the application.
In rest it is usual button.
* Total number of buttons for all applications is limited to 4095.
======================================================================
============ Function 9 - information on execution thread. ===========
======================================================================
Parameters:
* eax = 9 - function number
* ebx = pointer to 1-Kb buffer
* ecx = number of the slot of the thread
ecx = -1 - get information on the current thread
Returned value:
* eax = maximum number of the slot of a thread
* buffer pointed to by ebx contains the following information:
* +0: dword: usage of the processor (how many time units
per second leaves on execution of this thread)
* +4: word: position of the window of thread in the window stack
* +6: word: (has no relation to the specified thread)
number of the thread slot, which window has in the window stack
position ecx
* +8: word: reserved
* +10 = +0xA: 11 bytes: name of the process
(name of corresponding executable file in the format 8+3)
* +21 = +0x15: byte: alignment, this byte preserves
* +22 = +0x16: dword: address of the process in memory
* +26 = +0x1A: dword: size of used memory - 1
* +30 = +0x1E: dword: identifier (PID/TID)
* +34 = +0x22: dword: coordinate of the thread window on axis x
* +38 = +0x26: dword: coordinate of the thread window on axis y
* +42 = +0x2A: dword: size of the thread window on axis x
* +46 = +0x2E: dword: size of the thread window on axis y
* +50 = +0x32: word: status of the thread slot:
* 0 = thread is running
* 1 = thread is suspended
* 2 = thread is suspended while waiting for event
* 3 = thread is terminating as a result of call to function -1
or under duress as a result of call to subfunction 2
of function 18 or termination of the system
* 4 = thread is terminating as a result of exception
* 5 = thread waits for event
* 9 = requested slot is free, all other information on the slot
is not meaningful
Remarks:
* Slots are numbered starting from 1.
* Returned value is not a total number of threads, because there
can be free slots.
* When process is starting, system automatically creates
execution thread.
* Function gives information on the thread. Each process has
at least one thread. One process can create many threads,
in this case each thread has its own slot and the fields
+10, +22, +26 in these slots coincide.
Applications have no common way to define whether two threads
belong to one process.
* The active window - window on top of the window stack -
receives the messages on a keyboard input. For such window
the position in the window stack coincides with returned value.
* Slot 1 corresponds to special system thread, for which:
* the window is in the bottom of the window stack, the fields
+4 and +6 contain value 1
* name of the process - "OS/IDLE" (supplemented by spaces)
* address of the process in memory is 0, size of used memory is
16 Mb (0x1000000)
* PID=1
* coordinates and sizes of the window are by convention set to 0
* status of the slot is always 0 (running)
* the execution time adds of time leaving on operations itself
and idle time in waiting for interrupt (which can be got by call
to subfunction 4 of function 18).
* Beginning from slot 2, the normal applications are placed.
* The normal applications are placed in memory at the address
0x10000000 (kernel constand 'std_application_base_address').
There is no intersection, as each process has its own page table.
* At creation of the thread it is assigned the slot
in the system table and identifier (Process/Thread IDentifier =
PID/TID), which do not vary with time for given thread.
After completion of the thread its slot can be anew used
for another thread. The thread identifier can not be assigned
to other thread even after completion of this thread.
Identifiers, assigned to new threads, grow monotonously.
* If the thread has not yet defined the window by call to
function 0, the position and the sizes
of its window are considered to be zero.
* At the moment only the part of the buffer by a size
52 = 0x34 bytes is used. Nevertheless it is recommended to use
1-Kb buffer for the future compatibility, in the future
some fields can be added.
======================================================================
==================== Function 10 - wait for event. ===================
======================================================================
If the message queue is empty, waits for appearance of the message
in queue. In this state thread does not consume CPU time.
Then reads out the message from queue.
Parameters:
* eax = 10 - function number
Returned value:
* eax = event (see the list of events)
Remarks:
* Those events are taken into account only which enter into
a mask set by function 40. By default it is
redraw, key and button events.
* To check, whether there is a message in queue, use function 11.
To wait for no more than given time, use function 23.
======================================================================
=============== Function 11 - check for event, no wait. ==============
======================================================================
If the message queue contains event, function reads out
and return it. If the queue is empty, function returns 0.
Parameters:
* eax = 11 - function number
Returned value:
* eax = 0 - message queue is empty
* else eax = event (see the list of events)
Remarks:
* Those events are taken into account only, which enter into
a mask set by function 40. By default it is
redraw, key and button events.
* To wait for event, use function 10.
To wait for no more than given time, use function 23.
======================================================================
=============== Function 12 - begin/end window redraw. ===============
======================================================================
------------ Subfunction 1 - begin redraw of the window. -------------
Parameters:
* eax = 12 - function number
* ebx = 1 - subfunction number
Returned value:
* function does not return value
------------- Subfunction 2 - end redraw of the window. --------------
Parameters:
* eax = 12 - function number
* ebx = 2 - subfunction number
Returned value:
* function does not return value
Remarks:
* Subfunction 1 deletes all buttons defined with
function 8, they must be defined again.
======================================================================
============ Function 13 - draw a rectangle in the window. ===========
======================================================================
Parameters:
* eax = 13 - function number
* ebx = [coordinate on axis x]*65536 + [size on axis x]
* ecx = [coordinate on axis y]*65536 + [size on axis y]
* edx = color 0xRRGGBB or 0x80RRGGBB for gradient fill
Returned value:
* function does not return value
Remarks:
* Coordinates are understood as coordinates of the left upper corner
of a rectangle relative to the window.
======================================================================
=================== Function 14 - get screen size. ===================
======================================================================
Parameters:
* eax = 14 - function number
Returned value:
* eax = [xsize]*65536 + [ysize], where
* xsize = x-coordinate of the right lower corner of the screen =
horizontal size - 1
* ysize = y-coordinate of the right lower corner of the screen =
vertical size - 1
Remarks:
* See also subfunction 5 of function 48 - get sizes of
working area of the screen.
======================================================================
== Function 15, subfunction 1 - set a size of the background image. ==
======================================================================
Parameters:
* eax = 15 - function number
* ebx = 1 - subfunction number
* ecx = width of the image
* edx = height of the image
Returned value:
* function does not return value
Remarks:
* There is no checks for correctness. The setting of too large
values will result that the background will contain data abroad
of buffer for the background image. Buffer size = 0x160000-0x10,
that corresponds to maximum size 800*600. (800*600*3=0x15F900)
* For update of the screen (after completion of a series of commands
working with a background) call subfunction 3.
* There is a pair function for get size of the background image -
subfunction 1 of function 39.
======================================================================
=== Function 15, subfunction 2 - put pixel on the background image. ==
======================================================================
Parameters:
* eax = 15 - function number
* ebx = 2 - subfunction number
* ecx = offset
* edx = color of a pixel 0xRRGGBB
Returned value:
* function does not return value
Remarks:
* Offset for a pixel with coordinates (x,y) is calculated as
(x+y*xsize)*3.
* If the given offset exceeds 0x160000-16 = 1.375 Mb - 16 bytes,
the call is ignored.
* For update of the screen (after completion of a series of commands
working with a background) call subfunction 3.
* There is a pair function for get pixel on the background image -
subfunction 2 of function 39.
======================================================================
=========== Function 15, subfunction 3 - redraw background. ==========
======================================================================
Parameters:
* eax = 15 - function number
* ebx = 3 - subfunction number
Returned value:
* function does not return value
======================================================================
== Function 15, subfunction 4 - set drawing mode for the background. =
======================================================================
Parameters:
* eax = 15 - function number
* ebx = 4 - subfunction number
* ecx = drawing mode:
* 1 = tile
* 2 = stretch
Returned value:
* function does not return value
Remarks:
* For update of the screen (after completion of a series of commands
working with a background) call subfunction 3.
* There is a pair function for get drawing mode of the background -
subfunction 4 of function 39.
======================================================================
===================== Function 15, subfunction 5 =====================
============ Put block of pixels on the background image. ============
======================================================================
Parameters:
* eax = 15 - function number
* ebx = 5 - subfunction number
* ecx = pointer to the data in the format BBGGRRBBGGRR...
* edx = offset in data of the background image
* esi = size of data in bytes = 3 * number of pixels
Returned value:
* function does not return value
Remarks:
* If the block gets out abroad 0x160000-16 = 1.375 Mb - 16 bytes,
the call is ignored.
* Color of each pixel is stored as 3-bytes value BBGGRR.
* Pixels of the background image are written sequentially
from left to right, from up to down.
* Offset of pixel with coordinates (x,y) is (x+y*xsize)*3.
* For update of the screen (after completion of a series of commands
working with a background) call subfunction 3.
======================================================================
=============== Function 16 - save ramdisk on a floppy. ==============
======================================================================
Parameters:
* eax = 16 - function number
* ebx = 1 or ebx = 2 - on which floppy save
Returned value:
* eax = 0 - success
* eax = 1 - error
======================================================================
======= Function 17 - get the identifier of the pressed button. ======
======================================================================
Takes away the code of the pressed button from the buffer.
Parameters:
* eax = 17 - function number
Returned value:
* if the buffer is empty, function returns eax=1
* if the buffer is not empty, function returns al=0,
high 24 bits of eax contain button identifier (in particular, ah
contains low byte of the identifier; if all buttons have
the identifier less than 256, ah is enough to distinguish).
Remarks:
* "Buffer" keeps only one button, at pressing the new button the
information about old is lost.
* The call of this function by an application with inactive window
will return answer "buffer is empty".
======================================================================
============ Function 18, subfunction 1 - system shutdown. ===========
======================================================================
Parameters:
* eax = 18 - function number
* ebx = 1 - subfunction number
Returned value:
* function always return eax = 0 as tag of success
Remarks:
* On the last step menu of exit from the system appears and waits
response of the user.
* See also subfunction 9, system shutdown with
the parameter to force the choice in the exit menu.
======================================================================
= Function 18, subfunction 2 - terminate process/thread by the slot. =
======================================================================
Parameters:
* eax = 18 - function number
* ebx = 2 - subfunction number
* ecx = number of the slot of process/thread
Returned value:
* function does not return value
Remarks:
* It is impossible to terminate system thread OS/IDLE (with
number of the slot 1),
it is possible to terminate any normal process/thread.
* See also subfunction 18 - terminate
process/thread by the identifier.
======================================================================
===================== Function 18, subfunction 3 =====================
============= Make active the window of the given thread. ============
======================================================================
Parameters:
* eax = 18 - function number
* ebx = 3 - subfunction number
* ecx = number of the thread slot
Returned value:
* function does not return value
Remarks:
* If correct, but nonexistent slot is given,
some window is made active.
* To find out, which window is active, use subfunction 7.
======================================================================
===================== Function 18, subfunction 4 =====================
=========== Get counter of idle time units per one second. ===========
======================================================================
Idle time units are units, in which the processor stands idle
in waiting for interrupt (in the command 'hlt').
Parameters:
* eax = 18 - function number
* ebx = 4 - subfunction number
Returned value:
* eax = value of the counter of idle time units per one second
======================================================================
========== Function 18, subfunction 5 - get CPU clock rate. ==========
======================================================================
Parameters:
* eax = 18 - function number
* ebx = 5 - subfunction number
Returned value:
* eax = clock rate (modulo 2^32 clock ticks = 4GHz)
======================================================================
Function 18, subfunction 6 - save ramdisk to the file on hard drive.
======================================================================
Parameters:
* eax = 18 - function number
* ebx = 6 - subfunction number
* ecx defines path to the file:
* 1 = in the folder "/KOLIBRI"
* 2 = in the root folder
* 3 = edx points to the path (names of folders in the format 8+3,
divided by '/')
Returned value:
* eax = 0 - success
* else eax = error code of the file system
Çàìå÷àíèÿ:
* Filename is fixed, "menuet.img" (global kernel variable
'image_save' from 'preboot.inc')
* Drive and partition are defined by subfunction 7
and subfunction 8 of function 21.
* All folders in the given path must exist, otherwise function
returns value 5, "file not found".
======================================================================
=========== Function 18, subfunction 7 - get active window. ==========
======================================================================
Parameters:
* eax = 18 - function number
* ebx = 7 - subfunction number
Returned value:
* eax = number of the active window
(number of the slot of the thread with active window)
Remarks:
* Active window is at the top of the window stack and receives
messages on all keyboard input.
* To make a window active, use subfunction 3.
======================================================================
== Function 18, subfunction 8 - disable/enable the internal speaker. =
======================================================================
If speaker sound is disabled, all calls to subfunction 55 of
function 55 are ignored. If speaker sound is enabled,
they are routed on builtin speaker.
------------------- Subsubfunction 1 - get status. -------------------
Parameters:
* eax = 18 - function number
* ebx = 8 - subfunction number
* ecx = 1 - number of the subsubfunction
Returned value:
* eax = 0 - speaker sound is enabled; 1 - disabled
----------------- Subsubfunction 2 - toggle status. ------------------
Toggles states of disable/enable.
Parameters:
* eax = 18 - function number
* ebx = 8 - subfunction number
* ecx = 2 - number of the subsubfunction
Returned value:
* function does not return value
======================================================================
== Function 18, subfunction 9 - system shutdown with the parameter. ==
======================================================================
Parameters:
* eax = 18 - function number
* ebx = 9 - subfunction number
* ecx = parameter:
* 1 = on the last step of shutdown save ramdisk on a floppy and
then show the exit menu and request further operations
from the user
* 2 = turn off computer
* 3 = reboot computer
* 4 = restart the kernel from the file 'kernel.mnt' on ramdisk
Returned value:
* at incorrect ecx the registers do not change (i.e. eax=18)
* by correct call function always returns eax=0
as the tag of success
Remarks:
* Do not rely on returned value by incorrect call, it can be
changed in future versions of the kernel.
* It is possible to use subfunction 1, that on the last step
the user makes choice himself.
* It is not recommended to use value ecx=1 (to not irritate the user
with excessive questions); to save ramdisk on a floppy use
function 16 (which admits specification, on which floppy to
write), and to shutdown with the exit menu use already mentioned
subfunction 1.
======================================================================
===== Function 18, subfunction 10 - minimize application window. =====
======================================================================
Minimizes the own window.
Parameters:
* eax = 18 - function number
* ebx = 10 - subfunction number
Returned value:
* function does not return value
Remarks:
* The minimized window from the point of view of function 9
keeps position and sizes.
* Restoring of an application window occurs at its activation by
subfunction 3.
* Usually there is no necessity to minimize/restire a window
obviously: minimization of a window is carried out by the system
at pressing the minimization button (for skinned windows
it is defined automatically by function 0,
for other windows it can be defined manually by function 8),
restore of a window is done by the application '@panel'.
======================================================================
Function 18, subfunction 11 - get information on the disk subsystem.
======================================================================
Parameters:
* eax = 18 - function number
* ebx = 11 - subfunction number
* ecx = type of the table:
* 1 = short version, 10 bytes
* 2 = full version, 65536 bytes
* edx = pointer to the buffer (in the application) for the table
Returned value:
* function does not return value
Format of the table: short version:
* +0: byte: information about FDD's (drives for floppies),
AAAABBBB, where AAAA gives type of the first drive, BBBB -
of the second regarding to the following list:
* 0 = there is no drive
* 1 = 360Kb, 5.25''
* 2 = 1.2Mb, 5.25''
* 3 = 720Kb, 3.5''
* 4 = 1.44Mb, 3.5''
* 5 = 2.88Mb, 3.5'' (such drives are not used anymore)
For example, for the standard configuration from one 1.44-drive
here will be 40h, and for the case 1.2Mb on A: and 1.44Mb on B:
the value is 24h.
* +1: byte: information about hard disks and CD-drives, AABBCCDD,
where AA corresponds to the controller IDE0, ..., DD - IDE3:
* 0 = device is absent
* 1 = hard drive
* 2 = CD-drive
For example, in the case HD on IDE0 and CD on IDE2
this field contains 48h.
* +2: 4 db: number of the retrieved partitions on hard disks
at accordingly IDE0,...,IDE3.
If the hard disk on IDEx is absent, appropriate byte is zero,
otherwise it shows number of the recognized partitions, which
can be not presented (if the drive is not formatted or if
the file system is not supported). Current version of the kernel
supports only FAT16 and FAT32 for hard disks.
* +6: 4 db: reserved
Format of the table: full version:
* +0: 10 db: same as for the short version
* +10: 100 db: data for the first partition
* +110: 100 db: data for the second partition
* ...
* +10+100*(n-1): 100 db: data for the last partition
The partitions are located as follows: at first sequentially all
recoginzed partitions on HD on IDE0 (if present),
then on HD on IDE1 (if present) and so on up to IDE3.
Format of the information about partition
(at moment only FAT is supported):
* +0: dword: first physical sector of the partition
* +4: dword: last physical sector of the partition
(belongs to the partition)
* +8: dword: sectors per one copy of FAT
* +12 = +0xC: dword: number of copies of FAT
* +16 = +0x10: dword: number of sectors per cluster
* +20 = +0x14: dword: bytes per sector;
current implementation expects 0x200 = 512 in this field
* +24 = +0x18: dword: first root cluster in FAT32, 0 for FAT16
* +28 = +0x1C: dword: first physical sector of FAT
* +32 = +0x20: dword: first physical root sector for FAT16,
ignored for FAT32
* +36 = +0x24: dword: number of root sectors for FAT16,
0 for FAT32
* +40 = +0x28: dword: physical sector of the beginning of
the data area
* +44 = +0x2C: dword: maximum number of a cluster
* +48 = +0x30: dword: physical sector of the information
about the file system for FAT32, ignored for FAT16
* +52 = +0x34: dword: value used as boundary for special
values in FAT
* +56 = +0x38: dword: value used for bad clusters in FAT
* +60 = +0x3C: dword: value used as the end marker for FAT chain
* +64 = +0x40: dword: mask for FAT items
* +68 = +0x44: byte: file system type: 16 èëè 32
* +69 = +0x45: 31 db: reserved
Remarks:
* The short table can be used for obtaining the information about
available devices.
* First two fields in the information about partition
gives the parameters of partition, other - parameters of
FAT file system. For other file systems (when they will be
supported) specific for file system information will be, of
course, another, but first two fields will have the same sense.
======================================================================
========== Function 18, subfunction 13 - get kernel version. =========
======================================================================
Parameters:
* eax = 18 - function number
* ebx = 13 - subfunction number
* ecx = pointer to the buffer (not less than 16 bytes), where
the information will be placed
Returned value:
* function does not return value
Structure of the buffer:
db a,b,c,d for version a.b.c.d
db UID_xxx: one of UID_NONE=0, UID_MENUET=1, UID_KOLIBRI=2
db 'name',0 - ASCIIZ-string with the name
For Kolibri 0.5.8.1 kernel:
db 0,5,8,1
db 2
db 'Kolibri',0
======================================================================
======= Function 18, subfunction 14 - wait for screen retrace. =======
======================================================================
Waits for the beginning of retrace of the scanning ray of the screen
monitor.
Parameters:
* eax = 18 - function number
* ebx = 14 - subfunction number
Returned value:
* eax = 0 as the tag of success
Remarks:
* Function is intended only for active high-efficiency graphics
applications; is used for smooth output of a graphics.
======================================================================
== Function 18, subfunction 15 - center mouse cursor on the screen. ==
======================================================================
Parameters:
* eax = 18 - function number
* ebx = 15 - subfunction number
Returned value:
* eax = 0 as the tag of success
======================================================================
========= Function 18, subfunction 16 - get size of free RAM. ========
======================================================================
Parameters:
* eax = 18 - function number
* ebx = 16 - subfunction number
Returned value:
* eax = size of free memory in kilobytes
======================================================================
======== Function 18, subfunction 17 - get full amount of RAM. =======
======================================================================
Parameters:
* eax = 18 - function number
* ebx = 17 - subfunction number
Returned value:
* eax = total size of existing memory in kilobytes
======================================================================
===================== Function 18, subfunction 18 ====================
============= Terminate process/thread by the identifier. ============
======================================================================
Parameters:
* eax = 18 - function number
* ebx = 18 - subfunction number
* ecx = identifer of process/thread (PID/TID)
Returned value:
* eax = 0 - success
* eax = -1 - error (process is not found or is system)
Remarks:
* It is impossible to terminate system thread OS/IDLE (identifier
1), it is possible to terminate any normal process/thread.
* See also subfunction 2 - terminate
process/thread by given slot.
======================================================================
====================== Function 18, subfunction 19 =====================
======================= Get/set mouse features. ======================
======================================================================
Parameters:
* eax = 18 - function number
* ebx = 19 - subfunction number
* ecx = subsubfunction number
ecx = 0 - get mouse speed
Returned value:
* eax = current mouse speed
ecx = 1 - set mouse speed
edx = selected value of speed
Returned value:
* function does not return value
ecx = 2 - get mouse delay
Returned value:
* eax = current mouse delay
ecx = 3 - set mouse delay
edx = selected value of delay
Returned value:
* function does not return value
ecx = 4 - set mouse pointer position
edx = [coordinate on axis x]*65536 + [coordinate on axis y]
Returned value:
* function does not return value
Remarks:
* Recommended speed of the mouse (in subfunction 1) from 1 up to 9.
The installed value is not inspected by the code of a kernel, on this use
cautiously, at incorrect value the cursor can "freeze".
Speed of mouse can be regulated through the application SETUP.
* Recommended delay of the mouse (in subfunction 3) = 10. Lower value
is not handled COM by mice. At the very large values the movement of
the mouse on 1 pixel is impossible and the cursor will jump
on the value of the installed speed (subfunction 1).
The installed value is not inspected by the code of a kernel.
* In subfunction 4 the installed value is not inspected by
the code of a kernel. Before usage it is necessary to find out current
screen resolution and at installation of a position to watch,
that the value of a position should do not fall outside
the limits the screen.
======================================================================
============ Function 19 - start application from ramdisk. ===========
======================================================================
Parameters:
* eax = 19 - function number
* ebx = pointer to the application name in format similar
to function 6
* ecx = 0 or ecx = pointer to command line parameters
Returned value:
* If eax > 0, then eax contains PID of the created process
* If eax < 0, then -eax - file system error code
Remarks:
* This function is obsolete; use subfunction 7 of function 70.
* Command line must be terminated by the character with the code 0
(ASCIIZ-string); function takes into account either all characters
up to terminating zero inclusively or first 256 character
regarding what is less.
======================================================================
==================== Function 20 - MIDI interface. ===================
======================================================================
----------------------- Subfunction 1 - reset ------------------------
Parameters:
* eax = 20 - function number
* ebx = 1 - subfunction number
-------------------- Subfunction 2 - output byte ---------------------
Parameters:
* eax = 20 - function number
* ebx = 2 - subfunction number
* cl = byte for output
Returned value (is the same for both subfunctions):
* eax = 0 - success
* eax = 1 - base port is not defined
Remarks:
* Previously the base port must be defined by
subfunction 1 of function 21.
======================================================================
======== Function 21, subfunction 1 - set MPU MIDI base port. ========
======================================================================
Parameters:
* eax = 21 - function number
* ebx = 1 - subfunction number
* ecx = number of base port
Returned value
* eax = 0 - success
* eax = -1 - erratic number of a port
Remarks:
* Number of a port must satisfy to conditions 0x100<=ecx<=0xFFFF.
* The installation of base is necessary for function 20.
* To get base port use subfunction 1 of function 26.
======================================================================
========== Function 21, subfunction 2 - set keyboard layout. =========
======================================================================
Keyboard layout is used to convert keyboard scancodes to ASCII-codes,
which will be read by function 2.
Parameters:
* eax = 21 - function number
* ebx = 2 - subfunction number
* ecx = which layout to set:
* 1 = normal layout
* 2 = layout at pressed Shift
* 3 = layout at pressed Alt
* edx = pointer to layout - table of length 128 bytes
Or:
* ecx = 9
* dx = country identifier (1=eng, 2=fi, 3=ger, 4=rus)
Returned value:
* eax = 0 - success
* eax = 1 - incorrect parameter
Remarks:
* If Alt is pressed, the layout with Alt is used;
if Alt is not pressed, but Shift is pressed,
the layout with Shift is used;
if Alt and Shift are not pressed, but Ctrl is pressed, the normal
layout is used and then from the code is subtracted 0x60;
if no control key is pressed, the normal layout is used.
* To get layout and country identifier use
subfunction 2 of function 26.
* Country identifier is global system variable, which is not used
by the kernel itself; however the application '@panel' displays
the corresponding icon.
* The application @panel switches layouts on user request.
======================================================================
============== Function 21, subfunction 3 - set CD base. =============
======================================================================
Parameters:
* eax = 21 - function number
* ebx = 3 - subfunction number
* ecx = CD base: 1=IDE0, 2=IDE1, 3=IDE2, 4=IDE3
Returned value:
* eax = 0
Remarks:
* CD base is used by function 24.
* To get CD base use subfunction 3 of function 26.
======================================================================
====== Function 21, subfunction 4 - set Sound Blaster base port. =====
======================================================================
Parameters:
* eax = 21 - function number
* ebx = 4 - subfunction number
* ecx = number of the base port
Returned value:
* eax = 0 - success
* eax = -1 - erratic port number
Remarks:
* Number of the port must satisfy to conditions 0x100<=ecx<=0xFFFF.
* The installation of the base is necessary for
functions 25, 28, 55.
* To get base port use subfunction 4 of function 26.
======================================================================
========== Function 21, subfunction 5 - set system language. =========
======================================================================
Parameters:
* eax = 21 - function number
* ebx = 5 - subfunction number
* ecx = system language (1=eng, 2=fi, 3=ger, 4=rus)
Returned value:
* eax = 0
Remarks:
* System language is global system variable and is not used
by the kernel itself, however application @panel draws the
appropriate icon.
* Function does not check for correctness, as the kernel does not
use this variable.
* To get system language use subfunction 5 of function 26.
======================================================================
=========== Function 21, subfunction 6 - set WSS base port. ==========
======================================================================
Parameters:
* eax = 21 - function number
* ebx = 6 - subfunction number
* ecx = base port
Returned value:
* eax = 0 - success
* eax = -1 - erratic port number
Remarks:
* Port number must satisfy to condition 0x100<=ecx.
* WSS base is used by function 27.
* To get WSS base port use subfunction 6 of function 26.
======================================================================
============== Function 21, subfunction 7 - set HD base. =============
======================================================================
The HD base defines hard disk to write with usage of obsolete
file system functions and functions implicitly using the hard disk
(such as subfunction 6 of function 18);
at usage of function 58 and 70 and modern syntax /HD0,/HD1,/HD2,/HD3
these function set base themselves.
Parameters:
* eax = 21 - function number
* ebx = 7 - subfunction number
* ecx = HD base: 1=IDE0, 2=IDE1, 3=IDE2, 4=IDE3
Returned value:
* eax = 0
Remarks:
* Any application at any time can change the base.
* Do not change base, when any application works with hard disk.
If you do not want system bugs.
* To get HD base use subfunction 7 of function 26.
* It is also necessary to define used partition of hard disk by
subfunction 8.
======================================================================
========= Function 21, subfunction 8 - set used HD partition. ========
======================================================================
The HD partition defines partition of the hard disk to write with
usage of obsolete file system functions and functions implicitly
using the hard disk (such as subfunction 6 of function 18);
at usage of functions 58 and 70 and modern syntax /HD0,/HD1,/HD2,/HD3
these functions set base and partition themselves.
Parameters:
* eax = 21 - function number
* ebx = 8 - subfunction number
* ecx = HD partition (beginning from 1)
Return value:
* eax = 0
Remarks:
* Any application at any time can change partition.
* Do not change partition when any application works with hard disk.
If you do not want system bugs.
* To get used partition use subfunction 8 of function 26.
* There is no correctness checks.
* To get the number of partitions of a hard disk use
subfunction 11 of function 18.
* It is also necessary to define used HD base by subfunction 7.
======================================================================
======== Function 21, subfunction 10 - set sound DMA channel. ========
======================================================================
Parameters:
* eax = 21 - function number
* ebx = 10 - subfunction number
* ecx = number of channel (from 0 up to 3 inclusively)
Returned value:
* eax = 0 - success
* eax = -1 - incorrect channel number
Remarks:
* Number of DMA channel is used in subfunction 1 of function 55.
* To get sound DMA channel use subfunction 10 of function 26.
======================================================================
Function 21, subfunction 11 - enable/disable low-level access to HD.
======================================================================
Parameters:
* eax = 21 - function number
* ebx = 11 - subfunction number
* ecx = 0/1 - disable/enable
Returned value:
* eax = 0
Remarks:
* Is used in LBA-read (subfunction 8 of function 58).
* The current implementation uses only low bit of ecx.
* To get current status use subfunction 11 of function 26.
======================================================================
Function 21, subfunction 12 - enable/disable low-level access to PCI.
======================================================================
Parameters:
* eax = 21 - function number
* ebx = 12 - subfunction number
* ecx = 0/1 - disable/enable
Returned value:
* eax = 0
Remarks:
* Is used in operations with PCI bus (function 62).
* The current implementation uses only low bit of ecx.
* To get current status use subfunction 12 of function 26.
======================================================================
============ Function 21, subfunction 13, subsubfunction 1 ===========
======== Initialize + get information on the driver vmode.mdr. =======
======================================================================
Parameters:
* eax = 21 - function number
* ebx = 13 - subfunction number
* ecx = 1 - number of the driver function
* edx = pointer to 512-bytes buffer
Returned value:
* if driver is not loaded
(never happens in the current implementation):
* eax = -1
* ebx, ecx destroyed
* if driver is loaded:
* eax = 'MDAZ' (in fasm style, that is 'M' - low byte, 'Z' - high)
- signature
* ebx = current frequency of the scanning (in Hz)
* ecx destroyed
* buffer pointed to by edx is filled
Format of the buffer:
* +0: 32*byte: driver name, "Trans VideoDriver"
(without quotes, supplemented by spaces)
* +32 = +0x20: dword: driver version (version x.y is encoded as
y*65536+x), for the current implementation is 1 (1.0)
* +36 = +0x24: 7*dword: reserved (0 in the current implementation)
* +64 = +0x40: 32*word: list of supported videomodes (each word
is number of a videomode, after list itself there are zeroes)
* +128 = +0x80: 32*(5*word): list of supported frequences of the
scannings for videomodes: for each videomode listed in the
previous field up to 5 supported frequences are given
(unused positions contain zeroes)
Remarks:
* Function initializes the driver (if it is not initialized yet)
and must be called first, before others (otherwise they will do
nothing and return -1).
* The current implementation supports only one frequency
of the scanning on videomode.
======================================================================
============ Function 21, subfunction 13, subsubfunction 2 ===========
================ Get information on current videomode. ===============
======================================================================
Parameters:
* eax = 21 - function number
* ebx = 13 - subfunction number
* ecx = 2 - number of the driver function
Returned value:
* eax = -1 - driver is not loaded or not initialized;
ebx,ecx are destroyed
* eax = [width]*65536 + [height]
* ebx = frequency of the vertical scanning (in Hz)
* ecx = number of current videomode
Remarks:
* Driver must be initialized by call to
driver function 1.
* If only screen sizes are required, it is more expedient to use
function 14 taking into account that it
returns sizes on 1 less.
======================================================================
=== Function 21, subfunction 13, subsubfunction 3 - set videomode. ===
======================================================================
Parameters:
* eax = 21 - function number
* ebx = 13 - subfunction number
* ecx = 3 - number of the driver function
* edx = [scanning frequency]*65536 + [videomode number]
Returned value:
* eax = -1 - driver is not loaded, not initialized or
an error has occured
* eax = 0 - success
* ebx, ecx destroyed
Remarks:
* Driver must be initialized by driver function 1.
* The videomode number and frequency must be in the table
returned by driver function 1.
======================================================================
============ Function 21, subfunction 13, subsubfunction 4 ===========
================== Return to the initial videomode. ==================
======================================================================
Returns the screen to the videomode set at system boot.
Parameters:
* eax = 21 - function number
* ebx = 13 - subfunction number
* ecx = 4 - number of the driver function
Returned value:
* eax = -1 - driver is not loaded or not initialized
* eax = 0 - success
* ebx, ecx destroyed
Remarks:
* Driver must be initialized by call to driver function 1.
======================================================================
============ Function 21, subfunction 13, subsubfunction 5 ===========
===== Increase/decrease the size of the visible area of monitor. =====
======================================================================
Parameters:
* eax = 21 - function number
* ebx = 13 - subfunction number
* ecx = 5 - number of the driver function
* edx = 0/1 - decrease/increase horizontal size on 1 position
* edx = 2/3 - is not supported in the current implementation;
is planned as decrease/increase vertical size on 1 position
Returned value:
* eax = -1 - driver is not loaded or not initialized
* eax = 0 - success
* ebx, ecx destroyed
Remarks:
* Driver must be initialized by call to driver function 1.
* Function influences only the physical size of the screen image;
the logical size (number of pixels) does not change.
======================================================================
================= Function 22 - set system date/time. ================
======================================================================
Parameters:
* eax = 22 - function number
* ebx = 0 - set time
* ecx = 0x00SSMMHH - time in the binary-decimal code (BCD):
* HH=hour 00..23
* MM=minute 00..59
* SS=second 00..59
* ebx = 1 - set date
* ecx = 0x00DDMMYY - date in the binary-decimal code (BCD):
* DD=day 01..31
* MM=month 01..12
* YY=year 00..99
* ebx = 2 - set day of week
* ecx = 1 for Sunday, ..., 7 for Saturday
* ebx = 3 - set alarm clock
* ecx = 0x00SSMMHH
Returned value:
* eax = 0 - success
* eax = 1 - incorrect parameter
* eax = 2 - CMOS-battery was unloaded
Remarks:
* Value of installation of day of week seems to be doubtful,
as it a little where is used
(day of week can be calculated by date).
* Alarm clock can be set on operation in the given time every day.
But there is no existing system function to disable it.
* Operation of alarm clock consists in generation IRQ8.
* Generally CMOS supports for alarm clock set of value 0xFF
as one of parameters and it means that the appropriate parameter
is ignored. But current implementation does not allow this
(will return 1).
* Alarm clock is a global system resource; the set of
an alarm clock cancels automatically the previous set.
However, at moment no program uses it.
======================================================================
============= Function 23 - wait for event with timeout. =============
======================================================================
If the message queue is empty, waits for new message in the queue,
but no more than given time. Then reads out a message from the queue.
Parameters:
* eax = 23 - function number
* ebx = timeout (in 1/100 of second)
Returned value:
* eax = 0 - the message queue is empty
* otherwise eax = event (see the list of events)
Remarks:
* Only those events are taken into account, which enter into
the mask set by function 40. By default it is
redraw, key and button events.
* To check for presence of a message in the queue use function 11.
To wait without timeout use function 10.
* Transmission ebx=0 results in immediate returning eax=0.
* Current implementation returns immediately with eax=0,
if the addition of ebx with the current value of time counter
makes 32-bit overflow.
======================================================================
======== Function 24, subfunction 1 - begin to play CD-audio. ========
======================================================================
Parameters:
* eax = 24 - function number
* ebx = 1 - subfunction number
* ecx = 0x00FRSSMM, where
* MM = starting minute
* SS = starting second
* FR = starting frame
Returned value:
* eax = 0 - success
* eax = 1 - CD base is not defined
Remarks:
* Previously CD base must be defined by the call to
subfunction 3 of function 21.
* One second includes 75 frames, one minute includes 60 seconds.
* The function is asynchronous (returns control, when play begins).
======================================================================
======= Function 24, subfunction 2 - get information on tracks. ======
======================================================================
Parameters:
* eax = 24 - function number
* ebx = 2 - subfunction number
* ecx = pointer to the buffer for the table
(maximum 8*64h+4 bytes=100 tracks)
Returned value:
* eax = 0 - success
* eax = 1 - CD base is not defined
Remarks:
* The format of the table with tracks information is the same as
for ATAPI-CD command 43h (READ TOC), usual table (subcommand 00h).
Function returns addresses in MSF.
* Previously CD base port must be set by call to
subfunction 3 of function 21.
* Function returns information only about no more than 100
first tracks. In most cases it is enough.
======================================================================
========== Function 24, subfunction 3 - stop play CD-audio. ==========
======================================================================
Parameters:
* eax = 24 - function number
* ebx = 1 - subfunction number
Returned value:
* eax = 0 - success
* eax = 1 - CD base is not defined
Çàìå÷àíèÿ:
* Previously CD base port must be defined by call to
subfunction 3 of function 21.
======================================================================
=================== Function 25 - set SBPro volume. ==================
======================================================================
Parameters:
* eax = 25 - function number
* ebx = what to set:
* 1 - set common volume
* 2 - set CD-audio volume
* cl = volume level: high 4 bits for the left column,
low 4 bits for the right one
Returned value:
* eax = 0 - success
* eax = 1 - SB base is not defined
* eax = 2 - incorrect subfunction
Remarks:
* Previously SB base port must be defined by
subfunction 4 of function 21.
* See also function 28 which sets
volume for the later standard SB16.
======================================================================
======== Function 26, subfunction 1 - get MPU MIDI base port. ========
======================================================================
Parameters:
* eax = 26 - function number
* ebx = 1 - subfunction number
Returned value:
* eax = port number
Parameters:
* To set base port use subfunction 1 of function 21.
======================================================================
========== Function 26, subfunction 2 - get keyboard layout. =========
======================================================================
The keyboard layout is used to convert keyboard scancodes to
ASCII-codes for function 2.
Parameters:
* eax = 26 - function number
* ebx = 2 - subfunction number
* ecx = what layout to get:
* 1 = normal layout
* 2 = layout with pressed Shift
* 3 = layout with pressed Alt
* edx = pointer to the 128-bytes buffer, where the layout will be
copied
Returned value:
* function does not return value
Or:
* eax = 26 - function number
* ebx = 2 - subfunction number
* ecx = 9
Returned value:
* eax = country identifier (1=eng, 2=fi, 3=ger, 4=rus)
Remarks:
* If Alt is pressed, the layout with Alt is used;
if Alt is not pressed, but Shift is pressed,
the layout with Shift is used;
if Alt and Shift are not pressed, but Ctrl is pressed, the normal
layout is used and then from the code is subtracted 0x60;
if no control key is pressed, the normal layout is used.
* To set layout and country identifier use
subfunction 2 of function 21.
* Country identifier is global system variable, which is not used
by the kernel itself; however the application '@panel' displays
the corresponding icon (using this function).
* The application @panel switches layouts on user request.
======================================================================
============== Function 26, subfunction 3 - get CD base. =============
======================================================================
Parameters:
* eax = 26 - function number
* ebx = 3 - subfunction number
Returned value:
* eax = CD base: 1=IDE0, 2=IDE1, 3=IDE2, 4=IDE3
Remarks:
* CD base is used by function 24.
* To set CD base use subfunction 3 of function 21.
======================================================================
====== Function 26, subfunction 4 - get Sound Blaster base port. =====
======================================================================
Parameters:
* eax = 26 - function number
* ebx = 4 - subfunction number
Returned value:
* eax = base port number
Remarks:
* Bae port is used by functions 25, 55.
* To set base port use subfunction 4 of function 21.
======================================================================
========== Function 26, subfunction 5 - get system language. =========
======================================================================
Parameters:
* eax = 26 - function number
* ebx = 5 - subfunction number
Returned value:
* eax = system language (1=eng, 2=fi, 3=ger, 4=rus)
Remarks:
* System language is global system variable and is not used
by the kernel itself, however application @panel draws the
appropriate icon (using this function).
* To set system language use subfunction 5 of function 21.
======================================================================
=========== Function 26, subfunction 6 - get WSS base port. ==========
======================================================================
Parameters:
* eax = 26 - function number
* ebx = 6 - subfunction number
Returned value:
* eax = base port
Remarks:
* WSS base is used by function 27.
* To set WSS base port use subfunction 6 of function 21.
======================================================================
============== Function 26, subfunction 7 - get HD base. =============
======================================================================
The HD base defines hard disk to write with usage of obsolete
file system functions and functions implicitly using the hard disk
(such as subfunction 6 of function 18);
at usage of function 58 and 70 and modern syntax /HD0,/HD1,/HD2,/HD3
these function set base themselves.
Parameters:
* eax = 26 - function number
* ebx = 7 - subfunction number
Returned value:
* eax = HD base: 1=IDE0, 2=IDE1, 3=IDE2, 4=IDE3
Remarks:
* Any application in any time can change HD base.
* To set base use subfunction 7 of function 21.
* To get used partition of hard disk use subfunction 8.
======================================================================
========= Function 26, subfunction 8 - get used HD partition. ========
======================================================================
The HD partition defines partition of the hard disk to write with
usage of obsolete file system functions and functions implicitly
using the hard disk (such as subfunction 6 of function 18);
at usage of functions 58 and 70 and modern syntax /HD0,/HD1,/HD2,/HD3
these functions set base and partition themselves.
Parameters:
* eax = 26 - function number
* ebx = 8 - subfunction number
Returned value:
* eax = HD partition (beginning from 1)
Remarks:
* Any application in any time can change partition.
* To set partition use subfunction 8 of function 21.
* To get number of partitions on a hard disk use
subfunction 11 of function 18.
* To get base of used hard disk, use subfunction 7.
======================================================================
=== Function 26, subfunction 9 - get the value of the time counter. ==
======================================================================
Parameters:
* eax = 26 - function number
* ebx = 9 - subfunction number
Returned value:
* eax = number of 1/100s of second, past from the system boot time
Remarks:
* Counter takes modulo 2^32, that correspond to a little more
than 497 days.
* To get system time use function 3.
======================================================================
======== Function 26, subfunction 10 - get sound DMA channel. ========
======================================================================
Parameters:
* eax = 26 - function number
* ebx = 10 - subfunction number
Returned value:
* eax = number of the channel (from 0 to 3 inclusive)
Remarks:
* Number of the DMA channel is used by subfunction 1 of function 55.
* To set the sound DMA channel use subfunction 10 of function 21.
======================================================================
===================== Function 26, subfunction 11 ====================
========== Find out whether low-level HD access is enabled. ==========
======================================================================
Parameters:
* eax = 26 - function number
* ebx = 11 - subfunction number
Returned value:
* eax = 0/1 - disabled/enabled
Remarks:
* Is used in LBA read (subfunction 8 of function 58).
* To set current state use subfunction 11 of function 21.
======================================================================
===================== Function 26, subfunction 12 ====================
========== Find out whether low-level PCI access is enabled. =========
======================================================================
Parameters:
* eax = 26 - function number
* ebx = 12 - subfunction number
Returned value:
* eax = 0/1 - disabled/enabled
Remarks:
* Is used by operations with PCI bus (function 62).
* The current implementation uses only low bit of ecx.
* To set the current state use subfunction 12 of function 21.
======================================================================
======== Function 27 - set Windows Sound System (WSS) volume. ========
======================================================================
Parameters:
* eax = 27 - function number
* ebx = what to set:
* 1 - set common volume
* 2 - set Line In volume
* cl = volume level (0x0=highest, 0x1F=lowest,
if bit 0x80 is set=disable)
Returned value:
* eax = 0 - success
* eax = 1 - WSS base is not defined
* eax = 2 - incorrect subfunction
Remarks:
* Previously WSS base port must be defined by call to
subfunction 6 of function 21.
* Set of common volume is ignored (function simply returns eax=0).
* Old documentation and kernel sources erraticly name function 2
as CD-audio volume.
======================================================================
=================== Function 28 - set SB16 volume. ===================
======================================================================
Parameters:
* eax = 28 - function number
* ebx = what to install:
* 1 - install common volume
* 2 - install CD-audio volume
* cl = volume level (0=off, 0xFF=max)
Returned value:
* eax = 0 - success
* eax = 1 - SB base is not defined
* eax = 2 - incorrect subfunction
Remarks:
* Previously SB base port must be defined by
subfunction 4 of function 21.
* This function gives more variants for volume, that function 25.
======================================================================
=================== Function 29 - get system date. ===================
======================================================================
Parameters:
* eax = 29 - function number
Returned value:
* eax = 0x00DDMMYY, where
(binary-decimal coding, BCD, is used)
* YY = two low digits of year (00..99)
* MM = month (01..12)
* DD = day (01..31)
Remarks:
* To set system date use function 22.
======================================================================
=============== Function 32 - delete file from ramdisk. ==============
======================================================================
Parameters:
* eax = 32 - function number
* ebx = pointer to the filename
Returned value:
* eax = 0 - success; otherwise file system error code
Remarks:
* This function is obsolete; function 58 allows to fulfill
the same operations with the extended possibilities.
* The current implementation returns only values 0(success) and
5(file not found).
* The filename must be either in the format 8+3 characters
(first 8 characters - name itself, last 3 - extension,
the short names and extensions are supplemented with spaces),
or in the format 8.3 characters "FILE.EXT"/"FILE.EX "
(name no more than 8 characters, dot, extension 3 characters
supplemented if necessary by spaces).
The filename must be written with capital letters. The terminating
character with code 0 is not necessary (not ASCIIZ-string).
* This function does not support folders on the ramdisk.
======================================================================
================ Function 33 - write file to ramdisk. ================
======================================================================
Parameters:
* eax = 33 - function number
* ebx = pointer to the filename
* ecx = pointer to data for writing
* edx = number of bytes for writing
* should be set esi=0
Returned value:
* eax = 0 - success, otherwise file system error code
Remarks:
* This function is obsolete; function 70 allows to fulfil
the same operations with extended possibilities.
* If esi contains non-zero value and selected file already exists,
one more file with the same name will be created.
* Otherwise file will be overwritten.
* The filename must be either in the format 8+3 characters
(first 8 characters - name itself, last 3 - extension,
the short names and extensions are supplemented with spaces),
or in the format 8.3 characters "FILE.EXT"/"FILE.EX "
(name no more than 8 characters, dot, extension 3 characters
supplemented if necessary by spaces).
The filename must be written with capital letters. The terminating
character with code 0 is not necessary (not ASCIIZ-string).
* This function does not support folders on the ramdisk.
======================================================================
======= Function 35 - read the color of a pixel on the screen. =======
======================================================================
Parameters:
* eax = 35
* ebx = y*xsize+x, where
* (x,y) = coordinates of a pixel (beginning from 0)
* xsize = horizontal screen size
Returned value:
* eax = color 0x00RRGGBB
Remarks:
* To get screen sizes use function 14. Pay attention,
that it subtracts 1 from both sizes.
* There is also direct access (without any system calls)
to videomemory through the selector gs. To get parameters of
the current videomode, use function 61.
======================================================================
========= Function 37 - get coordinates/status of the mouse. =========
======================================================================
---------- Subfunction 0 - screen coordinates of the mouse -----------
Parameters:
* eax = 37 - function number
* ebx = 0 - subfunction number
Returned value:
* eax = x*65536 + y, (x,y)=coordinates of the mouse pointer
(beginning from 0)
-- Subfunction 1 - coordinates of the mouse relative to the window ---
Parameters:
* eax = 37 - function number
* ebx = 1 - subfunction number
Returned value:
* eax = x*65536 + y, (x,y)=coordinates of the mouse pointer
relative to the application window (beginning from 0)
Remarks:
* The value is calculated by formula (x-xwnd)*65536 + (y-ywnd).
If y>=ywnd, the low word is non-negative and contains
relative y-coordinate, and the high word - relative x-coordinate
(with correct sign). Otherwise the low word is negative and still
contains relative y-coordinate, and to the high word
1 should be added.
------------ Subfunction 2 - pressed buttons of the mouse ------------
Parameters:
* eax = 37 - function number
* ebx = 2 - subfunction number
Returned value:
* eax contains information on the pressed mouse buttons:
* bit 0 is set = left button is pressed
* bit 1 is set = right button is pressed
* other bits are cleared
======================================================================
====================== Function 38 - draw line. ======================
======================================================================
Parameters:
* eax = 38 - function number
* ebx = [start coordinate on axis x]*65536 +
[end coordinate on axis x]
* ecx = [start coordinate on axis y]*65536 +
[end coordinate on axis y]
* edx = 0x00RRGGBB - color
Returned value:
* function does not return value
Remarks:
* Coordinates are relative to the window.
* End point is also drawn.
======================================================================
== Function 39, subfunction 1 - get a size of the background image. ==
======================================================================
Parameters:
* eax = 39 - function number
* ebx = 1 - subfunction number
Returned value:
* eax = [width]*65536 + [height]
Remarks:
* There is a pair function to set sizes of background image -
subfunction 1 of function 15. After which it is necessary,
of course, anew to define image.
======================================================================
== Function 39, subfunction 2 - get pixel from the background image. =
======================================================================
Parameters:
* eax = 39 - function number
* ebx = 2 - subfunction number
* ecx = offset
Returned value:
* eax = 0x00RRGGBB - pixel color, if offset is valid
(less than 0x160000-16)
* eax = 2 otherwise
Remarks:
* Do not rely on returned value for invalid offsets, it may be
changed in future kernel versions.
* Offset for pixel with coordinates (x,y)
is calculated as (x+y*xsize)*3.
* There is a pair function to set pixel on the background image -
subfunction 2 of function 15.
======================================================================
== Function 39, subfunction 4 - get drawing mode for the background. =
======================================================================
Parameters:
* eax = 39 - function number
* ebx = 4 - subfunction number
Returned value:
* eax = 1 - tile
* eax = 2 - stretch
Remarks:
* There is a pair function to set drawing mode -
subfunction 4 of function 15.
======================================================================
=========== Function 40 - set the mask for expected events. ==========
======================================================================
The mask for expected events affects function working with events
10, 11, 23 - they notify only about events allowed by this mask.
Parameters:
* eax = 40 - function number
* ebx = mask: bit i corresponds to event i+1 (see list of events)
(set bit permits notice on event)
Returned value:
* function does not return value
Remarks:
* Default mask (7=111b) enables nofices about redraw,
keys and buttons. This is enough for many applications.
* Events prohibited in the mask are saved anyway, when come;
they are simply not informed with event functions.
* Event functions take into account the mask on moment of
function call, not on moment of event arrival.
======================================================================
==================== Function 41 - get IRQ owner. ====================
======================================================================
Parameters:
* eax = 41 - function number
* ebx = IRQ number, 0..15
Returned value:
* eax = owner PID
* eax = 0, if there is no owner
* eax = -1 for incorrect ebx
======================================================================
==================== Function 42 - read IRQ data. ====================
======================================================================
When an IRQ occurs, the system reads data from ports indicated
earlier by function 44 and writes this data to
internal buffer. This function reads out data from that buffer
bytewise.
Parameters:
* eax = 42 - function number
* ebx = IRQ number, 0..15
Returned value: (use value of ecx to distinguish)
* if the thread is not IRQ owner (or IRQ number is incorrect):
* ecx = 2
* if there is no data:
* eax = 0
* ecx = 1
* ebx destroyed
* if all is ok:
* eax = byte size of data, not yet read from buffer
* ecx = 0
* ebx = current byte
Remarks:
* Previously the thread must reserve indicated IRQ for itself
by function 45.
* The size of data buffer is 4000 bytes, on overflow
"fresh" data cease to be written in the buffer.
======================================================================
================ Function 43 - input/output to a port. ===============
======================================================================
------------------------ Output data to port -------------------------
Parameters:
* eax = 43 - function number
* bl = byte for output
* ecx = port number 0xnnnn (from 0 to 0xFFFF)
Returned value:
* eax = 0 - success
* eax = 1 - the thread has not reserved the selected port
------------------------ Input data from port ------------------------
Parameters:
* eax = 43 - function number
* ebx is ignored
* ecx = 0x8000nnnn, where nnnn = port number (from 0 to 0xFFFF)
Returned value:
* eax = 0 - success, thus ebx = entered byte
* eax = 1 - the thread has not reserved the selected port
Remarks:
* Previously the thread must reserve the selected port
for itself by function 46.
* Instead of call to this function it is better to use
processor instructions in/out - this is much
faster and a bit shorter and easier.
======================================================================
=========== Function 44 - define operations at IRQ arrival. ==========
======================================================================
At IRQ arrival the system can read the data from ports defined
by this function and write these data to internal buffer, whence
they can be read by ôóíêöèåé 42.
Parameters:
* eax = 44 - function number
* ebx = pointer to the array of structures each describing one port:
* +0: word: 0 means end of array, otherwise port number
* +2: byte: reserved (ignored)
* +3: byte: 1=read byte from this port, 2=read word
* ecx = IRQ number, 0..15
Returned value:
* eax = 0 - success
* eax = 1 - the thread is not owner of selected IRQ
Remarks:
* Previously the thread must reserve for itself selected IRQ
by function 45.
* First 16 ports are considered only.
* The current implementation considers incorrect value of field +3
as a signal to terminate IRQ processing.
======================================================================
=================== Function 45 - reserve/free IRQ. ==================
======================================================================
Parameters:
* eax = 45 - function number
* ebx = 0 - reserve, 1 = free
* ecx = IRQ number, 0..15
Returned value:
* eax = 0 - success
* eax = 1 - error (invalid IRQ number
or attempt to reserve not free IRQ
or to free IRQ, not reserved by this thread)
Remarks:
* IRQ reservation is required for functions 42 and 44.
* Only one thread can reserve the specific IRQ.
* IRQs, handled by the system itself, are reserved by the system
(thread 1) at booting.
* When a thread terminates, all reserved by it IRQs
are freed automatically.
======================================================================
====== Function 46 - reserve/free a group of input/output ports. =====
======================================================================
To work with reserved ports an application can access directly by
commands in/out (recommended way) and can use function 43
(not recommended way).
Parameters:
* eax = 46 - function number
* ebx = 0 - reserve, 1 - free
* ecx = start port number
* edx = end port number (inclusive)
Returned value:
* eax = 0 - success
* eax = 1 - error
Remarks:
* For ports reservation: an error occurs if and only if
one from the following condition satisfies:
* start port is more than end port;
* the selected range contains incorrect port number
(correct are from 0 to 0xFFFF);
* limit for the total number of reserved areas is exceeded
(maximum 255 are allowed);
* the selected range intersects with any of earlier reserved
* For ports free: an error is an attempt to free range,
that was not earlier reserved by this function
(with same ecx,edx).
* If an error occurs (for both cases) function performs no action.
* At booting the system reserves for itself ports 0..0xff, and if
COM-mouse is detected - additionally range of COM-ports
0x3f0..0x3ff and/or 0x2f0..0x2ff.
* When a thread terminates, all reserved by it ports
are freed automatically.
======================================================================
============= Function 47 - draw a number in the window. =============
======================================================================
Parameters:
* eax = 47 - function number
* ebx = parameters of conversion number to text:
* bl = 0 - ecx contains number
* bl = 1 - ecx contains pointer to dword-number
* bh = 0 - display in decimal number system
* bh = 1 - display in hexadecimal system
* bh = 2 - display in binary system
* áèòû 16-21 = how many digits to display
* áèòû 22-31 reserved and must be set to 0
* ecx = number (if bl=0) or pointer (if bl=1)
* edx = [coordinate on axis x]*65536 + [coordinate on axis y]
* esi = 0xN0RRGGBB, RRGGBB=color, N=font (0/1)
Returned value:
* function does not return value
Remarks:
* The given length must not exceed 60.
* The exactly given amount of digits is output. If number is small
and can be written by smaller amount of digits, it is supplemented
by leading zeroes; if the number is big and can not be written by
given amount of digits, extra digits are not drawn.
* Parameters of fonts are shown in the description of function 4
(text output).
======================================================================
========= Function 48, subfunction 0 - apply screen settings. ========
======================================================================
Parameters:
* eax = 48 - function number
* ebx = 0 - subfunction number
* ecx = 0 - reserved
Returned value:
* function does not return value
Remarks:
* Function redraws the screen after parameters change by
subfunctions 1 and 2.
* Function call without prior call to one of indicated subfunctions
is ignored.
* Function call with nonzero ecx is ignored.
======================================================================
=========== Function 48, subfunction 1 - set button style. ===========
======================================================================
Parameters:
* eax = 48 - function number
* ebx = 1 - subfunction number
* ecx = button style:
* 0 = flat
* 1 = 3d
Returned value:
* function does not return value
Remarks:
* After call to this function one should redraw the screen by
subfunction 0.
* Button style influences only to their draw of function 8.
======================================================================
====== Function 48, subfunction 2 - set standard window colors. ======
======================================================================
Parameters:
* eax = 48 - function number
* ebx = 2 - subfunction number
* ecx = pointer to the color table
* edx = size of the color table
(must be 40 bytes for future compatibility)
Format of the color table is shown in description of subfunction 3.
Returned value:
* function does not return value
Remarks:
* After call to this function one should redraw the screen by
subfunction 0.
* Table of standard colors influences only to applications,
which receive this table obviously (by subfunction 3)
and use it (specifying colors from it to drawing functions).
* Table of standard colors is included in skin and is installed
anew with skin installation (by subfunction 8).
* Color table can be viewed/changed interactively with
the application 'desktop'.
======================================================================
====== Function 48, subfunction 3 - get standard window colors. ======
======================================================================
Parameters:
* eax = 48 - function number
* ebx = 3 - subfunction number
* ecx = pointer to the buffer with size edx bytes,
where table will be written
* edx = size of color table
(must be 40 bytes for future compatibility)
Returned value:
* function does not return value
Format of the color table:
each item is dword-value for color 0x00RRGGBB
* +0: dword: frames - color of frame
* +4: dword: grab - color of header
* +8: dword: grab_button - color of button on header bar
* +12 = +0xC: dword: grab_button_text - color of text on button
on header bar
* +16 = +0x10: dword: grab_text - color of text on header
* +20 = +0x14: dword: work - color of working area
* +24 = +0x18: dword: work_button - color of button in working area
* +28 = +0x1C: dword: work_button_text - color of text on button
in working area
* +32 = +0x20: dword: work_text - color of text in working area
* +36 = +0x24: dword: work_graph - color of graphics in working area
Remarks:
* Structure of the color table is described in the standard
include file 'macros.inc' as 'system_colors'; for example,
it is possible to write:
sc system_colors ; variable declaration
... ; somewhere one must call
; this function with ecx=sc
mov ecx, [sc.work_button_text] ; read text color on
; buttin in working area
* A program itself desides to use or not to use color table.
For usage program must simply at calls to drawing functions select
color taken from the table.
* At change of the table of standard colors (by subfunction 2 with
the subsequent application of changes by subfunction 0 or
at skin set by subfunction 8) the system sends to all windows
redraw message (the event with code 1).
* Color table can be viewed/changed interactively with
the application 'desktop'.
======================================================================
============ Function 48, subfunction 4 - get skin height. ===========
======================================================================
Parameters:
* eax = 48 - function number
* ebx = 4 - subfunction number
Returned value:
* eax = skin height
Remarks:
* Skin height is defined as the height of a header
of skinned windows.
* See also general structure of window in the description
of function 0.
======================================================================
======== Function 48, subfunction 5 - get screen working area. =======
======================================================================
Parameters:
* eax = 48 - function number
* ebx = 5 - subfunction number
Returned value:
* eax = [left]*65536 + [right]
* ebx = [top]*65536 + [bottom]
Remarks:
* The screen working area defines position and coordinates of
a maximized window.
* The screen working area in view of normal work is all screen
without system panel (the application '@panel').
* (left,top) are coordinates of the left upper corner,
(right,bottom) are coordinates of the right lower one.
Thus the size of working area on x axis can be calculated by
formula right-left+1, on y axis - by formula bottom-right+1.
* See also function 14,
to get sizes of all screen.
* There is a pair function to set working area - subfunction 6.
======================================================================
======== Function 48, subfunction 6 - set screen working area. =======
======================================================================
Parameters:
* eax = 48 - function number
* ebx = 6 - subfunction number
* ecx = [left]*65536 + [right]
* edx = [top]*65536 + [bottom]
Returned value:
* function does not return value
Remarks:
* The screen working area defines position and coordinates of
a maximized window.
* This function is used only by the application '@panel',
which set working area to all screen without system panel.
* (left,top) are coordinates of the left upper corner,
(right,bottom) are coordinates of the right lower one.
Thus the size of working area on x axis can be calculated by
formula right-left+1, on y axis - by formula bottom-right+1.
* If 'left'>='right', x-coordinate of working area is not changed.
If 'left'<0, 'left' will not be set. If 'right' is greater than or
equal to screen width, 'right' will not be set.
Similarly on y axis.
* See also function 14,
to get sizes of all screen.
* There is a pair function to get working area - subfunction 5.
* This function redraws the screen automatically,
updating coordinates and sizes of maximized windows.
The system sends to all windows redraw message (the event 1).
======================================================================
=========== Function 48, subfunction 7 - get skin margins. ===========
======================================================================
Returns the area of a header of a skinned window, intended for
a text of a header.
Parameters:
* eax = 48 - function number
* ebx = 7 - subfunction number
Returned value:
* eax = [left]*65536 + [right]
* ebx = [top]*65536 + [bottom]
Remarks:
* An application decides itself to use or not to use this function.
* It is recommended to take into account returned value
of this function for choice of a place for drawing header text
(by function 4) or a substitute of header text
(at the discretion of an application).
======================================================================
============= Function 48, subfunction 8 - set used skin. ============
======================================================================
Parameters:
* eax = 48 - function number
* ebx = 8 - subfunction number
* ecx = pointer to a block for function 58, in
which the fields of intermediate buffer and file name are filled
Returned value:
* eax = 0 - success
* otherwise eax = file system error code; if file does not
contain valid skin, function returns error 3
(unknown file system).
Remarks:
* After successful skin loading the system sends to all windows
redraw message (the event 1).
* At booting the system reads skin from file 'default.skn'
on ramdisk.
* User can change the skin statically by creating hisself
'default.skn' or dynamically with the application 'desktop'.
======================================================================
=========== Function 49 - Advanced Power Management (APM). ===========
======================================================================
Parameters:
* eax = 49 - function number
* dx = number of the APM function
(analogue of ax in APM specification)
* bx, cx = parameters of the APM function
Returned value:
* 16-bit registers ax, bx, cx, dx, si, di and carry flag CF
are set according to the APM specification
* high halves of 32-bit registers eax, ebx, ecx,
edx, esi, edi are destroyed
Remarks:
* APM 1.2 specification is described in the document
"Advanced Power Management (APM) BIOS Specification"
(Revision 1.2), available at
http://www.microsoft.com/whdc/archive/amp_12.mspx;
besides it is included in famous Interrupt List by Ralf Brown
(http://www.pobox.com/~ralf/files.html,
ftp://ftp.cs.cmu.edu/afs/cs/user/ralf/pub/).
======================================================================
=================== Function 50 - set window shape. ==================
======================================================================
Normal windows have rectangular shape. This function can give to
a window any shape. The shape is given by a set of points inside
the base rectangle belonging to a window. Position and coordinates
of the base rectangle are set by function 0
and changed by function 67.
--------------------------- Set shape data ---------------------------
Parameters:
* eax = 50 - function number
* ebx = 0 - subfunction number
* ecx = pointer to shape data (array of bytes 0/1)
Returned value:
* function does not return value
-------------------------- Set shape scale ---------------------------
Parameters:
* eax = 50 - function number
* ebx = 1 - subfunction number
* ecx sets a scale: each byte of data defines
(2^scale)*(2^scale) pixels
Returned value:
* function does not return value
Remarks:
* Default scale is 0 (scale factor is 1). If in the shape data
one byte corresponds to one pixel, there is no necessity
to set scale.
* Let's designate xsize = window width (in pixels), ysize = height;
pay attention, that they are one pixel more than defined by
functions 0, 67.
* On definition of scale xsize and ysize must be divisible
on 2^scale.
* Byte of data on offset 'a' must be 0/1 and defines belonging
to a window of square with the side 2^scale (if scale=0,
this is one pixel) and coordinates of the left upper corner
(a mod (xsize shr scale), a div (xsize shr scale))
* Data size: (xsize shr scale)*(ysize shr scale).
* Data must be presented in the memory and not change
after set of shape.
* The system views the shape data at every window redraw by
function 0.
* The call of subfunction 0 with NULL pointer results in return
to the rectangular shape.
======================================================================
==================== Function 51 - create thread. ====================
======================================================================
Parameters:
* eax = 51 - function number
* ebx = 1 - unique subfunction
* ecx = address of thread entry point (starting eip)
* edx = pointer to thread stack (starting esp)
Returned value:
* eax = -1 - error (there is too many threads)
* otherwise eax = TID - thread identifier
</UL>
======================================================================
=== Function 52, subfunction 0 - get network driver configuration. ===
======================================================================
Parameters:
* eax = 52 - function number
* ebx = 0 - subfunction number
Returned value:
* eax = configuration dword
Remarks:
* Configuration dword can be set by subfunction 2.
* The kernel does not use this variable. The value of this
variable and working with it subfunctions 0 and 2 is represented
doubtful.
======================================================================
========= Function 52, subfunction 1 - get local IP-address. =========
======================================================================
Parameters:
* eax = 52 - function number
* ebx = 1 - subfunction number
Returned value:
* eax = IP-address (4 bytes)
Remarks:
* Local IP-address is set by subfunction 3.
======================================================================
=== Function 52, subfunction 2 - set network driver configuration. ===
======================================================================
Parameters:
* eax = 52 - function number
* ebx = 2 - subfunction number
* ecx = configuration dword; if low 7 bits derivate the number 3,
function [re-]initializes Ethernet-card, otherwise
Ethernet turns off
Returned value:
* if Ethernet-interface is not requested, function returns eax=2,
but this can be changed in future kernel versions
* if Ethernet-interface is requested, eax=0 means error
(absence of Ethernet-card), and nonzero value - success
Remarks:
* Configuration dword can be read by subfunction 0.
* The kernel does not use this variable. The value of this
variable, subfunction 0 and part of subfunction 2, which set it,
is represented doubtful.
======================================================================
========= Function 52, subfunction 3 - set local IP-address. =========
======================================================================
Parameters:
* eax = 52 - function number
* ebx = 3 - subfunction number
* ecx = IP-address (4 bytes)
Returned value:
* the current implementation returns eax=3, but this can be changed
in future versions
Remarks:
* Local IP-address can be get by subfunction 1.
======================================================================
= Function 52, subfunction 6 - add data to the stack of input queue. =
======================================================================
Parameters:
* eax = 52 - function number
* ebx = 6 - subfunction number
* edx = data size
* esi = data pointer
Returned value:
* eax = -1 - error
* eax = 0 - success
Remarks:
* This function is intended only for slow network drivers
(PPP, SLIP).
* Data size must not exceed 1500 bytes, though function
performs no checks on correctness.
======================================================================
Function 52, subfunction 8 - read data from the network output queue.
======================================================================
Parameters:
* eax = 52 - function number
* ebx = 8 - subfunction number
* esi = pointer to 1500-byte buffer
Returned value:
* eax = number of read bytes (in the current implementation
either 0 = no data or 1500)
* data was copied in buffer
Remarks:
* This function is intended only for slow network drivers
(PPP, SLIP).
======================================================================
============ Function 52, subfunction 9 - get gateway IP. ============
======================================================================
Parameters:
* eax = 52 - function number
* ebx = 9 - subfunction number
Returned value:
* eax = gateway IP (4 bytes)
======================================================================
=========== Function 52, subfunction 10 - get subnet mask. ===========
======================================================================
Parameters:
* eax = 52 - function number
* ebx = 10 - subfunction number
Returned value:
* eax = subnet mask
======================================================================
============ Function 52, subfunction 11 - set gateway IP. ===========
======================================================================
Parameters:
* eax = 52 - function number
* ebx = 11 - subfunction number
* ecx = gateway IP (4 bytes)
Returned value:
* the current implementation returns eax=11, but this can be changed
in future versions
======================================================================
=========== Function 52, subfunction 12 - set subnet mask. ===========
======================================================================
Parameters:
* eax = 52 - function number
* ebx = 12 - subfunction number
* ecx = subnet mask
Returned value:
* the current implementation returns eax=12, but this can be changed
in future versions
======================================================================
============== Function 52, subfunction 13 - get DNS IP. =============
======================================================================
Parameters:
* eax = 52 - function number
* ebx = 13 - subfunction number
Returned value:
* eax = DNS IP (4 bytes)
======================================================================
============== Function 52, subfunction 14 - set DNS IP. =============
======================================================================
Parameters:
* eax = 52 - function number
* ebx = 14 - subfunction number
* ecx = DNS IP (4 bytes)
Returned value:
* the current implementation returns eax=14, but this can be changed
in future versions
======================================================================
============ Function 53, subfunction 0 - open UDP-socket. ===========
======================================================================
Parameters:
* eax = 53 - function number
* ebx = 0 - subfunction number
* ecx = local port (only low word is taken into account)
* edx = remote port (only low word is taken into account)
* esi = remote IP
Returned value:
* eax = -1 = 0xFFFFFFFF - error; ebx destroyed
* eax = socket handle (some number which unambiguously identifies
socket and have sense only for the system) - success;
ebx destroyed
======================================================================
=========== Function 53, subfunction 1 - close UDP-socket. ===========
======================================================================
Parameters:
* eax = 53 - function number
* ebx = 1 - subfunction number
* ecx = socket handle
Returned value:
* eax = -1 - incorrect handle
* eax = 0 - success
* ebx destroyed
Remarks:
* The current implementation does not close automatically all
sockets of a thread at termination. In particular, one should not
kill a thread with many opened sockets - there will be an outflow
of resources.
* The current implementation does no checks on correctness
(function returns error only if thread tries to close not opened
socket with correct handle).
======================================================================
============== Function 53, subfunction 2 - poll socket. =============
======================================================================
Parameters:
* eax = 53 - function number
* ebx = 2 - subfunction number
* ecx = socket handle
Returned value:
* eax = number of read bytes
* ebx destroyed
Remarks:
* There is no checks for correctness.
======================================================================
========= Function 53, subfunction 3 - read byte from socket. ========
======================================================================
Parameters:
* eax = 53 - function number
* ebx = 3 - subfunction number
* ecx = socket handle
Returned value:
* if there is no read data: eax=0, bl=0,
other bytes of ebx are destroyed
* if there are read data: eax=number of rest bytes
(possibly 0), bl=read byte, other bytes of ebx are destroyed
Remarks:
* There is no checks for correctness.
======================================================================
========== Function 53, subfunction 4 - write to UDP-socket. =========
======================================================================
Parameters:
* eax = 53 - function number
* ebx = 4 - subfunction number
* ecx = socket handle
* edx = number of bytes to write
* esi = pointer to data to write
Returned value:
* eax = 0xffffffff - invalid handle
* eax = 0xffff - not enough memory
* eax = 0 - success
* ebx destroyed
Remarks:
* Check on validity of handle is minimal - only not very incorrect
not opened handles are eliminated.
* Number of bytes to write must not exceed 1500-28, though
the appropriate check is not made.
======================================================================
============ Function 53, subfunction 5 - open TCP-socket. ===========
======================================================================
Parameters:
* eax = 53 - function number
* ebx = 5 - subfunction number
* ecx = local port (only low word is taken into account)
* edx = remote port (only low word is taken into account)
* esi = remote IP
* edi = open mode: SOCKET_PASSIVE=0 or SOCKET_ACTIVE=1
Returned value:
* eax = -1 = 0xFFFFFFFF - error; ebx destroys
* eax = socket handle (some number which unambiguously identifies
socket and have sense only for the system) - success;
ebx destroyed
======================================================================
========= Function 53, subfunction 6 - get TCP-socket status. ========
======================================================================
Parameters:
* eax = 53 - function number
* ebx = 6 - subfunction number
* ecx = socket handle
Returned value:
* eax = socket status: one of
* TCB_LISTEN = 1
* TCB_SYN_SENT = 2
* TCB_SYN_RECEIVED = 3
* TCB_ESTABLISHED = 4
* TCB_FIN_WAIT_1 = 5
* TCB_FIN_WAIT_2 = 6
* TCB_CLOSE_WAIT = 7
* TCB_CLOSING = 8
* TCB_LAST_ASK = 9
* TCB_TIME_WAIT = 10
* TCB_CLOSED = 11
* ebx destroys
Remarks:
* There is no checks for correctness.
======================================================================
========== Function 53, subfunction 7 - write to TCP-socket. =========
======================================================================
Parameters:
* eax = 53 - function number
* ebx = 7 - subfunction number
* ecx = socket handle
* edx = number of bytes to write
* esi = pointer to data to write
Returned value:
* eax = 0xffffffff - error
* eax = 0xffff - not enough memory
* eax = 0 - success
* ebx destroyed
Remarks:
* Check on validity of handle is minimal - only not very incorrect
not opened handles are eliminated.
* Number of bytes to write must not exceed 1500-40, though
the appropriate check is not made.
======================================================================
=========== Function 53, subfunction 8 - close TCP-socket. ===========
======================================================================
Parameters:
* eax = 53 - function number
* ebx = 8 - subfunction number
* ecx = socket handle
Returned value:
* eax = -1 - invalid handle
* eax = 0xffff - not enough memory for socket close packet
* eax = 0 - success
* in many cases eax is destroyed (the result of function 'queue'
is returned) - probably this is bug, which will be corrected
* ebx destroyed
Remarks:
* The current implementation does not close automatically all
sockets of a thread at termination. In particular, one should not
kill a thread with many opened sockets - there will be an outflow
of resources.
* The current implementation does no checks on correctness
(function returns error only if thread tries to close not opened
socket with correct handle).
======================================================================
=== Function 53, subfunction 9 - check whether local port is free. ===
======================================================================
Parameters:
* eax = 53 - function number
* ebx = 9 - subfunction number
* ecx = local port number (low 16 bits are used only)
Returned value:
* eax = 0 - port is used
* eax = 1 - port is free
* ebx destroyed
======================================================================
= Function 53, subfunction 255 - debug information of network driver.
======================================================================
Parameters:
* eax = 53 - function number
* ebx = 255 - subfunction number
* ecx = type of requested information (see below)
Returned value:
* eax = requested information
* ebx destroyed
Possible values for ecx:
* 100: length of queue 0 (empty queue)
* 101: length of queue 1 (ip-out queue)
* 102: length of queue 2 (ip-in queue)
* 103: length of queue 3 (net1out queue)
* 200: number of items in the ARP table
* 201: size of the ARP table (in items) (20 for current version)
* 202: read item at edx of the ARP table to the temporary buffer,
whence 5 following types take information;
in this case eax is not defined
* 203: IP-address saved by type 202
* 204: high dword of MAC-address saved by type 202
* 205: low word of MAC-address saved by type 202
* 206: status word saved by type 202
* 207: ttl word saved by type 202
* 2: total number of received IP-packets
* 3: total number of transferred IP-packets
* 4: total number of dumped received packets
* 5: total number of received ARP-packets
* 6: status of packet driver, 0=inactive, nonzero=active
======================================================================
========== Function 55, subfunction 0 - load data for SB16. ==========
======================================================================
Parameters:
* eax = 55 - function number
* ebx = 0 - subfunction number
* ecx = pointer to data (is copied 64 kilobytes, is used as much as
set by subfunction 2)
Returned value:
* function does not return value
Remarks:
* Format and size of data are set by subfunction 2.
======================================================================
======== Function 55, subfunction 1 - begin play data on SB16. =======
======================================================================
Parameters:
* eax = 55 - function number
* ebx = 1 - subfunction number
Returned value:
* function does not return value
Remarks:
* Previously data must be loaded by subfunction 0 and
their format must be defined by subfunction 2.
* Function returns control, when playing of data began; after that
play goes independently from application (and does not use
processor time at all).
* Previously must be defined SB16 base port
(by subfunction 4 of function 21) and DMA channel
(by subfunction 10 of function 21).
======================================================================
======== Function 55, subfunction 2 - set format of SB16 data. =======
======================================================================
Parameters:
* eax = 55 - function number
* ebx = 2 - subfunction number
* ecx = 0 - set digit capacity
* edx = 1 - 8bit mono
* edx = 2 - 8bit stereo
* ecx = 1 - set data size
* edx = size in bytes
* ecx = 2 - set play frequency
* edx = frequency
Returned value:
* function does not return value
Remarks:
* When the system boots, it sets following default parameters:
digit capacity - 8bit mono, size - 64 Kb, frequency - 44100 Hz.
Nevertheless it is recommended to set necessary values obviously
as they could be reset by some application.
======================================================================
Function 55, subfunction 55 - begin to play data on built-in speaker.
======================================================================
Parameters:
* eax = 55 - function number
* ebx = 55 - subfunction number
* esi = pointer to data
Returned value:
* eax = 0 - success
* eax = 55 - error (speaker is off or busy)
Data is an array of items with variable length.
Format of each item is defined by first byte:
* 0 = end of data
* 1..0x80 = sets sound duration on 1/100 of second; sound note
is defined by immediate value of frequency
* following word (2 bytes) contains frequency divider;
frequency is defined as 1193180/divider
* 0x81 = invalid
* 0x82..0xFF = note is defined by octave and number:
* duration in 1/100 of second = (first byte)-0x81
* there is one more byte;
* (second byte)=0xFF - delay
* otherwise it looks like a*0x10+b, where b=number of the note in
an octave from 1 to 12, a=number of octave (beginning from 0)
Remarks:
* Speaker play can be disabled/enabled by
subfunction 8 of function 18.
* Function returns control, having informed the system
an information on request. Play itself goes independently from
the program.
* The data must be kept in the memory at least up to the end
of play.
======================================================================
=============== Function 56 - write file to hard disk. ===============
======================================================================
Parameters:
* eax = 56 - function number
* ebx = pointer to the file name
* ecx = size of data to write (in bytes)
* edx = pointer to data to write
* esi = pointer to path (ASCIIZ-string)
Returned value:
* eax = 0 - success, otherwise file system error code
Remarks:
* This function is obsolete; function 70 allows to fulfil the same
operations with the extended possibilities.
* This function assumes that during its call by one application
no other application works with hard disk.
* The path to file is ASCIIZ-string, which may be empty
(if the file is created in the root folder) or have the format
/d1/d2/.../dn, where all folder names must have the 8+3 format,
i.e. 8 characters of name and 3 characters of the extension
without separator, supplemented by blanks if necessary;
all letters must be capital.
* The file name must also have the format 8+3.
======================================================================
================ Function 58 - work with file system. ================
======================================================================
Parameters:
* eax = 58
* ebx = pointer to the information structure
Returned value:
* eax = 0 - success; otherwise file system error code
* some subfunctions return value in other registers too
General format of the information structure:
* +0: dword: subfunction number
* +4: dword: number of block
* +8: dword: size
* +12 = +0xC: dword: pointer to data
* +16 = +0x10: dword: pointer to a memory for system operations
(4096 bytes)
* +20 = +0x14: n db: ASCIIZ-string with the file name
Specifications - in documentation on the appropriate subfunction.
Filename is case-insensitive for latin letters, russian letters
must be capital.
Format of filename:
/base/number/dir1/dir2/.../dirn/file,
where /base/number identifies device, on which file is located:
one of
* /RD/1 = /RAMDISK/1 to access ramdisk
* /FD/1 = /FLOPPYDISK/1 to access first floppy drive,
/FD/2 = /FLOPPYDISK/2 to access second one
* /HD/x = /HARDDISK/x - obsolete variant of access to hard disk
(in this case base is defined by subfunction 7 of function 21),
x - partition number (beginning from 1)
* /HD0/x, /HD1/x, /HD2/x, /HD3/x to access accordingly to devices
IDE0 (Primary Master), IDE1 (Primary Slave),
IDE2 (Secondary Master), IDE3 (Secondary Slave);
x - partition number on the selected hard drive, varies from 1
to 255 (on each hard drive the indexing starts from 1)
Remarks:
* In the first two cases it is also possible to use FIRST
instead of 1, SECOND instead of 2, but it is not recommended
for convenience of transition to the future extensions.
* Limitation n<=39 is imposed.
* Names of folders and file dir1,...,dirn,file must have the
format 8.3: name no more than 8 characters, dot, extension no
more than 3 characters. Trailing spaces are ignored, no other
spaces is allowed. If name occupies equally 8 characters,
dot may be omitted (though it is not recommended to use this
feature for convenience of transition to the future extensions).
* This function does not support folders on ramdisk.
Examples:
* '/RAMDISK/FIRST/KERNEL.ASM',0
'/rd/1/kernel.asm',0
* '/HD0/1/kernel.asm',0
* '/hd0/1/menuet/pics/tanzania.bmp',0
Existing subfunctions:
* subfunction 0 - read file/folder
* subfunction 1 - rewrite file
* subfunction 2 - delete file/folder
* subfunction 3 - write to existing file
* subfunction 4 - make folder
* subfunction 5 - rename/move file/folder
* subfunction 8 - LBA-read from device
* subfunction 15 - get file system information
* subfunction 16 - start application
======================================================================
=========== Function 58, subfunction 0 - read file/folder. ===========
======================================================================
Parameters:
* eax = 58
* ebx = pointer to the information structure
Format of the information structure:
* +0: dword: 0 = subfunction number
* +4: dword: first block to read (beginning from 0)
* +8: dword: amount of blocks to read
* +12 = +0xC: dword: pointer to buffer for data
* +16 = +0x10: dword: pointer to buffer for system operations
(4096 bytes)
* +20 = +0x14: ASCIIZ-name of file, the rules of names forming are
given in the general description
Returned value:
* eax = 0 - success, otherwise file system error code
* ebx = file size (in bytes) or -1=0xffffffff, if file was not found
Remarks:
* Block size is 512 bytes.
* This function is obsolete, for reading files use subfunction 0
of function 70, for reading folders - subfunction 1 of
function 70.
* Function can read contents of a folder. Only FAT file system is
supported. The format of FAT-folder is described
in any FAT documentation.
* Size of a folder is determined by size of FAT clusters chain.
* If file was ended before last requested block was read,
the function will read as many as it can, and after that return
eax=6 (EOF).
* Function can read root folders /rd/1,/fd/x,/hd[n]/x, but
in the first two cases the current implementation does not follow
to the declared rules:
for /rd/1:
* if one want to read 0 blocks, function considers,
that he requested 1;
* if one requests more than 14 blocks or starting block is
not less than 14, function returns eax=5 (not found) è ebx=-1;
* size of ramdisk root folder is 14 blocks,
0x1C00=7168 áàéò; but function returns ebx=0
(except of the case of previous item);
* strangely enough, it is possible to read 14th block (which
generally contains a garbage - I remind, the indexing begins
from 0);
* if some block with the number not less than 14 was requested,
function returns eax=6(EOF); otherwise eax=0.
For /fd/x:
* if the start block is not less than 14, function returns
eax=5 (not found) and ebx=0;
* note that format of FAT12 allows floppies with the root size
more or less than 14 blocks;
* check for length is not performed;
* if data was successful read, function returns
eax=0,ebx=0; otherwise eax=10 (access denied), ebx=-1.
* The function handles reading of special folders /,/rd,/fd,/hd[n];
but the result does not correspond to expected (on operations with
normal files/folders), does not follow the declared rules,
may be changed in future versions of the kernel and consequently
is not described. To obtain the information about the equipment
use subfunction 11 of function 18 or
read corresponding folder with subfunction 1 of function 70.
======================================================================
============= Function 58, subfunction 1 - rewrite file. =============
======================================================================
If the file does not exist, it is created.
If the file exists, it is rewritten.
Parameters:
* eax = 58 - function number
* ebx = pointer to the information structure
Format of the information structure:
* +0: dword: 1 = subfunction number
* +4: dword: ignored (set to 0)
* +8: dword: number of bytes to write
* +12 = +0xC: dword: pointer to data to write
* +16 = +0x10: dword: pointer to buffer for system operations
(4096 bytes)
* +20 = +0x14: ASCIIZ-name of file, the rules of names forming are
given in the general description
Returned value:
* eax = 0 - success, otherwise file system error code
* ebx destroyed
Remarks:
* This function is obsolete, use subfunction 2 of function 70.
======================================================================
========== Function 58, subfunction 2 - delete file/folder. ==========
======================================================================
Parameters:
* eax = 58 - function number
* ebx = pointer to the information structure
Format of the information structure:
* +0: dword: 2 = subfunction number
* +4: dword: ignored
* +8: dword: ignored
* +12 = +0xC: dword: ignored
* +16 = +0x10: dword: pointer to buffer for system operations
(4096 bytes)
* +20 = +0x14: ASCIIZ-name of file, the rules of names forming are
given in the general description
Returned value:
* eax = 0 - success, otherwise file system error code
* ebx destroyed
Remarks:
* By operations with a floppy one should not delete not empty
folder. The code working with hard disk deletes not empty folders
correctly (i.e. recursively with all files and nested folders).
Function 58 does not support folders on ramdisk.
======================================================================
==== Function 58, subfunction 3 - write data to the existing file. ===
======================================================================
Parameters:
* eax = 58 - function number
* ebx = pointer to the information structure
Format of the information structure:
* +0: dword: 3 = subfunction number
* +4: dword: starting position in the file; -1 = append to the end
* +8: dword: number of bytes to write
* +12 = +0xC: dword: pointer to data to write
* +16 = +0x10: dword: pointer to buffer for system operations
(4096 bytes)
* +20 = +0x14: ASCIIZ-name of file, the rules of names forming are
given in the general description
Returned value:
* eax = 0 - success, otherwise file system error code
* ebx destroyed
Remarks:
* Ramdisk and floppies do not support this function, it is only
for hard disks.
* File must already exist (otherwise function returns 5, not found).
To create files use subfunction 1.
* If the starting position is greater than file size, the function
returns eax=6(EOF). If the end position is greater than file size,
file is extended.
* The code of write processing for hard disk interpretes zero
value of the field +8 as the instruction to truncate the file to
the size, given in the field +4. However the code of processing
58th function blocks this possibility for applications by
immediate return (with eax=0) in the case of zero size.
======================================================================
============== Function 58, subfunction 4 - make folder. =============
======================================================================
Parameters:
* eax = 58 - function number
* ebx = pointer to the information structure
Format of the information structure:
* +0: dword: 4 = subfunction number
* +4: dword: ignored
* +8: dword: ignored
* +12 = +0xC: dword: ignored
* +16 = +0x10: dword: pointer to buffer for system operations
(4096 bytes)
* +20 = +0x14: ASCIIZ-name of file, the rules of names forming are
given in the general description
Returned value:
* eax = 0 - success, otherwise file system error code
* ebx destroyed
Remarks:
* Ramdisk and floppies do not support this function, it is only
for hard disks.
======================================================================
======== Function 58, subfunction 5 - rename/move file/folder. =======
======================================================================
Parameters:
* eax = 58 - function number
* ebx = pointer to the information structure
Format of the information structure:
* +0: dword: 5 = subfunction number
* +4: dword: ignored
* +8: dword: ignored
* +12 = +0xC: dword: ignored
* +16 = +0x10: dword: pointer to buffer for system operations
(4096 bytes)
* +20 = +0x14: ASCIIZ-name of file, the rules of names forming are
given in the general description
* +20+n: (at once after terminating null character) new
ASCIIZ-name, must start from /hd/1, that is interpreted as
the hard disk, indicated in the first name
(moving from one disk to another is not supported)
Returned value:
* eax = 0 - success, otherwise file system error code
* ebx destroyed
Remarks:
* Ramdisk and floppies do not support this function, it is only
for hard disks.
* If the new ASCIIZ-name is strongly incorrect, i.e. does not start
from /hd/1, /hd/first, /harddisk/1, /harddisk/first or after this
space or null character follows, function returns, strangely
enough, error code 4. It is the only function which returns
this code.
======================================================================
========= Function 58, subfunction 8 - LBA-read from device. =========
======================================================================
Parameters:
* eax = 58 - function number
* ebx = pointer to the information structure
Format of the information structure:
* +0: dword: 8 = subfunction number
* +4: dword: number of block to read (beginning from 0)
* +8: dword: ignored (set to 1)
* +12 = +0xC: dword: pointer to buffer for data (512 bytes)
* +16 = +0x10: dword: pointer to buffer for system operations
(4096 bytes)
* +20 = +0x14: ASCIIZ-name of device: case-insensitive, one of
/rd/1 = /RamDisk/1, /hd/n = /HardDisk/n,
1<=n<=4 - number of device: 1=IDE0, ..., 4=IDE3.
Instead of digits it is allowed, though not recommended for
convenience of transition to future extensions, to use
'first','second','third','fourth'.
Returned value:
* for device name /hd/xxx, where xxx is not in the list above:
* eax = ebx = 1
* for invalid device name (except for the previous case):
* eax = 5
* ebx does not change
* if LBA-access is disabled by subfunction 11 of function 21:
* eax = 2
* ebx destroyed
* for ramdisk: attempt to read block outside ramdisk
(18*2*80 blocks) results in
* eax = 3
* ebx = 0
* for successful read:
* eax = ebx = 0
Remarks:
* Block size is 512 bytes; function reads one block.
* Do not depend on returned value, it can be changed
in future versions.
* Function requires that LBA-access to devices is enabled by
subfunction 11 of function 21. To check this one can use
subfunction 11 of function 26.
* LBA-read of floppy is not supported.
* Function reads data on physical hard drive; if for any reason
data of the concrete partition are required, application must
define starting sector of this partition (either directly
through MBR, or from the full structure returned by
ïîäôóíêöèåé 11 ôóíêöèè 18).
* Function does not check error code of hard disk, so request of
nonexisting sector reads something (most probably it will be
zeroes, but this is defined by device) and this is considered
as success (eax=0).
======================================================================
==== Function 58, subfunction 15 - get information on file system. ===
======================================================================
Parameters:
* eax = 58 - function number
* ebx = pointer to the information structure
Format of the information structure:
* +0: dword: 15 = subfunction number
* +4: dword: ignored
* +8: dword: ignored
* +12 = +0xC: dword: ignored
* +16 = +0x10: dword: ignored
* +20 = +0x14: (only second character is checked)
/rd=/RAMDISK or /hd=/HARDDISK
Returned value:
* if the second character does not belong to set {'r','R','h','H'}:
* eax = 3
* ebx = ecx = dword [fileinfo] = 0
* for ramdisk:
* eax = 0 (success)
* ebx = total number of clusters = 2847
* ecx = number of free clusters
* dword [fileinfo] = cluster size = 512
* for hard disk: base and partition are defined by subfunctions
7 and 8 of function 21:
* eax = 0 (success)
* ebx = total number of clusters
* ecx = number of free clusters
* dword [fileinfo] = cluster size (in bytes)
Remarks:
* Be not surprised to strange layout of 4th returned parameter
- when this code was writing, at system calls application got
only registers eax,ebx,ecx (from pushad-structure transmitted
as argument to the system function). Now it is corrected, so,
probably, it is meaningful to return cluster size in edx, while
this function is not used yet.
* There exists also subfunction 11 of function 18,
which returns information on file system. From the full table
of disk subsystem it is possible to deduce cluster size (there
it is stored in sectors) and total number of clusters
for hard disks.
======================================================================
========== Function 58, subfunction 16 - start application. ==========
======================================================================
Parameters:
* eax = 58 - function number
* ebx = pointer to the information structure
Format of the information structure:
* +0: dword: 16 = subfunction number
* +4: dword: flags:
* bit 0: start the process as debugged
* other bits are reserved and must be cleared
* +8: dword: 0 or pointer to ASCIIZ-string with parameters
* +12 = +0xC: dword: ignored
* +16 = +0x10: dword: pointer to buffer for system operations
(4096 bytes)
* +20 = +0x14: ASCIIZ-name of file, the rules of names forming are
given in the general description
Returned value:
* eax > 0 - the program is loaded, eax contains PID
* eax < 0 - an error has occured, -eax contains
file system error code
Remarks:
* This function is obsolete, use subfunction 7 of function 70.
* Command line must be terminated by character with code 0
(ASCIIZ-string); function takes into account either all characters
up to terminating null inclusively or the first 256 charachters
depending on what is less.
* If the process is started as debugged, it is created in
the suspended state; to run use subfunction 5 of function 69.
======================================================================
=============== Function 59 - trace last system calls. ===============
======================================================================
Gets data on all system calls of all processes.
Parameters:
* eax = 59 - function number
* ebx = 0 - unique subfunction
* ecx = pointer to the buffer
* edx = size of the buffer
Returned value:
* eax = total number of system calls made from system boot
(modulo 2^32)
* ebx = 0
Format of information on one call: (size = 0x40 = 64 bytes)
* +0: dword: PID of process/thread
* +4: 7*dword: garbage
* +32 = +0x20: dword: value of edi at the call
* +36 = +0x24: dword: esi
* +40 = +0x28: dword: ebp
* +44 = +0x2C: dword: stack pointer of the kernel handler
* +48 = +0x30: dword: ebx
* +52 = +0x34: dword: edx
* +56 = +0x38: dword: ecx
* +60 = +0x3C: dword: eax (=number of system function)
Remarks:
* The function is used only in the application 'systrace'.
It is rather difficult to imagine a situation, in which
this application or this function are really useful;
and all system calls for support of this function are a little
decelerated (though not strongly)...
* So there is a proposition to delete from the kernel
support of this function, together with application 'systrace'.
* The information on system calls saves in the system
ring buffer with 0x10 entries.
This function simply copies the given size of data
from this buffer to the given address.
* One can determine, which entry in the buffer corresponds to
last system call, by value of eax, namely, it is the entry
(eax and 0xF) (at offset (eax and 0xF)*0x40).
* In the current implementation there can be the seldom
meeting problems of unsynchronization, when the information
on some calls becomes outdated.
* Under the system buffer one page, 4Kb, is allocated.
Size of an entry = 64 bytes. Why only 16 entries are used,
is not clearly.
* The value of esp at the moment of system call cannot
be determined by this function.
* The current implementation does not check edx for correctness.
======================================================================
========== Function 60 - Inter Process Communication (IPC). ==========
======================================================================
IPC is used for message dispatching from one process/thread to
another. Previously it is necessary to agree how to interpret
the concrete message.
----------- Subfunction 1 - set the area for IPC receiving -----------
Is called by process-receiver.
Parameters:
* eax = 60 - function number
* ebx = 1 - subfunction number
* ecx = pointer to the buffer
* edx = size of the buffer
Returned value:
* eax = 0 - always success
Format of IPC-buffer:
* +0: dword: if nonzero, buffer is considered locked;
lock/unlock the buffer, when you work with it and need that
buffer data are not changed from outside (no new messages)
* +4: dword: occupied place in the buffer (in bytes)
* +8: first message
* +8+n: second message
* ...
Format of a message:
* +0: dword: PID of sender
* +4: dword: message length (not including this header)
* +8: n*byte: message data
------------------ Subfunction 2 - send IPC message ------------------
Is called by process-sender.
Parameters:
* eax = 60 - function number
* ebx = 2 - subfunction number
* ecx = PID of receiver
* edx = pointer to the message data
* esi = message length (in bytes)
Returned value:
* eax = 0 - success
* eax = 1 - the receiver has not defined buffer for IPC messages
(can be, still have no time,
and can be, this is not right process)
* eax = 2 - the receiver has blocked IPC-buffer; try to wait a bit
* eax = 3 - overflow of IPC-buffer of the receiver
* eax = 4 - process/thread with such PID does not exist
Remarks:
* Immediately after writing of IPC-message to the buffer the system
sends to the receiver the event with code 7 (see event codes).
======================================================================
==== Function 61 - get parameters for the direct graphics access. ====
======================================================================
The data of the graphics screen (the memory area which displays
screen contents) are accessible to a program directly, without
any system calls, through the selector gs:
mov eax, [gs:0]
places in eax the first dword of the buffer, which contains
information on color of the left upper point (and, possibly, colors
of several following).
mov [gs:0], eax
by work in VESA modes with LFB sets color of the left upper point
(and, possibly, colors of several following).
To interpret the data of graphics screen program needs to know
some parameters, returning by this function.
Remarks:
* Graphics parameters changes very seldom at work,
namely, only in cases, when user works with the application VRR.
* At videomode change the system redraws all windows (event
with code 1) and redraws the background (event 5).
Same events occur in other cases too, which meet much more often,
than videomode change.
* By operation in videomodes with LFB the selector gs points to
LFB itself, so reading/writing on gs result directly in
change of screen contents. By operation in videomodes without
LFB gs points to some data area in the kernel, and all functions
of screen output fulfil honesty double operation on writing
directly to the screen and writing to this buffer. In result
at reading contents of this buffer the results correspond to
screen contents (with, generally speaking, large color
resolution), and writing is ignored.
One exception is the mode 320*200, for which main loop of the
system thread updates the screen according to mouse movements.
------------------------- Screen resolution --------------------------
Parameters:
* eax = 61 - function number
* ebx = 1 - subfunction number
Returned value:
* eax = [resolution on x axis]*65536 + [resolution on y axis]
Remarks:
* One can use function 14 paying attention that
it returns sizes on 1 pixel less. It is fully equivalent way.
---------------------- Number of bits per pixel ----------------------
Parameters:
* eax = 61 - function number
* ebx = 2 - subfunction number
Returned value:
* eax = number of bits per pixel (24 or 32)
-------------------- Number of bytes per scanline --------------------
Parameters:
* eax = 61 - function number
* ebx = 3 - subfunction number
Returned value:
* eax = number of bytes occupied by one scanline
(horizontal line on the screen)
======================================================================
===== Function 62, subfunction 0 - get version of PCI-interface. =====
======================================================================
Parameters:
* eax = 62 - function number
* bl = 0 - subfunction number
Returned value:
* eax = -1 - PCI access is disabled; otherwise
* ah.al = version of PCI-interface (ah=version, al=subversion)
* high word of eax is zeroed
Remarks:
* Previously low-level access to PCI for applications must be
enabled by subfunction 12 of function 21.
* If PCI BIOS is not supported, the value of ax is undefined.
======================================================================
==== Function 62, subfunction 1 - get number of the last PCI-bus. ====
======================================================================
Parameters:
* eax = 62 - function number
* bl = 1 - subfunction number
Returned value:
* eax = -1 - access to PCI is disabled; otherwise
* al = number of the last PCI-bus; other bytes of eax are destroyed
Remarks:
* Previously low-level access to PCI for applications must be
enabled by subfunction 12 of function 21.
* If PCI BIOS is not supported, the value of ax is undefined.
======================================================================
===================== Function 62, subfunction 2 =====================
===== Get mechanism of addressing to the PCI configuration space. ====
======================================================================
Parameters:
* eax = 62 - function number
* bl = 2 - subfunction number
Returned value:
* eax = -1 - access to PCI is disabled; otherwise
* al = mechanism (1 or 2); other bytes of eax are destroyed
Remarks:
* Previously low-level access to PCI for applications must be
enabled by subfunction 12 of function 21.
* Addressing mechanism is selected depending on
equipment characteristics.
* Subfunctions of read and write work automatically
with the selected mechanism.
======================================================================
======== Function 62, subfunctions 4,5,6 - read PCI-register. ========
======================================================================
Parameters:
* eax = 62 - function number
* bl = 4 - read byte
* bl = 5 - read word
* bl = 6 - read dword
* bh = number of PCI-bus
* ch = dddddfff, where ddddd = number of the device on the bus,
fff = function number of device
* cl = number of register (must be even for bl=5,
divisible by 4 for bl=6)
Returned value:
* eax = -1 - error (access to PCI is disabled or parameters
are not supported); otherwise
* al/ax/eax (depending on requested size) contains the data;
the other part of register eax is destroyed
Remarks:
* Previously low-level access to PCI for applications must be
enabled by subfunction 12 of function 21.
* Access mechanism 2 supports only 16 devices on a bus and ignores
function number. To get access mechanism use subfunction 2.
* Some registers are standard and exist for all devices, some are
defined by the concrete device. The list of registers of the
first type can be found e.g. in famous
Interrupt List by Ralf Brown
(http://www.pobox.com/~ralf/files.html,
ftp://ftp.cs.cmu.edu/afs/cs/user/ralf/pub/);
registers of the second type must be listed
in the device documentation.
======================================================================
====== Function 62, subfunctions 8,9,10 - write to PCI-register. =====
======================================================================
Parameters:
* eax = 62 - function number
* bl = 8 - write byte
* bl = 9 - write word
* bl = 10 - write dword
* bh = number of PCI-bus
* ch = dddddfff, where ddddd = number of the device on the bus,
fff = function number of device
* cl = number of register (must be even for bl=9,
divisible by 4 for bl=10)
* dl/dx/edx (depending on requested size) contatins
the data to write
Returned value:
* eax = -1 - error (access to PCI is disabled or parameters
are not supported)
* eax = 0 - success
Remarks:
* Previously low-level access to PCI for applications must be
enabled by subfunction 12 of function 21.
* Access mechanism 2 supports only 16 devices on a bus and ignores
function number. To get access mechanism use subfunction 2.
* Some registers are standard and exist for all devices, some are
defined by the concrete device. The list of registers of the
first type can be found e.g. in famous Interrupt List by
Ralf Brown; registers of the second type must be listed
in the device documentation.
======================================================================
============== Function 63 - work with the debug board. ==============
======================================================================
The debug board is the global system buffer (with the size
512 bytes), to which any program can write (generally speaking,
arbitrary) data and from which other program can read these data.
By the agreement written data are text strings interpreted as
debug messages on a course of program execution. The kernel in
some situations also writes to the debug board information on
execution of some functions; by the agreement kernel messages
begins from the prefix "K : ".
For view of the debug board the application 'board' was created,
which reads data from the buffer and displays them in its window.
'board' interpretes the sequence of codes 13,10 as newline.
A character with null code in an end of line is not necessary,
but also does not prevent.
Because debugger has been written, the value of the debug board
has decreased, as debugger allows to inspect completely a course of
program execution without any efforts from the direction of program
itself. Nevertheless in some cases the debug board is still useful.
----------------------------- Write byte -----------------------------
Parameters:
* eax = 63 - function number
* ebx = 1 - subfunction number
* cl = data byte
Returned value:
* function does not return value
Remarks:
* Byte is written to the buffer. Buffer size is 512 bytes.
At buffer overflow all obtained data are lost.
* For output to the debug board of more complicated objects
(strings, numbers) it is enough to call this function in cycle.
It is possible not to write the appropriate code manually and use
file 'debug.inc', which is included into the distributive.
----------------------------- Read byte ------------------------------
Takes away byte from the buffer.
Parameters:
* eax = 63 - function number
* ebx = 2 - subfunction number
Returned value:
* eax = ebx = 0 - the buffer is empty
* eax = byte, ebx = 1 - byte was successfully read
======================================================================
============== Function 64 - resize application memory. ==============
======================================================================
Parameters:
* eax = 64 - function number
* ebx = 1 - unique subfunction
* ecx = new memory size
Returned value:
* eax = 0 - success
* eax = 1 - not enough memory
Remarks:
* At the moment this function is a sole resource for dynamic
allocation/free of application memory.
======================================================================
================== Function 66 - work with keyboard. =================
======================================================================
The input mode influences results of reading keys by function 2.
When a program loads, ASCII input mode is set for it.
-------------- Subfunction 1 - set keyboard input mode. --------------
Parameters:
* eax = 66 - function number
* ebx = 1 - subfunction number
* ecx = mode:
* 0 = normal (ASCII-characters)
* 1 = scancodes
Returned value:
* function does not return value
-------------- Subfunction 2 - get keyboard input mode. --------------
Parameters:
* eax = 66 - function number
* ebx = 2 - subfunction number
Returned value:
* eax = current mode
------------ Subfunction 3 - get status of control keys. -------------
Parameters:
* eax = 66 - function number
* ebx = 3 - subfunction number
Returned value:
* eax = bit mask:
* bit 0 (mask 1): left Shift is pressed
* bit 1 (mask 2): right Shift is pressed
* bit 2 (mask 4): left Ctrl is pressed
* bit 3 (mask 8): right Ctrl is pressed
* bit 4 (mask 0x10): left Alt is pressed
* bit 5 (mask 0x20): right Alt is pressed
* bit 6 (mask 0x40): CapsLock is on
* bit 7 (mask 0x80): NumLock is on
* bit 8 (mask 0x100): ScrollLock is on
* other bits are cleared
-------------- Subfunction 4 - set system-wide hotkey. ---------------
When hotkey is pressed, the system notifies only those applications,
which have installed it; the active application (which receives
all normal input) does not receive such keys.
The notification consists in sending event with the code 2.
Reading hotkey is the same as reading normal key - by function 2.
Parameters:
* eax = 66 - function number
* ebx = 4 - subfunction number
* cl determines key scancode;
use cl=0 to give combinations such as Ctrl+Shift
* edx = 0xXYZ determines possible states of control keys:
* Z (low 4 bits) determines state of LShift and RShift:
* 0 = no key must be pressed;
* 1 = exactly one key must be pressed;
* 2 = both keys must be pressed;
* 3 = must be pressed LShift, but not RShift;
* 4 = must be pressed RShift, but not LShift
* Y - similar for LCtrl and RCtrl;
* X - similar for LAlt and RAlt
Returned value:
* eax=0 - success
* eax=1 - too mant hotkeys (maximum 256 are allowed)
Remarks:
* Hotkey can work either at pressing or at release. Release
scancode of a key is more on 128 than pressing scancode
(i.e. high bit is set).
* Several applications can set the same combination;
all such applications will be informed on pressing
such combination.
-------------- Subfunction 5 - delete installed hotkey. --------------
Parameters:
* eax = 66 - function number
* ebx = 5 - subfunction number
* cl = scancode of key and edx = 0xXYZ the same as in subfunction 4
Returned value:
* eax = 0 - success
* eax = 1 - there is no such hotkey
Remarks:
* When a process/thread terminates, all hotkey installed by it are
deleted.
* The call to this subfunction does not affect other applications.
If other application has defined the same combination, it will
still receive notices.
======================================================================
========= Function 67 - change position/sizes of the window. =========
======================================================================
Parameters:
* eax = 67 - function number
* ebx = new x-coordinate of the window
* ecx = new y-coordinate of the window
* edx = new x-size of the window
* esi = new y-size of the window
Returned value:
* function does not return value
Remarks:
* The value -1 for a parameter means "do not change"; e.g. to move
the window without resizing it is possible to specify edx=esi=-1.
* Previously the window must be defined by function 0.
It sets initial coordinates and sizes of the window.
* Sizes of the window are understood in sense of function 0,
that is one pixel less than real sizes.
* The function call for maximized windows is simply ignored.
* For windows of appropriate styles position and/or sizes can be
changed by user; current position and sizes can be obtained by
call to function 9.
* The function sends to the window redraw event (with the code 1).
======================================================================
====== Function 68, subfunction 0 - get the task switch counter. =====
======================================================================
Parameters:
* eax = 68 - function number
* ebx = 0 - subfunction number
Returned value:
* eax = number of task switches from the system booting
(modulo 2^32)
======================================================================
======= Function 68, subfunction 1 - switch to the next thread. ======
======================================================================
The function completes the current time slice allocated to the
thread and switches to the next. (Which thread in which process
will be next, is unpredictable). Later, when execution queue
will reach the current thread, execution will be continued.
Parameters:
* eax = 68 - function number
* ebx = 1 - subfunction number
Returned value:
* function does not return value
======================================================================
============= Function 68, subfunction 2 - cache + rdpmc. ============
======================================================================
Parameters:
* eax = 68 - function number
* ebx = 2 - subfunction number
* ecx = required action:
* ecx = 0 - enable instruction 'rdpmc'
(ReaD Performance-Monitoring Counters) for applications
* ecx = 1 - find out whether cache is disabled/enabled
* ecx = 2 - enable cache
* ecx = 3 - disable cache
Returned value:
* for ecx=0:
* eax = the value of cr4
* for ecx=1:
* eax = (cr0 and 0x60000000):
* eax = 0 - cache is on
* eax <> 0 - cache is off
* for ecx=2 and ecx=3:
* function does not return value
======================================================================
=========== Function 68, subfunction 3 - read MSR-register. ==========
======================================================================
MSR = Model Specific Register; the complete list of MSR-registers
of a processor is included to the documentation on it (for example,
IA-32 Intel Architecture Software Developer's Manual,
Volume 3, Appendix B); each processor family has its own subset
of the MSR-registers.
Parameters:
* eax = 68 - function number
* ebx = 3 - subfunction number
* ecx is ignored
* edx = MSR address
Returned value:
* ebx:eax = high:low dword of the result
Remarks:
* If ecx contains nonexistent or not implemented for this processor
MSR, processor will generate an exception in the kernel, which
will kill the thread.
* Previously it is necessary to check, whether MSRs are supported
as a whole, with the instruction 'cpuid'. Otherwise processor
will generate other exception in the kernel, which will anyway
kill the thread.
======================================================================
========= Function 68, subfunction 4 - write to MSR-register. ========
======================================================================
MSR = Model Specific Register; the complete list of MSR-registers
of a processor is included to the documentation on it (for example,
IA-32 Intel Architecture Software Developer's Manual,
Volume 3, Appendix B); each processor family has its own subset
of the MSR-registers.
Parameters:
* eax = 68 - function number
* ebx = 4 - subfunction number
* ecx is ignored
* edx = MSR address
* esi:edi = high:low dword
Returned value:
* ebx:eax = copy of esi:edi
Çàìå÷àíèÿ:
* If ecx contains nonexistent or not implemented for this processor
MSR, processor will generate an exception in the kernel, which
will kill the thread.
* Previously it is necessary to check, whether MSRs are supported
as a whole, with the instruction 'cpuid'. Otherwise processor
will generate other exception in the kernel, which will anyway
kill the thread.
======================================================================
======= Function 68, subfunction 5 - allocate physical memory. =======
======================================================================
Parameters:
* eax = 68 - function number
* ebx = 5 - subfunction number
* ecx = size (in bytes)
Returned value:
* eax = physical address of allocated memory
Remarks:
* Normal applications must not use this function, it is intended
for the case, when for some device it is required to place
data to the known physical address. (In effect, this function
was developed for AC97WAV.)
* The number of blocks of physical memory is limited (by constant
24, and this constant includes some blocks for kernel).
* To free a memory allocated by such way use
subfunction 6, to copy data there and back
use subfunctions 7 and 8.
======================================================================
========= Function 68, subfunction 6 - free physical memory. =========
======================================================================
Parameters:
* eax = 68 - function number
* ebx = 6 - subfunction number
* ecx = physical address of memory
Returned value:
* function does not return value
Remarks:
* Normal applications must not use this function, it is intended
for the case, when for some device it is required to place
data to the known physical address. (In effect, this function
was developed for AC97WAV.)
* The memory must be previously allocated by subfunction 5.
======================================================================
===== Function 68, subfunction 7 - write data to physical memory. ====
======================================================================
Parameters:
* eax = 68 - function number
* ebx = 7 - subfunction number
* ecx = physical address
* edx = pointer to the data (in the application)
* esi = size of the data (in bytes)
Returned value:
* function does not return value
Remarks:
* Normal applications must not use this function, it is intended
for the case, when for some device it is required to place
data to the known physical address. (In effect, this function
was developed for AC97WAV.)
* The range of physical addresses should lie inside of previously
allocated by subfunction 5 block of physical memory.
* There is no check for correctness.
======================================================================
==== Function 68, subfunction 8 - read data from physical memory. ====
======================================================================
Parameters:
* eax = 68 - function number
* ebx = 8 - subfunction number
* ecx = physical address
* edx = pointer to buffer for data (in application)
* esi = size of data (in bytes)
Returned value:
* function does not return value
Remarks:
* Normal applications must not use this function, it is intended
for the case, when for some device it is required to place
data to the known physical address. (In effect, this function
was developed for AC97WAV.)
* The range of physical addresses should lie inside of previously
allocated by subfunction 5 block of physical memory.
* There is no check for correctness.
======================================================================
====================== Fucntion 69 - debugging. ======================
======================================================================
A process can load other process as debugged by set of corresponding
bit by call to subfunction 16 of function 58
or subfunction 7 of function 70.
A process can have only one debugger; one process can debug some
others. The system notifies debugger on events occuring with
debugged process. Messages are written to the buffer defined by
subfunction 0.
Format of a message:
* +0: dword: message code
* +4: dword: PID of debugged process
* +8: there can be additional data depending on message code
Message codes:
* 1 = exception
* in addition dword-number of the exception is given
* process is suspended
* 2 = process has terminated
* comes at any termination: both through the system function -1,
and at "murder" by any other process (including debugger itself)
* 3 = debug exception int 1 = #DB
* in addition dword-image of the register DR6 is given:
* bits 0-3: condition of the corresponding breakpoint (set by
subfunction 9) is satisfied
* áèò 14: exception has occured because of the trace mode
(flag TF is set TF)
* process is suspended
When debugger terminates, all debugged processes are killed.
If debugger does not want this, it must previously detach by
subfunction 3.
All subfunctions are applicable only to processes/threads started
from the current by function 58 or 70 with set debugging flag.
Debugging of multithreaded programs is not supported yet.
The full list of subfunctions:
* subfunction 0 - define data area for debug messages
* subfunction 1 - get contents of registers of debugged thread
* subfunction 2 - set contents of registers of debugged thread
* subfunction 3 - detach from debugged process
* subfunction 4 - suspend debugged thread
* subfunction 5 - resume debugged thread
* subfunction 6 - read from the memory of debugged process
* subfunction 7 - write to the memory of debugged process
* subfunction 8 - terminate debugged thread
* subfunction 9 - set/clear hardware breakpoint
======================================================================
= Function 69, subfunction 0 - define data area fror debug messages. =
======================================================================
Parameters:
* eax = 69 - function number
* ebx = 0 - subfunction number
* ecx = pointer
Format of data area:
* +0: dword: N = buffer size (not including this header)
* +4: dword: occupied place
* +8: N*byte: buffer
Returned value:
* function does not return value
Remarks:
* If the size field is negative, the buffer is considered locked
and at arrival of new message the system will wait.
For synchronization frame all work with the buffer by operations
lock/unlock
neg [bufsize]
* Data in the buffer are considered as array of items with variable
length - messages. Format of a message is explained in
general description.
======================================================================
===================== Function 69, subfunction 1 =====================
============ Get contents of registers of debugged thread. ===========
======================================================================
Parameters:
* eax = 69 - function number
* ebx = 1 - subfunction number
* ecx = thread identifier
* edx = size of context structure, must be 0x28=40 bytes
* esi = pointer to context structure
Returned value:
* function does not return value
Format of context structure: (FPU is not supported yet)
* +0: dword: eip
* +4: dword: eflags
* +8: dword: eax
* +12 = +0xC: dword: ecx
* +16 = +0x10: dword: edx
* +20 = +0x14: dword: ebx
* +24 = +0x18: dword: esp
* +28 = +0x1C: dword: ebp
* +32 = +0x20: dword: esi
* +36 = +0x24: dword: edi
Remarks:
* If the thread executes code of ring-0, the function returns
contents of registers of ring-3.
* Process must be loaded for debugging (as is shown in
general description).
======================================================================
===================== Function 69, subfunction 2 =====================
============ Set contents of registers of debugged thread. ===========
======================================================================
Parameters:
* eax = 69 - function number
* ebx = 2 - subfunction number
* ecx = thread identifier
* edx = size of context structure, must be 0x28=40 bytes
Returned value:
* function does not return value
Format of context structure is shown in the description of
subfunction 1.
Remarks:
* If the thread executes code of ring-0, the function returns
contents of registers of ring-3.
* Process must be loaded for debugging (as is shown in
general description).
======================================================================
===== Function 69, subfunction 3 - detach from debugged process. =====
======================================================================
Parameters:
* eax = 69 - function number
* ebx = 3 - subfunction number
* ecx = identifier
Returned value:
* function does not return value
Remarks:
* If the process was suspended, it resumes execution.
======================================================================
======== Function 69, subfunction 4 - suspend debugged thread. =======
======================================================================
Parameters:
* eax = 69 - function number
* ebx = 4 - subfunction number
* ecx = thread identifier
Returned value:
* function does not return value
Remarks:
* Process must be loaded for debugging (as is shown in
general description).
======================================================================
======== Function 69, subfunction 5 - resume debugged thread. ========
======================================================================
Parameters:
* eax = 69 - function number
* ebx = 5 - subfunction number
* ecx = thread identifier
Returned value:
* function does not return value
Remarks:
* Process must be loaded for debugging (as is shown in
general description).
======================================================================
= Fucntion 69, subfunction 6 - read from memory of debugged process. =
======================================================================
Parameters:
* eax = 69 - function number
* ebx = 6 - subfunction number
* ecx = identifier
* edx = number of bytes to read
* esi = address in the memory of debugged process
* edi = pointer to buffer for data
Returned value:
* eax = -1 at an error (invalid PID or buffer)
* otherwise eax = number of read bytes (possibly, 0,
if esi is too large)
Remarks:
* Process must be loaded for debugging (as is shown in
general description).
======================================================================
== Function 69, subfunction 7 - write to memory of debugged process. =
======================================================================
Parameters:
* eax = 69 - function number
* ebx = 7 - subfunction number
* ecx = identifier
* edx = number of bytes to write
* esi = address of memory in debugged process
* edi = pointer to data
Returned value:
* eax = -1 at an error (invalid PID or buffer)
* otherwise eax = number of written bytes (possibly, 0,
if esi is too large)
Remarks:
* Process must be loaded for debugging (as is shown in
general description).
======================================================================
======= Function 69, subfunction 8 - terminate debugged thread. ======
======================================================================
Parameters:
* eax = 69 - function number
* ebx = 8 - subfunction number
* ecx = identifier
Returned value:
* function does not return value
Remarks:
* Process must be loaded for debugging (as is shown in
general description).
* The function is similar to subfunction 2 of function 18
with two differences: it requires first remark and
accepts PID rather than slot number.
======================================================================
===== Function 69, subfunction 9 - set/clear hardware breakpoint. ====
======================================================================
Parameters:
* eax = 69 - function number
* ebx = 9 - subfunction number
* ecx = thread identifier
* dl = index of breakpoint, from 0 to 3 inclusively
* dh = flags:
* if high bit is cleared - set breakpoint:
* bits 0-1 - condition:
* 00 = breakpoint on execution
* 01 = breakpoint on read
* 11 = breakpoint on read/write
* bits 2-3 - length; for breakpoints on exception it must be
00, otherwise one of
* 00 = byte
* 01 = word
* 11 = dword
* esi = breakpoint address; must be aligned according to
the length (i.e. must be even for word breakpoints,
divisible by 4 for dword)
* if high bit is set - clear breakpoint
Returned value:
* eax = 0 - success
* eax = 1 - error in the input data
* eax = 2 - (reserved, is never returned in the current
implementation) a global breakpoint with that index is already set
Remarks:
* Process must be loaded for debugging (as is shown in
general description).
* Hardware breakpoints are implemented through DRx-registers of
the processor, all limitations results from this.
* The function can reinstall the breakpoint, previously set
by it (and it does not inform on this).
Carry on the list of set breakpoints in the debugger.
* Breakpoints generate debug exception #DB, on which the system
notifies debugger.
* Breakpoints on write and read/write act after
execution of the caused it instruction.
======================================================================
==== Function 70 - work with file system with long names support. ====
======================================================================
Parameters:
* eax = 70
* ebx = pointer to the information structure
Returned value:
* eax = 0 - success; otherwise file system error code
* some subfunctions return value in other registers too
General format of the information structure:
* +0: dword: subfunction number
* +4: dword: file offset
* +8: dword: high dword of offset (must be 0) or flags field
* +12 = +0xC: dword: size
* +16 = +0x10: dword: pointer to data
* +20 = +0x14: n db: ASCIIZ-string with the filename
or
* +20 = +0x14: db 0
* +21 = +0x15: dd pointer to ASCIIZ-string with the filename
Specifications - in documentation on the appropriate subfunction.
Filename is case-insensitive. Russian letters must be written in
the encoding cp866 (DOS).
Format of filename:
/base/number/dir1/dir2/.../dirn/file,
where /base/number identifies device, on which file is located:
one of
* /RD/1 = /RAMDISK/1 to access ramdisk
* /FD/1 = /FLOPPYDISK/1 to access first floppy drive,
/FD/2 = /FLOPPYDISK/2 to access second one
* /HD0/x, /HD1/x, /HD2/x, /HD3/x to access accordingly to devices
IDE0 (Primary Master), IDE1 (Primary Slave),
IDE2 (Secondary Master), IDE3 (Secondary Slave);
x - partition number on the selected hard drive, varies from 1
to 255 (on each hard drive the indexing starts from 1)
* /CD0/1, /CD1/1, /CD2/1, /CD3/1 to access accordingly to
CD on IDE0 (Primary Master), IDE1 (Primary Slave),
IDE2 (Secondary Master), IDE3 (Secondary Slave)
Examples:
* '/rd/1/kernel.asm',0
* '/HD0/1/kernel.asm',0
* '/hd0/2/menuet/pics/tanzania.bmp',0
* '/hd0/1/Program files/NameOfProgram/SomeFile.SomeExtension',0
Available subfunctions:
* subfunction 0 - read file
* subfunction 1 - read folder
* subfunction 2 - create/rewrite file
* subfunction 5 - get attributes of file/folder
* subfunction 6 - set attributes of file/folder
* subfunction 7 - start application
For CD-drives due to hardware limitations only subfunctions
0,1,5 and 7 are available, other subfunctions return error
with code 2.
======================================================================
=== Function 70, subfunction 0 - read file with long names support. ==
======================================================================
Parameters:
* eax = 70 - function number
* ebx = pointer to the information structure
Format of the information structure:
* +0: dword: 0 = subfunction number
* +4: dword: file offset (in bytes)
* +8: dword: 0 (reserved for high dword of offset)
* +12 = +0xC: dword: number of bytes to read
* +16 = +0x10: dword: pointer to buffer for data
* +20 = +0x14: ASCIIZ-name of file, the rules of names forming are
given in the general description
or
* +20 = +0x14: db 0
* +21 = +0x15: dd pointer to ASCIIZ-string with file name
Returned value:
* eax = 0 - success, otherwise file system error code
* ebx = number of read bytes or -1=0xffffffff if file was not found
Remarks:
* If file was ended before last requested block was read,
the function will read as many as it can, and after that return
eax=6 (EOF).
* The function does not allow to read folder (returns eax=10,
access denied).
======================================================================
== Function 70, subfunction 1 - read folder with long names support. =
======================================================================
Parameters:
* eax = 70 - function number
* ebx = pointer to the information structure
Format of the information structure:
* +0: dword: 1 = subfunction number
* +4: dword: index of starting block (beginning from 0)
* +8: dword: flags field:
* bit 0 (mask 1): in what format to return names,
0=ANSI, 1=UNICODE
* other bits are reserved and must be set to 0 for the future
compatibility
* +12 = +0xC: dword: number of blocks to read
* +16 = +0x10: dword: pointer to buffer for data, buffer size
must be not less than 32 + [+12]*560 bytes
* +20 = +0x14: ASCIIZ-name of folder, the rules of names forming are
given in the general description
or
* +20 = +0x14: db 0
* +21 = +0x15: dd pointer to ASCIIZ-string with file name
Returned value:
* eax = 0 - success, otherwise file system error code
* ebx = number of files, information on which was written to
the buffer, or -1=0xffffffff, if folder was not found
Structure of the buffer:
* +0: 32*byte: header
* +32 = +0x20: n1*byte: block with information on file 1
* +32+n1: n2*byte: block with information on file 2
* ...
Structure of header:
* +0: dword: version of structure (current is 1)
* +4: dword: number of placed blocks; is not greater than requested
in the field +12 of information structure; can be less, if
there are no more files in folder (the same as in ebx)
* +8: dword: total number of files in folder
* +12 = +0xC: 20*byte: reserved (zeroed)
Structure of block of data for folder entry (BDFE):
* +0: dword: attributes of file:
* bit 0 (mask 1): file is read-only
* bit 1 (mask 2): file is hidden
* bit 2 (mask 4): file is system
* bit 3 (mask 8): this is not a file but volume label
(for one partition meets no more than once and
only in root folder)
* bit 4 (mask 0x10): this is a folder
* bit 5 (mask 0x20): file was not archived - many archivation
programs have an option to archive only files with this bit set,
and after archiving this bit is cleared - it can be useful
for automatically creating of backup-archives as at writing
this bit is usually set
* +4: byte: type of name data:
(coincides with bit 0 of flags in the information structure)
* 0 = ASCII = 1-byte representation of each character
* 1 = UNICODE = 2-byte representation of each character
* +5: 3*byte: reserved (zero)
* +8: 4*byte: time of file creation
* +12 = +0xC: 4*byte: date of file creation
* +16 = +0x10: 4*byte: time of last access (read or write)
* +20 = +0x14: 4*byte: date of last access
* +24 = +0x18: 4*byte: time of last modification
* +28 = +0x1C: 4*byte: date of last modification
* +32 = +0x20: qword: file size in bytes (up to 16777216 Tb)
* +40 = +0x28: name
* for ASCII format: maximum length is 263 characters
(263 bytes), byte after the name has value 0
* äëÿ ôîðìàòà UNICODE: maximum length is 259 characters
(518 bytes), 2 bytes after the name have value 0
Time format:
* +0: byte: seconds
* +1: byte: minutes
* +2: byte: hours
* +3: byte: reserved (0)
* for example, 23.59.59 is written as (in hex) 3B 3B 17 00
Date format:
* +0: byte: day
* +1: byte: month
* +2: word: year
* for example, 25.11.1979 is written as (in hex) 19 0B BB 07
Remarks:
* If BDFE contains ASCII name, the length of BDFE is 304 bytes,
if UNICODE name - 560 bytes. Value of length is aligned
on 16-byte bound (to accelerate processing in CPU cache).
* First character after a name is zero (ASCIIZ-string). The further
data contain garbage.
* If files in folder were ended before requested number was read,
the function will read as many as it can, and after that return
eax=6 (EOF).
* Any folder on the disk, except for root, contains two special
entries "." and "..", identifying accordingly the folder itself
and the parent folder.
* The function allows also to read virtual folders "/", "/rd",
"/fd", "/hd[n]", thus attributes of subfolders are set to 0x10,
and times and dates are zeroed. An alternative way to get the
equipment information - subfunction 11 of function 18.
======================================================================
===================== Function 70, subfunction 2 =====================
============ Create/rewrite file with long names support. ============
======================================================================
Parameters:
* eax = 70 - function number
* ebx = pointer to the information structure
Format of the information structure:
* +0: dword: 2 = subfunction number
* +4: dword: 0 (reserved)
* +8: dword: 0 (reserved)
* +12 = +0xC: dword: number of bytes to read
* +16 = +0x10: dword: pointer to data
* +20 = +0x14: ASCIIZ-name of file, the rules of names forming are
given in the general description
or
* +20 = +0x14: db 0
* +21 = +0x15: dd pointer to ASCIIZ-string with file name
Returned value:
* eax = 0 - success, otherwise file system error code
* ebx = number of written bytes (possibly 0)
Remarks:
* If a file with given name did not exist, it is created;
if it existed, it is rewritten.
* If there is not enough free space on disk, the function will
write as many as can and then return error code 8.
* The function is not supported for CD (returns error code 2).
======================================================================
==== Function 70, subfunction 5 - get information on file/folder. ====
======================================================================
Parameters:
* eax = 70 - function number
* ebx = pointer to the information structure
Format of the information structure:
* +0: dword: 5 = subfunction number
* +4: dword: 0 (reserved)
* +8: dword: 0 (reserved)
* +12 = +0xC: dword: 0 (reserved)
* +16 = +0x10: dword: pointer to buffer for data (40 bytes)
* +20 = +0x14: ASCIIZ-name of file, the rules of names forming are
given in the general description
or
* +20 = +0x14: db 0
* +21 = +0x15: dd pointer to ASCIIZ-string with file name
Returned value:
* eax = 0 - success, otherwise file system error code
* ebx destroyed
Information on file is returned in the BDFE format (block of data
for folder entry), explained in the description of
subfunction 1, but without filename
(i.e. only first 40 = 0x28 bytes).
Remarks:
* The function does not support virtual folders such as /, /rd and
root folders like /rd/1.
======================================================================
===== Function 70, subfunction 6 - set attributes of file/folder. ====
======================================================================
Parameters:
* eax = 70 - function number
* ebx = pointer to the information structure
Format of the information structure:
* +0: dword: 6 = subfunction number
* +4: dword: 0 (reserved)
* +8: dword: 0 (reserved)
* +12 = +0xC: dword: 0 (reserved)
* +16 = +0x10: dword: pointer to buffer with attributes (32 bytes)
* +20 = +0x14: ASCIIZ-name of file, the rules of names forming are
given in the general description
or
* +20 = +0x14: db 0
* +21 = +0x15: dd pointer to ASCIIZ-string with file name
Returned value:
* eax = 0 - success, otherwise file system error code
* ebx destroyed
File attributes are first 32 bytes in BDFE (block of data
for folder entry), explained in the description of subfunction 1
(that is, without name and size of file). Attribute
file/folder/volume label (bits 3,4 in dword +0) is not changed.
Byte +4 (name format) is ignored.
Remarks:
* The function does not support virtual folders such as /, /rd and
root folders like /rd/1.
* The function is not supported for CD (returns error code 2).
======================================================================
=========== Function 70, subfunction 7 - start application. ==========
======================================================================
Parameters:
* eax = 70 - function number
* ebx = pointer to the information structure
Format of the information structure:
* +0: dword: 7 = subfunction number
* +4: dword: flags field:
* áèò 0: start process as debugged
* other bits are reserved and must be set to 0
* +8: dword: 0 or pointer to ASCIIZ-string with parameters
* +12 = +0xC: dword: 0 (reserved)
* +16 = +0x10: dword: 0 (reserved)
* +20 = +0x14: ASCIIZ-name of file, the rules of names forming are
given in the general description
or
* +20 = +0x14: db 0
* +21 = +0x15: dd pointer to ASCIIZ-string with file name
Returned value:
* eax > 0 - program is loaded, eax contains PID
* eax < 0 - an error has occured, -eax contains
file system error code
* ebx destroyed
Remarks:
* Command line must be terminated by the character with the code 0
(ASCIIZ-string); function takes into account either all characters
up to terminating zero inclusively or first 256 character
regarding what is less.
* If the process is started as debugged, it is created in
the suspended state; to run use subfunction 5 of function 69.
======================================================================
========== Function 71, subfunction 1 - set window caption. ==========
======================================================================
Parameters:
* eax = 71 - function number
* ebx = 1 - subfunction number
* ecx = pointer to caption string
Returned value:
* function does not return value
Remarks:
* String must be in the ASCIIZ-format. Disregarding real string
length, no more than 255 characters are drawn.
* Pass NULL in ecx to remove caption.
======================================================================
=============== Function -1 - terminate thread/process ===============
======================================================================
Parameters:
* eax = -1 - function number
Returned value:
* function does not return neither value nor control
Remarks:
* If the process did not create threads obviously, it has only
one thread, which termination results in process termination.
* If the current thread is last in the process, its termination
also results in process terminates.
* This function terminates the current thread. Other thread can be
killed by call to subfunction 2 of function 18.
======================================================================
=========================== List of events ===========================
======================================================================
Next event can be retrieved by the call of one from functions 10
(to wait for event), 11 (to check without waiting), 23
(to wait during the given time).
These functions return only those events, which enter into a mask set
by function 40. By default it is first three,
there is enough for most applications.
Codes of events:
* 1 = redraw event (is reset by call to function 0)
* 2 = key on keyboard is pressed (acts, only when the window is
active) or hotkey is pressed; is reset, when all keys from
the buffer are read out by function 2
* 3 = button is pressed, defined earlier by function 8
(or close button, created implicitly by function 0;
minimize button is handled by the system and sends no message;
acts, only when the window is active;
is reset when all buttons from the buffer
are read out by function 17)
* 4 = reserved (in current implementation never comes even after
unmasking by function 40)
* 5 = the desktop background is redrawed (is reset automatically
after redraw, so if in redraw time program does not wait and
does not check events, it will not remark this event)
* 6 = mouse event (something happened - button pressing or moving;
is reset at reading)
* 7 = IPC event (see function 60 -
Inter Process Communication; is reset at reading)
* 8 = network event (is reset at reading)
* 9 = debug event (is reset at reading; see
debug subsystem)
* 16..31 = event with appropriate IRQ
(16=IRQ0, 31=IRQ15) (is reset after reading all IRQ data)
======================================================================
=================== Error codes of the file system ===================
======================================================================
* 0 = success
* 1 = base and/or partition of a hard disk is not defined
(by subfunctions 7, 8 of function 21)
* 2 = function is not supported for the given file system
* 3 = unknown file system
* 4 = is returned only from function 'rename' by transmission of
the strongly incorrect parameter and in any way does not
correspond to the description in the kernel sources
"partition not defined at hd"
* 5 = file not found
* 6 = end of file, EOF
* 7 = pointer lies outside of application memory
* 8 = disk is full
* 9 = FAT table is destroyed
* 10 = access denied
* 11 = device error
Application start functions can return also following errors:
* 30 = 0x1E = not enough memory
* 31 = 0x1F = file is not executable
* 32 = 0x20 = too many processes