WebSVN – Kolibri OS – Diff – /kernel/branches/kolibri_pe/docs/sysfuncs.txt

-SYSTEM FUNCTIONS of OS Kolibri 0.7.1.0
+SYSTEM FUNCTIONS of OS Kolibri 0.7.5.0
 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,
 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. ==============
 ======================================================================
 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:
+  * if the buffer is not empty:
-    high 24 bits of eax contain button identifier (in particular, ah
+    * high 24 bits of eax contain button identifier (in particular,
-    contains low byte of the identifier; if all buttons have
+      ah contains low byte of the identifier; if all buttons have
-    the identifier less than 256, ah is enough to distinguish),
+      the identifier less than 256, ah is enough to distinguish)
-    and al contain 0 - if used left mouse button or bit of the used another mouse button
+    * al = 0 - the button was pressed with left mouse button
+    * al = bit corresponding to used mouse button otherwise
 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".
+  * Returned value for al corresponds to the state of mouse buttons
+    as in subfunction 2 of function 37 at the beginning
+    of button press, excluding lower bit, which is cleared.
 ======================================================================
 = Function 18, subfunction 2 - terminate process/thread by the slot. =
 ======================================================================
   * 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 = 2 - number of the subsubfunction
 Returned value:
   * function does not return value
 ======================================================================
-============ Function 18, subfunction 9 - system shutdown. ===========
+== Function 18, subfunction 9 - system shutdown with the parameter. ==
 ======================================================================
 Parameters:
   * eax = 18 - function number
   * ebx = 9 - subfunction number
   * 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.
 ======================================================================
 ===== Function 18, subfunction 10 - minimize application window. =====
 ======================================================================
 Minimizes the own window.
 Parameters:
 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
   * 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. ========
     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.
 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. =====
-======================================================================
-Removed
 ======================================================================
 ========== Function 21, subfunction 5 - set system language. =========
 ======================================================================
 Parameters:
   * eax = 21 - function number
 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. ========
   * 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. ========
-======================================================================
-Removed
 ======================================================================
  Function 21, subfunction 11 - enable/disable low-level access to HD.
 ======================================================================
 Parameters:
   * eax = 21 - function number
   * ebx = 11 - subfunction number
   * 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
     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.
     * 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).
   * 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.
   * ebx = 1 - subfunction number
 Returned value:
   * eax = 0 - success
   * eax = 1 - CD base is not defined
 Remarks:
   * Previously CD base port must be defined by call to
     subfunction 3 of function 21.
 ======================================================================
 ======= Function 24, subfunction 4 - eject tray of disk drive. =======
 Remarks:
   * The function is supported only for ATAPI devices (CD and DVD).
   * An example of usage of the function is the application CD_tray.
-======================================================================
-=================== Function 25 - set SBPro volume. ==================
-======================================================================
-Removed
 ======================================================================
 ======== Function 26, subfunction 1 - get MPU MIDI base port. ========
 ======================================================================
 Parameters:
   * eax = 26 - function number
     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.
 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. =====
-======================================================================
-Removed
 ======================================================================
 ========== Function 26, subfunction 5 - get system language. =========
 ======================================================================
 Parameters:
   * eax = 26 - function number
   * 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. ========
-======================================================================
-Removed
 ======================================================================
 ===================== Function 26, subfunction 11 ====================
 ========== Find out whether low-level HD access is enabled. ==========
 ======================================================================
 Parameters:
   * 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 28 - set SB16 volume. ===================
-======================================================================
-Removed
 ======================================================================
 =================== Function 29 - get system date. ===================
 ======================================================================
 Parameters:
   * eax = 29 - function number
 Remarks:
   * If the buffer is too small to hold all data, only first (edx-1)
     bytes are copied and than terminating 0 is inserted.
