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

[Lucas Adryell Ramalho <lucasadramalho@gmail.com>]

Translate driver_development_debugging_guide and add to debugging/index.rst.

Signed-off-by: Lucas Adryell Ramalho <lucasadramalho@gmail.com>
---
 .../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..4d0613ddf
--- /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 registros/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 registros
+- 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