Project

General

Profile

How to send patches to kernel » History » Version 5

Alexey Khoroshilov, 05/19/2022 08:07 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
При совместной разработке патча в конце коммита желательно указать учавствующих коллег:
97
98
<pre>
99
Co-developed-by: Co-Author <coauthor@ispras.ru>
100
Signed-off-by: Co-Author <coauthor@ispras.ru>
101
</pre>
102
103 5 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
Можно указать несколько патчей сразу через пробел, но если это независимые патчи, то делать этого '''не нужно''', ибо тогда git скомпонует из них одну цепочку (письма будут ответами на первое). Конечно, если вы посылаете серию патчей, то это делается одной командой:
201
202
 git send-email 0001-xxx.patch 0002-yyy.patch 0003-zzz.patch
203
204
Команда git send-email спрашивает кому отправить письма и т.д. Если в теле патча всё указано верно, то можно смело нажимать Enter ничего не вводя и git воспользуется значениями указанными в теле патча.
205
206
207
h1. Сообщение об ошибке без патча
208
209
Если вкратце, то готовим такое же письмо как и выше, и посылаем его тем же адресатам (см. ./scripts/get_maintainer.pl -f path_to_file), но только с описанием проблемы и её последствий, без предложения по исправлению. Посылаем из любого почтового клиента **плоским текстом (не HTML)**.
210
211
В конце письма необходимо вставить строчку:
212
213
 Found by Linux Verification Center (linuxtesting.org) with SVACE.