Referência

Contrato da placa BBC micro:bit V2 (Fase 9)

A nRF52833 no nosso núcleo Cortex-M4, com GPIO, GPIOTE, os TIMERs, RTC0, UARTE0 e a matriz de LEDs.

Esta é a referência de engenharia do modelo: o que ele implementa, registrador por registrador, para quem escreve firmware para ele. Para usar a placa no editor, comece por A BBC micro:bit V2 e página da placa.

O quinto microcontrolador, e o segundo no motor Cortex-M4. Um componente do kernel (microbit em crates/parts) envolve um modelo do SoC nRF52833 (crates/nrf52833) construído sobre o núcleo Cortex-M (crates/cortexm-core, Profile::V7M). O firmware é um ELF Thumb que conversa com os periféricos abaixo nos endereços reais do nRF52833, então um programa compilado para o Mokxi roda em um micro:bit V2 de verdade.

O tipo no catálogo é microbit (BBC micro:bit V2, nRF52833). Tudo o que está em docs/esp32c3.md sobre como um componente de placa se comporta (slices, canal do host, reset, linha de crash) vale aqui, a menos que este arquivo diga o contrário, e tudo o que está em docs/stm32f411.md sobre o núcleo Cortex-M4 vale para este núcleo.

Running MakeCode or MicroPython .hex images is not a goal: both are built against the vendor stack and expect the soft device, the radio and a file system, none of which are modeled. What is modeled is the set of peripherals pinMode, digitalWrite, digitalRead, millis, micros, delay, Serial, attachInterrupt, showLeds, showText and tone need, at their real addresses, so the same source built against firmware/microbit/ produces an image that also runs on the hardware.

A placa é diferente das outras daqui em dois aspectos, e ambos vêm do hardware. Ela não tem cabeçalho para encaixar numa protoboard: o conector de borda é um pente dourado ao longo da borda inferior, e só os seus cinco anéis grandes aceitam um jacaré ou um jumper, então a placa fica ao lado da protoboard em vez de dentro dela. E ela não tem um único LED para piscar: o display são 25 LEDs em dez pads, varridos pelo firmware, então uma imagem é algo que o simulador precisa reconstruir a partir da varredura em vez de ler de um registrador.

1. Pinos da placa (ordem do catálogo)

Cinco pinos, os cinco anéis grandes do conector de borda, da esquerda para a direita com a placa segurada com o soquete USB para cima:

0, 1, 2, 3V, GND.

As tiras finas entre os anéis são GPIO reais no componente e acessíveis pelo firmware, mas não são pinos do catálogo: nada numa protoboard alcança uma tira de 0,06 polegada de largura, e um pino que o usuário não consegue ligar é um pino que mente sobre o que é o circuito.

Elétrico:

  • 3V fornece 3,3 V em R_SUPPLY e GND fornece 0 V em R_SUPPLY, sempre, porque a placa é alimentada por USB. A placa é uma fonte para o resto do circuito.
  • 0, 1 and 2 are inout GPIO on P0.02, P0.03 and P0.04. Output (DIR bit set): push-pull at 3.3 V or 0 V through R_STRONG. Input: high-Z, plus a 13 k pull-up to 3.3 V when PIN_CNF[n].PULL is Pullup, a 13 k pull-down when it is Pulldown. 13 k is the figure in the product specification. Input reads the net voltage against 1.65 V, half the supply; Unknown reads 0, and a floating input reads noise, as on the Uno (docs/uno.md section 1). PIN_CNF[n].INPUT set to Disconnect makes the input read 0.
  • Um pino que o anel não expõe (os pinos de I2C 19 e 20, P0.26 e P1.00, a matriz, as tiras sobressalentes da borda) não tem nada nele além do chip, então ele lê o que o chip coloca ali: 1 no seu próprio pull-up ou na sua própria saída alta, 0 caso contrário. Assim, Wire, que solta suas linhas nos pull-ups, não encontra nenhum dispositivo em nenhum endereço ali, como na placa real.

2. Mapa de memória (endereços reais do nRF52833)

