ECL Format

Nella seguente documentazione si farà a volte riferimento ai sorgenti del POL. I sorgenti in quetsione sono i sorgenti del POL099 disponibili al seguente indirizzo: https://github.com/polserver/polserver. Nello specifico, il commit di riferimento alla data di redazione di questo documento è: 820790a6feedaa0462bfc3aa96faa739e08f0ecd.

I file pol-core/bscript/tokens.h e pol-core/bscript/executor.cpp contengono la maggior parte delle informazioni necessarie.

Codifica dei tipi

All'interno del file, sono condificati dati di più tipi primitivi a cui si farà riferimento successivamente. Le codifiche finora individuate sono:

• stringa a lunghezza fissa: La lunghezza è indicata preventivamente all'interno del blocco che ne fa uso o altrove. È rappresentata da un numero fisso di bytes, dove quelli non utilizzati sono impostati a NULL.
• stringa a lunghezza variabile: Si tratta di un numero variabile di bytes stringa di cui l'ultimo è sempre NULL e rappresenta la fine della stringa stessa
• numero intero: gli interi sono codificati sempre come 4 bytes, ordinati dal meno al più significativo (quindi invertiti, da un punto di vista algebrico). Sono sempre signed: il valore massimo per un intero è 0x7FFFFFFF, rappresentato come FF FF FF 7F. I valori negativi sono rappresentati partendo da FF FF FF FF che significa -1 e poi sottraendo la rappresentazione del valore come se fosse (intero - 1); ad esempio -255 è rappresentato come 01 FF FF FF.
• numeri a virgola mobile (float): i numeri a virgola mobile sono codificati sempre come 8 bytes (da chiarire in che formato, probabilmente 4 bytes base + 4 bytes esponente)

Header

Ogni file inizia con un header di 6 bytes così definito:

• byte 1-2: rappresentano il magic number del formato ("CE")
• byte 3: rappresenta il numero di versione (02 per POL093)
• byte 4: sempre 00
• byte 5: contiene un valore da decodificare (tra 00 e 07)
• byte 6: sempre 00

Struttura

Successivamente all'header, il file ECL sembra avere una struttura a sezioni. Di seguito sono elencati quelli noti, riportati nello stesso ordine in cui compariranno all'interno del file.

Ciascuna sezione inizia con 6 (2+4) bytes. Di questi 6 bytes, i primi 2 rappresentano il codice dela sezione, mentre i successivi 4 rappresentano, sotto forma di intero, la lunghezza della sezione, in bytes, non conteggiando i 6 bytes dell'intestazione stessa.

Fa eccezione il codice 01 00 per cui la lunghezza viene indicata sempre come 0.

Program - codice 04 00

Questa sezione definisce la direttiva program.

Non è sempre presente: ad esempio, non è usato nello script generale di startup start.ecl.

I primi 6 bytes sono 04 00 - 10 00 00 00, seguono 16 bytes di cui solo il primo sembra essere usato ed indica il numero di argomenti accettati dalla sezione program (01, 02, etc...).

Gli altri bytes sono sempre lasciati a NULL.

Usages - codice 01 00

I file .em contenenti le funzioni di sistema importati con la direttiva use sono specificate immediatamente dopo l'header. Ogni blocco use ha una dimensione variabile.

I primi 6 bytes sono 01 00 00 00 00 00, segue un blocco di 13 bytes così suddiviso:

• bytes 1-9: contengono il nome dell'usage sotto forma di stringa a lunghezza fissa
• byte 10: indica il numero di funzioni utilizzate da questo file
• bytes 11-13: sempre NULL

Segue la lista delle funzioni utilizzate da questo file, sotto forma 34 bytes ripetuti per il numero di volte indicato dal byte 10. Di questi 34 bytes, i primi 33 rappresentano una stringa a lunghezza fissa contenente il nome della funzione, mentre l'ultimo byte indica il numero di parametri accettati dalla funzione stessa.

"basic" e "basicio" sembrano essere sempre i primi due usages e sono inclusi implicitamente, e ribaditi quindi nel file ECL, anche se non dichiarati nello script sorgente.

Istruzioni - codice 02 00

ATTENZIONE!!! È probabile che questa sezione contenga ancora molti errori o imprecisioni

La sezione segue la struttura sopra citata: nell'intestazione è indicata la lunghezza della sezione in byte. Segue un intero che indica nuovamente la lunghezza della sezione meno i 4 byte che compongono l'intero stesso, per un totale di 10 byte di intestazione.

I successivi byte rappresentano le istruzioni stesse e sono sempre un numero di byte divisibile per 5.

Un'istruzione è composta da 5 byte, così definiti (pol-core/bscript/symcont.h:30):

• byte 1 - type: sebbene sia dichiarato come instruction type ed abbia una serie di valori predefiniti (pol-core/bscript/tokens.h:14), si ritiene che il suo significato originale sia andato perso. La maggior parte delle volte il suo valore può essere ignorato, mentre in alcuni casi speciali si limita a contenere degli argomenti
• byte 2 - id: identifica il tipo di istruzione e la sua funzione (pol-core/bscript/tokens.h:47)
• byte 3-4 - offset: contengono il primo parametro per l'istruzione, solitamente un puntatore a un indirizzo all'interno del blocco costanti, l'ID di una variabile, o una posizione dall'interno del programma (goto)
• byte 5 - module: contengono il secondo parametro per l'istruzione. Non viene usato spesso.

registri

