ZPUTA (Applicazione di Test ZPU)

English

ZPUTA

ZPUTA e' nata come semplice applicazione di test per verificare i design hardware della ZPU Evo e del SoC durante il loro sviluppo. Il nome deriva da ZPU Test Application. Si e' evoluta nel tempo da un semplice programma a qualcosa con un grado di sofisticazione simile a un sistema operativo. Puo' essere costruita come singola immagine firmware con tutta la funzionalita' incorporata oppure suddivisa, con la maggior parte della funzionalita' che risiede su un dispositivo di archiviazione collegato come una scheda SD. zOS e' stato derivato da ZPUTA e ha avuto gran parte della funzionalita' interna rimossa, affidandosi all'archiviazione esterna, il che lo rende piu' adatto per essere incorporato in progetti finali.

Originariamente, gli sviluppi di ZPUTA/zOS miravano solo all'architettura ZPU, e avevano due metodi di esecuzione primari:

• come applicazione avviata da IOCP,
• in modalita’ autonoma come firmware di avvio della ZPU Evo.

La modalita' viene scelta nella configurazione e la funzionalita' e' identica. Quando avviato come applicazione da IOCP, zOS e' memorizzato su una scheda SD e caricato all'avvio. In modalita' autonoma, zOS e' memorizzato nella flash onboard (o BRAM preconfigurata come ROM).

Recentemente, zOS/ZPUTA e' stato portato sull'architettura ARM Cortex-M4, per l'uso con il Freescale K64F nel progetto tranZPUterSW. Poiche' il K64F e' un CPU/SoC ad architettura fissa, esiste un solo metodo di esecuzione: 'autonomo'.

L'idea dietro ZPUTA e' principalmente il testing, ottenere accesso interno a un sistema hardware embedded e eseguire codelet per testare o sperimentare funzionalita' hardware. Ogni test verrebbe costruito come funzione interna e come app esterna, il che era cruciale a causa delle schede di sviluppo utilizzate.

Per il funzionamento, ZPUTA richiede come minimo una connessione seriale (fisica o USB virtuale), preferibilmente due per l'output di debug. Sulla connessione seriale primaria, e' preferibile avere collegato un pacchetto di emulazione terminale ANSI/VT100.

Utilizzo di ZPUTA

L'interfaccia ZPUTA e' stata scritta considerando che e' disponibile solo un terminale testuale seriale. Alcuni componenti come l'editor richiedono capacita' avanzate, e a questo scopo e' stata scelta la collaudata emulazione VT100 come candidato adatto. L'interazione e' basata su tastiera e testo (nessuna bella interfaccia GUI!).

Prima di ZPUTA, ho creato un programma di bootstrap chiamato IOCP (I/O Control Program) che operava ai livelli hardware piu’ bassi ed era in grado di avviare programmi piu’ sofisticati, ad esempio ZPUTA. IOCP e’ sensibile alle dimensioni e progettato per il bootstrap da qualsiasi dispositivo di archiviazione, e includendo una scheda SD e Petit FatFS puo’ eseguire il bootstrap da una scheda SD.

ZPUTA manterra' il suo scopo originale -- il testing -- mentre zOS diventera' col tempo un sistema operativo raffinato per i miei progetti.

Riga di comando

Il primo incontro con il sistema operativo e’ un messaggio di accesso che mostra CPU, versione, ecc. e presenta un prompt per l’inserimento dei comandi:

L'interazione con il sistema operativo non differisce da MSDOS -- si digita un comando e si riceve una risposta. La riga di comando di ZPUTA non e' un interprete di shell, ma solo una semplice interfaccia testuale con funzionalita' readline semplificata e cronologia.

Le mappature dei tasti readline e la lista completa dei comandi per IO su disco, buffer disco, file system, memoria, hardware, test di prestazione, esecuzione programmi e applicazioni sono identiche alla versione inglese e sono elencate li’.

Applicazioni

Le applicazioni fornite da ZPUTA si trovano su una scheda SD. La referenza completa dei comandi si trova nella [versione inglese](/zputa/).

Dettagli tecnici

Questa sezione mira a fornire alcuni dei dettagli interni dell'applicazione. Molte di queste informazioni sono identiche in zOS, ma man mano che zOS matura, ci saranno differenze significative.

Organizzazione della memoria

Le mappe di memoria di IOCP e ZPUTA sono identiche alla versione inglese e sono presentate li’.

Interfaccia dell'applicazione

Come la maggior parte dei sistemi operativi, ZPUTA fornisce un’API che un’applicazione opportunamente compilata puo’ utilizzare per ridurre le proprie dimensioni e complessita’ e riutilizzare le funzioni all’interno del sistema operativo come la connessione seriale.

Piuttosto che progettare un set API personalizzato, era piu’ sensato esporre i metodi all’interno di ZPUTA per l’uso dell’applicazione, ad esempio printf. Questo viene ottenuto creando una tabella di salto a un vettore fisso all’interno di ZPUTA.

La tabella completa dei vettori API e gli esempi di codice sono identici alla versione inglese.

Configurazione e compilazione automatizzate (consigliato)

