Debian Codegraph @

Documentation/translations/pt_BR/process/maintainer-soc.rst

raw
1 .. SPDX-License-Identifier: GPL-2.0
2
3 ==============
4 Subsistema SoC
5 ==============
6
7 Visão Geral
8 -----------
9
10 O subsistema SoC é um local de agregação para códigos específicos de SoC
11 System on Chip). Os principais componentes do subsistema são:
12
13 * Devicetrees (DTS) para ARM de 32 e 64 bits e RISC-V.
14 * Arquivos de placa (board files) ARM de 32 bits (arch/arm/mach*).
15 * Defconfigs ARM de 32 e 64 bits.
16 * Drivers específicos de SoC em diversas arquiteturas, em particular para ARM de
17 * 32 e 64 bits, RISC-V e Loongarch.
18
19 Estes "drivers específicos de SoC" não incluem drivers de clock, GPIO, etc., que
20 possuem outros mantenedores de alto nível. O diretório ``drivers/soc/`` é
21 geralmente destinado a drivers internos do kernel que são usados por outros
22 drivers para fornecer funcionalidades específicas do SoC, como identificar uma
23 revisão do chip ou fazer a interface com domínios de energia.
24
25 O subsistema SoC também serve como um local intermediário para alterações em
26 ``drivers/bus``, ``drivers/firmware``, ``drivers/reset`` e ``drivers/memory``.
27 A adição de novas plataformas, ou a remoção de existentes, geralmente passa pela
28 árvore SoC como um branch dedicado cobrindo múltiplos subsistemas.
29
30 A árvore principal do SoC está hospedada no git.kernel.org:
31 https://git.kernel.org/pub/scm/linux/kernel/git/soc/soc.git/
32
33 Mantenedores
34 ------------
35
36 Claramente, esta é uma gama bastante ampla de tópicos, que nenhuma pessoa, ou
37 mesmo um pequeno grupo de pessoas, é capaz de manter. Em vez disso, o
38 subsistema SoC é composto por muitos submantenedores (mantenedores de
39 plataforma), cada um cuidando de plataformas individuais e subdiretórios de
40 drivers.
41
42 Nesse sentido, "plataforma" geralmente se refere a uma série de SoCs de um
43 determinado fornecedor, por exemplo, a série de SoCs Tegra da Nvidia. Muitos
44 submantenedores operam em nível de fornecedor, sendo responsáveis por várias
45 linhas de produtos. Por diversos motivos, incluindo aquisições ou diferentes
46 unidades de negócios em uma empresa, as coisas variam significativamente aqui.
47 Os diversos submantenedores estão documentados no arquivo ``MAINTAINERS``.
48
49 A maioria desses submantenedores possui suas próprias árvores onde preparam os
50 patches, enviando pull requests para a árvore SoC principal. Essas árvores são
51 geralmente, mas nem sempre, listadas em ``MAINTAINERS``.
52
53 O que a árvore SoC não é, contudo, é um local para alterações de código
54 específicas da arquitetura. Cada arquitetura possui seus próprios mantenedores
55 que são responsáveis pelos detalhes arquiteturais, erratas de CPU e afins.
56
57 Submetendo Patches para um Determinado SoC
58 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
59
60 Todos os patches típicos relacionados à plataforma devem ser enviados por meio
61 dos submantenedores de SoC (mantenedores específicos da plataforma). Isso inclui
62 também alterações em defconfigs por plataforma ou compartilhadas. Note que
63 ``scripts/get_maintainer.pl`` pode não fornecer os endereços corretos para a
64 defconfig compartilhada; portanto, ignore sua saída e crie manualmente a lista
65 de CC baseada no arquivo ``MAINTAINERS`` ou use algo como
66 ``scripts/get_maintainer.pl -f drivers/soc/FOO/``.
67
68 Submetendo Patches para os Mantenedores Principais de SoC
69 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
70
71 Os mantenedores principais de SoC podem ser contatados via o alias
72 [email protected] apenas nos seguintes casos:
73
74 1. Não existem mantenedores específicos para a plataforma.
75
76 2. Os mantenedores específicos da plataforma não respondem.
77
78 3. Introdução de uma plataforma SoC completamente nova. Tal trabalho de novo SoC
79 deve ser enviado primeiro para as listas de discussão comuns, indicadas por
80 ``scripts/get_maintainer.pl``, para revisão da comunidade. Após uma revisão
81 positiva da comunidade, o trabalho deve ser enviado para [email protected] em
82 um único conjunto de patches (*patchset*) contendo a nova entrada em
83 ``arch/foo/Kconfig``, arquivos DTS, entrada no arquivo ``MAINTAINERS`` e,
84 opcionalmente, drivers iniciais com seus respectivos bindings de Devicetree.
85 A entrada no arquivo ``MAINTAINERS`` deve listar os novos mantenedores
86 específicos da plataforma, que serão responsáveis por lidar com os patches
87 da plataforma de agora em diante.
88
89 Note que o endereço [email protected] geralmente não é o local para discutir os
90 patches; portanto, o trabalho enviado para este endereço já deve ser
91 considerado aceitável pela comunidade.
92
93 Informações para (novos) Submantenedores
94 ----------------------------------------
95
96 À medida que novas plataformas surgem, elas frequentemente trazem consigo novos
97 submantenedores, muitos dos quais trabalham para o fornecedor do silício e podem
98 não estar familiarizados com o processo.
99
100 Estabilidade da ABI do Devicetree
101 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
102
103 Talvez um dos pontos mais importantes a destacar é que os *dt-bindings*
104 documentam a ABI entre o devicetree e o kernel. Por favor, leia
105 ``Documentation/devicetree/bindings/ABI.rst``.
106
107 Se estiverem sendo feitas alterações em um DTS que sejam incompatíveis com
108 kernels antigos, o patch do DTS não deve ser aplicado até que o driver seja, ou
109 em um momento apropriado posterior. Mais importante ainda, quaisquer alterações
110 incompatíveis devem ser claramente apontadas na descrição do patch e no pull
111 request, juntamente com o impacto esperado nos usuários existentes, como
112 bootloaders ou outros sistemas operacionais.
113
114 Dependências de Branch de Driver
115 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
116
117 Um problema comum é a sincronização de alterações entre drivers de dispositivos
118 e arquivos de devicetree. Mesmo que uma alteração seja compatível em ambas as
119 direções, isso pode exigir a coordenação de como as mudanças são mescladas
120 através de diferentes árvores de mantenedores.
121
122 Geralmente, o branch que inclui uma alteração de driver também incluirá a
123 mudança correspondente na descrição do binding do devicetree, para garantir que
124 sejam, de fato, compatíveis. Isso significa que o branch do devicetree pode
125 acabar causando avisos na etapa ``make dtbs_check``. Se uma alteração de
126 devicetree depender de adições ausentes em um arquivo de cabeçalho em
127 ``include/dt-bindings/``, ela falhará na etapa ``make dtbs`` e não será mesclada.
128
129 Existem várias maneiras de lidar com isso:
130
131 * Evite definir macros personalizadas em ``include/dt-bindings/`` para constantes
132 de hardware que podem ser derivadas de um datasheet -- macros de binding em
133 arquivos de cabeçalho devem ser usadas apenas como último recurso, se não
134 houver uma maneira natural de definir um binding.
135
136 * Use valores literais no arquivo devicetree em vez de macros, mesmo quando um
137 cabeçalho for necessário, e altere-os para a representação nomeada em um
138 lançamento posterior.
139
140 * Adie as alterações do devicetree para um lançamento após o binding e o driver
141 já terem sido mesclados.
142
143 * Altere os bindings em um branch imutável compartilhado que seja usado como
144 base tanto para a alteração do driver quanto para as alterações do devicetree.
145
146 * Adicione definições duplicadas no arquivo devicetree protegidas por uma seção
147 ``#ifndef``, removendo-as em um lançamento posterior.
148
149 Convenção de Nomenclatura de Devicetree
150 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
151
152 O esquema geral de nomenclatura para arquivos de devicetree é o seguinte. Os
153 aspectos de uma plataforma que são definidos no nível do SoC, como núcleos de
154 CPU, são contidos em um arquivo nomeado ``$soc.dtsi``, por exemplo,
155 ``jh7100.dtsi``. Detalhes de integração, que variam de placa para placa, são
156 descritos em ``$soc-$board.dts``. Um exemplo disso é
157 ``jh7100-beaglev-starlight.dts``. Frequentemente, muitas placas são variações
158 de um mesmo tema, e é comum haver arquivos intermediários, como
159 ``jh7100-common.dtsi``, que ficam entre os arquivos ``$soc.dtsi`` e
160 ``$soc-$board.dts``, contendo as descrições de hardware comum.
161
162 Algumas plataformas também possuem *System on Modules* (SoM), contendo um SoC,
163 que são então integrados em diversas placas diferentes. Para essas plataformas,
164 ``$soc-$som.dtsi`` e ``$soc-$som-$board.dts`` são típicos.
165
166 Os diretórios geralmente são nomeados após o fornecedor do SoC no momento de sua
167 inclusão, o que leva a alguns nomes de diretórios históricos na árvore.
168
169 Validando Arquivos de Devicetree
170 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
171
172 ``make dtbs_check`` pode ser usado para validar se os arquivos de devicetree
173 estão em conformidade com os *dt-bindings* que descrevem a ABI. Por favor, leia
174 a seção "Running checks" de ``Documentation/devicetree/bindings/writing-schema.rst``
175 para mais informações sobre a validação de devicetrees.
176
177 Para novas plataformas, ou adições a plataformas existentes, ``make dtbs_check``
178 não deve adicionar nenhum aviso (*warning*) novo. Para SoCs RISC-V e Samsung, é
179 exigido que ``make dtbs_check W=1`` não adicione nenhum novo aviso.
180 Se houver qualquer dúvida sobre uma alteração de devicetree, entre em contato
181 com os mantenedores de devicetree.
182
183 Branches e Pull Requests
184 ~~~~~~~~~~~~~~~~~~~~~~~~
185
186 Assim como a árvore SoC principal possui vários branches, espera-se que os
187 submantenedores façam o mesmo. Alterações de drivers, defconfig e devicetree
188 devem ser todas divididas em branches separados e aparecer em pull requests
189 distintos para os mantenedores de SoC. Cada branch deve ser utilizável por si só
190 e evitar regressões originadas de dependências em outros branches.
191
192 Pequenos conjuntos de patches também podem ser enviados como e-mails separados
193 para [email protected], agrupados nas mesmas categorias.
194
195 Se as alterações não se encaixarem nos padrões normais, pode haver branches de
196 nível superior adicionais, por exemplo, para uma reformulação em toda a árvore
197 (*treewide rework*) ou a adição de novas plataformas SoC, incluindo arquivos dts
198 e drivers.
199
200 Branches com muitas alterações podem se beneficiar ao serem divididos em
201 branches de tópicos separados, mesmo que acabem sendo mesclados no mesmo branch
202 da árvore SoC. Um exemplo aqui seria um branch para correções de avisos de
203 devicetree, um para uma reformulação e um para placas recém-adicionadas.
204
205 Outra forma comum de dividir as alterações é enviar um pull request antecipado
206 com a maioria das mudanças em algum momento entre rc1 e rc4, seguido por um ou
207 mais pull requests menores no final do ciclo, que podem adicionar alterações
208 tardias ou resolver problemas identificados durante os testes do primeiro
209 conjunto.
210
211 Embora não haja um prazo limite para pull requests tardios, ajuda enviar apenas
212 branches pequenos à medida que o tempo se aproxima da janela de mesclagem
213 (*merge window*).
214
215 Pull requests para correções de bugs (*bugfixes*) da versão atual podem ser
216 enviados a qualquer momento, mas, novamente, ter múltiplos branches menores é
217 melhor do que tentar combinar muitos patches em um único pull request.
218
219 A linha de assunto de um pull request deve começar com "[GIT PULL]" e ser feita
220 usando uma tag assinada, em vez de um branch. Esta tag deve conter uma breve
221 descrição resumindo as alterações no pull request. Para mais detalhes sobre o
222 envio de pull requests, consulte ``Documentation/maintainer/pull-requests.rst``.