the_linux_kernel_module_programming_guide.md

# The Linux Kernel Module Programming Guide (TLDP, 2.6)

Источник: [The Linux Kernel Module Programming Guide](https://tldp.org/LDP/lkmpg/2.6/html/index.html)

## Предисловие

## 1. Авторство

Руководство по программированию модулей ядра Linux (The Linux Kernel Module Programming Guide) было изначально написано для ядер 2.2 Ори Померанцем (Ori Pomerantz). Со временем у Ори уже не оставалось времени на сопровождение документа — ядро Linux, в конце концов, быстро движущаяся цель. Питер Джей Сальцман (Peter Jay Salzman) взял на себя сопровождение и обновил руководство для ядер 2.4. В конце концов и у Питера не осталось времени следить за развитием ядра 2.6, поэтому Майкл Буриан (Michael Burian) стал сопроводителем документа и обновил его для ядер 2.6.

## 2. Версии и примечания

Ядро Linux — движущаяся цель. Всегда стоял вопрос: удалять ли из LKMPG устаревшую информацию или сохранять её ради истории. Мы с Майклом Бурианом решили создавать новую ветку LKMPG для каждой новой стабильной версии ядра. Так, версия LKMPG 2.4.x посвящена ядру Linux 2.4, а LKMPG 2.6.x — ядру Linux 2.6. Архивировать историческую информацию мы не собираемся; тому, кому нужна такая информация, следует прочитать LKMPG соответствующей версии.

Исходный код и рассуждения должны быть применимы к большинству архитектур, но обещать ничего не могу. Единственное исключение — [глава 12](interrupthandlers.html), «Обработчики прерываний», которая не будет работать ни на одной архитектуре, кроме x86.

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

Следующие люди внесли исправления или дельные предложения: Игнасио Мартин (Ignacio Martin), Дэвид Портер (David Porter), Даниэле Паоло Скарпацца (Daniele Paolo Scarpazza), Димо Велев (Dimo Velev), Франсуа Одон (Francois Audeon) и Хорст Ширмайер (Horst Schirmeier).

## Глава 1. Введение

## 1.1. Что такое модуль ядра?

Итак, вы хотите написать модуль ядра. Вы знаете C, написали несколько обычных программ, выполняющихся как процессы, и теперь хотите добраться туда, где происходит настоящее действие, — туда, где один «одичавший» указатель может уничтожить вашу файловую систему, а core dump означает перезагрузку.

Что же такое модуль ядра? Модули — это фрагменты кода, которые можно по требованию загружать в ядро и выгружать из него. Они расширяют функциональность ядра без необходимости перезагружать систему. Например, один из типов модулей — драйвер устройства, позволяющий ядру работать с оборудованием, подключённым к системе. Без модулей нам пришлось бы собирать монолитные ядра и добавлять новую функциональность непосредственно в образ ядра. Помимо укрупнения ядра, у такого подхода есть и другой недостаток: каждый раз, когда нам понадобится новая функциональность, пришлось бы пересобирать ядро и перезагружать машину.

## 1.2. Как модули попадают в ядро?

Посмотреть, какие модули уже загружены в ядро, можно командой **lsmod**, которая получает информацию, читая файл `/proc/modules`.

Как же эти модули попадают в ядро? Когда ядру требуется возможность, не входящая в резидентную часть ядра, демон модулей ядра kmod[1] запускает modprobe, чтобы загрузить нужный модуль. modprobe передаётся строка одного из двух видов:

* имя модуля, например `softdog` или `ppp`;
* более общий идентификатор, например `char-major-10-30`.

Если modprobe получает общий идентификатор, он сначала ищет эту строку в файле `/etc/modprobe.conf`.[2] Если он находит строку вида:

```text
alias char-major-10-30 softdog
```

то понимает, что общий идентификатор указывает на модуль `softdog.ko`.

Далее modprobe просматривает файл `/lib/modules/version/modules.dep`, чтобы выяснить, не требуется ли перед запрашиваемым модулем загрузить другие модули. Этот файл создаётся командой **depmod -a** и содержит зависимости модулей. Например, модулю `msdos.ko` необходимо, чтобы модуль `fat.ko` уже был загружен в ядро. Запрашиваемый модуль зависит от другого модуля, если тот определяет символы (переменные или функции), которые использует запрашиваемый модуль.

Наконец, modprobe с помощью insmod сначала загружает в ядро все обязательные модули-предпосылки, а затем и сам запрашиваемый модуль. modprobe указывает insmod на `/lib/modules/version/`[3] — стандартный каталог модулей. insmod намеренно «глуп» в вопросах расположения модулей, тогда как modprobe знает стандартное место расположения модулей, умеет вычислять зависимости и загружать модули в правильном порядке. Так, например, если бы вы захотели загрузить модуль msdos, вам пришлось бы выполнить либо:

```bash
insmod /lib/modules/2.6.11/kernel/fs/fat/fat.ko
insmod /lib/modules/2.6.11/kernel/fs/msdos/msdos.ko
```

либо:

```bash
modprobe msdos
```

Итак, мы увидели: **insmod** требует, чтобы вы передали ему полный путь и вставляли модули в правильном порядке, а **modprobe** принимает просто имя без каких-либо расширений и сам выясняет всё необходимое, разбирая файл `/lib/modules/version/modules.dep`.

Дистрибутивы Linux поставляют modprobe, insmod и depmod в составе пакета module-init-tools. В предыдущих версиях этот пакет назывался modutils. Некоторые дистрибутивы также настраивают обёртки, позволяющие устанавливать оба пакета параллельно и поступать правильно, чтобы справляться и с ядрами 2.4, и с ядрами 2.6. Пользователям не нужно вникать в эти детали, пока они пользуются свежими версиями этих инструментов.

Теперь вы знаете, как модули попадают в ядро. История получает продолжение, если вы хотите писать собственные модули, зависящие от других модулей (мы называем это наложением модулей — stacking modules). Но этот вопрос придётся отложить до одной из следующих глав. Прежде чем перейти к этому относительно высокоуровневому вопросу, нам предстоит рассмотреть многое другое.

### 1.2.1. Прежде чем начать

Прежде чем погрузиться в код, нам нужно осветить несколько вопросов. Система у каждого своя, и у каждого свой привычный уклад. Заставить вашу первую программу «hello world» скомпилироваться и загрузиться корректно иногда бывает целым трюком. Будьте уверены: после того как вы преодолеете начальный барьер и сделаете это в первый раз, дальше всё пойдёт как по маслу.

#### 1.2.1.1. Версионирование модулей (modversioning)

Модуль, скомпилированный под одно ядро, не загрузится, если вы загрузитесь с другим ядром, — если только в ядре не включён `CONFIG_MODVERSIONS`. Версионирование модулей мы рассмотрим позже в этом руководстве. Пока мы не разобрали modversions, примеры из руководства могут не работать, если у вас запущено ядро с включённым modversioning. Однако большинство «штатных» ядер дистрибутивов Linux поставляется с ним включённым. Если у вас возникают проблемы с загрузкой модулей из-за ошибок версионирования, соберите ядро с выключенным modversioning.

#### 1.2.1.2. Использование X

Настоятельно рекомендую набрать, скомпилировать и загрузить все примеры, обсуждаемые в этом руководстве. Также настоятельно рекомендую делать это из консоли. Не следует заниматься этим в X.

Модули не могут печатать на экран так, как это делает `printf()`, но они могут записывать информацию и предупреждения в журнал, и эта информация выводится на ваш экран — но только на консоль. Если вы выполните insmod модуля из xterm, информация и предупреждения попадут в журнал, но только в файлы журналов. Вы их не увидите, пока не просмотрите файлы журналов. Чтобы иметь немедленный доступ к этой информации, выполняйте всю работу из консоли.

#### 1.2.1.3. Проблемы компиляции и версия ядра

Довольно часто дистрибутивы Linux распространяют исходники ядра, пропатченные разными нестандартными способами, что может вызвать проблемы.

Более распространённая проблема — некоторые дистрибутивы Linux распространяют неполные заголовки ядра. Вам понадобится компилировать свой код с использованием разных заголовочных файлов ядра Linux. По закону Мерфи отсутствующими окажутся именно те заголовки, которые нужны для работы вашего модуля.

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

По иронии судьбы, и это может создать проблему. По умолчанию gcc в вашей системе может искать заголовки ядра в их стандартном расположении, а не там, где вы установили новую копию ядра (обычно в `/usr/src/`). Это можно исправить ключом `-I` компилятора gcc.

#### Примечания

[1] В более ранних версиях Linux этот демон был известен как kerneld.

[2] Если такой файл существует. Обратите внимание, что фактическое поведение может зависеть от дистрибутива. Если вам интересны детали, прочитайте man-страницы, поставляемые с module-init-tools, и посмотрите сами, что на самом деле происходит. Можно использовать что-то вроде **strace modprobe dummy**, чтобы выяснить, как загружается dummy.ko. К сведению: dummy.ko, о котором здесь идёт речь, входит в основное дерево ядра и находится в разделе networking. Чтобы это сработало, его нужно скомпилировать как модуль (и, конечно, установить).

[3] Если вы модифицируете ядро, то, чтобы не перезаписывать существующие модули, вы можете использовать переменную `EXTRAVERSION` в Makefile ядра для создания отдельного каталога.

## Глава 2. Hello World

## 2.1. Hello, World (часть 1): простейший модуль

Когда первый программист из пещерных людей выбивал первую программу на стенах первого пещерного компьютера, это была программа, рисующая строку «Hello, world» картинками антилоп. Римские учебники программирования начинались с программы «Salut, Mundi». Я не знаю, что происходит с людьми, которые нарушают эту традицию, но думаю, что лучше не выяснять. Мы начнём с серии программ hello world, демонстрирующих разные аспекты основ написания модулей ядра.

Вот простейший из возможных модулей. Пока не компилируйте его; компиляции модулей посвящён следующий раздел.

**Пример 2-1. hello-1.c**

```c
/*
 *  hello-1.c - The simplest kernel module.
 */
#include <linux/module.h>	/* Needed by all modules */
#include <linux/kernel.h>	/* Needed for KERN_INFO */

int init_module(void)
{
	printk(KERN_INFO "Hello world 1.\n");

	/*
	 * A non 0 return means init_module failed; module can't be loaded.
	 */
	return 0;
}

void cleanup_module(void)
{
	printk(KERN_INFO "Goodbye world 1.\n");
}
```

Модули ядра должны иметь как минимум две функции: функцию «старта» (инициализации), называемую `init_module()`, которая вызывается, когда модуль вставляется в ядро командой insmod, и функцию «завершения» (очистки), называемую `cleanup_module()`, которая вызывается непосредственно перед выгрузкой модуля командой rmmod. На самом деле, начиная с ядра 2.3.13, ситуация изменилась: теперь для функций старта и завершения модуля можно использовать любые имена, и вы узнаете, как это делается, в [разделе 2.3](hello2.html). Фактически новый метод является предпочтительным. Тем не менее многие по-прежнему называют функции старта и завершения `init_module()` и `cleanup_module()`.

Обычно `init_module()` либо регистрирует в ядре какой-либо обработчик, либо заменяет одну из функций ядра собственным кодом (обычно кодом, который делает что-то своё и затем вызывает оригинальную функцию). Функция `cleanup_module()` должна отменить всё, что сделал `init_module()`, чтобы модуль можно было безопасно выгрузить.

Наконец, каждому модулю ядра необходимо подключать `linux/module.h`. А `linux/kernel.h` нам понадобился только ради раскрытия макроса уровня журналирования `printk()` — `KERN_ALERT`, о котором вы узнаете в [разделе 2.1.1](x121.html#INTRODUCINGPRINTK).

### 2.1.1. Знакомство с `printk()`

Вопреки тому, что вы могли подумать, `printk()` не предназначен для передачи информации пользователю, хотя в hello-1 мы использовали его именно для этого! На самом деле это механизм журналирования ядра, применяемый для записи информации или выдачи предупреждений. Поэтому каждый вызов `printk()` сопровождается приоритетом — это те `<1>` и `KERN_ALERT`, которые вы видели. Приоритетов восемь, и для них в ядре есть макросы, так что вам не нужно использовать загадочные числа; посмотреть их (и их значения) можно в `linux/kernel.h`. Если вы не укажете уровень приоритета, будет использован приоритет по умолчанию — `DEFAULT_MESSAGE_LOGLEVEL`.

Найдите время, чтобы внимательно прочитать макросы приоритетов. В заголовочном файле также описано, что означает каждый приоритет. На практике не используйте числа вроде `<4>` — всегда используйте макрос, например `KERN_WARNING`.

Если приоритет меньше значения `int console_loglevel`, сообщение выводится на ваш текущий терминал. Если запущены и **syslogd**, и klogd, сообщение также будет добавлено в `/var/log/messages`, независимо от того, было оно выведено на консоль или нет. Мы используем высокий приоритет, например `KERN_ALERT`, чтобы сообщения `printk()` гарантированно попали на вашу консоль, а не просто записались в файл журнала. Когда вы будете писать настоящие модули, вам захочется использовать приоритеты, имеющие смысл в конкретной ситуации.

## 2.2. Компиляция модулей ядра

Модули ядра нужно компилировать несколько иначе, чем обычные приложения пользовательского пространства. В прежних версиях ядра нам приходилось уделять много внимания этим настройкам, которые обычно хранятся в Makefile'ах. Несмотря на иерархическую организацию, в Makefile'ах нижних уровней накапливалось множество избыточных настроек, отчего они разрастались и становились довольно сложными в сопровождении. К счастью, появился новый способ делать всё это, называемый kbuild, и процесс сборки внешних загружаемых модулей теперь полностью интегрирован в стандартный механизм сборки ядра. Подробнее о том, как компилировать модули, не входящие в официальное ядро (как все примеры из этого руководства), см. в файле `linux/Documentation/kbuild/modules.txt`.

Итак, рассмотрим простой Makefile для компиляции модуля `hello-1.c`:

**Пример 2-2. Makefile для простейшего модуля ядра**

```make
obj-m += hello-1.o

all:
	make -C /lib/modules/$(shell uname -r)/build M=$(PWD) modules

clean:
	make -C /lib/modules/$(shell uname -r)/build M=$(PWD) clean
```

С технической точки зрения действительно необходима только первая строка; цели «all» и «clean» добавлены исключительно ради удобства.

Теперь вы можете скомпилировать модуль, выполнив команду **make**. Вы должны получить вывод, похожий на следующий:

```text
hostname:~/lkmpg-examples/02-HelloWorld# make
make -C /lib/modules/2.6.11/build M=/root/lkmpg-examples/02-HelloWorld modules
make[1]: Entering directory `/usr/src/linux-2.6.11'
  CC [M]  /root/lkmpg-examples/02-HelloWorld/hello-1.o
 Building modules, stage 2.
  MODPOST
  CC      /root/lkmpg-examples/02-HelloWorld/hello-1.mod.o
  LD [M]  /root/lkmpg-examples/02-HelloWorld/hello-1.ko
make[1]: Leaving directory `/usr/src/linux-2.6.11'
hostname:~/lkmpg-examples/02-HelloWorld#
```

Обратите внимание, что в ядре 2.6 появилась новая схема именования файлов: модули ядра теперь имеют расширение `.ko` (вместо старого расширения `.o`), что позволяет легко отличать их от обычных объектных файлов. Причина в том, что они содержат дополнительную секцию .modinfo, в которой хранится дополнительная информация о модуле. Скоро мы увидим, зачем нужна эта информация.

Выполните **modinfo hello-*.ko**, чтобы посмотреть, что это за информация.
```text
hostname:~/lkmpg-examples/02-HelloWorld# modinfo hello-1.ko
filename:       hello-1.ko
vermagic:       2.6.11 preempt PENTIUMII 4KSTACKS gcc-3.3
depends:
```

Пока ничего впечатляющего. Всё изменится, когда мы выполним modinfo для одного из наших последующих примеров — `hello-5.ko`.

```text
hostname:~/lkmpg-examples/02-HelloWorld# modinfo hello-5.ko
filename:       hello-5.ko
license:        GPL
author:         Peter Jay Salzman
vermagic:       2.6.11 preempt PENTIUMII 4KSTACKS gcc-3.3
depends:
parm:           myintArray:An array of integers (array of int)
parm:           mystring:A character string (charp)
parm:           mylong:A long integer (long)
parm:           myint:An integer (int)
parm:           myshort:A short integer (short)
hostname:~/lkmpg-examples/02-HelloWorld#
```

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

Дополнительные подробности о Makefile'ах для модулей ядра приведены в `linux/Documentation/kbuild/makefiles.txt`. Обязательно прочитайте этот и связанные с ним файлы, прежде чем начинать колдовать над Makefile'ами — это, вероятно, сэкономит вам кучу работы.

Теперь пора вставить ваш свежескомпилированный модуль в ядро командой **insmod ./hello-1.ko** (не обращайте внимания на сообщения о «заражённом» ядре; мы вскоре это обсудим).

Все загруженные в ядро модули перечислены в `/proc/modules`. Выполните cat этого файла и убедитесь, что ваш модуль действительно является частью ядра. Поздравляем — теперь вы автор кода ядра Linux! Когда новизна впечатлений угаснет, удалите модуль из ядра командой **rmmod hello-1**. Взгляните на `/var/log/messages`, чтобы убедиться, что запись попала в системный файл журнала.

Вот ещё одно упражнение для читателя. Видите комментарий над оператором return в `init_module()`? Измените возвращаемое значение на отрицательное, перекомпилируйте и снова загрузите модуль. Что произойдёт?

## 2.3. Hello World (часть 2)

Начиная с Linux 2.4 вы можете переименовывать функции инициализации и очистки своих модулей — они больше не обязаны называться `init_module()` и `cleanup_module()` соответственно. Это делается с помощью макросов `module_init()` и `module_exit()`. Эти макросы определены в `linux/init.h`. Единственная оговорка: функции инициализации и очистки должны быть определены до вызова макросов, иначе вы получите ошибки компиляции. Вот пример использования этой техники:

**Пример 2-3. hello-2.c**

```c
/*
 *  hello-2.c - Demonstrating the module_init() and module_exit() macros.
 *  This is preferred over using init_module() and cleanup_module().
 */
#include <linux/module.h>	/* Needed by all modules */
#include <linux/kernel.h>	/* Needed for KERN_INFO */
#include <linux/init.h>		/* Needed for the macros */

static int __init hello_2_init(void)
{
	printk(KERN_INFO "Hello, world 2\n");
	return 0;
}

static void __exit hello_2_exit(void)
{
	printk(KERN_INFO "Goodbye, world 2\n");
}

module_init(hello_2_init);
module_exit(hello_2_exit);
```

Итак, теперь в нашем активе два настоящих модуля ядра. Добавить ещё один модуль так же просто:

**Пример 2-4. Makefile для обоих наших модулей**

```make
obj-m += hello-1.o
obj-m += hello-2.o

all:
	make -C /lib/modules/$(shell uname -r)/build M=$(PWD) modules

clean:
	make -C /lib/modules/$(shell uname -r)/build M=$(PWD) clean
```

А теперь взгляните на `linux/drivers/char/Makefile` — это пример из реальной жизни. Как видите, кое-что жёстко вшивается в ядро (obj-y), но куда делись все те obj-m? Те, кто знаком со скриптами оболочки, легко их отыщут. Для остальных поясним: встречающиеся повсюду записи obj-$(CONFIG_FOO) разворачиваются в obj-y или obj-m в зависимости от того, установлена ли переменная CONFIG_FOO в y или m. К слову, это именно те переменные, которые вы задавали в файле `linux/.config` в последний раз, когда запускали **make menuconfig** или что-то в этом роде.

## 2.4. Hello World (часть 3): макросы `__init` и `__exit`

Этот пример демонстрирует возможность ядра 2.2 и более поздних. Обратите внимание на изменения в определениях функций инициализации и очистки. Макрос `__init` приводит к тому, что для встроенных в ядро драйверов функция инициализации после своего завершения отбрасывается, а занимаемая ей память освобождается; для загружаемых модулей этого не происходит. Если подумать, в какой момент вызывается функция инициализации, всё становится совершенно логичным.

Существует также макрос `__initdata`, работающий аналогично `__init`, но для переменных инициализации, а не функций.

Макрос `__exit` приводит к исключению функции, когда модуль встроен в ядро, и, подобно `__init`, не оказывает никакого действия на загружаемые модули. И снова: если учесть, в какой момент выполняется функция очистки, всё обретает полный смысл — встроенным драйверам функция очистки не нужна, а загружаемым модулям нужна.

Эти макросы определены в `linux/init.h` и служат для освобождения памяти ядра. Когда вы загружаете своё ядро и видите что-то вроде `Freeing unused kernel memory: 236k freed` — ядро освобождает именно эту память.

**Пример 2-5. hello-3.c**

```c
/*
 *  hello-3.c - Illustrating the __init, __initdata and __exit macros.
 */
#include <linux/module.h>	/* Needed by all modules */
#include <linux/kernel.h>	/* Needed for KERN_INFO */
#include <linux/init.h>		/* Needed for the macros */

static int hello3_data __initdata = 3;

static int __init hello_3_init(void)
{
	printk(KERN_INFO "Hello, world %d\n", hello3_data);
	return 0;
}

static void __exit hello_3_exit(void)
{
	printk(KERN_INFO "Goodbye, world 3\n");
}

module_init(hello_3_init);
module_exit(hello_3_exit);
```

## 2.5. Hello World (часть 4): лицензирование и документирование модулей

Если вы используете ядро 2.4 или более позднее, вы могли заметить при загрузке проприетарных модулей нечто подобное:

```text
## insmod xxxxxx.o
Warning: loading xxxxxx.ko will taint the kernel: no license
  See http://www.tux.org/lkml/#export-tainted for information about tainted modules
Module xxxxxx loaded, with warnings
```

В ядре 2.4 и более поздних был предусмотрен механизм идентификации кода, лицензированного под GPL (и совместимыми лицензиями), чтобы людей можно было предупреждать о не-open-source-коде. Это реализуется макросом `MODULE_LICENSE()`, который демонстрируется в следующем фрагменте кода. Установив лицензию GPL, вы можете предотвратить вывод предупреждения. Этот лицензионный механизм определён и документирован в `linux/module.h`:

```c
/*
 * The following license idents are currently accepted as indicating free
 * software modules
 *
 *	"GPL"				[GNU Public License v2 or later]
 *	"GPL v2"			[GNU Public License v2]
 *	"GPL and additional rights"	[GNU Public License v2 rights and more]
 *	"Dual BSD/GPL"			[GNU Public License v2
 *					 or BSD license choice]
 *	"Dual MIT/GPL"			[GNU Public License v2
 *					 or MIT license choice]
 *	"Dual MPL/GPL"			[GNU Public License v2
 *					 or Mozilla license choice]
 *
 * The following other idents are available
 *
 *	"Proprietary"			[Non free products]
 *
 * There are dual licensed components, but when running with Linux it is the
 * GPL that is relevant so this is a non issue. Similarly LGPL linked with GPL
 * is a GPL combined work.
 *
 * This exists for several reasons
 * 1.	So modinfo can show license info for users wanting to vet their setup 
 *	is free
 * 2.	So the community can ignore bug reports including proprietary modules
 * 3.	So vendors can do likewise based on their own policies
 */
```

Аналогично, `MODULE_DESCRIPTION()` используется для описания того, что делает модуль, `MODULE_AUTHOR()` объявляет автора модуля, а `MODULE_SUPPORTED_DEVICE()` объявляет, какие типы устройств поддерживает модуль.

Все эти макросы определены в `linux/module.h` и самим ядром не используются. Они предназначены исключительно для документирования и могут быть просмотрены таким инструментом, как objdump. В качестве упражнения для читателя попробуйте поискать эти макросы в `linux/drivers`, чтобы посмотреть, как авторы модулей используют их для документирования своих модулей.

Я рекомендую выполнить что-то вроде **grep -inr MODULE_AUTHOR *** в `/usr/src/linux-2.6.x/`. Людям, не дружащим с инструментами командной строки, вероятно, понравится какое-нибудь веб-решение: поищите сайты, предлагающие деревья ядра, проиндексированные с помощью LXR (или разверните такой у себя на локальной машине).

Пользователи традиционных Unix-редакторов вроде **emacs** или **vi** также найдут полезными файлы тегов. Они могут быть сгенерированы командами **make tags** или **make TAGS** в `/usr/src/linux-2.6.x/`. Когда в дереве ядра есть такой файл тегов, вы можете поместить курсор на какой-нибудь вызов функции и с помощью комбинации клавиш перейти прямо к определению функции.

**Пример 2-6. hello-4.c**

```c
/*
 *  hello-4.c - Demonstrates module documentation.
 */
#include <linux/module.h>	/* Needed by all modules */
#include <linux/kernel.h>	/* Needed for KERN_INFO */
#include <linux/init.h>		/* Needed for the macros */
#define DRIVER_AUTHOR "Peter Jay Salzman <p@dirac.org>"
#define DRIVER_DESC   "A sample driver"

static int __init init_hello_4(void)
{
	printk(KERN_INFO "Hello, world 4\n");
	return 0;
}

static void __exit cleanup_hello_4(void)
{
	printk(KERN_INFO "Goodbye, world 4\n");
}

module_init(init_hello_4);
module_exit(cleanup_hello_4);

/*
 *  You can use strings, like this:
 */

/*
 * Get rid of taint message by declaring code as GPL.
 */
MODULE_LICENSE("GPL");

/*
 * Or with defines, like this:
 */
MODULE_AUTHOR(DRIVER_AUTHOR);	/* Who wrote this module? */
MODULE_DESCRIPTION(DRIVER_DESC);	/* What does this module do */

/*
 *  This module uses /dev/testdevice.  The MODULE_SUPPORTED_DEVICE macro might
 *  be used in the future to help automatic configuration of modules, but is
 *  currently unused other than for documentation purposes.
 */
MODULE_SUPPORTED_DEVICE("testdevice");
```

## 2.6. Передача модулю аргументов командной строки

Модули могут принимать аргументы командной строки, но не через привычные вам `argc`/`argv`.

Чтобы модуль мог принимать аргументы, объявите переменные, которые будут принимать значения аргументов командной строки, как глобальные, а затем используйте макрос `module_param()` (определён в `linux/moduleparam.h`), чтобы настроить механизм. Во время выполнения insmod заполнит эти переменными значениями переданных аргументов командной строки, например **./insmod mymodule.ko myvariable=5**. Для ясности объявления переменных и макросы следует размещать в начале модуля. Пример кода должен прояснить моё, признаться, весьма неуклюжее объяснение.

Макрос `module_param()` принимает 3 аргумента: имя переменной, её тип и права доступа к соответствующему файлу в sysfs. Целочисленные типы могут быть как обычными знаковыми, так и беззнаковыми. Если вы хотите использовать массивы целых чисел или строк, см. `module_param_array()` и `module_param_string()`.

```c
int myint = 3;
module_param(myint, int, 0);
```

Массивы тоже поддерживаются, но сейчас дела обстоят несколько иначе, чем во времена 2.4. Чтобы отслеживать количество параметров, нужно передать указатель на переменную-счётчик третьим параметром. При желании счётчик можно проигнорировать и вместо него передать NULL. Мы покажем оба варианта:

```c
int myintarray[2];
module_param_array(myintarray, int, NULL, 0); /* not interested in count */

int myshortarray[4];
int count;
module_parm_array(myshortarray, short, , 0); /* put count into "count" variable */
```

Хорошее применение этому — задание значений по умолчанию для переменных модуля, например порта или адреса ввода-вывода. Если переменные содержат значения по умолчанию, выполняется автодетектирование (объясняется в другом месте). В противном случае сохраняется текущее значение. Позже это станет понятнее.

Наконец, существует макрос `MODULE_PARM_DESC()`, который используется для документирования аргументов, принимаемых модулем. Он принимает два параметра: имя переменной и произвольную строку с описанием этой переменной.

**Пример 2-7. hello-5.c**

```c
/*
 *  hello-5.c - Demonstrates command line argument passing to a module.
 */
#include <linux/module.h>
#include <linux/moduleparam.h>
#include <linux/kernel.h>
#include <linux/init.h>
#include <linux/stat.h>

MODULE_LICENSE("GPL");
MODULE_AUTHOR("Peter Jay Salzman");

static short int myshort = 1;
static int myint = 420;
static long int mylong = 9999;
static char *mystring = "blah";
static int myintArray[2] = { -1, -1 };
static int arr_argc = 0;

/*
 * module_param(foo, int, 0000)
 * The first param is the parameters name
 * The second param is it's data type
 * The final argument is the permissions bits,
 * for exposing parameters in sysfs (if non-zero) at a later stage.
 */

module_param(myshort, short, S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP);
MODULE_PARM_DESC(myshort, "A short integer");
module_param(myint, int, S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH);
MODULE_PARM_DESC(myint, "An integer");
module_param(mylong, long, S_IRUSR);
MODULE_PARM_DESC(mylong, "A long integer");
module_param(mystring, charp, 0000);
MODULE_PARM_DESC(mystring, "A character string");

/*
 * module_param_array(name, type, num, perm);
 * The first param is the parameter's (in this case the array's) name
 * The second param is the data type of the elements of the array
 * The third argument is a pointer to the variable that will store the number
 * of elements of the array initialized by the user at module loading time
 * The fourth argument is the permission bits
 */
module_param_array(myintArray, int, &arr_argc, 0000);
MODULE_PARM_DESC(myintArray, "An array of integers");

static int __init hello_5_init(void)
{
	int i;
	printk(KERN_INFO "Hello, world 5\n=============\n");
	printk(KERN_INFO "myshort is a short integer: %hd\n", myshort);
	printk(KERN_INFO "myint is an integer: %d\n", myint);
	printk(KERN_INFO "mylong is a long integer: %ld\n", mylong);
	printk(KERN_INFO "mystring is a string: %s\n", mystring);
	for (i = 0; i < (sizeof myintArray / sizeof (int)); i++)
	{
		printk(KERN_INFO "myintArray[%d] = %d\n", i, myintArray[i]);
	}
	printk(KERN_INFO "got %d arguments for myintArray.\n", arr_argc);
	return 0;
}

static void __exit hello_5_exit(void)
{
	printk(KERN_INFO "Goodbye, world 5\n");
}

module_init(hello_5_init);
module_exit(hello_5_exit);
```

Рекомендую поиграться с этим кодом:

```text
satan# insmod hello-5.ko mystring="bebop" mybyte=255 myintArray=-1
mybyte is an 8 bit integer: 255
myshort is a short integer: 1
myint is an integer: 20
mylong is a long integer: 9999
mystring is a string: bebop
myintArray is -1 and 420

satan# rmmod hello-5
Goodbye, world 5

satan# insmod hello-5.ko mystring="supercalifragilisticexpialidocious" \
> mybyte=256 myintArray=-1,-1
mybyte is an 8 bit integer: 0
myshort is a short integer: 1
myint is an integer: 20
mylong is a long integer: 9999
mystring is a string: supercalifragilisticexpialidocious
myintArray is -1 and -1

satan# rmmod hello-5
Goodbye, world 5

satan# insmod hello-5.ko mylong=hello
hello-5.o: invalid argument syntax for mylong: 'h'
```

## 2.7. Модули из нескольких файлов

Иногда имеет смысл распределить модуль ядра по нескольким исходным файлам.

Вот пример такого модуля ядра.

**Пример 2-8. start.c**

```c
/*
 *  start.c - Illustration of multi filed modules
 */

#include <linux/kernel.h>	/* We're doing kernel work */
#include <linux/module.h>	/* Specifically, a module */

int init_module(void)
{
	printk(KERN_INFO "Hello, world - this is the kernel speaking\n");
	return 0;
}
```

Следующий файл:

**Пример 2-9. stop.c**

```c
/*
 *  stop.c - Illustration of multi filed modules
 */

#include <linux/kernel.h>	/* We're doing kernel work */
#include <linux/module.h>	/* Specifically, a module  */

void cleanup_module()
{
	printk(KERN_INFO "Short is the life of a kernel module\n");
}
```

И наконец, Makefile:

**Пример 2-10. Makefile**

```make
obj-m += hello-1.o
obj-m += hello-2.o
obj-m += hello-3.o
obj-m += hello-4.o
obj-m += hello-5.o
obj-m += startstop.o
startstop-objs := start.o stop.o

all:
	make -C /lib/modules/$(shell uname -r)/build M=$(PWD) modules

clean:
	make -C /lib/modules/$(shell uname -r)/build M=$(PWD) clean
```

Это полный Makefile для всех рассмотренных нами примеров. Первые пять строк — ничего особенного, но для последнего примера нам понадобятся две строки. Сначала мы придумываем имя объекта для нашего составного модуля, а затем сообщаем **make**, какие объектные файлы входят в этот модуль.

## 2.8. Сборка модулей под прекомпилированное ядро

Очевидно, мы настоятельно рекомендуем вам пересобрать своё ядро, чтобы включить ряд полезных отладочных возможностей, таких как принудительная выгрузка модуля (`MODULE_FORCE_UNLOAD`): когда эта опция включена, вы можете заставить ядро выгрузить модуль, даже если оно считает это небезопасным, — командой **rmmod -f module**. Эта опция может сэкономить вам массу времени и немало перезагрузок в процессе разработки модуля.

Тем не менее существует ряд случаев, когда может понадобиться загрузить свой модуль в уже работающее прекомпилированное ядро — например, в то, что поставляется с обычными дистрибутивами Linux, или в ядро, которое вы компилировали в прошлом. В некоторых обстоятельствах может потребоваться скомпилировать и вставить модуль в работающее ядро, которое вам не разрешено пересобирать, или на машине, которую вы предпочли бы не перезагружать. Если вы не можете придумать случай, который вынудит вас использовать модули под прекомпилированное ядро, можете пропустить этот раздел и считать оставшуюся часть главы большой сноской.

Итак, если вы просто развернёте дерево исходников ядра, используете его для компиляции своего модуля и попытаетесь вставить модуль в ядро, в большинстве случаев вы получите примерно такую ошибку:

```text
insmod: error inserting 'poet_atkm.ko': -1 Invalid module format
```

Менее загадочная информация записывается в `/var/log/messages`:

```text
Jun  4 22:07:54 localhost kernel: poet_atkm: version magic '2.6.5-1.358custom 686
REGPARM 4KSTACKS gcc-3.3' should be '2.6.5-1.358 686 REGPARM 4KSTACKS gcc-3.3'
```

Иными словами, ядро отказывается принимать ваш модуль, потому что строки версии (точнее, version magic — «магия версии») не совпадают. Кстати, version magic хранится в объектном файле модуля в виде статической строки, начинающейся с `vermagic:`. Данные версии попадают в ваш модуль при линковке с файлом `init/vermagic.o`. Чтобы просмотреть version magic и другие строки, хранящиеся в конкретном модуле, выполните команду **modinfo module.ko**:

```text
[root@pcsenonsrv 02-HelloWorld]# modinfo hello-4.ko
license:        GPL
author:         Peter Jay Salzman <p@dirac.org>
description:    A sample driver
vermagic:       2.6.5-1.358 686 REGPARM 4KSTACKS gcc-3.3
depends:
```

Чтобы преодолеть эту проблему, можно прибегнуть к опции **\--force-vermagic**, но такое решение потенциально небезопасно и безоговорочно неприемлемо для модулей, используемых в продакшене. Следовательно, мы хотим компилировать свой модуль в окружении, идентичном тому, в котором было собрано наше прекомпилированное ядро. Как это сделать — тема оставшейся части этой главы.

Прежде всего убедитесь, что доступно дерево исходников ядра точно той же версии, что и ваше текущее ядро. Затем найдите файл конфигурации, который использовался при компиляции вашего прекомпилированного ядра. Обычно он находится в вашем текущем каталоге `/boot` под именем вида `config-2.6.x`. Можете просто скопировать его в дерево исходников ядра: **cp /boot/config-`uname -r` /usr/src/linux-`uname -r`/.config**.

Вернёмся к предыдущему сообщению об ошибке: более внимательный взгляд на строки version magic подсказывает, что даже при двух полностью идентичных файлах конфигурации возможно небольшое расхождение в version magic, и его достаточно, чтобы помешать вставке модуля в ядро. Это небольшое расхождение — а именно строка `custom`, которая присутствует в version magic модуля, но не ядра, — возникает из-за изменения относительно оригинала в Makefile, который поставляется с некоторыми дистрибутивами. Поэтому изучите свой `/usr/src/linux/Makefile` и убедитесь, что указанная там информация о версии в точности совпадает с той, что использована для вашего текущего ядра. Например, ваш Makefile может начинаться так:

```make
VERSION = 2
PATCHLEVEL = 6
SUBLEVEL = 5
EXTRAVERSION = -1.358custom
...
```

В этом случае вам нужно восстановить значение символа `EXTRAVERSION` на `-1.358`. Мы советуем хранить резервную копию Makefile, использованного для компиляции вашего ядра, в `/lib/modules/2.6.5-1.358/build`. Достаточно будет простой команды **cp /lib/modules/`uname -r`/build/Makefile /usr/src/linux-`uname -r`**. Кроме того, если вы уже начали сборку ядра с предыдущим (неправильным) `Makefile`, вам следует также заново выполнить **make**, либо напрямую изменить символ `UTS_RELEASE` в файле `/usr/src/linux-2.6.x/include/linux/version.h` в соответствии с содержимым файла `/lib/modules/2.6.x/build/include/linux/version.h`, либо перезаписать последний первым.

Теперь выполните **make**, чтобы обновить конфигурацию, а также заголовочные файлы и объектные файлы версий:

```text
[root@pcsenonsrv linux-2.6.x]# make
CHK     include/linux/version.h
UPD     include/linux/version.h
SYMLINK include/asm -> include/asm-i386
SPLIT   include/linux/autoconf.h -> include/config/*
HOSTCC  scripts/basic/fixdep
HOSTCC  scripts/basic/split-include
HOSTCC  scripts/basic/docproc
HOSTCC  scripts/conmakehash
HOSTCC  scripts/kallsyms
CC      scripts/empty.o
...
```

Если вы не желаете действительно компилировать ядро, вы можете прервать процесс сборки (**CTRL-C**) сразу после строки `SPLIT`, поскольку к этому моменту нужные вам файлы уже будут готовы. Теперь можете вернуться в каталог вашего модуля и скомпилировать его: он будет собран в точности по настройкам вашего текущего ядра и загрузится в него без каких-либо ошибок.

---

## Глава 3. Предварительные сведения

## 3.1. Модули и программы

### 3.1.1. Как модули начинаются и заканчиваются

Программа обычно начинается с функции `main()`, выполняет набор инструкций и завершается по их окончании. Модули ядра работают несколько иначе. Модуль всегда начинается либо с `init_module`, либо с функции, которую вы указываете при вызове `module_init`. Это входная функция модуля; она сообщает ядру, какую функциональность предоставляет модуль, и настраивает ядро так, чтобы функции модуля вызывались, когда они понадобятся. Сделав это, входная функция возвращает управление, и модуль ничего не делает, пока ядру не понадобится что-то сделать с кодом, который предоставляет модуль.

Все модули заканчиваются вызовом либо `cleanup_module`, либо функции, которую вы указали при вызове `module_exit`. Это выходная функция модуля; она отменяет всё, что сделала входная функция. Она разрегистрирует ту функциональность, которую зарегистрировала входная функция.

Каждый модуль обязан иметь входную и выходную функции. Поскольку существует больше одного способа указать входную и выходную функции, я буду стараться использовать термины «входная функция» и «выходная функция», но если я оговорюсь и назову их просто `init_module` и `cleanup_module`, думаю, вы поймёте, о чём речь.

### 3.1.2. Функции, доступные модулям

Программисты постоянно пользуются функциями, которые сами не определяли. Главный пример тому — `printf()`. Вы используете эти библиотечные функции, предоставляемые стандартной библиотекой языка C — libc. Определения этих функций попадают в вашу программу лишь на этапе компоновки, который гарантирует доступность кода (например, для `printf()`) и исправляет команду вызова так, чтобы она указывала на этот код.

Модули ядра отличаются и здесь. В примере hello world вы могли заметить, что мы использовали функцию `printk()`, но не подключали стандартную библиотеку ввода-вывода. Это оттого, что модули — объектные файлы, символы которых разрешаются при загрузке через insmod. Определения этих символов берутся из самого ядра; единственные внешние функции, которыми вы можете пользоваться, — это функции, предоставленные ядром. Если вам любопытно, какие символы экспортированы вашим ядром, взгляните на `/proc/kallsyms`.

Одна вещь, которую стоит держать в голове, — различие между библиотечными функциями и системными вызовами. Библиотечные функции более высокоуровневые, выполняются полностью в пользовательском пространстве и предоставляют программисту более удобный интерфейс к функциям, делающим настоящую работу, — системным вызовам. Системные вызовы выполняются в режиме ядра от имени пользователя и предоставляются самим ядром. Библиотечная функция `printf()` может выглядеть как очень универсальная функция печати, но всё, что она на самом деле делает, — форматирует данные в строки и записывает строковые данные с помощью низкоуровневого системного вызова `write()`, который затем отправляет данные в стандартный вывод.

Хотите увидеть, какие системные вызовы делает `printf()`? Это просто! Скомпилируйте следующую программу:

```c
#include <stdio.h>
int main(void)
{ printf("hello"); return 0; }
```

командой **gcc -Wall -o hello hello.c**. Запустите исполняемый файл командой **strace ./hello**. Впечатлены? Каждая строка, которую вы видите, соответствует системному вызову. strace[1] — удобная программа, которая сообщает подробности о том, какие системные вызовы делает программа: какой вызов совершается, каковы его аргументы и что он возвращает. Это бесценный инструмент, чтобы выяснять, например, к каким файлам пытается обратиться программа. Ближе к концу вы увидите строку, похожую на `write(1, "hello", 5hello)`. Вот она — лицо, скрытое за маской `printf()`. С write вы можете быть не знакомы, поскольку большинство людей пользуется для файлового ввода-вывода библиотечными функциями (вроде fopen, fputs, fclose). Если это ваш случай, попробуйте посмотреть **man 2 write**. Второй раздел man посвящён системным вызовам (вроде `kill()` и `read()`). Третий раздел man посвящён библиотечным вызовам, с которыми вы, вероятно, лучше знакомы (вроде `cosh()` и `random()`).

Вы даже можете писать модули, подменяющие системные вызовы ядра — чем мы вскоре и займёмся. Взломщики часто используют подобные вещи для бэкдоров и троянов, но вы можете писать собственные модули для куда более безобидных целей — например, чтобы ядро писало _«Хи-хи, щекотно!»_ всякий раз, когда кто-то пытается удалить файл в вашей системе.

### 3.1.3. Пользовательское пространство и пространство ядра

Ядро — это во многом вопрос доступа к ресурсам, будь то видеоплата, жёсткий диск или даже память. Программы часто соперничают за один и тот же ресурс. Только что, когда я сохранял этот документ, updatedb начал обновлять базу locate. Мой сеанс vim и updatedb одновременно используют жёсткий диск. Ядро должно поддерживать порядок и не давать пользователям доступ к ресурсам когда вздумается. Для этого процессор может работать в разных режимах. Каждый режим даёт свой уровень свободы действий в системе. Архитектура Intel 80386 имеет 4 таких режима, называемых кольцами (rings). Unix использует только два кольца: высшее (кольцо 0, также известное как «режим супервизора», где разрешено всё) и низшее, называемое «пользовательским режимом».

Вспомните рассуждение о библиотечных функциях и системных вызовах. Обычно вы используете библиотечную функцию в пользовательском режиме. Библиотечная функция вызывает один или несколько системных вызовов, и эти системные вызовы выполняются от имени библиотечной функции, но в режиме супервизора, поскольку они являются частью самого ядра. Когда системный вызов завершает свою задачу, он возвращает управление, и выполнение передаётся обратно в пользовательский режим.

### 3.1.4. Пространство имён

Когда вы пишете маленькую программу на C, вы используете переменные, удобные и понятные читателю. Если же вы пишете подпрограммы, которые станут частью чего-то большего, любые ваши глобальные переменные становятся частью сообщества глобальных переменных других людей; некоторые имена переменных могут конфликтовать. Когда в программе много глобальных переменных, недостаточно осмысленных, чтобы их различать, возникает _засорение пространства имён (namespace pollution)_. В больших проектах приходится прилагать усилия, чтобы помнить зарезервированные имена и вырабатывать схему именования уникальных имён переменных и символов.

При написании кода ядра даже самый маленький модуль компонуется со всем ядром, так что это безусловно актуальная проблема. Лучший способ с ней справиться — объявлять все свои переменные статическими и использовать хорошо определённый префикс для своих символов. По соглашению все префиксы в ядре пишутся в нижнем регистре. Если вы не хотите объявлять всё статическим, другой вариант — объявить таблицу символов (`symbol table`) и зарегистрировать её в ядре. Мы дойдём до этого позже.

Файл `/proc/kallsyms` содержит все символы, о которых знает ядро и которые, следовательно, доступны вашим модулям, поскольку те разделяют кодовое пространство ядра.

### 3.1.5. Кодовое пространство

Управление памятью — очень сложный предмет: бо́льшая часть книги O'Reilly «Understanding The Linux Kernel» посвящена именно управлению памятью! Мы не ставим целью стать экспертами в управлении памятью, но нам нужно знать пару фактов, чтобы вообще начать думать о написании настоящих модулей.

Если вы никогда не задумывались, что на самом деле означает segfault, вас может удивить тот факт, что указатели в действительности не указывают на ячейки памяти. По крайней мере, не на реальные. Когда создаётся процесс, ядро откладывает часть реальной физической памяти и передаёт её процессу под его исполняемый код, переменные, стек, кучу и прочие вещи, о которых знает учёный-компьютерщик[2]. Эта память начинается с 0x00000000 и простирается настолько, насколько необходимо. Поскольку области памяти любых двух процессов не пересекаются, каждый процесс, обращающийся к адресу памяти, скажем `0xbffff978`, на самом деле обращается к разным местам реальной физической памяти! Процессы обращаются к индексу с именем `0xbffff978`, который указывает на некоторое смещение внутри области памяти, отведённой конкретному процессу. В основном процесс вроде нашей программы Hello, World не может получить доступ к пространству другого процесса, хотя существуют и способы это сделать — о них мы поговорим позже.

У ядра есть и собственное пространство памяти. Поскольку модуль — это код, который можно динамически вставлять в ядро и удалять из него (а не полуавтономный объект), он разделяет кодовое пространство ядра, не имея своего собственного. Поэтому, если ваш модуль падает с segfault, падает и ядро. И если вы начнёте затирать данные из-за ошибки «на единицу» (off-by-one), вы будете топтаться по данным (или коду) ядра. Это хуже, чем звучит, так что старайтесь быть предельно аккуратными.

Кстати, хочу отметить, что всё сказанное выше верно для любой операционной системы с монолитным ядром[3]. Существуют так называемые микроядра, у которых модули получают собственное кодовое пространство. GNU Hurd и QNX Neutrino — два примера микроядра.

### 3.1.6. Драйверы устройств

Один из классов модулей — драйверы устройств, предоставляющие функциональность для оборудования вроде ТВ-карты или последовательного порта. В unix каждый элемент оборудования представлен файлом, расположенным в `/dev`, — файлом устройства (`device file`), который даёт средства связи с этим оборудованием. Драйвер устройства осуществляет связь от имени пользовательской программы. Так, драйвер звуковой карты `es1370.o` может связывать файл устройства `/dev/sound` со звуковой картой Ensoniq IS1370. Программа из пользовательского пространства, например mp3blaster, может использовать `/dev/sound`, вообще не зная, какая звуковая карта установлена.

#### 3.1.6.1. Старшие и младшие номера

Взглянем на некоторые файлы устройств. Вот файлы устройств, представляющие первые три раздела на основном (primary master) жёстком диске IDE:

```text
## ls -l /dev/hda[1-3]
brw-rw----  1 root  disk  3, 1 Jul  5  2000 /dev/hda1
brw-rw----  1 root  disk  3, 2 Jul  5  2000 /dev/hda2
brw-rw----  1 root  disk  3, 3 Jul  5  2000 /dev/hda3
```

Заметили столбец чисел, разделённых запятой? Первое число называется старшим номером (major number) устройства. Второе — младшим номером (minor number). Старший номер говорит, какой драйвер используется для доступа к оборудованию. Каждому драйверу назначен уникальный старший номер; все файлы устройств с одним и тем же старшим номером управляются одним и тем же драйвером. У всех перечисленных выше файлов старший номер — 3, потому что все они управляются одним драйвером.

Младший номер используется драйвером, чтобы различать оборудование, которым он управляет. Возвращаясь к примеру выше: хотя все три устройства обслуживаются одним драйвером, у них уникальные младшие номера, потому что драйвер видит их как разные куски железа.

Устройства делятся на два типа: символьные устройства и блочные устройства. Разница в том, что у блочных устройств есть буфер для запросов, поэтому они могут выбирать наилучший порядок их обработки. Это важно для накопителей, где читать или писать секторы, расположенные рядом, быстрее, чем далеко отстоящие друг от друга. Другое отличие состоит в том, что блочные устройства могут принимать ввод и возвращать вывод только блоками (размер которых может меняться от устройства к устройству), тогда как символьным устройствам позволено использовать сколько угодно байт — много или мало. Большинство устройств в мире — символьные, потому что им не нужен такой буфер и они не работают с фиксированным размером блока. Определить, для блочного или символьного устройства предназначен файл, можно по первому символу в выводе **ls -l**: если это `b` — блочное устройство, если `c` — символьное. Устройства, показанные выше, — блочные. Вот несколько символьных устройств (последовательные порты):

```text
crw-rw----  1 root  dial 4, 64 Feb 18 23:34 /dev/ttyS0
crw-r-----  1 root  dial 4, 65 Nov 17 10:26 /dev/ttyS1
crw-rw----  1 root  dial 4, 66 Jul  5  2000 /dev/ttyS2
crw-rw----  1 root  dial 4, 67 Jul  5  2000 /dev/ttyS3
```

Если вы хотите посмотреть, какие старшие номера уже назначены, загляните в `/usr/src/linux/Documentation/devices.txt`.

При установке системы все эти файлы устройств были созданы командой **mknod**. Чтобы создать новое символьное устройство с именем `coffee` со старшим/младшим номерами `12` и `2`, просто выполните **mknod /dev/coffee c 12 2**. Вы не _обязаны_ размещать свои файлы устройств в `/dev`, но так принято. Линус разместил свои файлы устройств в `/dev` — и вам следует поступать так же. Однако при создании файла устройства в целях тестирования, вероятно, допустимо поместить его в рабочий каталог, где вы компилируете модуль ядра. Только обязательно положите его на надлежащее место, когда закончите писать драйвер устройства.

Хочу сделать пару последних замечаний, которые неявно следуют из сказанного выше, но я хотел бы высказать их явно — на всякий случай. Когда происходит обращение к файлу устройства, ядро по старшему номеру файла определяет, какой драйвер должен обработать это обращение. Это значит, что ядру на самом деле не нужно использовать младший номер и даже знать о нём. О младшем номере заботится только сам драйвер. Драйвер использует младший номер, чтобы различать разные экземпляры оборудования.

Кстати, когда я говорю «оборудование», я имею в виду нечто более абстрактное, чем PCI-карта, которую можно подержать в руках. Посмотрите на эти два файла устройств:

```text
% ls -l /dev/fd0 /dev/fd0u1680
brwxrwxrwx   1 root  floppy   2,  0 Jul  5  2000 /dev/fd0
brw-rw----   1 root  floppy   2, 44 Jul  5  2000 /dev/fd0u1680
```

Теперь вы можете взглянуть на эти два файла устройств и мгновенно понять, что они блочные и обслуживаются одним драйвером (блочный, старший `2`). Вы даже можете знать, что оба они представляют ваш дисковод для гибких дисков, даже если дисковод у вас только один. Почему два файла? Один представляет дисковод с ёмкостью `1.44` МБ. Другой — это _тот же самый_ дисковод с ёмкостью `1.68` МБ, соответствующий тому, что некоторые называют «суперформатируемым» (superformatted) диском — диску, который вмещает больше данных, чем стандартно отформатированная дискета. Вот пример того, как два файла устройств с разными младшими номерами в действительности представляют один и тот же физический узел. Так что имейте в виду: слово «оборудование» в нашем разговоре может означать нечто весьма абстрактное.

#### Примечания

1. Это бесценный инструмент, чтобы выяснять, например, к каким файлам пытается обратиться программа. Бывало у вас, что программа молча падала, потому что не могла найти файл? Это же сущее мучение!
2. Я физик, а не учёный-компьютерщик, Джим!
3. Это не совсем то же самое, что «встроить все ваши модули в ядро», хотя идея та же.

## Глава 4. Файлы символьных устройств

## 4.1. Драйверы символьных устройств

### 4.1.1. Структура file_operations

Структура file_operations определена в `linux/fs.h` и хранит указатели на определённые драйвером функции, которые выполняют различные операции над устройством. Каждое поле структуры соответствует адресу некоторой функции, определённой драйвером для обработки запрошенной операции.

Например, каждому символьному драйверу нужно определить функцию, читающую из устройства. Структура file_operations хранит адрес функции модуля, выполняющей эту операцию. Вот как выглядит определение для ядра `2.6.5`:

```c
struct file_operations {
	struct module *owner;
	 loff_t(*llseek) (struct file *, loff_t, int);
	 ssize_t(*read) (struct file *, char __user *, size_t, loff_t *);
	 ssize_t(*aio_read) (struct kiocb *, char __user *, size_t, loff_t);
	 ssize_t(*write) (struct file *, const char __user *, size_t, loff_t *);
	 ssize_t(*aio_write) (struct kiocb *, const char __user *, size_t,
			      loff_t);
	int (*readdir) (struct file *, void *, filldir_t);
	unsigned int (*poll) (struct file *, struct poll_table_struct *);
	int (*ioctl) (struct inode *, struct file *, unsigned int,
		      unsigned long);
	int (*mmap) (struct file *, struct vm_area_struct *);
	int (*open) (struct inode *, struct file *);
	int (*flush) (struct file *);
	int (*release) (struct inode *, struct file *);
	int (*fsync) (struct file *, struct dentry *, int datasync);
	int (*aio_fsync) (struct kiocb *, int datasync);
	int (*fasync) (int, struct file *, int);
	int (*lock) (struct file *, int, struct file_lock *);
	 ssize_t(*readv) (struct file *, const struct iovec *, unsigned long,
			  loff_t *);
	 ssize_t(*writev) (struct file *, const struct iovec *, unsigned long,
			   loff_t *);
	 ssize_t(*sendfile) (struct file *, loff_t *, size_t, read_actor_t,
			     void __user *);
	 ssize_t(*sendpage) (struct file *, struct page *, int, size_t,
			     loff_t *, int);
	unsigned long (*get_unmapped_area) (struct file *, unsigned long,
					    unsigned long, unsigned long,
					    unsigned long);
};
```

Некоторые операции драйвером не реализуются. Например, драйвер, обслуживающий видеоплату, не нуждается в чтении из структуры каталога. Соответствующие поля структуры file_operations должны быть установлены в `NULL`.

Существует расширение gcc, которое делает присваивание этой структуры более удобным. Вы будете встречать его в современных драйверах, и оно может вас застать врасплох. Вот как выглядит новый способ присваивания структуре:

```c
struct file_operations fops = {
	read: device_read,
	write: device_write,
	open: device_open,
	release: device_release
};
```

Однако есть и способ C99 присваивания элементам структуры, и он определённо предпочтительнее использования расширения GNU. Версия gcc, которой пользовался автор при написании этого текста, — `2.95` — поддерживает новый синтаксис C99. Вам следует использовать именно этот синтаксис на случай, если кто-то захочет портировать ваш драйвер. Это поможет с совместимостью:

```c
struct file_operations fops = {
	.read = device_read,
	.write = device_write,
	.open = device_open,
	.release = device_release
};
```

Смысл очевиден, и вы должны знать: любой элемент структуры, которому вы явно не присвоите значение, gcc инициализирует значением `NULL`.

Экземпляр struct file_operations, содержащий указатели на функции, используемые для реализации системных вызовов read, write, open и так далее, обычно называют `fops`.

### 4.1.2. Структура file

Каждое устройство представлено в ядре структурой file, которая определена в `linux/fs.h`. Имейте в виду, что file — структура уровня ядра, и она никогда не появляется в программе пользовательского пространства. Это не то же самое, что FILE, определённый в glibc, который никогда не появится в функции пространства ядра. К тому же её имя немного вводит в заблуждение: она представляет абстрактный открытый «файл», а не файл на диске — файл на диске представлен структурой с именем inode.

Экземпляр `struct file` обычно называют `filp`. Вы также встретите его под именем `struct file file`. Не поддавайтесь этому соблазну.

Взгляните на определение `file`. Большинство полей, которые вы там увидите, например `struct dentry`, драйверами устройств не используются, и их можно игнорировать. Это оттого, что драйверы не заполняют `file` напрямую; они используют лишь структуры, содержащиеся в `file`, которые созданы в других местах.

### 4.1.3. Регистрация устройства

Как обсуждалось ранее, к символьным устройствам обращаются через файлы устройств, обычно расположенные в `/dev`[1]. Старший номер говорит, какой драйвер обслуживает тот или иной файл устройства. Младший номер используется только самим драйвером, чтобы отличать, с каким устройством он работает, — на случай, если драйвер обслуживает больше одного устройства.

Добавление драйвера в вашу систему означает его регистрацию в ядре. Это синонимично назначению ему старшего номера во время инициализации модуля. Делается это с помощью функции `register_chrdev`, определённой в `linux/fs.h`:

```c
int register_chrdev(unsigned int major, const char *name, struct file_operations *fops);
```

где `unsigned int major` — старший номер, который вы хотите запросить, `const char *name` — имя устройства в том виде, в каком оно появится в `/proc/devices`, а `struct file_operations *fops` — указатель на таблицу `file_operations` вашего драйвера. Отрицательное возвращаемое значение означает, что регистрация не удалась. Обратите внимание: мы не передаём младший номер в `register_chrdev`. Это потому, что ядру младший номер безразличен; им пользуется только наш драйвер.

Теперь вопрос: как получить старший номер, не узурпировав уже занятый? Проще всего было бы просмотреть `Documentation/devices.txt` и подобрать неиспользуемый. Но это плохой способ: вы никогда не будете уверены, что выбранное вами число не назначат позже. Ответ состоит в том, что вы можете попросить ядро назначить вам динамический старший номер.

Если передать в `register_chrdev` старший номер 0, возвращаемым значением будет динамически выделенный старый номер. Минус в том, что заранее создать файл устройства нельзя, поскольку вы не знаете, каким будет старший номер. Есть пара способов это обойти. Во-первых, сам драйвер может напечатать только что назначенный номер, и мы сможем создать файл устройства вручную. Во-вторых, у только что зарегистрированного устройства появится запись в `/proc/devices`, и мы можем либо создать файл устройства вручную, либо написать сценарий оболочки, который прочитает этот файл и создаст файл устройства. Третий способ — поручить нашему драйверу создавать файл устройства системным вызовом `mknod` после успешной регистрации и удалять его в вызове `cleanup_module`.

### 4.1.4. Разрегистрация устройства

Мы не можем позволить выгружать модуль ядра (rmmod) когда root вздумается. Если файл устройства открыт процессом, а мы затем удалим модуль ядра, использование файла приведёт к вызову по тому адресу памяти, где раньше находилась соответствующая функция (read/write). Если нам повезёт, туда не был загружен другой код, и мы получим уродливое сообщение об ошибке. Если не повезёт, в то же место был загружен другой модуль ядра — и произойдёт прыжок в середину другой функции внутри ядра. Последствия такого невозможно предсказать, но ничего хорошего они сулить не могут.

Обычно, когда вы хотите что-то запретить, вы возвращаете код ошибки (отрицательное число) из функции, которая должна это делать. С `cleanup_module` это невозможно, поскольку она — void-функция. Однако существует счётчик, который отслеживает, сколько процессов использует ваш модуль. Посмотреть его значение можно в третьем поле `/proc/modules`. Если это число не равно нулю, `rmmod` завершится неудачей. Заметьте, что проверять счётчик изнутри `cleanup_module` не нужно, поскольку проверка будет выполнена за вас системным вызовом `sys_delete_module`, определённым в `linux/module.c`. Использовать этот счётчик напрямую не следует, но в `linux/module.h` есть функции, позволяющие его увеличивать, уменьшать и отображать:

* `try_module_get(THIS_MODULE)`: увеличить счётчик использования.

* `module_put(THIS_MODULE)`: уменьшить счётчик использования.

Важно, чтобы счётчик был точным; если вы когда-нибудь потеряете верное значение счётчика использования, выгрузить модуль уже не удастся — придётся перезагружаться, друзья. Рано или поздно это обязательно случится с вами в ходе разработки модуля.

### 4.1.5. chardev.c

Следующий пример кода создаёт символьный драйвер с именем `chardev`. Вы можете выполнить `cat` его файла устройства (или `open` файл с помощью программы), и драйвер поместит в файл число, показывающее, сколько раз с файла устройства читали. Запись в файл (вроде **echo "hi" > /dev/hello**) не поддерживается, но такие попытки перехватываются, и пользователь получает сообщение о том, что операция не поддерживается. Не переживайте, если не видите, что мы делаем с данными, которые читаем в буфер: мы делаем с ними не так много. Мы просто читаем данные и печатаем сообщение с подтверждением того, что получили их.

**Пример 4-1. chardev.c**
```c
/*
 *  chardev.c: Создаёт символьное устройство только для чтения,
 *  сообщающее, сколько раз вы читали из файла устройства
 */

#include <linux/kernel.h>
#include <linux/module.h>
#include <linux/fs.h>
#include <asm/uaccess.h>	/* для put_user */

/*
 *  Прототипы - обычно они располагаются в .h файле
 */
int init_module(void);
void cleanup_module(void);
static int device_open(struct inode *, struct file *);
static int device_release(struct inode *, struct file *);
static ssize_t device_read(struct file *, char *, size_t, loff_t *);
static ssize_t device_write(struct file *, const char *, size_t, loff_t *);

#define SUCCESS 0
#define DEVICE_NAME "chardev"	/* Имя устройства, каким оно появляется в /proc/devices */
#define BUF_LEN 80		/* Максимальная длина сообщения от устройства */

/*
 * Глобальные переменные объявлены как static, то есть глобальны в пределах файла.
 */

static int Major;		/* Старший номер, назначенный нашему драйверу устройства */
static int Device_Open = 0;	/* Устройство открыто?
				 * Используется для предотвращения многократного доступа к устройству */
static char msg[BUF_LEN];	/* Сообщение, которое устройство выдаст по запросу */
static char *msg_Ptr;

static struct file_operations fops = {
	.read = device_read,
	.write = device_write,
	.open = device_open,
	.release = device_release
};

/*
 * Эта функция вызывается при загрузке модуля
 */
int init_module(void)
{
        Major = register_chrdev(0, DEVICE_NAME, &fops);

	if (Major < 0) {
	  printk(KERN_ALERT "Registering char device failed with %d\n", Major);
	  return Major;
	}

	printk(KERN_INFO "I was assigned major number %d. To talk to\n", Major);
	printk(KERN_INFO "the driver, create a dev file with\n");
	printk(KERN_INFO "'mknod /dev/%s c %d 0'.\n", DEVICE_NAME, Major);
	printk(KERN_INFO "Try various minor numbers. Try to cat and echo to\n");
	printk(KERN_INFO "the device file.\n");
	printk(KERN_INFO "Remove the device file and module when done.\n");

	return SUCCESS;
}

/*
 * Эта функция вызывается при выгрузке модуля
 */
void cleanup_module(void)
{
	/*
	 * Разрегистрируем устройство
	 */
	int ret = unregister_chrdev(Major, DEVICE_NAME);
	if (ret < 0)
		printk(KERN_ALERT "Error in unregister_chrdev: %d\n", ret);
}

/*
 * Методы
 */

/*
 * Вызывается, когда процесс пытается открыть файл устройства,
 * например "cat /dev/mycharfile"
 */
static int device_open(struct inode *inode, struct file *file)
{
	static int counter = 0;

	if (Device_Open)
		return -EBUSY;

	Device_Open++;
	sprintf(msg, "I already told you %d times Hello world!\n", counter++);
	msg_Ptr = msg;
	try_module_get(THIS_MODULE);

	return SUCCESS;
}

/*
 * Вызывается, когда процесс закрывает файл устройства.
 */
static int device_release(struct inode *inode, struct file *file)
{
	Device_Open--;		/* Теперь мы готовы к следующему вызывающему */

	/*
	 * Уменьшаем счётчик использования, иначе после открытия файла
	 * вы уже никогда не избавитесь от модуля.
	 */
	module_put(THIS_MODULE);

	return 0;
}

/*
 * Вызывается, когда процесс, уже открывший файл устройства,
 * пытается читать из него.
 */
static ssize_t device_read(struct file *filp,	/* см. include/linux/fs.h      */
			   char *buffer,	/* буфер для заполнения данными */
			   size_t length,	/* длина буфера                 */
			   loff_t * offset)
{
	/*
	 * Количество байт, фактически записанных в буфер
	 */
	int bytes_read = 0;

	/*
	 * Если мы в конце сообщения,
	 * возвращаем 0, обозначая конец файла
	 */
	if (*msg_Ptr == 0)
		return 0;

	/*
	 * Собственно помещаем данные в буфер
	 */
	while (length && *msg_Ptr) {

		/*
		 * Буфер находится в сегменте данных пользователя, а не ядра,
		 * поэтому присваивание "*" не сработает. Придётся использовать
		 * put_user, который копирует данные из сегмента данных ядра
		 * в сегмент данных пользователя.
		 */
		put_user(*(msg_Ptr++), buffer++);

		length--;
		bytes_read++;
	}

	/*
	 * Большинство функций чтения возвращают количество байт, помещённых в буфер
	 */
	return bytes_read;
}

/*
 * Вызывается, когда процесс пишет в файл устройства: echo "hi" > /dev/hello
 */
static ssize_t
device_write(struct file *filp, const char *buff, size_t len, loff_t * off)
{
	printk(KERN_ALERT "Sorry, this operation isn't supported.\n");
	return -EINVAL;
}
```

### 4.1.6. Написание модулей для нескольких версий ядра

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

Версии ядра Linux делятся на стабильные (n.<чётное число>.m) и разрабатываемые (n.<нечётное число>.m). Разрабатываемые версии включают все классные новые идеи, в том числе и те, которые в следующей версии будут признаны ошибкой или переделаны. Поэтому в этих версиях нельзя рассчитывать, что интерфейс останется прежним (по этой причине я не утруждаю себя поддержкой их в этой книге — слишком много работы, и она слишком быстро устарела бы). В стабильных же версиях, напротив, можно ожидать, что интерфейс останется неизменным независимо от номера исправления багов (числа m).

Между разными версиями ядра есть различия, и если вы хотите поддерживать несколько версий ядра, вам придётся писать директивы условной компиляции. Делается это сравнением макроса `LINUX_VERSION_CODE` с макросом `KERNEL_VERSION`. В версии ядра `a.b.c` значение этого макроса будет равно $2^{16}a+2^{8}b+c$.

Хотя предыдущие версии этого руководства подробно показывали, как с помощью таких конструкций писать обратно совместимый код, мы решили отказаться от этой традиции — и не без пользы. Тем, кому это интересно, теперь следует использовать LKMPG с версией, соответствующей их ядру. Мы решили присваивать LKMPG версии так же, как ядру, — по крайней мере, в части старшего и младшего номеров. Уровень патчей (patchlevel) мы используем для собственной нумерации: используйте LKMPG версии 2.4.x для ядер 2.4.x, LKMPG версии 2.6.x для ядер 2.6.x и так далее. Также всегда следите, чтобы и ядро, и руководство были актуальными, последними версиями.

Обновление: всё сказанное выше было верно для ядер вплоть до версии 2.6.10 включительно. Вы могли уже заметить, что недавние ядра выглядят иначе. Если нет — теперь они выглядят как 2.6.x.y. Смысл первых трёх чисел в основном остаётся тем же, но был добавлен уровень подпатчей (subpatchlevel), который будет обозначать исправления безопасности до выхода следующего стабильного уровня патчей. Так что люди могут выбирать между стабильным деревом с обновлениями безопасности _и_ использовать новейшее ядро в качестве дерева разработчиков. Поищите в архивах списка рассылки ядра, если вас интересует полная история.

#### Примечания

1. Так положено по соглашению. При написании драйвера допустимо поместить файл устройства в текущий каталог. Только обязательно разместите его в `/dev` для боевого драйвера.

---

## Глава 5. Файловая система /proc

## 5.1. Файловая система /proc

В Linux существует дополнительный механизм, с помощью которого ядро и модули ядра могут передавать информацию процессам, — файловая система `/proc`. Изначально она была разработана для удобного доступа к информации о процессах (отсюда и название), но теперь её использует каждая частица ядра, которой есть что интересного сообщить: например, `/proc/modules`, выдающая список модулей, и `/proc/meminfo`, которая сообщает статистику использования памяти.

Метод работы с файловой системой proc очень похож на тот, что используется с драйверами устройств: создаётся структура, содержащая всю необходимую для файла `/proc` информацию, включая указатели на функции-обработчики (в нашем случае такая функция одна — та, что вызывается, когда кто-то пытается прочитать файл `/proc`). Затем `init_module` регистрирует эту структуру в ядре, а `cleanup_module` отменяет регистрацию.

Мы используем `proc_register_dynamic`[1] потому, что не хотим заранее определять номер inode, используемый для нашего файла, а предпочитаем позволить ядру определить его самому, чтобы предотвратить конфликты. Обычные файловые системы располагаются на диске, а не только в памяти (где и находится `/proc`), и в этом случае номер inode — это указатель на место на диске, где расположен индексный узел файла (сокращённо inode). Inode содержит информацию о файле, например права доступа к нему, а также указатель на место или места на диске, где могут находиться данные файла.

Поскольку нас не вызывают при открытии и закрытии файла, в этом модуле нам некуда поместить `try_module_get` и `try_module_put`, и если файл открыт, а затем модуль удалён, избежать последствий невозможно.

Вот простой пример, показывающий, как использовать файл /proc. Это HelloWorld для файловой системы /proc. В нём три части: создать файл `/proc/helloworld` в функции `init_module`, вернуть значение (и буфер) при чтении файла `/proc/helloworld` в функции обратного вызова (callback) `procfs_read` и удалить файл `/proc/helloworld` в функции `cleanup_module`.

Файл `/proc/helloworld` создаётся при загрузке модуля с помощью функции `create_proc_entry`. Возвращаемое значение имеет тип `struct proc_dir_entry *` и используется для настройки файла `/proc/helloworld` (например, его владельца). Нулевое возвращаемое значение означает, что создание завершилось неудачей.

Каждый раз, когда файл `/proc/helloworld` читается, вызывается функция `procfs_read`. Два параметра этой функции очень важны: буфер (первый параметр) и смещение (offset, третий параметр). Содержимое буфера будет возвращено приложению, которое его прочитало (например, команде cat). Смещение — это текущая позиция в файле. Если возвращаемое значение функции не равно нулю, функция вызывается снова. Так что будьте осторожны с этой функцией: если она никогда не вернёт ноль, функция чтения будет вызываться бесконечно.

```text
% cat /proc/helloworld
HelloWorld!
```

**Пример 5-1. procfs1.c**

```c
/*
 *  procfs1.c -  создать "файл" в /proc
 *
 */

#include <linux/module.h>	/* В частности, модуль */
#include <linux/kernel.h>	/* Мы работаем над ядром */
#include <linux/proc_fs.h>	/* Необходимы, так как мы используем proc fs */

#define procfs_name "helloworld"

/**
 * Эта структура хранит информацию о файле /proc
 *
 */
struct proc_dir_entry *Our_Proc_File;

/* Поместить данные в файл proc fs.
 * 
 * Аргументы
 * =========
 * 1. Буфер, куда следует вставить данные, если
 *    вы решите его использовать.
 * 2. Указатель на указатель на символы. Это
 *    полезно, если вы не хотите использовать буфер,
 *    выделенный ядром.
 * 3. Текущая позиция в файле
 * 4. Размер буфера из первого аргумента.
 * 5. Запишите сюда "1", чтобы обозначить конец файла (EOF).
 * 6. Указатель на данные (полезен на случай одного общего
 *    чтения для нескольких записей /proc/...)
 *
 * Использование и возвращаемое значение
 * ======================
 * Возвращаемое значение, равное нулю, означает, что
 * на данный момент у вас нет дальнейшей информации
 * (конец файла). Отрицательное возвращаемое значение
 * означает ошибку.
 *
 * Для дополнительной информации
 * ====================
 * Способ, которым я выяснил, что делать с этой функцией,
 * заключался не в чтении документации, а в чтении
 * кода, который её использует. Я просто посмотрел, что
 * использует поле get_info структуры proc_dir_entry (я
 * использовал комбинацию find и grep, если вам
 * интересно), и увидел, что она используется в <каталог
 * исходников ядра>/fs/proc/array.c.
 *
 * Если о ядре что-то неизвестно, это
 * обычно верный путь. В Linux у нас есть огромное
 * преимущество — бесплатные исходные коды
 * ядра - пользуйтесь ими.
 */
int
procfile_read(char *buffer,
	      char **buffer_location,
	      off_t offset, int buffer_length, int *eof, void *data)
{
	int ret;
	
	printk(KERN_INFO "procfile_read (/proc/%s) called\n", procfs_name);
	
	/* 
	 * Мы отдаём всю нашу информацию за один раз, поэтому если
	 * пользователь спросит нас, есть ли у нас ещё информация,
	 * ответ всегда должен быть «нет».
	 *
	 * Это важно, потому что стандартная функция чтения
	 * из библиотеки будет продолжать выдавать
	 * системный вызов read, пока ядро не ответит,
	 * что у него больше нет информации, или пока её
	 * буфер не заполнится.
	 */
	if (offset > 0) {
		/* мы закончили чтение, возвращаем 0 */
		ret  = 0;
	} else {
		/* заполняем буфер, возвращаем размер буфера */
		ret = sprintf(buffer, "HelloWorld!\n");
	}

	return ret;
}

int init_module()
{
	Our_Proc_File = create_proc_entry(procfs_name, 0644, NULL);
	
	if (Our_Proc_File == NULL) {
		remove_proc_entry(procfs_name, &proc_root);
		printk(KERN_ALERT "Error: Could not initialize /proc/%s\n",
		       procfs_name);
		return -ENOMEM;
	}

	Our_Proc_File->read_proc = procfile_read;
	Our_Proc_File->owner 	 = THIS_MODULE;
	Our_Proc_File->mode 	 = S_IFREG | S_IRUGO;
	Our_Proc_File->uid 	 = 0;
	Our_Proc_File->gid 	 = 0;
	Our_Proc_File->size 	 = 37;

	printk(KERN_INFO "/proc/%s created\n", procfs_name);	
	return 0;	/* всё в порядке */
}

void cleanup_module()
{
	remove_proc_entry(procfs_name, &proc_root);
	printk(KERN_INFO "/proc/%s removed\n", procfs_name);
}
```

#### Примечания

[1] В версии 2.0; в версии 2.2 это делается автоматически, если мы зададим inode равным нулю.

## 5.2. Чтение и запись файла /proc

Мы видели очень простой пример файла /proc, в котором мы только читали файл `/proc/helloworld`. В файл /proc также можно и писать. Это работает так же, как чтение: при записи в файл /proc вызывается функция. Но есть небольшое отличие от чтения: данные приходят от пользователя, поэтому вам нужно импортировать данные из пространства пользователя (user space) в пространство ядра (kernel space) — с помощью `copy_from_user` или `get_user`.

Причина существования `copy_from_user` и `get_user` в том, что память в Linux (на архитектуре Intel; на некоторых других процессорах может быть иначе) сегментирована. Это означает, что сам по себе указатель не ссылается на уникальное место в памяти — только на место в сегменте памяти, и чтобы воспользоваться им, нужно знать, о каком сегменте памяти идёт речь. Существует один сегмент памяти для ядра и по одному для каждого процесса.

Процессу доступен только его собственный сегмент памяти, поэтому при написании обычных программ, работающих как процессы, беспокоиться о сегментах нет нужды. Когда вы пишете модуль ядра, обычно вы хотите работать с сегментом памяти ядра, и система обрабатывает это автоматически. Однако когда содержимое буфера памяти нужно передать между текущим выполняющимся процессом и ядром, функция ядра получает указатель на буфер памяти, находящийся в сегменте процесса. Макросы `put_user` и `get_user` позволяют обращаться к этой памяти. Эти функции работают только с одним символом; несколько символов можно обработать с помощью `copy_to_user` и `copy_from_user`. Поскольку буфер (в функции чтения или записи) находится в пространстве ядра, для функции записи нужно импортировать данные, потому что они приходят из пространства пользователя, а для функции чтения — нет, потому что данные уже находятся в пространстве ядра.

**Пример 5-2. procfs2.c**

```c
/**
 *  procfs2.c -  создать "файл" в /proc
 *
 */

#include <linux/module.h>	/* В частности, модуль */
#include <linux/kernel.h>	/* Мы работаем над ядром */
#include <linux/proc_fs.h>	/* Необходимы, так как мы используем proc fs */
#include <asm/uaccess.h>	/* для copy_from_user */

#define PROCFS_MAX_SIZE		1024
#define PROCFS_NAME 		"buffer1k"

/**
 * Эта структура хранит информацию о файле /proc
 *
 */
static struct proc_dir_entry *Our_Proc_File;

/**
 * Буфер, используемый для хранения символов этого модуля
 *
 */
static char procfs_buffer[PROCFS_MAX_SIZE];

/**
 * Размер буфера
 *
 */
static unsigned long procfs_buffer_size = 0;

/** 
 * Эта функция вызывается при чтении файла /proc
 *
 */
int 
procfile_read(char *buffer,
	      char **buffer_location,
	      off_t offset, int buffer_length, int *eof, void *data)
{
	int ret;
	
	printk(KERN_INFO "procfile_read (/proc/%s) called\n", PROCFS_NAME);
	
	if (offset > 0) {
		/* мы закончили чтение, возвращаем 0 */
		ret  = 0;
	} else {
		/* заполняем буфер, возвращаем размер буфера */
		memcpy(buffer, procfs_buffer, procfs_buffer_size);
		ret = procfs_buffer_size;
	}

	return ret;
}

/**
 * Эта функция вызывается при записи в файл /proc
 *
 */
int procfile_write(struct file *file, const char *buffer, unsigned long count,
		   void *data)
{
	/* получаем размер буфера */
	procfs_buffer_size = count;
	if (procfs_buffer_size > PROCFS_MAX_SIZE ) {
		procfs_buffer_size = PROCFS_MAX_SIZE;
	}
	
	/* записываем данные в буфер */
	if ( copy_from_user(procfs_buffer, buffer, procfs_buffer_size) ) {
		return -EFAULT;
	}
	
	return procfs_buffer_size;
}

/**
 * Эта функция вызывается при загрузке модуля
 *
 */
int init_module()
{
	/* создаём файл /proc */
	Our_Proc_File = create_proc_entry(PROCFS_NAME, 0644, NULL);
	
	if (Our_Proc_File == NULL) {
		remove_proc_entry(PROCFS_NAME, &proc_root);
		printk(KERN_ALERT "Error: Could not initialize /proc/%s\n",
			PROCFS_NAME);
		return -ENOMEM;
	}

	Our_Proc_File->read_proc  = procfile_read;
	Our_Proc_File->write_proc = procfile_write;
	Our_Proc_File->owner 	  = THIS_MODULE;
	Our_Proc_File->mode 	  = S_IFREG | S_IRUGO;
	Our_Proc_File->uid 	  = 0;
	Our_Proc_File->gid 	  = 0;
	Our_Proc_File->size 	  = 37;

	printk(KERN_INFO "/proc/%s created\n", PROCFS_NAME);	
	return 0;	/* всё в порядке */
}

/**
 * Эта функция вызывается при выгрузке модуля
 *
 */
void cleanup_module()
{
	remove_proc_entry(PROCFS_NAME, &proc_root);
	printk(KERN_INFO "/proc/%s removed\n", PROCFS_NAME);
}
```
## 5.3. Управление файлом /proc с помощью стандартной файловой системы

Мы видели, как читать и записывать файл /proc через интерфейс /proc. Но управлять файлом /proc можно также и с помощью inode. Главный интерес здесь в использовании продвинутых возможностей, таких как права доступа.

В Linux существует стандартный механизм регистрации файловых систем. Поскольку у каждой файловой системы должны быть собственные функции для обработки операций с inode и файлами[1], существует специальная структура, хранящая указатели на все эти функции, — `struct inode_operations`, которая включает указатель на `struct file_operations`. В /proc, когда бы мы ни регистрировали новый файл, мы можем указать, какая `struct inode_operations` будет использована для доступа к нему. Именно этот механизм мы и используем: `struct inode_operations`, включающая указатель на `struct file_operations`, которая в свою очередь включает указатели на наши функции `procfs_read` и `procfs_write`.

Ещё один интересный момент здесь — функция `module_permission`. Она вызывается всякий раз, когда процесс пытается что-то сделать с файлом `/proc`, и может решить, разрешить доступ или нет. Сейчас решение основано только на операции и uid текущего пользователя (доступном через `current` — указатель на структуру, содержащую информацию о текущем выполняющемся процессе), но оно может основываться на чём угодно: например, на том, что другие процессы делают с этим же файлом, на времени суток или на последних полученных нами входных данных.

Важно отметить, что привычные роли чтения и записи в ядре перевёрнуты. Функции чтения используются для вывода, тогда как функции записи — для ввода. Причина в том, что чтение и запись рассматриваются с точки зрения пользователя: если процесс читает что-то из ядра, то ядру нужно это вывести, а если процесс записывает что-то в ядро, то ядро получает это как ввод.

**Пример 5-3. procfs3.c**

```c
/* 
 *  procfs3.c -  создать "файл" в /proc, используя способ file_operation
 *  		для управления файлом.
 */
     
#include <linux/kernel.h>	/* Мы работаем над ядром */
#include <linux/module.h>	/* В частности, модуль */
#include <linux/proc_fs.h>	/* Необходимы, так как мы используем proc fs */
#include <asm/uaccess.h>	/* для copy_*_user */

#define PROC_ENTRY_FILENAME 	"buffer2k"
#define PROCFS_MAX_SIZE 	2048

/**
 * Буфер (2k) для этого модуля
 *
 */
static char procfs_buffer[PROCFS_MAX_SIZE];

/**
 * Размер данных, хранящихся в буфере
 *
 */
static unsigned long procfs_buffer_size = 0;

/**
 * Структура, хранящая информацию о файле /proc
 *
 */
static struct proc_dir_entry *Our_Proc_File;

/**
 * Эта функция вызывается при чтении файла /proc
 *
 */
static ssize_t procfs_read(struct file *filp,	/* см. include/linux/fs.h   */
			     char *buffer,	/* буфер для заполнения данными */
			     size_t length,	/* длина буфера     */
			     loff_t * offset)
{
	static int finished = 0;

	/* 
	 * Мы возвращаем 0, чтобы обозначить конец файла — что у нас
	 * больше нет информации. Иначе процессы будут
	 * продолжать читать из нас в бесконечном цикле. 
	 */
	if ( finished ) {
		printk(KERN_INFO "procfs_read: END\n");
		finished = 0;
		return 0;
	}
	
	finished = 1;
		
	/* 
	 * Мы используем put_to_user, чтобы скопировать строку из сегмента
	 * памяти ядра в сегмент памяти процесса,
	 * который нас вызвал. get_from_user, кстати,
	 * используется для обратного. 
	 */
	if ( copy_to_user(buffer, procfs_buffer, procfs_buffer_size) ) {
		return -EFAULT;
	}

	printk(KERN_INFO "procfs_read: read %lu bytes\n", procfs_buffer_size);

	return procfs_buffer_size;	/* Возвращаем количество «прочитанных» байтов */
}

/*
 * Эта функция вызывается при записи в /proc
 */
static ssize_t
procfs_write(struct file *file, const char *buffer, size_t len, loff_t * off)
{
	if ( len > PROCFS_MAX_SIZE )	{
		procfs_buffer_size = PROCFS_MAX_SIZE;
	}
	else	{
		procfs_buffer_size = len;
	}
	
	if ( copy_from_user(procfs_buffer, buffer, procfs_buffer_size) ) {
		return -EFAULT;
	}

	printk(KERN_INFO "procfs_write: write %lu bytes\n", procfs_buffer_size);
	
	return procfs_buffer_size;
}

/* 
 * Эта функция решает, разрешить операцию (вернуть ноль)
 * или не разрешить её (вернуть ненулевое значение,
 * которое объясняет, почему она не разрешена).
 *
 * Операция может принимать одно из следующих значений:
 * 0 - Выполнение (запуск "файла" - в нашем случае бессмысленно)
 * 2 - Запись (ввод в модуль ядра)
 * 4 - Чтение (вывод из модуля ядра)
 *
 * Это и есть настоящая функция, которая проверяет права
 * доступа к файлу. Права, возвращаемые ls -l, даны
 * только для справки и могут быть переопределены здесь.
 */
     
static int module_permission(struct inode *inode, int op, struct nameidata *foo)
{
	/* 
	 * Мы позволяем всем читать из нашего модуля, но
	 * писать в него может только root (uid 0) 
	 */
	if (op == 4 || (op == 2 && current->euid == 0))
		return 0;

	/* 
	 * Если это что-то иное, доступ запрещён 
	 */
	return -EACCES;
}

/* 
 * Файл открыт - нам, в общем-то, всё равно, но
 * это значит, что нужно увеличить счётчик
 * ссылок модуля. 
 */
int procfs_open(struct inode *inode, struct file *file)
{
	try_module_get(THIS_MODULE);
	return 0;
}

/* 
 * Файл закрыт - снова интересно только
 * из-за счётчика ссылок. 
 */
int procfs_close(struct inode *inode, struct file *file)
{
	module_put(THIS_MODULE);
	return 0;		/* успех */
}

static struct file_operations File_Ops_4_Our_Proc_File = {
	.read 	 = procfs_read,
	.write 	 = procfs_write,
	.open 	 = procfs_open,
	.release = procfs_close,
};

/* 
 * Операции с inode для нашего файла proc. Она нужна нам, чтобы
 * было где указать структуру операций над файлами,
 * которую мы хотим использовать, и функцию, которую мы
 * используем для проверки прав. Также можно указать функции,
 * вызываемые для всего остального, что можно сделать
 * с inode (хотя мы не утруждаемся и просто
 * пишем NULL). 
 */
     
static struct inode_operations Inode_Ops_4_Our_Proc_File = {
	.permission = module_permission,	/* проверка прав доступа */
};

/* 
 * Инициализация и очистка модуля 
 */
int init_module()
{
	/* создаём файл /proc */
	Our_Proc_File = create_proc_entry(PROC_ENTRY_FILENAME, 0644, NULL);
	
	/* проверяем, успешно ли создан файл /proc */
	if (Our_Proc_File == NULL){
		printk(KERN_ALERT "Error: Could not initialize /proc/%s\n",
		       PROC_ENTRY_FILENAME);
		return -ENOMEM;
	}
	
	Our_Proc_File->owner = THIS_MODULE;
	Our_Proc_File->proc_iops = &Inode_Ops_4_Our_Proc_File;
	Our_Proc_File->proc_fops = &File_Ops_4_Our_Proc_File;
	Our_Proc_File->mode = S_IFREG | S_IRUGO | S_IWUSR;
	Our_Proc_File->uid = 0;
	Our_Proc_File->gid = 0;
	Our_Proc_File->size = 80;

	printk(KERN_INFO "/proc/%s created\n", PROC_ENTRY_FILENAME);

	return 0;	/* успех */
}

void cleanup_module()
{
	remove_proc_entry(PROC_ENTRY_FILENAME, &proc_root);
	printk(KERN_INFO "/proc/%s removed\n", PROC_ENTRY_FILENAME);
}
```

Всё ещё не наелись примерами procfs? Что ж, во-первых, имейте в виду: ходят слухи, что procfs доживает свои дни, и стоит подумать об использовании sysfs вместо неё. Во-вторых, если вам действительно мало, ниже ` linux/Documentation/DocBook/ ` есть очень рекомендуемый бонусный уровень по procfs. Используйте **make help** в каталоге верхнего уровня исходников ядра, чтобы получить инструкции о том, как преобразовать его в ваш любимый формат. Например: **make htmldocs**. Подумайте об использовании этого механизма, если сами захотите задокументировать что-то, связанное с ядром.

#### Примечания

[1] Разница между ними в том, что операции над файлами имеют дело с самим файлом, а операции с inode — со способами ссылаться на файл, например создавать ссылки на него.

## 5.4. Управление файлом /proc с помощью seq_file

Как мы видели, написание файла /proc может оказаться довольно «сложным» занятием. Поэтому, чтобы помочь людям писать файлы /proc, существует API под названием seq_file, который помогает форматировать файл /proc для вывода. Он основан на последовательности (sequence), которая состоит из трёх функций: start(), next() и stop(). API seq_file запускает последовательность, когда пользователь читает файл /proc.

Последовательность начинается с вызова функции start(). Если возвращается ненулевое (не NULL) значение, вызывается функция next(). Эта функция является итератором; её цель — пройти по всем данным. Каждый раз, когда вызывается next(), вызывается и функция show(). Она записывает значения данных в буфер, читаемый пользователем. Функция next() вызывается до тех пор, пока не вернёт NULL. Последовательность завершается, когда next() возвращает NULL, и тогда вызывается функция stop().

БУДЬТЕ ВНИМАТЕЛЬНЫ: когда одна последовательность заканчивается, начинается другая. Это значит, что в конце функции stop() функция start() вызывается снова. Этот цикл завершается, когда функция start() возвращает NULL. Схему этого процесса вы можете увидеть на рисунке «Как работает seq_file».

**Рисунок 5-1. Как работает seq_file**

![](figures/seq_file.png)

Seq_file предоставляет базовые функции для file_operations, такие как seq_read, seq_lseek и некоторые другие. Но ничего для записи в файл /proc. Конечно, вы по-прежнему можете использовать тот же способ, что и в предыдущем примере.

**Пример 5-4. procfs4.c**

```c
/**
 *  procfs4.c -  создать "файл" в /proc
 * 	Эта программа использует библиотеку seq_file для управления файлом /proc.
 *
 */

#include <linux/kernel.h>	/* Мы работаем над ядром */
#include <linux/module.h>	/* В частности, модуль */
#include <linux/proc_fs.h>	/* Необходимы, так как мы используем proc fs */
#include <linux/seq_file.h>	/* для seq_file */

#define PROC_NAME	"iter"

MODULE_AUTHOR("Philippe Reynes");
MODULE_LICENSE("GPL");

/**
 * Эта функция вызывается в начале последовательности.
 * т.е. когда:
 *	- файл /proc читается (первый раз)
 *	- после функции stop (конец последовательности)
 *
 */
static void *my_seq_start(struct seq_file *s, loff_t *pos)
{
	static unsigned long counter = 0;

	/* начинаем новую последовательность ? */	
	if ( *pos == 0 )
	{	
		/* да => возвращаем ненулевое значение, чтобы начать последовательность */
		return &counter;
	}
	else
	{
		/* нет => это конец последовательности, возвращаем конец, чтобы прекратить чтение */
		*pos = 0;
		return NULL;
	}
}

/**
 * Эта функция вызывается после начала последовательности.
 * Она вызывается, пока не будет возвращено NULL (это завершает последовательность).
 *
 */
static void *my_seq_next(struct seq_file *s, void *v, loff_t *pos)
{
	unsigned long *tmp_v = (unsigned long *)v;
	(*tmp_v)++;
	(*pos)++;
	return NULL;
}

/**
 * Эта функция вызывается в конце последовательности
 * 
 */
static void my_seq_stop(struct seq_file *s, void *v)
{
	/* ничего делать не нужно, мы используем статическое значение в start() */
}

/**
 * Эта функция вызывается для каждого "шага" последовательности
 *
 */
static int my_seq_show(struct seq_file *s, void *v)
{
	loff_t *spos = (loff_t *) v;
	
	seq_printf(s, "%Ld\n", *spos);
	return 0;
}

/**
 * Эта структура собирает "функции" для управления последовательностью
 *
 */
static struct seq_operations my_seq_ops = {
	.start = my_seq_start,
	.next  = my_seq_next,
	.stop  = my_seq_stop,
	.show  = my_seq_show
};

/**
 * Эта функция вызывается при открытии файла /proc.
 *
 */
static int my_open(struct inode *inode, struct file *file)
{
	return seq_open(file, &my_seq_ops);
};

/**
 * Эта структура собирает "функции", управляющие файлом /proc
 *
 */
static struct file_operations my_file_ops = {
	.owner   = THIS_MODULE,
	.open    = my_open,
	.read    = seq_read,
	.llseek  = seq_lseek,
	.release = seq_release
};
	
	
/**
 * Эта функция вызывается при загрузке модуля
 *
 */
int init_module(void)
{
	struct proc_dir_entry *entry;

	entry = create_proc_entry(PROC_NAME, 0, NULL);
	if (entry) {
		entry->proc_fops = &my_file_ops;
	}
	
	return 0;
}

/**
 * Эта функция вызывается при выгрузке модуля.
 *
 */
void cleanup_module(void)
{
	remove_proc_entry(PROC_NAME, NULL);
}
```

Если вы хотите узнать больше, можете прочитать эти веб-страницы:

  * <http://lwn.net/Articles/22355/>

  * <http://www.kernelnewbies.org/documents/seq_file_howto.txt>

Вы также можете прочитать код fs/seq_file.c в ядре Linux.

---

## Глава 6. Использование /proc для ввода

### 6.1. TODO: Написать главу о sysfs

Пока это лишь заглушка. В конечном счёте здесь должна появиться (ещё не написанная) глава о sysfs. Если вы знакомы с sysfs и хотите поучаствовать в написании этой главы, обращайтесь к мейнтейнерам LKMPG за деталями.

## Глава 7. Общение с файлами устройств

### 7.1. Общение с файлами устройств (запись и IOCTL)

Файлы устройств должны представлять физические устройства. Большинство физических устройств используется и для вывода, и для ввода, поэтому должен существовать механизм, позволяющий драйверам устройств в ядре получать от процессов вывод для отправки устройству. Это делается открытием файла устройства для вывода и записью в него — как запись в обычный файл. В примере ниже это реализовано функцией `device_write`.

Но этого не всегда достаточно. Представьте, что к вам подключён модем через последовательный порт (даже внутренний модем с точки зрения CPU реализован как последовательный порт с подключённым модемом, так что не нужно слишком напрягать воображение). Естественным было бы использовать файл устройства для записи данных в модем (либо команд модема, либо данных для отправки по телефонной линии) и чтения данных из модема (либо ответов на команды, либо данных, принятых по телефонной линии). Однако остаётся открытым вопрос: что делать, когда нужно обратиться к самому последовательному порту — например, задать скорость, с которой данные отправляются и принимаются?

Ответ в Unix — использовать специальную функцию `ioctl` (сокращение от Input Output ConTroL). У каждого устройства могут быть собственные команды `ioctl`: читающие `ioctl` (чтобы передать информацию из процесса в ядро), пишущие `ioctl` (чтобы вернуть информацию процессу)[1], обе сразу или ни одной. Функция `ioctl` вызывается с тремя параметрами: файловым дескриптором соответствующего файла устройства, номером ioctl и параметром типа long, чтобы через приведение типа можно было передать что угодно[2].

Номер ioctl кодирует старший номер устройства, тип ioctl, команду и тип параметра. Этот номер обычно создаётся вызовом макроса (`_IO`, `_IOR`, `_IOW` или `_IOWR` — в зависимости от типа) в заголовочном файле. Этот заголовочный файл затем должен подключаться и программами, которые будут использовать `ioctl` (чтобы они могли генерировать корректные `ioctl`), и модулем ядра (чтобы он мог их понимать). В примере ниже заголовочный файл — `chardev.h`, а программа, которая его использует, — `ioctl.c`.

Если вы хотите использовать `ioctl` в собственных модулях ядра, лучше всего получить официальное назначение `ioctl` — тогда если вы случайно получите чьи-то чужие `ioctl` или кто-то получит ваши, вы будете знать, что что-то не так. Подробнее см. `Documentation/ioctl-number.txt` в дереве исходников ядра.

**Пример 7-1. chardev.c**

```c
/*
 *  chardev.c - Create an input/output character device
 *  (Создание символьного устройства ввода-вывода)
 */

#include <linux/kernel.h>	/* Мы работаем с ядром */
#include <linux/module.h>	/* А конкретно - с модулем */
#include <linux/fs.h>
#include <asm/uaccess.h>	/* для get_user и put_user */

#include "chardev.h"
#define SUCCESS 0
#define DEVICE_NAME "char_dev"
#define BUF_LEN 80

/*
 * Устройство открыто прямо сейчас? Используется для предотвращения
 * параллельного доступа к одному устройству
 */
static int Device_Open = 0;

/*
 * Сообщение, которое выдаст устройство по запросу
 */
static char Message[BUF_LEN];

/*
 * До какого места дочитал процесс сообщение?
 * Полезно, если сообщение больше размера буфера,
 * который мы заполняем в device_read.
 */
static char *Message_Ptr;

/*
 * Вызывается всякий раз, когда процесс пытается открыть файл устройства
 */
static int device_open(struct inode *inode, struct file *file)
{
#ifdef DEBUG
	printk(KERN_INFO "device_open(%p)\n", file);
#endif

	/*
	 * Мы не хотим разговаривать с двумя процессами одновременно
	 */
	if (Device_Open)
		return -EBUSY;

	Device_Open++;
	/*
	 * Инициализируем сообщение
	 */
	Message_Ptr = Message;
	try_module_get(THIS_MODULE);
	return SUCCESS;
}

static int device_release(struct inode *inode, struct file *file)
{
#ifdef DEBUG
	printk(KERN_INFO "device_release(%p,%p)\n", inode, file);
#endif

	/*
	 * Теперь мы готовы к следующему вызывающему
	 */
	Device_Open--;

	module_put(THIS_MODULE);
	return SUCCESS;
}

/*
 * Эта функция вызывается всякий раз, когда процесс, уже открывший
 * файл устройства, пытается читать из него.
 */
static ssize_t device_read(struct file *file,	/* см. include/linux/fs.h */
			   char __user * buffer,	/* буфер, который
							 * нужно заполнить данными */
			   size_t length,	/* длина буфера     */
			   loff_t * offset)
{
	/*
	 * Число байтов, фактически записанных в буфер
	 */
	int bytes_read = 0;

#ifdef DEBUG
	printk(KERN_INFO "device_read(%p,%p,%d)\n", file, buffer, length);
#endif

	/*
	 * Если мы в конце сообщения, возвращаем 0
	 * (что означает конец файла)
	 */
	if (*Message_Ptr == 0)
		return 0;

	/*
	 * Собственно помещаем данные в буфер
	 */
	while (length && *Message_Ptr) {

		/*
		 * Поскольку буфер находится в сегменте данных
		 * пользователя, а не ядра, простое присваивание не
		 * сработает. Вместо этого нужно использовать put_user,
		 * который копирует данные из сегмента данных ядра в
		 * сегмент данных пользователя.
		 */
		put_user(*(Message_Ptr++), buffer++);
		length--;
		bytes_read++;
	}

#ifdef DEBUG
	printk(KERN_INFO "Read %d bytes, %d left\n", bytes_read, length);
#endif

	/*
	 * Функции чтения должны возвращать число байтов,
	 * фактически помещённых в буфер
	 */
	return bytes_read;
}

/*
 * Эта функция вызывается, когда кто-то пытается
 * записать в наш файл устройства.
 */
static ssize_t
device_write(struct file *file,
	     const char __user * buffer, size_t length, loff_t * offset)
{
	int i;

#ifdef DEBUG
	printk(KERN_INFO "device_write(%p,%s,%d)", file, buffer, length);
#endif

	for (i = 0; i < length && i < BUF_LEN; i++)
		get_user(Message[i], buffer + i);

	Message_Ptr = Message;

	/*
	 * Снова возвращаем число использованных входных символов
	 */
	return i;
}

/*
 * Эта функция вызывается всякий раз, когда процесс пытается сделать ioctl
 * над нашим файлом устройства. Мы получаем два дополнительных параметра
 * (помимо структур inode и file, которые получают все функции устройств):
 * номер вызванного ioctl и параметр, переданный функции ioctl.
 *
 * Если ioctl - запись или чтение/запись (то есть вывод возвращается
 * вызывающему процессу), вызов ioctl вернёт вывод этой функции.
 */
int device_ioctl(struct inode *inode,	/* см. include/linux/fs.h */
		 struct file *file,	/* то же самое */
		 unsigned int ioctl_num,	/* номер и параметр ioctl */
		 unsigned long ioctl_param)
{
	int i;
	char *temp;
	char ch;

	/*
	 * Переключаемся в соответствии с вызванным ioctl
	 */
	switch (ioctl_num) {
	case IOCTL_SET_MSG:
		/*
		 * Получаем указатель на сообщение (в пользовательском
		 * пространстве) и устанавливаем его как сообщение
		 * устройства. Берём параметр, переданный процессом
		 * в ioctl.
		 */
		temp = (char *)ioctl_param;

		/*
		 * Находим длину сообщения
		 */
		get_user(ch, temp);
		for (i = 0; ch && i < BUF_LEN; i++, temp++)
			get_user(ch, temp);

		device_write(file, (char *)ioctl_param, i, 0);
		break;

	case IOCTL_GET_MSG:
		/*
		 * Отдаём текущее сообщение вызывающему процессу -
		 * полученный параметр - указатель, заполняем его.
		 */
		i = device_read(file, (char *)ioctl_param, 99, 0);

		/*
		 * Помещаем ноль в конец буфера, чтобы строка была
		 * корректно завершена
		 */
		put_user('\0', (char *)ioctl_param + i);
		break;

	case IOCTL_GET_NTH_BYTE:
		/*
		 * Этот ioctl - и вход (ioctl_param), и
		 * вывод (возвращаемое значение этой функции)
		 */
		return Message[ioctl_param];
		break;
	}

	return SUCCESS;
}

/* Объявления модуля */

/*
 * Эта структура содержит функции, которые будут вызываться,
 * когда процесс что-то делает с нашим устройством. Поскольку
 * указатель на эту структуру хранится в таблице устройств,
 * она не может быть локальной для init_module. NULL - для
 * нереализованных функций.
 */
struct file_operations Fops = {
	.read = device_read,
	.write = device_write,
	.ioctl = device_ioctl,
	.open = device_open,
	.release = device_release,	/* то же что close */
};

/*
 * Инициализация модуля - регистрируем символьное устройство
 */
int init_module()
{
	int ret_val;
	/*
	 * Регистрируем символьное устройство (по крайней мере, пытаемся)
	 */
	ret_val = register_chrdev(MAJOR_NUM, DEVICE_NAME, &Fops);

	/*
	 * Отрицательные значения означают ошибку
	 */
	if (ret_val < 0) {
		printk(KERN_ALERT "%s failed with %d\n",
		       "Sorry, registering the character device ", ret_val);
		return ret_val;
	}

	printk(KERN_INFO "%s The major device number is %d.\n",
	       "Registeration is a success", MAJOR_NUM);
	printk(KERN_INFO "If you want to talk to the device driver,\n");
	printk(KERN_INFO "you'll have to create a device file. \n");
	printk(KERN_INFO "We suggest you use:\n");
	printk(KERN_INFO "mknod %s c %d 0\n", DEVICE_FILE_NAME, MAJOR_NUM);
	printk(KERN_INFO "The device file name is important, because\n");
	printk(KERN_INFO "the ioctl program assumes that's the\n");
	printk(KERN_INFO "file you'll use.\n");

	return 0;
}

/*
 * Очистка - снимаем регистрацию соответствующего файла из /proc
 */
void cleanup_module()
{
	int ret;

	/*
	 * Снимаем регистрацию устройства
	 */
	ret = unregister_chrdev(MAJOR_NUM, DEVICE_NAME);

	/*
	 * Если есть ошибка - сообщаем о ней
	 */
	if (ret < 0)
		printk(KERN_ALERT "Error: unregister_chrdev: %d\n", ret);
}
```

**Пример 7-2. chardev.h**

```c
/*
 *  chardev.h - the header file with the ioctl definitions.
 *  (Заголовочный файл с определениями ioctl.)
 *
 *  Объявления должны находиться в заголовочном файле, потому что
 *  они нужны и модулю ядра (в chardev.c), и процессу, вызывающему
 *  ioctl (ioctl.c)
 */

#ifndef CHARDEV_H
#define CHARDEV_H

#include <linux/ioctl.h>

/*
 * Старший номер устройства. Динамическая регистрация больше не
 * подходит, потому что для ioctl он должен быть известен заранее.
 */
#define MAJOR_NUM 100

/*
 * Установить сообщение драйвера устройства
 */
#define IOCTL_SET_MSG _IOR(MAJOR_NUM, 0, char *)
/*
 * _IOR означает, что мы создаём номер команды ioctl
 * для передачи информации из пользовательского процесса
 * в модуль ядра.
 *
 * Первый аргумент, MAJOR_NUM - используемый нами старший
 * номер устройства.
 *
 * Второй аргумент - номер команды (их может быть несколько
 * с разными значениями).
 *
 * Третий аргумент - тип, который мы хотим передать от
 * процесса к ядру.
 */

/*
 * Получить сообщение драйвера устройства
 */
#define IOCTL_GET_MSG _IOR(MAJOR_NUM, 1, char *)
/*
 * Этот IOCTL используется для вывода - получить сообщение
 * драйвера устройства. Однако буфер для размещения сообщения
 * всё же должен быть входным, так как он выделяется процессом.
 */

/*
 * Получить n-й байт сообщения
 */
#define IOCTL_GET_NTH_BYTE _IOWR(MAJOR_NUM, 2, int)
/*
 * Этот IOCTL используется и для ввода, и для вывода. Он
 * получает от пользователя число n и возвращает Message[n].
 */

/*
 * Имя файла устройства
 */
#define DEVICE_FILE_NAME "char_dev"

#endif
```

**Пример 7-3. ioctl.c**

```c
/*
 *  ioctl.c - the process to use ioctl's to control the kernel module
 *  (Процесс, использующий ioctl для управления модулем ядра.)
 *
 *  До сих пор мы могли использовать cat для ввода и вывода.
 *  Но теперь нам нужны ioctl, а для этого нужно написать
 *  собственный процесс.
 */

/*
 * Специфика устройства: номера ioctl и старший номер
 * файла устройства.
 */
#include "chardev.h"

#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>		/* open */
#include <unistd.h>		/* exit */
#include <sys/ioctl.h>		/* ioctl */

/*
 * Функции для вызовов ioctl
 */

ioctl_set_msg(int file_desc, char *message)
{
	int ret_val;

	ret_val = ioctl(file_desc, IOCTL_SET_MSG, message);

	if (ret_val < 0) {
		printf("ioctl_set_msg failed:%d\n", ret_val);
		exit(-1);
	}
}

ioctl_get_msg(int file_desc)
{
	int ret_val;
	char message[100];

	/*
	 * Внимание - это опасно, потому что мы не сообщаем ядру,
	 * докуда ему разрешено писать, и оно может переполнить буфер.
	 * В настоящей боевой программе мы бы использовали два ioctl:
	 * один - сообщить ядру длину буфера, второй - передать сам
	 * буфер для заполнения.
	 */
	ret_val = ioctl(file_desc, IOCTL_GET_MSG, message);

	if (ret_val < 0) {
		printf("ioctl_get_msg failed:%d\n", ret_val);
		exit(-1);
	}

	printf("get_msg message:%s\n", message);
}

ioctl_get_nth_byte(int file_desc)
{
	int i;
	char c;

	printf("get_nth_byte message:");

	i = 0;
	do {
		c = ioctl(file_desc, IOCTL_GET_NTH_BYTE, i++);

		if (c < 0) {
			printf
			    ("ioctl_get_nth_byte failed at the %d'th byte:\n",
			     i);
			exit(-1);
		}

		putchar(c);
	} while (c != 0);
	putchar('\n');
}

/*
 * Main - вызываем функции ioctl
 */
main()
{
	int file_desc, ret_val;
	char *msg = "Message passed by ioctl\n";

	file_desc = open(DEVICE_FILE_NAME, 0);
	if (file_desc < 0) {
		printf("Can't open device file: %s\n", DEVICE_FILE_NAME);
		exit(-1);
	}

	ioctl_get_nth_byte(file_desc);
	ioctl_get_msg(file_desc);
	ioctl_set_msg(file_desc, msg);

	close(file_desc);
}
```

#### Примечания

1. Обратите внимание: здесь роли чтения и записи _снова_ перевёрнуты — в `ioctl` «чтение» — это отправка информации в ядро, а «запись» — получение информации из ядра.
2. Это неточно. Вы не сможете, например, передать структуру через ioctl — но сможете передать указатель на структуру.

## Глава 8. Системные вызовы

### 8.1. Системные вызовы

До сих пор всё, что мы делали, — использовали хорошо определённые механизмы ядра для регистрации файлов `/proc` и обработчиков устройств. Это нормально, если вы хотите сделать то, что программисты ядра предусмотрели заранее, — например, написать драйвер устройства. Но что если вы хотите сделать что-то необычное, как-то изменить поведение системы? Тогда вы по большому счёту предоставлены сами себе.

Именно здесь программирование ядра становится опасным. Пишу пример ниже, я убил системный вызов `open()`. Это значило, что я не мог открыть ни одного файла, не мог запустить ни одной программы и не мог **shutdown** компьютер. Пришлось выдёргивать питание. К счастью, ни один файл не пострадал. Чтобы и вы не потеряли файлы, выполняйте **sync** прямо перед **insmod** и **rmmod**.

Забудьте про файлы `/proc`, забудьте про файлы устройств. Это лишь мелкие детали. _Настоящий_ механизм связи процесса с ядром, который используют все процессы, — системные вызовы. Когда процесс запрашивает у ядра сервис (открытие файла, создание нового процесса, выделение дополнительной памяти), используется именно этот механизм. Если вы хотите изменить поведение ядра интересными способами — это то самое место. Кстати, если хотите посмотреть, какие системные вызовы использует программа, выполните **strace <аргументы>**.

В общем случае процесс не должен иметь доступа к ядру. Он не может обращаться к памяти ядра и не может вызывать функции ядра. Это обеспечивает аппаратура CPU (именно поэтому режим называется «защищённым» / protected mode).

Системные вызовы — исключение из этого общего правила. Процесс заполняет регистры соответствующими значениями и вызывает специальную инструкцию, которая передаёт управление в заранее определённую точку ядра (она, конечно, доступна пользовательским процессам для чтения, но не для записи). На CPU Intel это делается через прерывание 0x80. Аппаратура знает: раз вы перешли в это место — вы больше не работаете в ограниченном пользовательском режиме, а работаете как ядро операционной системы, и поэтому вам разрешено всё.

Точка ядра, в которую может перейти процесс, называется _system_call_. Процедура в этом месте проверяет номер системного вызова, который сообщает ядру, какой сервис запросил процесс. Затем она смотрит в таблицу системных вызовов (`sys_call_table`), чтобы найти адрес функции ядра для вызова. Затем она вызывает эту функцию и после возврата делает несколько системных проверок и возвращает управление процессу (или другому процессу, если время данного процесса истекло). Если хотите прочитать этот код, он находится в исходном файле `arch/$<$architecture$>$/kernel/entry.S` после строки `ENTRY(system_call)`.

Итак, если мы хотим изменить поведение определённого системного вызова, нам нужно написать собственную функцию, реализующую его (обычно добавив немного своего кода и затем вызвав исходную функцию), и изменить указатель в `sys_call_table`, чтобы он указывал на нашу функцию. Поскольку нас позже могут выгрузить и мы не хотим оставить систему в нестабильном состоянии, важно, чтобы `cleanup_module` восстановил таблицу в исходном виде.

Исходный код здесь — пример такого модуля ядра. Мы хотим «шпионить» за определённым пользователем и вызывать `printk()` с сообщением всякий раз, когда этот пользователь открывает файл. Для этого мы заменяем системный вызов открытия файла нашей собственной функцией `our_sys_open`. Эта функция проверяет uid (идентификатор пользователя) текущего процесса и, если он совпадает с uid, за которым мы шпионим, вызывает `printk()`, чтобы вывести имя открываемого файла. Затем, в любом случае, она вызывает исходную функцию `open()` с теми же параметрами, чтобы файл действительно открылся.

Функция `init_module` заменяет соответствующее место в `sys_call_table` и сохраняет исходный указатель в переменной. Функция `cleanup_module` использует эту переменную, чтобы вернуть всё как было. Такой подход опасен из-за возможности того, что два модуля ядра изменят один и тот же системный вызов. Представьте, что у нас есть два модуля ядра, A и B. Системный вызов open у A будет A_open, у B — B_open. Когда A вставляется в ядро, системный вызов заменяется на A_open, которая по завершении вызывает исходный sys_open. Затем B вставляется в ядро и заменяет системный вызов на B_open, которая вызывает то, что _она_ считает исходным системным вызовом — A_open.

Теперь, если B выгружается первым, всё будет хорошо — он просто восстановит системный вызов на A_open, который вызывает исходный. Однако если сначала выгрузить A, а потом B, система рухнет. Выгрузка A восстановит системный вызов в исходный sys_open, выключив B из цепочки. Затем, когда B выгружается, он восстановит системный вызов на то, что _он_ считает исходным — A_open, которого уже нет в памяти. На первый взгляд кажется, что эту проблему можно решить проверкой, равен ли системный вызов нашей функции open, и если да — вообще не менять его (чтобы B не менял системный вызов при выгрузке), но это приведёт к ещё худшей проблеме. При выгрузке A увидит, что системный вызов был изменён на B_open и больше не указывает на A_open, поэтому он не восстановит его на sys_open до того, как сам будет удалён из памяти. К сожалению, B_open всё ещё будет пытаться вызвать A_open, которого там уже нет, так что даже без выгрузки B система рухнет.

Обратите внимание: все связанные с этим проблемы делают перехват системных вызовов непригодным для боевого использования. Чтобы помешать людям делать потенциально опасные вещи, `sys_call_table` больше не экспортируется. Это значит: если вы хотите сделать нечто большее, чем сухую пробу этого примера, вам придётся пропатчить текущее ядро, чтобы `sys_call_table` снова экспортировался. В каталоге с примерами есть README и патч. Как вы понимаете, к таким модификациям не стоит относиться легкомысленно. Не пробуйте это на ценных системах (то есть на системах, которые вам не принадлежат или которые нелегко восстановить). Чтобы получить патч и README, понадобится полный исходный код этого руководства в tarball. В зависимости от версии ядра патч, возможно, придётся применять вручную. Всё ещё здесь? Что ж, эта глава тоже. Если бы Wyle E. Coyote был хакером ядра, это было бы первое, что он бы попробовал. ;)

**Пример 8-1. syscall.c**

```c
/*
 *  syscall.c
 *
 *  System call "stealing" sample.
 *  (Пример «перехвата» системного вызова.)
 */

/*
 * Copyright (C) 2001 by Peter Jay Salzman
 */

/*
 * Необходимые заголовочные файлы
 */

/*
 * Стандартные для модулей ядра
 */
#include <linux/kernel.h>	/* Мы работаем с ядром */
#include <linux/module.h>	/* А конкретно - с модулем, */
#include <linux/moduleparam.h>	/* у которого будут параметры */
#include <linux/unistd.h>	/* Список системных вызовов */

/*
 * Для структуры текущего процесса: она нужна, чтобы знать,
 * кто текущий пользователь.
 */
#include <linux/sched.h>
#include <asm/uaccess.h>

/*
 * Таблица системных вызовов (таблица функций). Мы просто
 * объявляем её внешней, и ядро заполнит её для нас после
 * insmod.
 *
 * sys_call_table больше не экспортируется в ядрах 2.6.x.
 * Если вы действительно хотите попробовать этот ОПАСНЫЙ модуль,
 * вам придётся применить приложенный патч к текущему ядру
 * и пересобрать его.
 */
extern void *sys_call_table[];

/*
 * UID, за которым хотим шпионить - заполнится из командной
 * строки
 */
static int uid;
module_param(uid, int, 0644);

/*
 * Указатель на исходный системный вызов. Мы храним его, а не
 * вызываем исходную функцию (sys_open), потому что кто-то
 * другой мог заменить системный вызов до нас. Заметим: это не
 * даёт 100% безопасности, поскольку если другой модуль заменил
 * sys_open до нас, то после нашей вставки мы будем вызывать
 * функцию из того модуля - а его могут выгрузить раньше нас.
 *
 * Другая причина: мы не можем получить сам sys_open.
 * Это статическая переменная, поэтому она не экспортируется.
 */
asmlinkage int (*original_call) (const char *, int, int);

/*
 * Функция, которой мы заменим sys_open (функцию, вызываемую
 * при системном вызове open). Чтобы найти точный прототип
 * с числом и типами аргументов, сначала найдём исходную
 * функцию (она в fs/open.c).
 *
 * Теоретически это значит, что мы привязаны к текущей версии
 * ядра. На практике системные вызовы почти никогда не меняются
 * (это устроило бы хаос и потребовало бы перекомпиляции программ,
 * поскольку системные вызовы - это интерфейс между ядром
 * и процессами).
 */
asmlinkage int our_sys_open(const char *filename, int flags, int mode)
{
	int i = 0;
	char ch;

	/*
	 * Проверяем, не тот ли это пользователь, за которым мы шпионим
	 */
	if (uid == current->uid) {
		/*
		 * Если актуально - сообщаем о файле
		 */
		printk("Opened file by %d: ", uid);
		do {
			get_user(ch, filename + i);
			i++;
			printk("%c", ch);
		} while (ch != 0);
		printk("\n");
	}

	/*
	 * Вызываем исходный sys_open - иначе мы потеряем
	 * способность открывать файлы
	 */
	return original_call(filename, flags, mode);
}

/*
 * Инициализация модуля - заменяем системный вызов
 */
int init_module()
{
	/*
	 * Предупреждение - уже поздновато, но, может быть,
	 * на следующий раз...
	 */
	printk(KERN_ALERT "I'm dangerous. I hope you did a ");
	printk(KERN_ALERT "sync before you insmod'ed me.\n");
	printk(KERN_ALERT "My counterpart, cleanup_module(), is even");
	printk(KERN_ALERT "more dangerous. If\n");
	printk(KERN_ALERT "you value your file system, it will ");
	printk(KERN_ALERT "be \"sync; rmmod\" \n");
	printk(KERN_ALERT "when you remove this module.\n");

	/*
	 * Сохраняем указатель на исходную функцию в original_call,
	 * а затем заменяем системный вызов в таблице системных
	 * вызовов на our_sys_open
	 */
	original_call = sys_call_table[__NR_open];
	sys_call_table[__NR_open] = our_sys_open;

	/*
	 * Чтобы получить адрес функции системного вызова foo,
	 * обращаемся к sys_call_table[__NR_foo].
	 */

	printk(KERN_INFO "Spying on UID:%d\n", uid);

	return 0;
}

/*
 * Очистка - снимаем регистрацию соответствующего файла из /proc
 */
void cleanup_module()
{
	/*
	 * Возвращаем системный вызов в нормальное состояние
	 */
	if (sys_call_table[__NR_open] != our_sys_open) {
		printk(KERN_ALERT "Somebody else also played with the ");
		printk(KERN_ALERT "open system call\n");
		printk(KERN_ALERT "The system may be left in ");
		printk(KERN_ALERT "an unstable state.\n");
	}

	sys_call_table[__NR_open] = original_call;
}
```

## Глава 9. Блокировка процессов

### 9.1. Блокировка процессов

Что вы делаете, когда кто-то просит вас о том, что вы не можете сделать прямо сейчас? Если вы человек и вас дёргает человек, единственное, что вы можете сказать: «Не сейчас, я занят. _Уйди!_». Но если вы модуль ядра и вас дёргает процесс, есть и другая возможность. Вы можете усыпить процесс, пока не сможете обслужить его. В конце концов, ядро постоянно усыпляет и будит процессы (именно так несколько процессов создают видимость одновременной работы на одном CPU).

Этот модуль ядра — пример такого подхода. Файл (называемый `/proc/sleep`) может быть открыт только одним процессом одновременно. Если файл уже открыт, модуль ядра вызывает `wait_event_interruptible`[1]. Эта функция меняет статус задачи (задача — структура данных ядра, хранящая информацию о процессе и текущем системном вызове, если он есть) на `_TASK_INTERRUPTIBLE_`, что означает: задача не будет выполняться, пока её кто-нибудь не разбудит, и добавляет её в WaitQ — очередь задач, ожидающих доступа к файлу. Затем функция вызывает планировщик, чтобы переключить контекст на другой процесс — тот, которому CPU полезен.

Когда процесс заканчивает работу с файлом, он закрывает его, и вызывается `module_close`. Эта функция будит все процессы в очереди (механизма, чтобы разбудить только один из них, нет). Затем она возвращается, и процесс, который только что закрыл файл, может продолжить работу. Со временем планировщик решает, что этому процессу хватит, и отдаёт CPU другому процессу. В конце концов одному из процессов, стоявших в очереди, планировщик отдаст CPU. Он продолжит выполнение сразу после вызова `module_interruptible_sleep_on`[2]. Затем он может установить глобальную переменную, сообщая остальным процессам, что файл всё ещё открыт, и продолжать жить. Когда остальные процессы получат кусок CPU, они увидят эту глобальную переменную и снова уснут.

Мы будем использовать **tail -f**, чтобы держать файл открытым в фоне, и одновременно пытаться получить к нему доступ другим процессом (тоже в фоне, чтобы не переключаться на другую виртуальную консоль). Как только первый фоновый процесс будет убит командой **kill %1**, второй проснётся, получит доступ к файлу и наконец завершится.

Чтобы жизнь была интереснее, у `module_close` нет монополии на пробуждение процессов, ожидающих доступа к файлу. Сигнал вроде **Ctrl**+**c** (`_SIGINT_`) тоже может разбудить процесс[3]. В этом случае мы хотим немедленно вернуть `_-EINTR_`. Это важно, чтобы пользователи могли, например, убить процесс до того, как он получит файл.

Есть ещё один момент, который нужно помнить. Иногда процессы не хотят спать: они хотят либо получить желаемое немедленно, либо узнать, что это невозможно. Такие процессы используют флаг `_O_NONBLOCK_` при открытии файла. Ядро должно ответить кодом ошибки `_-EAGAIN_` на операции, которые иначе заблокировали бы — например, открытие файла в этом примере. Программа **cat_noblock**, доступная в каталоге исходников этой главы, может открыть файл с `_O_NONBLOCK_`.

```text
hostname:~/lkmpg-examples/09-BlockingProcesses# insmod sleep.ko
hostname:~/lkmpg-examples/09-BlockingProcesses# cat_noblock /proc/sleep
Last input:
hostname:~/lkmpg-examples/09-BlockingProcesses# tail -f /proc/sleep &
Last input:
Last input:
Last input:
Last input:
Last input:
Last input:
Last input:
tail: /proc/sleep: file truncated
[1] 6540
hostname:~/lkmpg-examples/09-BlockingProcesses# cat_noblock /proc/sleep
Open would block
hostname:~/lkmpg-examples/09-BlockingProcesses# kill %1
[1]+  Terminated              tail -f /proc/sleep
hostname:~/lkmpg-examples/09-BlockingProcesses# cat_noblock /proc/sleep
Last input:
hostname:~/lkmpg-examples/09-BlockingProcesses#
```

**Пример 9-1. sleep.c**

```c
/*
 *  sleep.c - create a /proc file, and if several processes try to open it at
 *  the same time, put all but one to sleep
 *  (Создаёт файл /proc, и если несколько процессов пытаются открыть его
 *  одновременно, усыпляет все, кроме одного.)
 */

#include <linux/kernel.h>	/* Мы работаем с ядром */
#include <linux/module.h>	/* А конкретно - с модулем */
#include <linux/proc_fs.h>	/* Нужно, так как мы используем proc fs */
#include <linux/sched.h>	/* Для усыпления процессов и
				   их пробуждения */
#include <asm/uaccess.h>	/* для get_user и put_user */

/*
 * Файловые функции модуля
 */

/*
 * Здесь мы храним последнее полученное сообщение, чтобы доказать,
 * что умеем обрабатывать наш ввод
 */
#define MESSAGE_LENGTH 80
static char Message[MESSAGE_LENGTH];

static struct proc_dir_entry *Our_Proc_File;
#define PROC_ENTRY_FILENAME "sleep"

/*
 * Поскольку мы используем структуру file operations, мы не можем
 * использовать специальные механизмы вывода proc - нужна
 * стандартная функция чтения, вот она
 */
static ssize_t module_output(struct file *file,	/* см. include/linux/fs.h */
			     char *buf,	/* Буфер для данных
					   (в пользовательском сегменте) */
			     size_t len,	/* Длина буфера */
			     loff_t * offset)
{
	static int finished = 0;
	int i;
	char message[MESSAGE_LENGTH + 30];

	/*
	 * Возвращаем 0 как признак конца файла - нам больше
	 * нечего сказать в этот момент.
	 */
	if (finished) {
		finished = 0;
		return 0;
	}

	/*
	 * Если вы не понимаете это к текущему моменту - как
	 * программист ядра вы безнадёжны.
	 */
	sprintf(message, "Last input:%s\n", Message);
	for (i = 0; i < len && message[i]; i++)
		put_user(message[i], buf + i);

	finished = 1;
	return i;		/* Возвращаем число байтов «прочитано» */
}

/*
 * Эта функция получает ввод от пользователя, когда тот пишет
 * в файл /proc.
 */
static ssize_t module_input(struct file *file,	/* Сам файл */
			    const char *buf,	/* Буфер с вводом */
			    size_t length,	/* Длина буфера */
			    loff_t * offset)
{				/* смещение в файле - игнорируем */
	int i;

	/*
	 * Помещаем ввод в Message, откуда module_output позже
	 * сможет его использовать
	 */
	for (i = 0; i < MESSAGE_LENGTH - 1 && i < length; i++)
		get_user(Message[i], buf + i);
	/*
	 * Нам нужна стандартная строка, завершённая нулём
	 */
	Message[i] = '\0';

	/*
	 * Нужно вернуть число использованных символов ввода
	 */
	return i;
}

/*
 * 1, если файл сейчас кем-то открыт
 */
int Already_Open = 0;

/*
 * Очередь процессов, желающих получить наш файл
 */
DECLARE_WAIT_QUEUE_HEAD(WaitQ);
/*
 * Вызывается при открытии файла /proc
 */
static int module_open(struct inode *inode, struct file *file)
{
	/*
	 * Если флаги файла содержат O_NONBLOCK, процесс не хочет
	 * ждать файл. В этом случае, если файл уже открыт, следует
	 * вернуть -EAGAIN в значении «придётся попробовать снова»,
	 * вместо того чтобы блокировать процесс, который предпочёл
	 * бы не спать.
	 */
	if ((file->f_flags & O_NONBLOCK) && Already_Open)
		return -EAGAIN;

	/*
	 * Это правильное место для try_module_get(THIS_MODULE),
	 * потому что если процесс находится в цикле внутри модуля
	 * ядра, модуль ядра не должен удаляться.
	 */
	try_module_get(THIS_MODULE);

	/*
	 * Если файл уже открыт, ждём, пока это не перестанет быть так
	 */

	while (Already_Open) {
		int i, is_sig = 0;

		/*
		 * Эта функция усыпляет текущий процесс, включая любые
		 * системные вызовы - например, нас. Выполнение
		 * возобновится сразу после вызова функции: либо потому
		 * что кто-то вызвал wake_up(&WaitQ) (это делает только
		 * module_close при закрытии файла), либо когда
		 * процессу отправлен сигнал вроде Ctrl-C.
		 */
		wait_event_interruptible(WaitQ, !Already_Open);

		/*
		 * Если мы проснулись из-за неблокируемого сигнала,
		 * возвращаем -EINTR (системный вызов завершается
		 * ошибкой). Это позволяет убивать и останавливать
		 * процессы.
		 */

/*
 * Emmanuel Papirakis:
 *
 * Это небольшое обновление для работы с 2.2.*. Теперь сигналы
 * содержатся в двух словах (64 бита) и хранятся в структуре
 * с массивом из двух unsigned long. В нашем if теперь нужно
 * делать 2 проверки.
 *
 * Ori Pomerantz:
 *
 * Никто не обещал мне, что никогда не будет больше 64 бит или
 * что эта книга не будет использоваться с версией Linux с
 * размером слова 16 бит. Этот код сработает в любом случае.
 */
		for (i = 0; i < _NSIG_WORDS && !is_sig; i++)
			is_sig =
			    current->pending.signal.sig[i] & ~current->
			    blocked.sig[i];

		if (is_sig) {
			/*
			 * Важно поместить module_put(THIS_MODULE) здесь,
			 * потому что для процессов, чей open прерван,
			 * соответствующего close никогда не будет.
			 * Если мы не уменьшим счётчик использования здесь,
			 * мы останемся с положительным счётчиком, который
			 * никак не сможет дойти до нуля, и получим
			 * бессмертный модуль, который можно убить только
			 * перезагрузкой машины.
			 */
			module_put(THIS_MODULE);
			return -EINTR;
		}
	}

	/*
	 * Если мы сюда добрались, Already_Open должно быть нулём
	 */

	/*
	 * Открываем файл
	 */
	Already_Open = 1;
	return 0;		/* Разрешаем доступ */
}

/*
 * Вызывается при закрытии файла /proc
 */
int module_close(struct inode *inode, struct file *file)
{
	/*
	 * Устанавливаем Already_Open в ноль, чтобы один из процессов
	 * в WaitQ смог установить Already_Open обратно в единицу и
	 * открыть файл. Остальные процессы будут вызваны, когда
	 * Already_Open снова станет единицей, и снова уснут.
	 */
	Already_Open = 0;

	/*
	 * Будим все процессы в WaitQ, чтобы ожидающие файл
	 * могли его получить.
	 */
	wake_up(&WaitQ);

	module_put(THIS_MODULE);

	return 0;		/* успех */
}

/*
 * Эта функция решает, разрешить операцию (вернуть ноль) или не
 * разрешить (вернуть ненулевое значение, объясняющее запрет).
 *
 * Операция может быть одним из следующих значений:
 * 0 - Execute (запуск «файла» - в нашем случае бессмысленно)
 * 2 - Write (ввод в модуль ядра)
 * 4 - Read (вывод из модуля ядра)
 *
 * Это настоящая функция проверки прав доступа к файлу. Права
 * из ls -l даны лишь для ориентира и могут быть переопределены здесь.
 */
static int module_permission(struct inode *inode, int op, struct nameidata *nd)
{
	/*
	 * Мы разрешаем всем читать из нашего модуля, но писать
	 * в него может только root (uid 0)
	 */
	if (op == 4 || (op == 2 && current->euid == 0))
		return 0;

	/*
	 * Всё остальное - доступ запрещён
	 */
	return -EACCES;
}

/*
 * Структуры для регистрации в качестве файла /proc,
 * с указателями на все нужные функции.
 */

/*
 * Файловые операции для нашего proc-файла. Здесь мы размещаем
 * указатели на все функции, вызываемые, когда кто-то пытается
 * что-то сделать с нашим файлом. NULL означает, что мы не хотим
 * обрабатывать эту операцию.
 */
static struct file_operations File_Ops_4_Our_Proc_File = {
	.read = module_output,	/* «чтение» из файла */
	.write = module_input,	/* «запись» в файл */
	.open = module_open,	/* вызывается при открытии файла /proc */
	.release = module_close,	/* вызывается при закрытии */
};

/*
 * Операции с inode для нашего proc-файла. Она нужна, чтобы было
 * где указать структуру файловых операций, которую мы хотим
 * использовать, и функцию для проверки прав. Также можно указать
 * функции для всего остального, что можно сделать с inode
 * (хотя мы не заморачиваемся - просто ставим NULL).
 */

static struct inode_operations Inode_Ops_4_Our_Proc_File = {
	.permission = module_permission,	/* проверка прав */
};

/*
 * Инициализация и очистка модуля
 */

/*
 * Инициализация модуля - регистрируем proc-файл
 */

int init_module()
{

	Our_Proc_File = create_proc_entry(PROC_ENTRY_FILENAME, 0644, NULL);

	if (Our_Proc_File == NULL) {
		remove_proc_entry(PROC_ENTRY_FILENAME, &proc_root);
		printk(KERN_ALERT "Error: Could not initialize /proc/test\n");
		return -ENOMEM;
	}

	Our_Proc_File->owner = THIS_MODULE;
	Our_Proc_File->proc_iops = &Inode_Ops_4_Our_Proc_File;
	Our_Proc_File->proc_fops = &File_Ops_4_Our_Proc_File;
	Our_Proc_File->mode = S_IFREG | S_IRUGO | S_IWUSR;
	Our_Proc_File->uid = 0;
	Our_Proc_File->gid = 0;
	Our_Proc_File->size = 80;

	printk(KERN_INFO "/proc/test created\n");

	return 0;
}

/*
 * Очистка - снимаем регистрацию нашего файла из /proc. Это может
 * стать опасным, если в WaitQ всё ещё есть процессы: они находятся
 * внутри нашей функции open, которая будет выгружена. О том, как
 * избежать удаления модуля ядра в таком случае, рассказано
 * в главе 10.
 */
void cleanup_module()
{
	remove_proc_entry(PROC_ENTRY_FILENAME, &proc_root);

	printk(KERN_INFO "/proc/test removed\n");
}
```

**Пример 9-2. cat_noblock.c**

```c
/* cat_noblock.c - open a file and display its contents, but exit rather than
 * wait for input */
/* (Открывает файл и выводит его содержимое, но завершается
 * вместо ожидания ввода.) */


/* Copyright (C) 1998 by Ori Pomerantz */

#include <stdio.h>    /* standard I/O */
#include <fcntl.h>    /* for open */
#include <unistd.h>   /* for read */
#include <stdlib.h>   /* for exit */
#include <errno.h>    /* for errno */

#define MAX_BYTES 1024*4


main(int argc, char *argv[])
{
  int    fd;  /* Файловый дескриптор читаемого файла */
  size_t bytes; /* Число прочитанных байтов */
  char   buffer[MAX_BYTES]; /* Буфер для байтов */


  /* Использование */
  if (argc != 2) {
    printf("Usage: %s <filename>\n", argv[0]);
    puts("Reads the content of a file, but doesn't wait for input");
    exit(-1);
  }

  /* Открываем файл для чтения в неблокирующемся режиме */
  fd = open(argv[1], O_RDONLY | O_NONBLOCK);

  /* Если open не удался */
  if (fd == -1) {
    if (errno = EAGAIN)
      puts("Open would block");
    else
      puts("Open failed");
    exit(-1);
  }

  /* Читаем файл и выводим содержимое */
  do {
    int i;

    /* Читаем символы из файла */
    bytes = read(fd, buffer, MAX_BYTES);

    /* Если ошибка - сообщаем и умираем */
    if (bytes == -1) {
      if (errno = EAGAIN)
	puts("Normally I'd block, but you told me not to");
      else
	puts("Another read error");
      exit(-1);
    }

    /* Печатаем символы */
    if (bytes > 0) {
      for(i=0; i<bytes; i++)
	putchar(buffer[i]);
    }

    /* Пока нет ошибок и файл не кончился */
  } while (bytes > 0);
}
```

#### Примечания

1. Проще всего держать файл открытым с помощью **tail -f**.
2. Это значит, что процесс всё ещё находится в режиме ядра — с точки зрения процесса, он выполнил системный вызов `open`, и вызов ещё не вернулся. Процесс не знает, что кто-то другой использовал CPU большую часть времени между моментом вызова и моментом возврата.
3. Это потому, что мы использовали `module_interruptible_sleep_on`. Мы могли бы использовать `module_sleep_on`, но это привело бы к крайне злым пользователям, чьи **Ctrl**+**c** игнорируются.

---

## Глава 10. Замена printk (Replacing Printks)

## 10.1. Замена `printk`

В [разделе 1.2.1.2](x44.html#USINGX) я говорил, что X и программирование модулей ядра несовместимы. Это верно для разработки модулей ядра, но на практике вам захочется иметь возможность отправлять сообщения на тот tty[1], с которого пришла команда загрузки модуля.

Делается это с помощью `current` — указателя на текущую выполняющуюся задачу, — позволяющего получить структуру tty текущей задачи. Затем мы заглядываем внутрь этой структуры tty, чтобы найти указатель на функцию записи строки, и используем её, чтобы записать строку в tty.

**Пример 10-1. print_string.c**

```c
/* 
 *  print_string.c - Отправляет вывод на tty, на котором мы работаем, независимо от того,
 *  идёт ли это через X11, telnet и т.д. Мы делаем это, печатая строку на tty,
 *  связанном с текущей задачей.
 */
#include <linux/kernel.h>
#include <linux/module.h>
#include <linux/init.h>
#include <linux/sched.h>	/* Для current */
#include <linux/tty.h>		/* Для объявлений tty */
#include <linux/version.h>	/* Для LINUX_VERSION_CODE */

MODULE_LICENSE("GPL");
MODULE_AUTHOR("Peter Jay Salzman");

static void print_string(char *str)
{
	struct tty_struct *my_tty;

	/* 
	 * В 2.6.6 структура tty переехала в signal struct 
	 */
#if ( LINUX_VERSION_CODE <= KERNEL_VERSION(2,6,5) )
	/* 
	 * tty текущей задачи 
	 */
	my_tty = current->tty;
#else
	/* 
	 * tty текущей задачи для ядер 2.6.6+ 
	 */
	my_tty = current->signal->tty;
#endif

	/* 
	 * Если my_tty равен NULL, у текущей задачи нет tty, в который можно
	 * печатать (например, если это демон). В таком случае мы ничего
	 * не можем сделать.
	 */
	if (my_tty != NULL) {

		/* 
		 * my_tty->driver — это структура, содержащая функции tty,
		 * одна из которых (write) используется для записи строк в tty.
		 * Её можно использовать, чтобы взять строку как из сегмента
		 * памяти пользователя, так и из сегмента памяти ядра.
		 *
		 * Первый параметр функции — это tty, в который производится
		 * запись, потому что обычно одна и та же функция используется
		 * для всех tty определённого типа. Второй параметр управляет тем,
		 * получает ли функция строку из памяти ядра (false, 0) или из
		 * памяти пользователя (true, не ноль).
		 * Кстати: в ядрах > 2.6.9 этот параметр был удалён.
		 * (2-й) 3-й параметр — это указатель на строку.
		 * (3-й) 4-й параметр — это длина строки.
		 *
		 * Как вы увидите ниже, иногда необходимо использовать
		 * возможности препроцессора, чтобы создать код, работающий
		 * с разными версиями ядра. (Наивный) подход, применённый здесь,
		 * плохо масштабируется. Правильный способ решения этой
		 * задачи описан в разделе 2 документа
		 * linux/Documentation/SubmittingPatches
		 */
		((my_tty->driver)->write) (my_tty,	/* Сам tty */
#if ( LINUX_VERSION_CODE <= KERNEL_VERSION(2,6,9) )		
					   0,	/* Не брать строку 
						   из пространства пользователя */
#endif
					   str,	/* Строка                 */
					   strlen(str));	/* Длина */

		/* 
		 * Изначально tty были аппаратными устройствами, которые
		 * (обычно) строго следовали стандарту ASCII. В ASCII, чтобы
		 * перейти на новую строку, нужны два символа: возврат каретки
		 * и перевод строки. В Unix ASCII-перевод строки используется
		 * для обеих целей — поэтому мы не можем просто использовать
		 * \n, потому что он не содержит возврата каретки, и следующая
		 * строка начнётся в колонке сразу после перевода строки.
		 *
		 * Именно поэтому текстовые файлы различаются между Unix и
		 * MS Windows. В CP/M и её производных, таких как MS-DOS и
		 * MS Windows, стандарт ASCII соблюдался строго, и поэтому
		 * для перевода строки требуются и LF, и CR.
		 */

#if ( LINUX_VERSION_CODE <= KERNEL_VERSION(2,6,9) )		
		((my_tty->driver)->write) (my_tty, 0, "\015\012", 2);
#else
		((my_tty->driver)->write) (my_tty, "\015\012", 2);
#endif
	}
}

static int __init print_string_init(void)
{
	print_string("The module has been inserted.  Hello world!");
	return 0;
}

static void __exit print_string_exit(void)
{
	print_string("The module has been removed.  Farewell world!");
}

module_init(print_string_init);
module_exit(print_string_exit);
```

#### Примечания

[1] **tty** — от «**T**ele**ty**pe»: изначально комбинированное устройство «клавиатура-принтер», используемое для связи с системой Unix, а сегодня — абстракция текстового потока, используемого программой Unix, будь то физический терминал, xterm на X-дисплее, сетевое соединение, используемое с telnet, и т.д.

---

## 10.2. Мигание светодиодов клавиатуры (Flashing keyboard LEDs)

В некоторых ситуациях вам может понадобиться более простой и прямой способ связи с внешним миром. Мигание светодиодов (LED) клавиатуры может стать таким решением: это немедленный способ привлечь внимание или отобразить состояние. Светодиоды клавиатуры присутствуют на любом оборудовании, они всегда на виду, не требуют никакой настройки, а их использование довольно просто и ненавязчиво по сравнению с записью в tty или в файл.

Следующий исходный код демонстрирует минимальный модуль ядра, который после загрузки начинает мигать светодиодами клавиатуры до момента своей выгрузки.

**Пример 10-2. kbleds.c**

```c
/* 
 *  kbleds.c - Мигает светодиодами клавиатуры, пока модуль не выгружен.
 */

#include <linux/module.h>
#include <linux/config.h>
#include <linux/init.h>
#include <linux/tty.h>		/* Для fg_console, MAX_NR_CONSOLES */
#include <linux/kd.h>		/* Для KDSETLED */
#include <linux/vt.h>
#include <linux/console_struct.h>	/* Для vc_cons */

MODULE_DESCRIPTION("Example module illustrating the use of Keyboard LEDs.");
MODULE_AUTHOR("Daniele Paolo Scarpazza");
MODULE_LICENSE("GPL");

struct timer_list my_timer;
struct tty_driver *my_driver;
char kbledstatus = 0;

#define BLINK_DELAY   HZ/5
#define ALL_LEDS_ON   0x07
#define RESTORE_LEDS  0xFF

/*
 * Функция my_timer_func периодически мигает светодиодами клавиатуры, вызывая
 * команду KDSETLED ioctl() на драйвере клавиатуры. Чтобы узнать больше об
 * операциях ioctl виртуального терминала, смотрите файл:
 *     /usr/src/linux/drivers/char/vt_ioctl.c, функция vt_ioctl().
 *
 * Аргумент KDSETLED попеременно устанавливается в 7 (что переводит режим
 * светодиодов в LED_SHOW_IOCTL, и все светодиоды загораются) и в 0xFF
 * (любое значение больше 7 возвращает режим светодиодов в LED_SHOW_FLAGS,
 * и тогда светодиоды отражают реальное состояние клавиатуры). Чтобы узнать
 * больше об этом, смотрите файл:
 *     /usr/src/linux/drivers/char/keyboard.c, функция setledstate().
 * 
 */

static void my_timer_func(unsigned long ptr)
{
	int *pstatus = (int *)ptr;

	if (*pstatus == ALL_LEDS_ON)
		*pstatus = RESTORE_LEDS;
	else
		*pstatus = ALL_LEDS_ON;

	(my_driver->ioctl) (vc_cons[fg_console].d->vc_tty, NULL, KDSETLED,
			    *pstatus);

	my_timer.expires = jiffies + BLINK_DELAY;
	add_timer(&my_timer);
}

static int __init kbleds_init(void)
{
	int i;

	printk(KERN_INFO "kbleds: loading\n");
	printk(KERN_INFO "kbleds: fgconsole is %x\n", fg_console);
	for (i = 0; i < MAX_NR_CONSOLES; i++) {
		if (!vc_cons[i].d)
			break;
		printk(KERN_INFO "poet_atkm: console[%i/%i] #%i, tty %lx\n", i,
		       MAX_NR_CONSOLES, vc_cons[i].d->vc_num,
		       (unsigned long)vc_cons[i].d->vc_tty);
	}
	printk(KERN_INFO "kbleds: finished scanning consoles\n");

	my_driver = vc_cons[fg_console].d->vc_tty->driver;
	printk(KERN_INFO "kbleds: tty driver magic %x\n", my_driver->magic);

	/*
	 * Первая настройка таймера мигания светодиодов
	 */
	init_timer(&my_timer);
	my_timer.function = my_timer_func;
	my_timer.data = (unsigned long)&kbledstatus;
	my_timer.expires = jiffies + BLINK_DELAY;
	add_timer(&my_timer);

	return 0;
}

static void __exit kbleds_cleanup(void)
{
	printk(KERN_INFO "kbleds: unloading...\n");
	del_timer(&my_timer);
	(my_driver->ioctl) (vc_cons[fg_console].d->vc_tty, NULL, KDSETLED,
			    RESTORE_LEDS);
}

module_init(kbleds_init);
module_exit(kbleds_cleanup);
```

Если ни один из примеров этой главы не подошёл для ваших отладочных нужд, есть ещё несколько трюков, которые можно попробовать. Когда-нибудь задумывались, для чего нужен CONFIG_LL_DEBUG в **make menuconfig**? Если вы его активируете, вы получите низкоуровневый доступ к последовательному порту. Само по себе это может не показаться чем-то очень мощным, однако вы можете пропатчить `kernel/printk.c` или любой другой важный системный вызов, чтобы использовать printascii, что даст возможность трассировать практически всё, что делает ваш код, через последовательную линию. Если вы окажетесь в ситуации портирования ядра на новую и ранее не поддерживавшуюся архитектуру, это обычно входит в число первых вещей, которые следует реализовать. Также стоит попробовать ведение журнала через netconsole.

Хотя здесь вы увидели множество средств, способных помочь в отладке, о некоторых вещах следует помнить. Отладка почти всегда является вмешательством. Добавление отладочного кода может изменить ситуацию настолько, что ошибка будет казаться исчезнувшей. Поэтому старайтесь сводить отладочный код к минимуму и следите, чтобы он не попадал в рабочий (production) код.

---
## Глава 11. Планирование задач (Scheduling Tasks)

---

## 11.1. Планирование задач

Очень часто у нас есть «хозяйственные» задачи, которые должны выполняться в определённое время или время от времени. Если задача должна выполняться процессом, мы помещаем её в файл `crontab`. Если же задача должна выполняться модулем ядра, у нас есть две возможности. Первая — поместить в файл `crontab` процесс, который при необходимости будет «будить» модуль системным вызовом, например открытием файла. Однако это чудовищно неэффективно — мы запускаем новый процесс из `crontab`, читаем новый исполняемый файл в память, и всё это лишь для того, чтобы разбудить модуль ядра, который и так находится в памяти.

Вместо этого мы можем создать функцию, которая будет вызываться при каждом прерывании таймера. Делается это так: мы создаём задачу, хранимую в структуре workqueue_struct, которая будет содержать указатель на функцию. Затем мы используем `queue_delayed_work`, чтобы поместить эту задачу в список задач с именем my_workqueue — список задач, которые будут выполнены при следующем прерывании таймера. Поскольку мы хотим, чтобы функция продолжала выполняться, нам нужно помещать её обратно в my_workqueue при каждом её вызове, чтобы она сработала при следующем прерывании таймера.

Здесь нужно помнить ещё об одном моменте. Когда модуль удаляется командой **rmmod**, сначала проверяется его счётчик ссылок. Если он равен нулю, вызывается `module_cleanup`. Затем модуль удаляется из памяти вместе со всеми его функциями. Всё должно быть корректно остановлено, иначе случатся плохие вещи. Смотрите код ниже, чтобы узнать, как это можно сделать безопасным способом.

**Пример 11-1. sched.c**

```c
/*
 *  sched.c - планирует вызов функции при каждом прерывании таймера.
 *
 *  Copyright (C) 2001 by Peter Jay Salzman
 */

/* 
 * Необходимые заголовочные файлы 
 */

/* 
 * Стандартные для модулей ядра 
 */
#include <linux/kernel.h>	/* Мы работаем над ядром */
#include <linux/module.h>	/* В частности, над модулем */
#include <linux/proc_fs.h>	/* Необходимо, так как мы используем proc fs */
#include <linux/workqueue.h>	/* Здесь мы планируем задачи */
#include <linux/sched.h>	/* Нам нужно усыпить себя 
				   и позже разбудить */
#include <linux/init.h>		/* Для __init и __exit */
#include <linux/interrupt.h>	/* Для irqreturn_t */

struct proc_dir_entry *Our_Proc_File;
#define PROC_ENTRY_FILENAME "sched"
#define MY_WORK_QUEUE_NAME "WQsched.c"

/* 
 * Сколько раз прерывание таймера вызывалось на данный момент 
 */
static int TimerIntrpt = 0;

static void intrpt_routine(void *);

static int die = 0;		/* установите в 1 для завершения работы */

/* 
 * Структура рабочей очереди для этой задачи, из workqueue.h 
 */
static struct workqueue_struct *my_workqueue;

static struct work_struct Task;
static DECLARE_WORK(Task, intrpt_routine, NULL);

/* 
 * Эта функция будет вызываться при каждом прерывании таймера. Обратите
 * внимание на указатель void* — функции задач могут использоваться
 * более чем для одной цели, каждый раз получая разные параметры.
 */
static void intrpt_routine(void *irrelevant)
{
	/* 
	 * Увеличиваем счётчик 
	 */
	TimerIntrpt++;

	/* 
	 * Если очистка хочет, чтобы мы завершились 
	 */
	if (die == 0)
		queue_delayed_work(my_workqueue, &Task, 100);
}

/* 
 * Помещаем данные в файл proc fs. 
 */
ssize_t
procfile_read(char *buffer,
	      char **buffer_location,
	      off_t offset, int buffer_length, int *eof, void *data)
{
	int len;		/* Количество реально использованных байтов */

	/* 
	 * Буфер статический, чтобы он оставался в памяти 
	 * и после выхода из этой функции 
	 */
	static char my_buffer[80];

	/* 
	 * Мы отдаём всю информацию за один раз, поэтому если кто-либо
	 * спросит, есть ли у нас ещё информация, ответ всегда должен
	 * быть «нет».
	 */
	if (offset > 0)
		return 0;

	/* 
	 * Заполняем буфер и получаем его длину 
	 */
	len = sprintf(my_buffer, "Timer called %d times so far\n", TimerIntrpt);

	/* 
	 * Сообщаем вызвавшей нас функции, где находится буфер 
	 */
	*buffer_location = my_buffer;

	/* 
	 * Возвращаем длину 
	 */
	return len;
}

/* 
 * Инициализация модуля - регистрируем proc-файл 
 */
int __init init_module()
{
	/*
	 * Создаём наш файл /proc
	 */
	Our_Proc_File = create_proc_entry(PROC_ENTRY_FILENAME, 0644, NULL);
	
	if (Our_Proc_File == NULL) {
		remove_proc_entry(PROC_ENTRY_FILENAME, &proc_root);
		printk(KERN_ALERT "Error: Could not initialize /proc/%s\n",
		       PROC_ENTRY_FILENAME);
		return -ENOMEM;
	}

	Our_Proc_File->read_proc = procfile_read;
	Our_Proc_File->owner = THIS_MODULE;
	Our_Proc_File->mode = S_IFREG | S_IRUGO;
	Our_Proc_File->uid = 0;
	Our_Proc_File->gid = 0;
	Our_Proc_File->size = 80;

	/* 
	 * Помещаем задачу в рабочую очередь task work_timer, чтобы она была
	 * выполнена при следующем прерывании таймера
	 */
	my_workqueue = create_workqueue(MY_WORK_QUEUE_NAME);
	queue_delayed_work(my_workqueue, &Task, 100);
	
	
	printk(KERN_INFO "/proc/%s created\n", PROC_ENTRY_FILENAME);
	
	return 0;
}

/* 
 * Очистка 
 */
void __exit cleanup_module()
{
	/* 
	 * Отменяем регистрацию нашего файла /proc 
	 */
	remove_proc_entry(PROC_ENTRY_FILENAME, &proc_root);
	printk(KERN_INFO "/proc/%s removed\n", PROC_ENTRY_FILENAME);

	die = 1;		/* не даём intrp_routine ставить себя в очередь */
	cancel_delayed_work(&Task);	/* никаких «новых» */
	flush_workqueue(my_workqueue);	/* ждём завершения всех «старых» */
	destroy_workqueue(my_workqueue);

	/* 
	 * Спим, пока intrpt_routine не будет вызвана в последний раз. Это
	 * необходимо, потому что иначе мы освободим память, в которой
	 * находятся intrpt_routine и Task, в то время как work_timer всё
	 * ещё ссылается на них. Обратите внимание, что здесь мы не
	 * позволяем сигналам прерывать нас.
	 *
	 * Поскольку WaitQ теперь не NULL, это автоматически сообщает
	 * процедуре прерывания, что пришло время завершиться.
	 */

}

/* 
 * некоторые функции, связанные с work_queue,
 * доступны только модулям с лицензией GPL 
 */
MODULE_LICENSE("GPL");
```

---

## Глава 12. Обработчики прерываний (Interrupt Handlers)

---

## 12.1. Обработчики прерываний

### 12.1.1. Обработчики прерываний

За исключением последней главы, всё, что мы делали в ядре до сих пор, было ответом на запрос процесса — через работу со специальным файлом, отправку `ioctl()` или выполнение системного вызова. Но работа ядра заключается не только в ответах на запросы процессов. Другая задача, не менее важная, — общение с оборудованием, подключённым к машине.

Между CPU и остальным оборудованием компьютера существуют два типа взаимодействия. Первый — когда CPU отдаёт команды оборудованию; второй — когда оборудованию нужно что-то сообщить CPU. Второй тип, называемый прерываниями (interrupts), реализовать гораздо сложнее, поскольку с ним приходится разбираться тогда, когда удобно оборудованию, а не CPU. Аппаратные устройства обычно имеют очень небольшой объём RAM, и если вы не прочитаете их информацию, когда она доступна, она будет потеряна.

Под Linux аппаратные прерывания называются IRQ (_I_ nterrupt _R_ e _q_ uests — запросы прерываний)[1]. Существует два типа IRQ: короткие и длинные. Короткое IRQ — это то, которое, как ожидается, займёт _очень_ короткий промежуток времени, в течение которого остальная часть машины будет заблокирована и другие прерывания обслуживаться не будут. Длинное IRQ — это то, которое может занять больше времени, и в течение него могут возникать другие прерывания (но не прерывания от того же устройства). Если есть хоть какая-то возможность, лучше объявлять обработчик прерывания длинным.

Когда CPU получает прерывание, он прекращает то, что делает (если только он не обрабатывает более важное прерывание — в этом случае он займётся данным прерыванием только после завершения более важного), сохраняет определённые параметры в стеке и вызывает обработчик прерывания. Это означает, что в самом обработчике прерывания определённые вещи не разрешены, так как система находится в неизвестном состоянии. Решение этой проблемы состоит в том, чтобы обработчик прерывания сделал то, что нужно сделать немедленно — обычно что-то прочитал из оборудования или что-то отправил в оборудование, — а затем запланировал обработку новой информации на более позднее время (это называется «нижней половиной», bottom half) и вернул управление. Ядро тогда гарантированно вызовет нижнюю половину как можно скорее — и когда это произойдёт, будет разрешено всё, что разрешено в модулях ядра.

Реализуется это вызовом `request_irq()`, чтобы ваш обработчик прерывания вызывался при получении соответствующего IRQ.[2] Эта функция принимает номер IRQ, имя функции, флаги, имя для `/proc/interrupts` и параметр для передачи обработчику прерывания. Обычно доступно определённое количество IRQ. Сколько именно — зависит от оборудования. Флаги могут включать `_SA_SHIRQ_`, чтобы показать, что вы готовы использовать IRQ совместно с другими обработчиками прерываний (обычно потому, что несколько аппаратных устройств сидят на одном IRQ), и `_SA_INTERRUPT_`, чтобы показать, что это быстрое прерывание. Эта функция завершится успешно, только если на этом IRQ ещё нет обработчика или если оба согласны на совместное использование.

Затем из обработчика прерывания мы связываемся с оборудованием и используем `queue_work()`/`mark_bh(BH_IMMEDIATE)`, чтобы запланировать нижнюю половину.

### 12.1.2. Клавиатуры на архитектуре Intel

Оставшаяся часть этой главы полностью специфична для Intel. Если вы работаете не на платформе Intel, это не будет работать. Даже не пытайтесь компилировать этот код.

У меня была проблема с написанием примера кода для этой главы. С одной стороны, чтобы пример был полезным, он должен работать на компьютере каждого и давать осмысленные результаты. С другой стороны, ядро уже содержит драйверы устройств для всех распространённых устройств, и эти драйверы не будут сосуществовать с тем, что я собираюсь написать. Найденное мной решение — написать обработчик для прерывания клавиатуры, предварительно отключив обычный обработчик прерывания клавиатуры. Поскольку тот определён как статический символ в файлах исходного кода ядра (конкретно, `drivers/char/keyboard.c`), восстановить его невозможно. Перед `**insmod**` этого кода выполните на другом терминале `**sleep 120; reboot**`, если вам дорога ваша файловая система.

Этот код привязывает себя к IRQ 1 — это IRQ клавиатуры под архитектурой Intel. Затем, когда он получает прерывание клавиатуры, он читает статус клавиатуры (в этом и состоит цель `**inb(0x64)**`) и скан-код — значение, возвращаемое клавиатурой. Затем, как только ядро сочтёт это возможным, запускается `got_char`, который получает код использованной клавиши (первые семь бит скан-кода) и информацию о том, была ли она нажата (если 8-й бит равен нулю) или отпущена (если он равен единице).

**Пример 12-1. intrpt.c**

```c
/*
 *  intrpt.c - Обработчик прерывания.
 *
 *  Copyright (C) 2001 by Peter Jay Salzman
 */

/* 
 * Необходимые заголовочные файлы 
 */

/* 
 * Стандартные для модулей ядра 
 */
#include <linux/kernel.h>	/* Мы работаем над ядром */
#include <linux/module.h>	/* В частности, над модулем */
#include <linux/sched.h>
#include <linux/workqueue.h>
#include <linux/interrupt.h>	/* Нам нужно прерывание */
#include <asm/io.h>

#define MY_WORK_QUEUE_NAME "WQsched.c"

static struct workqueue_struct *my_workqueue;

/* 
 * Эта функция будет вызвана ядром, как только станет безопасно
 * делать всё, что обычно разрешено модулям ядра.
 */
static void got_char(void *scancode)
{
	printk(KERN_INFO "Scan Code %x %s.\n",
	       (int)*((char *)scancode) & 0x7F,
	       *((char *)scancode) & 0x80 ? "Released" : "Pressed");
}

/* 
 * Эта функция обслуживает прерывания клавиатуры. Она читает относящуюся
 * к делу информацию из клавиатуры, а затем помещает не критичную
 * ко времени часть в рабочую очередь. Она будет выполнена, когда ядро
 * сочтёт это безопасным.
 */
irqreturn_t irq_handler(int irq, void *dev_id, struct pt_regs *regs)
{
	/* 
	 * Эти переменные статические, потому что они должны быть
	 * доступны (через указатели) процедуре нижней половины.
	 */
	static int initialised = 0;
	static unsigned char scancode;
	static struct work_struct task;
	unsigned char status;

	/* 
	 * Читаем статус клавиатуры
	 */
	status = inb(0x64);
	scancode = inb(0x60);

	if (initialised == 0) {
		INIT_WORK(&task, got_char, &scancode);
		initialised = 1;
	} else {
		PREPARE_WORK(&task, got_char, &scancode);
	}

	queue_work(my_workqueue, &task);

	return IRQ_HANDLED;
}

/* 
 * Инициализация модуля - регистрируем обработчик IRQ 
 */
int init_module()
{
	my_workqueue = create_workqueue(MY_WORK_QUEUE_NAME);

	/* 
	 * Поскольку обработчик клавиатуры не будет сосуществовать
	 * с другим обработчиком, таким как мы, мы должны отключить его
	 * (освободить его IRQ), прежде чем делать что-либо. Поскольку
	 * мы не знаем, где он находится, нет способа восстановить его
	 * позже — так что по завершении компьютер придётся
	 * перезагрузить.
	 */
	free_irq(1, NULL);

	/* 
	 * Запрашиваем IRQ 1, IRQ клавиатуры, чтобы он шёл в наш
	 * irq_handler. SA_SHIRQ означает, что мы не против наличия
	 * других обработчиков на этом IRQ. SA_INTERRUPT можно
	 * использовать, чтобы сделать обработчик быстрым прерыванием.
	 */
	return request_irq(1,	/* Номер IRQ клавиатуры на ПК */
			   irq_handler,	/* наш обработчик */
			   SA_SHIRQ, "test_keyboard_irq_handler",
			   (void *)(irq_handler));
}

/* 
 * Очистка 
 */
void cleanup_module()
{
	/* 
	 * Это здесь только для полноты. Совершенно не важно, поскольку
	 * у нас нет способа восстановить нормальное прерывание
	 * клавиатуры, так что компьютер совершенно бесполезен и его
	 * придётся перезагрузить.
	 */
	free_irq(1, NULL);
}

/* 
 * некоторые функции, связанные с work_queue, доступны только
 * модулям с лицензией GPL
 */
MODULE_LICENSE("GPL");
```

#### Примечания

[1] Это стандартная номенклатура для архитектуры Intel, на которой зародился Linux.

[2] На практике обработка IRQ может быть несколько сложнее. Оборудование часто спроектировано так, что два контроллера прерываний объединены в цепочку, и все IRQ от контроллера прерываний B каскадируются на определённый IRQ контроллера прерываний A. Конечно, это требует, чтобы ядро потом выясняло, каким именно было прерывание, и это добавляет накладные расходы. Другие архитектуры предлагают специальные прерывания с очень низкими накладными расходами, так называемые «быстрые IRQ», или FIQ. Чтобы воспользоваться ими, обработчики нужно писать на ассемблере, поэтому они не очень хорошо вписываются в ядро. Их можно заставить работать подобно остальным, но после этой процедуры они уже не быстрее, чем «обычные» IRQ. Ядра с включённой поддержкой SMP, работающие на системах с более чем одним процессором, должны решить ещё целый ворох проблем. Недостаточно знать, что произошло определённое прерывание, важно также, для какого CPU (или CPU) оно было. Тем, кто всё ещё интересуется деталями, возможно, стоит прямо сейчас выполнить поиск в интернете по слову «APIC» ;)

---

## Глава 13. Симметричная мультипроцессорная обработка (Symmetric Multi Processing)

---

## 13.1. Симметричная мультипроцессорная обработка

Один из простейших и дешёвейших способов повысить производительность оборудования — разместить на плате более одного CPU. Это можно сделать либо заставив разные CPU брать на себя разные задачи (асимметричная мультипроцессорная обработка), либо заставив их всех работать параллельно, выполняя одну и ту же работу (симметричная мультипроцессорная обработка, она же SMP). Эффективная асимметричная мультипроцессорная обработка требует специальных знаний о задачах, которые должен выполнять компьютер, а такими знаниями универсальная операционная система вроде Linux не располагает. Симметричная же мультипроцессорная обработка относительно проста в реализации.

Под «относительно простой» я имею в виду именно это: я не говорю, что она _действительно_ проста. В среде симметричной мультипроцессорной обработки CPU используют общую память, и в результате код, выполняющийся на одном CPU, может затронуть память, используемую другим. Вы больше не можете быть уверены, что переменная, которой вы присвоили определённое значение в предыдущей строке, всё ещё имеет это значение — другой CPU мог «поиграть» с ней, пока вы не смотрели. Очевидно, что программировать так невозможно.

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

В версии 2.0.x это не является проблемой, потому что всё ядро находится в одной большой спин-блокировке (spinlock). Это значит, что если один CPU находится в ядре, а другой CPU хочет войти, например из-за системного вызова, ему придётся подождать, пока первый CPU не закончит. Это делает Linux безопасным для SMP[2], но неэффективным.

В версии 2.2.x несколько CPU могут находиться в ядре одновременно. Об этом авторам модулей нужно помнить.

#### Примечания

[1] Исключение — многопоточные процессы, которые могут выполняться сразу на нескольких CPU.

[2] То есть его безопасно использовать с SMP.

---

## Глава 14. Типичные ошибки (Common Pitfalls)

---

## 14.1. Типичные ошибки

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

### Использование стандартных библиотек

Этого делать нельзя. В модуле ядра вы можете использовать только функции ядра — те функции, которые видны в `/proc/kallsyms`.

### Запрет прерываний

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

### Сунуть голову в пасть крупному хищнику

Наверное, об этом предупреждать не нужно, но я всё же предупрежу — на всякий случай.

---

## Приложение A. Изменения: с 2.0 до 2.2 (Changes: 2.0 To 2.2)

---

## A.1. Изменения между 2.4 и 2.6

### A.1.1. Изменения между 2.4 и 2.6

Я не знаю всё ядро достаточно хорошо, чтобы задокументировать все изменения. Некоторые подсказки по портированию можно найти, сравнив эту версию LKMPG с её вариантом для ядра 2.4. Помимо этого, всем, кому нужно портировать драйверы с ядер 2.4 на 2.6, возможно, стоит посетить [http://lwn.net/Articles/driver-porting/](http://lwn.net/Articles/driver-porting/). Если вы всё ещё не можете найти пример, который точно соответствует вашим нуждам, найдите драйвер, похожий на ваш и присутствующий в обеих версиях ядра. Инструменты сравнения файлов вроде **xxdiff** или **meld** могут тогда очень помочь. Также проверьте, не охвачен ли ваш драйвер документацией в `linux/Documentation/`. Прежде чем начинать портирование и в случае, если вы застрянете, хорошая идея — найти подходящий список рассылки и попросить там людей подсказать направление.

---

## Приложение B. Что дальше (Where To Go From Here)

---

## B.1. Что дальше?

Я мог бы легко втиснуть в эту книгу ещё несколько глав. Я мог бы добавить главу о создании новых файловых систем или о добавлении новых сетевых протоколов (как будто в этом есть потребность — вам пришлось бы копать под землю, чтобы найти сетевой протокол, не поддерживаемый Linux). Я мог бы добавить объяснения механизмов ядра, которых мы не коснулись, таких как начальная загрузка (bootstrapping) или интерфейс диска.

Однако я решил этого не делать. Моей целью при написании этой книги было дать посвящение в тайны программирования модулей ядра и обучить общеупотребительным приёмам для этой цели. Тем, кто всерьёз интересуется программированием ядра, я рекомендую [список ресурсов по ядру](http://jungla.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html) Хуана-Мариано де Гойенече (Juan-Mariano de Goyeneche). Кроме того, как сказал Линус, лучший способ изучить ядро — читать исходный код самому.

Если вам интересны дополнительные примеры коротких модулей ядра, я рекомендую журнал Phrack. Даже если вы не интересуетесь безопасностью (а как программист вы должны бы), модули ядра там — хорошие примеры того, что можно делать внутри ядра, и они достаточно коротки, чтобы их понимание не требовало слишком больших усилий.

Надеюсь, я помог вам в вашем стремлении стать лучшим программистом или хотя бы получать удовольствие от технологий. И если вы всё же напишете полезные модули ядра, надеюсь, вы опубликуете их под лицензией GPL, чтобы и я мог ими пользоваться.

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

**********

[Linux](/tags/linux.md)
[ядро](/tags/kernel.md)
[модули ядра](/tags/kernel_modules.md)
[драйверы](/tags/device_drivers.md)