Inter e Intra #2 – Interfaces! – Blog do Andre Dainese

Olá pessoal, estamos de volta!

O nosso pequeno artigo 🙃 de hoje é a segunda parte do nosso projeto Inter e Intra, aonde estou mostrando os conceitos básicos desta arquitetura, utilizando de um projeto de exemplo simples com brinquedos de pelúcia fofinhos.

Se você ainda não leu a primeira parte desta série de artigos, sugiro que você comece lá! Também tem a minha palestra de introdução à este assunto, que vale muito a pena dar uma assistida! Confira!

Sobre o que vamos falar?

Hoje vou focar na arquitetura Inter, nos cabeçalhos públicos e em outros cabeçalhos importantes para a construção do nosso repositório. Ter estes arquivos definidos é um passo muito importante para estarmos prontos para mandar ver no código!

Enquanto isso as atividades na empresa continuam à todo vapor! No momento o foco está mais com as equipes de hardware e de mecânica. Isto é ótimo pois assim ficamos mais tranquilos para trabalharmos do nosso lado… mas logo logo os olhos vão se virar para cá, então é bom estarmos prontos!

Princípios da arquitetura Inter

A arquitetura Inter foca em separar as responsabilidades funcionais do seu produto em diferentes módulos. O seu produto irá fazer uma série de atividades fantásticas mas não é legal que todo o código delas fique todo junto, num único emaranhado de um ou poucos arquivos.

Precisamos separar toda a lógica que vamos implementar em módulos.

Pra que fazer isso, Andre?

Dentre as vantagens da separação do código em módulos, temos:

Redução de dependências

Se eu mudo alguma coisa do meu código do GPIO, isso não deveria mudar nada nos outros lugares totalmente não relacionados – por exemplo, como o de um cálculo de CRC. Não é mesmo?

Os módulos devem saber o mínimo possível uns dos outros. De fato, eles só devem saber o necessário para que eles possam exercer as suas atividades. Isso vai manter o nosso repositório super flexível.

Troca de implementações

Num dado produto um módulo pode ser implementado de uma maneira, enquanto que em outro produto ele é totalmente diferente. Mas ainda assim, na visão das outras partes, eles fornecem as mesmas funcionalidades e atendem ao mesmo cabeçalho, que deve ser genérico.

É muito fácil exemplificar este ponto com módulos de drivers, porque cada microcontrolador tem periféricos diferentes, os quais exigem uma lógica diferente para funcionar, mas mesmo assim eles ainda entregam as mesmas funcionalidades. Por exemplo:

GPIO: Este sempre trará rotinas relacionadas à ler e escrever informações de pinos.
Timer: Este driver sempre trará rotinas relacionadas à contagem de tempo.

Mas isto não vale apenas para drivers, na verdade isso deve valer para todos os módulos do seu repositório. Dando um exemplo ‘mais alto nível’:

Um módulo de sistema de arquivos sempre nos proverá rotinas relacionadas à leitura e escrita de arquivos, independente se é implementado o sistema X, Y, Z…

Simplificação de código

É impressionante como que implementações outrora complexas se tornam extremamente simples quando separadas em diferentes módulos. Isso acontece porque a lógica aparenta ser mais complicada do que realmente é quando ela não está corretamente distribuída. Se uma lógica está complicada de implementar, provavelmente ela pode ser ‘quebrada’ em módulos menores e ser simplificada. É isto que vamos fazer aqui.

Testes, testes, testes!

Separando o código em módulos fica mais fácil fazer os testes unitários dos seus produtos, porque num código modularizado, além dele ser mais simples, também se pode ‘mockar‘ as dependências, podendo testar cada módulo isoladamente.

Cabeçalhos públicos

As peças chaves da arquitetura Inter são os cabeçalhos públicos. Como o nome diz, eles são headers (arquivos com extensão ‘.h’) que declaram as capacidades que um dado módulo possui. Eles declaram:

