Diretrizes do módulo do fornecedor

Use as diretrizes a seguir para aumentar a robustez e a confiabilidade dos módulos de seu fornecedor. Muitas diretrizes, quando seguidas, podem ajudar a determinar a ordem correta de carregamento do módulo e a ordem na qual os drivers devem investigar os dispositivos.

Observação: as diretrizes estão listadas em ordem de importância e refletem a frequência de erros encontrados nos módulos do fornecedor.

Um módulo pode ser uma biblioteca ou um driver .

• Módulos de biblioteca são bibliotecas que fornecem APIs para outros módulos usarem. Esses módulos normalmente não são específicos de hardware. Exemplos de módulos de biblioteca incluem um módulo de criptografia AES, a estrutura remoteproc que é compilada como um módulo e um módulo logbuffer. O código do módulo em module_init() é executado para configurar estruturas de dados, mas nenhum outro código é executado a menos que seja acionado por um módulo externo.

• Módulos de driver são drivers que investigam ou se associam a um tipo específico de dispositivo. Esses módulos são específicos de hardware. Exemplos de módulos de driver incluem UART, PCIe e hardware de codificador de vídeo. Os módulos de driver são ativados somente quando seu dispositivo associado está presente no sistema.

  • Se o dispositivo não estiver presente, o único código de módulo executado é o código module_init() que registra o driver com a estrutura principal do driver.

  • Se o dispositivo estiver presente e o driver sondar ou vincular com êxito esse dispositivo, outro código de módulo poderá ser executado.

Use o módulo init/exit corretamente

Os módulos de driver devem registrar um driver em module_init() e cancelar o registro de um driver em module_exit() . Uma maneira simples de impor essas restrições é usar macros wrapper, o que evita o uso direto de module_init() , *_initcall() ou module_exit() .

• Para módulos que podem ser descarregados, use module_ subsystem _driver() . Exemplos: module_platform_driver() , module_i2c_driver() e module_pci_driver() .

• Para módulos que não podem ser descarregados, use builtin_ subsystem _driver() Exemplos: builtin_platform_driver() , builtin_i2c_driver() e builtin_pci_driver() .

Nota: Você pode construir drivers com builtin_ subsystem _driver() como módulos, mas você não pode descarregar esses drivers depois que eles forem carregados com sucesso.

Alguns módulos de driver usam module_init() e module_exit() porque registram mais de um driver. Para um módulo de driver que usa module_init() e module_exit() para registrar vários drivers, tente combinar os drivers em um único driver. Por exemplo, você pode diferenciar usando a string compatible ou os dados auxiliares do dispositivo em vez de registrar drivers separados. Alternativamente, você pode dividir o módulo do driver em dois módulos.

Exceções da função de inicialização e saída

Os módulos de biblioteca não registram drivers e estão isentos de restrições em module_init() e module_exit() , pois podem precisar dessas funções para configurar estruturas de dados, filas de trabalho ou threads de kernel.

Use a macro MODULE_DEVICE_TABLE

Os módulos de driver devem incluir a macro MODULE_DEVICE_TABLE , que permite que o espaço do usuário determine os dispositivos suportados por um módulo de driver antes de carregar o módulo. O Android pode usar esses dados para otimizar o carregamento do módulo, como para evitar o carregamento de módulos para dispositivos que não estão presentes no sistema. Para obter exemplos de uso da macro, consulte o código upstream.

Evite incompatibilidades de CRC devido a tipos de dados declarados para frente

Não inclua arquivos de cabeçalho para obter visibilidade dos tipos de dados declarados para frente. Algumas estruturas, uniões e outros tipos de dados definidos em um arquivo de cabeçalho ( header-Ah ) podem ser declarados para encaminhamento em um arquivo de cabeçalho diferente ( header-Bh ) que normalmente usa ponteiros para esses tipos de dados. Esse padrão de código significa que o kernel está tentando intencionalmente manter a estrutura de dados privada para os usuários de header-Bh .

