Технологический центр исследования безопасности ядра Linux

{{toc}}

h1. Сообщение об ошибке в виде патча

Ниже на примере рассматривается подготовка и отправка в kernel.org почтовой версии набора коммитов (патча) с исправлением ошибки, найденной в в коде драйвера при помощи Svace. Более полную информацию о разработке, подготовке и отправке патчей, в том числе для случаев изменений в коде драйверов и связанном с  платформами конечных устройств, а также о требованиях к отправляемому коду, можно получить в документации на "docs.kernel.org":https://docs.kernel.org/ ("Submitting patches: the essential guide to getting your code into the kernel":https://docs.kernel.org/process/submitting-patches.html, "Linux Kernel patch submission checklist":https://docs.kernel.org/process/submit-checklist.html, "A guide to the Kernel Development Process":https://docs.kernel.org/process/development-process.html).

h2. Предварительная настройка git

Для корректного оформления патчей все коммиты должны быть подписаны при помощи опции --signoff команды git commit. Для этого необходимо добавить в конфигурацию Git значения параметров user.name и user.email:

 git config --global user.name "Alexey Khoroshilov"

git config --global user.email "khoroshilov@ispras.ru"

Чтобы патчи, подготовленные для отправки в списки рассылки, не вставлять вручную в почтовый клиент,  можно использовать команду "git send-email":https://git-scm.com/docs/git-send-email. Для этого в конфигурацию Git в раздел [sendemail] необходимо добавить параметры, соответствующие настройкам сервера SMTP, через который будет отправляться почта. Часто достаточно задать адрес сервера SMTP, порт и тип шифрования:

 git config --global sendemail.smtpServer "mail.ispras.ru"

git config --global sendemail.smtpServerPort "587"

git config --global sendemail.smtpEncryption "tls"

Также для изменения конфигурации Git можно использовать команду git config --global --edit, которая открывает файл конфигурации Git в редакторе.  

Конфигурация Git для рассматриваемого примера выглядит следующим образом:

 cat ~/.gitconfig 

[user]

      name = Alexey Khoroshilov

      email = khoroshilov@ispras.ru

[sendemail]

      smtpserver = mail.ispras.ru

      smtpEncryption = tls

      smtpserverport = 587

h2. Обновление репозитория до самой свежей версии и создание новой ветки

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

Как правило, клонируется или обновляется основной репозиторий ядра: 

 git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

или, если репозиторий был уже склонирован ранее

 git pull

Создаем отдельную ветку для подготовки исправления (в рассматриваемом примере ветка названа по имени драйвера):

 git checkout -b usb_gadget master

h2. Вносим необходимые исправления в код, соблюдая принятые правила форматирования

При внесении изменений в код необходимо соблюдать принятые в сообществе разработчиков ядра Linux правила форматирования кода (см. "Linux kernel coding style":https://docs.kernel.org/process/coding-style.html, 

"root/Documentation/process/coding-style.rst":https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst).  

h2. Проверяем компилируемость ядра

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

 make allmodconfig

make prepare

make modules_prepare

make M=drivers/xxx/  #или

make drivers/xxx/filename.o

h2. Проверяем отсутствие ошибок после исправления

**TODO:** Предоставить возможность прогнать SVACE на версии с применённым патчем.

h2. Коммитим исправления

Делаем коммит.  Используем --signoff, чтобы добавить  строчку "Signed-off-by: Alexey Khoroshilov <khoroshilov@ispras.ru>"  (обязательно нужна).

 git commit --signoff drivers/usb/gadget/inode.c

В теле коммита, для простоты, можно сразу писать багрепорт.  Шаблон такой:

<pre>

usb-gadget: Add module_put on error path in if_open()

If something happens (describe the path), then module_put is not 

called (describe the problem).

Make if_open() do module_put on error path (describe the solution in imperative mood).

If the solution is trivial, this section can be omitted.

Found by Linux Driver Verification project (linuxtesting.org) with SVACE.

</pre>

Рекомендуется познакомиться с "общими правилами оформления сообщений коммитов":https://chris.beams.io/posts/git-commit/, которые применимы в том числе и для коммитов в ядро Linux.

Вместо usb-gadget нужен определённый идентифицирующий префикс; его можно посмотреть в логе изменений конкретного файла.

При совместной разработке патча в конце коммита желательно указать учавствующих коллег:

<pre>

Co-developed-by: Co-Author <coauthor@ispras.ru>

Signed-off-by: Co-Author <coauthor@ispras.ru>

</pre>