Definições necessárias para o seu uso.
As funções e rotinas disponíveis.
Helper dos testes unitários.

Tipo de rotinas

As rotinas que um módulo pode fornecer podem ser bloqueantes ou não bloqueantes.

Uma rotina bloqueante realiza todas as atividades que são esperadas daquela rotina quando ela é chamada, levando todo o tempo necessário para isso, e só depois retornando da sua chamada.

Seria como dar a ordem:

“Rotina fulana! Faça isto já!”

Estas rotinas têm a vantagem de simplificar a lógica não só de suas implementações mas também a de seus usuários. Porém, elas são ‘gulosas’.. como estes usuários ficam ‘parados’ esperando por elas, eles ficam bloqueados e isto pode causar problemas em sistemas aonde o determinismo tem bastante importância – se alguma atividade precisa ser realizada num determinado tempo, estes bloqueios podem comprometer este requisito de ser cumprido. Além do mais, como eles estão bloqueados, eles ficam impedidos de realizar algum ‘plano B’ no caso de problemas ou de eventos inesperados.

Uma rotina não bloqueante, porém, pode retornar a chamada e depois continuar a trabalhar na tarefa que lhe foi pedida, avisando em um tempo futuro quando ela acabar. Elas fazem esta notificação ‘a posteriori’ usando de callbacks, que são rotinas que os usuários passam para o módulo não bloqueante. Esta operação com callbacks ficará mais clara quando vermos as declarações dos cabeçalhos do nosso exemplo.

Seria como dar a ordem:

“Rotina ciclana! Comece a fazer isto e me avise por aqui [aponta um callback] quando você terminar!”

Este tipo de operação é ideal para sistemas determinísticos, pois seus clientes ficam livres para realizar outras atividades enquanto o módulo está trabalhando. Porém, a lógica envolvida para operar estas rotinas é um pouco mais complicada, o que faz muitos desenvolvedores preferirem implementar rotinas bloqueantes. Muitas vezes, entretanto, estas decisões se tornam grandes erros.

Que tipo de rotina usar, Andre?

Eu costumo encorajar a sempre usar rotinas não bloqueantes, a não ser que a atividade que o módulo tem que fazer seja ‘simples’ ou que se tenha alguma necessidade daquilo ser bloqueante. Rotinas não bloqueantes encorajam o seu sistema a ser determinístico e robusto. Porém, em situações como em rotinas de inicialização ou em drivers simples, eu costumo usar rotinas bloqueantes mesmo.

Vamos por a mão na massa!

Já ficamos demais na teoria, vamos trabalhar. O que faremos aqui hoje?

Definiremos que módulos teremos em nosso primeiro projeto.
O que cada um precisa fornecer.
O que cada um precisa dos outros (dependências).
Vamos criar os cabeçalhos públicos.

Definição dos módulos

Bem, não existe uma regra restrita de como os módulos são definidos, isso varia muito de desenvolvedor para desenvolvedor… alguns preferem uma certa arquitetura, enquanto outros preferem ir por outro caminho. Conforme a pessoa vai ganhando experiência, ela vai se tornando capaz de definir melhor os módulos. De certa maneira, fazer isto é uma ‘arte’!

Vamos recapitular o que o nosso produto precisa fazer. Na hora de bolar alguma arquitetura eu costumo ‘sintetizar’ a necessidade presente em uma ou mais frases, para me ajudar a ‘enxergar’ o que é preciso.

No primeiro artigo tivemos nossa primeira ‘especificação do produto’, aquele conjunto de bullets que bolamos depois da nossa primeira reunião. Usando eles de base e focando na parte do firmware, temos as seguintes afirmações:

O produto deve coordenar um LED, fazendo ele piscar de acordo com uma entrada digital. Nesta entrada está ligado um push-button, o qual vai ser pressionado pela crianç… pelo usuário!
Quando o botão não estiver pressionado, o LED deve piscar com um período total de [TBD1] ms, duty 50%.
Quando o botão estiver pressionado, o LED deve piscar com um período total de [TBD2] ms, duty 50%.
O botão é controlado pelo nosso produto, então ele precisa ter seu nível mantido por pulls e uma outra saída digital ser responsável por dar o nível quando o botão for pressionado.
A entrada digital deve ser lida periodicamente e seu nível reavaliado a cada [TBD3] ms.

Como deu pra perceber alguns valores ainda não ficaram definidos, deixei como [TBD] – To Be Defined. Os seus valores vão impactar como o produto se comporta e é melhor deixar para a liderança de empresa decidir estas características. Você prontamente já enviou um e-mail para eles sobre isto!

Com este descritivo pronto, vamos separar os módulos. A seguir listo alguns fatores que considero ao definir eles e, de tabela, vou levantando quais deles serão necessários para o nosso projeto:

O que é mais atrelado ao hardware? O que é menos?

Identificar módulos de drivers geralmente é simples, em grande parte eles são feitos pensando em operações ‘típicas’ para todos os microcontroladores. Por exemplo, todos eles geralmente têm entradas e saídas digitais, timers, ADCs, portas seriais, etc.

Para o nosso brinquedo vamos precisar atuar em entradas e saídas digitais e também vamos precisar contar tempo. Serão dois drivers.

Outro ponto importante é que todo microcontrolador precisa ser inicializado. Por exemplo, clocks precisam ser configurados, alguns outros periféricos precisam ser habilitados… até mesmo alguns pinos precisam passar por uma condição inicial. Assim, eu costumo ter um módulo relacionado à placa que o produto está sendo compilado e este módulo já é operado no main, logo na inicialização.

Assim, para o nosso projeto, já temos três módulos definidos:

hal, drivers, myGpio.
hal, drivers, myTimer.
hal, myBoard.

O que eu só vejo sendo usado em apenas um produto? O que eu já vejo sendo compartilhado por vários deles?

As regras de negócio do seu repositório geralmente nascem na camada de aplicação e, conforme for visto que mais de um produto vai utilizar do mesmo, a lógica vai ‘descendo’ para as camadas de bibliotecas. Porém, caso já esteja claro que um módulo vai ser compartilhado, então pode valer a pena que ele nasça como uma lib.

Aqui no nosso projeto está claro que teremos um módulo de sistema operacional e faz todo o sentido ele ser usado por outros futuros produtos, então temos mais um módulo definido, para ser uma lib. Para uso de RTOS, vamos seguir o padrão CMSIS-OS:

libs, cmsis_os.

Como podemos dividir as responsabilidades do nosso produto?

No nosso produto existem duas atividades bem distintas: uma para fazer a leitura do push-button, outra para coordenar o LED. Lembre-se que estamos em estágios bem iniciais do produto, nós estamos usando push-buttons e LEDs para fazermos nossos protótipos, ninguém nos disse ainda o que vai ter nos brinquedos… por exemplo, se ao invés de push buttons, for ter um acelerômetro e assim a ‘entrada de comandos’ for diferente? Neste caso, apenas o módulo do push button deveria ser mudado, o do LED deveria permanecer inalterado. Por tudo isso, é interessante termos um módulo para cada funcionalidade!

Assim, temos os dois últimos módulos do nosso projeto:

products, blinky, app, appButton.
products, blinky, app, appLed.

Os cabeçalhos básicos

Nossos produtos não consistirão apenas de módulos, precisamos também de outros cabeçalhos que fazem definições elementares, tais como a declaração dos tipos básicos, funções de debug, etc. Estes são cabeçalhos básicos e muitos dos módulos vão depender deles. Assim, eles são ‘auxiliares’ e ficam declarados em nosso diretório de helpers. São eles:

myDefs.h

Este cabeçalho define todos os tipos básicos das variáveis dos nossos produtos, além de declarar outros tipos que são comumente usados em nosso repositório. Abaixo a primeira declaração dele, contendo apenas o que precisaremos para o nosso primeiro produto. É natural este cabeçalho ir crescendo conforme novos tipos (como callbacks) forem sendo necessários.

