O editor

Escrevendo em assembly

Assembly é uma forma de programar uma placa aqui em pé de igualdade: uma aba .S ao lado do seu sketch, ou um projeto inteiro sem o core do Arduino por baixo.

Por que se dar ao trabalho

Porque algumas coisas só são verdadeiras uma instrução por vez. Um curso que ensina AVR ou Cortex-M pede um laço de atraso contado em ciclos, uma tabela de vetores escrita à mão e um conjunto de registradores que você pode ler numa parada. Tudo isso funciona no navegador, nos mesmos chips simulados em que os sketches rodam, sem nada para instalar.

Dois caminhos de entrada:

  • Assembly ao lado de um sketch. Adicione uma aba .S ou .s e chame-a a partir do C com extern "C". O core do Arduino continua lá, então Serial, millis() e pinMode() seguem funcionando.
  • Assembly sem o core do Arduino. Escolha um projeto inicial em Assembly (sem Arduino) na seção Firmware das propriedades da placa. Os arquivos da placa viram um único main.S, e nada além do seu próprio código e do código de inicialização é linkado.

Abas .S e .s

Aperte o + na faixa de arquivos e dê um nome ao arquivo. O prompt diz o que é aceito: "Nome do novo arquivo, como config.h, helpers.cpp ou delay.S". Qualquer coisa terminada em .S ou .s é assembly, e ela é compilada e linkada com as abas .ino e .cpp da mesma placa, exatamente como a Arduino IDE compila um .S ao lado de um sketch.

As duas grafias não são o mesmo arquivo:

  • .S, com S maiúsculo, passa primeiro pelo pré-processador do C. #include <avr/io.h>, #define, #if e // comentários funcionam, e __ASSEMBLER__ está definido. É este que você deve usar.
  • .s, com s minúsculo, vai para o montador como está. Sem includes, sem macros.

Uma aba nova .S ou .s não começa vazia. Ela abre com uma função funcionando que o sketch pode chamar, no próprio conjunto de instruções da placa: AVR no Uno, na Nano, na Mega, na Leonardo e na ATtiny85, e ARM Thumb na Pico, nas placas STM32, na Uno R4, na micro:bit e na XIAO. O comentário acima dela lista a convenção de chamada, então as regras ficam na sua frente enquanto você escreve. Apague-a ou construa sobre ela.

Abas de assembly têm realce de sintaxe próprio, e a canaleta de breakpoints ao lado dos números de linha, igual a um sketch.

Chamando entre C e assembly

Uma função escrita em assembly é um rótulo .global, e o C a alcança por extern "C", para o nome não ser embaralhado. Funciona nos dois sentidos: o assembly pode chamar uma função em C do mesmo jeito.

// sketch.ino
extern "C" uint8_t add_bytes(uint8_t a, uint8_t b);

void setup() {
  Serial.begin(9600);
  Serial.println(add_bytes(2, 40));   // 42
}

void loop() {}
; add.S
    .global add_bytes
add_bytes:
    add  r24, r22        ; a is in r24, b in r22
    ret                  ; the result goes back in r24

As regras são do próprio chip, não do Mokxi, então uma função que as segue também funciona numa placa real.

Nas placas AVR (o compilador chama isso de convenção de chamada do GCC AVR):

  • Os argumentos vão em r24, depois r22, depois r20, descendo de dois em dois. Um argumento de dois bytes ocupa um par, byte baixo primeiro: um int em r25:r24.
  • O resultado volta em r24 para um byte, r25:r24 para dois bytes e r25:r22 para quatro.
  • r1 deve ser zero quando você retornar. O compilador assume isso em todo lugar, então um mul que o suja precisa de clr r1 depois.
  • r2 a r17, r28 e r29 pertencem a quem chama. Faça push se usá-los, e pop antes do ret. Todo o resto é seu para modificar à vontade.

Nas placas ARM (o padrão de chamada de procedimento Arm):

  • Os argumentos vão em r0 a r3, e o resultado volta em r0.
  • r4 a r11 pertencem a quem chama: faça push deles e depois pop.
  • Retorne com bx lr e marque o rótulo .thumb_func.

avr/io.h em um arquivo .S

Em uma placa AVR, #include <avr/io.h> em um .S fornece os nomes dos registradores e dos bits, e funciona exatamente como o da avr-libc. Isso importa, porque uma regra pega quase todo mundo:

O nome de um registrador é um endereço de dados, não um endereço de E/S. PORTB é 0x25. O endereço de E/S é 32 menor, então in, out, sbi, cbi, sbic e sbis pedem _SFR_IO_ADDR(PORTB), que é 0x05:

    sbi  _SFR_IO_ADDR(DDRB), DDB5     ; PB5 is an output
    sts  TCCR1B, r16                  ; a high register, by its data address

