Справочник по исходному коду ядра KolibriOS

Internal structure and you change requests/suggestions
Post Reply
User avatar
rgimad
Posts: 155
Joined: Mon Apr 06, 2020 1:09 pm
Has thanked: 2 times

Справочник по исходному коду ядра KolibriOS

Post by rgimad »

Решил написать полный справочник (которого так не хватает) по исходному коду ядра Колибри, выкладываю то, что получилось на данный момент.
Пока идея документа простая, для каждого файла исходного кода описать, какие функции и структуры данных в нем реализуются, как они работают и зачем они нужны.
Знаю, в Вики подробно описана концепция работы ядра, но к сожалению она не описывает большинство внутренних функций и структур ядра, а только самые самые основные. Также стоит сказать, что некоторые участки ядра неплохо прокомментированы в самом коде, в то время как попадаются и места где комментарии полностью отсутствуют. В результате, я начал писать справочник.
P.S. в файле в некоторых местах встречаются пометки TODO вместо описаний а также пока не рассмотрены многие файлы кода, было бы очень хорошо если участники нашего сообщества, которые имеют более глубокие познания во внутренностях ядра, дополнили бы данный документ :D

UPD: Перенесено в Wiki: http://wiki.kolibrios.org/wiki/Kernel_code/ru и развивается там.
Attachments
kolibri_kernel_sources_map_v0.0.2.txt
(37.62 KiB) Downloaded 147 times
Last edited by rgimad on Fri May 14, 2021 4:09 pm, edited 1 time in total.
The best way to predict the future is to create it.
User avatar
dunkaist
Mentor
Posts: 728
Joined: Mon Oct 19, 2009 10:58 am
Been thanked: 2 times

Re: Справочник по исходному коду ядра KolibriOS

Post by dunkaist »

Documentation is vital for KolibriOS development and your effort is very appreciated.

Some thoughts on this:
  1. There is no reason to keep description of a function in a separate file from its body.
  2. Same for more high-level logic. CleverMouse set a quite high standard of documentation that I see no reason to not follow (except lazyness of course).
  3. May be it's time to proceed with discussion of in-code documentation?
User avatar
rgimad
Posts: 155
Joined: Mon Apr 06, 2020 1:09 pm
Has thanked: 2 times

Re: Справочник по исходному коду ядра KolibriOS

Post by rgimad »

dunkaist wrote:Documentation is vital for KolibriOS development and your effort is very appreciated.

Some thoughts on this:
  1. There is no reason to keep description of a function in a separate file from its body.
  2. Same for more high-level logic. CleverMouse set a quite high standard of documentation that I see no reason to not follow (except lazyness of course).
  3. May be it's time to proceed with discussion of in-code documentation?
1) I think it is convenient to have descriptions of all function in one place along with the comments in code. For example to overview the kernel structure its quite easier to learn documentation in one file (maybe with internal hyperlinks), than open many many tabs in text editor. Also, maybe Ill add more detailed explanations on how does some things in the kernel work, so document above can become rather a book than only documentation.
2) You mean http://wiki.kolibrios.org/wiki/Style/ru ? Yes, we need to translate existing russian comments in the kernel and add missing, following one standart.
3) Yes it is good idea to add possibility to automatically make documentation files from in-code comments. Writing python script that grabs function decriptions from source code file, using regexps, would be not bad and simple solution..
The best way to predict the future is to create it.
User avatar
rgimad
Posts: 155
Joined: Mon Apr 06, 2020 1:09 pm
Has thanked: 2 times

Re: Справочник по исходному коду ядра KolibriOS

Post by rgimad »

Here is the 0.0.2 version, ive added descriptions on some things and how they work. Now still only in russian, but in future I'll translate it in english too.
Attachments
kolibri_kernel_sources_map_v0.0.2.txt
(37.62 KiB) Downloaded 203 times
The best way to predict the future is to create it.
User avatar
rgimad
Posts: 155
Joined: Mon Apr 06, 2020 1:09 pm
Has thanked: 2 times

Re: Справочник по исходному коду ядра KolibriOS

Post by rgimad »

