= WTI mailbox attribution politic =

**Une version française de cette page peut être trouvée [https://www-soc.lip6.fr/trac/almos-mk/wiki/attribution_boite_wti, ici]**

[[PageOutline]]
The architecture [https://www-soc.lip6.fr/trac/tsar TSAR] has a component [http://www.soclib.fr/trac/dev/wiki/Component/VciIopic Iopic]. This component permits an external peripheral to write to a specific address.

This peripheral is principally used to write to certain register of the [http://www.soclib.fr/trac/dev/wiki/Component/VciXicu Xicu] component. Those registers are mailboxes, when one of them is written then the XICU emits an interrupt so the concerned core will execute the associated ISR.

[[Image(WTI.svg, 50%)]]

We call those interruptions the **Write Triggered Interruptions (WTI)** because they are triggered by a write operation in the Xicu's mailboxes register.

== Mailboxes' attribution ==
Each cluster possess an XICU which has 16 mailboxes, 4 of them are reserved for the inter process interruptions (IPI). The fifth mailbox of the cluster 0's Xicu is also reserved, it is the `DEV_NULL` mailbox, its use will be explained later.

External peripherals can use 12 of this mailboxes to signal their I/O operation's end and that the ISR associated to the peripheral has to be executed.

We choose an attribution politic called "polluter-payer".

When a thread executes an I/O operation, it will be the core which executes the thread which will execute the ISR associated to that operation. For this we have to :
1. get a mailbox,
2. reconfigure the Xicu's mask,
3. link the peripheral's ISR to the mailbox

When the ISR will execute, we have to :
1. release the mailbox,
2. reconfigure the Xicu's mask to mask the interrupt,
3. unlink the peripheral's ISR to the mailbox


== External peripheral's I/O operation progress ==
Each external peripheral is protected by a global lock, to execute an I/O operation with one of this peripheral we firstly have to the lock.

We decided that before to take the peripheral's lock the core should assure that it got a mailbox. Indeed, it is easier to get a mailbox because they are 12 by cluster. Moreover, they are shared only by the cores of the same cluster. //A contrario//, the peripheral are unique so all the architecture's core compete for their access.

Once the mailbox and the lock got we have to configure the Iopic 

After the interruption's reception the peripheral's lock and the mailbox will be released.

Moreover, the Iopic will be un-configure, that is if the peripheral sends an interrup it will be in a special mailbox : `DEV_NULL`.

The `DEV_NULL` mailbox is the first free mailbox of the cluster 0's Xicu, its ISR is executed by the core 0 of this cluster.

The ISR linked to this specific mailbox only prints a error message which points that an unwanted interrupt was received. This mecanism was implemented to protect the operation system against peripheral's potential dysfunction.

In the first figure, the core P1 begins an I/O operation with the disk. In addition to configure the disk, the core also configures the IOPIC so that the disk can write in the local Xicu's fifth mailbox.

When the disk will end its I/O operation, it will ordoer the IOPIC to write in the fifth mailbox so the core P1 will execute the disk's ISR.

== mailbox attribution API ==
Pour mettre en place ce mécanisme nous avons dû écrire une API, celle-ci est composée d'une structure et de trois fonctions.

Les deux fonctions de base de l'API sont donc `get_configure_mailbox` et `put_mailbox`. En effet, celles-ci pourront être utilisées dans l'écriture de futur driver.

=== La structure `mbox_manager`===
Cette structure est présente dans chaque cluster, elle contient deux champs :
* un spinlock pour prévenir les accès concurents
* un tableau d'état des boîtes aux lettres

Chaque case du tableau représente l'état d'une boîte aux lettres, ces différents états sont :
* IPI : La boîte aux lettres est utilisée pour une IPI, elle ne sera donc pas utilisée pour une WTI. Les ''n'' premières boîtes aux lettres sont réservées à cet usage (où ''n'' est le nombre de cœur du cluster).
* FREE : La boîte est libre et peut-être utilisée pour une WTI.
* L'identifiant local du cœur propriétaire.

=== `void mbox_m_init(struct mbox_manager *mbox_m)` ===
Cette fonction est appelée lors de l'initialisation du cluster, elle marque les premières boîtes aux lettres comme étant réservées aux IPI tandis que les autres seront marquées comme étant libres.

=== `void get_configure_mailbox(struct mbox_manager *mbox_m, struct device_s *dev)` ===
Cette fonction alloue une boîte aux lettres du mbox_manager `mbox_m` au device `dev` reconfigure le masque de l'Xicu et associe l'ISR de `dev` à la boîte au lettre allouée.
Cette fonction est bloquante tant qu'aucune boîte aux lettres n'a été trouvée.

=== `int put_mailbox(uint_t wti_index, struct mbox_manager *mbox_m)` ===
Cette fonction rend la boîte aux lettres d'index `wti_index` appartenant au mbox_manager `mbox_m`, elle masque aussi l'interruption et dés-associe l'ISR et la boîte aux lettres.
Cette fonction renvoie 0 en cas de succès ou un code d'erreur dans le cas contraire.

== Avantages et inconvénients de cette API ==
L'utilisation de cette API permet une certaine souplesse. En effet, grâce à cette API il serait possible d'utiliser tous les périphériques si on disposait d'une XICU possédant une unique boîte aux lettres (bien entendu les processeurs devraient se la partager et il y aurait alors de la séquentialité).

Grâce à la politique pollueur/payeur les caches des cœurs ne sont pas gâchés par l'ISR d'un cœur voisin.

Toutefois l'utilisation de cette API rallonge les opérations d'entrée/sortie. **En effet, il semblerait que l'exécution d'un simple programme "`open; read; close;`" prenne 40 000 cycles supplémentaires par rapport à une opération d'entrée/sortie sans utilisation de l'API.**