região endereço tamanho notas
flash 0x0000_0000 512 KB the part boots from zero; VTOR points here out of reset
RAM, barramento de código 0x0080_0000 128 KB os mesmos bytes de baixo, pelo barramento de código
RAM, barramento de dados 0x2000_0000 128 KB .data, .bss e a pilha
FICR 0x1000_0000 4 KB informações de fábrica, somente leitura
UICR 0x1000_1000 4 KB apagado, nunca programado aqui
periféricos APB 0x4000_0000 48 x 4 KB periférico id em 0x4000_0000 + id * 0x1000, disparando a IRQ id
GPIO P0 0x5000_0000 P0.00 a P0.31
GPIO P1 0x5000_0300 P1.00 a P1.09, nos mesmos deslocamentos mais 0x300
SCS 0xE000_E000 SysTick, NVIC e o SCB, de cortexm-core

A pilha cresce para baixo a partir do topo da RAM. firmware/microbit/link.ld falha na vinculação se os dados estáticos deixarem menos de 4 KB.

3. Registradores de periféricos (offsets reais, posições de bit reais)

Cada deslocamento e posição de bit aqui é o da Especificação de Produto do nRF52833. Os periféricos da Nordic compartilham um mesmo formato: tarefas em 0x000, eventos em 0x100, SHORTS em 0x200, INTEN / INTENSET / INTENCLR em 0x300, e os registradores de configuração a partir de 0x500. Escrever 1 em um registrador de tarefa a dispara; um registrador de evento lê 1 até que o firmware escreva 0 nele.

Um periférico que o modelo não implementa não está no mapa, então um sketch que tenta usar o rádio recebe uma falta de barramento e para com uma linha no monitor serial em vez de continuar rodando em silêncio. Dentro de um periférico implementado, um registrador que este modelo não usa lê 0 e é contado.

3.1 CLOCK e POWER (0x4000_0000, IRQ 0)

offset registrador
0x000 TASKS_HFCLKSTART
0x004 TASKS_HFCLKSTOP
0x008 TASKS_LFCLKSTART
0x00C TASKS_LFCLKSTOP
0x100 EVENTS_HFCLKSTARTED
0x104 EVENTS_LFCLKSTARTED
0x304 / 0x308 INTENSET / INTENCLR
0x408 / 0x40C HFCLKRUN / HFCLKSTAT
0x414 / 0x418 LFCLKRUN / LFCLKSTAT
0x518 LFCLKSRC
0x400 POWER.RESETREAS
0x500 POWER.SYSTEMOFF
0x51C / 0x520 POWER.GPREGRET / GPREGRET2

HFCLKSTAT e LFCLKSTAT carregam STATE no bit 16 e a fonte no bit 0. O HFXO é modelado como já em execução, então uma tarefa de início termina na mesma fatia em que foi escrita e o evento de início é gerado imediatamente.

3.2 GPIO (0x5000_0000 e 0x5000_0300)

offset registrador
0x504 OUT
0x508 / 0x50C OUTSET / OUTCLR
0x510 IN
0x514 DIR
0x518 / 0x51C DIRSET / DIRCLR
0x520 LATCH
0x524 DETECTMODE
0x700 + 4n PIN_CNF[n]

Campos de PIN_CNF[n]: DIR bit 0, INPUT bit 1 (1 desconecta o buffer), PULL bits 3:2 (0 desativado, 1 pull-down, 3 pull-up), DRIVE bits 10:8 e SENSE bits 17:16. Valor de reset 0x0000_0002: entrada, buffer desconectado, sem pull. O campo de força de acionamento é decodificado e guardado, mas o modelo tem uma única impedância de saída, então H0H1 e S0S1 acionam igual; um pad configurado como D0S1 ou S0D1 fica em dreno aberto na metade desconectada e essa metade fica em alta impedância.

3.3 GPIOTE (0x4000_6000, IRQ 6)

