WebSVN – Kolibri OS – Diff – /kernel/trunk/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. =
 ======================================================================
   * 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:
 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
   * 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
 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
 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. ===============
+=================== Function 36 - read screen area. ==================
 ======================================================================
 Paramters:
   * eax = 36 - function number
-  * ebx = pointer on the previously allocated area of memory,
+  * ebx = pointer to the previously allocated memory area,
-             where will be placed the image in the format BBGGRRBBGGRR...
+        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:
   * 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.
 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.
 ======================================================================
   * 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
 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.
 ======================================================================
   * 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 22 - open memory block. =======
-======================================================================
-Parameters:
-  * eax = 68 - function number
-  * ebx = 22 - subfunction number
-  * ecx = pointer to already allocated block (max 32 symbols)
-  * edx = block's size in bytes for SHM_CREATE and SHM_OPEN_ALWAYS
-  * esi = flags for opening and getting access
-          SHM_OPEN        = 0x00
-          SHM_OPEN_ALWAYS = 0x04
-          SHM_CREATE      = 0x08
-          SHM_READ        = 0x00
-          SHM_WRITE       = 0x01
-Returned value:
-  * eax = pointer to the readed block, 0 = error
-  * edx = if SHM_CREATE, SHM_OPEN, or SHM_OPEN_ALWAYS active
-Error codes:
-  * E_NOTFOUND =  5
-  * E_ACCESS   = 10
-  * E_NOMEM    = 30
-  * E_PARAM    = 33
-Remarks:
-  *
-  *
-======================================================================
-======= Function 68, subfunction 22 - close memory block. =======
-======================================================================
-Parameters:
-  * eax = 68 - function number
-  * ebx = 23 - subfunction number
-  * ecx = pointer to already allocated block (max 32 symbols)
-Returned value:
-  * not defined
 ======================================================================
 ====================== 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
   * 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/trunk/docs/sysfuncs.txt @ 4199 – Rev 991 → 1018