Ksphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget?/translations/zh_CN/userspace-api/gpio/gpio-lineevent-data-readmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget?/translations/zh_TW/userspace-api/gpio/gpio-lineevent-data-readmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget?/translations/it_IT/userspace-api/gpio/gpio-lineevent-data-readmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget?/translations/ja_JP/userspace-api/gpio/gpio-lineevent-data-readmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget?/translations/ko_KR/userspace-api/gpio/gpio-lineevent-data-readmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget?/translations/sp_SP/userspace-api/gpio/gpio-lineevent-data-readmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhY/var/lib/git/docbuild/linux/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rsthKubhtarget)}(h.. _GPIO_LINEEVENT_DATA_READ:h]h}(h]h ]h"]h$]h&]refidgpio-lineevent-data-readuh1hhKhhhhhhubhsection)}(hhh](htitle)}(hGPIO_LINEEVENT_DATA_READh]hGPIO_LINEEVENT_DATA_READ}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubhwarning)}(hUThis ioctl is part of chardev_v1.rst and is obsoleted by gpio-v2-line-event-read.rst.h]h paragraph)}(hUThis ioctl is part of chardev_v1.rst and is obsoleted by gpio-v2-line-event-read.rst.h]hUThis ioctl is part of chardev_v1.rst and is obsoleted by gpio-v2-line-event-read.rst.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhubah}(h]h ]h"]h$]h&]uh1hhhhhhhhNubh)}(hhh](h)}(hNameh]hName}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh)}(hHGPIO_LINEEVENT_DATA_READ - Read edge detection events from a line event.h]hHGPIO_LINEEVENT_DATA_READ - Read edge detection events from a line event.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubeh}(h]nameah ]h"]nameah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hSynopsish]hSynopsis}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(h3``int read(int event_fd, void *buf, size_t count)``h]hliteral)}(hj-h]h/int read(int event_fd, void *buf, size_t count)}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1j/hj+ubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]synopsisah ]h"]synopsisah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h Argumentsh]h Arguments}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjLhhhhhKubhdefinition_list)}(hhh](hdefinition_list_item)}(h``event_fd`` The file descriptor of the GPIO character device, as returned in the :c:type:`request.fd` by gpio-get-lineevent-ioctl.rst. h](hterm)}(h ``event_fd``h]j0)}(hjlh]hevent_fd}(hjnhhhNhNubah}(h]h ]h"]h$]h&]uh1j/hjjubah}(h]h ]h"]h$]h&]uh1jhhhhKhjdubh definition)}(hhh]h)}(hThe file descriptor of the GPIO character device, as returned in the :c:type:`request.fd` by gpio-get-lineevent-ioctl.rst.h](hEThe file descriptor of the GPIO character device, as returned in the }(hjhhhNhNubh)}(h':c:type:`request.fd`h]j0)}(hjh]h request.fd}(hjhhhNhNubah}(h]h ](xrefcc-typeeh"]h$]h&]uh1j/hjubah}(h]h ]h"]h$]h&]refdoc+userspace-api/gpio/gpio-lineevent-data-read refdomainjreftypetype refexplicitrefwarn reftargetgpioevent_requestuh1hhhhKhjubh! by gpio-get-lineevent-ioctl.rst.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjdubeh}(h]h ]h"]h$]h&]uh1jbhhhKhj_ubjc)}(hD``buf`` The buffer to contain the :c:type:`events`. h](ji)}(h``buf``h]j0)}(hjh]hbuf}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j/hjubah}(h]h ]h"]h$]h&]uh1jhhhhKhjubj)}(hhh]h)}(h;The buffer to contain the :c:type:`events`.h](hThe buffer to contain the }(hjhhhNhNubh)}(h :c:type:`events`h]j0)}(hjh]hevents}(hjhhhNhNubah}(h]h ](jjc-typeeh"]h$]h&]uh1j/hjubah}(h]h ]h"]h$]h&]refdocj refdomainjreftypetype refexplicitrefwarnjgpioevent_datauh1hhhhKhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jbhhhKhj_hhubjc)}(hs``count`` The number of bytes available in ``buf``, which must be at least the size of a :c:type:`gpioevent_data`. h](ji)}(h ``count``h]j0)}(hj(h]hcount}(hj*hhhNhNubah}(h]h ]h"]h$]h&]uh1j/hj&ubah}(h]h ]h"]h$]h&]uh1jhhhhK#hj"ubj)}(hhh]h)}(hhThe number of bytes available in ``buf``, which must be at least the size of a :c:type:`gpioevent_data`.h](h!The number of bytes available in }(hj@hhhNhNubj0)}(h``buf``h]hbuf}(hjHhhhNhNubah}(h]h ]h"]h$]h&]uh1j/hj@ubh', which must be at least the size of a }(hj@hhhNhNubh)}(h:c:type:`gpioevent_data`h]j0)}(hj\h]hgpioevent_data}(hj^hhhNhNubah}(h]h ](jjc-typeeh"]h$]h&]uh1j/hjZubah}(h]h ]h"]h$]h&]refdocj refdomainjreftypetype refexplicitrefwarnjgpioevent_datauh1hhhhK"hj@ubh.}(hj@hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK"hj=ubah}(h]h ]h"]h$]h&]uh1jhj"ubeh}(h]h ]h"]h$]h&]uh1jbhhhK#hj_hhubeh}(h]h ]h"]h$]h&]uh1j]hjLhhhhhNubeh}(h] argumentsah ]h"] argumentsah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h Descriptionh]h Description}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK&ubh)}(h8Read edge detection events for a line from a line event.h]h8Read edge detection events for a line from a line event.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK(hjhhubh)}(hEdge detection must be enabled for the input line using either ``GPIOEVENT_REQUEST_RISING_EDGE`` or ``GPIOEVENT_REQUEST_FALLING_EDGE``, or both. Edge events are then generated whenever edge interrupts are detected on the input line.h](h?Edge detection must be enabled for the input line using either }(hjhhhNhNubj0)}(h!``GPIOEVENT_REQUEST_RISING_EDGE``h]hGPIOEVENT_REQUEST_RISING_EDGE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j/hjubh or }(hjhhhNhNubj0)}(h"``GPIOEVENT_REQUEST_FALLING_EDGE``h]hGPIOEVENT_REQUEST_FALLING_EDGE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j/hjubhb, or both. Edge events are then generated whenever edge interrupts are detected on the input line.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK*hjhhubh)}(hX2Edges are defined in terms of changes to the logical line value, so an inactive to active transition is a rising edge. If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is set then logical polarity is the opposite of physical polarity, and ``GPIOEVENT_REQUEST_RISING_EDGE`` then corresponds to a falling physical edge.h](h{Edges are defined in terms of changes to the logical line value, so an inactive to active transition is a rising edge. If }(hjhhhNhNubj0)}(h!``GPIOHANDLE_REQUEST_ACTIVE_LOW``h]hGPIOHANDLE_REQUEST_ACTIVE_LOW}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j/hjubhH is set then logical polarity is the opposite of physical polarity, and }(hjhhhNhNubj0)}(h!``GPIOEVENT_REQUEST_RISING_EDGE``h]hGPIOEVENT_REQUEST_RISING_EDGE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j/hjubh- then corresponds to a falling physical edge.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK/hjhhubh)}(hThe kernel captures and timestamps edge events as close as possible to their occurrence and stores them in a buffer from where they can be read by userspace at its convenience using `read()`.h](hThe kernel captures and timestamps edge events as close as possible to their occurrence and stores them in a buffer from where they can be read by userspace at its convenience using }(hj hhhNhNubhtitle_reference)}(h`read()`h]hread()}(hj*hhhNhNubah}(h]h ]h"]h$]h&]uh1j(hj ubh.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK4hjhhubh)}(hX`The source of the clock for :c:type:`event.timestamp` is ``CLOCK_MONOTONIC``, except for kernels earlier than Linux 5.7 when it was ``CLOCK_REALTIME``. There is no indication in the :c:type:`gpioevent_data` as to which clock source is used, it must be determined from either the kernel version or sanity checks on the timestamp itself.h](hThe source of the clock for }(hjBhhhNhNubh)}(h):c:type:`event.timestamp`h]j0)}(hjLh]hevent.timestamp}(hjNhhhNhNubah}(h]h ](jjc-typeeh"]h$]h&]uh1j/hjJubah}(h]h ]h"]h$]h&]refdocj refdomainjreftypetype refexplicitrefwarnjgpioevent_datauh1hhhhK8hjBubh is }(hjBhhhNhNubj0)}(h``CLOCK_MONOTONIC``h]hCLOCK_MONOTONIC}(hjmhhhNhNubah}(h]h ]h"]h$]h&]uh1j/hjBubh8, except for kernels earlier than Linux 5.7 when it was }(hjBhhhNhNubj0)}(h``CLOCK_REALTIME``h]hCLOCK_REALTIME}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j/hjBubh!. There is no indication in the }(hjBhhhNhNubh)}(h:c:type:`gpioevent_data`h]j0)}(hjh]hgpioevent_data}(hjhhhNhNubah}(h]h ](jjc-typeeh"]h$]h&]uh1j/hjubah}(h]h ]h"]h$]h&]refdocj refdomainjreftypetype refexplicitrefwarnjgpioevent_datauh1hhhhK8hjBubh as to which clock source is used, it must be determined from either the kernel version or sanity checks on the timestamp itself.}(hjBhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK8hjhhubh)}(h_Events read from the buffer are always in the same order that they were detected by the kernel.h]h_Events read from the buffer are always in the same order that they were detected by the kernel.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK>hjhhubh)}(h:The size of the kernel event buffer is fixed at 16 events.h]h:The size of the kernel event buffer is fixed at 16 events.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKAhjhhubh)}(hThe buffer may overflow if bursts of events occur quicker than they are read by userspace. If an overflow occurs then the most recent event is discarded. Overflow cannot be detected from userspace.h]hThe buffer may overflow if bursts of events occur quicker than they are read by userspace. If an overflow occurs then the most recent event is discarded. Overflow cannot be detected from userspace.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKChjhhubh)}(hXTo minimize the number of calls required to copy events from the kernel to userspace, `read()` supports copying multiple events. The number of events copied is the lower of the number available in the kernel buffer and the number that will fit in the userspace buffer (``buf``).h](hVTo minimize the number of calls required to copy events from the kernel to userspace, }(hjhhhNhNubj))}(h`read()`h]hread()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j(hjubh supports copying multiple events. The number of events copied is the lower of the number available in the kernel buffer and the number that will fit in the userspace buffer (}(hjhhhNhNubj0)}(h``buf``h]hbuf}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j/hjubh).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKGhjhhubh)}(hfThe `read()` will block if no event is available and the ``event_fd`` has not been set **O_NONBLOCK**.h](hThe }(hjhhhNhNubj))}(h`read()`h]hread()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j(hjubh- will block if no event is available and the }(hjhhhNhNubj0)}(h ``event_fd``h]hevent_fd}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1j/hjubh has not been set }(hjhhhNhNubhstrong)}(h**O_NONBLOCK**h]h O_NONBLOCK}(hjDhhhNhNubah}(h]h ]h"]h$]h&]uh1jBhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKLhjhhubh)}(hyThe presence of an event can be tested for by checking that the ``event_fd`` is readable using `poll()` or an equivalent.h](h@The presence of an event can be tested for by checking that the }(hj\hhhNhNubj0)}(h ``event_fd``h]hevent_fd}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1j/hj\ubh is readable using }(hj\hhhNhNubj))}(h`poll()`h]hpoll()}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1j(hj\ubh or an equivalent.}(hj\hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKOhjhhubeh}(h] descriptionah ]h"] descriptionah$]h&]uh1hhhhhhhhK&ubh)}(hhh](h)}(h Return Valueh]h Return Value}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKSubh)}(hsOn success the number of bytes read, which will be a multiple of the size of a :c:type:`gpio_lineevent_data` event.h](hOOn success the number of bytes read, which will be a multiple of the size of a }(hjhhhNhNubh)}(h:c:type:`gpio_lineevent_data`h]j0)}(hjh]hgpio_lineevent_data}(hjhhhNhNubah}(h]h ](jjc-typeeh"]h$]h&]uh1j/hjubah}(h]h ]h"]h$]h&]refdocj refdomainjreftypetype refexplicitrefwarnjgpio_lineevent_datauh1hhhhKUhjubh event.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKUhjhhubh)}(hqOn error -1 and the ``errno`` variable is set appropriately. Common error codes are described in error-codes.rst.h](hOn error -1 and the }(hjhhhNhNubj0)}(h ``errno``h]herrno}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j/hjubhT variable is set appropriately. Common error codes are described in error-codes.rst.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKXhjhhubeh}(h] return-valueah ]h"] return valueah$]h&]uh1hhhhhhhhKSubeh}(h](hid1eh ]h"]gpio_lineevent_data_readah$]gpio_lineevent_data_readah&]uh1hhhhhhhhK referencedKexpect_referenced_by_name}jhsexpect_referenced_by_id}hhsubeh}(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_handlerj1error_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}h]hasnameids}(jhjjjIjFjjjjjju nametypes}(jjjIjjjuh}(hhjhjhjFjjjLjjjju footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}j?KsRparse_messages]hsystem_message)}(hhh]h)}(h;Duplicate implicit target name: "gpio_lineevent_data_read".h]h?Duplicate implicit target name: “gpio_lineevent_data_read”.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]jalevelKtypeINFOsourcehlineKuh1jhhhhhhhKubatransform_messages]j)}(hhh]h)}(hhh]h>Hyperlink target "gpio-lineevent-data-read" is not referenced.}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypejsourcehlineKuh1juba transformerN include_log] decorationNhhub.