.. include:: ../disclaimer-ita.rst
:Original: Documentation/process/botching-up-ioctls.rst
==========================================
(Come evitare di) Raffazzonare delle ioctl
==========================================
Preso da: https://blog.ffwll.ch/2013/11/botching-up-ioctls.html
Scritto da : Daniel Vetter, Copyright © 2013 Intel Corporation
Una cosa che gli sviluppatori del sottosistema grafico del kernel Linux hanno
imparato negli ultimi anni è l'inutilità di cercare di creare un'interfaccia
unificata per gestire la memoria e le unità esecutive di diverse GPU. Dunque,
oggigiorno ogni driver ha il suo insieme di ioctl per allocare memoria ed
inviare dei programmi alla GPU. Il che è va bene dato che non c'è più un insano
sistema che finge di essere generico, ma al suo posto ci sono interfacce
dedicate. Ma al tempo stesso è più facile incasinare le cose.
Per evitare di ripetere gli stessi errori ho preso nota delle lezioni imparate
mentre raffazzonavo il driver drm/i915. La maggior parte di queste lezioni si
focalizzano sui tecnicismi e non sulla visione d'insieme, come le discussioni
riguardo al modo migliore per implementare una ioctl per inviare compiti alla
GPU. Probabilmente, ogni sviluppatore di driver per GPU dovrebbe imparare queste
lezioni in autonomia.
Prerequisiti
------------
Prima i prerequisiti. Seguite i seguenti suggerimenti se non volete fallire in
partenza e ritrovarvi ad aggiungere un livello di compatibilità a 32-bit.
* Usate solamente interi a lunghezza fissa. Per evitare i conflitti coi tipi
definiti nello spazio utente, il kernel definisce alcuni tipi speciali, come:
``__u32``, ``__s64``. Usateli.
* Allineate tutto alla lunghezza naturale delle piattaforma in uso e riempite
esplicitamente i vuoti. Non necessariamente le piattaforme a 32-bit allineano
i valori a 64-bit rispettandone l'allineamento, ma le piattaforme a 64-bit lo
fanno. Dunque, per farlo correttamente in entrambe i casi dobbiamo sempre
riempire i vuoti.
* Se una struttura dati contiene valori a 64-bit, allora fate si che la sua
dimensione sia allineata a 64-bit, altrimenti la sua dimensione varierà su
sistemi a 32-bit e 64-bit. Avere una dimensione differente causa problemi
quando si passano vettori di strutture dati al kernel, o quando il kernel
effettua verifiche sulla dimensione (per esempio il sistema drm lo fa).
* I puntatori sono di tipo ``__u64``, con un *cast* da/a ``uintptr_t`` da lato
spazio utente e da/a ``void __user *`` nello spazio kernel. Sforzatevi il più
possibile per non ritardare la conversione, o peggio maneggiare ``__u64`` nel
vostro codice perché questo riduce le verifiche che strumenti come sparse
possono effettuare. La macro u64_to_user_ptr() può essere usata nel kernel
per evitare avvisi riguardo interi e puntatori di dimensioni differenti.
Le Basi
-------
Con la gioia d'aver evitato un livello di compatibilità, possiamo ora dare uno
sguardo alle basi. Trascurare questi punti renderà difficile la gestione della
compatibilità all'indietro ed in avanti. E dato che sbagliare al primo colpo è
garantito, dovrete rivisitare il codice o estenderlo per ogni interfaccia.
* Abbiate un modo chiaro per capire dallo spazio utente se una nuova ioctl, o
l'estensione di una esistente, sia supportata dal kernel in esecuzione. Se non
potete fidarvi del fatto che un vecchio kernel possa rifiutare correttamente
un nuovo *flag*, modalità, o ioctl, (probabilmente perché avevate raffazzonato
qualcosa nel passato) allora dovrete implementare nel driver un meccanismo per
notificare quali funzionalità sono supportate, o in alternativa un numero di
versione.
* Abbiate un piano per estendere le ioctl con nuovi *flag* o campi alla fine di
una struttura dati. Il sistema drm verifica la dimensione di ogni ioctl in
arrivo, ed estende con zeri ogni incongruenza fra kernel e spazio utente.
Questo aiuta, ma non è una soluzione completa dato che uno spazio utente nuovo
su un kernel vecchio non noterebbe che i campi nuovi alla fine della struttura
vengono ignorati. Dunque, anche questo avrà bisogno di essere notificato dal
driver allo spazio utente.
* Verificate tutti i campi e *flag* inutilizzati ed i riempimenti siano a 0,
altrimenti rifiutare la ioctl. Se non lo fate il vostro bel piano per
estendere le ioctl andrà a rotoli dato che qualcuno userà delle ioctl con
strutture dati con valori casuali dallo stack nei campi inutilizzati. Il che
si traduce nell'avere questi campi nell'ABI, e la cui unica utilità sarà
quella di contenere spazzatura. Per questo dovrete esplicitamente riempire i
vuoti di tutte le vostre strutture dati, anche se non le userete in un
vettore. Il riempimento fatto dal compilatore potrebbe contenere valori
casuali.
* Abbiate un semplice codice di test per ognuno dei casi sopracitati.
Divertirsi coi percorsi d'errore
--------------------------------
Oggigiorno non ci sono più scuse rimaste per permettere ai driver drm di essere
sfruttati per diventare root. Questo significa che dobbiamo avere una completa
validazione degli input e gestire in modo robusto i percorsi - tanto le GPU
moriranno comunque nel più strano dei casi particolari:
* Le ioctl devono verificare l'overflow dei vettori. Inoltre, per i valori
interi si devono verificare *overflow*, *underflow*, e *clamping*. Il
classico esempio è l'inserimento direttamente nell'hardware di valori di
posizionamento di un'immagine *sprite* quando l'hardware supporta giusto 12
bit, o qualcosa del genere. Tutto funzionerà finché qualche strano *display
server* non decide di preoccuparsi lui stesso del *clamping* e il cursore
farà il giro dello schermo.
* Avere un test semplice per ogni possibile fallimento della vostra ioctl.
Verificate che il codice di errore rispetti le aspettative. Ed infine,
assicuratevi che verifichiate un solo percorso sbagliato per ogni sotto-test
inviando comunque dati corretti. Senza questo, verifiche precedenti
potrebbero rigettare la ioctl troppo presto, impedendo l'esecuzione del
codice che si voleva effettivamente verificare, rischiando quindi di
mascherare bachi e regressioni.
* Fate si che tutte le vostre ioctl siano rieseguibili. Prima di tutto X adora
i segnali; secondo questo vi permetterà di verificare il 90% dei percorsi
d'errore interrompendo i vostri test con dei segnali. Grazie all'amore di X
per i segnali, otterrete gratuitamente un eccellente copertura di base per
tutti i vostri percorsi d'errore. Inoltre, siate consistenti sul modo di
gestire la riesecuzione delle ioctl - per esempio, drm ha una piccola
funzione di supporto `drmIoctl` nella sua librerie in spazio utente. Il
driver i915 l'abbozza con l'ioctl `set_tiling`, ed ora siamo inchiodati per
sempre con una semantica arcana sia nel kernel che nello spazio utente.
* Se non potete rendere un pezzo di codice rieseguibile, almeno rendete
possibile la sua interruzione. Le GPU moriranno e i vostri utenti non vi
apprezzeranno affatto se tenete in ostaggio il loro scatolotto (mediante un
processo X insopprimibile). Se anche recuperare lo stato è troppo complicato,
allora implementate una scadenza oppure come ultima spiaggia una rete di
sicurezza per rilevare situazioni di stallo quando l'hardware da di matto.
* Preparate dei test riguardo ai casi particolarmente estremi nel codice di
recupero del sistema - è troppo facile create uno stallo fra il vostro codice
anti-stallo e un processo scrittore.
Tempi, attese e mancate scadenze
--------------------------------
Le GPU fanno quasi tutto in modo asincrono, dunque dobbiamo regolare le
operazioni ed attendere quelle in sospeso. Questo è davvero difficile; al
momento nessuna delle ioctl supportante dal driver drm/i915 riesce a farlo
perfettamente, il che significa che qui ci sono ancora una valanga di lezioni da
apprendere.
* Per fare riferimento al tempo usate sempre ``CLOCK_MONOTONIC``. Oggigiorno
questo è quello che viene usato di base da alsa, drm, e v4l. Tuttavia,
lasciate allo spazio utente la possibilità di capire quali *timestamp*
derivano da domini temporali diversi come il vostro orologio di sistema
(fornito dal kernel) oppure un contatore hardware indipendente da qualche
parte. Gli orologi divergeranno, ma con questa informazione gli strumenti di
analisi delle prestazioni possono compensare il problema. Se il vostro spazio
utente può ottenere i valori grezzi degli orologi, allora considerate di
esporre anch'essi.
* Per descrivere il tempo, usate ``__s64`` per i secondi e ``__u64`` per i
nanosecondi. Non è il modo migliore per specificare il tempo, ma è
praticamente uno standard.
* Verificate che gli input di valori temporali siano normalizzati, e se non lo
sono scartateli. Fate attenzione perché la struttura dati ``struct ktime``
del kernel usa interi con segni sia per i secondi che per i nanosecondi.
* Per le scadenze (*timeout*) usate valori temporali assoluti. Se siete dei
bravi ragazzi e avete reso la vostra ioctl rieseguibile, allora i tempi
relativi tendono ad essere troppo grossolani e a causa degli arrotondamenti
potrebbero estendere in modo indefinito i tempi di attesa ad ogni
riesecuzione. Particolarmente vero se il vostro orologio di riferimento è
qualcosa di molto lento come il contatore di *frame*. Con la giacca da
avvocato delle specifiche diremmo che questo non è un baco perché tutte le
scadenze potrebbero essere estese - ma sicuramente gli utenti vi odieranno
quando le animazioni singhiozzano.
* Considerate l'idea di eliminare tutte le ioctl sincrone con scadenze, e di
sostituirle con una versione asincrona il cui stato può essere consultato
attraverso il descrittore di file mediante ``poll``. Questo approccio si
sposa meglio in un applicazione guidata dagli eventi.
* Sviluppate dei test per i casi estremi, specialmente verificate che i valori
di ritorno per gli eventi già completati, le attese terminate con successo, e
le attese scadute abbiano senso e servano ai vostri scopi.
Non perdere risorse
-------------------
Nel suo piccolo il driver drm implementa un sistema operativo specializzato per
certe GPU. Questo significa che il driver deve esporre verso lo spazio
utente tonnellate di agganci per accedere ad oggetti e altre risorse. Farlo
correttamente porterà con se alcune insidie:
* Collegate sempre la vita di una risorsa creata dinamicamente, a quella del
descrittore di file. Considerate una mappatura 1:1 se la vostra risorsa
dev'essere condivisa fra processi - passarsi descrittori di file sul socket
unix semplifica la gestione anche per lo spazio utente.
* Dev'esserci sempre Il supporto ``O_CLOEXEC``.
* Assicuratevi di avere abbastanza isolamento fra utenti diversi. Di base
impostate uno spazio dei nomi riservato per ogni descrittore di file, il che
forzerà ogni condivisione ad essere esplicita. Usate uno spazio più globale
per dispositivo solo se gli oggetti sono effettivamente unici per quel
dispositivo. Un controesempio viene dall'interfaccia drm modeset, dove
oggetti specifici di dispositivo, come i connettori, condividono uno spazio
dei nomi con oggetti per il *framebuffer*, ma questi non sono per niente
condivisi. Uno spazio separato, privato di base, per i *framebuffer* sarebbe
stato meglio.
* Pensate all'identificazione univoca degli agganci verso lo spazio utente. Per
esempio, per la maggior parte dei driver drm, si considera fallace la doppia
sottomissione di un oggetto allo stesso comando ioctl. Ma per evitarlo, se
gli oggetti sono condivisibili, lo spazio utente ha bisogno di sapere se il
driver ha importato un oggetto da un altro processo. Non l'ho ancora provato,
ma considerate l'idea di usare il numero di inode come identificatore per i
descrittori di file condivisi - che poi è come si distinguono i veri file.
Sfortunatamente, questo richiederebbe lo sviluppo di un vero e proprio
filesystem virtuale nel kernel.
Ultimo, ma non meno importante
------------------------------
Non tutti i problemi si risolvono con una nuova ioctl:
* Pensateci su due o tre volte prima di implementare un'interfaccia privata per
un driver. Ovviamente è molto più veloce seguire questa via piuttosto che
buttarsi in lunghe discussioni alla ricerca di una soluzione più generica. Ed
a volte un'interfaccia privata è quello che serve per sviluppare un nuovo
concetto. Ma alla fine, una volta che c'è un'interfaccia generica a
disposizione finirete per mantenere due interfacce. Per sempre.
* Considerate interfacce alternative alle ioctl. Gli attributi sysfs sono molto
meglio per impostazioni che sono specifiche di un dispositivo, o per
sotto-oggetti con una vita piuttosto statica (come le uscite dei connettori in
drm con tutti gli attributi per la sovrascrittura delle rilevazioni). O magari
solo il vostro sistema di test ha bisogno di una certa interfaccia, e allora
debugfs (che non ha un'interfaccia stabile) sarà la soluzione migliore.
Per concludere. Questo gioco consiste nel fare le cose giuste fin da subito,
dato che se il vostro driver diventa popolare e la piattaforma hardware longeva
finirete per mantenere le vostre ioctl per sempre. Potrete tentare di deprecare
alcune orribili ioctl, ma ci vorranno anni per riuscirci effettivamente. E
ancora, altri anni prima che sparisca l'ultimo utente capace di lamentarsi per
una regressione.
Codebase Browser
linux