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

{{toc}}

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

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

 cat ~/.gitconfig 

[user]

      name = Alexey Khoroshilov

      email = khoroshilov@ispras.ru

[sendemail]

      smtpserver = mail.ispras.ru

      smtpEncryption = tls

      smtpserverport = 587

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

В большинстве случаев - из [git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git].

 git pull

h2. Создаем отдельную ветку для подготовки исправления

В данном примере ветка названа по имени драйвера.

 git checkout -b usb_gadget master

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

См. 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).

</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.