How to send patches to kernel » History » Revision 8
Revision 7 (Alexey Khoroshilov, 06/30/2022 07:15 PM) → Revision 8/13 (Alexey Khoroshilov, 07/14/2022 04:17 PM)
{{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 Verification Center (linuxtesting.org) with SVACE. </pre> Если ошибка найдена не при помощи SVACE, то это необходимо отразить в последней строчке, например: Found by Linux Verification Center (linuxtesting.org) with syzkaller. Рекомендуется познакомиться с "общими правилами оформления сообщений коммитов":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.* Если известен коммит, в котором была внесена исправляемая ошибка, то в текст коммита (следом за строчкой "Signed-off-by: Alexey Khoroshilov <khoroshilov@ispras.ru>") рекомендуется вставить строчку с префиксом "Fixes:". Её можно сгенерировать при помощи команды: <pre> git show -s --pretty="format:Fixes: %h (\"%s\")" HASH-OF-COMMIT-THAT-INTRODUCED-BUG </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.