Convenzioni per la scrittura di codice in assembler

1) Leggibilità del codice
  1a) Utilizzo attento dei nomi
  1b) Indentazione del codice
  1c) Documentazione del codice
2) Layering
3) Evitare l'utilizzo dei "magic numbers" all'interno del codice

- http://users.ece.cmu.edu/~eno/coding/CCodingStandard.html
- http://users.ece.utexas.edu/~valvano/EE345L/Labs/Fall2011/style.pdf

Prima di imparare a scrivere programmi perfettamente funzionanti e performanti dovete imparare a scrivere codice chiaro e facilmente comprensibile, per voi e per le persone appartenenti al vostro gruppo di lavoro.
Diventa quindi importante rispettare, durante la scrittura del codice, stili e regole condivise.

I COMMENTI
I commenti presenti nei programmi saranno su tre livelli:
1. intestazione del modulo:

;==========================================================================================
; Project:  Assembler Template <nome del progetto/modulo/libreria>
; Date:     24/10/16 
; Author:   <inserire il nome dell'autore>
;~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
;
;  <inserire una breve descrizione del progetto/modulo/libreria>
;  <specifiche del progetto/modulo/libreria>
;  <specifiche del collaudo>
;
; Ver   Date        Comment
;~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
; 1.0   24/10/16     Versione iniziale
; <Descrivere per ogni revisione o cambio di versione le modifiche apportate>
; 
;==========================================================================================

2. intestazione delle routine:
;-----------------------------------------------------------------------------------------
; <inserire una breve descrizione della routine>
;
; INPUT:  <elenco dei parametri in ingresso alla funzione>
; OUTPUT: <valori restituiti (registri, variabili)>
; AUTORE: <nome dell'autore>
; 31/03/18  1.0  Versione iniziale
; <Descrivere per ogni revisione o cambio di versione le modifiche apportate> 
;-----------------------------------------------------------------------------------------

3. gruppi o singole istruzioni: i commenti che precedono il gruppi di istruzioni seguono l'indentazione del codice; per  le singole istruzioni il commento va messo preferibilmente a destra dell'istruzione stessa. Scriver i commenti prima del codice, scrivere cosa avete intenziore di fare seguendo quanto già scritto nei diagrammi
// Defines for I2C
// GPIO register offsets from BCM2835_BSC*_BASE.
// Offsets into the BSC Peripheral block in bytes per 3.1 BSC Register Map
#define BCM2835_BSC_C        0x0000 // BSC Master Control
#define BCM2835_BSC_S        0x0004 // BSC Master Status
#define BCM2835_BSC_DLEN     0x0008 // BSC Master Data Length
#define BCM2835_BSC_A        0x000c // BSC Master Slave Address

SEZIONI DEL FILE
rendere evidenti tramite dei commenti separatori le varie sezioni del file

1. Intestazione iniziale
2. Dichiarazioni di constanti e inclusione di quelle globali
3. Definizione di variabili/ Area DATA
4. Area CODE
5. Definizione delle funzioni

NOMI PER VARIABILI, COSTANTI e FUNZIONI
Per le variabili e le funzioni usare la notazione cammello l'iniziale del nome va scritto in maiuscolo per le variabile o le funzioni pubbliche.
I nomi delle costanti vanno scritte con tutti i caratteri in maiuscolo usando l'underscore per separare le parole che compongono il nome complessivo.
Usare nomi brevi ma significativi.

ALTRO
- Scrivere le etichette nella colonna zero dell'editor.
- Usare due tabulazioni per indentare le istruzioni.
- Nel file startup.s richiamare la funzione Main presente nel file Main.s e commentare la riga di codice ;IMPORT  __use_two_region_memory.
- Ragruppare le routine in moduli separati. Ad es. nel file Led.s scrivere tutte le routine che permettono di utilizzare i led presenti nell'hw: LedInit, LedOn, LedOff, LedTest, LedBlink, Led0On, Led0Off, Led1On, Led1Off, ...
- Inserire il file "GlobalDefine.inc" nel saranno presenti le dichiarazioni di costanti comuni a tutti i moduli

Template da utilizzare con Keil uVision
il file main.s deve essere presente in ogni progetto e deve avere sempre la seguente struttura
;==========================================================================================
; Project:  Assembler Template <nome del progetto>
; Date:     24/10/16 
; Author:   <inserire il nome dell'autore>
;~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
;
;  <inserire una breve descrizione del progetto>
;  <specifiche del progetto>
;  <specifiche del collaudo>
;
; Ver   Date        Comment
;~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
; 1.0   24/10/16     Versione iniziale
; <Descrivere per ogni revisione o cambio di versione le modifiche apportate>
; 
;==========================================================================================
;------------------------------------------------------------------------------------------
;=== COSTANTI =============================================================================
;------------------------------------------------------------------------------------------

THUMB
;------------------------------------------------------------------------------------------
;=== AREA DATI ============================================================================
;------------------------------------------------------------------------------------------
AREA MyData, DATA, ALIGN = 2

;------------------------------------------------------------------------------------------
;=== AREA ISTRUZIONI ======================================================================
;------------------------------------------------------------------------------------------
AREA MyCode, CODE, READONLY
;------------------
; EXPORT/IMPORT
;------------------

;INCLUDE subroutine.s
EXPORT Main

ENTRY
;------------------------------------------------------------------------------------------
;=== MAIN ROUTINE =========================================================================
;------------------------------------------------------------------------------------------
Main
       
; Inizializzazioni
;<routine di inizializzazione, per la configurazione dell'hw o del sw>
;BL LedInit
;BL ButtonInit

 
; Autodiagnostica
;<routine di autodiagnostica, per la verifica del funzionamento dell'hw>
;BL LedTest

 
MainLoop
; <richiare le routine relative all'esercizio corrente>
B MainLoop           ; Branch forever
;------------------------------------------------------------------------------------;
;   END MAIN
;------------------------------------------------------------------------------------;
ALIGN
END
  

-----
Versione 1.0.0 del 22.04.13

Revisione 1.0.1 del 20.02.14

Revisione 1.0.2 del 16.02.16
Revisione 1.0.3 del 25.10.16

Revisione 1.0.4 del 30.03.18