## Участие в проекте

Приветствуются любые виды вклада, включая исправления, уточнения, новые примеры, переводы и рецензии от разработчиков FreeBSD и учащихся.

### Способы внести вклад

- **Контент:** добавление новых глав, доработка существующего материала
- **Техническая рецензия:** проверка глав на соответствие FreeBSD 14.x
- **Рецензия переводов:** помощь в рецензировании и улучшении переведённых AI изданий **pt_BR** и **es_ES**; особенно приветствуются носители языка с опытом работы с FreeBSD/ядром
- **Новые переводы:** помощь в переводе книги на другие языки
- **Код:** улучшение примеров, сценариев сборки и инструментария
- **Issues:** сообщение об ошибках, фактических неточностях, неясных местах или проблемах форматирования

### Сообщение об issue

При создании issue, пожалуйста, укажите:

- Версию языка, который вы читали (`en_US`, `pt_BR`, `es_ES`)
- Используемый формат (PDF, EPUB, HTML или Markdown)
- Главу или раздел, в котором возникла проблема
- Краткое объяснение проблемы и, если есть, предлагаемое исправление

### Рабочий процесс

1. Форкните репозиторий
2. Создайте ветку: `git checkout -b feature/your-change`
3. Внесите изменения и протестируйте сборку с помощью `scripts/build-book.sh`
4. Сделайте коммит с понятным сообщением: `git commit -m "Chapter 18: clarify BAR mapping"`
5. Отправьте изменения и откройте Pull Request

Когда вы застряли при чтении книги, **создание issue помогает**. Если какой-то отрывок кажется неправильным или лабораторная работа неожиданно не удаётся, каждый отчёт делает путь следующего читателя более гладким.

## Часто задаваемые вопросы

### Зачем существует эта книга?

Честный ответ: Проекту FreeBSD нужны новые участники, а путь к работе с ядром и драйверами всегда был сложнее, чем следовало бы. Большинство существующих материалов предполагает, что вы уже знаете UNIX, хорошо знаете C, знаете, что такое шина, и умеете читать исходный код ядра. Это подходит для тех, кто уже прошёл большую часть пути. Но это мало помогает любопытному разработчику, который хочет начать.

Цель этой книги — снизить этот порог входа. Если хотя бы небольшое количество читателей дочитает её до конца и затем начнёт отправлять патчи, рецензировать код, писать новые драйверы или в конечном итоге станет коммиттерами FreeBSD, книга выполнит свою задачу. **Обучение следующего поколения участников FreeBSD — вот причина, по которой эта работа была написана**.

### Нужно ли знать C перед началом?

Нет. Главы 4 и 5 обучают C с нуля, уделяя внимание тем частям языка, которые важны для работы с ядром (указатели, структуры, расположение памяти, препроцессор и соглашения о вызовах). Если вы уже хорошо знаете C, боковые панели в этих главах подскажут, что можно просмотреть бегло, а что прочитать внимательно.

### Нужно ли знать UNIX или FreeBSD?

Нет. Глава 2 проведёт вас через установку FreeBSD в виртуальной машине или на "голое железо", а глава 3 знакомит с командной строкой UNIX, файловой системой, процессами, правами доступа и редакторами. К концу Части 1 у вас будет рабочая лаборатория и словарь для её использования.

### Нужно ли реальное оборудование?

Для большей части книги — нет. Виртуальной машины с FreeBSD 14.x достаточно для основ, первых глав о драйверах, параллелизма и синхронизации, а также большей части материалов по отладке. Реальное оборудование становится полезным (но всё ещё не строго обязательным), когда вы доходите до глав о PCI, прерываниях и DMA в Части 4. Эти главы написаны так, чтобы концепции были понятны, даже если вы запускаете их только в виртуальной машине.

### Поможет ли это мне писать драйверы для Linux?

Косвенно, да. Дисциплина программирования ядра хорошо переносится: стратегия блокировок, управление памятью, контекст прерываний, отображение DMA, различие между спящими и неспящими путями кода, порядок защитной очистки. Конкретные API различаются. После прочтения этой книги вы не будете знать модель устройств Linux, но вы узнаете её проблемы и форму её решений, и сможете гораздо легче читать Linux Device Drivers (LDD).

### Почему именно FreeBSD 14.x?

Каждый API, каждый пример и каждая лабораторная работа были спланированы для выполнения в дереве исходных кодов FreeBSD 14.3 и соответствующих страниц `man 9`. Ориентация на конкретный релиз позволяет книге быть точной в отношении сигнатур функций, расположения заголовочных файлов и поведения. Концепции переживут 14.x на много лет; точные номера строк и мелкие детали API — нет, и книга честна в этом.

### Является ли это официальной публикацией проекта FreeBSD?

Нет. Это независимая образовательная книга о разработке драйверов устройств FreeBSD. Это не официальная публикация проекта FreeBSD. Автор является коммиттером FreeBSD и членом команды разработки документации (DocEng), но книга отражает его работу и взгляды, а не официальную позицию проекта.

### Сколько времени это на самом деле займёт?

