Re: [PATCH v2 1/3] docs: translations: pt_BR: process: add driver_development_debugging_guide

[Daniel Pereira]

On Tue, Oct 20, 2026 at 1:13 AM Lucas Adryell Ramalho
<lucasadramalho@xxxxxxxxx> wrote:

Hi Lucas,

Thanks for the v2, the "registradores" change looks good. I built the
full documentation tree with this series applied and found one issue
in this patch, plus two small nits.

> +Simples printk()
> +~~~~~~~~~~~~~~~~

Nit: "printk() simples" reads more naturally in Portuguese.

> +Com esses arquivos, é possível armazenar valores de variáveis ou gerar
> +dumps de registradores/memória, ou ainda tornar esses arquivos graváveis e modificar
> +valores/configurações no driver.

Nit: after the v2 change this line is 84 columns long, please rewrap
it to stay within 80 columns.

> +Interfaces do devcoredump
> +~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +.. kernel-doc:: include/linux/devcoredump.h
> +
> +.. kernel-doc:: drivers/base/devcoredump.c

These two kernel-doc directives document the same C functions that the
English document already documents, so "make htmldocs" now reports 7
new warnings:

WARNING: Duplicate C declaration, also defined at
translations/pt_BR/process/debugging/driver_development_debugging_guide:102.

(and the same for lines 256, 280, 293, 320, 343 and 449).

Please drop both directives and point readers to the original
document instead, for example:

A documentação das interfaces está disponível na
:doc:`versão original em inglês
</process/debugging/driver_development_debugging_guide>`.

Thanks,
Daniel


