* [PATCH v2 1/7] docs: pt_BR: process: Translate the patch followthrough guide
2026-07-03 17:05 [PATCH v2 0/7] docs: pt_BR: process: translation updates and additions Daniel Pereira
@ 2026-07-03 17:05 ` Daniel Pereira
2026-07-03 17:05 ` [PATCH v2 2/7] docs: pt_BR: process: translate 7.AdvancedTopics and 8.Conclusion Daniel Pereira
` (5 subsequent siblings)
6 siblings, 0 replies; 8+ messages in thread
From: Daniel Pereira @ 2026-07-03 17:05 UTC (permalink / raw)
To: corbet; +Cc: linux-doc, Daniel Pereira
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=y, Size: 15072 bytes --]
Translates the section 6.followthrough.rst to Brazilian Portuguese
for the process directory.
Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
.../pt_BR/process/6.Followthrough.rst | 220 ++++++++++++++++++
.../pt_BR/process/development-process.rst | 1 +
2 files changed, 221 insertions(+)
create mode 100644 Documentation/translations/pt_BR/process/6.Followthrough.rst
diff --git a/Documentation/translations/pt_BR/process/6.Followthrough.rst b/Documentation/translations/pt_BR/process/6.Followthrough.rst
new file mode 100644
index 000000000..d6bdaa2cb
--- /dev/null
+++ b/Documentation/translations/pt_BR/process/6.Followthrough.rst
@@ -0,0 +1,220 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Acompanhamento
+==============
+
+Neste ponto, você seguiu as diretrizes apresentadas até aqui e, com a
+adição de suas próprias habilidades de engenharia, enviou uma série perfeita
+de patches. Um dos maiores erros que até mesmo desenvolvedores experientes
+do kernel podem cometer é concluir que o seu trabalho agora está concluído.
+Na verdade, o envio de patches indica uma transição para a próxima etapa
+do processo, possivelmente com uma quantidade considerável de trabalho
+ainda por fazer.
+
+É raro um patch ser tão bom em seu primeiro envio que não haja margem para
+melhorias. O processo de desenvolvimento do kernel reconhece esse fato e,
+como resultado, é fortemente orientado para o aprimoramento do código
+enviado. Espera-se que você, como autor desse código, trabalhe junto à
+comunidade do kernel para garantir que seu código esteja de acordo com os
+padrões de qualidade do kernel. A falha em participar desse processo muito
+provavelmente impedirá a inclusão de seus patches na árvore principal
+(*mainline*).
+
+
+Trabalhando com revisores
+-------------------------
+
+Um patch de qualquer relevância resultará em uma série de comentários de outros
+desenvolvedores à medida que eles revisam o código. Trabalhar com revisores
+pode ser, para muitos desenvolvedores, a parte mais intimidadora do processo
+de desenvolvimento do kernel. No entanto, a vida pode se tornar muito mais
+fácil se você mantiver algumas coisas em mente:
+
+* Se você explicou bem o seu patch, os revisores entenderão o seu valor
+ e o porquê de você ter tido o trabalho de escrevê-lo. Contudo, esse valor
+ não os impedirá de fazer uma pergunta fundamental: como será manter um
+ kernel com este código inserido nele daqui a cinco ou dez anos? Muitas das
+ mudanças que podem lhe pedir para fazer — desde ajustes de estilo de código
+ até reescritas substanciais — vêm do entendimento de que o Linux ainda estará
+ por aqui e sob desenvolvimento daqui a uma década.
+
+* A revisão de código é um trabalho árduo e uma ocupação relativamente
+ ingrata; as pessoas lembram quem escreveu o código do kernel, mas há pouca
+ fama duradoura para aqueles que o revisaram. Portanto, os revisores podem
+ ficar ranzinzas, especialmente quando veem os mesmos erros sendo cometidos
+ repetidamente. Se você receber uma revisão que pareça irritada, insultuosa
+ ou abertamente ofensiva, resista ao impulso de responder à altura. A revisão
+ de código diz respeito ao código, não às pessoas, e os revisores de código
+ não estão atacando você pessoalmente.
+
+* Da mesma forma, os revisores de código não estão tentando promover os
+ interesses de seus empregadores em detrimento dos seus. Os desenvolvedores
+ do kernel geralmente esperam continuar trabalhando no kernel daqui a muitos
+ anos, mas entendem que seu empregador pode mudar. Quase sem exceção, eles
+ estão verdadeiramente trabalhando em prol da criação do melhor kernel possível;
+ eles não estão tentando causar desconforto aos concorrentes de seus empregadores.
+
+* Esteja preparado para solicitações aparentemente tolas de mudanças no estilo
+ de codificação e pedidos para refatorar parte do seu código em seções
+ compartilhadas do kernel. Uma das funções dos mantenedores é manter as coisas
+ com a mesma aparência. Às vezes, isso significa que aquele truque inteligente
+ (*clever hack*) em seu driver para contornar um problema
+
+Note que você não precisa concordar com todas as mudanças sugeridas pelos
+revisores. Se você acredita que o revisor entendeu mal o seu código, explique
+o que realmente está acontecendo. Se tiver uma objeção técnica a uma mudança
+sugerida, descreva-a e justifique a sua solução para o problema. Se as suas
+explicações fizerem sentido, o revisor as aceitará. Contudo, caso a sua
+explicação não seja persuasiva — especialmente se outros começarem a concordar
+com o revisor —, reserve um tempo para repensar as coisas. Pode ser fácil ficar
+ceguificado por sua própria solução para um problema, a ponto de não perceber
+que algo está fundamentalmente errado ou que, talvez, você não esteja sequer
+resolvendo o problema certo.
+
+Andrew Morton sugeriu que todo comentário de revisão que não resulte em uma
+alteração de código deveria, em vez disso, resultar em um comentário adicional
+no próprio código; isso pode ajudar os futuros revisores a evitar as dúvidas
+que surgiram da primeira vez.
+
+Um erro fatal é ignorar os comentários de revisão na esperança de que eles
+desapareçam. Eles não vão desaparecer. Se você reenviar o código sem ter
+respondido aos comentários que recebeu da vez anterior, é provável que descubra
+que os seus patches não vão a lugar nenhum.
+
+Por falar em reenviar código: tenha em mente que os revisores não vão se
+lembrar de todos os detalhes do código que você enviou da última vez. Portanto,
+é sempre uma boa ideia lembrar os revisores dos problemas levantados
+anteriormente e de como você lidou com eles; o registro de alterações
+(*changelog*) do patch é um bom lugar para esse tipo de informação. Os revisores
+não deveriam ter que vasculhar os arquivos das listas de discussão para se
+familiarizarem com o que foi dito na última vez; se você ajudá-los a começar
+com o pé direito, eles estarão de melhor humor quando revisitarem o seu código.
+
+E se você tentou fazer tudo certo e as coisas ainda não estão avançando? A
+maioria das divergências técnicas pode ser resolvida por meio de discussão,
+mas há momentos em que alguém simplesmente precisa tomar uma decisão. Se você
+acredita genuinamente que essa decisão está indo contra você de forma errada,
+você sempre pode tentar recorrer a uma instância superior. Até o momento em
+que este texto foi escrito, essa instância superior costuma ser Andrew Morton.
+Andrew goza de um enorme respeito na comunidade de desenvolvimento do kernel;
+ele frequentemente consegue destravar uma situação que parece desesperadoramente
+bloqueada. Recorrer a Andrew, no entanto, não deve ser feito de ânimo leve e nem
+antes que todas as outras alternativas tenham sido esgotadas. E tenha em mente,
+é claro, que ele também pode não concordar com você.
+
+O que acontece a seguir
+-----------------------
+
+Se um patch for considerado algo bom para ser adicionado ao kernel, e assim
+que a maioria dos problemas de revisão tiver sido resolvida, o próximo passo
+geralmente é a entrada na árvore de um mantenedor de subsistema. Como isso
+funciona varia de um subsistema para o outro; cada mantenedor tem sua própria
+maneira de fazer as coisas. Em particular, pode haver mais de uma árvore — uma,
+talvez, dedicada a patches planejados para a próxima janela de mesclagem
+(*merge window*), e outra para trabalhos de longo prazo.
+
+Para patches que se aplicam a áreas para quais não há uma árvore de subsistema
+óbvia (patches de gerenciamento de memória, por exemplo), a árvore padrão
+geralmente acaba sendo a *-mm*. Patches que afetam múltiplos subsistemas
+também podem acabar passando pela árvore *-mm*.
+
+A inclusão em uma árvore de subsistema pode trazer um nível mais alto de
+visibilidade para um patch. Agora, outros desenvolvedores que trabalham com
+aquela árvore receberão o patch por padrão. As árvores de subsistemas tipicamente
+alimentam a *linux-next* também, tornando seus conteúdos visíveis para a
+comunidade de desenvolvimento como um todo. Neste ponto, há uma boa chance de
+você receber mais comentários de um novo conjunto de revisores; esses
+comentários precisam ser respondidos da mesma forma que na rodada anterior.
+
+O que também pode acontecer neste ponto, dependendo da natureza do seu patch,
+é surgirem conflitos com o trabalho que está sendo feito por outros. No pior
+dos casos, conflitos pesados de patches podem fazer com que alguns trabalhos
+sejam deixados em segundo plano, para que os patches restantes possam ser
+ajustados e mesclados. Outras vezes, a resolução de conflitos envolverá trabalhar
+junto a outros desenvolvedores e, possivelmente, mover alguns patches entre
+árvores para garantir que tudo se aplique de forma limpa. Este trabalho pode ser
+árduo, mas console-se com uma vantagem: antes do surgimento da árvore *linux-next*,
+esses conflitos frequentemente só apareciam durante a janela de mesclagem e
+tinham que ser resolvidos às pressas. Agora eles podem ser resolvidos com calma,
+antes que a janela de mesclagem se abra.
+
+Um belo dia, se tudo correr bem, você fará login e verá que o seu patch foi
+mesclado ao kernel principal (*mainline*). Parabéns! No entanto, assim que a
+comemoração terminar (e você tiver se adicionado ao arquivo MAINTAINERS), vale
+a pena lembrar de um pequeno fato importante: o trabalho ainda não acabou. A
+mesclagem na árvore principal traz os seus próprios desafios.
+
+Para começar, a visibilidade do seu patch aumentou ainda mais. Pode haver
+uma nova rodada de comentários de desenvolvedores que não estavam cientes do
+patch antes. Pode ser tentador ignorá-los, já que não há mais nenhuma dúvida
+sobre a mesclagem do seu código. No entanto, resista a essa tentação; você
+ainda precisa ser receptivo aos desenvolvedores que tiverem dúvidas ou
+sugestões.
+
+Mais importante ainda: a inclusão na árvore principal coloca o seu código
+nas mãos de um grupo muito maior de testadores. Mesmo que você tenha contribuído
+com um driver para um hardware que ainda não está disponível, você se
+surpreenderá com a quantidade de pessoas que compilarão seu código em seus
+próprios kernels. E, logicamente, onde há testadores, haverá relatórios de
+erros (*bug reports*).
+
+O pior tipo de relatório de erro são as regressões (*regressions*). Se o seu
+patch causar uma regressão, você descobrirá uma quantidade desconfortável de
+olhos voltados para você; as regressões precisam ser corrigidas o mais rápido
+possível. Se você não estiver disposto ou for incapaz de corrigir a regressão
+(e ninguém mais fizer isso por você), seu patch quase certamente será removido
+durante o período de estabilização. Além de anular todo o trabalho que você teve
+para colocar seu patch na árvore principal, ter um patch removido como resultado
+da falha em corrigir uma regressão pode muito bem tornar mais difícil para você
+mesclar trabalhos no futuro.
+
+Depois que todas as regressões tiverem sido tratadas, pode haver outros erros
+comuns com os quais lidar. O período de estabilização é a sua melhor oportunidade
+para corrigir esses problemas e garantir que a estreia do seu código em um
+lançamento do kernel principal seja o mais sólida possível. Portanto, por favor,
+responda aos relatórios de erros e corrija os problemas, se for viável. É para
+isso que serve o período de estabilização; você pode começar a criar novos
+patches fantásticos assim que quaisquer problemas com os antigos tiverem sido
+resolvidos.
+
+E não se esqueça de que existem outros marcos que também podem gerar relatórios
+de erros: o próximo lançamento estável da árvore principal, o momento em que
+distribuidores proeminentes adotarem uma versão do kernel que contenha o seu
+patch, etc. Continuar respondendo a esses relatórios é uma questão de orgulho
+básico pelo seu trabalho. Se isso não for motivação suficiente, contudo, também
+vale a pena considerar que a comunidade de desenvolvimento se lembra dos
+desenvolvedores que perdem o interesse em seu próprio código após a mesclagem.
+A próxima vez que você enviar um patch, eles o avaliarão sob a suposição de
+que você não estará por perto para mantê-lo depois.
+
+
+Outras coisas que podem acontecer
+---------------------------------
+
+Um dia, você poderá abrir o seu cliente de e-mail e ver que alguém lhe enviou
+um patch para o seu código. Afinal, essa é uma das vantagens de ter o seu
+código disponível publicamente. Se você concordar com o patch, poderá encaminhá-lo
+para o mantenedor do subsistema (certifique-se de incluir uma linha ``From:``
+adequada para que a atribuição de autoria esteja correta e adicione a sua
+própria assinatura — *signoff*) ou enviar uma resposta com um ``Acked-by:``
+e deixar que o remetente original o envie para cima.
+
+Se você não concordar com o patch, envie uma resposta educada explicando o
+motivo. Se possível, diga ao autor quais alterações precisam ser feitas para
+que o patch seja aceitável para você. Existe uma certa resistência em mesclar
+patches que sofrem oposição do autor e mantenedor do código, mas isso tem limite.
+Se você for visto como alguém que está bloqueando um bom trabalho sem necessidade,
+esses patches eventualmente seguirão outro fluxo ao seu redor e entrarão na
+árvore principal de qualquer maneira. No kernel do Linux, ninguém tem poder de
+veto absoluto sobre nenhum código. Exceto, talvez, o Linus.
+
+Em ocasiões muito raras, você poderá ver algo completamente diferente: outro
+desenvolvedor envia uma solução diferente para o seu problema. Nesse ponto,
+as chances são de que um dos dois patches não seja mesclado, e o argumento
+"o meu chegou primeiro" não é considerado um argumento técnico convincente.
+Se o patch de outra pessoa deslocar o seu e entrar na árvore principal, existe
+realmente apenas uma maneira de responder: fique satisfeito pelo fato de o seu
+problema ter sido resolvido e siga adiante com o seu trabalho. Ter o próprio
+trabalho deixado de lado dessa maneira pode ser doloroso e desanimador, mas a
+comunidade se lembrará da sua reação muito depois de terem esquecido de quem
+foi o patch que realmente foi mesclado.
diff --git a/Documentation/translations/pt_BR/process/development-process.rst b/Documentation/translations/pt_BR/process/development-process.rst
index e9f04df62..ca86b481a 100644
--- a/Documentation/translations/pt_BR/process/development-process.rst
+++ b/Documentation/translations/pt_BR/process/development-process.rst
@@ -22,3 +22,4 @@ conhecimento profundo de programação de kernel para ser compreendida.
3.Early-stage
4.Coding
5.Posting
+ 6.Followthrough
--
2.47.3
^ permalink raw reply related [flat|nested] 8+ messages in thread* [PATCH v2 2/7] docs: pt_BR: process: translate 7.AdvancedTopics and 8.Conclusion
2026-07-03 17:05 [PATCH v2 0/7] docs: pt_BR: process: translation updates and additions Daniel Pereira
2026-07-03 17:05 ` [PATCH v2 1/7] docs: pt_BR: process: Translate the patch followthrough guide Daniel Pereira
@ 2026-07-03 17:05 ` Daniel Pereira
2026-07-03 17:05 ` [PATCH v2 3/7] docs: pt_BR: Add translation for applying-patches and update index Daniel Pereira
` (4 subsequent siblings)
6 siblings, 0 replies; 8+ messages in thread
From: Daniel Pereira @ 2026-07-03 17:05 UTC (permalink / raw)
To: corbet; +Cc: linux-doc, Daniel Pereira
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=y, Size: 17895 bytes --]
Translate the "Advanced topics" and "Conclusion" sections into Brazilian
Portuguese, creating the 7.AdvancedTopics.rst and 8.Conclusion.rst
documents, and updating development-process.rst to include them.
This translation covers patch management practices with Git, community
guidelines for patch review, and the closing overview of the kernel
development cycle.
Ensure all text conforms to the strict 80-column line length limit
to maintain Sphinx rendering alignment.
Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
.../pt_BR/process/7.AdvancedTopics.rst | 201 ++++++++++++++++++
.../pt_BR/process/8.Conclusion.rst | 73 +++++++
.../pt_BR/process/development-process.rst | 2 +
3 files changed, 276 insertions(+)
create mode 100644 Documentation/translations/pt_BR/process/7.AdvancedTopics.rst
create mode 100644 Documentation/translations/pt_BR/process/8.Conclusion.rst
diff --git a/Documentation/translations/pt_BR/process/7.AdvancedTopics.rst b/Documentation/translations/pt_BR/process/7.AdvancedTopics.rst
new file mode 100644
index 000000000..97466fad1
--- /dev/null
+++ b/Documentation/translations/pt_BR/process/7.AdvancedTopics.rst
@@ -0,0 +1,201 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Tópicos avançados
+=================
+
+Neste ponto, esperamos que você já tenha uma boa noção de como funciona o
+processo de desenvolvimento. No entanto, ainda há mais a aprender! Esta seção
+cobrirá uma série de tópicos que podem ser úteis para desenvolvedores que
+desejam se tornar parte regular do processo de desenvolvimento do kernel Linux.
+
+Gerenciamento de patches com o git
+----------------------------------
+
+O uso de controle de versão distribuído para o kernel começou no início de
+2002, quando Linus começou a testar o aplicativo proprietário BitKeeper.
+Embora o BitKeeper fosse controverso, a abordagem de gerenciamento de versão
+de software que ele incorporava certamente não era. O controle de versão
+distribuído permitiu uma aceleração imediata do projeto de desenvolvimento do
+kernel. Atualmente, existem várias alternativas gratuitas ao BitKeeper. Para o
+bem ou para o mal, o projeto do kernel adotou o git como sua ferramenta de
+escolha.
+
+Gerenciar patches com o git pode facilitar muito a vida do desenvolvedor,
+especialmente à medida que o volume desses patches cresce. O git também tem suas
+pontas soltas e apresenta certos riscos; é uma ferramenta jovem e poderosa que
+ainda está sendo refinada por seus desenvolvedores. Este documento não tentará
+ensinar o leitor a usar o git; isso seria material suficiente para um documento
+longo por si só. Em vez disso, o foco aqui será em como o git se encaixa
+especificamente no processo de desenvolvimento do kernel. Os desenvolvedores
+que desejam se atualizar com o git encontrarão mais informações em:
+
+ https://git-scm.com/
+
+ https://www.kernel.org/pub/software/scm/git/docs/user-manual.html
+
+e em vários tutoriais encontrados na web.
+
+A primeira ordem do dia é ler os sites acima e obter uma compreensão sólida de
+como o git funciona antes de tentar usá-lo para disponibilizar patches para
+outros. Um desenvolvedor que utiliza o git deve ser capaz de obter uma cópia do
+repositório principal, explorar o histórico de revisões, comitar alterações na
+árvore, usar branches, etc. A compreensão das ferramentas do git para a
+reescrita de histórico (como o rebase) também é útil. O git vem com sua própria
+terminologia e conceitos; um novo usuário do git deve saber sobre refs, remote
+branches, o index, fast-forward merges, pushes e pulls, detached HEADs, etc.
+Tudo isso pode ser um pouco intimidante no início, mas os conceitos não são tão
+difíceis de entender com um pouco de estudo.
+
+Usar o git para gerar patches para submissão por e-mail pode ser um bom exercício
+enquanto você se atualiza.
+
+Quando estiver pronto para começar a disponibilizar árvores git para que outros
+possam examinar, você, logicamente, precisará de um servidor a partir do qual um
+pull possa ser feito. Configurar um servidor desse tipo com o git-daemon é
+relativamente simples se você tiver um sistema acessível à internet. Caso
+contrário, sites de hospedagem públicos e gratuitos (o GitHub, por exemplo)
+estão começando a surgir na rede. Desenvolvedores estabelecidos podem obter uma
+conta no kernel.org, mas estas não são fáceis de conseguir; consulte
+https://kernel.org/faq/ para mais informações.
+
+O fluxo de trabalho normal do git envolve o uso de muitas branches. Cada linha
+de desenvolvimento pode ser separada em uma "topic branch" distinta e mantida de
+forma independente. Branches no git são baratas, não há razão para não fazer um
+uso livre delas. E, em qualquer caso, você não deve fazer o seu desenvolvimento
+em nenhuma branch a partir da qual pretenda pedir para que outros deem pull.
+Branches disponíveis publicamente devem ser criadas com cuidado; mescle patches
+de branches de desenvolvimento quando eles estiverem em sua forma final e prontos
+para seguir em frente — não antes.
+
+O git fornece algumas ferramentas poderosas que podem permitir que você
+reescreva o seu histórico de desenvolvimento. Um patch inconveniente (um que
+quebre o bisection, por exemplo, ou que tenha algum outro tipo de bug óbvio)
+pode ser corrigido localmente ou feito desaparecer completamente do histórico.
+Uma série de patches pode ser reescrita como se tivesse sido escrita no topo da
+linha principal de hoje, mesmo que você esteja trabalhando nela há meses. As
+alterações podem ser movidas de forma transparente de uma branch para outra. E
+assim por diante. O uso criterioso da capacidade do git de revisar o histórico
+pode ajudar na criação de conjuntos de patches limpos e com menos problemas.
+
+O uso excessivo dessa capacidade pode levar a outros problemas, no entanto, além
+de uma simples obsessão pela criação do histórico de projeto perfeito. Reescrever
+o histórico reescreverá as alterações contidas nele, transformando uma árvore do
+kernel testada (assim se espera) em uma não testada. Mas, além disso, os
+desenvolvedores não podem colaborar facilmente se não tiverem uma visão
+compartilhada do histórico do projeto; se você reescrever o histórico que outros
+desenvolvedores já deram pull em seus repositórios, tornará a vida deles muito
+mais difícil. Portanto, uma regra prática simples se aplica aqui: o histórico
+que foi exportado para terceiros deve ser visto geralmente como imutável dali em
+diante.
+
+Sendo assim, uma vez que você faz o push de um conjunto de alterações para o seu
+servidor disponível publicamente, essas alterações não devem ser reescritas. O
+git tentará aplicar essa regra se você tentar dar push em alterações que não
+resultem em um fast-forward merge (ou seja, alterações que não compartilham o
+mesmo histórico). É possível anular essa verificação, e pode haver momentos em
+que seja necessário reescrever uma árvore exportada. Mover changesets entre
+árvores para evitar conflitos na linux-next é um exemplo. No entanto, tais ações
+devem ser raras. Esta é uma das razões pelas quais o desenvolvimento deve ser
+feito em branches privadas (que podem ser reescritas, se necessário) e apenas
+movido para branches públicas quando estiver em um estado razoavelmente avançado.
+
+À medida que a linha principal (ou outra árvore na qual um conjunto de
+alterações se baseia) avança, é tentador fazer o merge com essa árvore para
+permanecer na vanguarda. Para uma branch privada, o rebasing pode ser uma maneira
+fácil de acompanhar outra árvore, mas o rebasing não é uma opção uma vez que uma
+árvore é exportada para o mundo. Quando isso acontece, um merge completo deve
+ser feito. Fazer merges ocasionalmente faz todo o sentido, mas merges excessivamente
+frequentes podem poluir o histórico desnecessariamente. A técnica sugerida neste
+caso é fazer merges raramente, e geralmente apenas em release points específicos
+(como um lançamento -rc da linha principal). Se você estiver inseguro sobre
+mudanças específicas, sempre poderá realizar merges de teste em uma branch
+privada. A ferramenta "rerere" do git pode ser útil nessas situações; ela se
+lembra de como os conflitos de merge foram resolvidos para que você não precise
+fazer o mesmo trabalho duas vezes.
+
+Uma das maiores reclamações recorrentes sobre ferramentas como o git é esta: o
+movimento em massa de patches de um repositório para outro torna fácil a
+inclusão de mudanças desaconselháveis que entram na linha principal abaixo do
+radar de revisão. Os desenvolvedores do kernel costumam ficar descontentes quando
+veem esse tipo de coisa acontecer; disponibilizar uma árvore git com patches não
+revisados ou fora do tópico pode afetar a sua capacidade de ter suas árvores
+puxadas no futuro. Citando Linus:
+
+::
+
+ Você pode me enviar patches, mas para eu puxar um patch git de você, eu
+ preciso saber que você sabe o que está fazendo, e preciso ser capaz de
+ confiar nas coisas *sem* ter que ir lá e verificar cada mudança
+ individualmente à mão.
+
+(https://lwn.net/Articles/224135/).
+
+Para evitar esse tipo de situação, certifique-se de que todos os patches
+dentro de uma determinada branch permaneçam estritamente alinhados ao tópico
+associado; uma branch de "correções de drivers" não deveria fazer alterações no
+código central de gerenciamento de memória. E, acima de tudo, não use uma árvore
+git para burlar o processo de revisão. Publique ocasionalmente um resumo da
+árvore na lista de discussão relevante e, quando for o momento certo, solicite
+que a árvore seja incluída na linux-next.
+
+Se e quando outros começarem a enviar patches para inclusão em sua árvore, não
+se esqueça de revisá-los. Certifique-se também de manter as informações corretas
+de autoria; a ferramenta "am" do git faz o melhor que pode a esse respeito, mas
+você pode ter que adicionar uma linha "From:" ao patch se ele tiver sido
+retransmitido a você por terceiros.
+
+Ao solicitar um pull, certifique-se de fornecer todas as informações
+relevantes: onde está a sua árvore, qual branch deve ser puxada e quais
+alterações resultarão do pull. O comando git request-pull pode ser útil a esse
+respeito; ele formatará a solicitação da maneira que outros desenvolvedores
+esperam e também verificará se você se lembrou de dar push nessas alterações
+para o servidor público.
+
+
+Revisão de patches
+------------------
+
+Alguns leitores certamente objetarão a inclusão desta seção em "tópicos
+avançados" sob o argumento de que mesmo desenvolvedores iniciantes do kernel
+deveriam estar revisando patches. É certamente verdade que não há melhor maneira
+de aprender a programar no ambiente do kernel do que examinando o código
+postado por outros. Além disso, revisores estão sempre em falta; ao examinar o
+código, você pode fazer uma contribuição significativa para o processo como um
+todo.
+
+Revisar código pode ser uma perspectiva intimidadora, especialmente para um novo
+desenvolvedor do kernel que pode se sentir nervoso em questionar — em público —
+um código que foi postado por aqueles com mais experiência. No entanto, mesmo o
+código escrito pelos desenvolvedores mais experientes pode ser aprimorado. Talvez
+o melhor conselho para revisores (todos os revisores) seja este: formule os
+comentários de revisão como perguntas em vez de críticas. Perguntar "como o lock
+é liberado neste caminho?" sempre funcionará melhor do que afirmar "o bloqueio
+aqui está errado."
+
+Outra técnica útil em caso de desacordo é pedir que outros se manifestem. Se uma
+discussão chegar a um impasse após algumas trocas de mensagens, peça a opinião
+de outros revisores ou mantenedores. Frequentemente, aqueles que concordam com
+um revisor permanecem em silêncio, a menos que sejam solicitados. A opinião de
+múltiplas pessoas carrega exponencialmente mais peso.
+
+Diferentes desenvolvedores revisarão o código sob diferentes pontos de vista.
+Alguns estão preocupados principalmente com o estilo de codificação e se as
+linhas de código possuem espaços em branco no final (trailing white space).
+Outros se concentrarão principalmente em saber se a alteração implementada pelo
+patch como um todo é algo bom para o kernel ou não. Ainda assim, outros buscarão
+por bloqueios problemáticos, uso excessivo de pilha (stack usage), possíveis
+problemas de segurança, duplicação de código encontrado em outros lugares,
+documentação adequada, efeitos adversos no desempenho, alterações na ABI do
+espaço do usuário (user-space ABI), etc. Todos os tipos de revisão, se levarem a
+um código melhor entrando no kernel, são bem-vindos e valem a pena.
+
+Não há exigência estrita para o uso de tags específicas como ``Reviewed-by``. Na
+verdade, revisões em texto simples são mais informativas e incentivadas mesmo
+quando uma tag é fornecida, por exemplo: "Analisei os aspectos A, B e C deste
+envio e tudo me parece correto." Alguma forma de mensagem de revisão ou resposta
+é obviamente necessária, caso contrário, os mantenedores não saberão que o
+revisor sequer examinou o patch!
+
+Por último, mas não menos importante, a revisão de patches pode se tornar um
+processo negativo, focado em apontar problemas. Por favor, reserve um elogio de
+vez em quando, particularmente para os novatos!
diff --git a/Documentation/translations/pt_BR/process/8.Conclusion.rst b/Documentation/translations/pt_BR/process/8.Conclusion.rst
new file mode 100644
index 000000000..d5af31e7c
--- /dev/null
+++ b/Documentation/translations/pt_BR/process/8.Conclusion.rst
@@ -0,0 +1,73 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Para mais informações
+=====================
+
+Há inúmeras fontes de informação sobre o desenvolvimento do kernel Linux e
+tópicos relacionados. A primeira delas sempre será o diretório Documentation
+encontrado na distribuição do código-fonte do kernel. Comece com o arquivo de
+nível superior :ref:`process/howto.rst <process_howto>`; leia também
+:ref:`process/submitting-patches.rst <submittingpatches>`. Muitas APIs internas
+do kernel são documentadas usando o mecanismo kerneldoc; "make htmldocs" ou
+"make pdfdocs" podem ser usados para gerar esses documentos em formato HTML ou
+PDF (embora a versão do TeX fornecida por algumas distribuições esbarre em
+limites internos e falhe em processar os documentos corretamente).
+
+Vários sites discutem o desenvolvimento do kernel em todos os níveis de
+detalhes. O autor gostaria de sugerir humildemente o https://lwn.net/ como uma
+fonte; informações sobre muitos tópicos específicos do kernel podem ser
+encontradas através do índice do kernel do LWN em:
+
+ https://lwn.net/Kernel/Index/
+
+Além disso, um recurso valioso para os desenvolvedores do kernel é:
+ https://kernelnewbies.org/
+
+E, claro, não se deve esquecer o https://kernel.org/, o local definitivo
+para informações sobre os lançamentos do kernel.
+
+Há uma série de livros sobre o desenvolvimento do kernel:
+
+ Linux Device Drivers, 3rd Edition (Jonathan Corbet, Alessandro
+ Rubini, and Greg Kroah-Hartman). Online at
+ https://lwn.net/Kernel/LDD3/.
+
+ Linux Kernel Development (Robert Love).
+
+ Understanding the Linux Kernel (Daniel Bovet and Marco Cesati).
+
+Todos esses livros, no entanto, sofrem de um defeito comum: eles tendem a estar
+um pouco obsoletos quando chegam às prateleiras, e já estão nelas há algum
+tempo. Ainda assim, há uma boa quantidade de informações úteis a serem
+encontradas ali.
+
+A documentação para o git pode ser encontrada em:
+
+ https://www.kernel.org/pub/software/scm/git/docs/
+
+ https://www.kernel.org/pub/software/scm/git/docs/user-manual.html
+
+
+Conclusão
+=========
+
+Parabéns a qualquer pessoa que tenha chegado ao fim deste documento longo e
+detalhado. Esperamos que ele tenha fornecido uma compreensão útil de como o
+kernel Linux é desenvolvido e de como você pode participar desse processo.
+
+No fim das contas, é a participação que importa. Qualquer projeto de software
+de código aberto não é nada mais do que a soma do que seus colaboradores
+dedicam a ele. O kernel Linux progrediu tão rápido e tão bem porque foi ajudado
+por um grupo impressionantemente grande de desenvolvedores, todos trabalhando
+para torná-lo melhor. O kernel é um exemplo primordial do que pode ser feito
+quando milhares de pessoas trabalham juntas em direção a um objetivo comum.
+
+O kernel, no entanto, sempre pode se beneficiar de uma base maior de
+desenvolvedores. Há sempre mais trabalho a fazer. Mas, de forma igualmente
+importante, a maioria dos outros participantes do ecossistema Linux pode se
+beneficiar ao contribuir para o kernel. Colocar o código na linha principal
+(mainline) é a chave para uma maior qualidade de código, menores custos de
+manutenção e distribuição, um nível mais alto de influência sobre a direção do
+desenvolvimento do kernel e muito mais. É uma situação em que todos os
+envolvidos ganham. Abra o seu editor e venha se juntar a nós; você será mais do
+que bem-vindo.
diff --git a/Documentation/translations/pt_BR/process/development-process.rst b/Documentation/translations/pt_BR/process/development-process.rst
index ca86b481a..d303ab92b 100644
--- a/Documentation/translations/pt_BR/process/development-process.rst
+++ b/Documentation/translations/pt_BR/process/development-process.rst
@@ -23,3 +23,5 @@ conhecimento profundo de programação de kernel para ser compreendida.
4.Coding
5.Posting
6.Followthrough
+ 7.AdvancedTopics
+ 8.Conclusion
--
2.47.3
^ permalink raw reply related [flat|nested] 8+ messages in thread* [PATCH v2 3/7] docs: pt_BR: Add translation for applying-patches and update index
2026-07-03 17:05 [PATCH v2 0/7] docs: pt_BR: process: translation updates and additions Daniel Pereira
2026-07-03 17:05 ` [PATCH v2 1/7] docs: pt_BR: process: Translate the patch followthrough guide Daniel Pereira
2026-07-03 17:05 ` [PATCH v2 2/7] docs: pt_BR: process: translate 7.AdvancedTopics and 8.Conclusion Daniel Pereira
@ 2026-07-03 17:05 ` Daniel Pereira
2026-07-03 17:05 ` [PATCH v2 4/7] docs: pt_BR: translate backporting.rst documentation Daniel Pereira
` (3 subsequent siblings)
6 siblings, 0 replies; 8+ messages in thread
From: Daniel Pereira @ 2026-07-03 17:05 UTC (permalink / raw)
To: corbet; +Cc: linux-doc, Daniel Pereira
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=y, Size: 22184 bytes --]
Translate the 'applying-patches' documentation into Brazilian Portuguese,
ensuring alignment with the upstream structural guidelines.
Additionally, add the translated document to the main process index
toctree to integrate it into the documentation build tree.
Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
Documentation/translations/pt_BR/index.rst | 1 +
.../pt_BR/process/applying-patches.rst | 447 ++++++++++++++++++
2 files changed, 448 insertions(+)
create mode 100644 Documentation/translations/pt_BR/process/applying-patches.rst
diff --git a/Documentation/translations/pt_BR/index.rst b/Documentation/translations/pt_BR/index.rst
index 7a488f662..555bf1d3a 100644
--- a/Documentation/translations/pt_BR/index.rst
+++ b/Documentation/translations/pt_BR/index.rst
@@ -68,6 +68,7 @@ kernel e sobre como ver seu trabalho integrado.
Introdução <process/1.Intro>
Guia do Processo de Desenvolvimento <process/development-process>
+ Como aplicar patches <process/applying-patches>
Index de documentos do Kernel <process/kernel-docs>
Regras de licenciamento <process/license-rules>
Como começar <process/howto>
diff --git a/Documentation/translations/pt_BR/process/applying-patches.rst b/Documentation/translations/pt_BR/process/applying-patches.rst
new file mode 100644
index 000000000..313401bc2
--- /dev/null
+++ b/Documentation/translations/pt_BR/process/applying-patches.rst
@@ -0,0 +1,447 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Aplicando Patches ao Kernel Linux
++++++++++++++++++++++++++++++++++
+
+Autor Original:
+ Jesper Juhl, Agosto de 2005
+
+.. note::
+
+ Este documento está obsoleto. Na maioria dos casos, em vez de usar ``patch``
+ manualmente, você quase certamente desejará considerar o uso do Git.
+
+Uma pergunta feita com frequência na Linux Kernel Mailing List é como aplicar
+an patch ao kernel ou, mais especificamente, a qual kernel base um patch para
+uma das muitas árvores/branches deve ser aplicado. Esperamos que este documento
+explique isso a você.
+
+Além de explicar como aplicar e reverter patches, uma breve descrição das
+diferentes árvores do kernel (e exemplos de como aplicar seus patches
+específicos) também é fornecida.
+
+
+O que é um Patch?
+=================
+
+Um patch é um pequeno documento de texto que contém uma diferença (delta) de
+alterações entre duas versões diferentes de uma árvore de código-fonte. Os
+patches são criados com o programa ``diff``.
+
+Para aplicar um patch corretamente, você precisa saber de qual base ele foi
+gerado e em qual nova versão o patch transformará a árvore de código-fonte.
+Ambas as informações devem estar presentes nos metadados do arquivo de patch
+ou ser possíveis de deduzir a partir do nome do arquivo.
+
+
+Como eu aplico ou reverto um patch?
+===================================
+
+Você aplica um patch com o programa ``patch``. O programa patch lê um arquivo
+de diff (ou patch) e faz as alterações descritas nele na árvore de
+código-fonte.
+
+Os patches para o kernel Linux são gerados relativamente ao diretório pai que
+contém o diretório do código-fonte do kernel.
+
+Isso significa que os caminhos para os arquivos dentro do arquivo de patch
+contêm o nome dos diretórios do código-fonte do kernel contra os quais ele foi
+gerado (ou alguns outros nomes de diretório como "a/" e "b/").
+
+Como é improvável que isso corresponda ao nome do diretório do código-fonte do
+kernel na sua máquina local (mas frequentemente é uma informação útil para ver
+contra qual versão um patch sem identificação foi gerado), você deve entrar no
+seu diretório de código-fonte do kernel e, em seguida, remover o primeiro
+elemento do caminho dos nomes de arquivos no arquivo de patch ao aplicá-lo (o
+argumento ``-p1`` para o ``patch`` faz isso).
+
+Para reverter um patch aplicado anteriormente, use o argumento -R para o patch.
+Portanto, se você aplicou um patch desta forma::
+
+ patch -p1 < ../patch-x.y.z
+
+Você pode revertê-lo (desfazê-lo) assim::
+
+ patch -R -p1 < ../patch-x.y.z
+
+
+Como eu passo um arquivo de patch/diff para o ``patch``?
+========================================================
+
+Isso (como de costume no Linux e em outros sistemas operacionais do tipo UNIX)
+pode ser feito de várias maneiras diferentes.
+
+Em todos os exemplos abaixo, eu passo o arquivo (em formato não compactado) para
+o patch via stdin usando a seguinte sintaxe::
+
+ patch -p1 < path/to/patch-x.y.z
+
+Se você quer apenas ser capaz de seguir os exemplos abaixo e não deseja
+conhecer mais do que uma maneira de usar o patch, então você pode parar a
+leitura desta seção aqui.
+
+O patch também pode receber o nome do arquivo a ser usado através do argumento
+-i, desta forma::
+
+ patch -p1 -i path/to/patch-x.y.z
+
+Se o seu arquivo de patch estiver compactado com gzip ou xz e você não quiser
+descompactá-lo antes de aplicá-lo, você pode passá-lo para o patch desta outra
+forma::
+
+ xzcat path/to/patch-x.y.z.xz | patch -p1
+ bzcat path/to/patch-x.y.z.gz | patch -p1
+
+Se você deseja descompactar o arquivo de patch manualmente primeiro antes de
+aplicá-lo (o que presumo que você tenha feito nos exemplos abaixo), basta
+executar gunzip ou xz no arquivo -- desta forma::
+
+ gunzip patch-x.y.z.gz
+ xz -d patch-x.y.z.xz
+
+O que deixará você com um arquivo patch-x.y.z em texto puro que você pode
+passar para o patch via stdin ou pelo argumento ``-i``, conforme sua preferência.
+
+Alguns outros argumentos úteis para o patch são ``-s``, que faz com que o patch
+seja silencioso (exceto por erros), o que é bom para evitar que erros sumam da
+tela rolando rápido demais; e ``--dry-run``, que faz com que o patch apenas
+imprima uma lista do que aconteceria, mas sem realizar nenhuma alteração de
+fato. Por fim, ``--verbose`` diz ao patch para imprimir mais informações sobre o
+trabalho que está sendo realizado.
+
+
+Erros comuns ao aplicar patches
+===============================
+
+Quando o patch aplica um arquivo de patch, ele tenta verificar a integridade do
+arquivo de diferentes maneiras.
+
+Verificar se o arquivo parece um arquivo de patch válido e checar se o código ao
+redor dos trechos sendo modificados corresponde ao contexto fornecido no patch
+são apenas duas das verificações básicas de integridade que o patch faz.
+
+Se o patch encontrar algo que não pareça totalmente correto, ele tem duas
+opções. Ele pode se recusar a aplicar as alterações e abortar, ou pode tentar
+encontrar uma maneira de fazer o patch ser aplicado com algumas pequenas
+alterações.
+
+Um exemplo de algo que não está "totalmente correto" e que o patch tentará
+corrigir é se todo o contexto coincidir, as linhas sendo alteradas coincidirem,
+mas os números das linhas forem diferentes. Isso pode acontecer, por exemplo, se
+o patch fizer uma alteração no meio do arquivo, mas, por algum motivo, algumas
+linhas tiverem sido adicionadas ou removidas perto do início do arquivo. Nesse
+caso, tudo parece correto, apenas mudou um pouco para cima ou para baixo, e o
+patch geralmente ajustará os números das linhas e aplicará o patch.
+
+Sempre que o patch aplicar um patch que ele teve de modificar um pouco para
+fazer caber, ele avisará você dizendo que o patch foi aplicado com **fuzz**.
+Você deve ser cauteloso com tais alterações porque, embora o patch
+provavelmente tenha acertado, ele nem /sempre/ acerta, e o resultado às vezes
+será incorreto.
+
+Quando o patch encontra uma alteração que não consegue corrigir com fuzz, ele a
+rejeita imediatamente e deixa um arquivo com a extensão ``.rej`` (um arquivo de
+rejeição). Você pode ler esse arquivo para ver exatamente qual alteração não
+pôde ser aplicada, para que possa corrigi-la manualmente, se desejar.
+
+Se você não tem nenhum patch de terceiros aplicado ao seu código-fonte do
+kernel, mas apenas patches do kernel.org, e você aplica os patches na ordem
+correta, e não fez nenhuma modificação por conta própria nos arquivos de
+origem, então você nunca deveria ver uma mensagem de fuzz ou de rejeição (reject)
+do patch. Se você ainda assim vir tais mensagens, então há um alto risco de que
+sua árvore de código-fonte local ou o arquivo de patch estejam corrompidos de
+alguma forma. Nesse caso, você provavelmente deveria tentar baixar o patch
+novamente e, se as coisas ainda não estiverem certas, aconselha-se começar com
+uma árvore limpa baixada na íntegra do kernel.org.
+
+Vamos examinar um pouco mais algumas das mensagens que o patch pode produzir.
+
+Se o patch parar e apresentar um prompt ``File to patch:``, então o patch não
+conseguiu encontrar um arquivo para ser modificado. O mais provável é que você
+tenha esquecido de especificar -p1 ou esteja no diretório errado. Com menos
+frequência, você encontrará patches que precisam ser aplicados com ``-p0`` em
+vez de ``-p1`` (a leitura do arquivo de patch deve revelar se este é o caso -- se
+for, isso é um erro da pessoa que criou o patch, mas não é fatal).
+
+Se você receber ``Hunk #2 succeeded at 1887 with fuzz 2 (offset 7 lines).`` ou
+uma mensagem semelhante a essa, significa que o patch teve que ajustar o local
+da alteração (neste exemplo, ele precisou se mover 7 linhas de onde esperava
+fazer a alteração para fazê-la caber).
+
+O arquivo resultante pode ou não estar correto, dependendo do motivo pelo qual o
+arquivo estava diferente do esperado.
+
+Isso geralmente acontece se você tentar aplicar un patch que foi gerado contra uma
+versão de kernel diferente daquela que você está tentando modificar.
+
+Se você receber uma mensagem como ``Hunk #3 FAILED at 2387.``, significa que o
+patch não pôde ser aplicado corretamente e o programa patch não foi capaz de
+encontrar um caminho usando o fuzz. Isso gerará um arquivo ``.rej`` com a
+alteração que fez o patch falhar e também um arquivo ``.orig`` mostrando o
+conteúdo original que não pôde ser alterado.
+
+Se você receber ``Reversed (or previously applied) patch detected! Assume -R? [n]``
+então o patch detectou que a alteração contida no patch parece já ter sido feita.
+
+Se você realmente aplicou este patch anteriormente e apenas o reaplicou por erro,
+basta dizer [n]ão (n) e abortar este patch. Se você aplicou este patch
+anteriormente e realmente pretendia revertê-lo, mas esqueceu de especificar -R,
+você pode dizer [**y**]es (sim) aqui para fazer o patch revertê-lo para você.
+
+Isso também pode acontecer se o criador do patch inverteu os diretórios de
+origem e destino ao criar o patch e, nesse caso, reverter o patch irá, na
+verdade, aplicá-lo.
+
+Uma mensagem semelhante a ``patch: **** unexpected end of file in patch`` ou
+``patch unexpectedly ends in middle of line`` significa que o patch não conseguiu
+fazer sentido do arquivo que você passou para ele. Ou o seu download está
+quebrado, ou você tentou passar para o patch um arquivo de patch compactado sem
+descompactá-lo primeiro, ou o arquivo de patch que você está usando foi alterado
+por um cliente de e-mail ou agente de transferência de e-mail em algum lugar pelo
+caminho, por exemplo, dividindo uma linha longa em duas linhas. Frequentemente,
+esses avisos podem ser corrigidos facilmente juntando (concatenando) as duas
+linhas que foram divididas.
+
+Como já mencionei acima, esses erros nunca deveriam acontecer se você aplicar um
+patch do kernel.org na versão correta de uma árvore de código-fonte não
+modificada. Portanto, se você obtiver esses erros com patches do kernel.org,
+você provavelmente deve assumir que o seu arquivo de patch ou a sua árvore está
+quebrada, e eu o aconselharia a recomeçar com um download limpo de uma árvore
+completa do kernel e do patch que deseja aplicar.
+
+Existem alternativas ao ``patch``?
+==================================
+
+Sim, existem alternativas.
+
+Você pode usar o programa ``interdiff`` (http://cyberelk.net/tim/patchutils/) para
+gerar um patch que represente as diferenças entre dois patches e, em seguida,
+aplicar o resultado.
+
+Isso permitirá que você passe de algo como 5.7.2 para 5.7.3 em um único
+passo. A flag -z do interdiff permite até mesmo passar patches em formato
+compactado com gzip ou bzip2 diretamente, sem o uso de zcat, bzcat ou
+descompactação manual.
+
+Aqui está como você passaria de 5.7.2 para 5.7.3 em um único passo::
+
+ interdiff -z ../patch-5.7.2.gz ../patch-5.7.3.gz | patch -p1
+
+Embora o interdiff possa economizar um ou dois passos, geralmente recomenda-se
+realizar os passos adicionais, já que o interdiff pode errar em alguns casos.
+
+Outra alternativa é o ``ketchup``, que é um script em python para download e
+aplicação automática de patches (https://www.selenic.com/ketchup/).
+
+Outras ferramentas úteis são o diffstat, que mostra um resumo das alterações
+feitas por um patch; o lsdiff, que exibe uma lista curta dos arquivos afetados
+em um arquivo de patch, junto com (opcionalmente) os números das linhas de
+início de cada patch; e o grepdiff, que exibe uma lista dos arquivos modificados
+por um patch onde o patch contém uma determinada expressão regular.
+
+
+Onde posso baixar os patches?
+=============================
+
+Os patches estão disponíveis em https://kernel.org/
+Os patches mais recentes estão vinculados na página principal, mas eles também
+possuem locais específicos.
+
+Os patches 5.x.y (-stable) e 5.x residem em
+
+ https://www.kernel.org/pub/linux/kernel/v5.x/
+
+Os patches incrementais 5.x.y residem em
+
+ https://www.kernel.org/pub/linux/kernel/v5.x/incr/
+
+Os patches -rc não são armazenados no servidor web, mas são gerados sob
+demanda a partir de tags do git, tais como
+
+ https://git.kernel.org/torvalds/p/v5.1-rc1/v5.0
+
+Os patches estáveis -rc residem em
+
+ https://www.kernel.org/pub/linux/kernel/v5.x/stable-review/
+
+
+Os kernels 5.x
+==============
+
+Estes são os lançamentos estáveis base publicados por Linus. O lançamento com o
+número mais alto é o mais recente.
+
+Se regressões ou outras falhas graves forem encontradas, um patch de correção
+-stable será lançado (veja abaixo) sobre esta base. Assim que um novo kernel
+base 5.x é lançado, um patch é disponibilizado contendo o delta entre o kernel
+5.x anterior e o novo.
+
+Para aplicar um patch mudando da versão 5.6 para a 5.7, você faria o seguinte
+(note que tais patches **NÃO** se aplicam sobre kernels 5.x.y, mas sim sobre o
+kernel base 5.x -- se você precisar mudar de 5.x.y para 5.x+1, você deve
+primeiro reverter o patch do 5.x.y).
+
+Aqui estão alguns exemplos::
+
+ # mudando de 5.6 para 5.7
+
+ $ cd ~/linux-5.6 # muda para o dir do fonte do kernel
+ $ patch -p1 < ../patch-5.7 # aplica o patch do 5.7
+ $ cd ..
+ $ mv linux-5.6 linux-5.7 # renomeia o dir do fonte
+
+ # mudando de 5.6.1 para 5.7
+
+ $ cd ~/linux-5.6.1 # muda para o dir do fonte do kernel
+ $ patch -p1 -R < ../patch-5.6.1 # reverte o patch do 5.6.1
+ # o dir do fonte agora é o 5.6
+ $ patch -p1 < ../patch-5.7 # aplica o novo patch do 5.7
+ $ cd ..
+ $ mv linux-5.6.1 linux-5.7 # renomeia o dir do fonte
+
+Os kernels 5.x.y
+================
+
+Kernels com versões de 3 dígitos são kernels -stable (estáveis). Eles contêm
+correções críticas relativamente pequenas para problemas de segurança ou
+regressões significativas descobertas em um determinado kernel 5.x.
+
+Esta é a ramificação recomendada para usuários que desejam o kernel estável mais
+recente e não estão interessados em ajudar a testar versões de desenvolvimento
+ou experimentais.
+
+Se nenhum kernel 5.x.y estiver disponível, então o kernel 5.x com o número mais
+alto será o atual kernel estável.
+
+A equipe -stable fornece patches normais, bem como incrementais. Abaixo está
+como aplicar esses patches.
+
+Patches normais
+~~~~~~~~~~~~~~~
+
+Estes patches não são incrementais, o que significa que, por exemplo, o patch
+5.7.3 não se aplica sobre o código-fonte do kernel 5.7.2, mas sim sobre o
+código-fonte do kernel base 5.7.
+
+Portanto, para aplicar o patch 5.7.3 ao seu código-fonte existente do kernel
+5.7.2, você deve primeiro remover o patch 5.7.2 (de modo que reste apenas o
+código-fonte do kernel base 5.7) e então aplicar o novo patch 5.7.3.
+
+Aqui está um pequeno exemplo::
+
+ $ cd ~/linux-5.7.2 # muda para o dir do fonte do kernel
+ $ patch -p1 -R < ../patch-5.7.2 # reverte o patch do 5.7.2
+ $ patch -p1 < ../patch-5.7.3 # aplica o novo patch do 5.7.3
+ $ cd ..
+ $ mv linux-5.7.2 linux-5.7.3 # renomeia o dir do fonte do kernel
+
+Patches incrementais
+~~~~~~~~~~~~~~~~~~~~
+
+Os patches incrementais são diferentes: em vez de serem aplicados sobre o kernel
+base 5.x, eles são aplicados sobre o kernel estável anterior (5.x.y-1).
+
+Aqui está o exemplo para aplicar estes::
+
+ $ cd ~/linux-5.7.2 # muda para o dir do fonte do kernel
+ $ patch -p1 < ../patch-5.7.2-3 # aplica o novo patch do 5.7.3
+ $ cd ..
+ $ mv linux-5.7.2 linux-5.7.3 # renomeia o dir do fonte do kernel
+
+
+Os kernels -rc
+==============
+
+Estes são os kernels candidatos a lançamento (release-candidate). São kernels
+de desenvolvimento publicados por Linus sempre que ele considera que a árvore
+atual do git (a ferramenta de gerenciamento de código-fonte do kernel) está em
+um estado razoavelmente íntegro e adequado para testes.
+
+Estes kernels não são estáveis e você deve esperar quebras ocasionais se pretender
+executá-los. Esta é, no entanto, a mais estável das principais ramificações de
+desenvolvimento e é também o que eventualmente se tornará o próximo kernel
+estável, por isso é importante que seja testado pelo maior número possível de
+pessoas.
+
+Esta é uma boa ramificação para pessoas que querem ajudar a testar kernels de
+desenvolvimento, mas não querem executar algumas das coisas realmente
+experimentais (essas pessoas devem ver as seções sobre os kernels -next e -mm
+abaixo).
+
+Os patches -rc não são incrementais; eles se aplicam a um kernel base 5.x, assim
+como os patches 5.x.y descritos acima. A versão do kernel antes do sufixo -rcN
+indica a versão do kernel na qual este kernel -rc eventualmente se tornará.
+
+Portanto, 5.8-rc5 significa que este é o quinto candidato a lançamento para o
+kernel 5.8 e o patch deve ser aplicado sobre o código-fonte do kernel 5.7.
+
+Aqui estão 3 exemplos de como aplicar esses patches::
+
+ # primeiro, um exemplo de mudança do 5.7 para o 5.8-rc3
+
+ $ cd ~/linux-5.7 # muda para o dir do fonte do 5.7
+ $ patch -p1 < ../patch-5.8-rc3 # aplica o patch do 5.8-rc3
+ $ cd ..
+ $ mv linux-5.7 linux-5.8-rc3 # renomeia o dir do fonte
+
+ # agora vamos mudar do 5.8-rc3 para o 5.8-rc5
+
+ $ cd ~/linux-5.8-rc3 # muda para o dir do 5.8-rc3
+ $ patch -p1 -R < ../patch-5.8-rc3 # reverte o patch do 5.8-rc3
+ $ patch -p1 < ../patch-5.8-rc5 # aplica o novo patch do 5.8-rc5
+ $ cd ..
+ $ mv linux-5.8-rc3 linux-5.8-rc5 # renomeia o dir do fonte
+
+ # por fim, vamos tentar mudar do 5.7.3 para o 5.8-rc5
+
+ $ cd ~/linux-5.7.3 # muda para o dir do fonte do kernel
+ $ patch -p1 -R < ../patch-5.7.3 # reverte o patch do 5.7.3
+ $ patch -p1 < ../patch-5.8-rc5 # aplica o novo patch do 5.8-rc5
+ $ cd ..
+ $ mv linux-5.7.3 linux-5.8-rc5 # renomeia o dir do fonte do kernel
+
+
+Os patches -mm e a árvore linux-next
+====================================
+
+Os patches -mm são patches experimentais publicados por Andrew Morton.
+
+No passado, a árvore -mm também era usada para testar patches de subsistemas,
+mas essa função agora é realizada por meio da árvore
+`linux-next` (https://www.kernel.org/doc/man-pages/linux-next.html).
+Os mantenedores de subsistemas enviam seus patches primeiro para a linux-next e,
+durante a janela de mesclagem (merge window), enviam-nos diretamente para Linus.
+
+Os patches -mm servem como uma espécie de campo de testes para novos recursos e
+outros patches experimentais que não são mesclados por meio de uma árvore de
+subsistema. Assim que tais patches provam seu valor na -mm por um tempo, Andrew
+os envia para Linus para inclusão na linha principal (mainline).
+
+A árvore linux-next é atualizada diariamente e inclui os patches -mm. Ambas
+estão em constante fluxo e contêm muitos recursos experimentais, uma grande
+quantidade de patches de depuração (debugging) não apropriados para a linha
+principal etc., sendo as mais experimentais das ramificações descritas neste
+documento.
+
+Estes patches não são apropriados para uso em sistemas que devem ser estáveis e
+são mais arriscados de executar do que qualquer uma das outras ramificações
+(certifique-se de ter backups atualizados -- isso vale para qualquer kernel
+experimental, mas ainda mais para patches -mm ou ao usar um kernel da árvore
+linux-next).
+
+O teste dos patches -mm e da linux-next é imensamente apreciado, pois todo o
+objetivo deles é eliminar regressões, travamentos (crashes), bugs de corrupção
+de dados, quebras de compilação (e qualquer outro bug em geral) antes que as
+alterações sejam mescladas na árvore principal do Linus, que é mais estável.
+
+Mas os testadores da -mm e da linux-next devem estar cientes de que quebras são
+mais comuns do que em qualquer outra árvore.
+
+
+Isso conclui esta lista de explicações sobre as várias árvores do kernel.
+Espero que agora você tenha clareza sobre como aplicar os vários patches e
+ajudar a testar o kernel.
+
+Agradecimentos a Randy Dunlap, Rolf Eike Beer, Linus Torvalds, Bodo Eggert,
+Johannes Stezenbach, Grant Coady, Pavel Machek e outros que posso ter esquecido
+por suas revisões e contribuições para este documento.
\ No newline at end of file
--
2.47.3
^ permalink raw reply related [flat|nested] 8+ messages in thread* [PATCH v2 4/7] docs: pt_BR: translate backporting.rst documentation
2026-07-03 17:05 [PATCH v2 0/7] docs: pt_BR: process: translation updates and additions Daniel Pereira
` (2 preceding siblings ...)
2026-07-03 17:05 ` [PATCH v2 3/7] docs: pt_BR: Add translation for applying-patches and update index Daniel Pereira
@ 2026-07-03 17:05 ` Daniel Pereira
2026-07-03 17:05 ` [PATCH v2 5/7] docs: pt_BR: process: translate botching-up-ioctls guide Daniel Pereira
` (2 subsequent siblings)
6 siblings, 0 replies; 8+ messages in thread
From: Daniel Pereira @ 2026-07-03 17:05 UTC (permalink / raw)
To: corbet; +Cc: linux-doc, Daniel Pereira
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=y, Size: 31614 bytes --]
Translate the 'backporting' guide into Brazilian Portuguese, ensuring
strict alignment with the upstream content and structure.
The translation covers conflict resolution strategies, understanding git
conflict markers, and the process of submitting backports to the stable
kernel tree.
Additionally, maintain the strict 80-column line length limit across
the entire file to ensure proper Sphinx rendering.
Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
Documentation/translations/pt_BR/index.rst | 1 +
.../pt_BR/process/backporting.rst | 598 ++++++++++++++++++
2 files changed, 599 insertions(+)
create mode 100644 Documentation/translations/pt_BR/process/backporting.rst
diff --git a/Documentation/translations/pt_BR/index.rst b/Documentation/translations/pt_BR/index.rst
index 555bf1d3a..08faaacf3 100644
--- a/Documentation/translations/pt_BR/index.rst
+++ b/Documentation/translations/pt_BR/index.rst
@@ -69,6 +69,7 @@ kernel e sobre como ver seu trabalho integrado.
Introdução <process/1.Intro>
Guia do Processo de Desenvolvimento <process/development-process>
Como aplicar patches <process/applying-patches>
+ Backporting e resolução de conflitos <process/backporting>
Index de documentos do Kernel <process/kernel-docs>
Regras de licenciamento <process/license-rules>
Como começar <process/howto>
diff --git a/Documentation/translations/pt_BR/process/backporting.rst b/Documentation/translations/pt_BR/process/backporting.rst
new file mode 100644
index 000000000..ce3f9fb4f
--- /dev/null
+++ b/Documentation/translations/pt_BR/process/backporting.rst
@@ -0,0 +1,598 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================================
+Backporting e resolução de conflitos
+====================================
+
+:Autor: Vegard Nossum <vegard.nossum@oracle.com>
+
+.. contents::
+ :local:
+ :depth: 3
+ :backlinks: none
+
+Introdução
+==========
+
+Alguns desenvolvedores podem nunca precisar lidar de fato com backporting de
+patches, mesclagem de ramificações (branches) ou resolução de conflitos em seu
+trabalho diário, portanto, quando um conflito de mesclagem aparece, pode ser
+assustador. Felizmente, resolver conflitos é uma habilidade como qualquer outra,
+e existem muitas técnicas úteis que você pode usar para tornar o processo mais
+suave e aumentar sua confiança no resultado.
+
+Este documento tem como objetivo ser um guia abrangente e passo a passo para
+backporting e resolução de conflitos.
+
+Aplicando o patch a uma árvore
+==============================
+
+Às vezes, o patch que você está fazendo backport já existe como um commit do
+git, caso em que você apenas faz o cherry-pick dele diretamente usando
+``git cherry-pick``. No entanto, se o patch vier de um e-mail, como costuma
+acontecer no caso do kernel Linux, você precisará aplicá-lo a uma árvore usando
+``git am``.
+
+Se você já usou o ``git am``, provavelmente já sabe que ele é bastante exigente
+sobre o patch ser aplicado perfeitamente à sua árvore de código-fonte. Na
+verdade, você provavelmente já teve pesadelos com arquivos ``.rej`` e tentando
+editar o patch para fazê-lo ser aplicado.
+
+Recomenda-se fortemente, em vez disso, encontrar uma versão base apropriada onde
+o patch se aplique de forma limpa e *então* fazer o cherry-pick dele para a sua
+árvore de destino, pois isso fará com que o git exiba marcadores de conflito e
+permitirá que você resolva os conflitos com a ajuda do git e de quaisquer outras
+ferramentas de resolução de conflitos que preferir usar. Por exemplo, se você
+quiser aplicar um patch que acabou de chegar na LKML a um kernel estável mais
+antigo, você pode aplicá-lo ao kernel principal (mainline) mais recente e, em
+seguida, fazer o cherry-pick dele para a sua ramificação estável mais antiga.
+
+Geralmente é melhor usar exatamente a mesma base a partir da qual o patch foi
+gerado, mas isso não importa tanto, desde que ele se aplique de forma limpa e
+não esteja muito longe da base original. O único problema ao aplicar o patch na
+base "errada" é que isso pode trazer mais alterações não relacionadas no
+contexto do diff ao fazer o cherry-pick dele para a ramificação mais antiga.
+
+Um bom motivo para preferir o ``git cherry-pick`` em vez do ``git am`` é que o
+git conhece o histórico preciso de um commit existente, de modo que ele saberá
+quando o código foi movido de lugar e teve seus números de linha alterados; isso,
+por sua vez, torna menos provável que o patch seja aplicado no lugar errado (o
+que pode resultar em erros silenciosos ou conflitos confusos).
+
+Se você estiver usando o `b4`_. e estiver aplicando o patch diretamente de um
+e-mail, você pode usar o ``b4 am`` com as opções ``-g``/``--guess-base`` e
+``-3``/``--prep-3way`` para fazer parte disso automaticamente (veja a
+`apresentação do b4`_ para mais informações). No entanto, o restante deste
+artigo assumirá que você está fazendo um ``git cherry-pick`` simples.
+
+.. _b4: https://people.kernel.org/monsieuricon/introducing-b4-and-patch-attestation
+.. _apresentação do b4: https://youtu.be/mF10hgVIx9o?t=2996
+
+Assim que tiver o patch no git, você pode prosseguir e fazer o cherry-pick dele
+em sua árvore de código-fonte. Não se esqueça de fazer o cherry-pick com ``-x``
+se quiser um registro por escrito de onde o patch veio!
+
+Note que, se você estiver enviando um patch para a ramificação estável (stable),
+o formato é ligeiramente diferente; a primeira linha após a linha de assunto
+precisa ser::
+
+ commit <upstream commit> upstream
+
+ou::
+
+ [ Upstream commit <upstream commit> ]
+
+Resolvendo conflitos
+====================
+
+Ih, rapaz; o cherry-pick falhou com uma mensagem vagamente ameaçadora::
+
+ CONFLICT (content): Merge conflict
+
+O que fazer agora?
+
+Em geral, os conflitos aparecem quando o contexto do patch (ou seja, as linhas
+que estão sendo alteradas e/ou as linhas que cercam as alterações) não
+corresponde ao que está na árvore à qual você está tentando aplicar o patch.
+
+No caso de backports, o que provavelmente aconteceu foi que a ramificação
+(branch) a partir da qual você está fazendo o backport contém patches que não
+estão na ramificação para a qual você está fazendo o backport. No entanto, o
+inverso também é possível. Em qualquer caso, o resultado é um conflito que
+precisa ser resolvido.
+
+Se a sua tentativa de cherry-pick falhar com um conflito, o git edita os
+arquivos automaticamente para incluir os chamados marcadores de conflito,
+mostrando onde está o conflito e como as duas ramificações divergiram. Resolver
+o conflito normalmente significa editar o resultado final de forma que ele leve
+em consideração esses outros commits.
+
+A resolução do conflito pode ser feita manualmente em um editor de texto comum
+ou usando uma ferramenta dedicada de resolução de conflitos.
+
+Muitas pessoas preferem usar seu editor de texto comum e editar o conflito
+diretamente, pois pode ser mais fácil entender o que você está fazendo e
+controlar o resultado final. Definitivamente, existem prós e contras em cada
+método, e às vezes há valor em usar ambos.
+
+Não abordaremos o uso de ferramentas de mesclagem (merge tools) dedicadas aqui,
+além de fornecer algumas indicações de várias ferramentas que você poderia usar:
+
+- `Modo Emacs Ediff <https://www.emacswiki.org/emacs/EdiffMode>`__
+- `vimdiff/gvimdiff <https://linux.die.net/man/1/vimdiff>`__
+- `KDiff3 <http://kdiff3.sourceforge.net/>`__
+- `TortoiseMerge <https://tortoisesvn.net/TortoiseMerge.html>`__
+- `Meld <https://meldmerge.org/help/>`__
+- `P4Merge <https://www.perforce.com/products/helix-core-apps/merge-diff-tool-p4merge>`__
+- `Beyond Compare <https://www.scootersoftware.com/>`__
+- `IntelliJ <https://www.jetbrains.com/help/idea/resolve-conflicts.html>`__
+- `VSCode <https://code.visualstudio.com/docs/editor/versioncontrol>`__
+
+Para configurar o git para funcionar com elas, veja ``git mergetool --help`` ou
+a `documentação oficial do git-mergetool`_.
+
+.. _documentação oficial do git-mergetool: https://git-scm.com/docs/git-mergetool
+
+Patches pré-requisitos
+----------------------
+
+A maioria dos conflitos acontece porque a ramificação para a qual você está
+fazendo o backport não possui alguns patches em comparação com a ramificação a
+partir da qual você está fazendo o backport. No caso mais geral (como a
+mesclagem de duas ramificações independentes), o desenvolvimento poderia ter
+ocorrido em qualquer uma das ramificações, ou as ramificações simplesmente
+divergiram -- talvez a sua ramificação mais antiga tenha recebido alguns outros
+backports que, por si só, precisaram de resoluções de conflitos, causando uma
+divergência.
+
+É importante sempre identificar o commit ou os commits que causaram o conflito,
+pois, caso contrário, você não poderá ter confiança na correção da sua
+resolução. Como um bônus adicional, especialmente se o patch for em uma área com
+a qual você não está muito familiarizado, os registros de alterações (changelogs)
+desses commits frequentemente lhe darão o contexto para entender o código e os
+problemas ou armadilhas potenciais com a sua resolução de conflito.
+
+git log
+~~~~~~~
+
+Um bom primeiro passo é olhar o ``git log`` para o arquivo que possui o
+conflito -- isso geralmente é suficiente quando não há muitos patches no
+arquivo, mas pode ficar confuso se o arquivo for grande e frequentemente
+modificado por patches. Você deve executar o ``git log`` no intervalo de commits
+entre a sua ramificação atualmente ativa (``HEAD``) e o pai do patch que você está
+escolhendo (``<commit>``), ou seja::
+
+ git log HEAD..<commit>^ -- <path>
+
+Melhor ainda, se você quiser restringir essa saída a uma única função (porque é
+onde o conflito aparece), você pode usar a seguinte sintaxe::
+
+ git log -L:'\<function\>':<path> HEAD..<commit>^
+
+.. note::
+ O ``\<`` e o ``\>`` ao redor do nome da função garantem que as
+ correspondências fiquem ancoradas em um limite de palavra. Isso é
+ importante, pois essa parte é na verdade uma regex e o git segue apenas a
+ primeira correspondência; portanto, se você usar
+ ``-L:thread_stack:kernel/fork.c``, ele poderá fornecer apenas resultados
+ para a função ``try_release_thread_stack_to_cache``, embora existam muitas
+ outras funções naquele arquivo contendo a string ``thread_stack`` em seus
+ nomes.
+
+Outra opção útil para o ``git log`` é a ``-G``, que permite filtrar por certas
+strings que aparecem nos diffs dos commits que você está listando::
+
+ git log -G'regex' HEAD..<commit>^ -- <path>
+
+Esta também pode ser uma maneira prática de encontrar rapidamente quando algo
+(por exemplo, uma chamada de função ou uma variável) foi alterado, adicionado
+ou removido. A string de busca é uma expressão regular, o que significa que você
+pode potencialmente buscar por coisas mais específicas, como atribuições a um
+membro específico de uma struct::
+
+ git log -G'\->index\>.*='
+
+git blame
+~~~~~~~~~
+
+Outra maneira de encontrar commits pré-requisitos (embora apenas o mais recente
+para um determinado conflito) é executar o ``git blame``. Neste caso, você
+precisa executá-lo no commit pai do patch para o qual está fazendo o
+cherry-pick e no arquivo onde o conflito apareceu, ou seja::
+
+ git blame <commit>^ -- <path>
+
+Este comando também aceita o argumento ``-L`` (para restringir a saída a uma
+única função), mas, neste caso, você especifica o nome do arquivo no final do
+comando, como de costume::
+
+ git blame -L:'\<function\>' <commit>^ -- <path>
+
+Navegue até o local onde o conflito ocorreu. A primeira coluna da saída do
+blame é o ID do commit do patch que adicionou uma determinada linha de código.
+
+Pode ser uma boa ideia dar um ``git show`` nesses commits e ver se eles se
+parecem com a possível origem do conflito. Às vezes, haverá mais de um desses
+commits, seja porque múltiplos commits alteraram linhas diferentes da mesma área
+de conflito *ou* porque múltiplos patches subsequentes alteraram a mesma linha
+(ou linhas) várias vezes. Neste último caso, você pode ter que executar o
+``git blame`` novamente e especificar a versão mais antiga do arquivo para
+analisar, a fim de cavar mais fundo no histórico do arquivo.
+
+Patches pré-requisitos vs. incidentais
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Tendo encontrado o patch que causou o conflito, você precisa determinar se ele
+é um pré-requisito para o patch que você está fazendo o backport ou se é apenas
+incidental e pode ser pulado. Um patch incidental seria aquele que toca no mesmo
+código que o patch para o qual você está fazendo o backport, mas não altera a
+semântica do código de nenhuma forma relevante. Por exemplo, um patch de limpeza
+de espaços em branco é completamente incidental -- da mesma forma, um patch que
+simplesmente renomeia uma função ou uma variável também seria incidental. Por
+outro lado, se a função que está sendo alterada sequer existe na sua ramificação
+atual, então isso não seria nada incidental e você precisa considerar com
+cuidado se o patch que adiciona a função deve ser aplicado via cherry-pick
+primeiro.
+
+Se você descobrir que há um patch pré-requisito necessário, então você precisa
+parar e fazer o cherry-pick dele em vez disso. Se você já resolveu alguns
+conflitos em um arquivo diferente e não quer fazer isso de novo, você pode
+criar uma cópia temporária daquele arquivo.
+
+Para abortar o cherry-pick atual, vá em frente e execute
+``git cherry-pick --abort`` e, em seguida, reinicie o processo de cherry-pick
+com o ID do commit do patch pré-requisito.
+
+Entendendo os marcadores de conflito
+------------------------------------
+
+Diffs combinados
+~~~~~~~~~~~~~~~~
+
+Digamos que você tenha decidido não fazer o cherry-pick (ou o revert) de patches
+adicionais e quer apenas resolver o conflito. O Git terá inserido marcadores de
+conflito no seu arquivo. Por padrão, isso se parecerá com algo como::
+
+ <<<<<<< HEAD
+ this is what's in your current tree before cherry-picking
+ =======
+ this is what the patch wants it to be after cherry-picking
+ >>>>>>> <commit>... title
+
+Isso é o que você veria se abrisse o arquivo no seu editor. No entanto, se você
+executasse o ``git diff`` sem nenhum argumento, a saída seria algo assim::
+
+ $ git diff
+ [...]
+ ++<<<<<<<< HEAD
+ +this is what's in your current tree before cherry-picking
+ ++========
+ + this is what the patch wants it to be after cherry-picking
+ ++>>>>>>>> <commit>... title
+
+Quando você está resolvendo um conflito, o comportamento do ``git diff`` difere
+do seu comportamento normal. Note as duas colunas de marcadores de diff em vez
+da coluna única usual; este é o chamado "`diff combinado`_", aqui mostrando o
+diff de 3 vias (ou diff-de-diffs) entre:
+
+#. a ramificação atual (antes do cherry-pick) e o diretório de trabalho atual, e
+#. a ramificação atual (antes do cherry-pick) e o arquivo como ele fica após o
+ patch original ter sido aplicado.
+
+.. _diff combinado: https://git-scm.com/docs/diff-format#_combined_diff_format
+
+Diffs melhores
+~~~~~~~~~~~~~~
+
+Diffs combinados de 3 vias incluem todas as outras alterações que aconteceram
+no arquivo entre a sua ramificação atual e a ramificação a partir da qual você
+está fazendo o cherry-pick. Embora isso seja útil para detectar outras
+alterações que você precisa levar em consideração, também torna a saída do
+``git diff`` um tanto intimidadora e difícil de ler. Em vez disso, você pode
+preferir executar ``git diff HEAD`` (ou ``git diff --ours``), que mostra apenas
+o diff entre a ramificação atual antes do cherry-pick e o diretório de trabalho
+atual. Ele se parece com isso::
+
+ $ git diff HEAD
+ [...]
+ +<<<<<<<< HEAD
+ this is what's in your current tree before cherry-picking
+ +========
+ +this is what the patch wants it to be after cherry-picking
+ +>>>>>>>> <commit>... title
+
+Como você pode ver, isso é lido exatamente como qualquer outro diff e deixa claro
+quais linhas estão na ramificação atual e quais linhas estão sendo adicionadas
+porque fazem parte do conflito de mesclagem ou do patch que está sendo aplicado
+via cherry-pick.
+
+Estilos de mesclagem e diff3
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+O estilo padrão de marcador de conflito mostrado acima é conhecido como o estilo
+``merge``. Também está disponível um outro estilo, conhecido como o estilo
+``diff3``, que se parece com isso::
+
+ <<<<<<< HEAD
+ this is what is in your current tree before cherry-picking
+ ||||||| parent of <commit> (title)
+ this is what the patch expected to find there
+ =======
+ this is what the patch wants it to be after being applied
+ >>>>>>> <commit> (title)
+
+Como você pode ver, isso tem 3 partes em vez de 2, e inclui o que o git
+esperava encontrar lá, mas não encontrou. É *altamente recomendável* usar este
+estilo de conflito, pois deixa muito mais claro o que o patch realmente alterou;
+ou seja, ele permite que você compare as versões de antes e depois do arquivo
+para o commit do qual está fazendo o cherry-pick. Isso permite que você tome
+melhores decisões sobre como resolver o conflito.
+
+Para alterar os estilos de marcadores de conflito, você pode usar o seguinte
+comando::
+
+ git config merge.conflictStyle diff3
+
+Existe uma terceira opção, ``zdiff3``, introduzida no `Git 2.35`_, que possui as
+mesmas 3 seções do ``diff3``, mas onde as linhas comuns foram cortadas, tornando
+a área de conflito menor em alguns casos.
+
+.. _Git 2.35: https://github.blog/2022-01-24-highlights-from-git-2-35/
+
+Iterando em resoluções de conflito
+----------------------------------
+
+O primeiro passo em qualquer processo de resolução de conflito é entender o
+patch para o qual você está fazendo o backport. Para o kernel Linux, isso é
+especialmente importante, pois uma alteração incorreta pode levar ao travamento
+de todo o sistema -- ou pior, a uma vulnerabilidade de segurança não detectada.
+
+Entender o patch pode ser fácil ou difícil, dependendo do próprio patch, do
+registro de alterações (changelog) e da sua familiaridade com o código que está
+sendo alterado. No entanto, uma boa pergunta para cada alteração (ou cada bloco/
+hunk do patch) seria: "Por que este hunk está no patch?" As respostas a essas
+perguntas orientarão a sua resolução de conflito.
+
+Processo de resolução
+~~~~~~~~~~~~~~~~~~~~~
+
+Às vezes, a coisa mais fácil a fazer é apenas remover tudo, exceto a primeira
+parteda do conflito, deixando o arquivo essencialmente inalterado, e aplicar
+as alterações manualmente. Talvez o patch esteja alterando um argumento de
+chamada de função de ``0`` para ``1``, enquanto uma alteração conflitante
+adicionou um parâmetro totalmente novo (e insignificante) ao final da lista de
+parâmetros; nesse caso, é bastante fácil alterar o argumento de ``0`` para ``1``
+manualmente e deixar o restante dos argumentos como estão. Esta técnica de
+aplicar alterações manualmente é mais útil se o conflito tiver trazido muito
+contexto não relacionado com o qual você não precisa realmente se preocupar.
+
+Para conflitos particularmente difíceis com muitos marcadores de conflito, você
+pode usar ``git add`` ou ``git add -i`` para indexar (stage) seletivamente as
+suas resoluções para tirá-las do caminho; isso também permite que você use
+``git diff HEAD`` para ver sempre o que ainda resta a ser resolvido ou
+``git diff --cached`` para ver como está o seu patch até o momento.
+
+Lidando com arquivos renomeados
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Uma das coisas mais irritantes que podem acontecer ao fazer o backport de um
+patch é descobrir que um dos arquivos modificados foi renomeado, pois isso
+geralmente significa que o git sequer colocará marcadores de conflito, mas
+apenas lavará as mãos e dirá (parafraseando): "Caminho não mesclado! Faça você o
+trabalho..."
+
+Geralmente existem algumas maneiras de lidar com isso. Se o patch para o
+arquivo renomeado for pequeno, como uma alteração de uma única linha, a coisa
+mais fácil é prosseguir, aplicar a alteração manualmente e dar o caso por
+encerrado. Por outro lado, se a alteração for grande ou complicada, você
+definitivamente não vai querer fazê-la manualmente.
+
+Como uma primeira tentativa, você pode tentar algo assim, que reduzirá o limite
+(threshold) de detecção de renomeação para 30% (por padrão, o git usa 50%, o que
+significa que dois arquivos precisam ter pelo menos 50% em comum para que ele
+considere um par de adição/remoção como uma renomeação potencial)::
+
+ git cherry-pick -strategy=recursive -Xrename-threshold=30
+
+Às vezes, a coisa certa a fazer será fazer o backport também do patch que
+realizou a renomeação, mas esse definitivamente não é o caso mais comum. Em vez
+disso, o que você pode fazer é renomear temporariamente o arquivo na
+ramificação para a qual está fazendo o backport (usando ``git mv`` e commitando
+o resultado), reiniciar a tentativa de cherry-pick do patch, renomear o arquivo
+de volta (``git mv`` e commitando novamente) e, finalmente, esmagar (squash) o
+resultado usando ``git rebase -i`` (veja o `tutorial de rebase`_) para que ele
+apareça como um único commit quando você terminar.
+
+.. _tutorial de rebase: [https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ec](https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ec)
+
+Pegadinhas
+----------
+
+Argumentos de função
+~~~~~~~~~~~~~~~~~~~~
+
+Preste atenção às alterações em argumentos de função! É fácil deixar passar
+detalhes e pensar que duas linhas são iguais quando, na verdade, elas diferem em
+algum pequeno detalhe, como qual variável foi passada como argumento
+(especialmente se as duas variáveis forem de apenas um caractere e parecerem
+iguais, como i e j).
+
+Tratamento de erros
+~~~~~~~~~~~~~~~~~~~
+
+Se você fizer o cherry-pick de um patch que inclua uma instrução ``goto``
+(geralmente para tratamento de erros), é absolutamente imperativo verificar em
+dobro se o rótulo (label) de destino ainda está correto na ramificação para a
+qual você está fazendo o backport. O mesmo vale para instruções ``return``,
+``break`` e ``continue`` adicionadas.
+
+O tratamento de erros geralmente fica localizado no final da função, portanto,
+pode não fazer parte do conflito, mesmo que possa ter sido alterado por outros
+patches.
+
+Uma boa maneira de garantir que você revise os caminhos de erro é sempre usar
+``git diff -W`` e ``git show -W`` (também conhecido como ``--function-context``)
+ao inspecionar suas alterações. Para código em C, isso mostrará toda a função
+que está sendo alterada em um patch. Uma das coisas que frequentemente dão
+errado durante backports é que algo mais na função mudou em qualquer uma das
+ramificações a partir da qual ou para a qual você está fazendo o backport. Ao
+incluir a função inteira no diff, você obtém mais contexto e pode identificar
+mais facilmente problemas que de outra forma poderiam passar despercebidos.
+
+Código refatorado
+~~~~~~~~~~~~~~~~~
+
+Algo que acontece com bastante frequência é o código ser refatorado ao "isolar"
+uma sequência ou padrão de código comum em uma função auxiliar. Ao fazer o
+backport de patches para uma área onde tal refatoração ocorreu, você efetivamente
+precisa fazer o inverso ao realizar o backport: um patch para um único local pode
+precisar ser aplicado a múltiplos locais na versão que recebeu o backport. (Um
+indicativo para este cenário é que uma função foi renomeada -- mas nem sempre é o
+caso.)
+
+Para evitar backports incompletos, vale a pena tentar descobrir se o patch
+corrige um bug que aparece em mais de um lugar. Uma maneira de fazer isso seria
+usar o ``git grep``. (Isso, na verdade, é uma boa ideia de se fazer em geral, não
+apenas para backports.) Se você descobrir que o mesmo tipo de correção se
+aplicaria a outros lugares, também vale a pena ver se esses lugares existem no
+upstream -- se não existirem, é provável que o patch precise ser ajustado. O
+``git log`` é seu amigo para descobrir o que aconteceu com essas áreas, já que o
+``git blame`` não mostrará código que foi removido.
+
+Se você encontrar outras instâncias do mesmo padrão na árvore do upstream e não
+tiver certeza se isso também é um bug, pode valer a pena perguntar ao autor do
+patch. Não é incomum encontrar novos bugs durante o processo de backport!
+
+Verificando o resultado
+=======================
+
+colordiff
+---------
+
+Tendo commitado um novo patch sem conflitos, você pode agora comparar o seu
+patch com o patch original. É altamente recomendável que você use uma
+ferramenta como o `colordiff`_ que possa mostrar dois arquivos lado a lado e
+colori-los de acordo com as alterações entre eles::
+
+ colordiff -yw -W 200 <(git diff -W <upstream commit>^-) <(git diff -W HEAD^-) | less -SR
+
+.. _colordiff: https://www.colordiff.org/
+
+Aqui, ``-y`` significa fazer uma comparação lado a lado; ``-w`` ignora
+espaços em branco e ``-W 200`` define a largura da saída (caso contrário, ele
+usará 130 por padrão, o que costuma ser um pouco pouco).
+
+A sintaxe ``rev^-`` é um atalho prático para ``rev^..rev``, essencialmente
+fornecendo apenas o diff para aquele único commit; veja também a
+`documentação oficial do git rev-parse`_.
+
+.. _documentação oficial do git rev-parse: https://git-scm.com/docs/git-rev-parse#_other_rev_parent_shorthand_notations
+
+Novamente, note a inclusão de ``-W`` para o ``git diff``; isso garante que você
+verá a função completa para qualquer função que tenha mudado.
+
+Uma coisa incrivelmente importante que o colordiff faz é destacar as linhas que
+são diferentes. Por exemplo, se um ``goto`` de tratamento de erros teve seus
+rótulos alterados entre o patch original e o que sofreu o backport, o colordiff
+irá mostrá-los lado a lado, mas destacados em uma cor diferente. Assim, é fácil
+ver que as duas instruções ``goto`` estão saltando para rótulos diferentes. Da
+mesma forma, linhas que não foram modificadas por nenhum dos patches, mas que
+diferem no contexto, também serão destacadas e, portanto, se destacarão durante
+uma inspeção manual.
+
+Claro, esta é apenas uma inspeção visual; o teste real é compilar e executar o
+kernel (ou programa) com o patch aplicado.
+
+Testes de compilação (Build testing)
+------------------------------------
+
+Não abordaremos os testes em tempo de execução aqui, mas pode ser uma boa ideia
+compilar apenas os arquivos tocados pelo patch como uma verificação rápida de
+sanidade. Para o kernel Linux, você pode compilar arquivos únicos assim,
+assumindo que você tenha o ``.config`` e o ambiente de compilação configurados
+corretamente::
+
+ make caminho/para/o/arquivo.o
+
+Note que isso não descobrirá erros de ligação (linker errors), então você ainda
+deve fazer uma compilação completa após verificar que o arquivo único compila.
+Ao compilar o arquivo único primeiro, você pode evitar ter que esperar por uma
+compilação completa *caso* haja erros de compilador em qualquer um dos arquivos
+que você alterou.
+
+Testes em tempo de execução
+---------------------------
+
+Mesmo um teste de compilação ou de boot bem-sucedido não é necessariamente o
+suficiente para descartar uma dependência ausente em algum lugar. Embora as
+chances sejam pequenas, pode haver alterações de código onde duas modificações
+independentes no mesmo arquivo resultem em nenhum conflito, nenhum erro em tempo
+de compilação e erros em tempo de execução apenas em casos excepcionais.
+
+Um exemplo concreto disso foi um par de patches para o código de entrada de
+chamada de sistema (system call entry code), onde o primeiro patch salvava/
+restaurava um registrador e um patch posterior fazia uso do mesmo registrador
+em algum lugar no meio dessa sequência. Como não havia sobreposição entre as
+alterações, era possível fazer o cherry-pick do segundo patch, não ter conflitos
+e acreditar que tudo estava bem, quando na verdade o código estava agora
+sobrescrevendo (scribbling over) um registrador não salvo.
+
+Embora a vasta maioria dos erros seja capturada durante a compilação ou ao
+exercitar o código superficialmente, a única maneira de *realmente* verificar um
+backport é revisar o patch final com o mesmo nível de escrutínio que você daria
+(ou deveria dar) a qualquer outro patch. Ter testes unitários e testes de
+regressão ou outros tipos de testes automáticos pode ajudar a aumentar a
+confiança na correção de um backport.
+
+Enviando backports para a árvore estável (stable)
+=================================================
+
+À medida que os mantenedores da árvore estável tentam aplicar correções da linha
+principal (mainline) em seus kernels estáveis via cherry-pick, eles podem enviar
+e-mails solicitando backports quando encontram conflitos; veja, por exemplo,
+<https://lore.kernel.org/stable/2023101528-jawed-shelving-071a@gregkh/>.
+Esses e-mails normalmente incluem os passos exatos que você precisa seguir para
+fazer o cherry-pick do patch para a árvore correta e enviá-lo.
+
+Uma coisa a se certificar é que o seu registro de alterações (changelog) esteja
+em conformidade com o formato esperado::
+
+ <original patch title>
+
+ [ Upstream commit <mainline rev> ]
+
+ <rest of the original changelog>
+ [ <summary of the conflicts and their resolutions> ]
+ Signed-off-by: <your name and email>
+
+A linha "Upstream commit" às vezes é ligeiramente diferente dependendo da versão
+estável. Versões mais antigas usavam este formato::
+
+ commit <mainline rev> upstream.
+
+O mais comum é indicar a versão do kernel à qual o patch se aplica na linha de
+assunto do e-mail (usando, por exemplo,
+``git send-email --subject-prefix='PATCH 6.1.y'``), mas você também pode
+colocá-la na área do Signed-off-by: ou abaixo da linha ``---``.
+
+Os mantenedores da árvore estável esperam envios separados para cada versão
+estável ativa, e cada envio também deve ser testado separadamente.
+
+Algumas palavras finais de conselho
+===================================
+
+1) Aborde o processo de backport com humildade.
+2) Entenda o patch para o qual você está fazendo o backport; isso significa ler
+ tanto o registro de alterações (changelog) quanto o código.
+3) Seja honesto sobre a sua confiança no resultado ao enviar o patch.
+4) Peça aprovações explícitas (acks) aos mantenedores relevantes.
+
+Exemplos
+========
+
+O texto acima mostra, de forma geral, o processo idealizado de backport de um
+patch. Para um exemplo mais concreto, veja este tutorial em vídeo onde dois
+patches são portados da linha principal (mainline) para a estável (stable):
+`Backporting Linux Kernel Patches`_.
+
+.. _Backporting Linux Kernel Patches: https://youtu.be/sBR7R1V2FeA
\ No newline at end of file
--
2.47.3
^ permalink raw reply related [flat|nested] 8+ messages in thread* [PATCH v2 5/7] docs: pt_BR: process: translate botching-up-ioctls guide
2026-07-03 17:05 [PATCH v2 0/7] docs: pt_BR: process: translation updates and additions Daniel Pereira
` (3 preceding siblings ...)
2026-07-03 17:05 ` [PATCH v2 4/7] docs: pt_BR: translate backporting.rst documentation Daniel Pereira
@ 2026-07-03 17:05 ` Daniel Pereira
2026-07-03 17:05 ` [PATCH v2 6/7] docs: pt_BR: process: translate contribution maturity model Daniel Pereira
2026-07-03 17:05 ` [PATCH v2 7/7] docs: pt_BR: translate process/adding-syscalls.rst Daniel Pereira
6 siblings, 0 replies; 8+ messages in thread
From: Daniel Pereira @ 2026-07-03 17:05 UTC (permalink / raw)
To: corbet; +Cc: linux-doc, Daniel Pereira
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=y, Size: 16649 bytes --]
Translate the 'botching-up-ioctls' documentation into Brazilian
Portuguese, ensuring precise technical alignment with the upstream
source guidelines.
The translation covers critical driver-private API design concepts,
including fixed-sized integers, structure padding, error path
validation rules, and handling asynchronous hardware timeouts.
Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
Documentation/translations/pt_BR/index.rst | 1 +
.../pt_BR/process/botching-up-ioctls.rst | 256 ++++++++++++++++++
2 files changed, 257 insertions(+)
create mode 100644 Documentation/translations/pt_BR/process/botching-up-ioctls.rst
diff --git a/Documentation/translations/pt_BR/index.rst b/Documentation/translations/pt_BR/index.rst
index 08faaacf3..4a13b3d14 100644
--- a/Documentation/translations/pt_BR/index.rst
+++ b/Documentation/translations/pt_BR/index.rst
@@ -70,6 +70,7 @@ kernel e sobre como ver seu trabalho integrado.
Guia do Processo de Desenvolvimento <process/development-process>
Como aplicar patches <process/applying-patches>
Backporting e resolução de conflitos <process/backporting>
+ Como não Deixar as ioctls malfeitas <process/botching-up-ioctls>
Index de documentos do Kernel <process/kernel-docs>
Regras de licenciamento <process/license-rules>
Como começar <process/howto>
diff --git a/Documentation/translations/pt_BR/process/botching-up-ioctls.rst b/Documentation/translations/pt_BR/process/botching-up-ioctls.rst
new file mode 100644
index 000000000..193297619
--- /dev/null
+++ b/Documentation/translations/pt_BR/process/botching-up-ioctls.rst
@@ -0,0 +1,256 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============================================
+(Como evitar) Deixar as ioctls malfeitas
+============================================
+
+De: https://blog.ffwll.ch/2013/11/botching-up-ioctls.html
+
+Por: Daniel Vetter, Copyright © 2013 Intel Corporation
+
+Uma percepção clara que os hackers de gráficos do kernel tiveram nos últimos
+anos é que tentar criar uma interface unificada para gerenciar as unidades de
+execução e a memória em GPUs completamente diferentes é um esforço inútil.
+Portanto, hoje em dia, cada driver tem seu próprio conjunto de ioctls para
+alocar memória e enviar trabalho para a GPU. O que é bom, já que não há mais a
+insanidade na forma de interfaces falsamente genéricas, mas que na verdade só
+são usadas uma vez. No entanto, a desvantagem clara é que há muito mais
+potencial para estragar as coisas.
+
+Para evitar repetir todos os mesmos erros novamente, escrevi algumas das lições
+aprendidas enquanto fazia um trabalho malfeito para o driver drm/i915. A maioria
+delas aborda apenas tecnicalidades e não os problemas macro (big-picture), como
+deveria ser exatamente a aparência da ioctl de envio de comando. Aprender essas
+lições é provavelmente algo que cada driver de GPU tem que fazer por conta
+própria.
+
+
+Pré-requisitos
+--------------
+
+Primeiro, os pré-requisitos. Sem estes você já falhou, porque precisará
+adicionar uma camada de compatibilidade de 32 bits (compat layer):
+
+ * Use apenas inteiros de tamanho fixo. Para evitar conflitos com typedefs no
+ espaço de usuário (userspace), o kernel possui tipos especiais como __u32 e
+ __s64. Use-os.
+
+ * Alinhe tudo ao tamanho natural e use preenchimento (padding) explícito.
+ Plataformas de 32 bits não alinham necessariamente valores de 64 bits a
+ limites (boundaries) de 64 bits, mas plataformas de 64 bits o fazem. Portanto,
+ sempre precisamos de padding para o tamanho natural para acertar isso.
+
+ * Preencha a struct inteira para um múltiplo de 64 bits se a estrutura contiver
+ tipos de 64 bits -- caso contrário, o tamanho da estrutura diferirá entre
+ 32 bits e 64 bits. Ter um tamanho de estrutura diferente prejudica ao passar
+ matrizes (arrays) de estruturas para o kernel, ou se o kernel verificar o
+ tamanho da estrutura, o que o core do drm, por exemplo, faz.
+
+ * Ponteiros são __u64, convertidos de/para um uintptr_t no lado do espaço de
+ usuário e de/para um void __user * no kernel. Tente de verdade não atrasar
+ essa conversão ou, pior ainda, manipular o __u64 bruto pelo seu código, pois
+ isso diminui a verificação que ferramentas como o sparse podem fornecer. A
+ macro u64_to_user_ptr pode ser usada no kernel para evitar avisos sobre
+ inteiros e ponteiros de tamanhos diferentes.
+
+
+Conceitos básicos
+-----------------
+
+Evitadas as alegrias de escrever uma camada de compatibilidade (compat layer),
+podemos dar uma olhada nos deslizes básicos. Negligenciar estes pontos tornará a
+compatibilidade retroativa e futura uma verdadeira dor de cabeça. E, como errar
+na primeira tentativa é garantido, você certamente terá uma segunda iteração ou,
+pelo menos, uma extensão para qualquer interface fornecida.
+
+ * Tenha uma maneira clara para o espaço de usuário descobrir se a sua nova
+ ioctl ou extensão de ioctl é suportada em um determinado kernel. Se você não
+ puder confiar que os kernels antigos rejeitarão as novas flags/modos ou
+ ioctls (já que fazer isso foi deixado de lado no passado), então você
+ precisará de uma flag de recurso (feature flag) do driver ou de um número de
+ revisão em algum lugar.
+
+ * Tenha um plano para estender as ioctls com novas flags ou novos campos no
+ final da estrutura. O core do drm verifica o tamanho passado para cada
+ chamada de ioctl e preenche com zero (zero-extends) quaisquer divergências
+ entre o kernel e o espaço de usuário. Isso ajuda, mas não é uma solução
+ completa, já que um espaço de usuário mais novo em um kernel mais antigo não
+ notará que os campos recém-adicionados no final estão sendo ignorados.
+ Portanto, isso ainda exige novas flags de recurso do driver.
+
+ * Verifique todos os campos e flags não utilizados, além de todo o preenchimento
+ (padding), para garantir que estejam em 0, e rejeite a ioctl se esse não for
+ o caso. Caso contrário, seu excelente plano para extensões futuras irá por
+ água abaixo, pois alguém enviará uma struct de ioctl com lixo de pilha
+ (stack garbage) aleatório nas partes ainda não utilizadas. O que, então,
+ consolida na ABI que esses campos nunca poderão ser usados para nada além de
+ lixo. Esta também é a razão pela qual você deve preencher explicitamente todas
+ as estruturas, mesmo que nunca as use em uma matriz (array) -- o padding que
+ o compilador possa inserir poderia conter lixo.
+
+ * Tenha casos de teste simples para tudo o que foi mencionado acima.
+
+
+Diversão com caminhos de erro (Error Paths)
+-------------------------------------------
+
+Hoje em dia, não temos mais nenhuma desculpa para que os drivers drm sejam pequenos
+exploits de root disfarçados. Isso significa que precisamos tanto de uma
+validação completa de entrada quanto de caminhos sólidos de tratamento de erros
+-- as GPUs eventualmente vão parar de funcionar (die) nos casos mais bizarros
+de qualquer maneira:
+
+ * A ioctl deve verificar se há estouros de matriz (array overflows). Ela também
+ precisa verificar estouros superiores/inferiores (over/underflows) e problemas
+ de limitação (clamping) de valores inteiros em geral. O exemplo usual são os
+ valores de posicionamento de sprite alimentados diretamente no hardware, onde
+ o hardware possui apenas 12 bits ou algo assim. Funciona perfeitamente até que
+ algum servidor de exibição bizarro não se preocupe em fazer o clamping por si
+ mesmo e o cursor dê a volta (wrap around) na tela.
+
+ * Tenha casos de teste simples para cada caso de falha de validação de entrada
+ na sua ioctl. Verifique se o código de erro corresponde às suas expectativas.
+ E, finalmente, certifique-se de testar apenas um único caminho de erro em
+ cada subteste, enviando dados que, de outra forma, seriam perfeitamente
+ válidos. Sem isso, uma verificação anterior já poderia rejeitar a ioctl e
+ ofuscar (shadow) o caminho de código que você realmente deseja testar,
+ ocultando bugs e regressões.
+
+ * Torne todas as suas ioctls reiniciáveis (restartable). Primeiro, o X (X11)
+ realmente ama sinais (signals) e, segundo, isso permitirá que você teste 90%
+ de todos os caminhos de tratamento de erro apenas interrompendo sua suíte de
+ testes principal constantemente com sinais. Graças ao amor do X por sinais,
+ você obterá uma excelente cobertura de base de todos os seus caminhos de erro
+ praticamente de graça para drivers de gráficos. Além disso, seja consistente
+ na forma como você lida com a reinicialização de ioctls -- por exemplo, o drm
+ possui um pequeno helper drmIoctl em sua biblioteca de espaço de usuário. O
+ driver i915 estragou isso com a ioctl set_tiling; agora estamos presos para
+ sempre com algumas semânticas arcanas tanto no kernel quanto no espaço de
+ usuário.
+
+ * Se você não puder tornar um determinado caminho de código reiniciável, torne
+ uma tarefa travada pelo menos finalizável (killable). As GPUs simplesmente
+ morrem, e seus usuários não vão gostar mais de você se você travar a máquina
+ inteira deles (por meio de um processo do X impossível de matar). Se a
+ recuperação de estado ainda for muito complicada, tenha um timeout ou uma
+ rede de segurança de verificação de travamento (hangcheck) como um esforço de
+ última hora (last-ditch) caso o hardware enlouqueça (gone bananas).
+
+ * Tenha casos de teste para os cenários mais complexos (corner cases) no seu
+ código de recuperação de erros -- é fácil demais criar um deadlock entre seu
+ código de hangcheck e os processos que estão aguardando (waiters).
+
+
+Tempo, Espera e a Perda de Prazos
+---------------------------------
+
+As GPUs fazem quase tudo de forma assíncrona, portanto, temos a necessidade de
+cronometrar operações e aguardar pelas que estão pendentes. Esse é um negócio
+realmente complicado; no momento, nenhuma das ioctls suportadas pelo drm/i915
+acerta isso completamente, o que significa que ainda há toneladas de lições para
+aprender aqui.
+
+ * Use CLOCK_MONOTONIC como seu tempo de referência, sempre. É o que o alsa, o
+ drm e o v4l usam por padrão hoje em dia. Mas informe ao espaço de usuário
+ quais carimbos de data/hora (timestamps) são derivados de domínios de relógio
+ diferentes, como o relógio principal do seu sistema (fornecido pelo kernel)
+ ou algum contador de hardware independente em outro lugar. Os relógios vão
+ divergir se você olhar de perto o suficiente, mas se as ferramentas de
+ medição de desempenho tiverem essa informação, elas poderão ao menos compensar.
+ Se o seu espaço de usuário puder obter os valores brutos de alguns relógios
+ (por exemplo, por meio de instruções de amostragem de contador de desempenho
+ no fluxo de comandos), considere expor esses também.
+
+ * Use __s64 para segundos mais __u64 para nanossegundos para especificar o
+ tempo. Não é a especificação de tempo mais conveniente, mas é praticamente o
+ padrão.
+
+ * Verifique se os valores de tempo de entrada estão normalizados e rejeite-os
+ caso contrário. Note que a struct nativa do kernel, ktime, possui um inteiro
+ sinalizado tanto para segundos quanto para nanossegundos, portanto, cuidado
+ aqui.
+
+ * Para timeouts, use tempos absolutos. Se você for um bom sujeito e tiver
+ tornado a sua ioctl reiniciável, os timeouts relativos tendem a ser muito
+ imprecisos (coarse) e podem estender indefinidamente o seu tempo de espera
+ devido ao arredondamento a cada reinicialização. Especialmente se o seu relógio
+ de referência for algo realmente lento, como o contador de quadros da tela
+ (display frame counter). Vestindo o chapéu de advogado de especificações, isso
+ não é um bug, já que os timeouts sempre podem ser estendidos -- mas os usuários
+ com certeza vão odiar você se as belas animações deles começarem a gaguejar
+ (stutter) devido a isso.
+
+ * Considere descartar quaisquer ioctls de espera síncrona com timeouts e apenas
+ entregue um evento assíncrono em um descritor de arquivo passível de poll
+ (pollable file descriptor). Isso se encaixa muito melhor no loop principal de
+ aplicações orientadas a eventos.
+
+ * Tenha casos de teste para cenários complexos (corner-cases), especialmente se
+ os valores de retorno para eventos já concluídos, esperas bem-sucedidas e
+ esperas que estouraram o tempo (timed-out) são todos sãos e adequados às suas
+ necessidades.
+
+
+Evitando o vazamento de recursos (Leaking Resources, Not)
+---------------------------------------------------------
+
+Um driver drm completo essencialmente implementa um pequeno SO, mas especializado
+para as plataformas de GPU fornecidas. Isso significa que um driver precisa
+expor toneladas de handles (identificadores) para diferentes objetos e outros
+recursos para o espaço de usuário. Fazer isso corretamente traz seu próprio
+pequeno conjunto de armadilhas:
+
+ * Sempre vincule o tempo de vida (lifetime) de seus recursos criados
+ dinamicamente ao tempo de vida de um descritor de arquivo (file descriptor -
+ fd). Considere usar um mapeamento 1:1 se o seu recurso precisar ser
+ compartilhado entre processos -- a passagem de fds sobre unix domain sockets
+ também simplifica o gerenciamento do tempo de vida para o espaço de usuário.
+
+ * Sempre tenha suporte a O_CLOEXEC.
+
+ * Certifique-se de que você tem isolamento suficiente entre os diferentes
+ clientes. Por padrão, escolha um namespace privado por fd, o que força
+ qualquer compartilhamento a ser feito de forma explícita. Só adote um
+ namespace mais global por dispositivo se os objetos forem verdadeiramente
+ únicos do dispositivo. Um contraexemplo nas interfaces de modeset do drm é
+ que os objetos de modeset por dispositivo, como conectores, compartilham um
+ namespace com objetos de framebuffer, que na maioria das vezes não são
+ compartilhados de forma alguma. Um namespace separado, privado por padrão,
+ para os framebuffers teria sido mais adequado.
+
+ * Pense sobre os requisitos de unicidade para os handles do espaço de usuário.
+ Por exemplo, para a maioria dos drivers drm, é um bug do espaço de usuário
+ enviar o mesmo objeto duas vezes na mesma ioctl de envio de comando. Mas,
+ se os objetos forem compartilháveis, o espaço de usuário precisa saber se
+ já viu um objeto importado de outro processo ou não. Eu ainda não tentei isso
+ sozinho devido à falta de uma nova classe de objetos, mas considere usar
+ números de inode em seus descritores de arquivo compartilhados como
+ identificadores únicos -- é assim que arquivos reais também são diferenciados.
+ Infelizmente, isso requer um sistema de arquivos virtual completo no kernel.
+
+
+Por último, mas não menos importante
+------------------------------------
+
+Nem todo problema precisa de uma nova ioctl:
+
+ * Pense bem se você realmente quer uma interface privada do driver. Claro que
+ é muito mais rápido aprovar uma interface privada do driver do que se envolver
+ em discussões longas por uma solução mais genérica. E, ocasionalmente, criar
+ uma interface privada para liderar um novo conceito é o que se exige. Mas,
+ no final, assim que a interface genérica surgir, você acabará mantendo duas
+ interfaces. Indefinidamente.
+
+ * Considere outras interfaces além de ioctls. Um atributo sysfs é muito melhor
+ para configurações por dispositivo ou para objetos filhos com tempos de vida
+ razoavelmente estáticos (como conectores de saída no drm com todos os seus
+ atributos de sobreposição de detecção). Ou talvez apenas a sua suíte de
+ testes precise dessa interface e, nesse caso, o debugfs, com seu aviso de
+ isenção de responsabilidade por não ter uma ABI estável, seria melhor.
+
+Finalmente, o objetivo principal é acertar na primeira tentativa, pois se o seu
+driver se provar popular e suas plataformas de hardware forem duradouras, você
+ficará preso a uma determinada ioctl essencialmente para sempre. Você pode
+tentar depreciar ioctls horríveis em iterações mais novas do seu hardware, mas
+geralmente leva anos para conseguir isso. E depois mais anos até que o último
+usuário capaz de reclamar sobre regressões desapareça também.
\ No newline at end of file
--
2.47.3
^ permalink raw reply related [flat|nested] 8+ messages in thread* [PATCH v2 6/7] docs: pt_BR: process: translate contribution maturity model
2026-07-03 17:05 [PATCH v2 0/7] docs: pt_BR: process: translation updates and additions Daniel Pereira
` (4 preceding siblings ...)
2026-07-03 17:05 ` [PATCH v2 5/7] docs: pt_BR: process: translate botching-up-ioctls guide Daniel Pereira
@ 2026-07-03 17:05 ` Daniel Pereira
2026-07-03 17:05 ` [PATCH v2 7/7] docs: pt_BR: translate process/adding-syscalls.rst Daniel Pereira
6 siblings, 0 replies; 8+ messages in thread
From: Daniel Pereira @ 2026-07-03 17:05 UTC (permalink / raw)
To: corbet; +Cc: linux-doc, Daniel Pereira
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=y, Size: 7281 bytes --]
Translate the 'contribution-maturity-model' documentation into
Brazilian Portuguese, ensuring strict alignment with the upstream
source structure and language.
The translation covers the Open Source engagement framework proposed
by the Technical Advisory Board (TAB), detailing Levels 0 through 5
of organizational upstream maturity, community metrics, and engineer
career alignment.
Additionally, maintain strict 80-column line length restrictions
across the entire file to ensure proper Sphinx HTML rendering.
Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
Documentation/translations/pt_BR/index.rst | 1 +
.../process/contribution-maturity-model.rst | 111 ++++++++++++++++++
2 files changed, 112 insertions(+)
create mode 100644 Documentation/translations/pt_BR/process/contribution-maturity-model.rst
diff --git a/Documentation/translations/pt_BR/index.rst b/Documentation/translations/pt_BR/index.rst
index 4a13b3d14..749c5fc3f 100644
--- a/Documentation/translations/pt_BR/index.rst
+++ b/Documentation/translations/pt_BR/index.rst
@@ -76,6 +76,7 @@ kernel e sobre como ver seu trabalho integrado.
Como começar <process/howto>
Requisitos mínimos <process/changes>
Conclave (Continuidade do projeto) <process/conclave>
+ Modelos de Maturidade para Contribuição no Kernel Linux <process/contribution-maturity-model.rst>
Manuais dos mantenedores <process/maintainer-handbooks>
Processo do subsistema de rede (netdev) <process/maintainer-netdev>
Processo do subsistema SoC <process/maintainer-soc>
diff --git a/Documentation/translations/pt_BR/process/contribution-maturity-model.rst b/Documentation/translations/pt_BR/process/contribution-maturity-model.rst
new file mode 100644
index 000000000..bb003c4cd
--- /dev/null
+++ b/Documentation/translations/pt_BR/process/contribution-maturity-model.rst
@@ -0,0 +1,111 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================================================
+Modelos de Maturidade para Contribuição no Kernel Linux
+=======================================================
+
+
+Contexto
+========
+
+Como parte do Linux Kernel Maintainers’ Summit de 2021, houve uma
+`discussão <https://lwn.net/Articles/870581/>`_ sobre os desafios na
+contratação de mantenedores do kernel, bem como a sucessão de mantenedores.
+Algumas das conclusões daquela discussão incluíram que as empresas que fazem
+parte da comunidade do Kernel Linux precisam permitir que os engenheiros atuem
+como mantenedores como parte de seu trabalho, para que possam crescer e se
+tornar líderes respeitados e, eventualmente, mantenedores do kernel. Para
+apoiar um fluxo forte de talentos, os desenvolvedores devem ser autorizados e
+incentivados a assumir contribuições no upstream, como revisar os patches de
+outras pessoas, refatorar a infraestrutura do kernel e escrever documentação.
+
+Para tanto, o Conselho Técnico Consultivo (Technical Advisory Board - TAB) da
+Linux Foundation propõe este Modelo de Maturidade para Contribuição no Kernel
+Linux. Essas expectativas comuns para o engajamento da comunidade upstream visam
+aumentar a influência de desenvolvedores individuais, aumentar a colaboração
+de organizações e melhorar a saúde geral do ecossistema do Kernel Linux.
+
+O TAB insta as organizações a avaliarem continuamente seu modelo de maturidade
+em Open Source e a se comprometerem com melhorias para se alinharem a este
+modelo. Para ser eficaz, essa avaliação deve incorporar o feedback de toda a
+organização, incluindo a gerência e os desenvolvedores de todos os níveis de
+senioridade. No espírito do Open Source, incentivamos as organizações a
+publicarem suas avaliações e planos para melhorar seu engajamento com a
+comunidade upstream.
+
+Nível 0
+=======
+
+* Engenheiros de Software não têm permissão para contribuir com patches para o
+ kernel Linux.
+
+
+Nível 1
+=======
+
+* Engenheiros de Software têm permissão para contribuir com patches para o
+ kernel Linux, seja como parte de suas responsabilidades de trabalho ou em seu
+ próprio tempo.
+
+Nível 2
+=======
+
+* Espera-se que os Engenheiros de Software contribuam para o Kernel Linux como
+ parte de suas responsabilidades de trabalho.
+* Os Engenheiros de Software receberão apoio para participar de conferências
+ relacionadas ao Linux como parte de seu trabalho.
+* As contribuições de código no upstream de um Engenheiro de Software serão
+ consideradas em promoções e avaliações de desempenho.
+
+Nível 3
+=======
+
+* Espera-se que os Engenheiros de Software revisem patches (incluindo patches
+ escritos por engenheiros de outras empresas) como parte de suas
+ responsabilidades de trabalho.
+* A contribuição com apresentações ou artigos para conferências acadêmicas ou
+ relacionadas ao Linux (como as organizadas pela Linux Foundation, Usenix,
+ ACM, etc.) é considerada parte do trabalho do engenheiro.
+* As contribuições comunitárias de um Engenheiro de Software serão consideradas
+ em promoções e avaliações de desempenho.
+* As organizações relatarão regularmente as métricas de suas contribuições em
+ open source e acompanharão essas métricas ao longo do tempo. Essas métricas
+ podem ser publicadas apenas internamente na organização ou, a critério da
+ organização, algumas ou todas podem ser publicadas externamente. As métricas
+ fortemente sugeridas incluem:
+
+ * O número de contribuições ao kernel no upstream por equipe ou organização
+ (por exemplo, todas as pessoas que se reportam a um gerente, diretor ou
+ vice-presidente).
+ * A porcentagem de desenvolvedores de kernel que fizeram contribuições no
+ upstream em relação ao total de desenvolvedores de kernel na organização.
+ * O intervalo de tempo entre os kernels usados nos servidores e/ou produtos
+ da organização e a data de publicação do kernel upstream no qual o kernel
+ interno se baseia.
+ * O número de commits fora da árvore (out-of-tree) presentes nos kernels
+ internos.
+
+Nível 4
+=======
+
+* Os Engenheiros de Software são incentivados a dedicar uma parte do seu tempo
+ de trabalho focados no Trabalho no Upstream, o qual é definido como a revisão
+ de patches, atuação em comitês de programa, melhoria da infraestrutura central
+ do projeto -- como escrita ou manutenção de testes, redução de dívida técnica
+ no upstream, escrita de documentação, etc.
+* Os Engenheiros de Software recebem apoio para ajudar a organizar conferências
+ relacionadas ao Linux.
+* As organizações considerarão o feedback dos membros da comunidade em
+ avaliações de desempenho oficiais.
+
+Nível 5
+=======
+
+* O desenvolvimento de kernel no upstream é considerado um cargo formal, com
+ pelo menos um terço do tempo do engenheiro dedicado à realização de Trabalho
+ no Upstream.
+* As organizações buscarão ativamente o feedback dos membros da comunidade como
+ um fator nas avaliações de desempenho oficiais.
+* As organizações relatarão internamente e de forma regular a proporção entre o
+ Trabalho no Upstream e o trabalho focado em atingir diretamente os objetivos
+ de negócios.
\ No newline at end of file
--
2.47.3
^ permalink raw reply related [flat|nested] 8+ messages in thread* [PATCH v2 7/7] docs: pt_BR: translate process/adding-syscalls.rst
2026-07-03 17:05 [PATCH v2 0/7] docs: pt_BR: process: translation updates and additions Daniel Pereira
` (5 preceding siblings ...)
2026-07-03 17:05 ` [PATCH v2 6/7] docs: pt_BR: process: translate contribution maturity model Daniel Pereira
@ 2026-07-03 17:05 ` Daniel Pereira
6 siblings, 0 replies; 8+ messages in thread
From: Daniel Pereira @ 2026-07-03 17:05 UTC (permalink / raw)
To: corbet; +Cc: linux-doc, Daniel Pereira
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=y, Size: 36929 bytes --]
Translate the adding-syscalls.rst document into Brazilian Portuguese
(pt_BR) to improve accessibility for native Portuguese-speaking
developers contributing to the Linux kernel ecosystem.
Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
Changes in v2:
- Added adding-syscalls.rst to the index.rst toctree to resolve a Sphinx build warning.
Documentation/translations/pt_BR/index.rst | 1 +
.../pt_BR/process/adding-syscalls.rst | 700 ++++++++++++++++++
2 files changed, 701 insertions(+)
create mode 100644 Documentation/translations/pt_BR/process/adding-syscalls.rst
diff --git a/Documentation/translations/pt_BR/index.rst b/Documentation/translations/pt_BR/index.rst
index 749c5fc3f..2ab14c5d6 100644
--- a/Documentation/translations/pt_BR/index.rst
+++ b/Documentation/translations/pt_BR/index.rst
@@ -82,3 +82,4 @@ kernel e sobre como ver seu trabalho integrado.
Processo do subsistema SoC <process/maintainer-soc>
Conformidade de DTS para SoC <process/maintainer-soc-clean-dts>
Processo do subsistema KVM x86 <process/maintainer-kvm-x86>
+ Adicionando uma nova chamada de Sistema <process/adding-syscalls>
diff --git a/Documentation/translations/pt_BR/process/adding-syscalls.rst b/Documentation/translations/pt_BR/process/adding-syscalls.rst
new file mode 100644
index 000000000..cdf8b5033
--- /dev/null
+++ b/Documentation/translations/pt_BR/process/adding-syscalls.rst
@@ -0,0 +1,700 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================================
+Adicionando uma Nova Chamada de Sistema
+=======================================
+
+Este documento descreve o que está envolvido na adição de uma nova chamada de
+sistema (system call) ao kernel Linux, indo além dos conselhos normais de
+submissão em
+:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
+
+
+Alternativas às Chamadas de Sistema
+-----------------------------------
+
+A primeira coisa a se considerar ao adicionar uma nova chamada de sistema é se
+uma das alternativas poderia ser mais adequada. Embora as chamadas de sistema
+sejam os pontos de interação mais tradicionais e óbvios entre o espaço do
+usuário (userspace) e o kernel, existem outras possibilidades -- escolha o que
+melhor se adapta à sua interface.
+
+ - Se as operações envolvidas puderem ser moldadas para se parecerem com um
+ objeto do tipo arquivo, pode fazer mais sentido criar um novo sistema de
+ arquivos ou dispositivo. Isso também torna mais fácil encapsular a nova
+ funcionalidade em um módulo de kernel, em vez de exigir que ela seja
+ incorporada ao kernel principal.
+
+ - Se a nova funcionalidade envolver operações em que o kernel notifica o
+ espaço do usuário de que algo aconteceu, retornar um novo descritor de
+ arquivo (file descriptor) para o objeto relevante permite que o espaço
+ do usuário use ``poll``/``select``/``epoll`` para receber essa
+ notificação.
+ - No entanto, as operações que não se mapeiam para operações do tipo
+ :manpage:`read(2)`/:manpage:`write(2)` precisam ser implementadas como
+ requisições :manpage:`ioctl(2)`, o que pode levar a uma API um tanto
+ quanto opaca.
+
+ - Se você estiver apenas expondo informações do sistema em tempo de execução,
+ um novo nó no sysfs (veja ``Documentation/filesystems/sysfs.rst``) ou no
+ sistema de arquivos ``/proc`` pode ser mais apropriado. No entanto, o acesso
+ a esses mecanismos exige que o sistema de arquivos relevante esteja montado,
+ o que pode não ser sempre o caso (por exemplo, em um ambiente com namespaces,
+ sandboxed ou chrooted). Evite adicionar qualquer API ao debugfs, pois este
+ não é considerado uma interface de "produção" para o espaço do usuário.
+ - Se a operação for específica para um arquivo ou descritor de arquivo de um
+ determinado objeto, então uma opção de comando adicional para :manpage:`fcntl(2)`
+ pode ser mais adequada. Contudo, o :manpage:`fcntl(2)` é uma chamada de sistema
+ de multiplexação que oculta muita complexidade, portanto, esta opção é melhor
+ para quando a nova função for intimamente análoga à funcionalidade existente
+ do :manpage:`fcntl(2)`, ou se a nova funcionalidade for muito simples (por
+ exemplo, obter/definir uma flag simples relacionada a um descritor de arquivo).
+ - Se a operação for específica para uma tarefa (task) ou processo específico,
+ então uma opção de comando adicional para :manpage:`prctl(2)` pode ser mais
+ apropriada. Assim como no caso do :manpage:`fcntl(2)`, esta chamada de sistema
+ é um multiplexador complicado, sendo melhor reservá-la para análogos próximos
+ de comandos ``prctl()`` existentes ou para obter/definir uma flag simples
+ relacionada a um processo.
+
+
+Projetando a API: Planejando a Extensibilidade
+----------------------------------------------
+
+Uma nova chamada de sistema faz parte da API do kernel e deve ser suportada
+indefinidamente. Sendo assim, é uma excelente ideia discutir explicitamente a
+interface na lista de discussão do kernel (LKML), e é crucial planejar extensões
+futuras para essa interface.
+
+(A tabela de chamadas de sistema está repleta de exemplos históricos onde isso
+não foi feito, juntamente com as respectivas chamadas de sistema de acompanhamento
+-- ``eventfd``/``eventfd2``, ``dup2``/``dup3``, ``inotify_init``/``inotify_init1``,
+``pipe``/``pipe2``, ``renameat``/``renameat2`` -- portanto, aprenda com a história
+do kernel e planeje as extensões desde o início.)
+
+Para chamadas de sistema mais simples que recebem apenas alguns argumentos, a
+maneira preferencial de permitir extensibilidade futura é incluir um argumento de
+flags na chamada de sistema. Para garantir que os programas do espaço do usuário
+possam usar flags de forma segura entre diferentes versões do kernel, verifique
+se o valor de flags contém qualquer flag desconhecida e rejeite a chamada de
+sistema (com ``EINVAL``) se contiver::
+
+ if (flags & ~(THING_FLAG1 | THING_FLAG2 | THING_FLAG3))
+ return -EINVAL;
+
+(Se nenhum valor de flag for utilizado ainda, verifique se o argumento de flags
+é zero.)
+
+Para chamadas de sistema mais sofisticadas que envolvem um número maior de
+argumentos, prefere-se encapsular a maioria dos argumentos em uma estrutura
+(struct) que é passada por meio de um ponteiro. Esse tipo de estrutura pode
+lidar com extensões futuras incluindo um argumento de tamanho (size) na própria
+estrutura::
+
+ struct xyzzy_params {
+ u32 size; /* o espaço do usuário define p->size = sizeof(struct xyzzy_params) */
+ u32 param_1;
+ u64 param_2;
+ u64 param_3;
+ };
+
+Desde que qualquer campo adicionado subsequentemente, digamos ``param_4``, seja
+projetado de forma que um valor zero mantenha o comportamento anterior, isso
+permitirá lidar com a divergência de versões em ambas as direções:
+
+ - Para lidar com um programa de espaço do usuário mais novo chamando um kernel
+ mais antigo, o código do kernel deve verificar se qualquer memória além do
+ tamanho da estrutura que ele espera está zerada (efetivamente verificando
+ se ``param_4 == 0``).
+ - Para lidar com um programa de espaço do usuário mais antigo chamando um kernel
+ mais novo, o código do kernel pode preencher com zero (zero-extend) a
+ instância menor da estrutura (efetivamente definindo ``param_4 = 0``).
+
+Veja :manpage:`perf_event_open(2)` e a função ``perf_copy_attr()`` (em
+``kernel/events/core.c``) para um exemplo desta abordagem.
+
+
+Projetando a API: Outras Considerações
+--------------------------------------
+
+Se a sua nova chamada de sistema permitir que o espaço do usuário se refira a
+um objeto do kernel, ela deve usar um descritor de arquivo (file descriptor)
+como o handle (identificador) para esse objeto -- não invente um novo tipo de
+handle de objeto para o espaço do usuário quando o kernel já possui mecanismos
+e semânticas bem definidas para o uso de descritores de arquivo.
+
+Se a sua nova chamada de sistema (2) de fato retornar un novo descritor de
+arquivo, então o argumento de flags deve incluir um valor que seja equivalente
+a definir ``O_CLOEXEC`` no novo FD. Isso torna possível para o espaço do usuário
+fechar a janela de tempo entre a chamada ``()`` e a execução de
+``fcntl(fd, F_SETFD, FD_CLOEXEC)``, onde um ``fork()`` e ``execve()`` inesperados
+em outra thread poderiam vazar um descritor para o programa executado. (Contudo,
+resista à tentação de reutilizar o valor real da constante ``O_CLOEXEC``, pois
+ela é específica de cada arquitetura e faz parte de um espaço de numeração de
+flags ``O_*`` que está bastante cheio.)
+
+Se a sua chamada de sistema retornar um novo descritor de arquivo, você também
+deve considerar o que significa usar a família de chamadas de sistema
+:manpage:`poll(2)` nesse descritor de arquivo. Tornar um descritor de arquivo
+pronto para leitura ou escrita é a maneira normal de o kernel indicar ao espaço
+do usuário que um evento ocorreu no objeto correspondente do kernel.
+
+Se a sua nova chamada de sistema (2) envolver um argumento de nome de arquivo
+(filename)::
+
+ int sys_xyzzy(const char __user *path, ..., unsigned int flags);
+
+você também deve considerar se uma versão xyzzyat(2) seria mais apropriada::
+
+ int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags);
+
+Isso permite maior flexibilidade para a forma como o espaço do usuário especifica
+o arquivo em questão; em particular, permite que o espaço do usuário solicite a
+funcionalidade para um descritor de arquivo já aberto usando a flag
+``AT_EMPTY_PATH``, fornecendo efetivamente uma operação fxyzzy(3) de graça::
+
+ - xyzzyat(AT_FDCWD, path, ..., 0) é equivalente a (path,...)
+ - xyzzyat(fd, "", ..., AT_EMPTY_PATH) é equivalente a fxyzzy(fd, ...)
+
+(Para mais detalhes sobre a justificativa das chamadas \*at(), veja a página de
+manual :manpage:`openat(2)`; para um exemplo de AT_EMPTY_PATH, veja a página de
+manual :manpage:`fstatat(2)`.)
+
+Se a sua nova chamada de sistema (2) envolver um parâmetro que descreve um
+deslocamento (offset) dentro de um arquivo, mude o seu tipo para ``loff_t`` para
+que offsets de 64 bits possam ser suportados mesmo em arquiteturas de 32 bits.
+
+Se a sua nova chamada de sistema (2) envolver funcionalidades privilegiadas,
+ela precisa ser governada pelo bit de capacidade (capability) do Linux apropriado
+(verificado com uma chamada a ``capable()``), conforme descrito na página de
+manual :manpage:`capabilities(7)`. Escolha um bit de capacidade existente que governe
+funcionalidades relacionadas, mas tente evitar combinar muitas funções que tenham
+apenas uma vaga relação sob o mesmo bit, pois isso vai contra o propósito das
+capabilities de dividir o poder do root. Em particular, evite adicionar novos
+usos para a capacidade ``CAP_SYS_ADMIN``, que já é excessivamente generalista.
+
+Se a sua nova chamada de sistema (2) manipular um processo diferente do
+processo que a chamou, ela deve ser restrita (usando uma chamada a
+``ptrace_may_access()``) para que apenas um processo chamador com as mesmas
+permissões do processo alvo, ou com as capacidades necessárias, possa manipular
+o processo alvo.
+
+Finalmente, esteja ciente de que algumas arquiteturas não-x86 lidam melhor se os
+parâmetros da chamada de sistema que são explicitamente de 64 bits caírem em
+argumentos de numeração ímpar (ou seja, parâmetro 1, 3, 5), para permitir o uso
+de pares contíguos de registradores de 32 bits. (Esta preocupação não se aplica
+se os argumentos fizerem parte de uma estrutura que é passada por meio de um
+ponteiro.)
+
+
+Propondo a API
+--------------
+
+Para tornar as novas chamadas de sistema fáceis de revisar, é melhor dividir o
+conjunto de patches (patchset) em blocos separados. Estes devem incluir, pelo
+menos, os seguintes itens como commits distintos (cada um dos quais é descrito
+mais adiante):
+
+ - A implementação central da chamada de sistema, juntamente com protótipos,
+ numeração genérica, alterações no Kconfig e a implementação de stub de realinhamento (fallback stub).
+ - A fiação (wiring up) da nova chamada de sistema para uma arquitetura em
+ particular, geralmente x86 (incluindo todas as variantes x86_64, x86_32 e x32).
+ - Uma demonstração do uso da nova chamada de sistema no espaço do usuário por
+ meio de um selftest em ``tools/testing/selftests/``.
+ - Um rascunho da página de manual (man-page) para a nova chamada de sistema,
+ seja como texto simples na carta de apresentação (cover letter) ou como um
+ patch para o repositório (separado) de man-pages.
+
+Novas propostas de chamadas de sistema, como qualquer alteração na API do
+kernel, devem sempre ser enviadas com cópia (cc'ed) para linux-api@vger.kernel.org.
+
+
+Implementação Genérica de Chamadas de Sistema
+---------------------------------------------
+
+O ponto de entrada principal para a sua nova chamada de sistema (2) será chamado
+de ``sys_xyzzy()``, mas você deve adicionar esse ponto de entrada com a macro
+``SYSCALL_DEFINEn()`` apropriada, em vez de fazer isso explicitamente. O 'n'
+indica o número de argumentos da chamada de sistema, e a macro recebe o nome da
+chamada de sistema seguido pelos pares (tipo, nome) para os parâmetros como
+argumentos. O uso dessa macro permite que os metadados sobre a nova chamada de
+sistema fiquem disponíveis para outras ferramentas.
+
+O novo ponto de entrada também precisa de um protótipo de função correspondente
+em ``include/linux/syscalls.h``, marcado como asmlinkage para corresponder à
+maneira como as chamadas de sistema são invocadas::
+
+ asmlinkage long sys_xyzzy(...);
+
+Algumas arquiteturas (por exemplo, x86) possuem suas próprias tabelas de syscall
+específicas da arquitetura, mas várias outras arquiteturas compartilham uma tabela
+de syscall genérica. Adicione a sua nova chamada de sistema à lista genérica
+adicionando uma entrada na lista em ``include/uapi/asm-generic/unistd.h``::
+
+ #define __NR_xyzzy 292
+ __SYSCALL(__NR_xyzzy, sys_xyzzy)
+
+Atualize também a contagem de __NR_syscalls para refletir a chamada de sistema
+adicional, e observe que se múltiplas novas chamadas de sistema forem adicionadas
+na mesma janela de mesclagem (merge window), o número da sua nova syscall poderá
+ser ajustado para resolver conflitos.
+
+O arquivo ``kernel/sys_ni.c`` fornece uma implementação de stub de fallback para
+cada chamada de sistema, retornando ``-ENOSYS``. Adicione a sua nova chamada de
+sistema aqui também::
+
+ COND_SYSCALL(sys_xyzzy);
+
+A sua nova funcionalidade de kernel, e a chamada de sistema que a controla, deve
+normalmente ser opcional, portanto adicione uma opção ``CONFIG`` (tipicamente em
+``init/Kconfig``) para ela. Como de costume para novas opções ``CONFIG``:
+
+ - Inclua uma descrição da nova funcionalidade e da chamada de sistema controlada
+ pela opção.
+ - Faça a opção depender de EXPERT se ela deve ser ocultada dos usuários normais.
+ - Faça com que quaisquer novos arquivos de código-fonte que implementem a função
+ sejam dependentes da opção CONFIG no Makefile (por exemplo,
+ ``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.o``).
+ - Verifique duas vezes se o kernel ainda compila com a nova opção CONFIG desativada.
+
+Para resumir, você precisa de um commit que inclua:
+
+ - Opção ``CONFIG`` para a nova função, normalmente em ``init/Kconfig``
+ - ``SYSCALL_DEFINEn(, ...)`` para o ponto de entrada
+ - Protótipo correspondente em ``include/linux/syscalls.h``
+ - Entrada na tabela genérica em ``include/uapi/asm-generic/unistd.h``
+ - Stub de fallback em ``kernel/sys_ni.c``
+
+
+.. _pt_BR_syscall_generic_6_11:
+
+Desde a versão 6.11
+~~~~~~~~~~~~~~~~~~~
+
+A partir da versão 6.11 do kernel, a implementação de chamadas de sistema
+genéricas para as seguintes arquiteturas não requer mais modificações em
+``include/uapi/asm-generic/unistd.h``:
+
+ - arc
+ - arm64
+ - csky
+ - hexagon
+ - loongarch
+ - nios2
+ - openrisc
+ - riscv
+
+Em vez disso, você precisa atualizar ``scripts/syscall.tbl`` e, se aplicável,
+ajustar ``arch/*/kernel/Makefile.syscalls``.
+
+Como o ``scripts/syscall.tbl`` serve como uma tabela de syscall comum para
+múltiplas arquiteturas, uma nova entrada é necessária nesta tabela::
+
+ 468 common sys_xyzzy
+
+Note que adicionar uma entrada ao ``scripts/syscall.tbl`` com a ABI "common"
+também afeta todas as arquiteturas que compartilham essa tabela. Para alterações
+mais limitadas ou específicas de uma arquitetura, considere usar uma ABI
+específica da arquitetura ou definir uma nova.
+
+Se uma nova ABI, digamos ``xyz``, for introduzida, as atualizações
+correspondentes também devem ser feitas em ``arch/*/kernel/Makefile.syscalls``::
+
+ syscall_abis_{32,64} += xyz (...)
+
+Para resumir, você precisa de um commit que inclua:
+
+ - Opção ``CONFIG`` para a nova função, normalmente em ``init/Kconfig``
+ - ``SYSCALL_DEFINEn(, ...)`` para o ponto de entrada
+ - Protótipo correspondente em ``include/linux/syscalls.h``
+ - Nova entrada em ``scripts/syscall.tbl``
+ - (Se necessário) Atualizações de Makefile em ``arch/*/kernel/Makefile.syscalls``
+ - Stub de fallback em ``kernel/sys_ni.c``
+
+
+Implementação de Chamadas de Sistema em x86
+-------------------------------------------
+
+Para interligar (wire up) a sua nova chamada de sistema nas plataformas x86, você
+precisa atualizar as tabelas mestras de syscall. Assumindo que a sua nova chamada
+de sistema não seja especial de alguma forma (veja abaixo), isso envolve uma
+entrada "common" (para x86_64 e x32) em
+``arch/x86/entry/syscalls/syscall_64.tbl``::
+
+ 333 common sys_xyzzy
+
+e uma entrada "i386" em ``arch/x86/entry/syscalls/syscall_32.tbl``::
+
+ 380 i386 sys_xyzzy
+
+Novamente, esses números estão sujeitos a alterações caso ocorram conflitos na
+janela de mesclagem (merge window) relevante.
+
+Chamadas de Sistema de Compatibilidade (Genéricas)
+--------------------------------------------------
+
+Para a maioria das chamadas de sistema, a mesma implementação de 64 bits pode
+ser invocada mesmo quando o programa do espaço do usuário é, ele próprio, de 32
+bits; mesmo se os parâmetros da chamada de sistema incluírem um ponteiro
+explícito, isso é tratado de forma transparente.
+
+No entanto, existem algumas situações em que uma camada de compatibilidade
+(compatibility layer) é necessária para lidar com as diferenças de tamanho entre
+32 bits e 64 bits.
+
+A primeira é se o kernel de 64 bits também suportar programas de espaço do
+usuário de 32 bits e, portanto, precisar analisar áreas de memória
+(``__user``) que poderiam conter valores de 32 bits ou 64 bits. Em particular,
+isso é necessário sempre que um argumento de chamada de sistema for:
+
+ - um ponteiro para um ponteiro
+ - um ponteiro para uma struct que contém um ponteiro (por exemplo,
+ ``struct iovec __user *``)
+ - um ponteiro para um tipo integral de tamanho variável (``time_t``,
+ ``off_t``, ``long``, ...)
+ - um ponteiro para uma struct que contém um tipo integral de tamanho variável.
+
+A segunda situação que requer uma camada de compatibilidade é se um dos
+argumentos da chamada de sistema tiver um tipo que é explicitamente de 64 bits,
+mesmo em uma arquitetura de 32 bits, por exemplo, ``loff_t`` ou ``__u64``. Neste
+caso, um valor que chega ao kernel de 64 bits vindo de uma aplicação de 32 bits
+será dividido em dois valores de 32 bits, que precisarão ser remontados na
+camada de compatibilidade.
+
+(Note que um argumento de chamada de sistema que seja um ponteiro para um tipo
+explícito de 64 bits **não** precisa de uma camada de compatibilidade; por
+exemplo, os argumentos do :manpage:`splice(2)` do tipo ``loff_t __user *`` não
+disparam a necessidade de uma chamada de sistema ``compat_``.)
+
+A versão de compatibilidade da chamada de sistema é chamada de
+``compat_sys_xyzzy()`` e é adicionada com a macro ``COMPAT_SYSCALL_DEFINEn()``,
+de forma análoga à macro SYSCALL_DEFINEn. Esta versão da implementação roda como
+parte de um kernel de 64 bits, mas espera receber valores de parâmetros de 32
+bits e faz o que for necessário para lidar com eles. (Tipicamente, a versão
+``compat_sys_`` converte os valores para versões de 64 bits e chama a versão
+``sys_``, ou ambas chamam uma função interna comum de implementação).
+
+O ponto de entrada compat também precisa de um protótipo de função
+correspondente em ``include/linux/compat.h``, marcado como asmlinkage para
+corresponder à maneira como as chamadas de sistema são invocadas::
+
+ asmlinkage long compat_sys_xyzzy(...);
+
+Se a chamada de sistema envolver uma estrutura cujo layout seja diferente em
+sistemas de 32 bits e 64 bits, digamos ``struct xyzzy_args``, então o arquivo de
+cabeçalho ``include/linux/compat.h`` também deve incluir uma versão compat da
+estrutura (``struct compat_xyzzy_args``), onde cada campo de tamanho variável
+tenha o tipo ``compat_`` correspondente ao tipo na ``struct xyzzy_args``. A
+rotina ``compat_sys_xyzzy()`` pode então usar essa estrutura ``compat_`` para
+analisar os argumentos vindos de uma invocação de 32 bits.
+
+Por exemplo, se existirem os campos::
+
+ struct xyzzy_args {
+ const char __user *ptr;
+ __kernel_long_t varying_val;
+ u64 fixed_val;
+ /* ... */
+ };
+
+na struct xyzzy_args, então a struct compat_xyzzy_args teria::
+
+ struct compat_xyzzy_args {
+ compat_uptr_t ptr;
+ compat_long_t varying_val;
+ u64 fixed_val;
+ /* ... */
+ };
+
+A lista genérica de chamadas de sistema também precisa de ajustes para permitir
+a versão compat; a entrada em ``include/uapi/asm-generic/unistd.h`` deve usar
+``__SC_COMP`` em vez de ``__SYSCALL``::
+
+ #define __NR_xyzzy 292
+ __SC_COMP(__NR_xyzzy, sys_xyzzy, compat_sys_xyzzy)
+
+Para resumir, você precisa de:
+
+ - uma macro ``COMPAT_SYSCALL_DEFINEn(, ...)`` para o ponto de entrada compat
+ - protótipo correspondente em ``include/linux/compat.h``
+ - (se necessário) struct de mapeamento de 32 bits em ``include/linux/compat.h``
+ - instância de ``__SC_COMP``, e não de ``__SYSCALL``, em
+ ``include/uapi/asm-generic/unistd.h``
+
+Desde a versão 6.11
+~~~~~~~~~~~~~~~~~~~
+
+Isso se aplica a todas as arquiteturas listadas em
+:ref:`Desde a versão 6.11<pt_BR_syscall_generic_6_11>` sob "Implementação Genérica de
+Chamadas de Sistema", exceto arm64. Veja
+:ref:`Chamadas de Sistema de Compatibilidade (arm64)<pt_BR_compat_arm64>` para mais
+informações.
+
+Você precisa estender a entrada em ``scripts/syscall.tbl`` com uma coluna extra
+para indicar que um programa de espaço do usuário de 32 bits rodando em um
+kernel de 64 bits deve atingir o ponto de entrada compat::
+
+ 468 common sys_xyzzy compat_sys_xyzzy
+
+Para resumir, você precisa de:
+
+ - ``COMPAT_SYSCALL_DEFINEn(, ...)`` para o ponto de entrada compat
+ - Protótipo correspondente em ``include/linux/compat.h``
+ - Modificação da entrada em ``scripts/syscall.tbl`` para incluir uma coluna
+ "compat" extra
+ - (Se necessário) Struct de mapeamento de 32 bits em ``include/linux/compat.h``
+
+
+.. _pt_BR_compat_arm64:
+
+Chamadas de Sistema de Compatibilidade (arm64)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+No arm64, existe uma tabela de syscall dedicada para chamadas de sistema de
+compatibilidade voltadas para o espaço do usuário de 32 bits (AArch32):
+``arch/arm64/tools/syscall_32.tbl``. Você precisa adicionar uma linha adicional
+a esta tabela especificando o ponto de entrada compat::
+
+ 468 common sys_xyzzy compat_sys_xyzzy
+
+
+Chamadas de Sistema de Compatibilidade (x86)
+--------------------------------------------
+
+Para interligar a arquitetura x86 de uma chamada de sistema com uma versão de
+compatibilidade, as entradas nas tabelas de syscall precisam ser ajustadas.
+
+Primeiro, a entrada em ``arch/x86/entry/syscalls/syscall_32.tbl`` ganha uma
+coluna extra para indicar que um programa de espaço do usuário de 32 bits rodando
+em um kernel de 64 bits deve atingir o ponto de entrada compat::
+
+ 380 i386 sys_xyzzy __ia32_compat_sys_xyzzy
+
+Segundo, você precisa definir o que deve acontecer para a versão da ABI x32 da
+nova chamada de sistema. Há uma escolha aqui: o layout dos argumentos deve
+corresponder à versão de 64 bits ou à versão de 32 bits.
+
+Se houver um ponteiro para um ponteiro envolvido, a decisão é fácil: x32 é
+ILP32 (inteiro, long e ponteiro possuem 32 bits), portanto o layout deve
+corresponder à versão de 32 bits, e a entrada em
+``arch/x86/entry/syscalls/syscall_64.tbl`` é dividida para que os programas x32
+atinjam o wrapper de compatibilidade::
+
+ 333 64 sys_xyzzy
+ ...
+ 555 x32 __x32_compat_sys_xyzzy
+
+Se não houver ponteiros envolvidos, então é preferível reutilizar a chamada de
+sistema de 64 bits para a ABI x32 (e, consequentemente, a entrada em
+``arch/x86/entry/syscalls/syscall_64.tbl`` permanece inalterada).
+
+Em qualquer um dos casos, você deve verificar se os tipos envolvidos no layout
+dos seus argumentos de fato se mapeiam exatamente do x32 (-mx32) para os seus
+equivalentes de 32 bits (-m32) ou 64 bits (-m64).
+
+
+Chamadas de Sistema com Retorno para Outro Local
+------------------------------------------------
+
+Para a maioria das chamadas de sistema (syscalls), assim que a execução é
+concluída, o programa do usuário continua exatamente de onde parou -- na
+próxima instrução, com a pilha idêntica e a maior parte dos registradores no
+mesmo estado de antes da chamada, além do mesmo espaço de memória virtual.
+
+No entanto, algumas poucas chamadas de sistema agem de forma diferente. Elas
+podem retornar para um local distinto (``rt_sigreturn``), alterar o espaço de
+memória (``fork``/``vfork``/``clone``) ou até mesmo modificar a arquitetura
+(``execve``/``execveat``) do programa.
+
+Para permitir isso, a implementação da chamada de sistema no kernel pode
+precisar salvar e restaurar registradores adicionais na pilha do kernel,
+garantindo controle total de onde e como a execução continuará após a syscall.
+
+Isso é específico de cada arquitetura (arch-specific), mas tipicamente envolve
+a definição de pontos de entrada em assembly que salvam/restauram esses
+registradores adicionais e invocam o ponto de entrada real da chamada de
+sistema.
+
+Para x86_64, isso é implementado como um ponto de entrada ``stub_xyzzy`` em
+``arch/x86/entry/entry_64.S``, e a entrada correspondente na tabela de syscalls
+(``arch/x86/entry/syscalls/syscall_64.tbl``) é ajustada para refletir::
+
+ 333 common stub_xyzzy
+
+O equivalente para programas de 32 bits executados em um kernel de 64 bits é
+normalmente chamado de ``stub32_xyzzy`` e implementado em
+``arch/x86/entry/entry_64_compat.S``, com o respectivo ajuste na tabela de
+syscalls em ``arch/x86/entry/syscalls/syscall_32.tbl``::
+
+ 380 i386 sys_xyzzy stub32_xyzzy
+
+Se a chamada de sistema precisar de uma camada de compatibilidade (como na
+seção anterior), a versão ``stub32_`` precisará chamar a versão
+``compat_sys_`` da chamada de sistema em vez da versão nativa de 64 bits. Além
+disso, se a implementação da ABI x32 não for compartilhada com a versão
+x86_64, sua tabela de syscalls também precisará invocar um stub que direcione
+para a versão ``compat_sys_``.
+
+Por questões de integridade, também é recomendado configurar um mapeamento para
+que o User-Mode Linux (UML) continue funcionando -- sua tabela de syscalls fará
+referência a ``stub_xyzzy``, mas o build do UML não inclui a implementação de
+``arch/x86/entry/entry_64.S`` (já que o UML simula registradores, etc.). Corrigir
+isso é tão simples quanto adicionar um #define em
+``arch/x86/um/sys_call_table_64.c``::
+
+ #define stub_xyzzy sys_xyzzy
+
+
+Outros Detalhes
+---------------
+
+A maior parte do kernel trata as chamadas de sistema de maneira genérica, mas
+há exceções ocasionais que podem precisar de atualização para a sua chamada
+de sistema específica.
+
+O subsistema de auditoria (audit) é um desses casos especiais; ele inclui
+funções (específicas de cada arquitetura) que classificam alguns tipos
+especiais de chamada de sistema -- especificamente operações de abertura de
+arquivo (``open``/``openat``), execução de programa (``execve``/``exeveat``) ou
+multiplexador de socket (``socketcall``). Se a sua nova chamada de sistema for
+análoga a uma dessas, o sistema de auditoria deverá ser atualizado.
+
+De forma mais geral, se existir uma chamada de sistema atual que seja análoga
+à sua nova chamada de sistema, vale a pena fazer um grep em todo o kernel pela
+chamada existente para verificar se não há outros casos especiais.
+
+
+Testes
+------
+
+Uma nova chamada de sistema deve, obviamente, ser testada; também é útil
+fornecer aos revisores uma demonstração de como os programas do espaço do
+usuário (user space) usarão a chamada de sistema. Uma boa maneira de combinar
+esses objetivos é incluir um programa simples de autoteste em um novo diretório
+sob ``tools/testing/selftests/``.
+
+Para uma nova chamada de sistema, obviamente não haverá uma função de wrapper
+na libc e, portanto, o teste precisará invocá-la usando ``syscall()``; além
+disso, se a chamada de sistema envolver uma nova estrutura visível para o
+espaço do usuário, o cabeçalho correspondente precisará ser instalado para
+compilar o teste.
+
+Certifique-se de que o autoteste seja executado com sucesso em todas as
+arquiteturas suportadas. Por exemplo, verifique se ele funciona quando compitado
+como um programa ABI x86_64 (-m64), x86_32 (-m32) e x32 (-mx32).
+
+Para testes mais extensos e minuciosos de novas funcionalidades, você também
+deve considerar a adição de testes ao Linux Test Project ou ao projeto
+xfstests para alterações relacionadas
+
+Página de Manual (Man Page)
+---------------------------
+
+Todas as novas chamadas de sistema devem vir acompanhadas de uma página de
+manual completa, idealmente usando a marcação groff, mas texto simples também
+é aceitável. Se o groff for utilizado, é útil incluir uma versão ASCII pré-
+renderizada da página de manual no e-mail de apresentação (cover letter) do
+conjunto de patches (patchset), para a conveniência dos revisores.
+
+A página de manual deve ser enviada com cópia (cc) para
+linux-man@vger.kernel.org. Para mais detalhes, consulte
+https://www.kernel.org/doc/man-pages/patches.html
+
+
+Não invoque Chamadas de Sistema dentro do Kernel
+------------------------------------------------
+
+As chamadas de sistema são, como mencionado acima, pontos de interação entre o
+espaço do usuário (userspace) e o kernel. Portanto, funções de chamada de
+sistema como ``sys_xyzzy()`` ou ``compat_sys_xyzzy()`` só devem ser chamadas a
+partir do espaço do usuário por meio da tabela de syscalls, e não de outros
+lugares do kernel. Se a funcionalidade da syscall for útil para ser utilizada
+dentro do kernel, precisar ser compartilhada entre uma syscall antiga e uma
+nova, ou precisar ser compartilhada entre uma syscall e sua variante de
+compatibilidade, ela deve ser implementada por meio de uma função auxiliadora
+("helper", como ``ksys_xyzzy()``). Essa função do kernel poderá então ser
+chamada dentro do stub da syscall (``sys_xyzzy()``), do stub da syscall de
+compatibilidade (``compat_sys_xyzzy()``) e/ou de outro código do kernel.
+
+Pelo menos em x86 de 64 bits, será um requisito rígido a partir da versão v4.17
+em diante não chamar funções de chamadas de sistema no kernel. Essa arquitetura
+utiliza uma convenção de chamada diferente para chamadas de sistema na qual a
+``struct pt_regs`` é decodificada dinamicamente em um wrapper de syscall, que
+então repassa o processamento para a função real da syscall. Isso significa que
+apenas os parâmetros realmente necessários para uma syscall específica são
+passados durante a entrada da syscall, em vez de preencher seis registradores da
+CPU com conteúdos aleatórios do espaço do usuário o tempo todo (o que poderia
+causar problemas sérios no decorrer da cadeia de chamadas).
+
+Além disso, as regras sobre como os dados podem ser acessados diferem entre os
+dados do kernel e os dados do usuário. Essa é outra razão pela qual chamar
+``sys_xyzzy()`` geralmente é uma má ideia.
+
+Exceções a essa regra são permitidas apenas em substituições (overrides)
+específicas de cada arquitetura, wrappers de compatibilidade específicos de cada
+arquitetura ou outros códigos dentro do diretório arch/.
+
+Referências e Fontes
+--------------------
+
+ - Artigo da LWN por Michael Kerrisk sobre o uso do argumento flags em chamadas
+ de sistema:
+ https://lwn.net/Articles/585415/
+ - Artigo da LWN por Michael Kerrisk sobre como lidar com flags desconhecidas
+ em uma chamada de sistema: https://lwn.net/Articles/588444/
+ - Artigo da LWN por Jake Edge descrevendo restrições em argumentos de chamadas
+ de sistema de 64 bits: https://lwn.net/Articles/311630/
+ - Par de artigos da LWN por David Drysdale que descrevem detalhadamente os
+ caminhos de implementação de chamadas de sistema para a v3.14:
+
+ - https://lwn.net/Articles/604287/
+ - https://lwn.net/Articles/604515/
+
+ - Os requisitos específicos de arquitetura para chamadas de sistema são
+ discutidos na página de manual :manpage:`syscall(2)`:
+ http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES
+ - E-mails compilados de Linus Torvalds discutindo os problemas com ``ioctl()``:
+ https://yarchive.net/comp/linux/ioctl.html
+ - "How to not invent kernel interfaces", Arnd Bergmann,
+ https://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdf
+ - Artigo da LWN por Michael Kerrisk sobre evitar novos usos de CAP_SYS_ADMIN:
+ https://lwn.net/Articles/486306/
+ - Recomendação de Andrew Morton para que todas as informações relacionadas a
+ uma nova chamada de sistema venham na mesma thread de e-mail:
+ https://lore.kernel.org/r/20140724144747.3041b208832bbdf9fbce5d96@linux-foundation.org
+ - Recomendação de Michael Kerrisk para que uma nova chamada de sistema venha
+ acompanhada de uma página de manual:
+ https://lore.kernel.org/r/CAKgNAkgMA39AfoSoA5Pe1r9N+ZzfYQNvNPvcRN7tOvRb8+v06Q@mail.gmail.com
+ - Sugestão de Thomas Gleixner para que a vinculação (wire-up) do x86 esteja em
+ um commit separado:
+ https://lore.kernel.org/r/alpine.DEB.2.11.1411191249560.3909@nanos
+ - Sugestão de Greg Kroah-Hartman de que é bom que novas chamadas de sistema
+ venham acompanhadas de uma página de manual e um autoteste:
+ https://lore.kernel.org/r/20140320025530.GA25469@kroah.com
+ - Discussão de Michael Kerrisk sobre uma nova chamada de sistema versus a
+ extensão de :manpage:`prctl(2)`:
+ https://lore.kernel.org/r/CAHO5Pa3F2MjfTtfNxa8LbnkeeU8=YJ+9tDqxZpw7Gz59E-4AUg@mail.gmail.com
+ - Sugestão de Ingo Molnar de que as chamadas de sistema que envolvem múltiplos
+ argumentos devem encapsular esses argumentos em uma struct, a qual inclua um
+ campo de tamanho (size) para fins de extensibilidade futura:
+ https://lore.kernel.org/r/20150730083831.GA22182@gmail.com
+ - Excentricidades de numeração decorrentes do uso (e reuso) de flags do espaço
+ de numeração O_*:
+
+ - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness
+ check")
+ - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc
+ conflict")
+ - commit bb458c644a59 ("Safer ABI for O_TMPFILE")
+
+ - Discussão de Matthew Wilcox sobre restrições em argumentos de 64 bits:
+ https://lore.kernel.org/r/20081212152929.GM26095@parisc-linux.org
+ - Recomendação de Greg Kroah-Hartman de que flags desconhecidas devem ser
+ fiscalizadas/policiadas:
+ https://lore.kernel.org/r/20140717193330.GB4703@kroah.com
+ - Recomendação de Linus Torvalds de que as chamadas de sistema x32 devem
+ preferir a compatibilidade com as versões de 64 bits em vez das versões de
+ 32 bits:
+ https://lore.kernel.org/r/CA+55aFxfmwfB7jbbrXxa=K7VBYPfAvmu3XOkGrLbB1UFjX1+Ew@mail.gmail.com
+ - Série de patches revisando a infraestrutura da tabela de chamadas de sistema
+ para utilizar scripts/syscall.tbl em múltiplas arquiteturas:
+ https://lore.kernel.org/lkml/20240704143611.2979589-1-arnd@kernel.org
--
2.47.3
^ permalink raw reply related [flat|nested] 8+ messages in thread