system/docs: revert some old tweaks, add some new

2026-01-02 14:33:50 +02:00
parent 8fb3bb76c6
commit 5ed012b0d9
2 changed files with 84 additions and 86 deletions
--- a/kernel/trunk/docs/sysfuncr.txt
+++ b/kernel/trunk/docs/sysfuncr.txt
@@ -2217,11 +2217,10 @@ dword-значение цвета 0x00RRGGBB
 Замечания:
  * Структура таблицы цветов описана в стандартном включаемом файле
    macros.inc под названием system_colors; например, можно писать:
-    	sc	system_colors		; объявление переменной
-    	...				; где-то надо вызвать
-    					; описываемую функцию с ecx=sc
-    	mov	ecx, [sc.work_button_text]	; читаем цвет текста
-    					; на кнопке в рабочей области
+      sc  system_colors ; объявление переменной
+      ...               ; вызов описываемой функции с ecx = sc
+      mov ecx, [sc.work_button_text]  ; устанавливаем цвет текста
+                                      ; на кнопке в рабочей области
  * Таблица может быть больше (до 192 байт); дополнительные поля
    копируются как есть и интерпретируются скинами.
  * Использование/неиспользование этих цветов - дело исключительно
@@ -2493,6 +2492,7 @@ dword-значение цвета 0x00RRGGBB

 ---------------------- Константы для регистров: ----------------------
  eax - SF_SET_WINDOW_SHAPE (50)
+
 ======================================================================
 ===================== Функция 51, подфункция 1 =======================
 ========================== Создать поток =============================
@@ -2510,6 +2510,7 @@ dword-значение цвета 0x00RRGGBB
  eax - SF_CREATE_THREAD (51) / SF_THREAD_CONTROL (51)
  ebx - SSF_CREATE_THREAD (1), SSF_GET_CURR_THREAD_SLOT (2),
        SSF_GET_THREAD_PRIORITY (3), SSF_SET_THREAD_PRIORITY (4)
+
 ======================================================================
 ===================== Функция 51, подфункция 2 =======================
 ============= Получить номер слота текущего потока ===================
@@ -2759,10 +2760,10 @@ IPC применяется для посылок сообщений от одн
 Программе доступны данные графического экрана (область памяти, которая
 собственно и отображает содержимое экрана) напрямую без вызовов
 системных функций через селектор gs:
-	mov	eax, [gs:0]
+  mov eax, [gs:0]
 поместит в eax первый dword буфера, содержащий информацию о цвете
 левой верхней точки (и, возможно, цвета нескольких следующих).
-	mov	[gs:0], eax
+  mov [gs:0], eax
 при работе в режимах VESA c LFB
 установит цвет левой верхней точки
 (и возможно, цвета нескольких следующих).
@@ -3360,19 +3361,21 @@ Architecture Software Developer's Manual, Volume 3, Appendix B);
 ---------------------- Константы для регистров: ----------------------
  eax - SF_SYS_MISC (68)
  ebx - SSF_MEM_FREE (13)
+
 ======================================================================
 ====================== Функция 68, подфункция 14 =====================
-========== Получить событие ядра (обертка GetEvent). ==========
+====== Ожидать получения сигнала от других приложений/драйверов. =====
 ======================================================================
 Параметры:
  * eax = 68 - номер функции
  * ebx = 14 - номер подфункции
-  * ecx = указатель на буфер данных (6 dword = 24 байта)
+  * ecx = указатель на буфер для информации (24 байта)
 Возвращаемое значение:
-  * eax = дескриптор события
+  * eax разрушается
  * буфер, на который указывает ecx, содержит следующую информацию:
-    * +0: dword: EVENT.code (идентификатор последующих данных)
-    * +4: 5 dword: EVENT.data, формат зависит от EVENT.code
+    * +0: dword: идентификатор последующих данных сигнала
+    * +4: 5 dword: данные принятого сигнала, формат которых
+          определяется первым dword-ом
 Замечания:
  * Бесконечно ожидает любое событие в очереди событий текущего потока.
  * Сбрасывает байт приоритета в буфере.
