Project

General

Profile

How to send patches to kernel » History » Version 9

Alexey Khoroshilov, 07/14/2022 04:18 PM

1 1 Alexey Khoroshilov
{{toc}}
2
3
h1. Сообщение об ошибке в виде патча
4
5 3 Vitaly Omelchenko
Ниже на примере рассматривается подготовка и отправка в 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).
6 1 Alexey Khoroshilov
7
h2. Предварительная настройка git
8
9 3 Vitaly Omelchenko
10
Для корректного оформления патчей все коммиты должны быть подписаны при помощи опции --signoff команды git commit. Для этого необходимо добавить в конфигурацию Git значения параметров user.name и user.email:
11
12
 git config --global user.name "Alexey Khoroshilov"
13
git config --global user.email "khoroshilov@ispras.ru"
14
15
Чтобы патчи, подготовленные для отправки в списки рассылки, не вставлять вручную в почтовый клиент,  можно использовать команду "git send-email":https://git-scm.com/docs/git-send-email. Для этого в конфигурацию Git в раздел [sendemail] необходимо добавить параметры, соответствующие настройкам сервера SMTP, через который будет отправляться почта. Часто достаточно задать адрес сервера SMTP, порт и тип шифрования:
16
17
 git config --global sendemail.smtpServer "mail.ispras.ru"
18
git config --global sendemail.smtpServerPort "587"
19
git config --global sendemail.smtpEncryption "tls"
20
21
Также для изменения конфигурации Git можно использовать команду git config --global --edit, которая открывает файл конфигурации Git в редакторе.  
22
23
Конфигурация Git для рассматриваемого примера выглядит следующим образом:
24
25 1 Alexey Khoroshilov
 cat ~/.gitconfig 
26
[user]
27
      name = Alexey Khoroshilov
28
      email = khoroshilov@ispras.ru
29
[sendemail]
30
      smtpserver = mail.ispras.ru
31
      smtpEncryption = tls
32
      smtpserverport = 587
33
34 3 Vitaly Omelchenko
h2. Обновление репозитория до самой свежей версии и создание новой ветки
35 1 Alexey Khoroshilov
36 3 Vitaly Omelchenko
Перед внесением изменений в код ядра необходимо склонировать или обновить соответствующий репозиторий ядра и создать новую ветку для подготовки патча.
37 1 Alexey Khoroshilov
38 3 Vitaly Omelchenko
Как правило, клонируется или обновляется основной репозиторий ядра: 
39 1 Alexey Khoroshilov
40 3 Vitaly Omelchenko
 git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
41 1 Alexey Khoroshilov
42 3 Vitaly Omelchenko
или, если репозиторий был уже склонирован ранее
43 1 Alexey Khoroshilov
44 3 Vitaly Omelchenko
 git pull
45
46
Создаем отдельную ветку для подготовки исправления (в рассматриваемом примере ветка названа по имени драйвера):
47
48 1 Alexey Khoroshilov
 git checkout -b usb_gadget master
49
50
h2. Вносим необходимые исправления в код, соблюдая принятые правила форматирования
51
52 3 Vitaly Omelchenko
При внесении изменений в код необходимо соблюдать принятые в сообществе разработчиков ядра Linux правила форматирования кода (см. "Linux kernel coding style":https://docs.kernel.org/process/coding-style.html, 
53
"root/Documentation/process/coding-style.rst":https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst).  
54 1 Alexey Khoroshilov
55 3 Vitaly Omelchenko
h2. Проверяем компилируемость ядра
56 1 Alexey Khoroshilov
57 3 Vitaly Omelchenko
После внесения изменений в код запускаем сборку ядра, по завершении которой необходимо проверить, что измененные файлы были скомпилированы:
58
59 1 Alexey Khoroshilov
 make allmodconfig