Os usuários de header-Bh não devem incluir header-Ah para acessar diretamente os internos dessas estruturas de dados declaradas para frente. Isso causa problemas de incompatibilidade de CONFIG_MODVERSIONS CRC (o que gera problemas de conformidade com ABI) quando um kernel diferente (como o kernel GKI) tenta carregar o módulo.

Por exemplo, struct fwnode_handle é definido em include/linux/fwnode.h , mas é declarado como struct fwnode_handle; em include/linux/device.h porque o kernel está tentando manter os detalhes de struct fwnode_handle privados dos usuários de include/linux/device.h . Nesse cenário, não adicione #include <linux/fwnode.h> em um módulo para obter acesso a membros de struct fwnode_handle . Qualquer design no qual você precise incluir esses arquivos de cabeçalho indica um padrão de design ruim.

Não acesse diretamente as estruturas principais do kernel

Acessar ou modificar diretamente as estruturas de dados do núcleo do kernel pode levar a um comportamento indesejável, incluindo vazamentos de memória, travamentos e quebra de compatibilidade com versões futuras do kernel. Uma estrutura de dados é uma estrutura de dados central do kernel quando atende a qualquer uma das seguintes condições:

• A estrutura de dados é definida em KERNEL-DIR /include/ . Por exemplo, struct device e struct dev_links_info . As estruturas de dados definidas em include/linux/soc são isentas.

• A estrutura de dados é alocada ou inicializada pelo módulo, mas torna-se visível para o kernel sendo passada, indiretamente (através de um ponteiro em uma estrutura) ou diretamente, como entrada em uma função exportada pelo kernel. Por exemplo, um módulo de driver cpufreq inicializa o struct cpufreq_driver e o passa como entrada para cpufreq_register_driver() . Após este ponto, o módulo de driver cpufreq não deve modificar struct cpufreq_driver diretamente porque chamar cpufreq_register_driver() torna struct cpufreq_driver visível para o kernel.

• A estrutura de dados não é inicializada pelo seu módulo. Por exemplo, struct regulator_dev retornado por regulator_register() .

Acesse as principais estruturas de dados do kernel apenas por meio de funções exportadas pelo kernel ou por meio de parâmetros explicitamente passados ​​como entrada para ganchos do fornecedor. Se você não tiver uma API ou um gancho de fornecedor para modificar partes de uma estrutura de dados do núcleo do kernel, provavelmente é intencional e você não deve modificar a estrutura de dados dos módulos. Por exemplo, não modifique nenhum campo dentro de struct device ou struct device.links .

• Para modificar device.devres_head , use uma devm_*() como devm_clk_get() , devm_regulator_get() ou devm_kzalloc() .

• Para modificar campos dentro struct device.links , use uma API de link de dispositivo como device_link_add() ou device_link_del() .

Não analise nós devicetree com propriedade compatível

Se um nó de árvore de dispositivos (DT) tiver uma propriedade compatible , um struct device será alocado para ele automaticamente ou quando of_platform_populate() for chamado no nó DT pai (normalmente pelo driver de dispositivo do dispositivo pai). A expectativa padrão (exceto para alguns dispositivos inicializados antecipadamente para o escalonador) é que um nó DT com uma propriedade compatible tenha um struct device e um driver de dispositivo correspondente. Todas as outras exceções já são tratadas pelo código upstream.

Além disso, fw_devlink (anteriormente chamado of_devlink ) considera os nós DT com a propriedade compatible como dispositivos com um struct device alocado que é testado por um driver. Se um nó DT tiver uma propriedade compatible , mas o struct device alocado não for testado, fw_devlink poderá impedir que seus dispositivos consumidores sejam investigados ou impedir que chamadas sync_state() sejam chamadas para seus dispositivos fornecedores.

