| 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``. |