offset registrador
0x000 + 4n TASKS_OUT[n]
0x030 + 4n TASKS_SET[n]
0x060 + 4n TASKS_CLR[n]
0x100 + 4n EVENTS_IN[n]
0x17C EVENTS_PORT
0x300 / 0x304 / 0x308 INTEN / INTENSET / INTENCLR
0x510 + 4n CONFIG[n]

Oito canais. CONFIG[n]: MODE bits 1:0 (0 desativado, 1 evento, 3 tarefa), PSEL bits 12:8, PORT bit 13, POLARITY bits 17:16 (1 de baixa para alta, 2 de alta para baixa, 3 alternar) e OUTINIT bit 20. O bit 31 de INTEN é o evento PORT, que é o que alimenta PIN_CNF[n].SENSE. O attachInterrupt no runtime usa canais de evento; o evento PORT está lá para firmwares que querem acordar com um grupo de pinos de uma vez.

3.4 TIMER0, TIMER1, TIMER2 (0x4000_8000, 0x4000_9000, 0x4000_A000; IRQ 8, 9, 10)

offset registrador
0x000 / 0x004 TASKS_START / TASKS_STOP
0x008 / 0x00C TASKS_COUNT / TASKS_CLEAR
0x010 TASKS_SHUTDOWN
0x040 + 4n TASKS_CAPTURE[n]
0x140 + 4n EVENTS_COMPARE[n]
0x200 SHORTS
0x304 / 0x308 INTENSET / INTENCLR
0x504 MODE
0x508 BITMODE
0x510 PRESCALER
0x540 + 4n CC[n]

O modo timer conta o PCLK16M dividido por 2^PRESCALER; o prescaler de reset é 4, ou seja, 1 MHz. O modo contador conta TASKS_COUNT no lugar. BITMODE é 16, 8, 24 ou 32 bits (0, 1, 2, 3). O bit n de SHORTS é COMPARE[n]_CLEAR e o bit 8 + n é COMPARE[n]_STOP; o bit 16 + n de INTEN é COMPARE[n]. Os três timers têm quatro canais de comparação.

3.5 RTC0 (0x4000_B000, IRQ 11)

offset registrador
0x000 / 0x004 / 0x008 TASKS_START / TASKS_STOP / TASKS_CLEAR
0x00C TASKS_TRIGOVRFLW
0x100 / 0x104 EVENTS_TICK / EVENTS_OVRFLW
0x140 + 4n EVENTS_COMPARE[n]
0x304 / 0x308 INTENSET / INTENCLR
0x340 / 0x344 / 0x348 EVTEN / EVTENSET / EVTENCLR
0x504 COUNTER
0x508 PRESCALER
0x540 + 4n CC[n]

O contador tem 24 bits e roda a partir do LFCLK a 32.768 Hz por um prescaler de 12 bits, com três canais de comparação. INTEN e EVTEN: TICK bit 0, OVRFLW bit 1, COMPARE[n] bit 16 + n. PRESCALER só pode ser escrito com o RTC parado, como no componente.

3.6 UARTE0 (0x4000_2000, IRQ 2)

offset registrador
0x000 / 0x004 TASKS_STARTRX / TASKS_STOPRX
0x008 / 0x00C TASKS_STARTTX / TASKS_STOPTX
0x02C TASKS_FLUSHRX
0x108 EVENTS_RXDRDY
0x110 EVENTS_ENDRX
0x11C EVENTS_TXDRDY
0x120 EVENTS_ENDTX
0x124 EVENTS_ERROR
0x144 / 0x14C / 0x150 EVENTS_RXTO / EVENTS_RXSTARTED / EVENTS_TXSTARTED
0x200 SHORTS
0x300 / 0x304 / 0x308 INTEN / INTENSET / INTENCLR
0x500 ENABLE (4 a UART legada, 8 a UARTE)
0x508 .. 0x514 PSEL.RTS, PSEL.TXD, PSEL.CTS, PSEL.RXD
0x518 / 0x51C RXD / TXD (os registradores legados de um byte)
0x524 BAUDRATE
0x534 / 0x538 / 0x53C RXD.PTR / RXD.MAXCNT / RXD.AMOUNT
0x544 / 0x548 / 0x54C TXD.PTR / TXD.MAXCNT / TXD.AMOUNT
0x56C CONFIG