Se seu driver usa uma of_find_*() (como of_find_node_by_name() ou of_find_compatible_node() ) para encontrar diretamente um nó DT que tenha uma propriedade compatible e então analisar esse nó DT, corrija o módulo escrevendo um driver de dispositivo que possa sondar o dispositivo ou remova a propriedade compatible (possível apenas se não tiver sido upstream). Para discutir alternativas, entre em contato com a equipe do kernel do Android em [e-mail] e esteja preparado para justificar seus casos de uso.

Nota: O uso de fw_devlink é obrigatório para GKI.

Use phandles DT para procurar fornecedores

Consulte um fornecedor usando um phandle (uma referência/ponteiro para um nó DT) no DT sempre que possível. O uso de associações e phandles de DT padrão para se referir a fornecedores permite que fw_devlink (anteriormente of_devlink ) determine automaticamente as dependências entre dispositivos analisando o DT em tempo de execução. O kernel pode então testar automaticamente os dispositivos na ordem correta, eliminando a necessidade de ordenação de carga de módulo ou MODULE_SOFTDEP() .

Observação: os exemplos a seguir especificam os reguladores, mas a mesma diretriz se aplica às associações de DT do fornecedor, como clocks , iio-channels , interrupts , -gpios , pinctrl- , dmas , iommu , phys , extcon e nvmem-cells .

Cenário legado (sem suporte DT no kernel ARM)

Anteriormente, antes que o suporte DT fosse adicionado aos kernels ARM, consumidores, como dispositivos de toque, procuravam fornecedores, como reguladores, usando strings globalmente exclusivas. Por exemplo, o driver ACME PMIC pode registrar ou anunciar vários reguladores (como acme-pmic-ldo1 a acme-pmic-ldo10 ) e um driver de toque pode procurar um regulador usando regulator_get(dev, "acme-pmic-ldo10") . No entanto, em uma placa diferente, o LDO8 pode fornecer o dispositivo de toque, criando um sistema complicado em que o mesmo driver de toque precisa determinar a string de pesquisa correta para o regulador para cada placa em que o dispositivo de toque é usado.

Cenário atual (suporte a DT no kernel ARM)

Depois que o suporte DT foi adicionado aos kernels ARM, os consumidores podem identificar fornecedores no DT consultando o nó da árvore de dispositivos do fornecedor usando um phandle . Os consumidores também podem nomear o recurso com base no que é usado em vez de quem o fornece. Por exemplo, o driver de toque do exemplo anterior poderia usar regulator_get(dev, "core") e regulator_get(dev, "sensor") para obter os fornecedores que alimentam o núcleo e o sensor do dispositivo de toque. O DT associado para tal dispositivo é semelhante ao seguinte exemplo de código:

touch-device {
    compatible = "fizz,touch";
    ...
    core-supply = <&acme_pmic_ldo4>;
    sensor-supply = <&acme_pmic_ldo10>;
};

acme-pmic {
    compatible = "acme,super-pmic";
    ...
    acme_pmic_ldo4: ldo4 {
        ...
    };
    ...
    acme_pmic_ldo10: ldo10 {
        ...
    };
};

Nota: *-supply é a ligação (ou propriedade) padronizada de DT para se referir aos reguladores que fornecem um dispositivo.

Cenário do pior dos dois mundos

Alguns drivers portados de kernels mais antigos incluem o comportamento legado no DT que pega a pior parte do esquema legado e o força no esquema mais recente, destinado a facilitar as coisas. Nesses drivers, o driver consumidor lê a string a ser usada para pesquisa usando uma propriedade DT específica do dispositivo, o fornecedor usa outra propriedade específica do fornecedor para definir o nome a ser usado para registrar o recurso do fornecedor, então o consumidor e o fornecedor continuam usando o mesmo esquema antigo de usar strings para procurar o fornecedor. Neste cenário do pior dos dois mundos:

• O driver de toque usa um código semelhante ao código a seguir:

  str = of_property_read(np, "fizz,core-regulator");
  core_reg = regulator_get(dev, str);
  str = of_property_read(np, "fizz,sensor-regulator");
  sensor_reg = regulator_get(dev, str);
  