@@ -3380,48 +3383,54 @@ Architecture Software Developer's Manual, Volume 3, Appendix B);
 ---------------------- Константы для регистров: ----------------------
  eax - SF_SYS_MISC (68)
  ebx - SSF_WAIT_SIGNAL (14)
+
 ======================================================================
-=========== Функция 68, подфункция 16 - получить сервис. ===========
+=========== Функция 68, подфункция 16 - загрузить драйвер. ===========
 ======================================================================
 Параметры:
  * eax = 68 - номер функции
  * ebx = 16 - номер подфункции
-  * ecx = указатель на ASCIIZ-строку с именем сервиса
+  * ecx = указатель на ASCIIZ-строку с именем драйвера
 Возвращаемое значение:
-  * eax = указатель на структуру SRV, 0 при ошибке
+  * eax = хэндл драйвера
+          0 при ошибке
 Замечания:
-  * Если сервис ещё не загружен, ядро пытается загрузить его из
-    /sys/drivers/<name>.sys.
-  * Имя сервиса чувствительно к регистру символов.
+  * Если драйвер ещё не загружен, он загружается;
+    если драйвер уже загружен, ничего не меняется.
+  * Имя драйвера чувствительно к регистру символов.
    Максимальная длина имени - 16 символов, включая завершающий
    нулевой символ, остальные символы игнорируются.
+  * Драйвер с именем "ABC" загружается из файла /sys/drivers/ABC.sys.

 ---------------------- Константы для регистров: ----------------------
  eax - SF_SYS_MISC (68)
-  ebx - SSF_GET_SERVICE (16) / SSF_LOAD_DRIVER (16)
+  ebx - SSF_LOAD_DRIVER (16) / SSF_GET_SERVICE (16)
+
 ======================================================================
-========== Функция 68, подфункция 17 - вызвать сервис. =========
+========== Функция 68, подфункция 17 - управление драйвером. =========
 ======================================================================
 Параметры:
  * eax = 68 - номер функции
  * ebx = 17 - номер подфункции
-  * ecx = указатель на структуру IOCTL:
-    * +0:  dword: хэндл сервиса (указатель на SRV)
-    * +4:  dword: io_code
-    * +8:  dword: указатель на входные данные
-    * +12: dword: размер входных данных
-    * +16: dword: указатель на выходные данные
-    * +20: dword: размер выходных данных
+  * ecx = указатель на управляющую структуру:
+    * +0: dword: хэндл драйвера
+    * +4: dword: код функции драйвера
+    * +8: dword: указатель на входные данные
+    * +12 = +0x0C: dword: размер входных данных
+    * +16 = +0x10: dword: указатель на выходные данные
+    * +20 = +0x14: dword: размер выходных данных
 Возвращаемое значение:
-  * eax = значение, возвращаемое обработчиком сервиса, -1 при ошибке
+  * eax = определяется драйвером
+          -1 при ошибке
 Замечания:
  * Коды функций и структура входных/выходных данных
-    определяются сервисом.
-  * Хэндл сервиса можно получить подфункцией 16.
+    определяются драйвером.
+  * Хэндл драйвера необходимо предварительно получить подфункцией 16.

 ---------------------- Константы для регистров: ----------------------
  eax - SF_SYS_MISC (68)
-  ebx - SSF_CALL_SERVICE (17) / SSF_CONTROL_DRIVER (17)
+  ebx - SSF_CONTROL_DRIVER (17) / SSF_CALL_SERVICE (17)
+
 ======================================================================
 == Функция 68, подфункция 18 - загрузить DLL с указанием кодировки. ==
 ======================================================================
@@ -3678,7 +3687,7 @@ Architecture Software Developer's Manual, Volume 3, Appendix B);
  * функция загружает и, при необходимости, распаковывает файл (kunpack)

 ======================================================================
-======== Функция 68, подфункция 29 - выделить кольцевую память. =========
+======= Функция 68, подфункция 29 - выделить кольцевую память. =======
 ======================================================================
 Параметры:
  * eax = 68 - номер функции
@@ -3810,7 +3819,7 @@ Architecture Software Developer's Manual, Volume 3, Appendix B);
    и при поступлении нового сообщения система будет ждать.
    Для синхронизации обрамляйте всю работу с буфером операциями
    блокировки/разблокировки
