Debian Codegraph @

Documentation/userspace-api/gpio/gpio-lineinfo-changed-read.rst

raw
1 .. SPDX-License-Identifier: GPL-2.0
2
3 .. _GPIO_LINEINFO_CHANGED_READ:
4
5 **************************
6 GPIO_LINEINFO_CHANGED_READ
7 **************************
8
9 .. warning::
10 This ioctl is part of chardev_v1.rst and is obsoleted by
11 gpio-v2-lineinfo-changed-read.rst.
12
13 Name
14 ====
15
16 GPIO_LINEINFO_CHANGED_READ - Read line info change events for watched lines
17 from the chip.
18
19 Synopsis
20 ========
21
22 ``int read(int chip_fd, void *buf, size_t count)``
23
24 Arguments
25 =========
26
27 ``chip_fd``
28 The file descriptor of the GPIO character device returned by `open()`.
29
30 ``buf``
31 The buffer to contain the :c:type:`events<gpioline_info_changed>`.
32
33 ``count``
34 The number of bytes available in ``buf``, which must be at least the size
35 of a :c:type:`gpioline_info_changed` event.
36
37 Description
38 ===========
39
40 Read line info change events for watched lines from the chip.
41
42 .. note::
43 Monitoring line info changes is not generally required, and would typically
44 only be performed by a system monitoring component.
45
46 These events relate to changes in a line's request state or configuration,
47 not its value. Use gpio-lineevent-data-read.rst to receive events when a
48 line changes value.
49
50 A line must be watched using gpio-get-lineinfo-watch-ioctl.rst to generate
51 info changed events. Subsequently, a request, release, or reconfiguration
52 of the line will generate an info changed event.
53
54 The kernel timestamps events when they occur and stores them in a buffer
55 from where they can be read by userspace at its convenience using `read()`.
56
57 The size of the kernel event buffer is fixed at 32 events per ``chip_fd``.
58
59 The buffer may overflow if bursts of events occur quicker than they are read
60 by userspace. If an overflow occurs then the most recent event is discarded.
61 Overflow cannot be detected from userspace.
62
63 Events read from the buffer are always in the same order that they were
64 detected by the kernel, including when multiple lines are being monitored by
65 the one ``chip_fd``.
66
67 To minimize the number of calls required to copy events from the kernel to
68 userspace, `read()` supports copying multiple events. The number of events
69 copied is the lower of the number available in the kernel buffer and the
70 number that will fit in the userspace buffer (``buf``).
71
72 A `read()` will block if no event is available and the ``chip_fd`` has not
73 been set **O_NONBLOCK**.
74
75 The presence of an event can be tested for by checking that the ``chip_fd`` is
76 readable using `poll()` or an equivalent.
77
78 First added in 5.7.
79
80 Return Value
81 ============
82
83 On success the number of bytes read, which will be a multiple of the size of
84 a :c:type:`gpioline_info_changed` event.
85
86 On error -1 and the ``errno`` variable is set appropriately.
87 Common error codes are described in error-codes.rst.