O que temos neste arquivo:

Inclusão dos tipos básicos da biblioteca C, os quais sempre usaremos quando possível. Recomendo que sempre trabalhe com os tipos ‘uintx_t’, mas isso é assunto para outro post.
Criação do seu tipo de retorno padrão. ‘myRet_t’ será o seu tipo mais importante, ele indicará se alguma operação foi (ou não) bem sucedida. Repare que o valor de ‘sucesso’ é zero, isso é particularmente útil na hora de trabalhar com os testes unitários, pois com isso os valores default dos mocks serão de sucesso e nossos testes ficarão mais clean.
Criação do seu primeiro tipo de callback. Este é o mais simples, que simplesmente chama algo, sem argumento nenhum. Vamos usar ele já na nossa rotina não bloqueante do timer.

myAssert.h

É uma excelente prática utilizarmos de assertions durante o desenvolvimento do nosso código. Um assertion bem colocado pode te poupar de horas e horas de investigação quando algum problema acontece. Sendo assim, vamos fazer um cabeçalho dele:

Esse é o tipo de assertion mais simples que existe – caso uma expressão não for verdadeira, o código simplesmente fica num laço infinito.

Este cabeçalho pode ser incrementado de várias maneiras e, inclusive, futuramente ele poderá ter um source, mas para o que precisamos agora, é mais que suficiente.

Como ficou nosso diretório?

Agora que definimos os nossos cabeçalhos públicos e os cabeçalhos básicos, vamos atualizar o nosso repositório:

Criando os cabeçalhos públicos

Com os módulos definidos e nossos cabeçalhos básicos declarados, podemos partir para as declarações de nossos cabeçalhos públicos.

Para criar cada um, vamos usar de uma checklist, com pontos para respondermos:

Faça uma breve descrição do que o módulo deve fazer.
Este módulo é independente ou ele fornecerá funções para outros módulos?
Que dependências este módulo terá?
Que tipos específicos este módulo precisará declarar para poder ser usado?
Este módulo será todo desenvolvido por nós ou será a abstração de módulos de terceiros?
Que rotinas o módulo terá?
Que respostas cada rotina precisa ter? Quais são bloqueantes e quais são não bloqueantes?
~~Bolacha ou biscoito~~? (Não, esse não, Andre!) 🤣

Vamos começar dos módulos das aplicações e vamos descendo até os drivers.

appButton.h

Faça uma breve descrição do que o módulo deve fazer.

Este módulo deve realizar a leitura periódica de uma entrada digital. Dependendo do nível desta entrada, ele deve atuar no módulo de LED para mudar o período que ele pisca. Este módulo deve configurar o necessário para o uso de um push button: uma saída digital e a entrada com um pull.

Este módulo é independente ou ele fornecerá funções para outros módulos?

Ele é totalmente independente, tendo apenas uma rotina para a sua inicialização.

Que dependências este módulo terá?

appLed.

cmsis_os.

myGpio.

myTimer.

Que tipos específicos este módulo precisará declarar para poder ser usado?

Nenhum.

Este módulo será todo desenvolvido por nós ou será a abstração de módulos de terceiros?

Será desenvolvido totalmente por nós.

Que rotinas o módulo terá?

Rotina de inicialização do módulo.

Que respostas cada rotina precisa ter? Quais são bloqueantes e quais são não bloqueantes?

A inicialização é bloqueante e apenas responde se foi bem sucedida (ou não).

appLed.h

Faça uma breve descrição do que o módulo deve fazer.

Este módulo deve coordenar uma saída digital, ligada à um LED. Ele deve manter este LED piscando de acordo com um intervalo de tempo, intervalo este passado pelos clientes.

Este módulo é independente ou ele fornecerá funções para outros módulos?

Além da inicialização, ele fornecerá uma função para alterar o período de piscar do LED.