60
make prepare
61
make modules_prepare
62 3 Vitaly Omelchenko
make M=drivers/xxx/  #или
63
make drivers/xxx/filename.o
64 1 Alexey Khoroshilov
65
h2. Проверяем отсутствие ошибок после исправления
66
67
**TODO:** Предоставить возможность прогнать SVACE на версии с применённым патчем.
68
69
h2. Коммитим исправления
70
71
Делаем коммит.  Используем --signoff, чтобы добавить  строчку "Signed-off-by: Alexey Khoroshilov <khoroshilov@ispras.ru>"  (обязательно нужна).
72
73
 git commit --signoff drivers/usb/gadget/inode.c
74
75
В теле коммита, для простоты, можно сразу писать багрепорт.  Шаблон такой:
76
77
<pre>
78
usb-gadget: Add module_put on error path in if_open()
79
80
If something happens (describe the path), then module_put is not 
81
called (describe the problem).
82
    
83
Make if_open() do module_put on error path (describe the solution in imperative mood).
84
If the solution is trivial, this section can be omitted.
85
    
86 4 Alexey Khoroshilov
Found by Linux Verification Center (linuxtesting.org) with SVACE.
87 1 Alexey Khoroshilov
</pre>
88 4 Alexey Khoroshilov
89
Если ошибка найдена не при помощи SVACE, то это необходимо отразить в последней строчке, например:
90
Found by Linux Verification Center (linuxtesting.org) with syzkaller.
91 1 Alexey Khoroshilov
92
Рекомендуется познакомиться с "общими правилами оформления сообщений коммитов":https://chris.beams.io/posts/git-commit/, которые применимы в том числе и для коммитов в ядро Linux.
93
94
Вместо usb-gadget нужен определённый идентифицирующий префикс; его можно посмотреть в логе изменений конкретного файла.
95
96 7 Alexey Khoroshilov
При совместной разработке патча в конце коммита желательно указать участвующих коллег:
97 1 Alexey Khoroshilov
98
<pre>
99
Co-developed-by: Co-Author <coauthor@ispras.ru>
100
Signed-off-by: Co-Author <coauthor@ispras.ru>
101
</pre>
102
103 9 Alexey Khoroshilov
*Hint.* Если известен коммит, в котором была внесена исправляемая ошибка, то в текст коммита (перед строчкой "Signed-off-by: Alexey Khoroshilov <khoroshilov@ispras.ru>") рекомендуется вставить строчку с префиксом "Fixes:". Её можно сгенерировать при помощи команды:
104 1 Alexey Khoroshilov
105
<pre>
106 5 Alexey Khoroshilov
 git show -s --pretty="format:Fixes: %h (\"%s\")" HASH-OF-COMMIT-THAT-INTRODUCED-BUG
107 1 Alexey Khoroshilov
</pre>
108
109
В последнее время разработчики достаточно регулярно просят указать данный тег, поэтому рекомедуется делать это в обязательном порядке, даже если при этом приходится ссылаться на первоначальный коммит, который добавил соответствующий драйвер в ядро, т.е. ошибка была в коде изначально.
110
111
h2. Создаем сам патч
112
113
 git format-patch master..usb_gadget
114
115
Гит сделает что-то типа письма из того коммита, который был сделан ранее.
116
117
*Hint.* Имя текущей ветки можно и опустить:
118
119
<pre>
120
 git format-patch master..
121
</pre>
122
123
*Hint.* При генерации второй и последующих версий используйте аргумент -v:
124
125
<pre>
126
 git format-patch -v 2 master..
127
</pre>
128
129
130
h2. Проверяем его форматирование
131
132
 ./scripts/checkpatch.pl 0001-xxx.patch
133
134
h2. Редактируем файл с патчем
135
136
h3. Тема письма
137
138
Если всё сделали правильно, то формат-патч сам создаст такую тему:
139
140
 [PATCH] prefix: short description
141
 
142
h3. Идентифицируем адресатов
143
144
 ./scripts/get_maintainer.pl 0001-xxx.patch
