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