Que dependências este módulo terá?

cmsis_os.

myGpio.

myTimer.

Que tipos específicos este módulo precisará declarar para poder ser usado?

Nenhum.

Este módulo será todo desenvolvido por nós ou será a abstração de módulos de terceiros?

Será desenvolvido totalmente por nós.

Que rotinas o módulo terá?

Rotina de inicialização do módulo.

Rotina para definir o período de piscar do LED.

Que respostas cada rotina precisa ter? Quais são bloqueantes e quais são não bloqueantes?

As rotinas são bloqueantes e apenas respondem se foram bem sucedidas (ou não).

cmsis_os.h

Faça uma breve descrição do que o módulo deve fazer.

Este módulo deve fornecer os serviços do sistema operacional. Em particular, deve prover a capacidade de iniciarmos threads e de enviarmos mensagens para elas.

Este módulo é independente ou ele fornecerá funções para outros módulos?

Este módulo fornecerá funções para outros módulos.

Que dependências este módulo terá?

Da implementação do sistema operacional.

Que tipos específicos este módulo precisará declarar para poder ser usado?

Os seus tipos para os artefatos do sistema operacional.

Este módulo será todo desenvolvido por nós ou será a abstração de módulos de terceiros?

Será a abstração de módulos de terceiros. Inclusive na maioria das vezes estes mesmos terceiros que irão nos fornecer o cabeçalho deste módulo.

Que rotinas o módulo terá?

As rotinas de uso abstraído do sistema operacional.

Que respostas cada rotina precisa ter? Quais são bloqueantes e quais são não bloqueantes?

São inúmeras rotinas, estas informações já estão definidas e o cabeçalho já está implementado. Não precisamos nos preocupar.

A lib de sistema operacional é, infelizmente, a primeira lib que precisamos em nosso repositório. Eu digo infelizmente porque ela não segue totalmente o conceito de cabeçalho público que estou apresentando aqui para vocês. Eu mostrei que o cabeçalho público de um módulo é único e que as suas implementações deveriam seguir o mesmo. Aqui, pelo fato de que cada RTOS ter as suas características, é preciso que cada implementação tenha o seu próprio cabeçalho, divergindo do que falei. Mas deixo claro que ainda assim existe compatibilidade entre eles e mudando a implementação não afeta a compilação de seus clientes! De qualquer maneira, vamos prosseguir assim.

Lembrando que esta lib será usada somente pelos nossos submódulos de sistema, para implementar os nossos objetos ativos.

A primeira implementação que vamos usar do CMSIS-OS é para o FreeRTOS, eu estarei adicionando ela ao nosso repositório quando começarmos a implementar as nossas aplicações.

myBoard.h

Faça uma breve descrição do que o módulo deve fazer.

Este módulo deve realizar a inicialização da placa do nosso produto, iniciando o core do microcontrolador e quaisquer pinos que forem necessários.

Este módulo é independente ou ele fornecerá funções para outros módulos?

Ele é independente, apenas fornecendo uma rotina para a sua inicialização.

Que dependências este módulo terá?

Apenas do SDK do fabricante do microcontrolador.

Que tipos específicos este módulo precisará declarar para poder ser usado?

Nenhum.

Este módulo será todo desenvolvido por nós ou será a abstração de módulos de terceiros?

Será desenvolvido por nós.

Que rotinas o módulo terá?

Rotina de inicialização do módulo.

Que respostas cada rotina precisa ter? Quais são bloqueantes e quais são não bloqueantes?

As rotinas são bloqueantes e apenas respondem se foram bem sucedidas (ou não).

myGpio.h

Faça uma breve descrição do que o módulo deve fazer.

Este módulo deve atuar sobre os pinos do microcontrolador, fornecendo funções de entrada e saída digitais simples. Os pinos podem ser configurados como saídas e colocados em níveis lógicos altos ou baixos. Também, eles podem ser configurados como entradas digitais, com o módulo indicando se eles estão em nível lógico alto ou baixo. As entradas podem ter pull-ups ou pull-downs habilitados.

