1*4882a593Smuzhiyun.. include:: ../disclaimer-ita.rst 2*4882a593Smuzhiyun 3*4882a593Smuzhiyun.. note:: Per leggere la documentazione originale in inglese: 4*4882a593Smuzhiyun :ref:`Documentation/doc-guide/index.rst <doc_guide>` 5*4882a593Smuzhiyun 6*4882a593Smuzhiyun========================================= 7*4882a593SmuzhiyunIncludere gli i file di intestazione uAPI 8*4882a593Smuzhiyun========================================= 9*4882a593Smuzhiyun 10*4882a593SmuzhiyunQualche volta è utile includere dei file di intestazione e degli esempi di codice C 11*4882a593Smuzhiyunal fine di descrivere l'API per lo spazio utente e per generare dei riferimenti 12*4882a593Smuzhiyunfra il codice e la documentazione. Aggiungere i riferimenti ai file dell'API 13*4882a593Smuzhiyundello spazio utente ha ulteriori vantaggi: Sphinx genererà dei messaggi 14*4882a593Smuzhiyund'avviso se un simbolo non viene trovato nella documentazione. Questo permette 15*4882a593Smuzhiyundi mantenere allineate la documentazione della uAPI (API spazio utente) 16*4882a593Smuzhiyuncon le modifiche del kernel. 17*4882a593SmuzhiyunIl programma :ref:`parse_headers.pl <it_parse_headers>` genera questi riferimenti. 18*4882a593SmuzhiyunEsso dev'essere invocato attraverso un Makefile, mentre si genera la 19*4882a593Smuzhiyundocumentazione. Per avere un esempio su come utilizzarlo all'interno del kernel 20*4882a593Smuzhiyunconsultate ``Documentation/userspace-api/media/Makefile``. 21*4882a593Smuzhiyun 22*4882a593Smuzhiyun.. _it_parse_headers: 23*4882a593Smuzhiyun 24*4882a593Smuzhiyunparse_headers.pl 25*4882a593Smuzhiyun^^^^^^^^^^^^^^^^ 26*4882a593Smuzhiyun 27*4882a593SmuzhiyunNOME 28*4882a593Smuzhiyun**** 29*4882a593Smuzhiyun 30*4882a593Smuzhiyun 31*4882a593Smuzhiyunparse_headers.pl - analizza i file C al fine di identificare funzioni, 32*4882a593Smuzhiyunstrutture, enumerati e definizioni, e creare riferimenti per Sphinx 33*4882a593Smuzhiyun 34*4882a593SmuzhiyunSINTASSI 35*4882a593Smuzhiyun******** 36*4882a593Smuzhiyun 37*4882a593Smuzhiyun 38*4882a593Smuzhiyun\ **parse_headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>] 39*4882a593Smuzhiyun 40*4882a593SmuzhiyunDove <options> può essere: --debug, --usage o --help. 41*4882a593Smuzhiyun 42*4882a593Smuzhiyun 43*4882a593SmuzhiyunOPZIONI 44*4882a593Smuzhiyun******* 45*4882a593Smuzhiyun 46*4882a593Smuzhiyun 47*4882a593Smuzhiyun 48*4882a593Smuzhiyun\ **--debug**\ 49*4882a593Smuzhiyun 50*4882a593Smuzhiyun Lo script viene messo in modalità verbosa, utile per il debugging. 51*4882a593Smuzhiyun 52*4882a593Smuzhiyun 53*4882a593Smuzhiyun\ **--usage**\ 54*4882a593Smuzhiyun 55*4882a593Smuzhiyun Mostra un messaggio d'aiuto breve e termina. 56*4882a593Smuzhiyun 57*4882a593Smuzhiyun 58*4882a593Smuzhiyun\ **--help**\ 59*4882a593Smuzhiyun 60*4882a593Smuzhiyun Mostra un messaggio d'aiuto dettagliato e termina. 61*4882a593Smuzhiyun 62*4882a593Smuzhiyun 63*4882a593SmuzhiyunDESCRIZIONE 64*4882a593Smuzhiyun*********** 65*4882a593Smuzhiyun 66*4882a593SmuzhiyunConverte un file d'intestazione o un file sorgente C (C_FILE) in un testo 67*4882a593SmuzhiyunReStructuredText incluso mediante il blocco ..parsed-literal 68*4882a593Smuzhiyuncon riferimenti alla documentazione che descrive l'API. Opzionalmente, 69*4882a593Smuzhiyunil programma accetta anche un altro file (EXCEPTIONS_FILE) che 70*4882a593Smuzhiyundescrive quali elementi debbano essere ignorati o il cui riferimento 71*4882a593Smuzhiyundeve puntare ad elemento diverso dal predefinito. 72*4882a593Smuzhiyun 73*4882a593SmuzhiyunIl file generato sarà disponibile in (OUT_FILE). 74*4882a593Smuzhiyun 75*4882a593SmuzhiyunIl programma è capace di identificare *define*, funzioni, strutture, 76*4882a593Smuzhiyuntipi di dato, enumerati e valori di enumerati, e di creare i riferimenti 77*4882a593Smuzhiyunper ognuno di loro. Inoltre, esso è capace di distinguere le #define 78*4882a593Smuzhiyunutilizzate per specificare i comandi ioctl di Linux. 79*4882a593Smuzhiyun 80*4882a593SmuzhiyunIl file EXCEPTIONS_FILE contiene due tipi di dichiarazioni: 81*4882a593Smuzhiyun\ **ignore**\ o \ **replace**\ . 82*4882a593Smuzhiyun 83*4882a593SmuzhiyunLa sintassi per ignore è: 84*4882a593Smuzhiyun 85*4882a593Smuzhiyunignore \ **tipo**\ \ **nome**\ 86*4882a593Smuzhiyun 87*4882a593SmuzhiyunLa dichiarazione \ **ignore**\ significa che non verrà generato alcun 88*4882a593Smuzhiyunriferimento per il simbolo \ **name**\ di tipo \ **tipo**\ . 89*4882a593Smuzhiyun 90*4882a593Smuzhiyun 91*4882a593SmuzhiyunLa sintassi per replace è: 92*4882a593Smuzhiyun 93*4882a593Smuzhiyunreplace \ **tipo**\ \ **nome**\ \ **nuovo_valore**\ 94*4882a593Smuzhiyun 95*4882a593SmuzhiyunLa dichiarazione \ **replace**\ significa che verrà generato un 96*4882a593Smuzhiyunriferimento per il simbolo \ **name**\ di tipo \ **tipo**\ , ma, invece 97*4882a593Smuzhiyundi utilizzare il valore predefinito, verrà utilizzato il valore 98*4882a593Smuzhiyun\ **nuovo_valore**\ . 99*4882a593Smuzhiyun 100*4882a593SmuzhiyunPer entrambe le dichiarazioni, il \ **tipo**\ può essere uno dei seguenti: 101*4882a593Smuzhiyun 102*4882a593Smuzhiyun 103*4882a593Smuzhiyun\ **ioctl**\ 104*4882a593Smuzhiyun 105*4882a593Smuzhiyun La dichiarazione ignore o replace verrà applicata su definizioni di ioctl 106*4882a593Smuzhiyun come la seguente: 107*4882a593Smuzhiyun 108*4882a593Smuzhiyun #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register) 109*4882a593Smuzhiyun 110*4882a593Smuzhiyun 111*4882a593Smuzhiyun 112*4882a593Smuzhiyun\ **define**\ 113*4882a593Smuzhiyun 114*4882a593Smuzhiyun La dichiarazione ignore o replace verrà applicata su una qualsiasi #define 115*4882a593Smuzhiyun trovata in C_FILE. 116*4882a593Smuzhiyun 117*4882a593Smuzhiyun 118*4882a593Smuzhiyun 119*4882a593Smuzhiyun\ **typedef**\ 120*4882a593Smuzhiyun 121*4882a593Smuzhiyun La dichiarazione ignore o replace verrà applicata ad una dichiarazione typedef 122*4882a593Smuzhiyun in C_FILE. 123*4882a593Smuzhiyun 124*4882a593Smuzhiyun 125*4882a593Smuzhiyun 126*4882a593Smuzhiyun\ **struct**\ 127*4882a593Smuzhiyun 128*4882a593Smuzhiyun La dichiarazione ignore o replace verrà applicata ai nomi di strutture 129*4882a593Smuzhiyun in C_FILE. 130*4882a593Smuzhiyun 131*4882a593Smuzhiyun 132*4882a593Smuzhiyun 133*4882a593Smuzhiyun\ **enum**\ 134*4882a593Smuzhiyun 135*4882a593Smuzhiyun La dichiarazione ignore o replace verrà applicata ai nomi di enumerati 136*4882a593Smuzhiyun in C_FILE. 137*4882a593Smuzhiyun 138*4882a593Smuzhiyun 139*4882a593Smuzhiyun 140*4882a593Smuzhiyun\ **symbol**\ 141*4882a593Smuzhiyun 142*4882a593Smuzhiyun La dichiarazione ignore o replace verrà applicata ai nomi di valori di 143*4882a593Smuzhiyun enumerati in C_FILE. 144*4882a593Smuzhiyun 145*4882a593Smuzhiyun Per le dichiarazioni di tipo replace, il campo \ **new_value**\ utilizzerà 146*4882a593Smuzhiyun automaticamente i riferimenti :c:type: per \ **typedef**\ , \ **enum**\ e 147*4882a593Smuzhiyun \ **struct**\. Invece, utilizzerà :ref: per \ **ioctl**\ , \ **define**\ e 148*4882a593Smuzhiyun \ **symbol**\. Il tipo di riferimento può essere definito esplicitamente 149*4882a593Smuzhiyun nella dichiarazione stessa. 150*4882a593Smuzhiyun 151*4882a593Smuzhiyun 152*4882a593SmuzhiyunESEMPI 153*4882a593Smuzhiyun****** 154*4882a593Smuzhiyun 155*4882a593Smuzhiyun 156*4882a593Smuzhiyunignore define _VIDEODEV2_H 157*4882a593Smuzhiyun 158*4882a593Smuzhiyun 159*4882a593SmuzhiyunIgnora una definizione #define _VIDEODEV2_H nel file C_FILE. 160*4882a593Smuzhiyun 161*4882a593Smuzhiyunignore symbol PRIVATE 162*4882a593Smuzhiyun 163*4882a593Smuzhiyun 164*4882a593SmuzhiyunIn un enumerato come il seguente: 165*4882a593Smuzhiyun 166*4882a593Smuzhiyunenum foo { BAR1, BAR2, PRIVATE }; 167*4882a593Smuzhiyun 168*4882a593SmuzhiyunNon genererà alcun riferimento per \ **PRIVATE**\ . 169*4882a593Smuzhiyun 170*4882a593Smuzhiyunreplace symbol BAR1 :c:type:\`foo\` 171*4882a593Smuzhiyunreplace symbol BAR2 :c:type:\`foo\` 172*4882a593Smuzhiyun 173*4882a593Smuzhiyun 174*4882a593SmuzhiyunIn un enumerato come il seguente: 175*4882a593Smuzhiyun 176*4882a593Smuzhiyunenum foo { BAR1, BAR2, PRIVATE }; 177*4882a593Smuzhiyun 178*4882a593SmuzhiyunGenererà un riferimento ai valori BAR1 e BAR2 dal simbolo foo nel dominio C. 179*4882a593Smuzhiyun 180*4882a593Smuzhiyun 181*4882a593SmuzhiyunBUGS 182*4882a593Smuzhiyun**** 183*4882a593Smuzhiyun 184*4882a593SmuzhiyunRiferire ogni malfunzionamento a Mauro Carvalho Chehab <mchehab@s-opensource.com> 185*4882a593Smuzhiyun 186*4882a593Smuzhiyun 187*4882a593SmuzhiyunCOPYRIGHT 188*4882a593Smuzhiyun********* 189*4882a593Smuzhiyun 190*4882a593Smuzhiyun 191*4882a593SmuzhiyunCopyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>. 192*4882a593Smuzhiyun 193*4882a593SmuzhiyunLicenza GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>. 194*4882a593Smuzhiyun 195*4882a593SmuzhiyunQuesto è software libero: siete liberi di cambiarlo e ridistribuirlo. 196*4882a593SmuzhiyunNon c'è alcuna garanzia, nei limiti permessi dalla legge. 197