-    	neg	[bufsize]
+      neg [bufsize]
  * Данные в буфере трактуются как массив элементов переменной длины -
    сообщений. Формат сообщения указан в общем описании.

@@ -4693,7 +4702,7 @@ Architecture Software Developer's Manual, Volume 3, Appendix B);
  eax - SF_NETWORK_GET (74) / SF_NETWORK_DEVICE (74)
   bl - SSF_LINK_STATUS (10)
 ======================================================================
-== Функция 74.11, Получить количество пакетов переданных с ошибкой. ==
+== Функция 74.11, Получить количество пакетов переданных с ошибкой. ==
 ======================================================================
 Параметры:
  * eax = 74 - номер функции
@@ -4707,7 +4716,7 @@ Architecture Software Developer's Manual, Volume 3, Appendix B);
  eax - SF_NETWORK_GET (74) / SF_NETWORK_DEVICE (74)
   bl - SSF_TX_PACKET_ERROR_COUNT (11)
 ======================================================================
-=== Функция 74.12, Получить число пакетов отброшенных при отправке. ==
+=== Функция 74.12, Получить число пакетов отброшенных при отправке. ==
 ======================================================================
 Параметры:
  * eax = 74 - номер функции
@@ -4721,7 +4730,7 @@ Architecture Software Developer's Manual, Volume 3, Appendix B);
  eax - SF_NETWORK_GET (74) / SF_NETWORK_DEVICE (74)
   bl - SSF_TX_PACKET_DROP_COUNT (12)
 ======================================================================
-=== Функция 74.13, Получить число пакетов утерянных при отправке. ====
+=== Функция 74.13, Получить число пакетов утерянных при отправке. ====
 ======================================================================
 Параметры:
  * eax = 74 - номер функции
@@ -4736,7 +4745,7 @@ Architecture Software Developer's Manual, Volume 3, Appendix B);
   bl - SSF_TX_PACKET_MISS_COUNT (13)

 ======================================================================
-==== Функция 74.14, Получить число пакетов полученных с ошибкой. =====
+==== Функция 74.14, Получить число пакетов полученных с ошибкой. =====
 ======================================================================
 Параметры:
  * eax = 74 - номер функции
@@ -4745,12 +4754,13 @@ Architecture Software Developer's Manual, Volume 3, Appendix B);
 Возвращаемое значение:
  * eax = число пакетов, полученных с ошибкой с момента запуска 
    устройства, -1 при ошибке
-	
+
 ---------------------- Константы для регистров: ----------------------
  eax - SF_NETWORK_GET (74) / SF_NETWORK_DEVICE (74)
   bl - SSF_RX_PACKET_ERROR_COUNT (14)
+
 ======================================================================
-== Функция 74.15, Получить число пакетов отброшенных при получении. ==
+== Функция 74.15, Получить число пакетов отброшенных при получении. ==
 ======================================================================
 Параметры:
  * eax = 74 - номер функции
@@ -4764,7 +4774,7 @@ Architecture Software Developer's Manual, Volume 3, Appendix B);
  eax - SF_NETWORK_GET (74) / SF_NETWORK_DEVICE (74)
   bl - SSF_RX_PACKET_DROP_COUNT (15)
 ======================================================================
-=== Функция 74.16, Получить число пакетов утерянных при получении. ===
+=== Функция 74.16, Получить число пакетов утерянных при получении. ===
 ======================================================================
 Параметры:
  * eax = 74 - номер функции
@@ -5074,10 +5084,11 @@ Architecture Software Developer's Manual, Volume 3, Appendix B);
  * ebx = 2 - номер подфункции
  * ecx = дескриптор фьютекса
  * edx = контрольное значение
-  * esi = таймаут в тиках системного таймера, 0 - ждать бесконечно
+  * esi = таймаут в сотых секунды, 0 - ждать бесконечно
 Возвращаемое значение:
-  * eax = 0 - успешно, -1 - таймаут,
-        -2 - контрольное значение не соответствует
+  * eax = 0 - успешно,
+         -1 - таймаут,
+         -2 - контрольное значение не соответствует

 ---------------------- Константы для регистров: ----------------------
  eax - SF_FUTEX (77)