Este módulo é independente ou ele fornecerá funções para outros módulos?

Ele fornecerá funções para que outros módulos possam configurar e usar os pinos do microcontrolador.

Que dependências este módulo terá?

Apenas do SDK do fabricante do microcontrolador.

Que tipos específicos este módulo precisará declarar para poder ser usado?

Ele precisará declarar tipos específicos e uma estrutura de configuração que um cliente indique como deseja que um pino seja operado.

Este módulo será todo desenvolvido por nós ou será a abstração de módulos de terceiros?

Será desenvolvido por nós.

Que rotinas o módulo terá?

Rotinas para configuração e uso dos pinos.

Que respostas cada rotina precisa ter? Quais são bloqueantes e quais são não bloqueantes?

As rotinas são bloqueantes, as de inicialização e saída digital apenas respondem se foram bem sucedidas (ou não) e as de entrada digital informam o nível lógico atual dos pinos.

myTimer.h

Faça uma breve descrição do que o módulo deve fazer.

Este módulo deve usar de periféricos do microcontrolador para prover contagem de tempo, na escala de milissegundos. Como exemplo, os clientes querem ser notificados depois que um certo tempo passou. Algumas partes vão querer ser periodicamente notificados, enquanto que outras apenas uma única vez (single shot). Por enquanto não temos clientes que vão usar deste último caso.

Este módulo é independente ou ele fornecerá funções para outros módulos?

Ele fornecerá interfaces para que os clientes possam configurar e requisitar pedidos de contagem de tempo.

Que dependências este módulo terá?

Apenas do SDK do fabricante do microcontrolador.

Que tipos específicos este módulo precisará declarar para poder ser usado?

Ele precisará declarar tipos específicos e uma estrutura de configuração para indicar como um cliente deseja que um timer seja operado.

Este módulo será todo desenvolvido por nós ou será a abstração de módulos de terceiros?

Será desenvolvido por nós.

Que rotinas o módulo terá?

Rotinas para configuração e uso dos timers.

Que respostas cada rotina precisa ter? Quais são bloqueantes e quais são não bloqueantes?

A rotina de inicialização é bloqueante, a de contagem de tempo são é bloqueante.

Finalizando...

Pois bem pessoal! Acabamos mais uma parte muito importante do nosso projeto, identificando as atividades que precisam ser feitas, como vamos dividir elas em módulos e que interfaces estes módulos vão ter!

No próximo artigo estaremos preparando o nosso ambiente, falando um pouco dos testes unitários e das IDEs que vamos utilizar com as nossas placas de desenvolvimento.

O repositório está atualizado com os cabeçalhos que definimos aqui hoje!

Ficou com alguma dúvida? Entre em contato – ou deixe um comentário – e ficarei feliz em lhe ajudar! Cadastre seu e-mail para receber na sua caixa de entrada os próximos artigos!

Até a próxima!

2 comentários em “Inter e Intra #2 – Interfaces!”

Wagner 6 de novembro de 2020 em 10:05

André, conteúdo de OURO, estou aprendendo como nunca. Na parte dos callbacks eu tive que fritar os neurônios pra entender mas depois que eu aprendí, um novo horizonte se abriu. Agora não entendo muito bem ainda a parte dos “assertions” e sua relação com os testes unitários, mas vou ficar ligado aqui pra continuar aprendendo contigo. Muito obrigado pela sua disposição em compartilhar esse conhecimento fantástico. Abraços !

Andre F. N. Dainese 7 de novembro de 2020 em 11:15

Olá novamente, Wagner!
Obrigado pelos comentários e por estar acompanhando, fico feliz destas informações estarem lhe sendo úteis! Quanto aos assertions e testes unitários, bem… eles não tem relação nenhuma! Tenho certeza que nos próximos posts isto ficará mais claro… outro abraço!

Não é possível comentar.