• O DT usa código semelhante ao seguinte:

  touch-device {
    compatible = "fizz,touch";
    ...
    fizz,core-regulator = "acme-pmic-ldo4";
    fizz,sensor-regulator = "acme-pmic-ldo4";
  };
  acme-pmic {
    compatible = "acme,super-pmic";
    ...
    ldo4 {
      regulator-name = "acme-pmic-ldo4"
      ...
    };
    ...
    acme_pmic_ldo10: ldo10 {
      ...
      regulator-name = "acme-pmic-ldo10"
    };
  };
  

Observação: se o seu driver implementar esse cenário do pior dos dois mundos, corrija-o imediatamente para usar phandles para procurar fornecedores.

Não modifique os erros da API do framework

APIs de estrutura, como regulator , clocks , irq , gpio , phys e extcon , retornam -EPROBE_DEFER como um valor de retorno de erro para indicar que um dispositivo está tentando testar, mas não pode neste momento, e o kernel deve tentar novamente a análise mais tarde. Para garantir que a função .probe() do seu dispositivo falhe conforme o esperado nesses casos, não substitua ou remapear o valor do erro. Substituir ou remapear o valor do erro pode fazer com que -EPROBE_DEFER seja descartado e fazer com que seu dispositivo nunca seja investigado.

Use variantes de API devm_*()

Quando o dispositivo adquire um recurso usando uma devm_*() , o recurso é liberado automaticamente pelo kernel se o dispositivo falhar na sondagem ou sondar com sucesso e posteriormente for desvinculado. Essa funcionalidade torna o código de tratamento de erros na função probe() mais limpo porque não requer saltos goto para liberar os recursos adquiridos por devm_*() e simplifica as operações de desvinculação do driver.

Lidar com a desvinculação do driver de dispositivo

Seja intencional sobre a desvinculação de drivers de dispositivo e não deixe a desvinculação indefinida porque indefinido não significa não permitido. Você deve implementar totalmente a desvinculação de driver de dispositivo ou desabilitar explicitamente a desvinculação de driver de dispositivo.

Nota: Existem alguns casos em que não fazer nada explicitamente é aceitável porque o kernel lida com todas as operações necessárias.

Implementando a desvinculação do driver de dispositivo

Ao optar por implementar totalmente a desvinculação do driver de dispositivo, desvincule os drivers de dispositivo de forma limpa para evitar vazamentos de memória ou de recursos e problemas de segurança. Você pode vincular um dispositivo a um driver chamando a função probe() de um driver e desvincular um dispositivo chamando a função remove() do driver. Se não existir nenhuma função remove() , o kernel ainda pode desvincular o dispositivo; o núcleo do driver assume que nenhum trabalho de limpeza é necessário pelo driver quando ele se desvincula do dispositivo. Um driver desvinculado de um dispositivo não precisa fazer nenhum trabalho de limpeza explícito quando ambas as condições a seguir forem verdadeiras:

• Todos os recursos adquiridos pela função probe() de um driver são por meio devm_*() .

• O dispositivo de hardware não precisa de uma sequência de desligamento ou quiesce.

Nessa situação, o núcleo do driver lida com a liberação de todos os recursos adquiridos por meio das APIs devm_*() . Se qualquer uma das declarações anteriores for falsa, o driver precisará executar a limpeza (liberar recursos e desligar ou desativar o hardware) ao desvincular de um dispositivo. Para garantir que um dispositivo possa desvincular um módulo de driver de forma limpa, use uma das seguintes opções:

• Se o hardware não precisar de uma sequência de desligamento ou quiesce, altere o módulo do dispositivo para adquirir recursos usando devm_*() .

• Implemente a operação de driver remove() na mesma estrutura que a função probe() e, em seguida, execute as etapas de limpeza usando a função remove() .

Desativando explicitamente a desvinculação do driver de dispositivo (não recomendado)

Ao optar por desabilitar explicitamente a desvinculação do driver de dispositivo, você precisa desabilitar a desvinculação e desabilitar o descarregamento do módulo.