As duas faces do periférico são modeladas: a UARTE com EasyDMA, que lê e escreve buffers na RAM, e os registradores legados de um byte RXD e TXD, que são o que um runtime pequeno procura primeiro. BAUDRATE aceita os valores listados na especificação do produto (0x01D7_E000 é 115.200), e cada byte custa no tempo simulado o que dez bits nessa taxa custariam, então uma linha longa demora aqui o mesmo que demora na placa. Os pads nomeados por PSEL.TXD e PSEL.RXD continuam sendo GPIO; os bytes vão para o canal do host (seção 4), exatamente como docs/esp32c3.md faz.

3.7 NVMC (0x4001_E000) e FICR (0x1000_0000)

NVMC.READY em 0x400 lê 1 e NVMC.CONFIG em 0x504 aceita os modos de escrita e apagamento; o apagamento de uma página limpa 4 KB da imagem de flash e uma escrita de palavra faz um and nela, como o flash faz. A FICR carrega CODEPAGESIZE (0x010, 4096), CODESIZE (0x014, 128 páginas), DEVICEID0/1 (0x060, 0x064) e o bloco INFO a partir de 0x100: parte 0x52833, a variante, o pacote, 128 KB de RAM e 512 KB de flash.

3.8 O core e as interrupções

Cortex-M4 (ARMv7-M) a 64 MHz, sem FPU: CPUID lê 0x410F_C241 e toda instrução VFP ou DSP levanta UNDEFINSTR, e é por isso que firmware/microbit/build.sh compila com soft float e não é por acaso. A NVIC implementa os três bits de prioridade mais altos dos oito, como a família nRF52 faz. O SysTick não tem clock de referência separado, então SYST_CALIB lê 0xC000_0000.

Os números de interrupção são os IDs dos periféricos: POWER_CLOCK 0, UARTE0 2, GPIOTE 6, TIMER0 8, TIMER1 9, TIMER2 10, RTC0 11.

4. Canal do host

host_write entrega à placa os bytes digitados no monitor serial; eles chegam pelo caminho de recepção da UARTE0 e levantam EVENTS_RXDRDY. host_read pega os bytes que o firmware transmitiu. A string de formato no catálogo é utf-8 bytes on UARTE0. Numa placa real esses pads (P0.06 TX, P1.08 RX) vão para o chip de interface e saem pelo USB, então o monitor serial está no lugar da porta serial USB e não de um segundo UART.

O formato de programa é elf32 arm nrf52833. load aceita um ELF Thumb para o mapa de memória da seção 2 e refaz toda a sequência de inicialização.

5. Modelo de tempo, a ponta de prova e o poke

O componente roda o SoC em fatias de 10 microssegundos, como o componente do STM32F411 faz: 640 ciclos a 64 MHz, exatamente. Cada fatia devolve as mudanças de pad que fez com o deslocamento dentro da fatia em que cada uma aconteceu, e o componente as transforma em chamadas drive_after em seus próprios deslocamentos, então um pino que mudou no ciclo 12 de uma fatia muda 187,5 nanossegundos dentro dela em vez de no fim. Um núcleo parado em WFI não custa nada até aquilo que ele espera, ou até o circuito ou o host mexer com ele; on_pin_change e on_poke o acordam um nanossegundo depois em vez de no mesmo ciclo de delta, então uma mudança de pino nunca pode iniciar um laço que se alimenta a si mesmo.

A matriz. Vinte e cinco LEDs em cinco pads de linha (P0.21, P0.22, P0.15, P0.24, P0.19) e cinco pads de coluna (P0.28, P0.11, P0.31, P1.05, P0.30). Um LED acende enquanto sua linha dirige alto e sua coluna dirige baixo, que é o que a varredura do runtime faz, uma linha por vez. Cada LED é lembrado por 40 milissegundos depois de ter sido aceso pela última vez, então uma varredura que mostra uma linha por milissegundo aparece como a imagem estável que um olho vê, e um display que é apagado ainda escurece antes da próxima piscada. Os dez pads da matriz não são levados a um anel, então eles nunca dirigem um nó.