Sono presenti un numero indefinito di registri W, utilizzati come argomenti per le chiamate alle funzioni builtin. Tali registri sono rappresentati come un'array o lista di registri. Nell'implementazione POL è usata una deque (http://it.cppreference.com/w/cpp/container/deque).

elementi

All'interno di una istruzione, si possono trovare uno o più dei seguenti elementi che si ripetono, tutti a lunghezza fissa:

• intero3 (3 byte): Si tratta di un intero che ha lo stesso formato dell'intero definito precedentemente, ma manca del byte più significativo, che si assume essere sempre 00.
• puntatore (4 byte):
  • byte 1: Il tipo di argomento: 00 = intero, 01 = float, 02 = stringa, 33 = variabile locale, 34 = variabile globale
  • byte 2-4: Se il byte precedente indica una costante, è l'offset all'interno della sezione delle costanti (intestazione esclusa): indica la posizione in byte dell'argomento da leggere. È da notare che le stringhe possono non essere lette dall'inizio: ad esempio, una stringa "abc" può essere usata come stringa "bc" semplicemente puntando al secondo carattere anziché all'inizio della stringa. Nel caso di una variabile, è il suo ID univoco. Rappresentato come intero3.

istruzione 2F: run

Esegue una funzione builtin (use).Il numero progressivo (partendo da 0) della funzione da eseguire, nell'ordine in cui è citata all'interno della sezione usage è indicato dal byte "type". Il byte "module" indica a quale blocco usage fa riferimento l'istruzione (00 solitamente è basic, 01 basicio e 02 quello indicato dalla prima direttiva "use" del sorgente).

Per prima cosa recupera il numero di parametri indicato nella relativa dichiarazione dall'interno della sezione usage, consumandoli da W. Quindi aggiunge il risultato della funzione alla fine di W.

istruzione 3B: invocazione di un metodo (method)

Per prima cosa, recupera il numero di parametri (Pn) indicato da "offset", rimuovendoli uno ad uno dalla fine di W. Quindi recupera un ulteriore parametro R, consumandolo. Esegue il metodo R.const dove const è la costante stringa indicata da "offset". Aggiunge il risultato alla fine di W.

istruzioni 00,01,02,33,34: accesso a una variabile o costante (load)

Copia una costante o una variabile aggiungendo un nuovo elemento alla fine di W. Se si tratta di una costante, "offset" è la posizione del valore all'interno del blocco costanti. Se invece si tratta di una variabile, "offset" indica l'ID della variabile. Il token è così differenziato:

• 00: legge una costante interpretando il valore come intero
• 01: legge una costante interpretando il valore come float
• 02: legge una costante interpretando il valore come stringa
• 33: legge una variabile locale
• 34: legge una variabile globale

istruzioni 04,05,06,07,08, 13,14, 1A, 1E, 42: assegnazione (assign)

Questa categoria di istruzioni prende due operatori dai registri W e li sostituisce con uno. Il tipo di operazione eseguito, l'operatore, cambia in base al token. I due operatori sono R (right), ovvero l'ultimo elemento di W e L (left), ovvero il penultimo elemento di W. R viene rimosso mentre L viene sostituito con il risultato dell'operazione.

L'istruzione cambia significato in base al valore del byte 2:

• 04: L = L + R
• 05: L = L - R
• 06: L = L * R
• 07: L = L / R
• 08: L = R
• 13: L = L == R
• 14: L = L != R
• 1A: L = L[R]
• 1E: L = L.R (legge la proprietà di un oggetto)
• 42: L = & R (assegnazione byRef)

istruzione 38: recupera argomento (getarg)

Recupera un argomento il blocco corrente. "offset" è un puntatore alla sezione costanti, dove è memorizzato il nome della variabile. L'ID della variabile usato è automaticamente il primo libero nel contesto locale.

istruzioni 39,3a: definizione array (array)

Queste istruzioni sono usate per la creazione di una nuova array

• 3a: Crea una nuova array, aggiungendola in coda a W
• 39: Rimuove l'ultimo valore di W e lo aggiunge all'array che si trova nel penultimo valore di W

istruzione 19: pulizia dell'ultimo registro (consume)

Rimuove l'ultimo elemento dall'array W senza utilizzarlo.

istruzioni 2A/2B: dichiarazione di una variabile (var)

Dichiara una variabile e la carica nel prossimo registro (load). L'istruzione 2A dichiara una variabile locale mentre la 2B una globale. I bit "offset" indicano l'ID univoco della variabile.

istruzioni 25,26,27: salto (goto)

Salta alla posizione indicata da "offset". Se il salto è condizionale, salta solo dopo aver valutato l'ultimo valore nel registro W, consumandolo.

• 25: salta se TRUE
• 26: salta se FALSE
• 27: salto incondizionato (non modifica i registri)

istruzione 20: fine programma (progend)

Arresta l'esecuzione. È automaticamente inclusa dal compilatore alla fine della sezione istruzioni.

istruzione 24: fine blocco (blockend)

Rimuove il numero di variabili indicato da "offset" dalla fine dei registri W.

Costanti - codice 03 00

In questa sezione, l'ultima del file, sono contenute le costanti usate all'interno del file stesso.

L'inizio della sezione è indicata dai 6 bytes 03 00 XX XX XX XX: dove XX rappresenta la lunghezza della sezione, in formato intero: sembra sempre uguale all'intero indicato dai successivi 4 bytes + 4.

I successivi 4 bytes rappresentano un intero che indica il numero di bytes da cui è composta la sezione delle costanti + 1 (ovvero indica 1 per 0 bytes, 2 per 1 byte, etc...).

Ad esempio, una sezione costanti contenente 4 bytes di dati puri inizierà con: 03 00 - 09 00 00 00 - 05 00 00 00.

Possono essere presenti i seguenti tipi di dati:

• stringhe a lunghezza variabile
• interi
• float