Se você preferir escrever os nomes simples em todo lugar, coloque uma linha antes do include e eles passam a ser endereços de E/S, como faz o próprio código de inicialização do avr-gcc:

#define __SFR_OFFSET 0
#include <avr/io.h>
    sbi  DDRB, DDB5

O resto do cabeçalho também funciona:

  • Nomes de bits. DDB5, PINB5, TXEN0, WGM12, OCIE1A e os outros são os números dos bits, então (1 << TXEN0) é lido da mesma forma que no data sheet.
  • Nomes de vetores. TIMER1_COMPA_vect é __vector_11, então .global TIMER1_COMPA_vect seguido do rótulo cria um tratador de interrupção para onde a tabela de vetores salta. Termine com reti.
  • __zero_reg__ é r1 e __tmp_reg__ é r0, com esses nomes.
  • Registradores além dos 64 primeiros, como UCSR0B e TIMSK1, são mapeados em memória: leia com lds e escreva com sts.

Assembly inline

Algumas instruções dentro de uma função em C não precisam de uma aba só delas. asm volatile com constraints funciona nas placas AVR e ARM:

uint8_t x = 5;
asm volatile ("lsl %0" : "+r" (x));   // x is 10

O simulador conta ciclos, então um atraso escrito à mão realmente dura o que a folha de dados diz. Um laço de nop, dec e brne, cronometrado com o Timer 1 no clock completo, dá exatamente a contagem que a folha de dados do ATmega328P informa para suas instruções: um lds, um ldi e 50 voltas do laço medem 202 ciclos, não 201 e nem 203. É isso que torna a contagem de ciclos valiosa para ensinar aqui.

Assembly sem core do Arduino

Abra o painel de propriedades da placa e olhe a seção Firmware. No Arduino Uno, no Nano, no Pro Mini a 16 MHz, no Raspberry Pi Pico e no STM32F411 Black Pill há um grupo chamado Assembly (sem Arduino) com quatro projetos iniciais:

Projeto inicial O que faz
Blink em assembly Alterna o LED da placa a cada 250 ms com um laço de atraso contado.
Botão para LED em assembly O LED acompanha um botão mantido no terra pelo seu pull-up.
UART hello em assembly Imprime uma linha no monitor serial duas vezes por segundo.
Interrupção de timer em assembly Uma interrupção de timer alterna o LED, e o laço principal só fica ocioso.

Escolha um e os arquivos da placa viram um único main.S. Se houver trabalho seu na placa, você é avisado antes. Depois disso a lista de programas mantém o projeto inicial de onde você começou, e a nota abaixo dele diz que Rodar monta o main.S sem core do Arduino, então a placa continua em assembly quando você voltar.

Não há core do Arduino nesta versão: sem setup(), sem loop(), sem o tique do millis() e sem Serial. O que é vinculado é apenas isto:

  • Em uma placa AVR, o seu arquivo mais o código de inicialização, que é o que o gcrt1.o da avr-libc é para avr-gcc main.S. É a tabela de vetores com cada __vector_n como um reti fraco que você pode sobrescrever, depois r1 zerado, a pilha em RAMEND, .data copiado da flash, .bss zerado e um call para o seu main. Então você escreve main e os tratadores que quiser, com os nomes de vetores da avr-libc. Se o seu arquivo definir sua própria seção .vectors, você não recebe código de inicialização nenhum e o programa inteiro é seu.
  • No Pico e no Black Pill, nada além do seu arquivo. Seu arquivo é a tabela de vetores: .word _stack_top no Pico ou .word _estack no Black Pill, depois .word Reset_Handler, depois os tratadores que quiser, cada um .thumb_func.

O que os projetos iniciais configuram, se você quiser ler os registradores junto com eles:

  • O blink AVR alterna PB5 escrevendo 1 em PINB5, que o ATmega328P interpreta como "alternar", e atrasa com um laço externo e um interno: "250 ms a 16 MHz são 4.000.000 de ciclos: 40 vezes 100.000", e o laço interno tem quatro ciclos por volta.
  • O botão AVR lê PD2 com o pull-up ligado, então um aperto lê 0, e usa sbic para pular uma linha.
  • A UART AVR configura a USART0 para 9600 baud com UBRR 103, guarda o texto em .progmem e lê um byte por vez com lpm.
  • O timer AVR roda o Timer 1 no modo CTC no clock dividido por 256 com OCR1A em 31.249, o que dá a cada 0,5 s, e alterna o LED em TIMER1_COMPA_vect.
  • O Pico tira IO_BANK0 e PADS_BANK0 (e UART0, no da UART) de RESETS, controla a GPIO25 pelo SIO em 0xD0000000, atrasa com TIMERAWL, conversa na UART0 pela GPIO0 a 115200 e usa o alarme 0 de IRQ do TIMER no projeto inicial do timer.
  • O Black Pill liga os clocks em RCC_AHB1ENR, controla a PC13, que fica acesa quando está em nível baixo, lê a PA0 com o pull-up, imprime na USART1 pela PA9 a 115200 com BRR 729 e roda o SysTick a 1 kHz.

