Commit | Line | Data |
---|---|---|
37912da4 FV |
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 | ========================================= | |
7 | Includere gli i file di intestazione uAPI | |
8 | ========================================= | |
9 | ||
10 | Qualche volta è utile includere dei file di intestazione e degli esempi di codice C | |
11 | al fine di descrivere l'API per lo spazio utente e per generare dei riferimenti | |
12 | fra il codice e la documentazione. Aggiungere i riferimenti ai file dell'API | |
13 | dello spazio utente ha ulteriori vantaggi: Sphinx genererà dei messaggi | |
14 | d'avviso se un simbolo non viene trovato nella documentazione. Questo permette | |
15 | di mantenere allineate la documentazione della uAPI (API spazio utente) | |
16 | con le modifiche del kernel. | |
17 | Il programma :ref:`parse_headers.pl <it_parse_headers>` genera questi riferimenti. | |
18 | Esso dev'essere invocato attraverso un Makefile, mentre si genera la | |
19 | documentazione. Per avere un esempio su come utilizzarlo all'interno del kernel | |
54f38fca | 20 | consultate ``Documentation/userspace-api/media/Makefile``. |
37912da4 FV |
21 | |
22 | .. _it_parse_headers: | |
23 | ||
24 | parse_headers.pl | |
25 | ^^^^^^^^^^^^^^^^ | |
26 | ||
27 | NOME | |
28 | **** | |
29 | ||
30 | ||
31 | parse_headers.pl - analizza i file C al fine di identificare funzioni, | |
32 | strutture, enumerati e definizioni, e creare riferimenti per Sphinx | |
33 | ||
34 | SINTASSI | |
35 | ******** | |
36 | ||
37 | ||
38 | \ **parse_headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>] | |
39 | ||
40 | Dove <options> può essere: --debug, --usage o --help. | |
41 | ||
42 | ||
43 | OPZIONI | |
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 | ||
63 | DESCRIZIONE | |
64 | *********** | |
65 | ||
66 | Converte un file d'intestazione o un file sorgente C (C_FILE) in un testo | |
67 | ReStructuredText incluso mediante il blocco ..parsed-literal | |
68 | con riferimenti alla documentazione che descrive l'API. Opzionalmente, | |
69 | il programma accetta anche un altro file (EXCEPTIONS_FILE) che | |
70 | descrive quali elementi debbano essere ignorati o il cui riferimento | |
71 | deve puntare ad elemento diverso dal predefinito. | |
72 | ||
73 | Il file generato sarà disponibile in (OUT_FILE). | |
74 | ||
75 | Il programma è capace di identificare *define*, funzioni, strutture, | |
76 | tipi di dato, enumerati e valori di enumerati, e di creare i riferimenti | |
77 | per ognuno di loro. Inoltre, esso è capace di distinguere le #define | |
78 | utilizzate per specificare i comandi ioctl di Linux. | |
79 | ||
80 | Il file EXCEPTIONS_FILE contiene due tipi di dichiarazioni: | |
81 | \ **ignore**\ o \ **replace**\ . | |
82 | ||
83 | La sintassi per ignore è: | |
84 | ||
85 | ignore \ **tipo**\ \ **nome**\ | |
86 | ||
87 | La dichiarazione \ **ignore**\ significa che non verrà generato alcun | |
88 | riferimento per il simbolo \ **name**\ di tipo \ **tipo**\ . | |
89 | ||
90 | ||
91 | La sintassi per replace è: | |
92 | ||
93 | replace \ **tipo**\ \ **nome**\ \ **nuovo_valore**\ | |
94 | ||
95 | La dichiarazione \ **replace**\ significa che verrà generato un | |
96 | riferimento per il simbolo \ **name**\ di tipo \ **tipo**\ , ma, invece | |
97 | di utilizzare il valore predefinito, verrà utilizzato il valore | |
98 | \ **nuovo_valore**\ . | |
99 | ||
100 | Per 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 | ||
152 | ESEMPI | |
153 | ****** | |
154 | ||
155 | ||
156 | ignore define _VIDEODEV2_H | |
157 | ||
158 | ||
159 | Ignora una definizione #define _VIDEODEV2_H nel file C_FILE. | |
160 | ||
161 | ignore symbol PRIVATE | |
162 | ||
163 | ||
164 | In un enumerato come il seguente: | |
165 | ||
166 | enum foo { BAR1, BAR2, PRIVATE }; | |
167 | ||
168 | Non genererà alcun riferimento per \ **PRIVATE**\ . | |
169 | ||
170 | replace symbol BAR1 :c:type:\`foo\` | |
171 | replace symbol BAR2 :c:type:\`foo\` | |
172 | ||
173 | ||
174 | In un enumerato come il seguente: | |
175 | ||
176 | enum foo { BAR1, BAR2, PRIVATE }; | |
177 | ||
178 | Genererà un riferimento ai valori BAR1 e BAR2 dal simbolo foo nel dominio C. | |
179 | ||
180 | ||
181 | BUGS | |
182 | **** | |
183 | ||
184 | Riferire ogni malfunzionamento a Mauro Carvalho Chehab <mchehab@s-opensource.com> | |
185 | ||
186 | ||
187 | COPYRIGHT | |
188 | ********* | |
189 | ||
190 | ||
191 | Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>. | |
192 | ||
193 | Licenza GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>. | |
194 | ||
195 | Questo è software libero: siete liberi di cambiarlo e ridistribuirlo. | |
196 | Non c'è alcuna garanzia, nei limiti permessi dalla legge. |