Перенес из txt в новую страницу на Wiki: http://wiki.kolibrios.org/wiki/Kernel_code/ru . В начале страницы располагается автоматическое иерархическое оглавление, что дает большое удобство навигации. В дальнейшем справочник будет развиваться и дополняться именно на данной странице.
The best way to predict the future is to create it.
User avatar
art_zh
Kernel Developer
Posts: 1462
Joined: Fri Aug 14, 2009 1:46 am

Re: Справочник по исходному коду ядра KolibriOS

Post by art_zh »

Гм, имхо легче искать информацию в исходном асм-листинге,
чем ползать по одной плоской вики-странице.

Надо добавить граф/таблицу перекрёстных ссылок,
иначе не поймёшь где конкретная функция используется
и для чего она вообще в ядре нужна.
User avatar
rgimad
Posts: 155
Joined: Mon Apr 06, 2020 1:09 pm
Has thanked: 2 times

Re: Справочник по исходному коду ядра KolibriOS

Post by rgimad »

art_zh wrote:Гм, имхо легче искать информацию в исходном асм-листинге,
чем ползать по одной плоской вики-странице.
В идеале, конечно, неплохо бы сделать на Doxygen или аналогах. Хотя, мне кажется что и у вики-версии есть свои плюсы: в описании функции можно написать свои пространные рассуждения о том, как и что там работает, и даже привести примеры использования. Не думаю, что в коде уместно писать настолько много и подробно..
art_zh wrote:Надо добавить граф/таблицу перекрёстных ссылок,
иначе не поймёшь где конкретная функция используется
и для чего она вообще в ядре нужна.
Помню dunkaist генерировал граф инклудов в ядре. Сделать то же самое для функций было бы классно (кстати граф выйдет гигантским :) )
Таблицу перекрестных ссылок сделать попроще, думаю добавлю. То есть в конце описания каждой функции будет "Используется в :" и набор ссылок.
The best way to predict the future is to create it.
User avatar
IgorA
Posts: 939
Joined: Mon Oct 27, 2008 10:10 pm

Re: Справочник по исходному коду ядра KolibriOS

Post by IgorA »

Файл unpacker.inc
Это lzma-распаковщик, содержит одну единственную функцию void unpack(void* packed_data, void* unpacked_data);
TODO: вопрос - как задается для данных которые нужно распаковать? т.е как эта функция определяет длину packed_data?
как эта функция определяет длину packed_data я не знаю, но сюда можно добавить:

Code: Select all

dword[packed_data + 0] -> символы 'KPCK'
dword[packed_data + 4] -> размер unpacked_data
User avatar
rgimad
Posts: 155
Joined: Mon Apr 06, 2020 1:09 pm
Has thanked: 2 times

Re: Справочник по исходному коду ядра KolibriOS

Post by rgimad »

IgorA wrote:но сюда можно добавить:

Code: Select all

dword[packed_data + 0] -> символы 'KPCK'
dword[packed_data + 4] -> размер unpacked_data
Спасибо, добавил
The best way to predict the future is to create it.
eurol
Posts: 17
Joined: Wed Apr 23, 2014 10:17 am

Re: Справочник по исходному коду ядра KolibriOS

Post by eurol »

А вообще есть такая вики, где рассказывается подробно понятным языком, как ОС грузится, раскладывается по оперативке и т.п.?
User avatar
art_zh
Kernel Developer
Posts: 1462
Joined: Fri Aug 14, 2009 1:46 am

Re: Справочник по исходному коду ядра KolibriOS

Post by art_zh »

eurol wrote:А вообще есть такая вики, где рассказывается подробно понятным языком, как ОС грузится, раскладывается по оперативке и т.п.?
https://wiki.osdev.org
eurol
Posts: 17
Joined: Wed Apr 23, 2014 10:17 am

Re: Справочник по исходному коду ядра KolibriOS

Post by eurol »

Вообще-то вопрос был про Колибри. :)
User avatar
art_zh
Kernel Developer
Posts: 1462
Joined: Fri Aug 14, 2009 1:46 am

Re: Справочник по исходному коду ядра KolibriOS

Post by art_zh »

eurol wrote:Вообще-то вопрос был про Колибри. :)

http://wiki.kolibrios.org/wiki/Kernel/ru
Post Reply

Who is online

Users browsing this forum: No registered users and 1 guest