Em ter., 20 de out. de 2026 às 01:14, Lucas Adryell Ramalho
<lucasadramalho@xxxxxxxxx> escreveu:
>
> Translate the driver debugging guide and update debugging/index.rst.
>
> Signed-off-by: Lucas Adryell Ramalho <lucasadramalho@xxxxxxxxx>
> ---
>  .../driver_development_debugging_guide.rst    | 244 ++++++++++++++++++
>  .../pt_BR/process/debugging/index.rst         |   6 +-
>  2 files changed, 249 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/translations/pt_BR/process/debugging/driver_development_debugging_guide.rst
>
> diff --git a/Documentation/translations/pt_BR/process/debugging/driver_development_debugging_guide.rst b/Documentation/translations/pt_BR/process/debugging/driver_development_debugging_guide.rst
> new file mode 100644
> index 000000000..a5c318821
> --- /dev/null
> +++ b/Documentation/translations/pt_BR/process/debugging/driver_development_debugging_guide.rst
> @@ -0,0 +1,244 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +==========================================================
> +Orientações de depuração para o desenvolvimento de drivers
> +==========================================================
> +
> +Este documento serve como ponto de partida e referência geral para a
> +depuração de drivers de dispositivos.
> +Enquanto este guia se concentra na depuração que exige recompilar o
> +módulo ou o kernel, o :doc:`guia de depuração em espaço de usuário
> +</process/debugging/userspace_debugging_guide>` orienta sobre ferramentas
> +como depuração dinâmica, Ftrace e outras ferramentas úteis para investigar
> +problemas e analisar comportamentos.
> +Para orientações gerais sobre depuração, consulte o
> +:doc:`guia geral de depuração </process/debugging/index>`.
> +
> +.. contents::
> +    :depth: 3
> +
> +As seções a seguir mostram as ferramentas disponíveis.
> +
> +printk() e amigos
> +-----------------
> +
> +Esses derivados de printf() podem enviar mensagens a destinos diferentes e
> +podem ser ativados ou desativados dinamicamente, quando há suporte para isso.
> +
> +Simples printk()
> +~~~~~~~~~~~~~~~~
> +
> +O método clássico é simples e pode ser muito útil para desenvolver módulos
> +rapidamente ou extrair dados necessários para investigar problemas.
> +
> +Pré-requisito: ``CONFIG_PRINTK`` (geralmente habilitado por padrão)
> +
> +**Prós**:
> +
> +- Não há necessidade de aprender nada, simples de usar
> +- Fácil de adaptar às suas necessidades, incluindo a formatação dos dados
> +  (consulte :doc:`/core-api/printk-formats`) e a visibilidade no log
> +- Pode causar atrasos na execução do código (benéfico para confirmar se o
> +  tempo é um fator)
> +
> +**Contras**:
> +
> +- Requer reconstrução do kernel/módulo
> +- Pode causar atrasos na execução do código (o que pode fazer com que os
> +  problemas não sejam reproduzíveis)
> +
> +Para a documentação completa, consulte :doc:`/core-api/printk-basics`.
> +
> +trace_printk()
> +~~~~~~~~~~~~~~
> +
> +Pré-requisito: ``CONFIG_DYNAMIC_FTRACE`` & ``#include <linux/ftrace.h>``
> +
> +É um pouco menos confortável de usar que printk(), porque as mensagens devem
> +ser lidas no arquivo de rastreamento (consulte :ref:`read_ftrace_log`),
> +em vez de no log do kernel. Ainda assim, é muito útil quando printk() causa
> +atrasos indesejados na execução do código, tornando os problemas intermitentes
> +ou difíceis de reproduzir.
> +
> +Se isso ainda causar problemas de temporização, tente trace_puts().
> +
> +Para a documentação completa, consulte trace_printk().
> +
> +dev_dbg
> +~~~~~~~
> +
> +Chamada de depuração que pode ser controlada por
> +:ref:`process/debugging/userspace_debugging_guide:dynamic debug` e inclui
> +informações adicionais sobre o dispositivo associado.
> +
> +**Quando é apropriado manter uma mensagem de depuração no código?**
> +
> +
> +As mensagens de depuração permanentes devem ajudar o desenvolvedor a investigar
> +problemas no funcionamento do driver. Avaliar quais mensagens são úteis é mais
> +uma arte do que uma ciência, mas algumas diretrizes estão nas
> +:ref:`Diretrizes de estilo de codificação
> +<translations/pt_BR/process/coding-style:13) Imprimindo mensagens do kernel>`.
> +Em quase todos os casos, as mensagens de depuração não devem ser enviadas
> +ao upstream, pois um driver funcional deve ser silencioso.
> +
> +printk personalizado
> +~~~~~~~~~~~~~~~~~~~~
> +
> +Exemplo::
> +
> +  #define core_dbg(fmt, arg...) do { \
> +         if (core_debug) \
> +                 printk(KERN_DEBUG pr_fmt("core: " fmt), ## arg); \
> +         } while (0)
> +
> +**Quando você deve fazer isso?**
> +
> +É melhor usar pr_debug(), que pode ser ativado ou desativado posteriormente
> +com a depuração dinâmica. Além disso, muitos drivers ativam essas mensagens
> +por meio de uma variável como ``core_debug``, definida por um parâmetro do
> +módulo. No entanto, os parâmetros de módulo `não são mais recomendados
> +<https://lore.kernel.org/all/2024032757-surcharge-grime-d3dd@gregkh>`_.
> +
> +Ftrace
> +------
> +
> +Criando um ponto de rastreamento Ftrace personalizado
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Um ponto de rastreamento adiciona um gancho ao seu código que será chamado e
> +registrado quando o ponto de rastreamento estiver ativado. Isso pode ser usado,
> +por exemplo, para rastrear a execução de um ramo condicional ou para gerar um
> +dump do estado interno em pontos específicos do fluxo do código durante uma
> +sessão de depuração.
> +
> +Aqui está uma descrição básica de
> +:ref:`como implementar novos pontos de rastreamento
> +<trace/tracepoints:usage>`.
> +
> +Para a documentação completa sobre rastreamento de eventos, consulte
> +:doc:`/trace/events`.
> +
> +Para a documentação completa do Ftrace, consulte :doc:`/trace/ftrace`.
> +
> +DebugFS
> +-------
> +
> +Pré-requisito: ``CONFIG_DEBUG_FS`` e ``#include <linux/debugfs.h>``
> +
> +O DebugFS difere das outras abordagens de depuração, pois não grava mensagens
> +no log do kernel nem adiciona rastros ao código. Em vez disso, permite que o
> +desenvolvedor gerencie um conjunto de arquivos.
> +Com esses arquivos, é possível armazenar valores de variáveis ou gerar
> +dumps de registradores/memória, ou ainda tornar esses arquivos graváveis e modificar
> +valores/configurações no driver.
> +
> +Possíveis casos de uso, entre outros:
> +
> +- Armazenar valores de registradores
> +- Acompanhar variáveis
> +- Armazenar erros
> +- Armazenar configurações
> +- Ativar ou desativar uma configuração, como o modo de depuração
> +- Injeção de erros
> +
> +Isso é especialmente útil quando o tamanho de um dump de dados dificultaria
> +sua análise como parte do log geral do kernel (por exemplo, ao despejar dados
> +brutos de um fluxo de bits) ou quando você não precisa acompanhar todos os
> +valores continuamente, mas quer poder inspecioná-los quando necessário.
> +
> +A ideia geral é:
> +
> +- Criar um diretório durante a execução do ``probe`` (``struct dentry *parent =
> +  debugfs_create_dir("my_driver", NULL);``)
> +- Criar um arquivo:
> +
> +  ``debugfs_create_u32("my_value", 444, parent, &my_variable);``
> +
> +  - Neste exemplo, o arquivo está localizado em
> +    ``/sys/kernel/debug/my_driver/my_value`` (com permissões de leitura para
> +    usuário/grupo/outros)
> +  - Qualquer leitura do arquivo retornará o conteúdo atual da variável
> +    ``my_variable``
> +
> +- Limpe o diretório ao remover o dispositivo
> +  (``debugfs_remove(parent);``)
> +
> +Para a documentação completa, consulte :doc:`/filesystems/debugfs`.
> +
> +KASAN, UBSAN, lockdep e outros verificadores de erros
> +-----------------------------------------------------
> +
> +KASAN (Kernel Address Sanitizer)
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Pré-requisito: ``CONFIG_KASAN``
> +
> +O KASAN é um detector dinâmico de erros de memória que ajuda a identificar
> +bugs de uso após liberação (*use-after-free*) e acessos fora dos limites
> +(*out-of-bounds*). Ele utiliza instrumentação em tempo de compilação para
> +verificar cada acesso à memória.
> +
> +Para a documentação completa veja :doc:`/dev-tools/kasan`.
> +
> +UBSAN (Undefined Behavior Sanitizer)
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Pré-requisito: ``CONFIG_UBSAN``
> +
> +O UBSAN usa instrumentação do compilador e verificações em tempo de execução
> +para detectar comportamentos indefinidos. Ele identifica vários problemas,
> +incluindo estouro de inteiro com sinal e índice de array fora dos limites.
> +
> +Para a documentação completa, consulte :doc:`/dev-tools/ubsan`.
> +
> +lockdep (Lock Dependency Validator)
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Pré-requisito: ``CONFIG_DEBUG_LOCKDEP``
> +
> +O lockdep é um validador de dependências de bloqueio em tempo de execução que
> +detecta possíveis deadlocks e outros problemas relacionados a bloqueios no
> +kernel. Ele rastreia a aquisição e a liberação de bloqueios, constrói um
> +gráfico de dependências e o analisa em busca de possíveis deadlocks. O lockdep
> +é especialmente útil para validar a ordem correta dos bloqueios no kernel.
> +
> +PSI (Pressure stall information tracking)
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Pré-requisito: ``CONFIG_PSI``
> +
> +O PSI é uma ferramenta de medição que identifica a sobrecarga excessiva dos
> +recursos de hardware, capaz de causar perda de desempenho ou até encerramentos
> +de processos por falta de memória (OOM).
> +
> +coredump do dispositivo
> +-----------------------
> +
> +Pré-requisito: ``CONFIG_DEV_COREDUMP`` e ``#include <linux/devcoredump.h>``
> +
> +Essa infraestrutura permite que um driver envie dados arbitrários ao espaço do
> +usuário. Ela é usada com frequência em conjunto com o udev ou outro aplicativo
> +de espaço de usuário que monitore os uevents do kernel indicando que o dump
> +está pronto. O udev pode ter regras para copiar o arquivo para armazenamento e
> +análise de longo prazo, pois, por padrão, os dados do dump são removidos após
> +cinco minutos. Esses dados são analisados com ferramentas específicas do driver
> +ou com o GDB.
> +
> +Um coredump do dispositivo pode ser criado a partir de uma área vmalloc, com
> +métodos de leitura e liberação ou como uma lista scatter/gather.
> +
> +Você pode encontrar um exemplo de implementação em:
> +`drivers/media/platform/qcom/venus/core.c
> +<https://elixir.bootlin.com/linux/v6.11.6/source/drivers/media/platform/qcom/venus/core.c#L30>`__,
> +na camada HCI do Bluetooth, em vários drivers sem fio e em vários
> +drivers DRM.
> +
> +Interfaces do devcoredump
> +~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +.. kernel-doc:: include/linux/devcoredump.h
> +
> +.. kernel-doc:: drivers/base/devcoredump.c
> +
> +**Copyright** ©2024 : Collabora
> diff --git a/Documentation/translations/pt_BR/process/debugging/index.rst b/Documentation/translations/pt_BR/process/debugging/index.rst
> index b223fae34..5c2c73493 100644
> --- a/Documentation/translations/pt_BR/process/debugging/index.rst
> +++ b/Documentation/translations/pt_BR/process/debugging/index.rst
> @@ -7,9 +7,13 @@ Dicas de depuração para desenvolvedores do Kernel Linux
>  Guias gerais
>  ------------
>
> +.. toctree::
> +   :maxdepth: 1
> +
> +   Orientações de depuração para o desenvolvimento de drivers <driver_development_debugging_guide>
> +
>  Todolist:
>
> -*   driver_development_debugging_guide
>  *   gdb-kernel-debugging
>  *   kgdb
>  *   userspace_debugging_guide
> --
> 2.55.0
>