Os botões. A em P0.14 e B em P0.23, atrás dos pull-ups de 10 k da própria placa, então um botão pressionado leva o pad ao terra. Eles chegam por poke, porque o canvas não tem noção de região de um componente: 1 é A pressionado, 2 é B pressionado, 3 é ambos, 0 é nenhum.

O alto-falante. No P0.00. O componente mede as bordas do pad do mesmo jeito que o componente piezo faz e considera que está tocando enquanto elas continuam chegando entre 20 Hz e 20 kHz, ficando em silêncio 60 milissegundos após a última.

A ponta de prova é um f32, e a placa tem mais a dizer do que um inteiro num float carrega exatamente. Então a ponta de prova é uma palavra de 32 bits no padrão de bits do float, disposta de modo que seja sempre um número normal e nunca um NaN:

bit significado
0..24 a matriz de LEDs, em ordem de leitura: da esquerda para a direita, de cima para baixo
25 rodando
26 botão A pressionado
27 botão B pressionado
28 atividade serial nos últimos 20 ms
29 always set: the tag that says this is a packed word
30 always clear, so the float is never a NaN
31 o alto-falante tocando

Sem programa, ou depois de uma falha, a ponta de prova é 0 puro. O visual lê os bits de volta do mesmo float (web/src/parts/microbit.ts, probeWord).

6. O que não é modelado

  • O rádio. Nada de 2,4 GHz: sem Bluetooth, sem mensagens de micro:bit para micro:bit, e sem fingimento de nenhum dos dois.
  • Os sensores. O acelerômetro e a bússola (um LSM303 em I2C na V2 real), o microfone e o logotipo sensível ao toque. Os pads existem; nada está atrás deles.
  • SAADC, PWM, PPI, I2S, SPIM, TWIM e o sensor de temperatura. Os endereços deles estão fora do mapa, então tocar um é uma falha em vez de um zero silencioso. tone() é uma onda quadrada alternada pela interrupção de comparação do TIMER1; analogWrite e analogRead não têm periférico por trás.
  • O soft device, o chip de interface DAPLink e o sistema de arquivos. Um .hex do MakeCode ou do MicroPython não roda aqui.
  • RTC1 e RTC2, TIMER3 e TIMER4. Só RTC0 e TIMER0 a TIMER2 são modelados.
  • A V1. Aquilo é um nRF51822, um chip diferente.

7. Runtime do firmware (firmware/microbit/)

Um runtime de C e C++ freestanding com uma API no formato Arduino, compilado com clang e ld.lld para thumbv7em-none-eabi com soft float. Sem newlib, sem CMSIS, sem SDK da Nordic, sem libgcc e sem compiler-rt.

./firmware/microbit/build.sh          # every example into web/public/firmware/microbit/

Um sketch nomeia um pino do jeito que a placa faz: 0 a 20 para o conector de borda, mais BUTTON_A, BUTTON_B, SPEAKER, MIC, LOGO e os dez nomes LED_ROW* e LED_COL* da matriz. firmware/microbit/include/pins.h guarda o mapa desses números para os pads do nRF52833, e é o do esquemático da micro:bit V2.

Além do conjunto Arduino usual, o runtime oferece o display: showLeds(picture) recebe cinco linhas de cinco, # para um LED aceso e . para um apagado; showChar(c) mantém um caractere da fonte 5x5; showText(s) rola uma string da direita para a esquerda e retorna quando a última letra sai; plot, unplot e point alcançam um LED. O varrimento roda a partir da interrupção do SysTick, uma linha por vez, então um sketch que chama showLeds e depois dorme mantém sua imagem. buttonA() e buttonB() leem os dois botões da placa, e tone(SPEAKER, hz, ms) é uma onda quadrada no P0.00.

Os quatro exemplos prontos são blink (um coração batendo na matriz), button (A e B mudam o rosto, um botão no anel 1 acende um LED no anel 0), serial (diz o que os botões fazem e ecoa o que você digita) e scroll (uma palavra atravessando a matriz). build.sh escreve web/public/firmware/microbit/index.json, que carrega o código-fonte de cada sketch para o editor.