*Hint.* Если известен коммит, ошибку в котором была внесена исправляемая ошибка, то в текст коммита рекомендуется вставить строчку с префиксом "Fixes:". Её можно сгенерировать при помощи команды:

<pre>

 git show -s --pretty="format:Fixes: %h (\"%s\")" HASH-OF-COMMIT

</pre>

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

h2. Создаем сам патч

 git format-patch master..usb_gadget

Гит сделает что-то типа письма из того коммита, который был сделан ранее.

*Hint.* Имя текущей ветки можно и опустить:

<pre>

 git format-patch master..

</pre>

*Hint.* При генерации второй и последующих версий используйте аргумент -v:

<pre>

 git format-patch -v 2 master..

</pre>

h2. Проверяем его форматирование

 ./scripts/checkpatch.pl 0001-xxx.patch

h2. Редактируем файл с патчем

h3. Тема письма

Если всё сделали правильно, то формат-патч сам создаст такую тему:

 [PATCH] prefix: short description

h3. Идентифицируем адресатов

 ./scripts/get_maintainer.pl 0001-xxx.patch

Удаляем то, что в скобочках круглых, ставим первому адресату To:, а остальным — Cc:.  Дописываем в письмо. Также добавляем в Cc список рассылки: ldv-project@linuxtesting.org.

На этом этапе в текст письма можно внести произвольные изменения.

В результате получается что-то типа:

<pre>

From 9bbb34d71038fc7015917646a3365bca20cacb02 Mon Sep 17 00:00:00 2001

From: Alexey Khoroshilov <khoroshilov@ispras.ru>

To: Mauro Carvalho Chehab <mchehab@infradead.org>

Cc: linux-media@vger.kernel.org

Cc: linux-kernel@vger.kernel.org

Cc: ldv-project@linuxtesting.org

Date: Thu, 26 May 2011 00:38:12 +0400

Subject: [PATCH] usb-gadget: unlock data->lock mutex on error path in ep_write()

ep_read() acquires data->lock mutex in get_ready_ep() and releases it on

all paths except for one: when usb_endpoint_xfer_isoc() failed. The

patch adds mutex_unlock(&data->lock) at that path.

Found by Linux Verification Center (linuxtesting.org) with SVACE.

Signed-off-by: Alexey Khoroshilov <khoroshilov@ispras.ru>

---

 drivers/usb/gadget/inode.c |    4 +++-

 1 files changed, 3 insertions(+), 1 deletions(-)

diff --git a/drivers/usb/gadget/inode.c b/drivers/usb/gadget/inode.c

index 3ed73f4..a01383f 100644

--- a/drivers/usb/gadget/inode.c

+++ b/drivers/usb/gadget/inode.c

@@ -386,8 +386,10 @@ ep_read (struct file *fd, char __user *buf, size_tlen, loff_t *ptr)

	/* halt any endpoint by doing a "wrong direction" i/o call */

	if (usb_endpoint_dir_in(&data->desc)) {

-		if (usb_endpoint_xfer_isoc(&data->desc))

+		if (usb_endpoint_xfer_isoc(&data->desc)) {

+			mutex_unlock(&data->lock);

			return -EINVAL;

+		}

		DBG (data->dev, "%s halt\n", data->name);

		spin_lock_irq (&data->dev->lock);

		if (likely (data->ep != NULL))

-- 1.7.0.4

</pre>

h3. Внимательно проверяем орфографию

Например, можно скопировать текст из 0001-xxx.patch в какой-нибудь редактор документов, в котором включены соответствующие проверки. Это позволит не нервировать разработчиков орфографическими ошибками, а также избежать повторной отправки патчей.

h2. Отправляем

 git send-email 0001-xxx.patch

Можно указать несколько патчей сразу через пробел, но если это независимые патчи, то делать этого '''не нужно''', ибо тогда git скомпонует из них одну цепочку (письма будут ответами на первое). Конечно, если вы посылаете серию патчей, то это делается одной командой:

 git send-email 0001-xxx.patch 0002-yyy.patch 0003-zzz.patch

Команда git send-email спрашивает кому отправить письма и т.д. Если в теле патча всё указано верно, то можно смело нажимать Enter ничего не вводя и git воспользуется значениями указанными в теле патча.

h1. Сообщение об ошибке без патча

Если вкратце, то готовим такое же письмо как и выше, и посылаем его тем же адресатам (см. ./scripts/get_maintainer.pl -f path_to_file), но только с описанием проблемы и её последствий, без предложения по исправлению. Посылаем из любого почтового клиента **плоским текстом (не HTML)**.

В конце письма необходимо вставить строчку:

 Found by Linux Verification Center (linuxtesting.org) with SVACE.