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 xx 2F: run

Esegue una funzione builtin (use). Si tratta di un'istruzione anomala, in quanto identificata dal secondo byte. Gli argomenti passati sono quelli precedentemente caricati nei registri Wx. Se nei registri ci sono più argomenti di quanti necessari, vengono usati i più recenti.

• byte 1: indica il numero progressivo (partendo da 0) della funzione da eseguire, nell'ordine in cui è citata all'interno della sezione usage
• byte 3-4: sempre 00 00
• byte 5: indica a quale blocco usage fa riferimento l'istruzione (00 solitamente è basic, 01 basicio e 02 quello indicato dalla prima direttiva "use" del sorgente)

Assegna il risultato al registro W1.

istruzione 01 3B: invocazione di un metodo (method)

Esegue il metodo W1.const dove const è la costante stringa indicata dal puntatore ai bytes 3-5. Assegna il risultato a W1.

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 si tratta di una costante, "offset" indica l'ID della costante. 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, 1E: 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
• 1E: L = L.R (legge la proprietà di un oggetto)

Ancora da chiarire:
* 08: Assegna il valore indicato dall'ultimo registro W al registro W1 (W1 := W<last>). I byte 3-5 sono sempre 00. Sempre che sia usato 08 se  l'assegnazione avviene contestualmente alla dichiarazione, altrimenti 42.
* 1E: Assegna al registro W1 la priorità dell'oggetto identificata da W<last-1>.W<last>
* 38: Assegna il nome della variabile alla sezione program. I byte 3-5 sono un puntatore alla costante. L'ID della variabile usato è automaticamente il primo libero.
* 04: Assegna a un nuovo registro Wx la concatenazione delle stringhe W1 + W2

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