`sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget+/translations/zh_CN/doc-guide/parse-headersmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget+/translations/zh_TW/doc-guide/parse-headersmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget+/translations/it_IT/doc-guide/parse-headersmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget+/translations/ja_JP/doc-guide/parse-headersmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget+/translations/ko_KR/doc-guide/parse-headersmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget+/translations/pt_BR/doc-guide/parse-headersmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget+/translations/sp_SP/doc-guide/parse-headersmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhsection)}(hhh](htitle)}(hIncluding uAPI header filesh]hIncluding uAPI header files}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhE/var/lib/git/docbuild/linux/Documentation/doc-guide/parse-headers.rsthKubh paragraph)}(hXSometimes, it is useful to include header files and C example codes in order to describe the userspace API and to generate cross-references between the code and the documentation. Adding cross-references for userspace API files has an additional advantage: Sphinx will generate warnings if a symbol is not found at the documentation. That helps to keep the uAPI documentation in sync with the Kernel changes. The :ref:`parse-headers.py ` provides a way to generate such cross-references. During the documentation build, the same parser is used by the ``kernel-include`` directive with the ``:generate-cross-refs:`` option. Please see ``Documentation/userspace-api/media/cec/cec-header.rst`` for an example about how to use it inside the Kernel tree.h](hXSometimes, it is useful to include header files and C example codes in order to describe the userspace API and to generate cross-references between the code and the documentation. Adding cross-references for userspace API files has an additional advantage: Sphinx will generate warnings if a symbol is not found at the documentation. That helps to keep the uAPI documentation in sync with the Kernel changes. The }(hhhhhNhNubh)}(h':ref:`parse-headers.py `h]hinline)}(hhh]hparse-headers.py}(hhhhhNhNubah}(h]h ](xrefstdstd-refeh"]h$]h&]uh1hhhubah}(h]h ]h"]h$]h&]refdocdoc-guide/parse-headers refdomainhreftyperef refexplicitrefwarn reftarget parse_headersuh1hhhhKhhubhr provides a way to generate such cross-references. During the documentation build, the same parser is used by the }(hhhhhNhNubhliteral)}(h``kernel-include``h]hkernel-include}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubh directive with the }(hhhhhNhNubh)}(h``:generate-cross-refs:``h]h:generate-cross-refs:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubh option. Please see }(hhhhhNhNubh)}(h8``Documentation/userspace-api/media/cec/cec-header.rst``h]h4Documentation/userspace-api/media/cec/cec-header.rst}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubh; for an example about how to use it inside the Kernel tree.}(hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubhtarget)}(h.. _parse_headers:h]h}(h]h ]h"]h$]h&]refid parse-headersuh1j<hKhhhhhhubh)}(hhh](h)}(htools/docs/parse-headers.pyh]htools/docs/parse-headers.py}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjJhhhhhKubh)}(hhh](h)}(hNAMEh]hNAME}(hj^hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj[hhhhhKubh)}(hparse-headers.py - parse a C file, in order to identify functions, structs, enums and defines and create cross-references to a Sphinx book.h]hparse-headers.py - parse a C file, in order to identify functions, structs, enums and defines and create cross-references to a Sphinx book.}(hjlhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj[hhubeh}(h]nameah ]h"]nameah$]h&]uh1hhjJhhhhhKubh)}(hhh](h)}(hUSAGEh]hUSAGE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hIparse-headers.py [-h] [-d] [-t] ``FILE_IN`` ``FILE_OUT`` [``FILE_RULES``]h](h parse-headers.py [-h] [-d] [-t] }(hjhhhNhNubh)}(h ``FILE_IN``h]hFILE_IN}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh }(hjhhhNhNubh)}(h ``FILE_OUT``h]hFILE_OUT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh [}(hjhhhNhNubh)}(h``FILE_RULES``h]h FILE_RULES}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh]}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]usageah ]h"]usageah$]h&]uh1hhjJhhhhhKubh)}(hhh](h)}(hSYNOPSISh]hSYNOPSIS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK"ubh)}(hXDConverts a C header or source file ``FILE_IN`` into a ReStructured Text included via ..parsed-literal block with cross-references for the documentation files that describe the API. It accepts an optional ``FILE_RULES`` file to describe what elements will be either ignored or be pointed to a non-default reference type/name.h](h#Converts a C header or source file }(hjhhhNhNubh)}(h ``FILE_IN``h]hFILE_IN}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh into a ReStructured Text included via ..parsed-literal block with cross-references for the documentation files that describe the API. It accepts an optional }(hjhhhNhNubh)}(h``FILE_RULES``h]h FILE_RULES}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhj file to describe what elements will be either ignored or be pointed to a non-default reference type/name.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK$hjhhubh)}(h&The output is written at ``FILE_OUT``.h](hThe output is written at }(hj"hhhNhNubh)}(h ``FILE_OUT``h]hFILE_OUT}(hj*hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj"ubh.}(hj"hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK*hjhhubh)}(hIt is capable of identifying ``define``, ``struct``, ``typedef``, ``enum`` and enum ``symbol``, creating cross-references for all of them.h](hIt is capable of identifying }(hjBhhhNhNubh)}(h ``define``h]hdefine}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjBubh, }(hjBhhhNhNubh)}(h ``struct``h]hstruct}(hj\hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjBubh, }hjBsbh)}(h ``typedef``h]htypedef}(hjnhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjBubh, }hjBsbh)}(h``enum``h]henum}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjBubh and enum }(hjBhhhNhNubh)}(h ``symbol``h]hsymbol}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjBubh,, creating cross-references for all of them.}(hjBhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK,hjhhubh)}(htIt is also capable of distinguishing ``#define`` used for specifying Linux-specific macros used to define ``ioctl``.h](h%It is also capable of distinguishing }(hjhhhNhNubh)}(h ``#define``h]h#define}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh: used for specifying Linux-specific macros used to define }(hjhhhNhNubh)}(h ``ioctl``h]hioctl}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK/hjhhubh)}(h:The optional ``FILE_RULES`` contains a set of rules like::h](h The optional }(hjhhhNhNubh)}(h``FILE_RULES``h]h FILE_RULES}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh contains a set of rules like:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK2hjhhubh literal_block)}(hignore ioctl VIDIOC_ENUM_FMT replace ioctl VIDIOC_DQBUF vidioc_qbuf replace define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ :c:type:`v4l2_event_motion_det`h]hignore ioctl VIDIOC_ENUM_FMT replace ioctl VIDIOC_DQBUF vidioc_qbuf replace define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ :c:type:`v4l2_event_motion_det`}hjsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1jhhhK4hjhhubeh}(h]synopsisah ]h"]synopsisah$]h&]uh1hhjJhhhhhK"ubh)}(hhh](h)}(hPOSITIONAL ARGUMENTSh]hPOSITIONAL ARGUMENTS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK9ubh block_quote)}(hn``FILE_IN`` Input C file ``FILE_OUT`` Output RST file ``FILE_RULES`` Exceptions file (optional) h]hdefinition_list)}(hhh](hdefinition_list_item)}(h``FILE_IN`` Input C file h](hterm)}(h ``FILE_IN``h]h)}(hj<h]hFILE_IN}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj:ubah}(h]h ]h"]h$]h&]uh1j8hhhK ubah}(h]h ]h"]h$]h&]uh1jQhj, ubeh}(h]h ]h"]h$]h&]uh1j2hhhKhj) ubah}(h]h ]h"]h$]h&]uh1j-hj% ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]j/j0uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1j'hhhKhjhhubeh}(h] descriptionah ]h"] descriptionah$]h&]uh1hhjJhhhhhKPubh)}(hhh](h)}(hEXAMPLESh]hEXAMPLES}(hj~ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj{ hhhhhKubj)}(hhh](j)}(hPIgnore a define ``_VIDEODEV2_H`` at ``FILE_IN``:: ignore define _VIDEODEV2_H h](h)}(h1Ignore a define ``_VIDEODEV2_H`` at ``FILE_IN``::h](hIgnore a define }(hj hhhNhNubh)}(h``_VIDEODEV2_H``h]h _VIDEODEV2_H}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh at }(hj hhhNhNubh)}(h ``FILE_IN``h]hFILE_IN}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubj)}(hignore define _VIDEODEV2_Hh]hignore define _VIDEODEV2_H}hj sbah}(h]h ]h"]h$]h&]j j uh1jhhhKhj ubeh}(h]h ]h"]h$]h&]uh1jhj hhhhhNubj)}(hXbOn an data structure like this enum:: enum foo { BAR1, BAR2, PRIVATE }; It won't generate cross-references for ``PRIVATE``:: ignore symbol PRIVATE At the same struct, instead of creating one cross reference per symbol, make them all point to the ``enum foo`` C type:: replace symbol BAR1 :c:type:\`foo\` replace symbol BAR2 :c:type:\`foo\` h](h)}(h%On an data structure like this enum::h]h$On an data structure like this enum:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubj)}(h!enum foo { BAR1, BAR2, PRIVATE };h]h!enum foo { BAR1, BAR2, PRIVATE };}hj sbah}(h]h ]h"]h$]h&]j j uh1jhhhKhj ubh)}(h4It won't generate cross-references for ``PRIVATE``::h](h)It won’t generate cross-references for }(hj hhhNhNubh)}(h ``PRIVATE``h]hPRIVATE}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubj)}(hignore symbol PRIVATEh]hignore symbol PRIVATE}hj sbah}(h]h ]h"]h$]h&]j j uh1jhhhKhj ubh)}(hxAt the same struct, instead of creating one cross reference per symbol, make them all point to the ``enum foo`` C type::h](hcAt the same struct, instead of creating one cross reference per symbol, make them all point to the }(hj' hhhNhNubh)}(h ``enum foo``h]henum foo}(hj/ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj' ubh C type:}(hj' hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubj)}(hGreplace symbol BAR1 :c:type:\`foo\` replace symbol BAR2 :c:type:\`foo\`h]hGreplace symbol BAR1 :c:type:\`foo\` replace symbol BAR2 :c:type:\`foo\`}hjG sbah}(h]h ]h"]h$]h&]j j uh1jhhhKhj ubeh}(h]h ]h"]h$]h&]uh1jhj hhhhhNubj)}(hHUse C namespace ``MC`` for all symbols at ``FILE_IN``:: namespace MC h](h)}(h7Use C namespace ``MC`` for all symbols at ``FILE_IN``::h](hUse C namespace }(hj_ hhhNhNubh)}(h``MC``h]hMC}(hjg hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj_ ubh for all symbols at }(hj_ hhhNhNubh)}(h ``FILE_IN``h]hFILE_IN}(hjy hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj_ ubh:}(hj_ hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj[ ubj)}(h namespace MCh]h namespace MC}hj sbah}(h]h ]h"]h$]h&]j j uh1jhhhKhj[ ubeh}(h]h ]h"]h$]h&]uh1jhj hhhhhNubeh}(h]h ]h"]h$]h&]j/j0uh1jhhhKhj{ hhubeh}(h]examplesah ]h"]examplesah$]h&]uh1hhjJhhhhhKubh)}(hhh](h)}(hBUGSh]hBUGS}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(h9Report bugs to Mauro Carvalho Chehab h](h&Report bugs to Mauro Carvalho Chehab <}(hj hhhNhNubh reference)}(hmchehab@kernel.orgh]hmchehab@kernel.org}(hj hhhNhNubah}(h]h ]h"]h$]h&]refurimailto:mchehab@kernel.orguh1j hj ubh>}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubeh}(h]bugsah ]h"]bugsah$]h&]uh1hhjJhhhhhKubh)}(hhh](h)}(h COPYRIGHTh]h COPYRIGHT}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(hNCopyright (c) 2016, 2025 by Mauro Carvalho Chehab .h](h3Copyright (c) 2016, 2025 by Mauro Carvalho Chehab <}(hj hhhNhNubj )}(hmchehab+huawei@kernel.orgh]hmchehab+huawei@kernel.org}(hj hhhNhNubah}(h]h ]h"]h$]h&]refuri mailto:mchehab+huawei@kernel.orguh1j hj ubh>.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hELicense GPLv2: GNU GPL version 2 .h](h"License GPLv2: GNU GPL version 2 <}(hj# hhhNhNubj )}(h!https://gnu.org/licenses/gpl.htmlh]h!https://gnu.org/licenses/gpl.html}(hj+ hhhNhNubah}(h]h ]h"]h$]h&]refurij- uh1j hj# ubh>.}(hj# hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hxThis is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.h]hxThis is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.}(hjD hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubeh}(h] copyrightah ]h"] copyrightah$]h&]uh1hhjJhhhhhKubeh}(h](tools-docs-parse-headers-pyjIeh ]h"](tools/docs/parse-headers.py parse_headerseh$]h&]uh1hhhhhhhhKexpect_referenced_by_name}j` j>sexpect_referenced_by_id}jIj>subeh}(h]including-uapi-header-filesah ]h"]including uapi header filesah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehʌ _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}jI]j>asnameids}(jl ji j` jIj_ j\ jj|jjjjjjjjjx ju j j j j jW jT u nametypes}(jl j` j_ jjjjjjx j j jW uh}(ji hjIjJj\ jJj|j[jjjjjjjjju jj j{ j j jT j u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]hsystem_message)}(hhh]h)}(h:Enumerated list start value not ordinal-1: "2" (ordinal 2)h]h>Enumerated list start value not ordinal-1: “2” (ordinal 2)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]levelKtypeINFOsourcehʌlineKuh1j hjhhhhhKlubatransform_messages]j )}(hhh]h)}(hhh]h3Hyperlink target "parse-headers" is not referenced.}hj sbah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]levelKtypej sourcehʌlineKuh1j uba transformerN include_log] decorationNhhub.