.. 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.