aboutsummaryrefslogtreecommitdiff
path: root/documentation/content/pt-br/articles/geom-class/_index.adoc
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/content/pt-br/articles/geom-class/_index.adoc')
-rw-r--r--documentation/content/pt-br/articles/geom-class/_index.adoc177
1 files changed, 90 insertions, 87 deletions
diff --git a/documentation/content/pt-br/articles/geom-class/_index.adoc b/documentation/content/pt-br/articles/geom-class/_index.adoc
index e108fc373c..f05d77126f 100644
--- a/documentation/content/pt-br/articles/geom-class/_index.adoc
+++ b/documentation/content/pt-br/articles/geom-class/_index.adoc
@@ -1,8 +1,11 @@
---
-title: Escrevendo uma classe GEOM
authors:
- - author: Ivan Voras
+ -
+ author: 'Ivan Voras'
email: ivoras@FreeBSD.org
+description: 'Um guia sobre os internals do GEOM e sobre como escrever sua própria classe GEOM'
+tags: ["GEOM", "kernel", "modules", "FreeBSD"]
+title: 'Escrevendo uma classe GEOM'
trademarks: ["freebsd", "intel", "general"]
---
@@ -40,7 +43,7 @@ endif::[]
[.abstract-title]
Resumo
-Este texto documenta alguns pontos de partida no desenvolvimento de classes GEOM e módulos do kernel em geral. Supõe-se que o leitor esteja familiarizado com a programação C do userland.
+Este texto documenta alguns pontos de partida no desenvolvimento de classes GEOM e módulos de kernel em geral. Pressupõe-se que o leitor esteja familiarizado com a programação de espaço de usuário em C.
'''
@@ -52,27 +55,27 @@ toc::[]
[[intro-docs]]
=== Documentação
-A documentação sobre programação do kernel é escassa - é uma das poucas áreas na qual não há quase nada de tutoriais amigáveis, e a frase "usa a fonte!" realmente é verdadeira. No entanto, existem alguns pedaços (alguns deles seriamente desatualizados) flutuando por ai e que devem ser estudados antes de começar a codificar:
+A documentação sobre programação de kernel é escassa - é uma das poucas áreas em que quase não há tutoriais amigáveis, e a frase "use o código fonte!" realmente é verdadeira. No entanto, existem alguns fragmentos (alguns deles seriamente desatualizados) circulando que devem ser estudados antes de começar a codificar:
-* O extref:{developers-handbook}[Manual do Desenvolvedor do FreeBSD] - parte do projeto de documentação, ele não contém nenhum informação específica para a programação do kernel, mas possui algumas informações gerais úteis.
-* O extref:{arch-handbook}[Manual de Arquitetura do FreeBSD] - também do projeto de documentação, contém descrições de várias instalações e procedimentos de baixo nível. O capítulo mais importante é o 13, extref:{arch-handbook}[Escrevendo drivers de dispositivo FreeBSD, driverbasics].
-* A seção Blueprints do site do http://www.freebsddiary.org[FreeBSD Diary] contém vários artigos interessantes sobre os recursos do kernel.
-* As páginas de manual na seção 9 - para documentação importante sobre as funções do kernel.
-* A página man man:geom[4] e os http://phk.freebsd.dk/pubs/[Slides sobre o GEOM de PHK] - para uma introdução geral do subsistema GEOM.
-* Páginas de manual man:g_bio[9], man:g_event[9], man:g_data[9], man:g_geom[9], man:g_provider[9] man:g_consumer[9], man:g_access[9] & outros ligados a partir deles, para documentação sobre funcionalidades específicas.
-* A página do manual man:style[9] - para documentação sobre as convenções de estilo de codificação que devem ser seguidas para qualquer código que se destine a ser incorporado à Árvore do Subversion do FreeBSD.
+* O extref:{developers-handbook}[Handbook do Desenvolvedor do FreeBSD] - parte do projeto de documentação, não contém nada específico sobre programação do kernel, mas sim algumas informações úteis em geral.
+* O extref:{arch-handbook}[Handbook de Arquitetura do FreeBSD] - também do projeto de documentação, contém descrições de várias instalações e procedimentos de baixo nível. O capítulo mais importante é o 13, extref:{arch-handbook}[Escrevendo drivers de dispositivos FreeBSD, driverbasics].
+* A seção Blueprints do site http://www.freebsddiary.org contém vários artigos interessantes sobre as facilidades do kernel.
+* As páginas de manual da seção 9 - para documentação importante sobre as funções do kernel.
+* A página de manual man:geom[4] e os slides sobre o GEOM do PHK em http://phk.freebsd.dk/pubs/ - para uma introdução geral ao subsistema GEOM.
+* As páginas de manual man:g_bio[9], man:g_event[9], man:g_data[9], man:g_geom[9], man:g_provider[9], man:g_consumer[9], man:g_access[9] e outras vinculadas a elas, para documentação sobre funcionalidades específicas.
+* A página de manual man:style[9] - para documentação sobre as convenções de estilo de codificação que devem ser seguidas para qualquer código que seja commitado para a árvore do FreeBSD.
[[prelim]]
== Preliminares
-A melhor maneira de fazer o desenvolvimento do kernel é ter (pelo menos) dois computadores separados. Um deles conteria o ambiente de desenvolvimento e o código fonte, e o outro seria usado para testar o código recém escrito, inicializando por meio da rede e montando seu sistema de arquivo a partir do primeiro computador. Desta forma, se o novo código contiver erros e travar a máquina, isso não irá atrapalhar o código fonte (e nem nenhum outros dado "vivo"). O segundo sistema nem sequer requer um monitor adequado. Em vez disso, ele pode ser conectado por meio de um cabo serial ou KVM ao primeiro computador.
+A melhor maneira de desenvolver para o kernel é ter (pelo menos) dois computadores separados. Um deles conteria o ambiente de desenvolvimento e as fontes, e o outro seria usado para testar o código recém-escrito por meio do boot e montagem de sistemas de arquivos por rede do primeiro. Dessa forma, se o novo código contiver erros e travar a máquina, ele não afetará as fontes (e outros dados "ao vivo"). O segundo sistema nem mesmo precisa de uma tela adequada. Em vez disso, ele pode ser conectado com um cabo serial ou KVM para o primeiro.
-Mas, como nem todo mundo tem dois ou mais computadores à mão, há algumas coisas que podem ser feitas para preparar um sistema "vivo " para desenvolver código para o kernel. Esta configuração também é aplicável para desenvolvimento em uma máquina virtual criada com o http://www.vmware.com/[VMWare] ou com o http://www.qemu.org/[QEmu] (a próxima melhor coisa depois de uma máquina de desenvolvimento dedicada).
+No entanto, como nem todo mundo tem dois ou mais computadores disponíveis, existem algumas coisas que podem ser feitas para preparar um sistema "ao vivo" para o desenvolvimento de código do kernel. Essa configuração também é aplicável para desenvolvimento em uma máquina virtual http://www.vmware.com/[VMWare] ou http://www.qemu.org/[QEmu] (a próxima melhor opção depois de uma máquina de desenvolvimento dedicada).
[[prelim-system]]
=== Modificando um sistema para desenvolvimento
-Para qualquer programação do kernel, um kernel com a opção `INVARIANTS` ativada é obrigatório. Então, digite estas linhas no seu arquivo de configuração do kernel:
+Para qualquer programação de kernel, é essencial ter um kernel com `INVARIANTS` ativado. Portanto, adicione as seguintes opções no arquivo de configuração do kernel:
[.programlisting]
....
@@ -80,7 +83,7 @@ options INVARIANT_SUPPORT
options INVARIANTS
....
-Para ter um maior nível de depuração, você também devrá incluir o suporte ao WITNESS, o qual irá alertá-lo sobre erros relacionados a bloqueios (locking):
+Para obter mais depuração, você também deve incluir o suporte a WITNESS, que alertará sobre erros de bloqueio:
[.programlisting]
....
@@ -88,16 +91,16 @@ options WITNESS_SUPPORT
options WITNESS
....
-Para depurar despejos de memória, é necessário um kernel com símbolos de depuração:
+Para depurar despejos de falhas (crash dumps), é necessário um kernel com símbolos de depuração:
[.programlisting]
....
makeoptions DEBUG=-g
....
-Com a maneira usual de instalar o kernel (`make installkernel`) o kernel de depuração não será instalado automaticamente. Ele é chamado de [.filename]#kernel.debug# e fica localizado em [.filename]#/usr/obj/usr/src/sys/KERNELNAME/#. Por conveniência, deve ser copiado para [.filename]#/boot/kernel/#.
+Com a maneira usual de instalar o kernel (`make installkernel`), o kernel de depuração não será instalado automaticamente. Ele é chamado de [.filename]#kernel.debug# e fica localizado em [.filename]#/usr/obj/usr/src/sys/NOME_DO_KERNEL/#. Por conveniência, ele deve ser copiado para [.filename]#/boot/kernel/#.
-Outra conveniência é habilitar o depurador do kernel para que você possa examinar o panic do kernel quando isso acontece. Para isso, insira as seguintes linhas no seu arquivo de configuração do kernel:
+Outra conveniência é habilitar o depurador do kernel para que você possa examinar um kernel panic quando ele ocorrer. Para isso, adicione as seguintes linhas no arquivo de configuração do kernel:
[.programlisting]
....
@@ -113,7 +116,7 @@ Para que isso funcione, você pode precisar definir um sysctl (se ele não estiv
debug.debugger_on_panic=1
....
-Kernel panics acontecerão, portanto, deve-se ter cuidado com o cache do sistema de arquivos. Em particular, ter o softupdates habilitado pode significar que a versão mais recente do arquivo pode ser perdida se um panic ocorrer antes de ser committed para armazenamento. Desativar o softupdates produz um grande impacto na performance e ainda não garante a consistência dos dados. A montagem do sistema de arquivos com a opção "sync" é necessária para isso. Para um compromisso, os atrasos do cache de softupdates podem ser encurtados. Existem três sysctl's que são úteis para isso (melhor ser configurado em [.filename]#/etc/sysctl.conf#):
+Panics do kernel podem acontecer, portanto, é preciso ter cuidado com o cache do sistema de arquivos. Em particular, ter softupdates pode significar que a versão mais recente de um arquivo pode ser perdida se ocorrer um panic antes que seja gravada no armazenamento. Desabilitar o softupdates implica em uma grande perda de desempenho e ainda não garante a consistência dos dados. É necessário montar o sistema de arquivos com a opção "sync" para garantir isso. Como um compromisso, os atrasos do cache do softupdates podem ser encurtados. Existem três sysctl que são úteis para isso (melhor configurados em [.filename]#/etc/sysctl.conf#):
[.programlisting]
....
@@ -124,7 +127,7 @@ kern.metadelay=3
Os números representam segundos.
-Para depurar os panics do kernel, os dumps do núcleo do kernel são necessários. Como um kernel panic pode tornar os sistemas de arquivos inutilizáveis, esse despejo de memória é primeiramente gravado em uma partição bruta. Normalmente, esta é a partição de swap. Essa partição deve ser pelo menos tão grande quanto a RAM física na máquina. Na próxima inicialização, o despejo é copiado para um arquivo normal. Isso acontece depois que os sistemas de arquivos são verificados e montados e antes que o swap seja ativado. Isto é controlado com duas variáveis [.filename]#/etc/rc.conf#:
+Para depurar panics do kernel, são necessários os despejos de núcleo do kernel. Como um kernel panic pode tornar os sistemas de arquivos inutilizáveis, este despejo de falhas é primeiro gravado em uma partição raw. Geralmente, isso é feito na partição de swap. Esta partição deve ter pelo menos o tamanho da RAM física da máquina. No próximo boot, o despejo é copiado para um arquivo regular. Isso acontece após a verificação e montagem dos sistemas de arquivos e antes que o swap seja ativado. Isso é controlado com duas variáveis do arquivo [.filename]#/etc/rc.conf#:
[.programlisting]
....
@@ -132,35 +135,35 @@ dumpdev="/dev/ad0s4b"
dumpdir="/usr/core
....
-A variável `dumpdev` especifica a partição de swap e `dumpdir` informa ao sistema onde no sistema de arquivos ele deverá realocar o dump principal na reinicialização.
+A variável `dumpdev` especifica a partição de swap e `dumpdir` informa ao sistema onde no sistema de arquivos realocar o core dump no reboot.
-A gravação de core dumps é lenta e leva muito tempo, então se você tiver muita memória (>256M) e muitos panics, pode ser frustrante sentar e esperar enquanto isso é feito (duas vezes - primeiro para gravar para o swap, depois para realocá-lo para o sistema de arquivos). É conveniente limitar a quantidade de RAM que o sistema usará através de uma variável do [.filename]#/boot/loader.conf#:
+Gravar o core dump do kernel é lento e leva muito tempo, portanto, se você tiver muita memória (>256 MB) e muitos panics, pode ser frustrante esperar enquanto isso é feito (duas vezes - primeiro para gravá-lo na troca, depois para realocá-lo no sistema de arquivos). É conveniente, portanto, limitar a quantidade de RAM que o sistema usará por meio de um ajuste no [.filename]#/boot/loader.conf#:
[.programlisting]
....
hw.physmem="256M"
....
-Se os panics são frequentes e os sistemas de arquivos são grandes (ou você simplesmente não confia em softupdates + background fsck), é aconselhável desligar o fsck em background através da variável [.filename]#/etc/rc.conf#:
+Se os panics forem frequentes e os sistemas de arquivos forem grandes (ou se você simplesmente não confiar no softupdates + fsck em segundo plano), é aconselhável desativar o fsck em segundo plano por meio da seguinte variável no arquivo [.filename]#/etc/rc.conf#:
[.programlisting]
....
background_fsck="NO"
....
-Dessa forma, os sistemas de arquivos sempre serão verificados quando necessário. Observe que, com o fsck em segundo plano, um novo panic pode acontecer enquanto ele está verificando os discos. Novamente, a maneira mais segura é não ter muitos sistemas de arquivos locais, usando o outro computador como um servidor NFS.
+Dessa forma, os sistemas de arquivos serão sempre verificados quando necessário. Observe que, com o fsck em segundo plano, um novo panic pode ocorrer enquanto os discos estão sendo verificados. Novamente, a maneira mais segura é não ter muitos sistemas de arquivos locais, usando outro computador como um servidor NFS.
[[prelim-starting]]
=== Começando o projeto
-Para o propósito de criar uma nova classe GEOM, um subdiretório vazio deve ser criado sob um diretório arbitrário acessível pelo usuário. Você não precisa criar o diretório do módulo em [.filename]#/usr/src#.
+Para criar uma nova classe GEOM, um subdiretório vazio deve ser criado em um diretório arbitrário acessível pelo usuário. Você não precisa criar o diretório do módulo em [.filename]#/usr/src#.
[[prelim-makefile]]
=== O Makefile
-É uma boa prática criar [.filename]#Makefiles# para cada projeto de codificação não trivial, o que obviamente inclui módulos do kernel.
+É uma boa prática criar arquivos [.filename]#Makefile# para todos os projetos de codificação não triviais, o que inclui, é claro, módulos do kernel.
-Criar o [.filename]#Makefile# é simples graças a um extenso conjunto de rotinas auxiliares fornecidas pelo sistema. Em suma, aqui está um exemplo de como um Makefile [.filename]#mínimo# para um módulo do kernel se parece:
+Criar o arquivo [.filename]#Makefile# é simples graças a um extenso conjunto de rotinas auxiliares fornecidas pelo sistema. Em resumo, aqui está como um [.filename]#Makefile# mínimo se parece para um módulo do kernel:
[.programlisting]
....
@@ -170,7 +173,7 @@ KMOD=geom_journal
.include <bsd.kmod.mk>
....
-Este [.filename]#Makefile# (com nomes de arquivos alterados) serve para qualquer módulo do kernel, e uma classe GEOM pode residir em apenas um módulo do kernel. Se mais de um arquivo for necessário, liste-o na variável `SRCS`, separado com espaço em branco de outros nomes de arquivos.
+Este [.filename]#Makefile# (com nomes de arquivo alterados) serve para qualquer módulo do kernel e uma classe GEOM pode residir em apenas um módulo do kernel. Se mais de um arquivo for necessário, liste-os na variável `SRCS`, separados por espaço de outros nomes de arquivo.
[[kernelprog]]
== Programação do kernel do FreeBSD
@@ -178,34 +181,34 @@ Este [.filename]#Makefile# (com nomes de arquivos alterados) serve para qualquer
[[kernelprog-memalloc]]
=== Alocação de memória
-Veja o man:malloc[9]. A alocação básica de memória é apenas ligeiramente diferente do seu userland equivalente. Mais notavelmente, `malloc`() e `free`() aceitam parâmetros adicionais conforme descrito na página do manual.
+Consulte man:malloc[9]. A alocação básica de memória é apenas ligeiramente diferente da sua equivalente no espaço do usuário. Mais notavelmente, `malloc()` e `free()` aceitam parâmetros adicionais conforme descrito na página do manual.
-Um "malloc type" deve ser declarado na seção de declaração de um arquivo fonte, assim:
+Um "malloc type" deve ser declarado na seção de declaração de um arquivo de código fonte, por exemplo desta forma:
[.programlisting]
....
static MALLOC_DEFINE(M_GJOURNAL, "gjournal data", "GEOM_JOURNAL Data");
....
-Para usar esta macro, os cabeçalhos [.filename]#sys/param.h#, [.filename]#sys/kernel.h# e [.filename]#sys/malloc.h# devem ser incluídos.
+Para usar essa macro, os cabeçalhos [.filename]#sys/param.h#, [.filename]#sys/kernel.h# e [.filename]#sys/malloc.h# devem ser incluídos.
-Existe outro mecanismo para alocar memória, o UMA (Universal Memory Allocator). Veja man:uma[9] para detalhes, mas ele é um tipo especial de alocador usado principalmente para alocação rápida de listas compostas de itens do mesmo tamanho (por exemplo, matrizes dinâmicas de estruturas).
+Existe outro mecanismo para alocar memória, o UMA (Universal Memory Allocator). Consulte man:uma[9] para obter detalhes, mas é um tipo especial de alocador usado principalmente para alocação rápida de listas compostas por itens do mesmo tamanho (por exemplo, matrizes dinâmicas de estruturas).
[[kernelprog-lists]]
=== Listas e filas
-Veja man:queue[3]. Há MUITOS casos quando uma lista de coisas precisa ser mantida. Felizmente, essa estrutura de dados é implementada (de várias maneiras) por macros C incluídas no sistema. O tipo de lista mais usado é o TAILQ, porque é o mais flexível. É também aquele com os maiores requisitos de memória (seus elementos são duplamente vinculados) e também o mais lento (embora a variação de velocidade seja mais da ordem de várias instruções da CPU, portanto, ela não deve ser levada a sério).
+Consulte man:queue[3]. Existem MUITOS casos em que uma lista de coisas precisa ser mantida. Felizmente, essa estrutura de dados é implementada (de várias maneiras) por macros em C incluídas no sistema. O tipo de lista mais usado é TAILQ porque é o mais flexível. Também é o que tem os maiores requisitos de memória (seus elementos são duplamente vinculados) e também o mais lento (embora a variação de velocidade seja da ordem de algumas instruções de CPU a mais, então não deve ser levado a sério).
-Se a velocidade de recuperação de dados for muito importante, veja man:tree[3] e man:hashinit[9].
+Se a velocidade de recuperação de dados é muito importante, consulte man:tree[3] e man:hashinit[9].
[[kernelprog-bios]]
=== BIOS
-A estrutura `bio` é usada para todas e quaisquer operações de Input/Output relativas ao GEOM. Ele basicamente contém informações sobre qual dispositivo ('provedor') deve satisfazer a solicitação, tipo de pedido, offset, comprimento, ponteiro para um buffer e um monte de sinalizadores "específicos do usuário" e campos que podem ajudar a implementar vários hacks.
+A estrutura `bio` é usada para todas e quaisquer operações de entrada/saída relacionadas ao GEOM. Basicamente, ela contém informações sobre qual dispositivo ('provider') deve satisfazer a solicitação, tipo de solicitação, deslocamento, comprimento, ponteiro para um buffer e um conjunto de flags e campos "específicos do usuário" que podem ajudar a implementar vários ajustes.
-O importante aqui é que os `bio`-s são tratados de forma assíncrona. Isso significa que, na maior parte do código, não há nenhum análogo as chamadas man:read[2] e man:write[2] que não retornam até que uma solicitação seja feita. Em vez disso, uma função fornecida pelo desenvolvedor é chamada como uma notificação quando a solicitação é concluída (ou resulta em erro).
+O importante aqui é que os ``bio``s são manipulados de forma assíncrona. Isso significa que, na maioria das partes do código, não há um análogo das chamadas man:read[2] e man:write[2] do espaço do usuário que não retornam até que uma solicitação seja concluída. Em vez disso, uma função fornecida pelo desenvolvedor é chamada como uma notificação quando a solicitação é concluída (ou resulta em erro).
-O modelo de programação assíncrona (também chamado de "orientado a eventos") é um pouco mais difícil do que o imperativo muito mais usado no userland (pelo menos leva um tempo para se acostumar com isso). Em alguns casos, as rotinas auxiliares `g_write_data`() e `g_read_data`() podem ser usadas, mas __nem sempre__. Em particular, elas não podem ser usadas quando um mutex é mantido; por exemplo, o mutex de topologia GEOM ou o mutex interno mantido durante as funções `.start`() e `.stop`().
+O modelo de programação assíncrono (também chamado de "event-driven") é um pouco mais difícil do que o muito usado modelo imperativo usado no espaço do usuário (pelo menos leva um tempo para se acostumar). Em alguns casos, as rotinas auxiliares `g_write_data()` e `g_read_data()` podem ser usadas, mas __nem sempre__. Em particular, elas não podem ser usadas quando um mutex é mantido; por exemplo, o mutex de topologia GEOM ou o mutex interno mantido durante as funções `.start()` e `.stop()`.
[[geom]]
== Programação GEOM
@@ -218,15 +221,15 @@ Se o desempenho máximo não for necessário, uma maneira muito mais simples de
[[geom-class]]
=== Classe GEOM
-Classes GEOM são transformações nos dados. Essas transformações podem ser combinadas em uma forma de árvore. Instâncias de classes GEOM são chamadas de __geoms__.
+As classes GEOM são transformações nos dados. Essas transformações podem ser combinadas de maneira semelhante a uma árvore. As instâncias de classes GEOM são chamadas de __geoms__.
-Cada classe GEOM possui vários "métodos de classe" que são chamados quando não há nenhuma instância geom disponível (ou simplesmente não estão vinculados a uma única instância):
+Cada classe GEOM tem vários "métodos de classe" que são chamados quando não há uma instância geom disponível (ou simplesmente não estão vinculados a uma única instância):
-* `.init` é chamada quando o GEOM toma conhecimento de uma classe GEOM (quando o módulo do kernel é carregado).
-* `.fini` é chamada quando o GEOM abandona a classe (quando o módulo é descarregado)
-* `.taste` é chamada next, uma vez para cada provedor que o sistema tiver disponível. Se aplicável, essa função geralmente criará e iniciará uma instância geom.
-* `.destroy_geom` é chamada quando o geom deve ser desfeito
-* `.ctlconf` é chamado quando o usuário solicita a reconfiguração do geom existente
+* O `.init` é chamado quando o GEOM toma conhecimento de uma classe GEOM (quando o módulo do kernel é carregado.)
+* O `.fini` é chamado quando o GEOM abandona a classe (quando o módulo é descarregado)
+* O `.taste` é chamado em seguida, uma vez para cada provider que o sistema tem disponível. Se aplicável, esta função geralmente criará e iniciará uma instância geom.
+* O `.destroy_geom` é chamado quando o geom deve ser desmontado
+* O `.ctlconf` é chamado quando o usuário solicita a reconfiguração do geom existente
Também são definidas as funções de evento GEOM, que serão copiadas para a instância geom.
@@ -237,13 +240,13 @@ Estas funções são chamadas a partir da thread g_event do kernel.
[[geom-softc]]
=== Softc
-O nome "softc" é um termo legado para "dados privados do driver". O nome provavelmente vem do termo arcaico "bloco de controle de software". No GEOM, ele é uma estrutura (mais precisamente: ponteiro para uma estrutura) que pode ser anexada a uma instância geom para armazenar quaisquer dados que sejam privados para a instância geom. A maioria das classes GEOM possui os seguintes membros:
+O nome "softc" é um termo legado para "dados privados do driver". O nome provavelmente vem do termo arcaico "bloco de controle de software". No GEOM, é uma estrutura (mais precisamente, um ponteiro para uma estrutura) que pode ser anexada a uma instância geom para manter quaisquer dados que sejam privados à instância geom. A maioria das classes GEOM tem os seguintes membros:
-* `struct g_provider *provider` : O "provedor" que este geom instância
-* `uint16_t n_disks` : Número de consumidores que este geom consome
-* `struct g_consumer \**disks`: Array de `struct g_consumer*`. (Não é possível usar apenas uma única via indireta porque o struct g_consumer* é criado em nosso nome pela GEOM).
+* `struct g_provider *provider`: Instância geom criada a partir do provider correspondente
+* `uint16_t n_disks`: Número de consumidores que esta instância geom consome
+* `struct g_consumer \**disks`: Array de `struct g_consumer*`. (Não é possível usar apenas uma única indireção porque os `struct g_consumer*` são criados em nosso nome pelo GEOM).
-A estrutura `softc` contém todo o estado da instância geom. Cada instância geom possui seu próprio softc.
+A estrutura `softc` contém todo o estado da instância geom. Cada instância geom tem sua própria estrutura `softc`.
[[geom-metadata]]
=== Metadados
@@ -264,22 +267,22 @@ Os metadados estão localizados no último setor do provedor (e, portanto, devem
A sequência de eventos é:
-* o usuário chama o utilitário man:geom[8] (ou um de seus equivalentes hardlinked)
-* o utilitário descobre qual classe geom ele é suposto manipular e procura pela biblioteca [.filename]#geom_CLASSNAME.so# (geralmente em [.filename]#/lib/geom#).
-* ele man:dlopen[3]-s a biblioteca, extrai as definições dos parâmetros da linha de comandos e funções auxiliares.
+* O usuário chama o utilitário man:geom[8] (ou um comandos alternativos para o mesmo utilitário)
+* O utilitário determina qual classe geom ele deve manipular e procura pela biblioteca [.filename]#geom_CLASSNAME.so# (geralmente em [.filename]#/lib/geom#).
+* O utilitário utiliza a função man:dlopen[3] para carregar dinamicamente a biblioteca, extrair as definições dos parâmetros de linha de comando e funções auxiliares.
No caso da criação/rotulação de um novo geom, isso é o que acontece:
-* O man:geom[8] procura no argumento da linha de comando pelo comando (geralmente `label`) e chama uma função auxiliar .
+* O comando man:geom[8] procura na linha de comando pelo comando (geralmente `label`) e chama uma função auxiliar correspondente.
* A função auxiliar verifica parâmetros e reúne metadados, que são gravados em todos os provedores envolvidos.
-* Este "estraga" geoms existentes (se existirem) e inicializa uma nova rodada de "degustação" dos provedores. A classe geom pretendida reconhece os metadados e carrega o geom.
+* Isso "anula" os geoms existentes (se houver) e inicializa uma nova rodada de "degustação" dos providers. A classe geom pretendida reconhece os metadados e coloca o geom em funcionamento.
(A sequência de eventos acima é dependente da implementação, mas todo o código existente funciona assim, e é suportado pelas bibliotecas.)
[[geom-command]]
=== Estrutura do Comando GEOM
-A biblioteca helper [.filename]#geom_CLASSNAME.so# exporta a estrutura `class_commands`, que é uma matriz dos elementos `struct g_command`. Os comandos são uniformes no formato e se parecem com:
+A biblioteca auxiliar [.filename]#geom_CLASSNAME.so# exporta a estrutura `class_commands`, que é um array de elementos `struct g_command`. Os comandos têm um formato uniforme e se parecem com:
[.programlisting]
....
@@ -288,72 +291,72 @@ A biblioteca helper [.filename]#geom_CLASSNAME.so# exporta a estrutura `class_co
Verbos comuns são:
-* label - para gravar metadados em dispositivos para que eles possam ser reconhecidos em degustações e criados em geoms
-* destroy - para destruir metadados, para que as geoms sejam destruídas
+* label - para escrever metadados nos dispositivos para que possam ser reconhecidos durante o processo de "tasting" e trazidos à tona em geoms
+* destroy - para destruir metadados, fazendo com que os geoms sejam destruídos
Opções comuns são:
-* `-v` : be verbose
-* `-f` : force
+* `-v` : ser verboso (mostrar mais informações)
+* `-f` : forçar
-Muitas ações, como rotular e destruir metadados, podem ser executadas no userland. Para isso, `struct g_command` fornece o campo `gc_func` que pode ser definido para uma função (no mesmo [.filename]#.so#) que será chamada para processar um verbo. Se `gc_func` for NULL, o comando será passado para o módulo do kernel, para a função `.ctlreq` da classe geom.
+Muitas ações, como rotular e destruir metadados, podem ser executadas no espaço de usuário. Para isso, `struct g_command` fornece o campo `gc_func`, que pode ser definido como uma função (no mesmo arquivo [.filename]#.so#) que será chamada para processar um verbo. Se `gc_func` for NULL, o comando será passado para o módulo do kernel, para a função `.ctlreq` da classe geom.
[[geom-geoms]]
=== Geoms
-Geoms são instâncias de classes GEOM. Eles possuem dados internos (uma estrutura softc) e algumas funções com as quais eles respondem a eventos externos.
+Os Geoms são instâncias das classes GEOM. Eles têm dados internos (uma estrutura softc) e algumas funções com as quais eles respondem a eventos externos.
As funções de evento são:
-* `.acess`: calcula permissões (leitura / escrita / exclusiva)
-* `.dumpconf`: retorna informações formatadas em XML sobre o geom
-* `.orphan`: chamado quando algum provedor subjacente é desconectado
-* `.spoiled`: chamado quando algum provedor subjacente é gravado
-* `.start`: lida com I/O
+* `.access` : calcula as permissões (leitura/escrita/exclusiva)
+* `.dumpconf` : uma função que retorna informações formatadas em XML sobre o geom
+* `.orphan` : chamado quando algum provedor subjacente é desconectado
+* `.spoiled` : chamado quando algum provedor subjacente é escrito
+* `.start` : lida com operações de entrada/saída (I/O)
-Estas funções são chamadas a partir da thread `g_down` do kernel e não pode haver sleeping neste contexto, (veja a definição de sleeping em outro lugar) o que limita um pouco o que pode ser feito, mas força o manuseio a ser rápido .
+Essas funções são chamadas a partir da thread do kernel `g_down` e não é permitido dormir nesse contexto (consulte a definição de dormir em outro lugar), o que limita bastante o que pode ser feito, mas força o tratamento a ser rápido.
-Destes, a função mais importante para fazer o trabalho útil real é a função `.start`(), que é chamada quando uma requisição BIO chega para um provedor gerenciado por uma instância da classe geom.
+A função mais importante para realizar trabalho útil é a função `.start()`, que é chamada quando uma solicitação BIO chega para um provider gerenciado por uma instância de classe geom.
[[geom-threads]]
=== Threads GEOM
Existem três threads de kernel criados e executados pelo framework GEOM:
-* `g_down` : trata de solicitações provenientes de entidades de alto nível (como uma solicitação do userland) no caminho para dispositivos físicos
-* `g_up` : lida com respostas de drivers de dispositivos para solicitações feitas por entidades de nível superior
-* `g_event` : lida com todos os outros casos: criação de instâncias geom, contagem de acessos, eventos "spoil", etc.
+* `g_down` : responsável por lidar com solicitações vindas de entidades de alto nível (como uma solicitação do espaço do usuário) a caminho de dispositivos físicos
+* `g_up` : Lida com as respostas dos drivers de dispositivo às solicitações feitas por entidades de nível superior
+* `g_event` : lida com todos os outros casos: criação de instâncias de geom, contagem de acesso, eventos de "spoil", etc.
-Quando um processo do usuário emite um pedido de "leitura de dados X no deslocamento Y de um arquivo", isto é o que acontece:
+Quando um processo do usuário emite uma solicitação para "ler dados X no deslocamento Y de um arquivo", o seguinte acontece:
* O sistema de arquivos converte o pedido em uma instância struct bio e o transmite para o subsistema GEOM. Ele sabe o que a instância geom deve manipular porque os sistemas de arquivos são hospedados diretamente em uma instância geom.
* A requisição termina como uma chamada para a função `.start`() feita para a thread g_down e atinge a instância geom de nível superior.
-* Essa instância geom de nível superior (por exemplo, o segmentador de partições) determina que a solicitação deve ser roteada para uma instância de nível inferior (por exemplo, o driver de disco). Ele faz uma cópia da solicitação bio (solicitações bio _SEMPRE_ precisam ser copiadas entre instâncias, com `g_clone_bio`()!), modifica os campos de dados offset e de provedor de destino e executa a cópia com `g_io_request`()
-* O driver de disco obtém a solicitação bio também como uma chamada para `.start`() na thread `g_down`. Ela fala com o hardware, recupera os dados e chama `g_io_deliver`() na bio.
-* Agora, a notificação de bio conclusão "borbulha" na thread `g_up`. Primeiro, o slicer de partição obtém `.done`() chamado na thread `g_up`, ele usa as informações armazenadas na bio para liberar a estrutura `bio` clonada (com `g_destroy_bio`()) e chama `g_io_deliver`() no pedido original.
+* Esta instância geom de nível superior (por exemplo, o "partition slicer") determina que a solicitação deve ser encaminhada para uma instância de nível inferior (por exemplo, o driver de disco). Ela faz uma cópia da solicitação bio (solicitações bio PRECISAM SEMPRE ser copiadas entre instâncias, com `g_clone_bio`()!), modifica o deslocamento dos dados e os campos do provider de destino e executa a cópia com `g_io_request`()
+* O driver de disco também recebe a requisição bio como uma chamada para `.start`() na thread `g_down`. Ele conversa com o hardware, recebe os dados de volta e chama `g_io_deliver`() na bio.
+* Agora, a notificação da conclusão do bio "sobe" na thread `g_up`. Primeiro, o particionador recebe `.done`() chamado na thread `g_up`, usa as informações armazenadas no bio para liberar a estrutura de `bio` clonada (com `g_destroy_bio`()) e chama `g_io_deliver`() no pedido original.
* O sistema de arquivos obtém os dados e os transfere para o usuário.
-Veja a página de manual para o man:g_bio[9] para obter informações sobre como os dados são passados para frente e para trás na estrutura `bio` (observe em particular os campos `bio_parent` e `bio_children` e como eles são manipulados).
+Consulte a página do manual man:g_bio[9] para obter informações sobre como os dados são passados de um lado para o outro na estrutura `bio` (observe em particular os campos `bio_parent` e `bio_children` e como eles são manipulados).
-Uma característica importante: __NAS THREADS G_UP E G_DOWN NÃO SE PODE DORMIR (SELEEPING)__. Isso significa que nenhuma das seguintes coisas pode ser feita nessas threads (a lista não é completa, mas apenas informativa):
+Uma característica importante é que __ NÃO PODEM HAVER CHAMADAS DE FUNÇÃO QUE BLOQUEIEM O PROCESSO (DURMAM) NAS THREADS G_UP E G_DOWN__. Isso significa que nenhuma das seguintes coisas pode ser feita nesses threads (a lista é apenas informativa e não completa):
* Chamadas para `msleep`() e `tsleep`(), obviamente.
-* Chamadas para `g_write_data`() e `g_read_data`(), porque estes dormem entre passar os dados para os consumidores e retornar.
-* Esperando I/O.
-* Chamadas para man:malloc[9] e `uma_zalloc`() com o conjunto de flags `M_WAITOK`
-* sx e outros sleepable locks
+* Chamadas para `g_write_data`() e `g_read_data()`, pois elas dormem entre a passagem dos dados para os consumidores e o retorno.
+* Aguardando I/O.
+* Chamadas a man:malloc[9] e `uma_zalloc`() com a flag `M_WAITOK` definida
+* sx e outros tipos de bloqueios sleepable
-Esta restrição está aqui para impedir que o código GEOM obstrua o caminho da solicitação de I/O, já que sleeping normalmente não é limitado pelo tempo e não pode haver garantias sobre quanto tempo levará (também existem algumas outras razões mais técnicas). Isso também significa que não existe muito o que possa ser feito nessas threads; por exemplo, quase qualquer coisa complexa requer alocação de memória. Felizmente, existe uma saída: criar threads adicionais no kernel.
+Essa restrição foi imposta para evitar que o código GEOM obstrua o caminho de solicitação de E/S, já que a espera geralmente não está relacionada ao tempo e não há garantias sobre quanto tempo levará (há outras razões técnicas também). Isso também significa que não há muito o que se possa fazer nessas threads; por exemplo, quase qualquer coisa complexa requer alocação de memória. Felizmente, há uma saída: criar threads adicionais do kernel.
[[geom-kernelthreads]]
=== Threads de kernel para uso no código GEOM
-As threads do kernel são criadas com a função man:kthread_create[9], e elas são semelhantes aos threads do userland no comportamento, eles somente não podem retornar ao chamador para exprimir a conclusão, mas deve chamar man:kthread_exit[9].
+Threads do Kernel são criados com a função man:kthread_create[9], e eles são parecidos com threads de espaço de usuário em termos de comportamento, apenas que não podem retornar ao chamador para indicar término, mas devem chamar man:kthread_exit[9].
-No código GEOM, o uso usual de threads é para descarregar o processamento de requisições da thread `g_down` (a função `.start`). Estas threads se parecem com um "event handlers": elas têm uma lista encadeada de eventos associados a elas (nos quais eventos podem ser postados por várias funções em várias threads, portanto, devem ser protegidos por um mutex), pegam os eventos da lista, um por um, e processa-os em uma grande instrução `switch`().
+No código do GEOM, o uso usual de threads é para descarregar o processamento de solicitações da thread `g_down` (a função `.start()`). Essas threads se parecem com "manipuladores de eventos": elas têm uma lista vinculada de eventos associados a elas (na qual eventos podem ser postados por várias funções em várias threads, então ela deve ser protegida por um mutex), pegam os eventos da lista um por um e os processam em uma grande declaração `switch()`.
-A principal vantagem de usar uma thread para lidar com solicitações de I/O é que ela pode dormir quando necessário. Agora, isso parece bom, mas deve ser cuidadosamente pensado. Dormir é bom e muito conveniente, mas pode ser muito efetivo em destruir o desempenho da transformação geom. As classes extremamente sensíveis ao desempenho provavelmente devem fazer todo o trabalho na chamada de função `.start`(), tomando muito cuidado para lidar com erros de falta de memória e similares.
+O principal benefício de usar uma thread para lidar com as solicitações de E/S é que ela pode dormir quando necessário. Agora, isso parece bom, mas deve ser cuidadosamente pensado. Dormir é bem conveniente, mas pode destruir efetivamente o desempenho da transformação geom. As classes extremamente sensíveis ao desempenho provavelmente devem fazer todo o trabalho na chamada de função `.start()`, tendo muito cuidado para lidar com erros de falta de memória e similares.
-O outro benefício de ter uma thread de manipulação de eventos como essa é serializar todas as solicitações e respostas provenientes de diferentes threads geom em uma thread. Isso também é muito conveniente, mas pode ser lento. Na maioria dos casos, o tratamento de pedidos `.done`() pode ser deixado para a thread `g_up`.
+O outro benefício de ter uma thread de tratamento de eventos é a serialização de todas as solicitações e respostas vindas de diferentes threads do geom em uma única thread. Isso também é muito conveniente, mas pode ser lento. Na maioria dos casos, o tratamento de solicitações `.done`() pode ser deixado para a thread `g_up`.
-Mutexes no kernel do FreeBSD (veja man:mutex[9]) têm uma distinção de seus primos mais comuns do userland - o código não pode dormir enquanto estiver segurando um mutex). Se o código precisar dormir muito, os bloqueios man:sx[9] podem ser mais apropriados. Por outro lado, se você faz quase tudo em um único thread, você pode se safar sem utilizar mutexes.
+Mutexes no kernel do FreeBSD (veja man:mutex[9]) possuem uma distinção em relação às suas contrapartes mais comuns no userland - o código não pode dormir enquanto segura um mutex. Se o código precisa dormir muito, as travas man:sx[9] podem ser mais apropriadas. Por outro lado, se você fizer quase tudo em um único thread, pode se livrar completamente do uso de mutexes.