Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs/pt_BR: translation of maintainer-soc.rst
Translate Documentation/process/maintainer-soc.rst into Portuguese.
This is part of the effort to localize the kernel documentation.
Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260319115416.495020-2-danielmaraboo@gmail.com>
authored by
Daniel Pereira
and committed by
Jonathan Corbet
a39b136f
98e7b575
+224
+1
Documentation/translations/pt_BR/index.rst
+1
Documentation/translations/pt_BR/index.rst
+1
Documentation/translations/pt_BR/process/maintainer-handbooks.rst
+1
Documentation/translations/pt_BR/process/maintainer-handbooks.rst
+222
Documentation/translations/pt_BR/process/maintainer-soc.rst
+222
Documentation/translations/pt_BR/process/maintainer-soc.rst
···
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
+
soc@kernel.org 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 soc@kernel.org 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 soc@kernel.org 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 soc@kernel.org, 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``.