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