• Para desabilitar a desvinculação, defina o sinalizador suppress_bind_attrs como true na struct device_driver do driver; essa configuração impede que os arquivos de bind e unbind sejam exibidos no diretório sysfs do driver. O arquivo unbind é o que permite que o espaço do usuário acione a desvinculação de um driver de seu dispositivo.

• Para impedir o descarregamento do módulo, certifique-se de que o módulo tenha [permanent] em lsmod . Ao não usar module_exit() ou module_XXX_driver() , o módulo é marcado como [permanent] .

Não carregue o firmware de dentro da função de sonda

O driver não deve carregar o firmware de dentro da função .probe() , pois eles podem não ter acesso ao firmware se o driver investigar antes que o sistema de arquivos baseado em armazenamento permanente ou flash seja montado. Nesses casos, a API request_firmware*() pode bloquear por um longo tempo e depois falhar, o que pode retardar o processo de inicialização desnecessariamente. Em vez disso, adie o carregamento do firmware para quando um cliente começar a usar o dispositivo. Por exemplo, um driver de vídeo pode carregar o firmware quando o dispositivo de vídeo é aberto.

Usar .probe() para carregar firmware pode ser bom em alguns casos, como em um driver de relógio que precisa de firmware para funcionar, mas o dispositivo não está exposto ao espaço do usuário. Outros casos de uso apropriados são possíveis.

Implementar sondagem assíncrona

Dê suporte e use a sondagem assíncrona para aproveitar os aprimoramentos futuros, como carregamento de módulo paralelo ou sondagem de dispositivo para acelerar o tempo de inicialização, que podem ser adicionados ao Android em versões futuras. Módulos de driver que não usam sondagem assíncrona podem reduzir a eficácia de tais otimizações.

Para marcar um driver como dando suporte e preferindo a sondagem assíncrona, defina o campo probe_type no membro struct device_driver do driver. O exemplo a seguir mostra esse suporte habilitado para um driver de plataforma:

static struct platform_driver acme_driver = {
        .probe          = acme_probe,
        ...
        .driver         = {
                .name   = "acme",
                ...
                .probe_type = PROBE_PREFER_ASYNCHRONOUS,
        },
};

Fazer um driver funcionar com sondagem assíncrona não requer código especial. No entanto, lembre-se do seguinte ao adicionar suporte de sondagem assíncrona.

• Não faça suposições sobre dependências testadas anteriormente. Verifique direta ou indiretamente (a maioria das chamadas de estrutura) e retorne -EPROBE_DEFER se um ou mais fornecedores ainda não estiverem prontos.

• Se você adicionar dispositivos filho na função de sondagem de um dispositivo pai, não presuma que os dispositivos filho sejam sondados imediatamente.

• Se um probe falhar, execute o tratamento e a limpeza de erros adequados (consulte Usar variantes de API devm_*() ).

Não use MODULE_SOFTDEP para solicitar sondas de dispositivo

A função MODULE_SOFTDEP() não é uma solução confiável para garantir a ordem das sondagens do dispositivo e não deve ser usada pelos seguintes motivos.

• Sonda adiada. Quando um módulo é carregado, o probe do dispositivo pode ser adiado porque um de seus fornecedores não está pronto. Isso pode levar a uma incompatibilidade entre a ordem de carregamento do módulo e a ordem da sonda do dispositivo.

• Um driver, muitos dispositivos. Um módulo de driver pode gerenciar um tipo de dispositivo específico. Se o sistema incluir mais de uma instância de um tipo de dispositivo e cada um desses dispositivos tiver um requisito de ordem de sonda diferente, você não poderá respeitar esses requisitos usando a ordenação de carregamento do módulo.