Если вы будете читать внимательно и выполнять лабораторные работы, планируйте около 200 часов общей работы. Это примерно 100 часов чтения и 100 часов практической лабораторной работы. При пяти часах в неделю это примерно шестимесячный вечерний проект; при десяти часах в неделю — интенсивный двухмесячный спринт. Чтение без выполнения лабораторных работ сокращает время примерно вдвое, но также снижает ценность: программирование ядра вознаграждает мышечную память так, как мало какие дисциплины.

### Могу ли я пропустить лабораторные работы?

Можете, но, вероятно, не стоит. Лабораторные работы — это то, где проза становится рефлексом. Шаблоны, такие как порядок подключения, развёртывание очистки и форма захвата блокировок, повторяются в каждой главе, и единственный надёжный способ их усвоить — набрать их, скомпилировать, загрузить в работающее ядро и намеренно наблюдать за их сбоями. Читатели, пропускающие лабораторные работы, сообщают о прогрессе, который сначала кажется гладким, а затем незаметно застревает примерно на Части 3 или Части 4.

### Как я могу внести вклад в FreeBSD после прочтения этой книги?

Глава 37 охватывает полный рабочий процесс подачи: как подготовить патч, как использовать Phabricator (система рецензирования кода FreeBSD), как найти коммиттера для спонсирования вашей работы, как отвечать на отзывы рецензии и как провести драйвер в дерево. Предыдущие главы формируют технические навыки; Глава 37 формирует социальный рабочий процесс. Важны оба.

### Книга огромна. С чего мне начать?

Начните с Главы 1, если у вас нет причин не делать этого. Книга накопительная; более поздние главы опираются на лексику и привычки, установленные ранее. Если вы уже знаете C, UNIX и общую структуру ядра ОС, заметки быстрого пути внутри Части 1 подскажут вам, что можно просмотреть бегло. Если вас привела сюда конкретная подсистема (USB, сеть, хранилище, PCI), можно внимательно прочитать Части 1 и 2, а затем перепрыгнуть вперёд, но ожидайте возвращаться назад, когда термины из предыдущих глав появятся снова.

### Я нашёл ошибку. Что мне делать?

Откройте issue на GitHub. Укажите версию языка, формат, который вы читали, главу или раздел, краткое описание проблемы и, если есть, предлагаемое исправление. Каждый отчёт делает опыт следующего читателя лучше. Проблемы перевода в изданиях pt_BR и es_ES особенно приветствуются, поскольку они ещё не прошли полную человеческую техническую рецензию.

### Книга действительно бесплатна?

Да. Она выпущена под лицензией MIT. Вы можете читать её, делиться, печатать, цитировать, развивать и переводить. Указание авторства приветствуется, но не требуется для личного использования. Если вы хотите поддержать работу, самые полезные вещи, которые вы можете сделать: рассказать другим о книге, создавать issue, когда находите проблемы, вносить рецензии или переводы и (если это в конечном итоге приведёт вас туда) отправлять свою собственную работу в проект FreeBSD.

## Об авторе

Я — Эдсон Бранди. Мой путь в технологии был далёк от обычного. Я начал как студент-химик в Unicamp в Бразилии в 1995 году, без планов работать с компьютерами, но с одним настойчивым вопросом: *как это на самом деле работает?* Этот вопрос привёл меня к FreeBSD, и FreeBSD с тех пор формирует мою карьеру.

В последующие годы я основал **Бразильскую группу пользователей FreeBSD (FUG-BR)**, совместно создал **Набор инструментов FreeBSD LiveCD**, а в 2002 году стал сооснователем **FreeBSD Brasil** — компании, предоставляющей обучение, консультации и поддержку FreeBSD, которая работает до сих пор. Я являюсь коммиттером FreeBSD и в настоящее время членом **Команды разработки документации FreeBSD (DocEng)**, помогая поддерживать системы, которые сохраняют документацию FreeBSD живой и доступной по всему миру.

Профессионально, я провёл свою карьеру в руководстве инфраструктурой и инженерией в различных отраслях, и сегодня я работаю IT-директором в финтех-компании в Лондоне.

Я написал эту книгу, потому что хочу, чтобы другие любопытные люди имели тот порог входа, которого у меня никогда не было. Вам не нужна степень в области компьютерных наук, чтобы писать код ядра. Вам нужны любопытство, настойчивость, терпение и руководство, которое встречает вас там, где вы находитесь.

Edson Brandi · [email protected]

## Лицензия

Эта книга и сопровождающий её исходный код выпущены под **лицензией MIT**. См. [LICENSE](https://github.com/ebrandi/fdd-book/blob/HEAD/LICENSE) для полного текста. Вы можете свободно читать, делиться и развивать эту работу; указание авторства приветствуется.

## Благодарности

- Сообщество разработчиков FreeBSD
- Все участники, рецензенты и переводчики
- Все, кто когда-либо создавал issue или задавал вопрос, который улучшил главу

## Ссылки

- **Репозиторий:** https://github.com/ebrandi/FDD-book
- **Issues:** https://github.com/ebrandi/FDD-book/issues
- **Обсуждения:** https://github.com/ebrandi/FDD-book/discussions
- **Автор:** Эдсон Бранди · [email protected]

---

<p align="center"><em>Если эта книга помогла вам, пожалуйста, поставьте звёздочку репозиторию и поделитесь ею с кем-то ещё, кто интересуется, как на самом деле работают компьютеры.</em></p>