Update documentation for kernel #215

New Issue

Doczom · 2025-04-15T22:05:31+02:00

Doczom commented

2025-04-15 22:05:31 +02:00

Add documentation fro executable file formates (MENUET01/02 and KX).
Add docs for TLS - Thread local storage(errno, end stack address etc).
Added docs for driver api:

Synhronization(mutex, spinlock etc);
Kernel and thread objects;
Graphical api;
recomendations for development IOCTL functions.

Add documentation fro executable file formates (MENUET01/02 and KX). Add docs for TLS - Thread local storage(errno, end stack address etc). Added docs for driver api: - Synhronization(mutex, spinlock etc); - Kernel and thread objects; - Graphical api; - recomendations for development IOCTL functions.

👍 1

Doczom added the

labels 2025-04-15 22:05:31 +02:00

Doczom commented

2025-04-19 20:31:57 +02:00

Add documentation for executable file formates:
for sysfuncr.txt

======================================================================
================ Описание форматов исполняемых файлов. ===============
======================================================================
Все форматы исполняемых файлов представляют собой бинарные файлы, 
содержащие заголовок и код, использующий в качестве базы начало файла.
Все форматы не имеют секций и нет выставления флагов страниц, все 
страницы кода(содржащие также и данные) установленны с флагами rwx. 
======================================================================
================ Описание форматов исполняемых файлов. ===============
============================== MENUET01  =============================
======================================================================
Данный формат содержит следующий заголовок в начале файла:
  * +0: qword: значение-идентификатор формата, представляет собой 
               строку "MENUET01".
  * +8: dword: версия формата, всегда устанавливается значение 1.
  * +12 = +0x0C: dword: адрес точки входа относительно начала файла
  * +16 = +0x10: dword: адрес указывающий на конец блока кода и 
                        инициализированных данных(или конец файла)
  * +20 = +0x14: dword: адрес указывающий на конец используемой 
                        приложением памяти на момент передачи 
                        управления в точку входа, а именно:
                          - код и инициализированные данные;
                          - неинициализированные данные;
                          - участок памяти под стек;
                          - участок памяти под строку параметров
                            (256 байт);
                          - участок памяти под путь к исполняемому
                            файлу (1024 байт).
                        При инициализации процесса ядро выравнивает
                        это значение до кратного 4кб в большую строну.
  * +24 = +0x18: dword: адрес вершины стека при попадании в точку
                        входа.
  * +28 = +0x1c: dword: адрес на строку с параметрами запуска. 
                        Если программа не намерена получать параметры,
                        то следует записать значение ноль. В ином
                        случае в данную переменную записывается адрес
                        буфера на 256 байт.
                        Примечание: если длина строки параметров
                        будет превышать 256 байт с завершающим нулём,
                        то ядро изменит количество используемой 
                        памяти на размер параметров и изменит значеие
                        данного поля на новый указатель со строкой
                        параметров. 
                        Максимальный размер строки параметров: 64 кб.
  * +32 = +0x20: dword: адрес буфера под путь к исполняемому файлу.
                        Путь записан в кодировке UTF-8 и имеет 
                        вначале последовательность байт 0x2f 0x03
                        для сохранения совместимости.
======================================================================
================ Описание форматов исполняемых файлов. ===============
============================ MENUET01-KX  ============================
======================================================================
Данный формат файла идентичен MENUET01, но значение по смещению 0x8
изменено на 2 и за основным заголовком следует дополнительный:
  * +36 = +0x24: word: идентификатор заголовка, строка "KX"
  * +38 = +0x26: byte: ревизия данного формата, всегда 0.
  * +39 = +0x27: byte: SigArch, всегда 0. 
  * +40 = +0x28: word: поле содержащее набор битовых флагов:
    * bit 5 - заголовок содержит таблицу экспорта(не реализовано)
    * bit 6 - заголовок содержит таблицу импорта
    Остальные флаги должны быть выставлены в 0.
  * +42 = +0x2A: word: зарезервировано, всегда 0
  * +44 = +0x2C: dword: адрес таблицы импорта функций из динамических 
                        библиотек. 

Данный формат исполняемого файла использует для автоматического 
импорта функций библиотеку dll.obj. Также из точки входа можно выйти
используя инструкцию "ret", которая вернёт управление в библиотеку. 