8. O que este modelo sabe com certeza, e o que não sabe

Três grupos, a mesma ordenação que a seção 7 de docs/esp32c6.md usa. Ela existe porque um modelo de placa que adivinha silenciosamente um endereço é pior do que um que diz que não sabia.

Tirado da especificação do produto, e percorrido por firmware de verdade. Todo endereço base, deslocamento de registrador e posição de bit das seções 2 e 3 vem da nRF52833 Product Specification: CLOCK e POWER em 0x4000_0000, UARTE0 em 0x4000_2000, GPIOTE em 0x4000_6000, TIMER0 a TIMER2 em 0x4000_8000/9000/A000, RTC0 em 0x4000_B000, NVMC em 0x4001_E000, FICR em 0x1000_0000 e GPIO P0/P1 em 0x5000_0000/0300, com seus números de IRQ. crates/nrf52833/tests/firmware.rs carrega ELFs reais e aciona GPIO, GPIOTE, os timers, RTC0 e UARTE0 através deles. Os números da própria micro:bit V2 (a matriz 5x5 como cinco linhas em P0.21/22/15/24/19 e cinco colunas, botões A e B em P0.14 e P0.23, o alto-falante em P0.00 e os três grandes anéis do conector de borda) são do esquemático da placa.

Modelado, mas não preso aos números da especificação. Comportamentos em vez de endereços:

  • O clock é 64 MHz e a árvore de clocks é um esqueleto. As tarefas HFCLKSTART e LFCLKSTART do CLOCK definem seus eventos imediatamente e o núcleo roda a 64 MHz independente do que for pedido; não há tempo de partida do cristal, nem calibração de RC, nem domínio de clock de baixo consumo.
  • A fatia tem duas marchas, e a primeira escrita depois de um período calmo chega cedo. O núcleo roda em lotes grossos até uma escrita cair em um registrador de GPIO, GPIOTE, TIMER ou UARTE e então passa um tempo executando uma instrução por vez, o mesmo formato que a seção 7 de docs/stm32f411.md descreve.
  • A matriz de LEDs é uma leitura, não um varrimento que você pode assistir. O modelo reporta os vinte e cinco pixels como uma máscara de bits; a multiplexação linha por linha que uma micro:bit real executa existe nas escritas de registrador (e crates/nrf52833/tests/firmware.rs verifica que uma linha está acesa por vez), mas a imagem entregue ao canvas são as vinte e cinco de uma vez, sem brilho por pixel e sem persistência.
  • O alto-falante é uma onda quadrada que o próprio runtime cronometra, reportada como uma frequência entre 20 Hz e 20 kHz com uma manutenção de 40 ms e 60 ms de silêncio para parar, não uma forma de onda dirigida, sem volume e sem periférico de PWM por trás.
  • Os pads são três estados e um limiar. Push-pull a 3,3 V, alta impedância, ou um pull interno de 13 kΩ (o típico da especificação), lidos contra metade da alimentação, sem histerese, sem ajuste de força de acionamento, sem tempo de subida e sem limite de corrente. Apenas os anéis 0, 1, 2, 3V e GND são pinos aqui; o resto do conector de borda não é.
  • A placa é uma fonte de alimentação ideal a 3,3 V; nada sofre brown-out, e nem o conector de bateria nem a alimentação USB são modelados. A inicialização leva um microssegundo.

Deliberately absent, as section 6 lists: the radio, the accelerometer, compass, microphone and touch logo, SAADC, PWM, PPI, I2S, SPIM, TWIM, PDM, NFC, USB, the temperature sensor, the watchdog, RTC1 and RTC2, TIMER3 and TIMER4, the FPU, flash programming, the soft device, the DAPLink interface chip and the file system. Their addresses are unmapped, so touching one is a fault rather than a silent zero, which means analogRead and analogWrite have no peripheral behind them, and a MakeCode or MicroPython .hex will not run here.