- The Linux Kernel documentation¶
- Licensing documentation¶
- User-oriented documentation¶
- Firmware-related documentation¶
- Application-developer documentation¶
- Introduction to kernel development¶
- Kernel API documentation¶
- How to view and browse the linux kernel source?
- Kernel tree root directory:
- About the author
- David Adams
- Linux kernel development для самых маленьких
- 0. Подготовка
- 1. Mail
- 2. Git
- 3. Coding
- 4. Kernel build
- 5. Patches
- 6. Debuging
The Linux Kernel documentation¶
This is the top level of the kernel’s documentation tree. Kernel documentation, like the kernel itself, is very much a work in progress; that is especially true as we work to integrate our many scattered documents into a coherent whole. Please note that improvements to the documentation are welcome; join the linux-doc list at vger.kernel.org if you want to help out.
Licensing documentation¶
The following describes the license of the Linux kernel source code (GPLv2), how to properly mark the license of individual files in the source tree, as well as links to the full license text.
User-oriented documentation¶
The following manuals are written for users of the kernel — those who are trying to get it to work optimally on a given system.
Firmware-related documentation¶
The following holds information on the kernel’s expectations regarding the platform firmwares.
Application-developer documentation¶
The user-space API manual gathers together documents describing aspects of the kernel interface as seen by application developers.
Introduction to kernel development¶
These manuals contain overall information about how to develop the kernel. The kernel community is quite large, with thousands of developers contributing over the course of a year. As with any large community, knowing how things are done will make the process of getting your changes merged much easier.
Kernel API documentation¶
These books get into the details of how specific kernel subsystems work from the point of view of a kernel developer. Much of the information here is taken directly from the kernel source, with supplemental material added as needed (or at least as we managed to add it — probably not all that is needed).
Источник
How to view and browse the linux kernel source?
The source directory contains the following subdirectories called kernel tree, learning the structure of the kernel tree and the function of each path is the first step to start browsing the kernel.
Kernel tree root directory:
Documentation/: kernel source documentation.
LICENSES/: It contains the licenses to be applied to the kernel source and individual source files which may have different licenses. Inside this directory you will find 3 subdirectories: preferred (GNU GPL), exceptions listed in the COPYING file and other.
arch/: source codes for specific architectures (e.g powerpc, x86,etc). Inside this directory you’ll find subdirectories belonging to each supported architecture lie i386, sparc, arm, etc.
block/: block I/O layer, contains code for the management of block devices (such as hard disks, dvd, floppy disks, etc.) and their requests.
Certs/: certificates and sign files to enable module signature to make the kernel load signed modules, this can be useful to prevent malicious code from running with kernel modules like rootkits.
Crypto/: Crypto API. Contains cryptographic ciphers which handles cryptographic and compression tasks.
drivers/: Hardware device drivers. Contains code of device drivers to support hardware, inside this directory you’ll find subdirectories for each hardware such as video, bluetooth,etc (any hardware supported).
ipc/: Inter-Process Communication such as signals and pipes.
kernel/: Core subsystems, such as the scheduler signal handling code, etc.
lib/: library routines common string operations, hardware dependent operations, debugging routines and command line parsing code.
mm/: Memory management and virtual memory. The kernel manages both the hardware and virtual memory (swap). This directory stores code for the memory management.
net/: Network stack. Contains code related to communication protocols such as IP, TCP,UP, etc.
samples/: sample code and configuration files.
scripts/: scripts to build the kernel.
sound/: The sound subsystem, here you’ll find sound drivers and code related to sound such as ALSA,
tools/: tools for compressed kernel development such as ACPI, cgroup, USB testing tools, vhost test module, GPIO, IIO and spi tools, Inter energy policy tool among more.
virt/: Virtualization, this directory contains the KVM (Kernel Virtual Machine) module for hypervisor.
These are the main subdirectories of the kernel tree and their function, hope its helpful for you.
About the author
David Adams
David Adams is a System Admin and writer that is focused on open source technologies, security software, and computer systems.
Источник
Linux kernel development для самых маленьких
Любой программист знает, что теоретически он может внести свой посильный вклад в развитие Linux ядра. С другой стороны, подавляющее большинство уверено, что занимаются этим исключительно небожители, а процесс контрибьюта в ядро настолько сложен и запутан, что обычному человеку разобраться в нём нет никакой возможности. А значит, и надобности.
Сегодня мы попробуем развеять эту легенду и покажем, как абсолютно любой инженер при наличии достойной идеи, воплощённой в коде, может предложить ее на рассмотрение Linux community для включения в ядро.
0. Подготовка
Как и перед любой инженерной операцией, всё начинается с подготовки своего рабочего места. И первейшее здесь действие — это завести себе аккаунт с адекватным именем. В идеальном мире это будет просто транскрипция имени и фамилии. Если за учётку вроде MamkinC0d$r или Developer31337 в других местах пальцем в вас тыкать не будут, то правила LKC (Linux kernel community) такое прямо запрещают — инкогнито контрибьютить в ядро не принято.
Далее вам понадобится место на локальной машине. Сама папка Linux со скачанными исходниками весит чуть меньше 3-х гигов. Но если ядро пробовать собирать, то вместе с модулями займёт все 30 GB.
Захотелось собрать несколько веток? Умножаем 30 на число веток.
И помним — скорость сборки прямо связана с количеством доступных ядер! Больше ядер — быстрее соберётся. Так что не стесняйтесь выделять под это самую мощную машину.
1. Mail
Самый спорный и поэтому регулярно вызывающий споры момент — это канал коммуникации с LKC. Он безальтернативно один. Почта. Причём сообщения отправляются по классике через smtp.
Вокруг необходимости делать всё через плейнтекст в почте есть масса споров. Недавно в сети была очередная громкая статья на эту тему. Суть материала: письма — это, конечно, здорово, но пихать туда всё, включая куски кода — это вам (т.е. LKC) популярности не добавляет и даже наоборот, отпугивает новичков. С одной стороны вроде и да, если ты не можешь спокойно и структурировано изложить свои мысли в голом тексте, то в низкоуровневой разработке ловить будет особо нечего. С другой стороны, слать в письмах сорсы патчей — это даже архаизмом назвать уже сложно.
Но, как принято в уютном мирке ядра, Линус хлопнул кулаком по столу — и все пишут письма. Возможно, буквально завтра это изменится, но на момент выхода статьи это письма и только письма.
Какой email-client выбрать — есть рекомендации. Самым рекомендуемым почтовым агентом для LKC остаётся mutt. Да, тот самый текстовый почтовый клиент, от которого сводит олдскулы. Для начала mutt нужно поставить (я думаю, со своим пакетным менеджером вы и сами справитесь), а потом задать параметры в файле
Но почты недостаточно. Без Git никуда.
2. Git
Прежде чем что-то делать с исходниками ядра, нужно настроить Git. Можно конфигурировать файлы напрямую, но есть упрощающая жизнь утилита git config, через которую можно регулировать все аспекты работы Git’a.
Внутри есть три уровня настроек: общие для всех пользователей системы и для всех репозиториев (git config —system), общие для всех репозиториев конкретного пользователя (git config —global), отдельные для каждого репозитория (git config —local).
Глобальные настройки хранятся в /etc/gitconfig, настройки пользователя в
/.config/git/config, а настройки отдельных репозиториев хранятся в файле config в каталоге .git/config.
В общем случае будет достаточно законфигурировать файл для пользователя
/.gitconfig . Основная идея: при отправке коммитов должно отображаться ваше корректное имя.
Примечательно, что параметр sslVerify = true препятствует работе с Git напрямую через git://git.kernel.org и форсит доступ только через https://git.kernel.org . Так, наверное, секьюрнее, хотя какого-то смысла я в этом не вижу. Но, может, чего-то не знаю?
signOff обязателен, чтоб в коммитах была информация об авторе. По идее, надо бы, чтобы коммиты подписывались. Была тут недавно статья на эту тему.
Отправка патча выполняется командой git send-email. У git send-email есть несколько параметров с участием smtp, которые можно (и нужно) переопределить.
Полезный параметр —smtp-debug=1. Осуществляет логирование SMTP запросов и ответов, что помогает при разборе проблем с настройками почты. Например, я столкнулся с тем, что почтовый сервер, на котором есть у меня почтовый ящик, не поддерживает TLS. Возможны проблемы с аутентификацией, а сообщения об ошибке git send-email выдаёт не особо разнообразные и адекватные.
Можно задавать пароль к почте через параметр —smtp-pass=p4ssw0rd или вообще захардкорить в конфиге, но это это для тех, кому терять нечего. Но если каждый раз вводить пароль лень, то есть некий хак: если username был задан (через —smtp-user или sendmail.smtpUser), а пароль не указан, тогда пароль получается через git-credential.
Итак, окно в большой мир прорубили. Можно переходить к воплощению своей грандиозной идеи в коде.
3. Coding
Итак, мы готовы сделать первый шаг непосредственно в разработке — склонировать к себе репозиторий. Советую делать это сразу с указанием ветки, которая будет создана. Также отмечу, что работать лучше не над текущим состоянием в master, а над стабильной версией или кандидатом на релиз. Так вы будете более уверены, что ядро соберётся и будет как-то работать, не вызовет неожиданных конфликтов из-за изменений в других подсистемах. Поэтому всегда внимательно смотрите тэги.
И — опять же — имя своей ветке постарайтесь дать чёткое и лаконичное. В идеальном мире оно даже может отображать суть вносимых изменений. Если вы исправляете известный баг, то хорошим тоном считается включить в название ветки номер issue.
Операция довольно долгая, так что смело можно идти за кофе или на обед. А если попробовать ускорить процесс, отказавшись от истории, то работать с «этим» будет невозможно.
Итак, мы получили ветку, в которой можно начинать свою разработку. Здесь всё очевидно: пишем код, собираем, тестируем, исправляем баги — и так до получения нужного результата. О том, как собирать ядро и проводить отладку, информации в сети море, так что подробно описывать весь процесс я не буду. Лишь вкратце пробежимся по нему чуть позже. Единственный нюанс, который добавлю от себя прямо сейчас: перед сборкой проверьте наличие всех необходимых программ из этого списка и их минимальные версии.
Если бродить вслепую по гуглу не хочется, то вся максимально полезная информация по ядру сконцентрирована тут. Прочитать стоит действительно всё. Особенно правильно будет начать с How To о том, как правильно коммуницировать. Потому что мейнтейнеры, как правило, люди весьма занятые, и вникать в невнятно составленные письма им никакого интереса. Да и вам будет обидно, если из-за плохого описание ваше детище не примут в апстрим.
И вот свой небольшой и эффективный код вы написали, отладили, всё протестировали и готовы отправлять на рассмотрение. Но не спешите этого делать. Для начала обязательно проверьтесь на code style. В этом вам поможет ./script/checkpatch.pl . Для этого сделаем патч и отправим его на проверку.
После того, как пройдёт первое удивление и вы доустановите необходимые компоненты для python2 типа ply и git (который у меня так и не установился), наступит чудесное время исправления ошибок и ворнингов. По результатам которых вы а) поймёте, что красивый код писать вы не умеете б) потеряете всякое желание что-то куда-то отправлять. Ведь даже если отбросить все шутки, ещё можно как-то смириться с тем, что длина строк ограничена 100 символами (это начиная с версии 5.7, раньше так было вообще 80). Но вот такие места оставляют неизгладимое впечатление:
Для .h файлов строка с информацией о лицензии должна быть в ремарках / * */, а для *.c файлов должна быть в ремарках //. Такое запросто выбьет кого угодно из душевного равновесия. Вопрос: «Зачем?!» до сих пор болтается в моей голове, хотя есть вера в то, что это не просто ошибка в скриптах.
Кстати, чтобы просто проверить один файл достаточно вызвать
Можно прикрутить этот вызов к git, чтобы автоматически запускался этот скрипт при попытке что-то зачекинить.
Ещё важное замечание: clang-format добрался и до ядра Linux. Файл .clang-format расположился в корне ядра в кучке с другими конфигами. Но я не советую добавлять его в хук для git. Лучше всего корректно настроить среду разработки и запомнить code style. Лично мне не понравилось как он делает переносы длинных строк. Если вдруг строка оказалась длиннее допустимой, то скорее всего функция, в которой эта строка расположилась, является кандидатом на рефакторинг, и лучше его не откладывать. С другой стороны, если у вас много уже готового кода который нужно адаптировать для ядра — clang-format может сильно облегчить вам задачу.
4. Kernel build
Несмотря на то, что процесс описан в других статьях тут и тут, я все же повторюсь.
По шагам процесс сборки ядра довольно прост, если не вдаваться в детали. Для начала ставим необходимые пакеты (использовался Debian 10):
Это без компилятора и обычного для С/С++ разработчика набора программ.
Запускаем конфигурацию:
Тут есть интересный аспект: в качестве шаблона будет браться config ядра от вашего боевого ядра, которое, скорее всего, подготовлено дистрибьютером. Для Debian 10 сборка проходит успешно, если в конфиге потереть информацию о встраиваемых в ядро сертификатах.
Перед попыткой собрать проверьте, что нужные программы уже установлены. Список тут. Чтобы собрать само ядро:
Этого достаточно для проверки собираемости, но недостаточно для запуска ядра в системе, так как без модулей ядро на реальной системе практически беспомощно.
Если какой-то модуль не собирается, просто вырубите его в ближайшем Makefile-е (если 100% уверены, что не пытались в нём что-то улучшить). Наверняка он вам не пригодится, и тратить время на исправления смысла нет.
Теперь можно деплоить то, что получилось, на эту же систему.
Хотя, конечно, экспериментировать с ядром на той же машине, где ведётся разработка — дело рискованное.
Поэтому как минимум нужно снять снапшот, сделать резервную копию или лучше вообще выполнять отладку на другой (лучше виртуальной) машине. Но как это делать, я пока не разбирался. Если у кого есть такой опыт — пишите в комменты, добавлю в статью.
На моей системе загрузчик после установки ядра автоматически обновился. Если у вас этого не произошло, то это делается это на Debian-подобных системах командой:
Update: Как верно заметил gavk, ядро давно уже умеет собирать пакеты, причём как для deb, так и для rpm.
Команда
выводит весь ассортимент. Так что команда
должна собрать пакет с ядром.
5. Patches
Вот теперь мы действительно подготовили код для отправки. Лучше всего, чтобы это был единственный коммит. Так проще делать ревью и так быстрее вам ответят. Всё проверив, наконец-то делаем коммит.
Ещё можно комментарии к коммиту дополнить в человеческом текстовом редакторе.
И теперь его можно оформить в виде того самого письма. Правила хорошего тона, или best practice, если угодно — это 75 символов на строку.
В результате получите два файла. В первом 000-cover-letter.patch нужно указать заголовок письма «Subject» и основное описание патча. В описании патча пишем, для чего он создавался, кому он сделает жизнь на нашей планете лучше и каким образом. Только не словоблудим про космические корабли в Большом театре, а пишем лаконично и по делу. И не в коем случае не пишите корпоративную лабуду а-ля «Без этого патча мой бизнес встанет, меня уволят, а дети мои умрут от голода». Нет, строго по существу: «Увидел вот такую проблему вот тут, починить решил вот таким образом, исходники патча прилагаю». Всё, вы восхитительны! А если не превысили 75 символов на строку, то восхитительны в квадрате.
А ещё один волшебный скриптик ./scripts/getmaintainers.pl
позволит узнать, кому письмо отправлять.
И вот он, момент отправления письма, ради которого всё и затевалось:
Дальше остаётся только сидеть и ждать ответного письма, где вам скорее всего скажут, что всё здорово, но надо ещё сделать вот это и поправить вот здесь. Возможно, придётся доказывать, что ваш функционал действительно новый и не создаёт дублирования. Хотя могут и сразу всё принять, сказав большое спасибо (шутка :-).
После того, как ваш патч был принят, крайне желательно удалить свою ветку.
6. Debuging
И чуть-чуть про отладку. Бонус «на сладкое» для начинающих разработчиков ядра, так сказать.
Как правило, при ошибке вы получаете лог с calltrace-ом. Там указываются имена функций и смещения. Примерно вот так:
Так вот, чтобы понять, в каком месте функции произошла ошибка, достаточно запустить дебагер с подгруженным в него модулем:
Важно, чтобы в модуле сохранились символы (stripped модуль вам тут не поможет).
Выполнив команду list
вы увидите строку кода, приведшую к ошибке. В случае передачи управления по неверному адресу, вы увидите следующую за ошибкой строку.
И на этом позвольте откланяться.
Буду рад вопросам и замечаниям в комментариях.
Источник