How to send patches to kernel » History » Version 11
Alexey Khoroshilov, 07/14/2022 04:24 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 | 11 | Alexey Khoroshilov | При поиске коммита, который внёс ошибку важно учитывать перемещения файла между директориями. Для этого бывает удобно воспользоваться опцией --follow, которая позволяет увидеть историю изменений в файле с учётом его перемещений внутри репозитория: |
112 | |||
113 | <pre> |
||
114 | git log -p --follow drivers/usb/gadget/legacy/inode.c |
||
115 | </pre> |
||
116 | |||
117 | |||
118 | 1 | Alexey Khoroshilov | h2. Создаем сам патч |
119 | |||
120 | git format-patch master..usb_gadget |
||
121 | |||
122 | Гит сделает что-то типа письма из того коммита, который был сделан ранее. |
||
123 | |||
124 | *Hint.* Имя текущей ветки можно и опустить: |
||
125 | |||
126 | <pre> |
||
127 | git format-patch master.. |
||
128 | </pre> |
||
129 | |||
130 | *Hint.* При генерации второй и последующих версий используйте аргумент -v: |
||
131 | |||
132 | <pre> |
||
133 | git format-patch -v 2 master.. |
||
134 | </pre> |
||
135 | |||
136 | |||
137 | h2. Проверяем его форматирование |
||
138 | |||
139 | ./scripts/checkpatch.pl 0001-xxx.patch |
||
140 | |||
141 | h2. Редактируем файл с патчем |
||
142 | |||
143 | h3. Тема письма |
||
144 | |||
145 | Если всё сделали правильно, то формат-патч сам создаст такую тему: |
||
146 | |||
147 | [PATCH] prefix: short description |
||
148 | 10 | Alexey Khoroshilov | |
149 | 1 | Alexey Khoroshilov | h3. Идентифицируем адресатов |
150 | |||
151 | ./scripts/get_maintainer.pl 0001-xxx.patch |
||
152 | |||
153 | Удаляем то, что в скобочках круглых, ставим первому адресату To:, а остальным — Cc:. Дописываем в письмо. Также добавляем в Cc список рассылки: ldv-project@linuxtesting.org. |
||
154 | |||
155 | На этом этапе в текст письма можно внести произвольные изменения. |
||
156 | |||
157 | В результате получается что-то типа: |
||
158 | |||
159 | <pre> |
||
160 | From 9bbb34d71038fc7015917646a3365bca20cacb02 Mon Sep 17 00:00:00 2001 |
||
161 | From: Alexey Khoroshilov <khoroshilov@ispras.ru> |
||
162 | To: Mauro Carvalho Chehab <mchehab@infradead.org> |
||
163 | Cc: linux-media@vger.kernel.org |
||
164 | Cc: linux-kernel@vger.kernel.org |
||
165 | Cc: ldv-project@linuxtesting.org |
||
166 | Date: Thu, 26 May 2011 00:38:12 +0400 |
||
167 | Subject: [PATCH] usb-gadget: unlock data->lock mutex on error path in ep_write() |
||
168 | |||
169 | ep_read() acquires data->lock mutex in get_ready_ep() and releases it on |
||
170 | all paths except for one: when usb_endpoint_xfer_isoc() failed. The |
||
171 | patch adds mutex_unlock(&data->lock) at that path. |
||
172 | |||
173 | Found by Linux Verification Center (linuxtesting.org) with SVACE. |
||
174 | |||
175 | 10 | Alexey Khoroshilov | Fixes: 193ab2a60700 ("usb: gadget: allow multiple gadgets to be built") |
176 | 1 | Alexey Khoroshilov | Signed-off-by: Alexey Khoroshilov <khoroshilov@ispras.ru> |
177 | --- |
||
178 | drivers/usb/gadget/inode.c | 4 +++- |
||
179 | 1 files changed, 3 insertions(+), 1 deletions(-) |
||
180 | |||
181 | diff --git a/drivers/usb/gadget/inode.c b/drivers/usb/gadget/inode.c |
||
182 | index 3ed73f4..a01383f 100644 |
||
183 | --- a/drivers/usb/gadget/inode.c |
||
184 | +++ b/drivers/usb/gadget/inode.c |
||
185 | @@ -386,8 +386,10 @@ ep_read (struct file *fd, char __user *buf, size_tlen, loff_t *ptr) |
||
186 | |||
187 | /* halt any endpoint by doing a "wrong direction" i/o call */ |
||
188 | if (usb_endpoint_dir_in(&data->desc)) { |
||
189 | - if (usb_endpoint_xfer_isoc(&data->desc)) |
||
190 | + if (usb_endpoint_xfer_isoc(&data->desc)) { |
||
191 | + mutex_unlock(&data->lock); |
||
192 | return -EINVAL; |
||
193 | + } |
||
194 | DBG (data->dev, "%s halt\n", data->name); |
||
195 | spin_lock_irq (&data->dev->lock); |
||
196 | if (likely (data->ep != NULL)) |
||
197 | -- 1.7.0.4 |
||
198 | </pre> |
||
199 | |||
200 | h3. Внимательно проверяем орфографию |
||
201 | |||
202 | Например, можно скопировать текст из 0001-xxx.patch в какой-нибудь редактор документов, в котором включены соответствующие проверки. Это позволит не нервировать разработчиков орфографическими ошибками, а также избежать повторной отправки патчей. |
||
203 | |||
204 | h2. Отправляем |
||
205 | |||
206 | git send-email 0001-xxx.patch |
||
207 | |||
208 | 8 | Alexey Khoroshilov | Можно указать несколько патчей сразу через пробел, но если это независимые патчи, то делать этого **не нужно**, ибо тогда git скомпонует из них одну цепочку (письма будут ответами на первое). Конечно, если вы посылаете серию патчей, то это делается одной командой: |
209 | 1 | Alexey Khoroshilov | |
210 | git send-email 0001-xxx.patch 0002-yyy.patch 0003-zzz.patch |
||
211 | |||
212 | Команда git send-email спрашивает кому отправить письма и т.д. Если в теле патча всё указано верно, то можно смело нажимать Enter ничего не вводя и git воспользуется значениями указанными в теле патча. |
||
213 | |||
214 | h1. Сообщение об ошибке без патча |
||
215 | |||
216 | Если вкратце, то готовим такое же письмо как и выше, и посылаем его тем же адресатам (см. ./scripts/get_maintainer.pl -f path_to_file), но только с описанием проблемы и её последствий, без предложения по исправлению. Посылаем из любого почтового клиента **плоским текстом (не HTML)**. |
||
217 | |||
218 | В конце письма необходимо вставить строчку: |
||
219 | |||
220 | Found by Linux Verification Center (linuxtesting.org) with SVACE. |