Project

General

Profile

How to send patches to kernel » History » Version 13

Evgeny Novikov, 08/20/2021 02:10 PM

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