WebSVN – Kolibri OS – Diff – /kernel/trunk/docs/sysfuncs.txt

-SYSTEM FUNCTIONS of OS Kolibri 0.7.5.0
+SYSTEM FUNCTIONS of OS Kolibri 0.7.7.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,
     * 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.
-  * Applications are placed in memory at the address   0x0
+  * The normal applications are placed in memory at the address
-    (kernel constant 'std_application_base_address').
+(kernel constant '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
   * 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
 dd REV - kernel SVN revision number
-For Kolibri 0.7.1.0 kernel:
+For Kolibri 0.7.7.0 kernel:
-db 0,7,0,0
+db 0,7,7,0
 db 2
-dd 638
+dd 1319
 ======================================================================
 ======= Function 18, subfunction 14 - wait for screen retrace. =======
 ======================================================================
 Returned value:
   * eax = size of the current folder's name (including terminating 0)
 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
+  * By default, current folder for the thread is "/rd/1".
-    (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.
+  * At process/thread creation the current folder will be inherited
-======================================================================
-================ 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
+    from the parent.
-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. =======
 ======================================================================
     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 62, subfunction 11 ====================
-==              Initialize user-accessible MMIO channel             ==
-======================================================================
-Parameters:
-  * eax = 62 - function
-  * bl  = 11 - subfunction
-  * cx  = PCI-address (bbbbbbbb dddddfff)
-Returns:
-  * eax = -1 - PCI access not granted;
-  * eax = -2 - no user MMIO access to this PCI address;
-  * eax = -3 - memory allocation error; otherwise
-  * eax = available user heap size.
-Remarks:
-  * Low-level PCI access must be allowed (fn21:12)
-  * PCI-address should correspond the system var [mmio_pci_addr]
-======================================================================
-===================== Function 62, subfunction 12 ====================
-==            Request user-accessible MMIO address space            ==
-======================================================================
-Parameters:
-  * eax = 62 - function
-  * bl  = 12 - subfunction
-  * bh  = BAR number in PCI configuration space
-  * ecx = MMIO-block size needed (bytes)
-  * edx = MMIO-offset (number of whole 4Kb-pages!)
-Returns:
-  * eax = -1 - user PCI access denied;
-  * eax = -2 - invalid BAR number;
-  * eax = -3 - BAR contains no valid IO addres;
-  * eax = -4 - BAR addresses IO ports;
-  * eax = -5 - dynamic allocation error; otherwise
-  * eax = MMIO start address (in application's linear space).
-Remarks:
-  * Low-level PCI access must be allowed (fn21:12)
-  * The system var [mmio_pci_addr] sets the actual PCI-address
-  * The granted MMIO addresses should be released after use (fn62:13)
-======================================================================
-===================== Function 62, subfunction 13 ====================
-==              Release a block of user MMIO addresses              ==
-======================================================================
- à ¬¥âàë:
-  * eax = 62 - function
-  * bl  = 12 - subfunction
-  * ecx = MMIO start address (in application's linear space).
-Returns:
-  * eax = 1 if the block is successfully released;
-  * eax = 0 in case of reallocation error;
-Remarks:
-  * A valid uMMIO block should exist at this address (fn62:12)
 ======================================================================
 ============== Function 63 - work with the debug board. ==============
 ======================================================================
 The debug board is the global system buffer (with the size
 bytes), to which any program can write (generally speaking,
 ======================================================================
 ================== 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.
-If subfunction is not support then eax=-1.
 -------------- Subfunction 1 - set keyboard input mode. --------------
 Parameters:
   * eax = 66 - function number
   * The memory block must have been allocated by subfunction 12
     or subfunction 20.
 ======================================================================
 ===================== Function 68, subfunction 14 ====================
-====== Waiting delivering of signal from another program/driver ======
+============ Wait for signal from another program/driver. ============
 ======================================================================
 Parameters:
   * eax = 68 - function number
   * ebx = 14 - subfunction number
   * ecx = pointer to the buffer for information (24 bytes)
 Returned value:
   * buffer pointed to by ecx contains the following information:
-    * +0: dword: identifier for underlying data of signal
+    * +0: dword: identifier for following data of signal
-    * +4: data of signal (20 bytes), format of which is defining by
+    * +4: dword: data of signal (20 bytes), format of which is defined
-          first dword
-======================================================================
-====== Function 68, subfunction 15 - set FPU exception handler. ======
-======================================================================
-Deleted (in current implementation only 0 is returned).
-Using subfunctions 24, 25 is true.
+          by the first dword
 ======================================================================
 ============= Function 68, subfunction 16 - load driver. =============
     * +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 =  error code
+  * eax = determined by driver
-- 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. ======
-======================================================================
-Deleted (in current implementation only 0 is returned).
-Using subfunctions 24, 25 is true.
 ======================================================================
 =============== Function 68, subfunction 19 - load DLL. ==============
 ======================================================================
 Parameters:
   * eax = 68 - function number
   * 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 named memory area. =======
+======================================================================
+Parameters:
+  * eax = 68 - function number
+  * ebx = 22 - subfunction number
+  * ecx = area name. Maximum of 31 characters with terminating zero
+  * edx = area size in bytes for SHM_CREATE and SHM_OPEN_ALWAYS
+  * esi = flags for open and access:
+    * SHM_OPEN        = 0x00 - open existing memory area. If an area
+                          with such name does not exist, the function
+                          will return error code 5.
+    * SHM_OPEN_ALWAYS = 0x04 - open existing or create new
+                          memory area.
+    * SHM_CREATE      = 0x08 - create new memory area. If an area
+                          with such name already exists, the function
+                          will return error code 10.
+    * SHM_READ        = 0x00 - only read access
+    * SHM_WRITE       = 0x01 - read and write access
+Returned value:
+  * eax = pointer to memory area, 0 if error has occured
+  * if new area is created (SHM_CREATE or SHM_OPEN_ALWAYS):
+    edx = 0 - success, otherwise - error code
+  * if existing area is opened (SHM_OPEN or SHM_OPEN_ALWAYS):
+    edx = error code (if eax=0) or area size in bytes
+Error codes:
+  * E_NOTFOUND = 5
+  * E_ACCESS = 10
+  * E_NOMEM = 30
+  * E_PARAM = 33
+Remarks:
+  * Before this call one must initialize process heap by call to
+    subfunction 11.
+  * If a new area is created, access flags set maximal rights
+    for other processes. An attempt from other process to open
+    with denied rights will fail with error code E_ACCESS.
+  * The process which has created an area always has write access.
+======================================================================
+======= Function 68, subfunction 23 - close named memory area. =======
+======================================================================
+Parameters:
+  * eax = 68 - function number
+  * ebx = 23 - subfunction number
+  * ecx = area name. Maximum of 31 characters with terminating zero
+Returned value:
+  * eax destroyed
+Remarks:
+  * A memory area is physically freed (with deleting all data and
+    freeing physical memory), when all threads which have opened
+    this area will close it.
+  * When thread is terminating, all opened by it areas are closed.
 ======================================================================
-====== Function 68, subfunction 24 - set new exceptions handler ======
+======== Function 68, subfunction 24 - set exception handler. ========
 ======================================================================
 Parameters:
   * eax = 68 - function number
   * ebx = 24 - subfunction number
   * ecx = address of the new exception handler
-  * edx = the mask of processing exceptions
+  * edx = the mask of handled exceptions
 Returned value:
   * eax = address of the old exception handler (0, if it was not set)
-  * ebx = the old mask of exception handler
+  * ebx = the old mask of handled exceptions
 Remarks:
-  * Bit number in mask of exceptions is correspond to exception number
+  * Bit number in mask of exceptions corresponds to exception number
-    by CPU-specification (Intel-PC). For example, FPU-exception have
+    in CPU-specification (Intel-PC). For example, FPU exceptions have
-    number 16 (#MF), and SSE-exception - 19 (#XF)
+    number 16 (#MF), and SSE exceptions - 19 (#XF).
-  * The current implementation ignore the inquiry for hook of 7
+  * The current implementation ignores the inquiry for hook of 7
-    exception - system process #NM by one's own.
+    exception - the system handles #NM by its own.
-  * User handler get exception number in stack parameter. So, correct
+  * The exception handler is called with exception number as first
-    exit from handler is: RET 4. Return from handler is to the same
+    (and only) stack parameter. So, correct exit from the handler is
+    RET 4. It returns to the instruction, that caused the exception,
+    for faults, and to the next instruction for traps (see
-    instruction, that was cause the exception
+    classification of exceptions in CPU specification).
-  * When control is transfering to user handler, corresponding bit in
+  * When user handler receives control, the corresponding bit in
-    exception mask is clearing. Rising this exception in consequence
+    the exception mask is cleared. Raising this exception
+    in consequence leads to default handling, that is,
-    - reduce to default-handling. Exactly: terminating the application,
+    terminating the application in absence of debugger or
-    or suspending with debug-notify to owner.
+    suspend with notification of debugger otherwise.
-  * After completion of critical operations in user handler, it may be
+  * After user handler completes critical operations, it can set
-    rising corresponding bit in exception mask by using subfunction 25
+    the corresponding bit in the exception mask with subfunction 25.
-    Clearing exceptions flags in FPU and/or XMM modules - is
+    Also user handler is responsible for clearing exceptions flags in
-    responsibility of user handler too.
+    FPU and/or SSE.
 ======================================================================
-==== Function 68, subfunction 25 - change state of signal activity ===
+====== Function 68, subfunction 25 - set FPU exception handler. ======
 ======================================================================
 Parameters:
   * eax = 68 - function number
   * ebx = 25 - subfunction number
   * ecx = signal number
+  * edx = value of activity (0/1)
-  * edx = value of activity (0/1)
+Returned value:
-Returned value:
+  * eax = -1 - invalid signal number
-  * eax = value of old activity for this signal (0/1)
+  * otherwise eax = old value of activity for this signal (0/1)
 Remarks:
-  * In current implementation, it is changed only exception mask for
+  * In current implementation only mask for user excepton handler,
-    user exception handler, wich was previously set by subfunction 24.
+    which has been previously set by subfunction 24,
-    At that, number of signal correspond to exception number.
+    is changed. Signal number corresponds to exception number.
 ======================================================================
-====================== Fucntion 69 - debugging. ======================
+====================== Function 69 - debugging. ======================
 ======================================================================
 A process can load other process as debugged by set of corresponding
   * '/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
   * '/sys/MySuperApp.ini',0
+Also function supports relative names.  If the path begins not
+with '/', it is considered relative to a current folder. To get or
+set a current folder, use the function 30.
 Available subfunctions:
   * subfunction 0 - read file
   * subfunction 1 - read folder
   * subfunction 2 - create/rewrite file
   * subfunction 3 - write to existing file

Subversion Repositories Kolibri OS

(root)/kernel/trunk/docs/sysfuncs.txt @ 5836 – Rev 1494 → 1662