@@ -5118,24 +5129,25 @@ Architecture Software Developer's Manual, Volume 3, Appendix B);
 ---------------------- Константы для регистров: ----------------------
  eax - SF_FUTEX (77)
  ebx - 10
+
 ======================================================================
-======== Функция 77, подфункция 11, Записать в pipe. =======
+======== Функция 77, подфункция 11, Записать из буфера в файл. =======
 ======================================================================
 Параметры:
  * eax = 77 - номер функции
  * ebx = 11 - номер подфункции
-  * ecx = дескриптор pipe
+  * ecx = дескриптор файла
  * edx = указатель на буфер, откуда брать данные для записи
  * esi = сколько байт записать
 Возвращаемое значение:
-  * eax = количество записанных байт, -EBADF при ошибке,
+  * eax = количество записанных байт
+          -EBADF при ошибке
          -EPIPE если нет читателей
-Замечания:
-  * Поддерживаются только pipe-дескрипторы.

 ---------------------- Константы для регистров: ----------------------
  eax - SF_FUTEX (77)
  ebx - 11
+
 ======================================================================
 =========== Функция 77, подфункция 13, Создать новый pipe. ===========
 ======================================================================
@@ -5156,6 +5168,7 @@ Architecture Software Developer's Manual, Volume 3, Appendix B);
 ---------------------- Константы для регистров: ----------------------
  eax - SF_FUTEX (77)
  ebx - 13
+
 ======================================================================
 ========== Функция -1 - завершить выполнение потока/процесса =========
 ======================================================================
@@ -5173,6 +5186,7 @@ Architecture Software Developer's Manual, Volume 3, Appendix B);

 ---------------------- Константы для регистров: ----------------------
  eax - SF_TERMINATE_PROCESS (-1)
+
 ======================================================================
 === Функция 80 - работа с файловой системой с указанием кодировки. ===
 ======================================================================
--- a/kernel/trunk/docs/sysfuncs.txt
+++ b/kernel/trunk/docs/sysfuncs.txt
@@ -2179,7 +2179,7 @@ Parameters:
  * ecx = pointer to the buffer with size edx bytes,
    where table will be written
  * edx = size of color table
-    (up to 192 bytes; 40 bytes for base structure)
+    (must be 40 bytes for future compatibility)
 Returned value:
  * function does not return value
 Format of the color table:
@@ -2480,7 +2480,7 @@ Remarks:
 ---------------------- Constants for registers: ----------------------
  eax - SF_SET_WINDOW_SHAPE (50)
 ======================================================================
-==================== Function 51 - create thread. ====================
+============= Function 51, subfunction 1 - create thread. ============
 ======================================================================
 Parameters:
  * eax = 51 - function number
@@ -3334,14 +3334,14 @@ Remarks:
  ebx - SSF_MEM_FREE (13)
 ======================================================================
 ===================== Function 68, subfunction 14 ====================
-================= Get kernel event (GetEvent wrapper). ===============
+==== Wait for a signal from other applications/drivers. ==============
 ======================================================================
 Parameters:
  * eax = 68 - function number
  * ebx = 14 - subfunction number
  * ecx = pointer to data buffer (6 dword = 24 bytes)
 Returned value:
-  * eax = event handle
+  * eax is destroyed
  * buffer pointed to by ecx contains the following information:
    * +0: dword: EVENT.code (identifier of following data)
    * +4: 5 dword: EVENT.data, format depends on EVENT.code
@@ -3353,43 +3353,44 @@ Remarks:
  eax - SF_SYS_MISC (68)
  ebx - SSF_WAIT_SIGNAL (14)
 ======================================================================
-============= Function 68, subfunction 16 - get service. =============
+=========== Function 68, subfunction 16 - load driver. ===============
 ======================================================================
 Parameters:
  * eax = 68 - function number
  * ebx = 16 - subfunction number
-  * ecx = pointer to ASCIIZ-string with service name
+  * ecx = pointer to ASCIIZ-string with driver name
 Returned value:
-  * eax = pointer to SRV structure, 0 on error
+  * eax = driver handle, 0 on error
 Remarks:
-  * If the service is not loaded yet, the kernel attempts to load it
-    from /sys/drivers/<name>.sys.
-  * Service name is case-sensitive.
+  * If the driver is not loaded yet, it is loaded;
+    if the driver is already loaded, nothing changes.
+  * Driver name is case-sensitive.
    Maximum length of the name is 16 characters, including
    terminating null character, the rest is ignored.
+  * Driver with name "ABC" is loaded from /sys/drivers/ABC.sys.

 ---------------------- Constants for registers: ----------------------
  eax - SF_SYS_MISC (68)
  ebx - SSF_GET_SERVICE (16) / SSF_LOAD_DRIVER (16)
 ======================================================================
-============ Function 68, subfunction 17 - call service. =============
+========== Function 68, subfunction 17 - control driver. =============
 ======================================================================
 Parameters:
  * eax = 68 - function number
  * ebx = 17 - subfunction number
-  * ecx = pointer to the IOCTL structure:
-    * +0:  dword: service handle (pointer to SRV)
-    * +4:  dword: io_code
+  * ecx = pointer to the control structure:
+    * +0:  dword: driver handle
+    * +4:  dword: driver function code
    * +8:  dword: pointer to input data
    * +12: dword: size of input data
    * +16: dword: pointer to output data
    * +20: dword: size of output data
 Returned value:
-  * eax = value returned by the service handler, -1 on error
+  * eax = determined by driver, -1 on error
 Remarks:
  * Function codes and the structure of input/output data
-    are defined by the service.
-  * The service handle can be obtained by subfunction 16.
+    are defined by the driver.
+  * Driver handle can be obtained by subfunction 16.

 ---------------------- Constants for registers: ----------------------
  eax - SF_SYS_MISC (68)
@@ -3662,10 +3663,6 @@ Remarks:
    write beyond the size of the allocated memory and will reach the 
    beginning of the buffer again.

---------------------- Constants for registers: ----------------------
-  eax - SF_SYS_MISC (68)
-  ebx - SSF_MEM_ALLOC_RING (29)  
-
 ======================================================================
 =========== Function 68, subfunction 30 - unload driver. ============
 ======================================================================
@@ -3898,7 +3895,7 @@ Remarks:
  eax - SF_DEBUG (69)
  ebx - SSF_RESUME (5)
 ======================================================================
-= Fucntion 69, subfunction 6 - read from memory of debugged process. =
+== Function 69, subfunction 6 - read from memory of debugged process. ==
 ======================================================================
 Parameters:
  * eax = 69 - function number
@@ -5274,10 +5271,6 @@ Parameters:
  * ecx = pointer to futex dword
 Returned value:
  * eax = futex handle, 0 on error
-Remarks:
-  * Use subfunction 1 to destroy the futex.
-    The kernel destroys the futexes automatically when the process
-    terminates.

 ---------------------- Constants for registers: ----------------------
  eax - SF_FUTEX (77)
@@ -5292,7 +5285,8 @@ Parameters:
 Returned value:
  * eax = 0 - successfull, -1 on error
 Remarks:
-  * The futex handle must have been created by subfunction 0
+  * The kernel destroys the futexes automatically when the process
+    terminates.

 ---------------------- Constants for registers: ----------------------
  eax - SF_FUTEX (77)
@@ -5305,16 +5299,11 @@ Parameters:
  * ebx = 2 - subfunction number
  * ecx = futex handle
  * edx = control value
-  * esi = timeout in system ticks or 0 for infinity
+  * esi = timeout in hundredths of a second, 0 - wait forever
 Returned value:
  * eax = 0 - successfull
         -1 - timeout
         -2 - futex dword does not have the same value as edx
-Remarks:
-  * This function tests that the value at the futex dword still
-    contains the expected control value, and if so, then sleeps
-    waiting for a wake operation on the futex.
-  * The futex handle must have been created by subfunction 0

 ---------------------- Constants for registers: ----------------------
  eax - SF_FUTEX (77)
@@ -5330,11 +5319,6 @@ Parameters:
 Returned value:
  * eax = number of waiters that were woken up

-Remarks:
-  * This function wakes at most edx of the waiters that are
-    waiting (e.g., inside futex wait) on the futex dword
-  * The futex handle must have been created by subfunction 0
-
 ---------------------- Constants for registers: ----------------------
  eax - SF_FUTEX (77)
  ebx - SSF_WAKE (3)