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