======================================================================
================ Описание форматов исполняемых файлов. ===============
============================== MENUET02  =============================
======================================================================
Данный формат специфичен для программ использующих GCC тулчейн и 
Newlib. Он расширяет изначальный формат MENUET01, меняя идентификатор
по смещению 0 на "MENUET02" и дополняя заголовок следующими полями:
  * +36 = 0x24: dword: __subsystem__, всегда 0
  * +40 = 0x28: dword: адрес начала таблицы импорта
  * +44 = 0x2c: dword: адрес конца таблицы импорта 
  * +48 = 0x30: dword: адрес функции main

Все описанные поля не учитываются ядром, но для данного формата ядро
создаёт TLS(Thread Local Storage), адресуемое через сегмент fs.
Размер TLS равен одной странице(4096 байт).

Описание структуры Thread Local Storage :
  * +0: dword: PID потока
  * +4: dword: TID потока(что-то не особо используется)
  * +8: dword: нижняя граница стека
  * +12 = +0x0c: dword: верхняя граница стека
  * +16 = +0x10: dword: TLS_KEY_LIBC

Add documentation for executable file formates: for sysfuncr.txt ``` ====================================================================== ================ Описание форматов исполняемых файлов. =============== ====================================================================== Все форматы исполняемых файлов представляют собой бинарные файлы, содержащие заголовок и код, использующий в качестве базы начало файла. Все форматы не имеют секций и нет выставления флагов страниц, все страницы кода(содржащие также и данные) установленны с флагами rwx. ====================================================================== ================ Описание форматов исполняемых файлов. =============== ============================== MENUET01 ============================= ====================================================================== Данный формат содержит следующий заголовок в начале файла: * +0: qword: значение-идентификатор формата, представляет собой строку "MENUET01". * +8: dword: версия формата, всегда устанавливается значение 1. * +12 = +0x0C: dword: адрес точки входа относительно начала файла * +16 = +0x10: dword: адрес указывающий на конец блока кода и инициализированных данных(или конец файла) * +20 = +0x14: dword: адрес указывающий на конец используемой приложением памяти на момент передачи управления в точку входа, а именно: - код и инициализированные данные; - неинициализированные данные; - участок памяти под стек; - участок памяти под строку параметров (256 байт); - участок памяти под путь к исполняемому файлу (1024 байт). При инициализации процесса ядро выравнивает это значение до кратного 4кб в большую строну. * +24 = +0x18: dword: адрес вершины стека при попадании в точку входа. * +28 = +0x1c: dword: адрес на строку с параметрами запуска. Если программа не намерена получать параметры, то следует записать значение ноль. В ином случае в данную переменную записывается адрес буфера на 256 байт. Примечание: если длина строки параметров будет превышать 256 байт с завершающим нулём, то ядро изменит количество используемой памяти на размер параметров и изменит значеие данного поля на новый указатель со строкой параметров. Максимальный размер строки параметров: 64 кб. * +32 = +0x20: dword: адрес буфера под путь к исполняемому файлу. Путь записан в кодировке UTF-8 и имеет вначале последовательность байт 0x2f 0x03 для сохранения совместимости. ====================================================================== ================ Описание форматов исполняемых файлов. =============== ============================ MENUET01-KX ============================ ====================================================================== Данный формат файла идентичен MENUET01, но значение по смещению 0x8 изменено на 2 и за основным заголовком следует дополнительный: * +36 = +0x24: word: идентификатор заголовка, строка "KX" * +38 = +0x26: byte: ревизия данного формата, всегда 0. * +39 = +0x27: byte: SigArch, всегда 0. * +40 = +0x28: word: поле содержащее набор битовых флагов: * bit 5 - заголовок содержит таблицу экспорта(не реализовано) * bit 6 - заголовок содержит таблицу импорта Остальные флаги должны быть выставлены в 0. * +42 = +0x2A: word: зарезервировано, всегда 0 * +44 = +0x2C: dword: адрес таблицы импорта функций из динамических библиотек. Данный формат исполняемого файла использует для автоматического импорта функций библиотеку dll.obj. Также из точки входа можно выйти используя инструкцию "ret", которая вернёт управление в библиотеку. ====================================================================== ================ Описание форматов исполняемых файлов. =============== ============================== MENUET02 ============================= ====================================================================== Данный формат специфичен для программ использующих GCC тулчейн и Newlib. Он расширяет изначальный формат MENUET01, меняя идентификатор по смещению 0 на "MENUET02" и дополняя заголовок следующими полями: * +36 = 0x24: dword: __subsystem__, всегда 0 * +40 = 0x28: dword: адрес начала таблицы импорта * +44 = 0x2c: dword: адрес конца таблицы импорта * +48 = 0x30: dword: адрес функции main Все описанные поля не учитываются ядром, но для данного формата ядро создаёт TLS(Thread Local Storage), адресуемое через сегмент fs. Размер TLS равен одной странице(4096 байт). Описание структуры Thread Local Storage : * +0: dword: PID потока * +4: dword: TID потока(что-то не особо используется) * +8: dword: нижняя граница стека * +12 = +0x0c: dword: верхняя граница стека * +16 = +0x10: dword: TLS_KEY_LIBC ```

