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