1.. include:: ../disclaimer-ita.rst 2 3:Original: Documentation/process/botching-up-ioctls.rst 4 5========================================== 6(Come evitare di) Raffazzonare delle ioctl 7========================================== 8 9Preso da: https://blog.ffwll.ch/2013/11/botching-up-ioctls.html 10 11Scritto da : Daniel Vetter, Copyright © 2013 Intel Corporation 12 13Una cosa che gli sviluppatori del sottosistema grafico del kernel Linux hanno 14imparato negli ultimi anni è l'inutilità di cercare di creare un'interfaccia 15unificata per gestire la memoria e le unità esecutive di diverse GPU. Dunque, 16oggigiorno ogni driver ha il suo insieme di ioctl per allocare memoria ed 17inviare dei programmi alla GPU. Il che è va bene dato che non c'è più un insano 18sistema che finge di essere generico, ma al suo posto ci sono interfacce 19dedicate. Ma al tempo stesso è più facile incasinare le cose. 20 21Per evitare di ripetere gli stessi errori ho preso nota delle lezioni imparate 22mentre raffazzonavo il driver drm/i915. La maggior parte di queste lezioni si 23focalizzano sui tecnicismi e non sulla visione d'insieme, come le discussioni 24riguardo al modo migliore per implementare una ioctl per inviare compiti alla 25GPU. Probabilmente, ogni sviluppatore di driver per GPU dovrebbe imparare queste 26lezioni in autonomia. 27 28 29Prerequisiti 30------------ 31 32Prima i prerequisiti. Seguite i seguenti suggerimenti se non volete fallire in 33partenza e ritrovarvi ad aggiungere un livello di compatibilità a 32-bit. 34 35* Usate solamente interi a lunghezza fissa. Per evitare i conflitti coi tipi 36 definiti nello spazio utente, il kernel definisce alcuni tipi speciali, come: 37 ``__u32``, ``__s64``. Usateli. 38 39* Allineate tutto alla lunghezza naturale delle piattaforma in uso e riempite 40 esplicitamente i vuoti. Non necessariamente le piattaforme a 32-bit allineano 41 i valori a 64-bit rispettandone l'allineamento, ma le piattaforme a 64-bit lo 42 fanno. Dunque, per farlo correttamente in entrambe i casi dobbiamo sempre 43 riempire i vuoti. 44 45* Se una struttura dati contiene valori a 64-bit, allora fate si che la sua 46 dimensione sia allineata a 64-bit, altrimenti la sua dimensione varierà su 47 sistemi a 32-bit e 64-bit. Avere una dimensione differente causa problemi 48 quando si passano vettori di strutture dati al kernel, o quando il kernel 49 effettua verifiche sulla dimensione (per esempio il sistema drm lo fa). 50 51* I puntatori sono di tipo ``__u64``, con un *cast* da/a ``uintptr_t`` da lato 52 spazio utente e da/a ``void __user *`` nello spazio kernel. Sforzatevi il più 53 possibile per non ritardare la conversione, o peggio maneggiare ``__u64`` nel 54 vostro codice perché questo riduce le verifiche che strumenti come sparse 55 possono effettuare. La macro u64_to_user_ptr() può essere usata nel kernel 56 per evitare avvisi riguardo interi e puntatori di dimensioni differenti. 57 58 59Le Basi 60------- 61 62Con la gioia d'aver evitato un livello di compatibilità, possiamo ora dare uno 63sguardo alle basi. Trascurare questi punti renderà difficile la gestione della 64compatibilità all'indietro ed in avanti. E dato che sbagliare al primo colpo è 65garantito, dovrete rivisitare il codice o estenderlo per ogni interfaccia. 66 67* Abbiate un modo chiaro per capire dallo spazio utente se una nuova ioctl, o 68 l'estensione di una esistente, sia supportata dal kernel in esecuzione. Se non 69 potete fidarvi del fatto che un vecchio kernel possa rifiutare correttamente 70 un nuovo *flag*, modalità, o ioctl, (probabilmente perché avevate raffazzonato 71 qualcosa nel passato) allora dovrete implementare nel driver un meccanismo per 72 notificare quali funzionalità sono supportate, o in alternativa un numero di 73 versione. 74 75* Abbiate un piano per estendere le ioctl con nuovi *flag* o campi alla fine di 76 una struttura dati. Il sistema drm verifica la dimensione di ogni ioctl in 77 arrivo, ed estende con zeri ogni incongruenza fra kernel e spazio utente. 78 Questo aiuta, ma non è una soluzione completa dato che uno spazio utente nuovo 79 su un kernel vecchio non noterebbe che i campi nuovi alla fine della struttura 80 vengono ignorati. Dunque, anche questo avrà bisogno di essere notificato dal 81 driver allo spazio utente. 82 83* Verificate tutti i campi e *flag* inutilizzati ed i riempimenti siano a 0, 84 altrimenti rifiutare la ioctl. Se non lo fate il vostro bel piano per 85 estendere le ioctl andrà a rotoli dato che qualcuno userà delle ioctl con 86 strutture dati con valori casuali dallo stack nei campi inutilizzati. Il che 87 si traduce nell'avere questi campi nell'ABI, e la cui unica utilità sarà 88 quella di contenere spazzatura. Per questo dovrete esplicitamente riempire i 89 vuoti di tutte le vostre strutture dati, anche se non le userete in un 90 vettore. Il riempimento fatto dal compilatore potrebbe contenere valori 91 casuali. 92 93* Abbiate un semplice codice di test per ognuno dei casi sopracitati. 94 95 96Divertirsi coi percorsi d'errore 97-------------------------------- 98 99Oggigiorno non ci sono più scuse rimaste per permettere ai driver drm di essere 100sfruttati per diventare root. Questo significa che dobbiamo avere una completa 101validazione degli input e gestire in modo robusto i percorsi - tanto le GPU 102moriranno comunque nel più strano dei casi particolari: 103 104 * Le ioctl devono verificare l'overflow dei vettori. Inoltre, per i valori 105 interi si devono verificare *overflow*, *underflow*, e *clamping*. Il 106 classico esempio è l'inserimento direttamente nell'hardware di valori di 107 posizionamento di un'immagine *sprite* quando l'hardware supporta giusto 12 108 bit, o qualcosa del genere. Tutto funzionerà finché qualche strano *display 109 server* non decide di preoccuparsi lui stesso del *clamping* e il cursore 110 farà il giro dello schermo. 111 112 * Avere un test semplice per ogni possibile fallimento della vostra ioctl. 113 Verificate che il codice di errore rispetti le aspettative. Ed infine, 114 assicuratevi che verifichiate un solo percorso sbagliato per ogni sotto-test 115 inviando comunque dati corretti. Senza questo, verifiche precedenti 116 potrebbero rigettare la ioctl troppo presto, impedendo l'esecuzione del 117 codice che si voleva effettivamente verificare, rischiando quindi di 118 mascherare bachi e regressioni. 119 120 * Fate si che tutte le vostre ioctl siano rieseguibili. Prima di tutto X adora 121 i segnali; secondo questo vi permetterà di verificare il 90% dei percorsi 122 d'errore interrompendo i vostri test con dei segnali. Grazie all'amore di X 123 per i segnali, otterrete gratuitamente un eccellente copertura di base per 124 tutti i vostri percorsi d'errore. Inoltre, siate consistenti sul modo di 125 gestire la riesecuzione delle ioctl - per esempio, drm ha una piccola 126 funzione di supporto `drmIoctl` nella sua librerie in spazio utente. Il 127 driver i915 l'abbozza con l'ioctl `set_tiling`, ed ora siamo inchiodati per 128 sempre con una semantica arcana sia nel kernel che nello spazio utente. 129 130 131 * Se non potete rendere un pezzo di codice rieseguibile, almeno rendete 132 possibile la sua interruzione. Le GPU moriranno e i vostri utenti non vi 133 apprezzeranno affatto se tenete in ostaggio il loro scatolotto (mediante un 134 processo X insopprimibile). Se anche recuperare lo stato è troppo complicato, 135 allora implementate una scadenza oppure come ultima spiaggia una rete di 136 sicurezza per rilevare situazioni di stallo quando l'hardware da di matto. 137 138 * Preparate dei test riguardo ai casi particolarmente estremi nel codice di 139 recupero del sistema - è troppo facile create uno stallo fra il vostro codice 140 anti-stallo e un processo scrittore. 141 142 143Tempi, attese e mancate scadenze 144-------------------------------- 145 146Le GPU fanno quasi tutto in modo asincrono, dunque dobbiamo regolare le 147operazioni ed attendere quelle in sospeso. Questo è davvero difficile; al 148momento nessuna delle ioctl supportante dal driver drm/i915 riesce a farlo 149perfettamente, il che significa che qui ci sono ancora una valanga di lezioni da 150apprendere. 151 152 * Per fare riferimento al tempo usate sempre ``CLOCK_MONOTONIC``. Oggigiorno 153 questo è quello che viene usato di base da alsa, drm, e v4l. Tuttavia, 154 lasciate allo spazio utente la possibilità di capire quali *timestamp* 155 derivano da domini temporali diversi come il vostro orologio di sistema 156 (fornito dal kernel) oppure un contatore hardware indipendente da qualche 157 parte. Gli orologi divergeranno, ma con questa informazione gli strumenti di 158 analisi delle prestazioni possono compensare il problema. Se il vostro spazio 159 utente può ottenere i valori grezzi degli orologi, allora considerate di 160 esporre anch'essi. 161 162 * Per descrivere il tempo, usate ``__s64`` per i secondi e ``__u64`` per i 163 nanosecondi. Non è il modo migliore per specificare il tempo, ma è 164 praticamente uno standard. 165 166 * Verificate che gli input di valori temporali siano normalizzati, e se non lo 167 sono scartateli. Fate attenzione perché la struttura dati ``struct ktime`` 168 del kernel usa interi con segni sia per i secondi che per i nanosecondi. 169 170 * Per le scadenze (*timeout*) usate valori temporali assoluti. Se siete dei 171 bravi ragazzi e avete reso la vostra ioctl rieseguibile, allora i tempi 172 relativi tendono ad essere troppo grossolani e a causa degli arrotondamenti 173 potrebbero estendere in modo indefinito i tempi di attesa ad ogni 174 riesecuzione. Particolarmente vero se il vostro orologio di riferimento è 175 qualcosa di molto lento come il contatore di *frame*. Con la giacca da 176 avvocato delle specifiche diremmo che questo non è un baco perché tutte le 177 scadenze potrebbero essere estese - ma sicuramente gli utenti vi odieranno 178 quando le animazioni singhiozzano. 179 180 * Considerate l'idea di eliminare tutte le ioctl sincrone con scadenze, e di 181 sostituirle con una versione asincrona il cui stato può essere consultato 182 attraverso il descrittore di file mediante ``poll``. Questo approccio si 183 sposa meglio in un applicazione guidata dagli eventi. 184 185 * Sviluppate dei test per i casi estremi, specialmente verificate che i valori 186 di ritorno per gli eventi già completati, le attese terminate con successo, e 187 le attese scadute abbiano senso e servano ai vostri scopi. 188 189 190Non perdere risorse 191------------------- 192Nel suo piccolo il driver drm implementa un sistema operativo specializzato per 193certe GPU. Questo significa che il driver deve esporre verso lo spazio 194utente tonnellate di agganci per accedere ad oggetti e altre risorse. Farlo 195correttamente porterà con se alcune insidie: 196 197 * Collegate sempre la vita di una risorsa creata dinamicamente, a quella del 198 descrittore di file. Considerate una mappatura 1:1 se la vostra risorsa 199 dev'essere condivisa fra processi - passarsi descrittori di file sul socket 200 unix semplifica la gestione anche per lo spazio utente. 201 202 * Dev'esserci sempre Il supporto ``O_CLOEXEC``. 203 204 * Assicuratevi di avere abbastanza isolamento fra utenti diversi. Di base 205 impostate uno spazio dei nomi riservato per ogni descrittore di file, il che 206 forzerà ogni condivisione ad essere esplicita. Usate uno spazio più globale 207 per dispositivo solo se gli oggetti sono effettivamente unici per quel 208 dispositivo. Un controesempio viene dall'interfaccia drm modeset, dove 209 oggetti specifici di dispositivo, come i connettori, condividono uno spazio 210 dei nomi con oggetti per il *framebuffer*, ma questi non sono per niente 211 condivisi. Uno spazio separato, privato di base, per i *framebuffer* sarebbe 212 stato meglio. 213 214 * Pensate all'identificazione univoca degli agganci verso lo spazio utente. Per 215 esempio, per la maggior parte dei driver drm, si considera fallace la doppia 216 sottomissione di un oggetto allo stesso comando ioctl. Ma per evitarlo, se 217 gli oggetti sono condivisibili, lo spazio utente ha bisogno di sapere se il 218 driver ha importato un oggetto da un altro processo. Non l'ho ancora provato, 219 ma considerate l'idea di usare il numero di inode come identificatore per i 220 descrittori di file condivisi - che poi è come si distinguono i veri file. 221 Sfortunatamente, questo richiederebbe lo sviluppo di un vero e proprio 222 filesystem virtuale nel kernel. 223 224 225Ultimo, ma non meno importante 226------------------------------ 227 228Non tutti i problemi si risolvono con una nuova ioctl: 229 230* Pensateci su due o tre volte prima di implementare un'interfaccia privata per 231 un driver. Ovviamente è molto più veloce seguire questa via piuttosto che 232 buttarsi in lunghe discussioni alla ricerca di una soluzione più generica. Ed 233 a volte un'interfaccia privata è quello che serve per sviluppare un nuovo 234 concetto. Ma alla fine, una volta che c'è un'interfaccia generica a 235 disposizione finirete per mantenere due interfacce. Per sempre. 236 237* Considerate interfacce alternative alle ioctl. Gli attributi sysfs sono molto 238 meglio per impostazioni che sono specifiche di un dispositivo, o per 239 sotto-oggetti con una vita piuttosto statica (come le uscite dei connettori in 240 drm con tutti gli attributi per la sovrascrittura delle rilevazioni). O magari 241 solo il vostro sistema di test ha bisogno di una certa interfaccia, e allora 242 debugfs (che non ha un'interfaccia stabile) sarà la soluzione migliore. 243 244Per concludere. Questo gioco consiste nel fare le cose giuste fin da subito, 245dato che se il vostro driver diventa popolare e la piattaforma hardware longeva 246finirete per mantenere le vostre ioctl per sempre. Potrete tentare di deprecare 247alcune orribili ioctl, ma ci vorranno anni per riuscirci effettivamente. E 248ancora, altri anni prima che sparisca l'ultimo utente capace di lamentarsi per 249una regressione. 250