From nobody Tue Sep 16 14:14:54 2025 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 05469C46467 for ; Mon, 2 Jan 2023 18:37:59 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234233AbjABShi (ORCPT ); Mon, 2 Jan 2023 13:37:38 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:57290 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S230127AbjABShg (ORCPT ); Mon, 2 Jan 2023 13:37:36 -0500 Received: from mx.kolabnow.com (mx.kolabnow.com [212.103.80.153]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id EB83FBC00; Mon, 2 Jan 2023 10:37:34 -0800 (PST) Received: from localhost (unknown [127.0.0.1]) by mx.kolabnow.com (Postfix) with ESMTP id B9B041477; Mon, 2 Jan 2023 19:37:33 +0100 (CET) Authentication-Results: ext-mx-out001.mykolab.com (amavisd-new); dkim=pass (4096-bit key) reason="pass (just generated, assumed good)" header.d=kolabnow.com DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=kolabnow.com; h= content-transfer-encoding:content-type:content-type:mime-version :message-id:date:date:subject:subject:from:from:received :received:received; s=dkim20160331; t=1672684650; x=1674499051; bh=4YjTrq0DmiDxfBbNzorUJPbMFARwoTxezIspcPfWriY=; b=oG64+UmRrKBX 7g2GbmzhQWJE3n2o/5mdJYtsSBH8VP5cGNh5NESpoYAPN2OEvt+x+xjQswqbxbss Om8ppc/xxvfF2xC/AceqW9uZ0dG7515lQoZvYGRY8PgzUs8BqIPNTTBw5yUMAzdQ 7fwGxwxTIWzh4pEp+FaExCFv3XZAssjjwsAMunD3ldIdkz9VCYerKYbsq2//PxuO Dgx1xmBd/rNDH1MkmBJyxvq5e9eU3bsvpo/IbEcKPJzt4NaWtLOAcbPLnVutoqMi 2pG2lVbDwTpaotSfG3BFpUqwPjqOUv+ZJV5j7DBWvxa27Vf2FXoBILYY5J1P2Ahd zIW4JCaY8Uw9pTxceS0yQjIb5ossSgt6draMT7ZZAAddd0mZtQcbzQXQWwhCpLc6 OEJXovmUWA1h/YSvvTCsAAh5qwbWRbyKE5U408PY4hNq3H1LKPVQXen55SFh5pbc S0cx7tPW6U8fJ3rIbrrpdInY4c993wMpuTMeG7Z936nSA0Xf3xfRrHPZoULf0pcj nJ+uHgHJ4whoXeNzdvIRjlbM/h/h4/oEoSHADBN7+E2h1geRrBK/GIVhWNFTKWTK kqj7HYFrGEEasQovL0Sn8gNlTqOJQEfTNVJZOxwFFXxvFYQgInc8ltANZwa6b/Yv ZqvnDHmb/6Hj3UsWIz2bnJCBlWwP/90= X-Virus-Scanned: amavisd-new at mykolab.com Received: from mx.kolabnow.com ([127.0.0.1]) by localhost (ext-mx-out001.mykolab.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id cGALrTCVUsGX; Mon, 2 Jan 2023 19:37:30 +0100 (CET) Received: from int-mx003.mykolab.com (unknown [10.9.13.3]) by mx.kolabnow.com (Postfix) with ESMTPS id 2D833E8A; Mon, 2 Jan 2023 19:37:28 +0100 (CET) Received: from ext-subm002.mykolab.com (unknown [10.9.6.2]) by int-mx003.mykolab.com (Postfix) with ESMTPS id 5B1BD3123; Mon, 2 Jan 2023 19:37:28 +0100 (CET) From: Federico Vaga To: Jonathan Corbet Cc: Federico Vaga , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH V2] doc:it_IT: add translation for botching-up-ioctl.rst Date: Mon, 2 Jan 2023 19:37:16 +0100 Message-Id: <20230102183716.9698-1-federico.vaga@vaga.pv.it> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org This patch adds the translation for the botching up ioctl document. Signed-off-by: Federico Vaga --- V1 -> V2 use the kernel-doc mecanism to link functions in documents .../it_IT/process/botching-up-ioctls.rst | 249 ++++++++++++++++++ .../translations/it_IT/process/index.rst | 1 + 2 files changed, 250 insertions(+) create mode 100644 Documentation/translations/it_IT/process/botching-up-io= ctls.rst diff --git a/Documentation/translations/it_IT/process/botching-up-ioctls.rs= t b/Documentation/translations/it_IT/process/botching-up-ioctls.rst new file mode 100644 index 000000000000..91732cdf808a --- /dev/null +++ b/Documentation/translations/it_IT/process/botching-up-ioctls.rst @@ -0,0 +1,249 @@ +.. include:: ../disclaimer-ita.rst + +:Original: Documentation/process/botching-up-ioctls.rst + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +(Come evitare di) Raffazzonare delle ioctl +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Preso da: https://blog.ffwll.ch/2013/11/botching-up-ioctls.html + +Scritto da : Daniel Vetter, Copyright =C2=A9 2013 Intel Corporation + +Una cosa che gli sviluppatori del sottosistema grafico del kernel Linux ha= nno +imparato negli ultimi anni =C3=A8 l'inutilit=C3=A0 di cercare di creare un= 'interfaccia +unificata per gestire la memoria e le unit=C3=A0 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 =C3=A8 va bene dato che non c'=C3= =A8 pi=C3=B9 un insano +sistema che finge di essere generico, ma al suo posto ci sono interfacce +dedicate. Ma al tempo stesso =C3=A8 pi=C3=B9 facile incasinare le cose. + +Per evitare di ripetere gli stessi errori ho preso nota delle lezioni impa= rate +mentre raffazzonavo il driver drm/i915. La maggior parte di queste lezioni= si +focalizzano sui tecnicismi e non sulla visione d'insieme, come le discussi= oni +riguardo al modo migliore per implementare una ioctl per inviare compiti a= lla +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 fallir= e in +partenza e ritrovarvi ad aggiungere un livello di compatibilit=C3=A0 a 32-= bit. + +* Usate solamente interi a lunghezza fissa. Per evitare i conflitti coi ti= pi + definiti nello spazio utente, il kernel definisce alcuni tipi speciali, = come: + ``__u32``, ``__s64``. Usateli. + +* Allineate tutto alla lunghezza naturale delle piattaforma in uso e riemp= ite + esplicitamente i vuoti. Non necessariamente le piattaforme a 32-bit alli= neano + i valori a 64-bit rispettandone l'allineamento, ma le piattaforme a 64-b= it 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= =C3=A0 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 i= l pi=C3=B9 + possibile per non ritardare la conversione, o peggio maneggiare ``__u64`= ` nel + vostro codice perch=C3=A9 questo riduce le verifiche che strumenti come = sparse + possono effettuare. La macro u64_to_user_ptr() pu=C3=B2 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=C3=A0, possiamo ora= dare uno +sguardo alle basi. Trascurare questi punti render=C3=A0 difficile la gesti= one della +compatibilit=C3=A0 all'indietro ed in avanti. E dato che sbagliare al prim= o colpo =C3=A8 +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 correttam= ente + un nuovo *flag*, modalit=C3=A0, o ioctl, (probabilmente perch=C3=A9 avev= ate raffazzonato + qualcosa nel passato) allora dovrete implementare nel driver un meccanis= mo per + notificare quali funzionalit=C3=A0 sono supportate, o in alternativa un = numero di + versione. + +* Abbiate un piano per estendere le ioctl con nuovi *flag* o campi alla fi= ne 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 =C3=A8 una soluzione completa dato che uno spazio u= tente nuovo + su un kernel vecchio non noterebbe che i campi nuovi alla fine della str= uttura + vengono ignorati. Dunque, anche questo avr=C3=A0 bisogno di essere notif= icato 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=C3=A0 a rotoli dato che qualcuno user=C3=A0 dell= e 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=C3=A0= sar=C3=A0 + quella di contenere spazzatura. Per questo dovrete esplicitamente riempi= re 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=C3=B9 scuse rimaste per permettere ai driver drm= di essere +sfruttati per diventare root. Questo significa che dobbiamo avere una comp= leta +validazione degli input e gestire in modo robusto i percorsi - tanto le GPU +moriranno comunque nel pi=C3=B9 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 =C3=A8 l'inserimento direttamente nell'hardware di val= ori di + posizionamento di un'immagine *sprite* quando l'hardware supporta giust= o 12 + bit, o qualcosa del genere. Tutto funzioner=C3=A0 finch=C3=A9 qualche s= trano *display + server* non decide di preoccuparsi lui stesso del *clamping* e il curso= re + far=C3=A0 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=C3=A0 di verificare il 90% dei p= ercorsi + 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 (mediant= e un + processo X insopprimibile). Se anche recuperare lo stato =C3=A8 troppo = complicato, + allora implementate una scadenza oppure come ultima spiaggia una rete di + sicurezza per rilevare situazioni di stallo quando l'hardware da di mat= to. + + * Preparate dei test riguardo ai casi particolarmente estremi nel codice = di + recupero del sistema - =C3=A8 troppo facile create uno stallo fra il vo= stro 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 =C3=A8 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 lezi= oni da +apprendere. + + * Per fare riferimento al tempo usate sempre ``CLOCK_MONOTONIC``. Oggigio= rno + questo =C3=A8 quello che viene usato di base da alsa, drm, e v4l. Tutta= via, + lasciate allo spazio utente la possibilit=C3=A0 di capire quali *timest= amp* + derivano da domini temporali diversi come il vostro orologio di sistema + (fornito dal kernel) oppure un contatore hardware indipendente da qualc= he + parte. Gli orologi divergeranno, ma con questa informazione gli strumen= ti di + analisi delle prestazioni possono compensare il problema. Se il vostro = spazio + utente pu=C3=B2 ottenere i valori grezzi degli orologi, allora consider= ate di + esporre anch'essi. + + * Per descrivere il tempo, usate ``__s64`` per i secondi e ``__u64`` per i + nanosecondi. Non =C3=A8 il modo migliore per specificare il tempo, ma = =C3=A8 + praticamente uno standard. + + * Verificate che gli input di valori temporali siano normalizzati, e se n= on lo + sono scartateli. Fate attenzione perch=C3=A9 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 d= ei + bravi ragazzi e avete reso la vostra ioctl rieseguibile, allora i tempi + relativi tendono ad essere troppo grossolani e a causa degli arrotondam= enti + potrebbero estendere in modo indefinito i tempi di attesa ad ogni + riesecuzione. Particolarmente vero se il vostro orologio di riferimento= =C3=A8 + qualcosa di molto lento come il contatore di *frame*. Con la giacca da + avvocato delle specifiche diremmo che questo non =C3=A8 un baco perch= =C3=A9 tutte le + scadenze potrebbero essere estese - ma sicuramente gli utenti vi odiera= nno + 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=C3=B2 essere con= sultato + 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 v= alori + di ritorno per gli eventi gi=C3=A0 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 specializzat= o 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=C3=A0 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 so= cket + 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, i= l che + forzer=C3=A0 ogni condivisione ad essere esplicita. Usate uno spazio pi= =C3=B9 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 sp= azio + dei nomi con oggetti per il *framebuffer*, ma questi non sono per niente + condivisi. Uno spazio separato, privato di base, per i *framebuffer* sa= rebbe + stato meglio. + + * Pensate all'identificazione univoca degli agganci verso lo spazio utent= e. Per + esempio, per la maggior parte dei driver drm, si considera fallace la d= oppia + sottomissione di un oggetto allo stesso comando ioctl. Ma per evitarlo,= se + gli oggetti sono condivisibili, lo spazio utente ha bisogno di sapere s= e il + driver ha importato un oggetto da un altro processo. Non l'ho ancora pr= ovato, + ma considerate l'idea di usare il numero di inode come identificatore p= er i + descrittori di file condivisi - che poi =C3=A8 come si distinguono i ve= ri 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 privat= a per + un driver. Ovviamente =C3=A8 molto pi=C3=B9 veloce seguire questa via pi= uttosto che + buttarsi in lunghe discussioni alla ricerca di una soluzione pi=C3=B9 ge= nerica. Ed + a volte un'interfaccia privata =C3=A8 quello che serve per sviluppare un= nuovo + concetto. Ma alla fine, una volta che c'=C3=A8 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 connett= ori 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 al= lora + debugfs (che non ha un'interfaccia stabile) sar=C3=A0 la soluzione migli= ore. + +Per concludere. Questo gioco consiste nel fare le cose giuste fin da subit= o, +dato che se il vostro driver diventa popolare e la piattaforma hardware lo= ngeva +finirete per mantenere le vostre ioctl per sempre. Potrete tentare di depr= ecare +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. diff --git a/Documentation/translations/it_IT/process/index.rst b/Documenta= tion/translations/it_IT/process/index.rst index 8d4e36a07ff4..25602c1a97d1 100644 --- a/Documentation/translations/it_IT/process/index.rst +++ b/Documentation/translations/it_IT/process/index.rst @@ -58,6 +58,7 @@ perch=C3=A9 non si =C3=A8 trovato un posto migliore. adding-syscalls magic-number volatile-considered-harmful + botching-up-ioctls clang-format ../riscv/patch-acceptance =20 --=20 2.30.2