Aperte Rodar e a placa executa. O monitor serial, o osciloscópio, o analisador lógico e os componentes no canvas funcionam como de costume, porque o chip simulado não sabe, nem se importa, com a linguagem que gerou a imagem.

Quando não monta

Os erros do montador caem na aba e na linha certas, com uma frase em linguagem simples abaixo deles dizendo o que escrever no lugar. Alguns deles:

  • ldi r3, 5 diz que LDI funciona só nos registradores altos, r16 a r31, e para fazer mov do valor para baixo depois, se precisar dele em um registrador baixo.
  • lid r16, 5 diz que "lid" não é uma instrução AVR e lembra que um rótulo termina em dois-pontos e uma diretiva começa com um ponto.
  • Um rótulo escrito sem os dois-pontos tem seu nome devolvido a você com os dois-pontos adicionados.
  • Um desvio condicional que não alcança seu alvo é colocado na sua linha pelo linker, junto com a correção: brne 1f, rjmp far, 1:.

Quatro deles são verificações que o avr-as faz e o montador do LLVM não faz, então o próprio Mokxi as faz, antes de qualquer ferramenta rodar. Sem elas, um erro seria montado em silêncio no programa errado:

  • ldi r16, 300 não cabe em um byte. Carregue as metades com lo8() e hi8().
  • sbi PORTB, 5 usa o endereço de dados 0x25 onde sbi pede um endereço de E/S. Escreva _SFR_IO_ADDR(PORTB).
  • add r16, 5 se lê como add r16, r5, porque ADD recebe dois registradores. Não existe ADDI: subtraia o negativo com subi r16, -5.
  • out PORTB, r16 sem __SFR_OFFSET 0 é um aviso, não um erro, porque isso monta sim: só escreve em um registrador diferente do que foi nomeado.

in e out além do endereço de E/S 63, sbiw e adiw além de 63, e um número de bit além de 7 são pegos do mesmo jeito, cada um com a instrução a usar no lugar.

Nas placas Thumb, os casos comuns são um registrador alto em um Cortex-M0+, que alcança apenas r0 a r7, uma forma Thumb-2 de 32 bits em um Cortex-M0+, que tem apenas o conjunto de 16 bits, um desvio fora do alcance, um Reset_Handler ausente e um main ausente.

Executando instrução por instrução

Tudo no depurador funciona sobre assembly. Breakpoints vão na medianiz de uma aba .S e param naquela linha, porque os números de linha que o montador registra são os da própria aba, não os da cópia pré-processada.

A aba Debug tem uma seção Desmontagem. Em uma pausa, ela lista as instruções ao redor do contador de programa: o endereço, os bytes, a instrução na grafia do llvm-objdump e a linha de origem em que cada uma começa, que é um botão que leva até ela. A instrução prestes a rodar fica marcada. Passo de instrução executa exatamente uma instrução de máquina, enquanto Passo por cima e Passo para dentro ainda avançam uma linha de origem inteira por vez.

Os registradores aparecem como o core os vê. O sreg em um AVR também é escrito por extenso como suas flags, ITHSVNZC, com um ponto para cada uma que está zerada, e o xpsr em um ARM é escrito como N Z C V Q, porque oito bits não são um número.

Limites

  • Assembly sem core do Arduino é oferecido no Uno, no Nano, no Pro Mini, no Pico e no STM32F411 Black Pill. Todas as outras placas ainda aceitam abas .S e .s ao lado de um sketch.
  • A família ESP32 não está incluída. O próprio montador Xtensa do Clang não está completo para arquivos escritos à mão, então essas placas compilam apenas C e C++.
  • O Pico W não tem projetos iniciais. Seu LED fica no chip de rede sem fio em vez de em um pino GPIO. Use um Pico comum.
  • Um projeto é plano. Os nomes de arquivo não trazem diretórios, então um caminho de include tem um diretório de profundidade.