Linux Driver Verification

{{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. Проверяем отсутствие ошибок после исправления

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

* Unsafe, который соответствует ложному сообщению об ошибке по какой-либо причине. Можно попытаться обойти соответствующую проблему, если это не очень сложно.

* Safe. При этом желательно убедиться, что покрытие кода более-менее адекватное. Иногда бывает так, что в suspend/resume/remove/disconnect могут быть ошибки похожие на ошибки в probe, например, что-то не удаляется, не чистится или не учитывается код возврата некоторой функции. С большой вероятностью разработчики это заметят и всё равно попросят сделать нужные исправления. Достаточно часто Klever сможет выдать Unsafe для данных ошибок при повторной верификации.

* Unknown, например, timeout. В данном случае скорее всего по-простому сделать ничего не получится.

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

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 Driver Verification project (linuxtesting.org).

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 воспользуется значениями указанными в теле патча.

h2. Заводим описание проблемы на linuxtesting.org

Когда разработчики подтвердят, что они ошибку признают, её нужно опубликовать на linuxtesting.org.

Для этого логинимся на linuxtesting.org под своим логином.

Идем сюда: http://linuxtesting.ru/results/impl_reports_admin.

Заводим проблему с идентификатором LXXXX, где XXXX - следующий свободный номер.

Пример описания в плоском виде:

http://linuxtesting.org/results/impl_reports_admin?action=edit&num=L0044

В качестве "типа" проблемы указываем подходящий вариант.

В "краткое описание" копируем заголовок патча. 

В "подробное описание" добавляем описание патча, исключая упоминания о самом патче. 

Следующее поле, которое необходимо заполнить - "Компонент (с версией)". Здесь указывается версия ядра, в которой еще не было исправления, указанного в патче. Посмотреть это можно на сайте kernel.org, в соответствии с тегами в ветке Линуса Торвальдса.

В поле "принято" копируем следующие строчки: 

<pre>

<a href="https://lkml.org/lkml/2012/4/5/373">https://lkml.org/lkml/2012/4/5/373</a><br/>

<a href="http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=commitdiff;h=e4459e1682c107d7ee1bf102c1ba534230e9b50b">commit</a>

</pre>

и затем правим их.

В гугле набираем следующий запрос: "site:lkml.org ХХХ", где вместо ХХХ пишем заголовок нашего патча. Тем самым мы находим публикацию нашего патча на сайте lkml.org.

Вставляем полученную ссылку вместо той, которая указана в примере.

Дальше меняем ссылку с git.kernel.org на свою (меняем только номер коммита, остальая часть должна быть такой же).

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

 git describe --contains e4459e1682c107d7ee1bf102c1ba534230e9b50b

Дату и время берем из коммита из раздела committer. 

Жмем кнопку "submit".

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

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

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

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