145
146
Удаляем то, что в скобочках круглых, ставим первому адресату To:, а остальным — Cc:.  Дописываем в письмо. Также добавляем в Cc список рассылки: ldv-project@linuxtesting.org.
147
148
На этом этапе в текст письма можно внести произвольные изменения.
149
150
В результате получается что-то типа:
151
152
<pre>
153
From 9bbb34d71038fc7015917646a3365bca20cacb02 Mon Sep 17 00:00:00 2001
154
From: Alexey Khoroshilov <khoroshilov@ispras.ru>
155
To: Mauro Carvalho Chehab <mchehab@infradead.org>
156
Cc: linux-media@vger.kernel.org
157
Cc: linux-kernel@vger.kernel.org
158
Cc: ldv-project@linuxtesting.org
159
Date: Thu, 26 May 2011 00:38:12 +0400
160
Subject: [PATCH] usb-gadget: unlock data->lock mutex on error path in ep_write()
161
162
ep_read() acquires data->lock mutex in get_ready_ep() and releases it on
163
all paths except for one: when usb_endpoint_xfer_isoc() failed. The
164
patch adds mutex_unlock(&data->lock) at that path.
165
166
Found by Linux Verification Center (linuxtesting.org) with SVACE.
167
168
Signed-off-by: Alexey Khoroshilov <khoroshilov@ispras.ru>
169
---
170
 drivers/usb/gadget/inode.c |    4 +++-
171
 1 files changed, 3 insertions(+), 1 deletions(-)
172
173
diff --git a/drivers/usb/gadget/inode.c b/drivers/usb/gadget/inode.c
174
index 3ed73f4..a01383f 100644
175
--- a/drivers/usb/gadget/inode.c
176
+++ b/drivers/usb/gadget/inode.c
177
@@ -386,8 +386,10 @@ ep_read (struct file *fd, char __user *buf, size_tlen, loff_t *ptr)
178
179
	/* halt any endpoint by doing a "wrong direction" i/o call */
180
	if (usb_endpoint_dir_in(&data->desc)) {
181
-		if (usb_endpoint_xfer_isoc(&data->desc))
182
+		if (usb_endpoint_xfer_isoc(&data->desc)) {
183
+			mutex_unlock(&data->lock);
184
			return -EINVAL;
185
+		}
186
		DBG (data->dev, "%s halt\n", data->name);
187
		spin_lock_irq (&data->dev->lock);
188
		if (likely (data->ep != NULL))
189
-- 1.7.0.4
190
</pre>
191
192
h3. Внимательно проверяем орфографию
193
194
Например, можно скопировать текст из 0001-xxx.patch в какой-нибудь редактор документов, в котором включены соответствующие проверки. Это позволит не нервировать разработчиков орфографическими ошибками, а также избежать повторной отправки патчей.
195
196
h2. Отправляем
197
198
 git send-email 0001-xxx.patch
199
200 8 Alexey Khoroshilov
Можно указать несколько патчей сразу через пробел, но если это независимые патчи, то делать этого **не нужно**, ибо тогда git скомпонует из них одну цепочку (письма будут ответами на первое). Конечно, если вы посылаете серию патчей, то это делается одной командой:
201 1 Alexey Khoroshilov
202
 git send-email 0001-xxx.patch 0002-yyy.patch 0003-zzz.patch
203
204
Команда git send-email спрашивает кому отправить письма и т.д. Если в теле патча всё указано верно, то можно смело нажимать Enter ничего не вводя и git воспользуется значениями указанными в теле патча.
205
206
h1. Сообщение об ошибке без патча
207
208
Если вкратце, то готовим такое же письмо как и выше, и посылаем его тем же адресатам (см. ./scripts/get_maintainer.pl -f path_to_file), но только с описанием проблемы и её последствий, без предложения по исправлению. Посылаем из любого почтового клиента **плоским текстом (не HTML)**.
209
210
В конце письма необходимо вставить строчку:
211
212
 Found by Linux Verification Center (linuxtesting.org) with SVACE.