Il modo consigliato per compilare ZPUTA e' lo script di configurazione automatizzata per la propria piattaforma. Verifica e installa i prerequisiti, installa la toolchain ZPU, clona il repository (se non ci si trova gia' all'interno di un checkout) e propone di eseguire la prima compilazione — con valori predefiniti sensati che si possono accettare premendo Enter. Ogni script e' autonomo: e' sufficiente copiare il singolo file per la propria piattaforma ed eseguirlo. I passaggi manuali piu' in basso sono destinati agli utenti avanzati, alle ricompilazioni parziali e alla CI.

La compilazione e' gestita da build.sh, che assembla/compila IOCP, ZPUTA e le app per una determinata CPU in un unico passaggio. ZPUTA puo' essere compilato come singola immagine autonoma con la propria funzionalita' incorporata (utile quando non e' presente una scheda SD) oppure suddiviso con gli applet sulla scheda SD. Sono coinvolte due toolchain e gli script di configurazione le forniscono entrambe:

Toolchain	CPU di destinazione	Origine
ZPU zpu-elf-gcc 3.4.2	Small Medium Flex Evo EvoMin (ZPU)	installata in /opt/zpu (da ZPU_TOOLCHAIN_URL)
ARM arm-none-eabi	K64F (Kinetis / Teensy 3.5)	inclusa nel repository in tools/arm (nessuna installazione)

Poiche’ entrambe le toolchain sono binari Linux / cross, la compilazione viene eseguita nativamente su Linux, in Docker su macOS e tramite WSL1 su Windows:

Script	Piattaforma	Note
setup_zSoft.sh	Linux (nativo) / macOS (Docker)	Installa gli strumenti di build di base + la toolchain ZPU; su macOS compila all’interno dell’immagine Docker zsoft-build:latest.
setup_zSoft_windows.cmd	Windows 10 / 11	Launcher da doppio clic che richiama lo script PowerShell sottostante.
setup_zSoft_windows_native.ps1	Windows 10 / 11 (WSL1)	Configura WSL1 (distribuzione predefinita Ubuntu-24.04) ed esegue al suo interno la configurazione Linux.
setup_zSoft_wsl1.sh	all’interno di WSL1	Il passo di configurazione Linux richiamato automaticamente nella distribuzione WSL1.

Linux / macOS — setup_zSoft.sh

chmod +x setup_zSoft.sh
./setup_zSoft.sh

Windows 10 / 11 — setup_zSoft_windows_native.ps1 — doppio clic su setup_zSoft_windows.cmd, oppure da un prompt PowerShell:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\setup_zSoft_windows_native.ps1

La configurazione clona ZSOFT_REPO_URL (predefinito https://git.eaw.app/eaw/zSoft.git) in ~/zSoft. Una volta terminata, si compila ZPUTA con (build.sh seleziona automaticamente native / Docker / WSL1 per l’host):

./build.sh -C Evo  -O zputa      # ZPUTA for the Evo ZPU
./build.sh -C K64F -O zputa      # ZPUTA for the K64F (ARM Cortex-M4)
./build.sh -h                    # all options (-C CPU, -I IOCP, -O os, -o os ver, addresses, sizes ...)

Gli output vengono creati in build/ e build/SD/ — la ROM di avvio (BOOT.ROM / BOOTTINY.ROM), il boot loader IOCP_<func>_<addr>.bin e il file .bin di ZPUTA, oltre ai binari delle app in bin/ pronti per essere copiati su una scheda SD formattata FAT.

Override utili delle variabili d’ambiente:

Variabile	Scopo
ZSOFT_REPO_URL	Repository da clonare (predefinito https://git.eaw.app/eaw/zSoft.git).
ZSOFT_DIR	Compila all’interno di un checkout esistente invece di clonare.
ZPU_TOOLCHAIN_URL	Posizione del tarball della toolchain zpu-elf-gcc 3.4.2 installata in /opt/zpu.
ZSOFT_BUILD_IMAGE	Immagine Docker usata per la compilazione su macOS (predefinita zsoft-build:latest).
ZSOFT_WSL_DISTRO	Nome della distribuzione WSL1 su Windows (predefinito Ubuntu-24.04).
ZSOFT_ASSUME_YES=1	Accetta tutti i prompt in modo non interattivo (installazioni automatiche / CI).

Se si preferisce compilare manualmente o si sta creando una pipeline CI, la compilazione manuale — i percorsi, l'elenco degli strumenti, l'albero di build e la matrice completa dei flag di build.sh — e' documentata nella sezione Build del software immediatamente sotto.

Build del software

Questa sezione mostra come costruire un kernel ZPUTA di base. Il punto di partenza per il build di ZPUTA e’ lo script ‘build.sh’.

Percorsi

La tabella completa dei percorsi e la documentazione del build tree sono identiche alla versione inglese.

Strumenti

Tutto lo sviluppo e’ stato effettuato su Linux, in particolare Debian/Ubuntu. Il software necessario include la ZPU GCC ToolChain e opzionalmente Arduino e Teensyduino.

Build.sh

La documentazione completa di build.sh con tutti i parametri e gli esempi si trova nella versione inglese.

Ringraziamenti

I ringraziamenti e le licenze sono identici alla versione inglese.

Licenze

La licenza FreeBSD

Questo progetto e’ rilasciato sotto la licenza FreeBSD. I dettagli si trovano nella versione inglese.

La GNU Public License v3

Parti di questo progetto sono rilasciate sotto la GPLv3. I dettagli si trovano nella versione inglese.