+======================================================================
+=============== 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
+(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
   * 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 36 - read screen area. ==================
+======================================================================
+Paramters:
+  * eax = 36 - function number
+  * ebx = pointer to the previously allocated memory area,
+        where will be placed 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 screen.
+  * Size of the image in bytes is 3*xsize*ysize.
 ======================================================================
 =================== Function 37 - work with mouse. ===================
 ======================================================================
 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. =
   * 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. ==========
   * eax = owner PID
   * eax = 0, if there is no owner
   * eax = -1 for incorrect ebx
 ======================================================================
-==================== Function 42 - work with IRQ data. ===============
+================== Function 42 - work with IRQ data. =================
-======================================================================
------------------------- Reading 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.
-internal buffer. This function reads out data from that buffer
-to the buffer specified as parameter.
+--------------------- Subfunction 0 - read data ----------------------
 Parameters:
   * eax = 42 - function number
   * bl = IRQ number, 0..15
-  * bh = subfunction number, 0
+  * bh = 0 - subfunction number
-Other part of register ebx, must be zero.
+  * rest of ebx must be zeroed
-  * ecx = pointer to the receive buffer
+  * ecx = pointer to a buffer with size not less than 4000 bytes
 Returned value: (use value of eax to distinguish)
-  * if the thread is not IRQ owner (or IRQ number is incorrect):
+  * if the thread is not IRQ owner
-    * eax = -1
+    (or IRQ number is incorrect): eax = -1
-  * if there is no data:
-    * eax = 0
+  * if there is no data: eax = 0
   * if all is ok:
-    * eax = byte size of data, read from buffer
-See remarks below.
+    eax = size of data read (in bytes)
 ------------------------ Get data size -------------------------------
 ------------- Subfunction 1 - get size of data in buffer -------------
 Parameters:
   * eax = 42 - function number
   * bl = IRQ number, 0..15
-  * bh = subfunction number, 0
-Other part of register ebx, must be zero.
+  * bh = 0 - subfunction number
-  * ecx = pointer to receive buffer
+  * rest of ebx must be zeroed
-Returned value: (use value of eax to distinguish)
+Returned value:
-  * if the thread is not IRQ owner (or IRQ number is incorrect):
-    * eax = -1
+  * if the thread is not IRQ owner
-  * if all is ok:
-    * eax = byte size of data in buffer
+    (or IRQ number is incorrect): eax = -1
   * otherwise eax = size of data in buffer
 Remarks:
   * Previously the thread must reserve indicated IRQ for itself
     by function 45.
   * +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
+        sc      system_colors           ; variable declaration
-    	...				; somewhere one must call
+        ...                             ; somewhere one must call
-    					; this function with ecx=sc
+                                        ; this function with ecx=sc
-    	mov	ecx, [sc.work_button_text]	; read text color on
+        mov     ecx, [sc.work_button_text]      ; read text color on
-    					; buttin in working area
+                                        ; 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
   * 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
 ======================================================================
 === Function 52, subfunction 0 - get network driver configuration. ===
 ======================================================================
     (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
 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
+  * eax = number of read bytes, 0 for incorrect handle
-  * ebx destroyed
-Remarks:
-  * There is no checks for correctness.
+  * ebx destroyed
 ======================================================================
 ========= 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,
+  * if there is no read data or handle is incorrect: 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:
+  * if there are read data: eax=number of rest bytes
-  * There is no checks for correctness.
+    (possibly 0), bl=read byte, other bytes of ebx are destroyed
 ======================================================================
   * 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 = 0xffffffff - error (invalid handle or not enough memory)
-  * 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.
 ======================================================================
 Parameters:
   * eax = 53 - function number
   * ebx = 6 - subfunction number
   * ecx = socket handle
 Returned value:
-  * eax = socket status: one of
+  * eax = 0 for incorrect handle or socket status: one of
   * TCB_LISTEN = 1
   * TCB_SYN_SENT = 2
   * TCB_SYN_RECEIVED = 3
   * TCB_ESTABLISHED = 4
   * TCB_FIN_WAIT_1 = 5
   * TCB_CLOSE_WAIT = 7
   * TCB_CLOSING = 8
   * TCB_LAST_ASK = 9
   * TCB_TIME_WAIT = 10
   * TCB_CLOSED = 11
-  * ebx destroys
+  * ebx destroyed
-Remarks:
-  * There is no checks for correctness.
 ======================================================================
 ========== Function 53, subfunction 7 - write to TCP-socket. =========
 ======================================================================
   * 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 = 0xffffffff - error (invalid handle or 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.
 ======================================================================
 Parameters:
   * eax = 53 - function number
   * ebx = 8 - subfunction number
   * ecx = socket handle
 Returned value:
-  * eax = -1 - invalid handle
+  * eax = -1 - error (invalid handle or
-  * eax = 0xffff - not enough memory for socket close packet
+    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. ===
 ======================================================================
   * ecx = socket handle
   * edx = pointer to buffer
   * esi = number of bytes to read;
   * esi = 0 - read all data (maximum 4096 bytes)
 Returned value:
-  * eax = number of bytes read
+  * eax = number of bytes read (0 for incorrect handle)
   * ebx destroyed
-Remakrs:
-  * There is no check on handle correctness.
 ======================================================================
 = Function 53, subfunction 255 - debug information of network driver.
 ======================================================================
 Parameters:
   * eax = 53 - function number
   * ebx = 255 - subfunction number
   * 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
     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,
 x1C00=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);
     * 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
 ==== 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]
+        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
+        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:
 Parameters:
   * eax = 65 - function number
   * ebx = pointer to the image
   * ecx = [size on axis x]*65536 + [size on axis y]
   * edx = [coordinate on axis x]*65536 + [coordinate on axis y]
-  * esi = number of bits per pixel, must be 8, 24 or 32
+  * esi = number of bits per pixel, must be 1,2,4,8,15,16,24 or 32
-  * edi = pointer to palette (256 colors 0x00RRGGBB);
+  * edi = pointer to palette (2 to the power esi colors 0x00RRGGBB);
-          ignored when esi = 24 and 32
+          ignored when esi > 8
   * ebp = offset of next row data relative to previous row data
 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 xsize*ysize.
+  * Format of image with 1 bit per pixel: each byte of image
+    (possibly excluding last bytes in rows), contains information on
+    the color of 8 pixels, MSB corresponds to first pixel.
+  * Format of image with 2 bits per pixel: each byte of image
+    (possibly excluding last bytes in rows), contains information on
+    the color of 4 pixels, two MSBs correspond to first pixel.
+  * Format of image with 4 bits per pixel: each byte of image
+    excluding last bytes in rows (if width is odd) contains
+    information on the color of 2 pixels, high-order tetrad
+    corresponds to first pixel.
+  * Format of image with 8 bits per pixel: each byte of image is
-  * Each byte of image is index in the palette.
+    index in the palette.
-  * If the image uses less than 256 colors, palette size may be
+  * Format of image with 15 bits per pixel: the color of each pixel
+    is coded as (bit representation) 0RRRRRGGGGGBBBBB - 5 bits per
-    less than 256 too.
+    each color.
+  * Format of image with 16 bits per pixel: the color of each pixel
+    is coded as RRRRRGGGGGGBBBBB (5+6+5).
+  * Format of image with 24 bits per pixel: the color of each pixel
+    is coded as 3 bytes - sequentially blue, green, red components.
+  * Format of image with 32 bits per pixel: similar to 24, but
+    one additional ignored byte is present.
   * The call to function 7 is equivalent to call to this function
     with esi=24, ebp=0.
 ======================================================================
 Remarks:
   * The memory block must have been allocated by subfunction 12
     or subfunction 20.
 ======================================================================
+===================== Function 68, subfunction 14 ====================
-======== Function 68, subfunction 14 - wait for driver notify. =======
+====== Waiting delivering of signal from another program/driver ======
 ======================================================================
 Parameters:
   * eax = 68 - function number
   * ebx = 14 - subfunction number
-  * ecx = pointer to the buffer for information (8 bytes)
+  * ecx = pointer to the buffer for information (24 bytes)
 Returned value:
   * buffer pointed to by ecx contains the following information:
-    * +0: dword: constant EV_INTR = 1
-    * +4: dword: driver data
-Remarks:
+    * +0: dword: identifier for underlying data of signal
-  * The current implementation at wait time uses "heavy" operations
+    * +4: data of signal (20 bytes), format of which is defining by
-    of task switch.
+          first dword
 ======================================================================
-====== Function 68, subfunction 15 - set FPU exception handler. ======
-======================================================================
+====== Function 68, subfunction 15 - set FPU exception handler. ======
-Parameters:
+======================================================================
-  * eax = 68 - function number
-  * ebx = 15 - subfunction number
-  * ecx = address of the new exception handler
-Returned value:
+Deleted (in current implementation only 0 is returned).
-  * eax = address of the old exception handler (0, if it was not set)
+Using subfunctions 24, 25 is true.
 ======================================================================
     * +8: dword: pointer to input data
     * +12 = +0xC: dword: size of input data
     * +16 = +0x10: dword: pointer to output data
     * +20 = +0x14: dword: size of output data
 Returned value:
-  * eax = determined by driver
+  * eax =  error code
+- successful call
+     -1  - any error.
+     -2, -3, -4, etc. reserved for kernel error codes
+, 2, 3, etc    driver specific error codes
 Remarks:
   * Function codes and the structure of input/output data
     are defined by driver.
   * Previously one must obtain driver handle by subfunction 16.
 ======================================================================
 ====== Function 68, subfunction 18 - set SSE exception handler. ======
-======================================================================
-Parameters:
+======================================================================
-  * eax = 68 - function number
+Deleted (in current implementation only 0 is returned).
-  * ebx = 15 - subfunction number
-  * ecx = address of the new exception handler
-Returned value:
-  * eax = address of the old exception handler (0, if it was not set)
+Using subfunctions 24, 25 is true.
 ======================================================================
 =============== Function 68, subfunction 19 - load DLL. ==============
   * If ecx=0, the function frees memory block at edx and returns 0.
   * The contents of the block are unchanged up to the shorter of
     the new and old sizes.
+======================================================================
+====== Function 68, subfunction 24 - set new exceptions handler ======
+======================================================================
+Parameters:
+  * eax = 68 - function number
+  * ebx = 24 - subfunction number
+  * ecx = address of the new exception handler
+  * edx = the mask of processing exceptions
+Returned value:
+  * eax = address of the old exception handler (0, if it was not set)
+  * ebx = the old mask of exception handler
+Remarks:
+  * Bit number in mask of exceptions is correspond to exception number
+    by CPU-specification (Intel-PC). For example, FPU-exception have
+    number 16 (#MF), and SSE-exception - 19 (#XF)
+  * The current implementation ignore the inquiry for hook of 7
+    exception - system process #NM by one's own.
+  * User handler get exception number in stack parameter. So, correct
+    exit from handler is: RET 4. Return from handler is to the same
+    instruction, that was cause the exception
+  * When control is transfering to user handler, corresponding bit in
+    exception mask is clearing. Rising this exception in consequence
+    - reduce to default-handling. Exactly: terminating the application,
+    or suspending with debug-notify to owner.
+  * After completion of critical operations in user handler, it may be
+    rising corresponding bit in exception mask by using subfunction 25
+    Clearing exceptions flags in FPU and/or XMM modules - is
+    responsibility of user handler too.
+======================================================================
+==== Function 68, subfunction 25 - change state of signal activity ===
+======================================================================
+Parameters:
+  * eax = 68 - function number
+  * ebx = 25 - subfunction number
+  * ecx = signal number
+  * edx = value of activity (0/1)
+Returned value:
+  * eax = value of old activity for this signal (0/1)
+Remarks:
+  * In current implementation, it is changed only exception mask for
+    user exception handler, wich was previously set by subfunction 24.
+    At that, number of signal correspond to exception number.
 ======================================================================
 ====================== Fucntion 69 - debugging. ======================
 ======================================================================
 A process can load other process as debugged by set of corresponding
 bit by call to subfunction 7 of function 70.
     * 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 except 4 and 5 are applicable only to
-processes/threads started from the current by function 70
+All subfunctions are applicable only to processes/threads started
-with set debugging flag.
+from the current by function 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
 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]
+        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 does not return value
 Remarks:
   * If the process was suspended, it resumes execution.
 ======================================================================
-============= Function 69, subfunction 4 - suspend thread. ===========
+======== 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
-  * function does not return value
+    general description).
 ======================================================================
-============= Function 69, subfunction 5 - resume thread. ============
+======== 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:
-Returned value:
+  * Process must be loaded for debugging (as is shown in
-  * function does not return value
+    general description).
 ======================================================================

Subversion Repositories Kolibri OS

(root)/kernel/branches/kolibri_pe/docs/sysfuncs.txt – Rev 837 → 2971