• Sondagem assíncrona. Módulos de driver que realizam sondagem assíncrona não sondam imediatamente um dispositivo quando o módulo é carregado. Em vez disso, um thread paralelo trata da sondagem do dispositivo, o que pode levar a uma incompatibilidade entre a ordem de carregamento do módulo e a ordem da sondagem do dispositivo. Por exemplo, quando um módulo de driver mestre I2C executa uma sondagem assíncrona e um módulo de driver de toque depende do PMIC que está no barramento I2C, mesmo que o driver de toque e o driver PMIC sejam carregados na ordem correta, a sonda do driver de toque pode ser tentada antes a sonda do driver PMIC.

Se você tiver módulos de driver usando a função MODULE_SOFTDEP() , corrija-os para que não usem essa função. Para ajudá-lo, a equipe do Android fez upstream de alterações que permitem que o kernel lide com problemas de ordenação sem usar MODULE_SOFTDEP() . Especificamente, você pode usar fw_devlink para garantir a ordenação da sonda e (depois que todos os consumidores de um dispositivo tiverem sondado) usar o retorno de chamada sync_state() para executar quaisquer tarefas necessárias.

Use #if IS_ENABLED() em vez de #ifdef para configurações

Use #if IS_ENABLED(CONFIG_XXX) em vez de #ifdef CONFIG_XXX para garantir que o código dentro do bloco #if continue a compilar se a configuração mudar para uma configuração tristate no futuro. As diferenças são as seguintes:

• #if IS_ENABLED(CONFIG_XXX) avaliado como true quando CONFIG_XXX é definido como módulo ( =m ) ou integrado ( =y ).

• #ifdef CONFIG_XXX avaliado como true quando CONFIG_XXX é definido como built-in ( =y ) , mas não quando CONFIG_XXX é definido como módulo ( =m ). Use isso apenas quando tiver certeza de que deseja fazer a mesma coisa quando a configuração estiver definida como módulo ou estiver desabilitada.

Nota: Use #if IS_ENABLED(CONFIG_XXX) mesmo que a configuração seja um booleano.

Use a macro correta para compilações condicionais

Aviso: Isso pode ser complicado para arquivos de cabeçalho! Revise os detalhes a seguir com cuidado.

Se um CONFIG_XXX for definido como módulo ( =m ), o sistema de compilação definirá automaticamente CONFIG_XXX_MODULE . Se o seu driver é controlado pelo CONFIG_XXX e você deseja verificar se o seu driver está sendo compilado como um módulo, use as seguintes diretrizes:

• No arquivo C (ou em qualquer arquivo de origem que não seja um arquivo de cabeçalho) para seu driver, não use #ifdef CONFIG_XXX_MODULE , pois é desnecessariamente restritivo e quebra se a configuração for renomeada para CONFIG_XYZ . Para qualquer arquivo de origem não-cabeçalho compilado em um módulo, o sistema de compilação define automaticamente MODULE para o escopo desse arquivo. Portanto, para verificar se um arquivo C (ou qualquer arquivo fonte não-cabeçalho) está sendo compilado como parte de um módulo, use #ifdef MODULE (sem o prefixo CONFIG_ ).

• Nos arquivos de cabeçalho, a mesma verificação é mais complicada porque os arquivos de cabeçalho não são compilados diretamente em um binário, mas sim compilados como parte de um arquivo C (ou outros arquivos de origem). Use as seguintes regras para arquivos de cabeçalho:

  • Para um arquivo de cabeçalho que usa #ifdef MODULE , o resultado muda com base no arquivo de origem que o está usando. Isso significa que o mesmo arquivo de cabeçalho na mesma compilação pode ter diferentes partes de seu código compiladas para diferentes arquivos de origem (módulo versus integrado ou desabilitado). Isso pode ser útil quando você deseja definir uma macro que precisa expandir de uma maneira para o código interno e expandir de uma maneira diferente para um módulo.

  • Para um arquivo de cabeçalho que precisa ser compilado em um pedaço de código quando um CONFIG_XXX específico é definido como módulo (independentemente de o arquivo de origem que o inclui ser um módulo), o arquivo de cabeçalho deve usar #ifdef CONFIG_XXX_MODULE .