Doczom commented

2025-08-03 15:31:45 +02:00

Предварительная версия главы документации по библиотекам

======================================================================
================= Динамически подключаемые библиотеки ================
======================================================================
Данный раздел описывает особенностей написания и поддержки DLL.
Система поддерживает возможность создания и использования динамически
подключаемых библиотек(DLL) в формате MS COFF на уровне ядра.


Формат DLL представляет собой файл в формате MS COFF обладающий
публичным символом "EXPORTS", указывающим на таблицу экспорта функций
DLL. Таблица экспорта функций предстваляет собой массив из элементов,
состоящих из двух указателей: по смещению 0 указатель на имя функции
в ASCII формате, завершающийся символом '\0', по смещению 4 находится
указатель на функцию. Данный массив завершается элементом, содержащим
нули во всех полях.

Как таковой точки входа(dll_entry) в данной реализации библиотек нет,
но присутствует возможность добавить первым элементом в массив функцию
с наименованием "lib_init"(в реальности "lib_" достаточно).
Данная функция получает следующие параметры:
       eax - Указатель на функцию выделения страниц памяти
       ebx - Указатель на функцию освобождения страниц памяти
       ecx - Указатель на функцию релокации страниц памяти
       edx - Указатель на функцию dll.load

При написании данной функции необходимо учитывать, что функция может
быть вызвана множество раз, при этлом таблица импорта может быть
загруженна только один раз и повторная загрузка может привести к
ошибкам во время загрузки программ.

Динамические библиотеки могут быть загруженны из любой директории.
Для упрощения создания и использования библиотек в файлах системы
присутствуют следующие макросы:
             Library
             import
             export

Предварительная версия главы документации по библиотекам ``` ====================================================================== ================= Динамически подключаемые библиотеки ================ ====================================================================== Данный раздел описывает особенностей написания и поддержки DLL. Система поддерживает возможность создания и использования динамически подключаемых библиотек(DLL) в формате MS COFF на уровне ядра. Формат DLL представляет собой файл в формате MS COFF обладающий публичным символом "EXPORTS", указывающим на таблицу экспорта функций DLL. Таблица экспорта функций предстваляет собой массив из элементов, состоящих из двух указателей: по смещению 0 указатель на имя функции в ASCII формате, завершающийся символом '\0', по смещению 4 находится указатель на функцию. Данный массив завершается элементом, содержащим нули во всех полях. Как таковой точки входа(dll_entry) в данной реализации библиотек нет, но присутствует возможность добавить первым элементом в массив функцию с наименованием "lib_init"(в реальности "lib_" достаточно). Данная функция получает следующие параметры: eax - Указатель на функцию выделения страниц памяти ebx - Указатель на функцию освобождения страниц памяти ecx - Указатель на функцию релокации страниц памяти edx - Указатель на функцию dll.load При написании данной функции необходимо учитывать, что функция может быть вызвана множество раз, при этлом таблица импорта может быть загруженна только один раз и повторная загрузка может привести к ошибкам во время загрузки программ. Динамические библиотеки могут быть загруженны из любой директории. Для упрощения создания и использования библиотек в файлах системы присутствуют следующие макросы: Library import export ```

Doczom referenced this issue

2025-08-03 15:40:20 +02:00

Ошибка в dll.inc при импорте неиспользуемых библиотек #273

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: KolibriOS/kolibrios#215