1.. include:: ../disclaimer-ita.rst 2 3===================================== 4Includere i file di intestazione uAPI 5===================================== 6 7Qualche volta è utile includere dei file di intestazione e degli esempi di codice C 8al fine di descrivere l'API per lo spazio utente e per generare dei riferimenti 9fra il codice e la documentazione. Aggiungere i riferimenti ai file dell'API 10dello spazio utente ha un ulteriore vantaggio: Sphinx genererà dei messaggi 11d'avviso se un simbolo non viene trovato nella documentazione. Questo permette 12di mantenere allineate la documentazione della uAPI (API spazio utente) 13con le modifiche del kernel. 14Il programma :ref:`parse_headers.py <it_parse_headers>` genera questi 15riferimenti. Esso dev'essere invocato attraverso un Makefile, mentre si genera 16la documentazione. Per avere un esempio su come utilizzarlo all'interno del 17kernel consultate ``Documentation/userspace-api/media/Makefile``. 18 19.. _it_parse_headers: 20 21tools/docs/parse_headers.py 22^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23 24NOME 25**** 26 27parse_headers.py - analizza un file C al fine di identificare funzioni, 28strutture, enumerati e definizioni, e creare riferimenti per un libro Sphinx. 29 30USO 31*** 32 33parse-headers.py [-h] [-d] [-t] ``FILE_IN`` ``FILE_OUT`` ``FILE_RULES`` 34 35SINOSSI 36******* 37 38Converte un file d'intestazione o un file sorgente C ``FILE_IN`` in un testo 39ReStructured Text incluso mediante il blocco ..parsed-literal con riferimenti 40alla documentazione che descrive l'API. Accetta opzionalmente un file 41``FILE_RULES`` che descrive quali elementi debbano essere ignorati o il cui 42riferimento debba puntare ad un tipo/nome diverso da quello predefinito. 43 44Il file generato viene scritto in ``FILE_OUT``. 45 46Il programma è capace di identificare ``define``, ``struct``, ``typedef``, 47``enum`` e ``symbol`` di un enumerato, creando i riferimenti per ognuno di 48loro. 49 50Inoltre, esso è capace di distinguere le ``#define`` utilizzate per 51specificare le macro specifiche di Linux usate per definire gli ``ioctl``. 52 53Il file ``FILE_RULES``, opzionale, contiene un insieme di regole come le 54seguenti:: 55 56 ignore ioctl VIDIOC_ENUM_FMT 57 replace ioctl VIDIOC_DQBUF vidioc_qbuf 58 replace define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ :c:type:`v4l2_event_motion_det` 59 60ARGOMENTI POSIZIONALI 61********************* 62 63 ``FILE_IN`` 64 File C d'ingresso 65 66 ``FILE_OUT`` 67 File RST generato 68 69 ``FILE_RULES`` 70 File delle eccezioni (opzionale) 71 72OPZIONI 73******* 74 75 ``-h``, ``--help`` 76 mostra un messaggio d'aiuto e termina 77 ``-d``, ``--debug`` 78 aumenta il livello di debug. Può essere usato più volte 79 ``-t``, ``--toc`` 80 invece di un blocco letterale, genera nel file RST una tabella 81 dell'indice (TOC) 82 83 84DESCRIZIONE 85*********** 86 87Crea, a partire da ``FILE_IN``, una versione arricchita di un file 88d'intestazione del kernel con collegamenti incrociati verso ogni tipo di 89struttura dati C, formattandola con la notazione reStructuredText, sia 90come blocco letterale che come tabella dell'indice. 91 92Accetta opzionalmente un file ``FILE_RULES`` che descrive quali elementi 93debbano essere ignorati o il cui riferimento debba puntare ad un valore 94diverso da quello predefinito, e che può opzionalmente definire lo spazio 95dei nomi C da utilizzare. 96 97Ha lo scopo di permettere una documentazione più completa, in cui i file 98d'intestazione della uAPI creino collegamenti incrociati verso il codice. 99 100Il file generato viene scritto in ``FILE_OUT``. 101 102Il file ``FILE_RULES`` può contenere tre tipi di dichiarazioni: 103**ignore**, **replace** e **namespace**. 104 105Per impostazione predefinita, vengono create regole per tutti i simboli e 106le definizioni, ma è anche possibile fornire un file di eccezioni. Questo 107file contiene un insieme di regole che seguono la sintassi descritta di 108seguito: 109 1101. Regole ignore: 111 112 ignore *tipo* *simbolo* 113 114Rimuove il simbolo dalla generazione dei riferimenti. 115 1162. Regole replace: 117 118 replace *tipo* *vecchio_simbolo* *nuovo_riferimento* 119 120 Sostituisce *vecchio_simbolo* con *nuovo_riferimento*. 121 *nuovo_riferimento* può essere: 122 123 - un semplice nome di simbolo; 124 - un riferimento Sphinx completo. 125 1263. Regole namespace 127 128 namespace *spazio_dei_nomi* 129 130 Imposta lo *spazio_dei_nomi* C da utilizzare durante la generazione dei 131 riferimenti incrociati. Può essere sovrascritto dalle regole replace. 132 133Nelle regole ignore e replace, *tipo* può essere: 134 135 - ioctl: 136 per le definizioni della forma ``_IO*``, per esempio le definizioni 137 di ioctl 138 139 - define: 140 per le altre definizioni 141 142 - symbol: 143 per i simboli definiti all'interno di enumerati; 144 145 - typedef: 146 per i typedef; 147 148 - enum: 149 per il nome di un enumerato non anonimo; 150 151 - struct: 152 per le strutture. 153 154 155ESEMPI 156****** 157 158- Ignora una definizione ``_VIDEODEV2_H`` in ``FILE_IN``:: 159 160 ignore define _VIDEODEV2_H 161 162- In una struttura dati come questo enumerato:: 163 164 enum foo { BAR1, BAR2, PRIVATE }; 165 166 Non genererà alcun riferimento incrociato per ``PRIVATE``:: 167 168 ignore symbol PRIVATE 169 170 Nello stesso enumerato, invece di creare un riferimento incrociato per 171 ogni simbolo, si può far si che tutti puntino al tipo C ``enum foo``:: 172 173 replace symbol BAR1 :c:type:\`foo\` 174 replace symbol BAR2 :c:type:\`foo\` 175 176 177- Usa lo spazio dei nomi C ``MC`` per tutti i simboli in ``FILE_IN``:: 178 179 namespace MC 180 181BUGS 182**** 183 184Segnalate qualsiasi malfunzionamento a Mauro Carvalho Chehab 185<mchehab@kernel.org> 186 187COPYRIGHT 188********* 189 190Copyright (c) 2016, 2025 di Mauro Carvalho Chehab <mchehab+huawei@kernel.org>. 191 192Licenza GPLv2: GNU GPL versione 2 <https://gnu.org/licenses/gpl.html>. 193 194Questo è software libero: siete liberi di cambiarlo e ridistribuirlo. 195Non c'è alcuna garanzia, nei limiti permessi dalla legge. 196