From patchwork Mon Jan 15 00:48:39 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Kent Gibson X-Patchwork-Id: 763183 Received: from mail-ot1-f50.google.com (mail-ot1-f50.google.com [209.85.210.50]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 248111872; Mon, 15 Jan 2024 00:49:19 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="U1tOnyVH" Received: by mail-ot1-f50.google.com with SMTP id 46e09a7af769-6e0a64d94d1so1017955a34.3; Sun, 14 Jan 2024 16:49:19 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1705279759; x=1705884559; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=jRnqaRA694L3HpGLinKd7ruafofbW/AycSUmAuA+5ss=; b=U1tOnyVHlvvBV6fQCtWW5DlvAyIIJeWWzDG4g9eR+foH2k6A52VO8io4f3BidEoAyv es5KJa2m+tYwtbjWngGvq1ZdrgY0dMav8SfluUgPl9gB0d4uBC17rOVpK2KmlaC4MZyA /JdsBbsfbu9zTG0/oqCcuk8Hp5ohWSxT4eaJ4oZJjctbpAG4pUtdp7b6WDk8nEZzR6aH ZX4Jl7Qe3rBt9iNjpN8FgJsmZUZtKkvQv8evFfj/PC3icUL8kCRUBD5l6l9xrW0kU0NL Q85UYVIxFkuUWiNYB1j4XFcM1q1uS76gCRrbZ06VDudcztq9oVIxCEz3bhO2p4C/4u+m EdAw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1705279759; x=1705884559; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=jRnqaRA694L3HpGLinKd7ruafofbW/AycSUmAuA+5ss=; b=IJq5CFZMvmdDHATDNuaZ8eArpKTdItsTIcO7MVNWopuPliKUoZBcPUl5CpOPjYK3+k oyUguqYXXG/0S5hEHW71BGJTWCvJy18EWZtJMl0cWjcEcSj+c9qN74I5NUq8qZEoW6UI k/NrDRFt/fvfn7vdzY5BeOeDv0fbIdEGVvicYjdki4gbj3+N9H1PxRphOAW8reYumKt4 yrN6kRsxaj4oDrps1/oorxJFSRI5IlumtN2fOFSTABmd6EXE3uYlRIqi+mvAX33lmAjD neYR+7nAeL0b0lLC+AOjJyJKWNvLbMBJRMvYRH02ov2pTMwm7mURASFhGKnPAO48G4w8 Lp+A== X-Gm-Message-State: AOJu0YwLXeqr2zPT8EIouf7Oa3+wgGw/QqLGYegthu4QsmHggbykbWRN zv9oCCwgNj08Ozn/j4UMRHtnQSE6xhsLiw== X-Google-Smtp-Source: AGHT+IGgn0f7oLN6x6xjdS8FASDJoJySBPVzEnEGQ6Z8/oGRIOZpQGv4hGu/Nt4sQNPl8n9zYGMCCw== X-Received: by 2002:a05:6830:1089:b0:6db:dc52:389a with SMTP id y9-20020a056830108900b006dbdc52389amr3848996oto.16.1705279758392; Sun, 14 Jan 2024 16:49:18 -0800 (PST) Received: from rigel.home.arpa (60-241-235-125.tpgi.com.au. [60.241.235.125]) by smtp.gmail.com with ESMTPSA id 4-20020aa79204000000b006d999f4a3c0sm6538365pfo.152.2024.01.14.16.49.14 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 14 Jan 2024 16:49:18 -0800 (PST) From: Kent Gibson To: linux-kernel@vger.kernel.org, linux-gpio@vger.kernel.org, linux-doc@vger.kernel.org, brgl@bgdev.pl, linus.walleij@linaro.org, andy@kernel.org, corbet@lwn.net Cc: Kent Gibson Subject: [PATCH v2 1/9] Documentation: gpio: add chardev userspace API documentation Date: Mon, 15 Jan 2024 08:48:39 +0800 Message-Id: <20240115004847.22369-2-warthog618@gmail.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240115004847.22369-1-warthog618@gmail.com> References: <20240115004847.22369-1-warthog618@gmail.com> Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Add documentation for the GPIO character device userspace API. Added to the userspace-api book, but also provide a link from the admin-guide book, as historically the GPIO documentation has been there. Signed-off-by: Kent Gibson Reviewed-by: Linus Walleij --- Documentation/admin-guide/gpio/index.rst | 1 + Documentation/userspace-api/gpio/chardev.rst | 116 ++++++++++++++++++ .../userspace-api/gpio/error-codes.rst | 78 ++++++++++++ .../gpio/gpio-get-chipinfo-ioctl.rst | 41 +++++++ .../gpio/gpio-get-lineinfo-unwatch-ioctl.rst | 49 ++++++++ .../gpio/gpio-v2-get-line-ioctl.rst | 101 +++++++++++++++ .../gpio/gpio-v2-get-lineinfo-ioctl.rst | 50 ++++++++ .../gpio/gpio-v2-get-lineinfo-watch-ioctl.rst | 67 ++++++++++ .../gpio/gpio-v2-line-event-read.rst | 83 +++++++++++++ .../gpio/gpio-v2-line-get-values-ioctl.rst | 51 ++++++++ .../gpio/gpio-v2-line-set-config-ioctl.rst | 57 +++++++++ .../gpio/gpio-v2-line-set-values-ioctl.rst | 47 +++++++ .../gpio/gpio-v2-lineinfo-changed-read.rst | 81 ++++++++++++ Documentation/userspace-api/gpio/index.rst | 17 +++ Documentation/userspace-api/index.rst | 1 + 15 files changed, 840 insertions(+) create mode 100644 Documentation/userspace-api/gpio/chardev.rst create mode 100644 Documentation/userspace-api/gpio/error-codes.rst create mode 100644 Documentation/userspace-api/gpio/gpio-get-chipinfo-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-v2-lineinfo-changed-read.rst create mode 100644 Documentation/userspace-api/gpio/index.rst diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst index f6861ca16ffe..b40f0a2a6822 100644 --- a/Documentation/admin-guide/gpio/index.rst +++ b/Documentation/admin-guide/gpio/index.rst @@ -7,6 +7,7 @@ gpio .. toctree:: :maxdepth: 1 + Character Device Userspace API <../../userspace-api/gpio/chardev> gpio-aggregator sysfs gpio-mockup diff --git a/Documentation/userspace-api/gpio/chardev.rst b/Documentation/userspace-api/gpio/chardev.rst new file mode 100644 index 000000000000..c58dd9771ac9 --- /dev/null +++ b/Documentation/userspace-api/gpio/chardev.rst @@ -0,0 +1,116 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================== +GPIO Character Device Userspace API +=================================== + +This is latest version (v2) of the character device API, as defined in +``include/uapi/linux/gpio.h.`` + +First added in 5.10. + +.. note:: + Do NOT abuse userspace APIs to control hardware that has proper kernel + drivers. There may already be a driver for your use case, and an existing + kernel driver is sure to provide a superior solution to bitbashing + from userspace. + + Read Documentation/driver-api/gpio/drivers-on-gpio.rst to avoid reinventing + kernel wheels in userspace. + + Similarly, for multi-function lines there may be other subsystems, such as + Documentation/spi/index.rst, Documentation/i2c/index.rst, + Documentation/driver-api/pwm.rst, Documentation/w1/index.rst etc, that + provide suitable drivers and APIs for your hardware. + +Basic examples using the character device API can be found in ``tools/gpio/*``. + +The API is based around two major objects, the :ref:`gpio-v2-chip` and the +:ref:`gpio-v2-line-request`. + +.. _gpio-v2-chip: + +Chip +==== + +The Chip represents a single GPIO chip and is exposed to userspace using device +files of the form ``/dev/gpiochipX``. + +Each chip supports a number of GPIO lines, +:c:type:`chip.lines`. Lines on the chip are identified by an +``offset`` in the range from 0 to ``chip.lines - 1``, i.e. `[0,chip.lines)`. + +Lines are requested from the chip using gpio-v2-get-line-ioctl.rst +and the resulting line request is used to access the GPIO chip's lines or +monitor the lines for edge events. + +Within this documentation, the file descriptor returned by calling `open()` +on the GPIO device file is referred to as ``chip_fd``. + +Operations +---------- + +The following operations may be performed on the chip: + +.. toctree:: + :titlesonly: + + Get Line + Get Chip Info + Get Line Info + Watch Line Info + Unwatch Line Info + Read Line Info Changed Events + +.. _gpio-v2-line-request: + +Line Request +============ + +Line requests are created by gpio-v2-get-line-ioctl.rst and provide +access to a set of requested lines. The line request is exposed to userspace +via the anonymous file descriptor returned in +:c:type:`request.fd` by gpio-v2-get-line-ioctl.rst. + +Within this documentation, the line request file descriptor is referred to +as ``req_fd``. + +Operations +---------- + +The following operations may be performed on the line request: + +.. toctree:: + :titlesonly: + + Get Line Values + Set Line Values + Read Line Edge Events + Reconfigure Lines + +Types +===== + +This section contains the structs and enums that are referenced by the API v2, +as defined in ``include/uapi/linux/gpio.h``. + +.. kernel-doc:: include/uapi/linux/gpio.h + :identifiers: + gpio_v2_line_attr_id + gpio_v2_line_attribute + gpio_v2_line_changed_type + gpio_v2_line_config + gpio_v2_line_config_attribute + gpio_v2_line_event + gpio_v2_line_event_id + gpio_v2_line_flag + gpio_v2_line_info + gpio_v2_line_info_changed + gpio_v2_line_request + gpio_v2_line_values + gpiochip_info + +.. toctree:: + :hidden: + + error-codes diff --git a/Documentation/userspace-api/gpio/error-codes.rst b/Documentation/userspace-api/gpio/error-codes.rst new file mode 100644 index 000000000000..edf01f2cf9d2 --- /dev/null +++ b/Documentation/userspace-api/gpio/error-codes.rst @@ -0,0 +1,78 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _gpio_errors: + +******************* +GPIO Error Codes +******************* + +.. _gpio-errors: + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: Common GPIO error codes + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - - ``EAGAIN`` (aka ``EWOULDBLOCK``) + + - The device was opened in non-blocking mode and a read can't + be performed as there is no data available. + + - - ``EBADF`` + + - The file descriptor is not valid. + + - - ``EBUSY`` + + - The ioctl can't be handled because the device is busy. Typically + returned when an ioctl attempts something that would require the + usage of a resource that was already allocated. The ioctl must not + be retried without performing another action to fix the problem + first. + + - - ``EFAULT`` + + - There was a failure while copying data from/to userspace, probably + caused by an invalid pointer reference. + + - - ``EINVAL`` + + - One or more of the ioctl parameters are invalid or out of the + allowed range. This is a widely used error code. + + - - ``ENODEV`` + + - Device not found or was removed. + + - - ``ENOMEM`` + + - There's not enough memory to handle the desired operation. + + - - ``EPERM`` + + - Permission denied. Typically returned in response to an attempt + to perform an action incompatible with the current line + configuration. + + - - ``EIO`` + + - I/O error. Typically returned when there are problems communicating + with a hardware device or requesting features that hardware does not + support. This could indicate broken or flaky hardware. + It's a 'Something is wrong, I give up!' type of error. + + - - ``ENXIO`` + + - No device corresponding to this device special file exists. + +.. note:: + + #. This list is not exhaustive; ioctls may return other error codes. + Since errors may have side effects such as a driver reset, + applications should abort on unexpected errors, or otherwise + assume that the device is in a bad state. + + #. Request-specific error codes are listed in the individual + requests descriptions. diff --git a/Documentation/userspace-api/gpio/gpio-get-chipinfo-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-chipinfo-ioctl.rst new file mode 100644 index 000000000000..05f07fdefe2f --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-get-chipinfo-ioctl.rst @@ -0,0 +1,41 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_GET_CHIPINFO_IOCTL: + +*********************** +GPIO_GET_CHIPINFO_IOCTL +*********************** + +Name +==== + +GPIO_GET_CHIPINFO_IOCTL - Get the publicly available information for a chip. + +Synopsis +======== + +.. c:macro:: GPIO_GET_CHIPINFO_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_CHIPINFO_IOCTL, struct gpiochip_info *info)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``info`` + The :c:type:`chip_info` to be populated. + +Description +=========== + +Gets the publicly available information for a particular GPIO chip. + +Return Value +============ + +On success 0 and ``info`` is populated with the chip info. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst new file mode 100644 index 000000000000..2fec6f12e3bf --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_GET_LINEINFO_UNWATCH_IOCTL: + +******************************* +GPIO_GET_LINEINFO_UNWATCH_IOCTL +******************************* + +Name +==== + +GPIO_GET_LINEINFO_UNWATCH_IOCTL - Disable watching a line for changes to its +requested state and configuration information. + +Synopsis +======== + +.. c:macro:: GPIO_GET_LINEINFO_UNWATCH_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_LINEINFO_UNWATCH_IOCTL, u32 *offset)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``offset`` + The offset of the line to no longer watch. + +Description +=========== + +Remove the line from the list of lines being watched on this ``chip_fd``. + +This is the opposite of gpio-v2-get-lineinfo-watch-ioctl.rst (v2) and +gpio-get-lineinfo-watch-ioctl.rst (v1). + +Unwatching a line that is not watched is an error (**EBUSY**). + +First added in 5.7. + +Return Value +============ + +On success 0. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst new file mode 100644 index 000000000000..d76e614c8343 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst @@ -0,0 +1,101 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_GET_LINE_IOCTL: + +********************** +GPIO_V2_GET_LINE_IOCTL +********************** + +Name +==== + +GPIO_V2_GET_LINE_IOCTL - Request a line or lines from the kernel. + +Synopsis +======== + +.. c:macro:: GPIO_V2_GET_LINE_IOCTL + +``int ioctl(int chip_fd, GPIO_V2_GET_LINE_IOCTL, struct gpio_v2_line_request *request)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``request`` + The :c:type:`line_request` specifying the lines + to request and their configuration. + +Description +=========== + +On success, the requesting process is granted exclusive access to the line +value, write access to the line configuration, and may receive events when +edges are detected on the line, all of which are described in more detail in +:ref:`gpio-v2-line-request`. + +A number of lines may be requested in the one line request, and request +operations are performed on the requested lines by the kernel as atomically +as possible. e.g. gpio-v2-line-get-values-ioctl.rst will read all the +requested lines at once. + +The state of a line, including the value of output lines, is guaranteed to +remain as requested until the returned file descriptor is closed. Once the +file descriptor is closed, the state of the line becomes uncontrolled from +the userspace perspective, and may revert to its default state. + +Requesting a line already in use is an error (**EBUSY**). + +Closing the ``chip_fd`` has no effect on existing line requests. + +.. _gpio-v2-get-line-config-rules: + +Configuration Rules +------------------- + +For any given requested line, the following configuration rules apply: + +The direction flags, ``GPIO_V2_LINE_FLAG_INPUT`` and +``GPIO_V2_LINE_FLAG_OUTPUT``, cannot be combined. If neither are set then +the only other flag that may be set is ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` +and the line is requested "as-is" to allow reading of the line value +without altering the electrical configuration. + +The drive flags, ``GPIO_V2_LINE_FLAG_OPEN_xxx``, require the +``GPIO_V2_LINE_FLAG_OUTPUT`` to be set. +Only one drive flag may be set. +If none are set then the line is assumed push-pull. + +Only one bias flag, ``GPIO_V2_LINE_FLAG_BIAS_xxx``, may be set, and it +requires a direction flag to also be set. +If no bias flags are set then the bias configuration is not changed. + +The edge flags, ``GPIO_V2_LINE_FLAG_EDGE_xxx``, require +``GPIO_V2_LINE_FLAG_INPUT`` to be set and may be combined to detect both rising +and falling edges. + +Only one event clock flag, ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_xxx``, may be set. +If none are set then the event clock defaults to ``CLOCK_MONOTONIC``. +The ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE`` flag requires supporting hardware +and a kernel with ``CONFIG_HTE`` set. Requesting HTE from a device that +doesn't support it is an error (**EOPNOTSUP**). + +The :c:type:`debounce_period_us` attribute may only +be applied to lines with ``GPIO_V2_LINE_FLAG_INPUT`` set. When set, debounce +applies to both the values returned by gpio-v2-line-get-values-ioctl.rst and +the edges returned by gpio-v2-line-event-read.rst. If not +supported directly by hardware, the debouncing is performed in software by the +kernel. + +Requesting an invalid configuration is an error (**EINVAL**). + +Return Value +============ + +On success 0 and the :c:type:`request.fd` contains the +file descriptor for the request. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-ioctl.rst new file mode 100644 index 000000000000..bc4d8df887d4 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-ioctl.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_GET_LINEINFO_IOCTL: + +************************** +GPIO_V2_GET_LINEINFO_IOCTL +************************** + +Name +==== + +GPIO_V2_GET_LINEINFO_IOCTL - Get the publicly available information for a line. + +Synopsis +======== + +.. c:macro:: GPIO_V2_GET_LINEINFO_IOCTL + +``int ioctl(int chip_fd, GPIO_V2_GET_LINEINFO_IOCTL, struct gpio_v2_line_info *info)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``info`` + The :c:type:`line_info` to be populated, with the + ``offset`` field set to indicate the line to be collected. + +Description +=========== + +Get the publicly available information for a line. + +This information is available independent of whether the line is in use. + +.. note:: + The line info does not include the line value. + + The line must be requested using gpio-v2-get-line-ioctl.rst to access its + value. + +Return Value +============ + +On success 0 and ``info`` is populated with the chip info. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.rst new file mode 100644 index 000000000000..938ff85a9322 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.rst @@ -0,0 +1,67 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_GET_LINEINFO_WATCH_IOCTL: + +******************************** +GPIO_V2_GET_LINEINFO_WATCH_IOCTL +******************************** + +Name +==== + +GPIO_V2_GET_LINEINFO_WATCH_IOCTL - Enable watching a line for changes to its +request state and configuration information. + +Synopsis +======== + +.. c:macro:: GPIO_V2_GET_LINEINFO_WATCH_IOCTL + +``int ioctl(int chip_fd, GPIO_V2_GET_LINEINFO_WATCH_IOCTL, struct gpio_v2_line_info *info)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``info`` + The :c:type:`line_info` struct to be populated, with + the ``offset`` set to indicate the line to watch + +Description +=========== + +Enable watching a line for changes to its request state and configuration +information. Changes to line info include a line being requested, released +or reconfigured. + +.. note:: + Watching line info is not generally required, and would typically only be + used by a system monitoring component. + + The line info does NOT include the line value. + The line must be requested using gpio-v2-get-line-ioctl.rst to access + its value, and the line request can monitor a line for events using + gpio-v2-line-event-read.rst. + +By default all lines are unwatched when the GPIO chip is opened. + +Multiple lines may be watched simultaneously by adding a watch for each. + +Once a watch is set, any changes to line info will generate events which can be +read from the ``chip_fd`` as described in +gpio-v2-lineinfo-changed-read.rst. + +Adding a watch to a line that is already watched is an error (**EBUSY**). + +Watches are specific to the ``chip_fd`` and are independent of watches +on the same GPIO chip opened with a separate call to `open()`. + +Return Value +============ + +On success 0 and ``info`` is populated with the current line info. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst b/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst new file mode 100644 index 000000000000..6513c23fb7ca --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst @@ -0,0 +1,83 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_LINE_EVENT_READ: + +*********************** +GPIO_V2_LINE_EVENT_READ +*********************** + +Name +==== + +GPIO_V2_LINE_EVENT_READ - Read edge detection events for lines from a request. + +Synopsis +======== + +``int read(int req_fd, void *buf, size_t count)`` + +Arguments +========= + +``req_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd` by gpio-v2-get-line-ioctl.rst. + +``buf`` + The buffer to contain the :c:type:`events`. + +``count`` + The number of bytes available in ``buf``, which must be at + least the size of a :c:type:`gpio_v2_line_event`. + +Description +=========== + +Read edge detection events for lines from a request. + +Edge detection must be enabled for the input line using either +``GPIO_V2_LINE_FLAG_EDGE_RISING`` or ``GPIO_V2_LINE_FLAG_EDGE_FALLING``, or +both. Edge events are then generated whenever edge interrupts are detected on +the input line. + +The 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()`. + +Events read from the buffer are always in the same order that they were +detected by the kernel, including when multiple lines are being monitored by +the one request. + +The size of the kernel event buffer is fixed at the time of line request +creation, and can be influenced by the +:c:type:`request.event_buffer_size`. +The default size is 16 times the number of lines requested. + +The buffer may overflow if bursts of events occur quicker than they are read +by userspace. If an overflow occurs then the oldest buffered event is +discarded. Overflow can be detected from userspace by monitoring the event +sequence numbers. + +To 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``). + +Changing the edge detection flags using gpio-v2-line-set-config-ioctl.rst +does not remove or modify the events already contained in the kernel event +buffer. + +The `read()` will block if no event is available and the ``req_fd`` has not +been set **O_NONBLOCK**. + +The presence of an event can be tested for by checking that the ``req_fd`` is +readable using `poll()` or an equivalent. + +Return Value +============ + +On success the number of bytes read, which will be a multiple of the size of a +:c:type:`gpio_v2_line_event` event. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst new file mode 100644 index 000000000000..e4e74a1926d8 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst @@ -0,0 +1,51 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_LINE_GET_VALUES_IOCTL: + +***************************** +GPIO_V2_LINE_GET_VALUES_IOCTL +***************************** + +Name +==== + +GPIO_V2_LINE_GET_VALUES_IOCTL - Get the values of requested lines. + +Synopsis +======== + +.. c:macro:: GPIO_V2_LINE_GET_VALUES_IOCTL + +``int ioctl(int req_fd, GPIO_V2_LINE_GET_VALUES_IOCTL, struct gpio_v2_line_values *values)`` + +Arguments +========= + +``req_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd` by gpio-v2-get-line-ioctl.rst. + +``values`` + The :c:type:`line_values` to get with the ``mask`` set + to indicate the subset of requested lines to get. + +Description +=========== + +Get the values of requested lines. + +The values of both input and output lines may be read. + +For output lines, the value returned is driver and configuration dependent and +may be either the output buffer (the last requested value set) or the input +buffer (the actual level of the line), and depending on the hardware and +configuration these may differ. + +Return Value +============ + +On success 0 and the corresponding :c:type:`values.bits` +contain the value read. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst new file mode 100644 index 000000000000..126c2626ba6b --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst @@ -0,0 +1,57 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_LINE_SET_CONFIG_IOCTL: + +***************************** +GPIO_V2_LINE_SET_CONFIG_IOCTL +***************************** + +Name +==== + +GPIO_V2_LINE_SET_CONFIG_IOCTL - Update the configuration of previously requested lines. + +Synopsis +======== + +.. c:macro:: GPIO_V2_LINE_SET_CONFIG_IOCTL + +``int ioctl(int req_fd, GPIO_V2_LINE_SET_CONFIG_IOCTL, struct gpio_v2_line_config *config)`` + +Arguments +========= + +``req_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd` by gpio-v2-get-line-ioctl.rst. + +``config`` + The new :c:type:`configuration` to apply to the + requested lines. + +Description +=========== + +Update the configuration of previously requested lines, without releasing the +line or introducing potential glitches. + +The new configuration must specify the configuration of all requested lines. + +The same :ref:`gpio-v2-get-line-config-rules` that apply when requesting the lines +also apply when updating the line configuration. + +The motivating use case for this command is changing direction of +bi-directional lines between input and output, but it may also be used to +dynamically control edge detection, or more generally move lines seamlessly +from one configuration state to another. + +To only change the value of output lines, use +gpio-v2-line-set-values-ioctl.rst. + +Return Value +============ + +On success 0. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst new file mode 100644 index 000000000000..6d2d1886950b --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst @@ -0,0 +1,47 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_LINE_SET_VALUES_IOCTL: + +***************************** +GPIO_V2_LINE_SET_VALUES_IOCTL +***************************** + +Name +==== + +GPIO_V2_LINE_SET_VALUES_IOCTL - Set the values of requested output lines. + +Synopsis +======== + +.. c:macro:: GPIO_V2_LINE_SET_VALUES_IOCTL + +``int ioctl(int req_fd, GPIO_V2_LINE_SET_VALUES_IOCTL, struct gpio_v2_line_values *values)`` + +Arguments +========= + +``req_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd` by gpio-v2-get-line-ioctl.rst. + +``values`` + The :c:type:`line_values` to set with the ``mask`` set + to indicate the subset of requested lines to set and ``bits`` set to + indicate the new value. + +Description +=========== + +Set the values of requested output lines. + +Only the values of output lines may be set. +Attempting to set the value of an input line is an error (**EPERM**). + +Return Value +============ + +On success 0. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-lineinfo-changed-read.rst b/Documentation/userspace-api/gpio/gpio-v2-lineinfo-changed-read.rst new file mode 100644 index 000000000000..24ad325e7253 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-lineinfo-changed-read.rst @@ -0,0 +1,81 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_LINEINFO_CHANGED_READ: + +***************************** +GPIO_V2_LINEINFO_CHANGED_READ +***************************** + +Name +==== + +GPIO_V2_LINEINFO_CHANGED_READ - Read line info changed events for watched +lines from the chip. + +Synopsis +======== + +``int read(int chip_fd, void *buf, size_t count)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``buf`` + The buffer to contain the :c:type:`events`. + +``count`` + The number of bytes available in ``buf``, which must be at least the size + of a :c:type:`gpio_v2_line_info_changed` event. + +Description +=========== + +Read line info changed events for watched lines from the chip. + +.. note:: + Monitoring line info changes is not generally required, and would typically + only be performed by a system monitoring component. + + These events relate to changes in a line's request state or configuration, + not its value. Use gpio-v2-line-event-read.rst to receive events when a + line changes value. + +A line must be watched using gpio-v2-get-lineinfo-watch-ioctl.rst to generate +info changed events. Subsequently, a request, release, or reconfiguration +of the line will generate an info changed event. + +The kernel timestamps events when they occur and stores them in a buffer +from where they can be read by userspace at its convenience using `read()`. + +The size of the kernel event buffer is fixed at 32 events per ``chip_fd``. + +The 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. + +Events read from the buffer are always in the same order that they were +detected by the kernel, including when multiple lines are being monitored by +the one ``chip_fd``. + +To 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``). + +A `read()` will block if no event is available and the ``chip_fd`` has not +been set **O_NONBLOCK**. + +The presence of an event can be tested for by checking that the ``chip_fd`` is +readable using `poll()` or an equivalent. + +Return Value +============ + +On success the number of bytes read, which will be a multiple of the size +of a :c:type:`gpio_v2_line_info_changed` event. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/index.rst b/Documentation/userspace-api/gpio/index.rst new file mode 100644 index 000000000000..072b9fa18aea --- /dev/null +++ b/Documentation/userspace-api/gpio/index.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==== +GPIO +==== + +.. toctree:: + :maxdepth: 1 + + Character Device Userspace API + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index 031df47a7c19..8e174a605f69 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -25,6 +25,7 @@ place where this information is gathered. dma-buf-alloc-exchange ebpf/index ELF + gpio/index ioctl/index iommu iommufd From patchwork Mon Jan 15 00:48:40 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Kent Gibson X-Patchwork-Id: 762905 Received: from mail-oi1-f175.google.com (mail-oi1-f175.google.com [209.85.167.175]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id ECFEE20F4; Mon, 15 Jan 2024 00:49:29 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="l6uPeFtM" Received: by mail-oi1-f175.google.com with SMTP id 5614622812f47-3bb53e20a43so5867752b6e.1; Sun, 14 Jan 2024 16:49:29 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1705279769; x=1705884569; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=vbGb8zBMQYQKYcbDGRHhZWu6ZjU/ySFVlEqOv4kf1cQ=; b=l6uPeFtMUGF6Gq+oyIugpIu8IaMi+COCaHcmeWJmUj3zQAQLbuecDlraisVBWYvgYK idCejcsEruXCAT1UyrcXjwkLM/6e2WfhfGAlfgP8GvAdbZB+qgylIclJcVFTw3uVSEK7 dgzRK0HYYPLRvGBqJxOk/y3LEU16HfAEnqgnIdkIwTdGip2q6AlL7sjuk3MmeqivytPD NBo154Yh2OOqQBstxBftmwgDQNNB0Z5kI8BZ1oPoq3bu/0vJRbCK5iT9Cpsu8MP7cucW oKJjqRXVdpCHhV5rvFIBL/K6/4k1d2VgUP+NAROw3AZY+ETIAdal1WbiH06CdFq0ISIu SYhA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1705279769; x=1705884569; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=vbGb8zBMQYQKYcbDGRHhZWu6ZjU/ySFVlEqOv4kf1cQ=; b=LtolOoXg3ByUxJfI7Dp5bZlQGDxRZU2G2TjDEAF4ebk2ZQI8+2RhFYwdG1URvkPr47 nu11SyAXbQDZX+fhqVCHu23ShHDrtZc/90zWeICxeumjwPEn+NjKSdRZTV71jz7LcK4U Kgoo/Kr7awVZGdx+RYjEFq3aP//IaIRgUKgd+EzRMRpIgqe5pANEElliM+IUnOx2Z62u hFgCH43bYf7Ww2SqbGD5/rAs9CaY95ZdR3CgrBxwOUnfQ2Ynq87uqwayTmbn5dTvB1VM v2pf9YsOs6JBokE+94Zc0nx9bM1mWcbr/WyVjkjROHeyKP41jZZakNJ/60FQ3satU+58 P+jw== X-Gm-Message-State: AOJu0Yy8K+kJLTI/b+wKONtEhZk/yEed8Wv7HtnmVq6sY2LD41Ma0Bkp lwH8CLqMN9GflU8KxonQ09sonx9nolczSA== X-Google-Smtp-Source: AGHT+IG29p5+vCkQP/j3ICy5UNtO+jCfUgPK1JmqidHnVL6Veqp7REuXnn2uMxpOJT49jtRkAlCp8g== X-Received: by 2002:a54:468b:0:b0:3bb:edfd:42db with SMTP id k11-20020a54468b000000b003bbedfd42dbmr4423368oic.63.1705279768873; Sun, 14 Jan 2024 16:49:28 -0800 (PST) Received: from rigel.home.arpa (60-241-235-125.tpgi.com.au. [60.241.235.125]) by smtp.gmail.com with ESMTPSA id 4-20020aa79204000000b006d999f4a3c0sm6538365pfo.152.2024.01.14.16.49.25 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 14 Jan 2024 16:49:28 -0800 (PST) From: Kent Gibson To: linux-kernel@vger.kernel.org, linux-gpio@vger.kernel.org, linux-doc@vger.kernel.org, brgl@bgdev.pl, linus.walleij@linaro.org, andy@kernel.org, corbet@lwn.net Cc: Kent Gibson Subject: [PATCH v2 2/9] Documentation: ABI: update gpio-cdev to reference chardev.rst Date: Mon, 15 Jan 2024 08:48:40 +0800 Message-Id: <20240115004847.22369-3-warthog618@gmail.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240115004847.22369-1-warthog618@gmail.com> References: <20240115004847.22369-1-warthog618@gmail.com> Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Update the gpio-cdev interface document to refer to the new chardev.rst. Signed-off-by: Kent Gibson --- Documentation/ABI/testing/gpio-cdev | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Documentation/ABI/testing/gpio-cdev b/Documentation/ABI/testing/gpio-cdev index 66bdcd188b6c..c9689b2a6fed 100644 --- a/Documentation/ABI/testing/gpio-cdev +++ b/Documentation/ABI/testing/gpio-cdev @@ -6,8 +6,9 @@ Description: The character device files /dev/gpiochip* are the interface between GPIO chips and userspace. - The ioctl(2)-based ABI is defined and documented in - [include/uapi]. + The ioctl(2)-based ABI is defined in + [include/uapi] and documented in + Documentation/userspace-api/gpio/chardev.rst. The following file operations are supported: @@ -17,8 +18,8 @@ Description: ioctl(2) Initiate various actions. - See the inline documentation in [include/uapi] - for descriptions of all ioctls. + See Documentation/userspace-api/gpio/chardev.rst + for a description of all ioctls. close(2) Stops and free up the I/O contexts that was associated From patchwork Mon Jan 15 00:48:41 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Kent Gibson X-Patchwork-Id: 763182 Received: from mail-pg1-f175.google.com (mail-pg1-f175.google.com [209.85.215.175]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 12EBB3C0E; Mon, 15 Jan 2024 00:49:39 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="J+kUwrdf" Received: by mail-pg1-f175.google.com with SMTP id 41be03b00d2f7-5ce07cf1e5dso4028128a12.2; Sun, 14 Jan 2024 16:49:39 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1705279779; x=1705884579; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=FiHyUz9MWa8IOwndsZYuQ8RGJ7cOjISqLVJMLSNv/lU=; b=J+kUwrdflRQJ2DonxaCTaYMBXYdMA6PBElxxdBghu8lkseJJOz3TgU+z/XNgGgOLK7 UaYV9ZNxziJqzWW5NqzXYN2HXnRAclP80V+m9Mph1v2YS5Jibmt+Nc3zBedFaXjIr1tI cX39OgpMIUxQXc9SR8rnQyfpqqo1phMIDqecUY+5nf4WZFQezzFUMTAKZPUJrDi5IXfD jTvfaNmAPNDFLWsSZip6IqmGnbP9HnrzNeGelYt/LLq2GueXmEkoBl/RB8OH9FGDNInH 9gLKkM71bPgFSjuxmWAcH6x3jB9wH7ZtCp8disQAQ3kWsCOrAapf6DVp7Zpn+C9kYwqA F9tQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1705279779; x=1705884579; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=FiHyUz9MWa8IOwndsZYuQ8RGJ7cOjISqLVJMLSNv/lU=; b=aBuRaMwjtmU7DG/0k133lYHJZQ+nCPlIlW9HMG1UVL3dJl9Y/6MZ+DX7xKrTjDbjgX lcs6gUe72BmiL0NieL78UvojUmcKCkpiiQm18AU6LhTFhpzt+WNaCRfz7VigskYisfSN DMscLtPt8M8IldMPpQK958eaZ15hZUm5brCl0OvMfmDc3f0TFagabtP0/4rETaQFrbq5 8y2KOwXWBSl363SFPrUEHCO+SQaUOBMFPJ7zUMlqHVo3DB2wl4WHcmIP+THq0S3WM9kx V74Ksxz884AJv2m1G8dpS0Q+Ix/XC57zHE1l8f5cLlBCUgntfwjeKdLQWH5mPcueBFyn JLgQ== X-Gm-Message-State: AOJu0YyONza9g1EshOQMLaecI/3y5neWTxr7OSYdKzG6KtQNovmUhV5r dWowmBPP/PPLjDPTxlbBreAYrDMqDfuDNw== X-Google-Smtp-Source: AGHT+IHpQPJ6Zh56XfXp3oFTraoVjRT/bLVWXn86o1jFW62TUAlj5jZgkX31SCZwPYwpc+ALBgwJtQ== X-Received: by 2002:a05:6a00:17a6:b0:6d9:9de5:d121 with SMTP id s38-20020a056a0017a600b006d99de5d121mr2513546pfg.27.1705279779003; Sun, 14 Jan 2024 16:49:39 -0800 (PST) Received: from rigel.home.arpa (60-241-235-125.tpgi.com.au. [60.241.235.125]) by smtp.gmail.com with ESMTPSA id 4-20020aa79204000000b006d999f4a3c0sm6538365pfo.152.2024.01.14.16.49.35 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 14 Jan 2024 16:49:38 -0800 (PST) From: Kent Gibson To: linux-kernel@vger.kernel.org, linux-gpio@vger.kernel.org, linux-doc@vger.kernel.org, brgl@bgdev.pl, linus.walleij@linaro.org, andy@kernel.org, corbet@lwn.net Cc: Kent Gibson Subject: [PATCH v2 3/9] Documentation: ABI: update sysfs-gpio to reference gpio-cdev Date: Mon, 15 Jan 2024 08:48:41 +0800 Message-Id: <20240115004847.22369-4-warthog618@gmail.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240115004847.22369-1-warthog618@gmail.com> References: <20240115004847.22369-1-warthog618@gmail.com> Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Update the sysfs-gpio interface document to refer to the gpio-cdev interface that obsoletes it. Signed-off-by: Kent Gibson --- Documentation/ABI/obsolete/sysfs-gpio | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/ABI/obsolete/sysfs-gpio b/Documentation/ABI/obsolete/sysfs-gpio index b8b0fd341c17..da1345d854b4 100644 --- a/Documentation/ABI/obsolete/sysfs-gpio +++ b/Documentation/ABI/obsolete/sysfs-gpio @@ -28,5 +28,5 @@ Description: /label ... (r/o) descriptive, not necessarily unique /ngpio ... (r/o) number of GPIOs; numbered N to N + (ngpio - 1) - This ABI is deprecated and will be removed after 2020. It is - replaced with the GPIO character device. + This ABI is obsoleted by Documentation/ABI/testing/gpio-cdev and will be + removed after 2020. From patchwork Mon Jan 15 00:48:42 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Kent Gibson X-Patchwork-Id: 762904 Received: from mail-oi1-f179.google.com (mail-oi1-f179.google.com [209.85.167.179]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 9738D3C00; Mon, 15 Jan 2024 00:49:50 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="A1fT7xfS" Received: by mail-oi1-f179.google.com with SMTP id 5614622812f47-3bd6ef33227so856122b6e.0; Sun, 14 Jan 2024 16:49:50 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1705279789; x=1705884589; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=DT6DB3XTDC40oMMuTXn3Vaf1U+FT3q/F4RaRZt+9Hsw=; b=A1fT7xfSnqKtt50iehnuLNPQdJWL+VTD8/9FKlBPZ2wCDnRj/ArMsBwt1YJJEpZYP1 e5/e0EfP5x7w/qUeof3WcpSgAKNiaQGC6y4AkpjMTstCjis4yOYOXfDVFeBiB2qdZVqT FsLtPQzETJMIj0cl3nXULIa1KC0DBjSgiMok+h5ycK++p6elPSVugo/UOCCa3UBgFXka ZzfMADF378feRrybgRbCDBkgWAKyCrWx4RhivwoV9kdM1cokTWqSRgLV5BhpkLHVktdW 6uAy7pljMxT5WhE/K2wkLW/BuaspS83EuHkg7RTRbBCNxxfzW9gjfwrLtmoM2yY1tlJD WIvg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1705279789; x=1705884589; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=DT6DB3XTDC40oMMuTXn3Vaf1U+FT3q/F4RaRZt+9Hsw=; b=kzwEF9ay1WXIj05luwq73um+LpIPZ9KZESEiNlABmnmoIY57K7f3t6R+CXhgkFzIaB 4dH183whJx//FIV21dBay4snsFZPvmVz52Tmqf/LstOvPCSpopHGC8VpFJph2RsLwjyk qElLzRZxbNi5VSrey1yX/wymvBbvO+eSs5r1sl0TDiazSWx0J1hG/KdXG+3sCDLNNvIW lkciykVTPAtxDQA/9knVVkkk8Y6hJ/SBmEdeZM6XpTnK7FTXmqEqqNo0lszuVw/sVCw+ e/AvGIB4rRKiiX9mOHqdq5rmXAmiNCn02BLGH9OM0genxFqrnbfv9eJ+uV4qsBkCl2js noUA== X-Gm-Message-State: AOJu0YwIFR1doe875QIg7YLiJbJDcqaTfTd1KrsBaUSO6SehbXJ1yHgq IV/k9uBTENNbUdLtWVnn9/FU1goV6RQ4bA== X-Google-Smtp-Source: AGHT+IGt9s7kpfOp2/QJFQ6Mvf68WBiNEg9v9PGbK2e7riYjvwQTE9jBwW4nwrWfDyJ9K0w59PIodg== X-Received: by 2002:a05:6808:1312:b0:3bd:6ab0:b98 with SMTP id y18-20020a056808131200b003bd6ab00b98mr4698191oiv.15.1705279789506; Sun, 14 Jan 2024 16:49:49 -0800 (PST) Received: from rigel.home.arpa (60-241-235-125.tpgi.com.au. [60.241.235.125]) by smtp.gmail.com with ESMTPSA id 4-20020aa79204000000b006d999f4a3c0sm6538365pfo.152.2024.01.14.16.49.46 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 14 Jan 2024 16:49:49 -0800 (PST) From: Kent Gibson To: linux-kernel@vger.kernel.org, linux-gpio@vger.kernel.org, linux-doc@vger.kernel.org, brgl@bgdev.pl, linus.walleij@linaro.org, andy@kernel.org, corbet@lwn.net Cc: Kent Gibson Subject: [PATCH v2 4/9] Documentation: gpio: move sysfs into an obsolete section Date: Mon, 15 Jan 2024 08:48:42 +0800 Message-Id: <20240115004847.22369-5-warthog618@gmail.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240115004847.22369-1-warthog618@gmail.com> References: <20240115004847.22369-1-warthog618@gmail.com> Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 The GPIO sysfs API is long obsolete, so highlight this even further by moving it into an obsolete APIs section in both the admin-guide and userspace-api books. Signed-off-by: Kent Gibson --- Documentation/admin-guide/gpio/index.rst | 2 +- Documentation/admin-guide/gpio/obsolete.rst | 11 +++++++++++ Documentation/userspace-api/gpio/index.rst | 1 + Documentation/userspace-api/gpio/obsolete.rst | 10 ++++++++++ .../{admin-guide => userspace-api}/gpio/sysfs.rst | 0 5 files changed, 23 insertions(+), 1 deletion(-) create mode 100644 Documentation/admin-guide/gpio/obsolete.rst create mode 100644 Documentation/userspace-api/gpio/obsolete.rst rename Documentation/{admin-guide => userspace-api}/gpio/sysfs.rst (100%) diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst index b40f0a2a6822..3ac3aa15fa8b 100644 --- a/Documentation/admin-guide/gpio/index.rst +++ b/Documentation/admin-guide/gpio/index.rst @@ -9,9 +9,9 @@ gpio Character Device Userspace API <../../userspace-api/gpio/chardev> gpio-aggregator - sysfs gpio-mockup gpio-sim + Obsolete APIs .. only:: subproject and html diff --git a/Documentation/admin-guide/gpio/obsolete.rst b/Documentation/admin-guide/gpio/obsolete.rst new file mode 100644 index 000000000000..dbf88f13c680 --- /dev/null +++ b/Documentation/admin-guide/gpio/obsolete.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================== +Obsolete GPIO APIs +================== + +.. toctree:: + :maxdepth: 1 + + Sysfs Interface <../../userspace-api/gpio/sysfs> + diff --git a/Documentation/userspace-api/gpio/index.rst b/Documentation/userspace-api/gpio/index.rst index 072b9fa18aea..f258de4ef370 100644 --- a/Documentation/userspace-api/gpio/index.rst +++ b/Documentation/userspace-api/gpio/index.rst @@ -8,6 +8,7 @@ GPIO :maxdepth: 1 Character Device Userspace API + Obsolete Userspace APIs .. only:: subproject and html diff --git a/Documentation/userspace-api/gpio/obsolete.rst b/Documentation/userspace-api/gpio/obsolete.rst new file mode 100644 index 000000000000..c27bd6014a3d --- /dev/null +++ b/Documentation/userspace-api/gpio/obsolete.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================ +Obsolete GPIO Userspace APIs +============================ + +.. toctree:: + :maxdepth: 1 + + Sysfs Interface diff --git a/Documentation/admin-guide/gpio/sysfs.rst b/Documentation/userspace-api/gpio/sysfs.rst similarity index 100% rename from Documentation/admin-guide/gpio/sysfs.rst rename to Documentation/userspace-api/gpio/sysfs.rst From patchwork Mon Jan 15 00:48:43 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Kent Gibson X-Patchwork-Id: 763181 Received: from mail-pf1-f182.google.com (mail-pf1-f182.google.com [209.85.210.182]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 118B2468A; Mon, 15 Jan 2024 00:50:00 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="MkayhyQJ" Received: by mail-pf1-f182.google.com with SMTP id d2e1a72fcca58-6db79e11596so330344b3a.0; Sun, 14 Jan 2024 16:50:00 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1705279800; x=1705884600; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=rMlrrpyPoOkhOpyz7nMSzvwkhIZ9LzG5C/a8I1U5X7c=; b=MkayhyQJUuLS2gNgVDUugfb8o8BHKK8MsUK53rGui1nmMGUvykArZ5Ns5mSS315/mo 9j9lOfiYhpJYP0SyBadB3ZSRZsjFNq302In5wdjP13LXwXl0W6osdqFLMspH/wMTMNyD qz04jMneoA2w5DWRukNEfXLF1VYL9rVYKuBXO+OQDlqjXKqASZED7gjn2FXblqzGNKoP tOEFcOJdbPz3O5VUR2O4l0PupHp3LM+jVgM+UY8Li8WVslMKv1QZ7nylf+JwFTSXaZvi cOHGZqzwHfftoQdVdkGgFLVwqNM8JXvq43hQanhsE3oFmhYQjRO3rIut+dsWm1CEcJzx SNyw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1705279800; x=1705884600; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=rMlrrpyPoOkhOpyz7nMSzvwkhIZ9LzG5C/a8I1U5X7c=; b=JrLuGonoWx2+Exps3rovLsgIRI+SkUDzilOvIrIGiHcOzwguoqCj5zQS4TsSXRx8gg iFBYwb62aPUD8mltSyi2WvFzl0vrgKkw9YxBMn1ezjvd7dHhtz2NbJYBbZU8XqCogfNs P+uanvyTw8wS24EfVul6hOCd3HcQ4eMnk06LdtRHJy260IE9G17Y0JMNiyaO41FlYEt1 VMNLam7zi8sf8ssgf5pdsx0WBxrKQUAOJVESpHFGWQP/fJWsZ+Q5lP5SzmugfHlMfXeB /C6LxYij06kWHmpFZ8iGfLDXfKNAb1vALVJ6QFoP3qlSHMDhTLdXmSlFEhjEJ1MUBKXs 1x9w== X-Gm-Message-State: AOJu0YwpOqb9F7h3CDtDEox+ZiJXcvxDVd7LNaSBpllcL8u8aSfmcyoA Kx1YOegpA0Mkh77BHXeITPP+V6XE0gcGlw== X-Google-Smtp-Source: AGHT+IHh9rOasoaGaDcjxHn1QgIhNgNeRGrqWUGZj0E3PuJSDlqVm0UfZYrZFIHd85azXnU8th91wg== X-Received: by 2002:a05:6a00:3988:b0:6d9:a856:eec2 with SMTP id fi8-20020a056a00398800b006d9a856eec2mr5967151pfb.14.1705279800116; Sun, 14 Jan 2024 16:50:00 -0800 (PST) Received: from rigel.home.arpa (60-241-235-125.tpgi.com.au. [60.241.235.125]) by smtp.gmail.com with ESMTPSA id 4-20020aa79204000000b006d999f4a3c0sm6538365pfo.152.2024.01.14.16.49.56 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 14 Jan 2024 16:49:59 -0800 (PST) From: Kent Gibson To: linux-kernel@vger.kernel.org, linux-gpio@vger.kernel.org, linux-doc@vger.kernel.org, brgl@bgdev.pl, linus.walleij@linaro.org, andy@kernel.org, corbet@lwn.net Cc: Kent Gibson Subject: [PATCH v2 5/9] Documentation: gpio: update sysfs documentation to reference new chardev doc Date: Mon, 15 Jan 2024 08:48:43 +0800 Message-Id: <20240115004847.22369-6-warthog618@gmail.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240115004847.22369-1-warthog618@gmail.com> References: <20240115004847.22369-1-warthog618@gmail.com> Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Update GPIO sysfs interface documentation to reference the new chardev document rather than gpio.h. Signed-off-by: Kent Gibson --- Documentation/userspace-api/gpio/sysfs.rst | 27 ++++++++++++---------- 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/Documentation/userspace-api/gpio/sysfs.rst b/Documentation/userspace-api/gpio/sysfs.rst index 35171d15f78d..e12037a0f2b4 100644 --- a/Documentation/userspace-api/gpio/sysfs.rst +++ b/Documentation/userspace-api/gpio/sysfs.rst @@ -2,18 +2,18 @@ GPIO Sysfs Interface for Userspace ================================== .. warning:: + This API is obsoleted by the chardev.rst and the ABI documentation has + been moved to Documentation/ABI/obsolete/sysfs-gpio. - THIS ABI IS DEPRECATED, THE ABI DOCUMENTATION HAS BEEN MOVED TO - Documentation/ABI/obsolete/sysfs-gpio AND NEW USERSPACE CONSUMERS - ARE SUPPOSED TO USE THE CHARACTER DEVICE ABI. THIS OLD SYSFS ABI WILL - NOT BE DEVELOPED (NO NEW FEATURES), IT WILL JUST BE MAINTAINED. + New developments should use the chardev.rst, and existing developments are + encouraged to migrate as soon as possible, as this API will be removed + in the future. -Refer to the examples in tools/gpio/* for an introduction to the new -character device ABI. Also see the userspace header in -include/uapi/linux/gpio.h + This interface will continue to be maintained for the migration period, + but new features will only be added to the new API. -The deprecated sysfs ABI ------------------------- +The obsolete sysfs ABI +---------------------- Platforms which use the "gpiolib" implementors framework may choose to configure a sysfs user interface to GPIOs. This is different from the debugfs interface, since it provides control over GPIO direction and @@ -33,9 +33,12 @@ userspace GPIO can be used to determine system configuration data that standard kernels won't know about. And for some tasks, simple userspace GPIO drivers could be all that the system really needs. -DO NOT ABUSE SYSFS TO CONTROL HARDWARE THAT HAS PROPER KERNEL DRIVERS. -PLEASE READ THE DOCUMENT AT Documentation/driver-api/gpio/drivers-on-gpio.rst -TO AVOID REINVENTING KERNEL WHEELS IN USERSPACE. I MEAN IT. REALLY. +.. note:: + Do NOT abuse sysfs to control hardware that has proper kernel drivers. + Please read Documentation/driver-api/gpio/drivers-on-gpio.rst + to avoid reinventing kernel wheels in userspace. + + I MEAN IT. REALLY. Paths in Sysfs -------------- From patchwork Mon Jan 15 00:48:44 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Kent Gibson X-Patchwork-Id: 762903 Received: from mail-pf1-f179.google.com (mail-pf1-f179.google.com [209.85.210.179]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 485DD63C5; Mon, 15 Jan 2024 00:50:14 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="b21qzixP" Received: by mail-pf1-f179.google.com with SMTP id d2e1a72fcca58-6d9344f30caso5456384b3a.1; Sun, 14 Jan 2024 16:50:14 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1705279813; x=1705884613; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=MK7KhU/c/OCKeFhc+Alpj9+x/wfFEroXy7/XTlKq6R4=; b=b21qzixPnEPxuTgGlHOk/M7UikDc/qk0LdFosakmyXwWA5jNHnsNz51O2y2J/1aZ+x T39P2zG06RYFHZQFrF7EVPclcRKB5Ik4xrgqT5lNIQ7LuWHU6FCd2hXMgG+YQfTO8wIt CM/QZlptZpMIakZxRMD/lkhZiMXCiHEZyx3me6yfpcszdX3AY5dT3QPnHrShYfzqgMSO faKKX6vCQVOr59aLW/HFwjVyyGqPT+2YiTeIdk8Cdf+8dV80zdxn8xontWdfXisIwkWb Bdd7fGZReOKZLvQ4sjk/5OZ4rl8nyp+Wt7K1qaxo4zSPy/P8Prtfhh0hQqXvZ/6p4hCG oV9Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1705279813; x=1705884613; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=MK7KhU/c/OCKeFhc+Alpj9+x/wfFEroXy7/XTlKq6R4=; b=wkMTuabH1weBj5bk27EfTMR+usI53GyFrkky30kmp0UDhH2xqmJDSjHyhKw/xdbUkX FiexFnMxa3WmECM4VkVSCs99flcbiV0s5P3pr26DEmbRQazTdn76w9aU1OqPXR7FXsaA VZk+JD8wKJlpIi7kVFJXiSIJqUcvlSGgXB6gYp0oLKTV4ug/Uwrn26hQVykKZ23aZX2R sOiBJsJrNQooEST/GgMSf7mFDgz6T9K7aRAS7pVnWB7zQR2Bd4vPN5h0cr/cmCiBaQ6d DBhGSvEHSFr9C7ynOXEtgIdQgHt8dx8+UUtxqteVMH2zy1EJIsKcyObNXDc28Tuo/sKc cmCQ== X-Gm-Message-State: AOJu0YwpMEchxsraXfyQ85uQCsXJGjOH+Co4aze65KVDLWuHtL1pysNP QjiDGtKDTYtktxPKOVEiXpxC/wQGLosoRg== X-Google-Smtp-Source: AGHT+IF1252Hb1TRGhUTV/ms0tdoru/Fxg9mZnjWddthfavflk45lZaqONNEJ1BNDyLNcrh3lAamQQ== X-Received: by 2002:a05:6a00:2282:b0:6d2:74fc:1f1e with SMTP id f2-20020a056a00228200b006d274fc1f1emr5760378pfe.14.1705279812958; Sun, 14 Jan 2024 16:50:12 -0800 (PST) Received: from rigel.home.arpa (60-241-235-125.tpgi.com.au. [60.241.235.125]) by smtp.gmail.com with ESMTPSA id 4-20020aa79204000000b006d999f4a3c0sm6538365pfo.152.2024.01.14.16.50.09 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 14 Jan 2024 16:50:12 -0800 (PST) From: Kent Gibson To: linux-kernel@vger.kernel.org, linux-gpio@vger.kernel.org, linux-doc@vger.kernel.org, brgl@bgdev.pl, linus.walleij@linaro.org, andy@kernel.org, corbet@lwn.net Cc: Kent Gibson Subject: [PATCH v2 6/9] Documentation: gpio: add chardev v1 userspace API documentation Date: Mon, 15 Jan 2024 08:48:44 +0800 Message-Id: <20240115004847.22369-7-warthog618@gmail.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240115004847.22369-1-warthog618@gmail.com> References: <20240115004847.22369-1-warthog618@gmail.com> Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Add documentation for v1 of the GPIO character device userspace API to the obsolete section of both the admin-guide and userspace-api books. Signed-off-by: Kent Gibson --- Documentation/admin-guide/gpio/obsolete.rst | 1 + .../userspace-api/gpio/chardev_v1.rst | 131 ++++++++++++++++++ .../gpio/gpio-get-lineevent-ioctl.rst | 78 +++++++++++ .../gpio/gpio-get-linehandle-ioctl.rst | 86 ++++++++++++ .../gpio/gpio-get-lineinfo-ioctl.rst | 54 ++++++++ .../gpio/gpio-get-lineinfo-unwatch-ioctl.rst | 2 +- .../gpio/gpio-get-lineinfo-watch-ioctl.rst | 74 ++++++++++ .../gpio-handle-get-line-values-ioctl.rst | 56 ++++++++ .../gpio/gpio-handle-set-config-ioctl.rst | 62 +++++++++ .../gpio-handle-set-line-values-ioctl.rst | 48 +++++++ .../gpio/gpio-lineevent-data-read.rst | 84 +++++++++++ .../gpio/gpio-lineinfo-changed-read.rst | 87 ++++++++++++ Documentation/userspace-api/gpio/obsolete.rst | 1 + 13 files changed, 763 insertions(+), 1 deletion(-) create mode 100644 Documentation/userspace-api/gpio/chardev_v1.rst create mode 100644 Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-get-lineinfo-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-get-lineinfo-watch-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst create mode 100644 Documentation/userspace-api/gpio/gpio-lineinfo-changed-read.rst diff --git a/Documentation/admin-guide/gpio/obsolete.rst b/Documentation/admin-guide/gpio/obsolete.rst index dbf88f13c680..5926e5440207 100644 --- a/Documentation/admin-guide/gpio/obsolete.rst +++ b/Documentation/admin-guide/gpio/obsolete.rst @@ -7,5 +7,6 @@ Obsolete GPIO APIs .. toctree:: :maxdepth: 1 + Character Device Userspace API (v1) <../../userspace-api/gpio/chardev_v1> Sysfs Interface <../../userspace-api/gpio/sysfs> diff --git a/Documentation/userspace-api/gpio/chardev_v1.rst b/Documentation/userspace-api/gpio/chardev_v1.rst new file mode 100644 index 000000000000..67124b1d0487 --- /dev/null +++ b/Documentation/userspace-api/gpio/chardev_v1.rst @@ -0,0 +1,131 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================== +GPIO Character Device Userspace API (v1) +======================================== + +.. warning:: + This API is obsoleted by chardev.rst (v2). + + New developments should use the v2 API, and existing developments are + encouraged to migrate as soon as possible, as this API will be removed + in the future. The v2 API is a functional superset of the v1 API so any + v1 call can be directly translated to a v2 equivalent. + + This interface will continue to be maintained for the migration period, + but new features will only be added to the new API. + +First added in 4.8. + +The API is based around three major objects, the :ref:`gpio-v1-chip`, the +:ref:`gpio-v1-line-handle`, and the :ref:`gpio-v1-line-event`. + +Where "line event" is used in this document it refers to the request that can +monitor a line for edge events, not the edge events themselves. + +.. _gpio-v1-chip: + +Chip +==== + +The Chip represents a single GPIO chip and is exposed to userspace using device +files of the form ``/dev/gpiochipX``. + +Each chip supports a number of GPIO lines, +:c:type:`chip.lines`. Lines on the chip are identified by an +``offset`` in the range from 0 to ``chip.lines - 1``, i.e. `[0,chip.lines)`. + +Lines are requested from the chip using either gpio-get-linehandle-ioctl.rst +and the resulting line handle is used to access the GPIO chip's lines, or +gpio-get-lineevent-ioctl.rst and the resulting line event is used to monitor +a GPIO line for edge events. + +Within this documentation, the file descriptor returned by calling `open()` +on the GPIO device file is referred to as ``chip_fd``. + +Operations +---------- + +The following operations may be performed on the chip: + +.. toctree:: + :titlesonly: + + Get Line Handle + Get Line Event + Get Chip Info + Get Line Info + Watch Line Info + Unwatch Line Info + Read Line Info Changed Events + +.. _gpio-v1-line-handle: + +Line Handle +=========== + +Line handles are created by gpio-get-linehandle-ioctl.rst and provide +access to a set of requested lines. The line handle is exposed to userspace +via the anonymous file descriptor returned in +:c:type:`request.fd` by gpio-get-linehandle-ioctl.rst. + +Within this documentation, the line handle file descriptor is referred to +as ``handle_fd``. + +Operations +---------- + +The following operations may be performed on the line handle: + +.. toctree:: + :titlesonly: + + Get Line Values + Set Line Values + Reconfigure Lines + +.. _gpio-v1-line-event: + +Line Event +========== + +Line events are created by gpio-get-lineevent-ioctl.rst and provide +access to a requested line. The line event is exposed to userspace +via the anonymous file descriptor returned in +:c:type:`request.fd` by gpio-get-lineevent-ioctl.rst. + +Within this documentation, the line event file descriptor is referred to +as ``event_fd``. + +Operations +---------- + +The following operations may be performed on the line event: + +.. toctree:: + :titlesonly: + + Get Line Value + Read Line Edge Events + +Types +===== + +This section contains the structs that are referenced by the ABI v1. + +The :c:type:`struct gpiochip_info` is common to ABI v1 and v2. + +.. kernel-doc:: include/uapi/linux/gpio.h + :identifiers: + gpioevent_data + gpioevent_request + gpiohandle_config + gpiohandle_data + gpiohandle_request + gpioline_info + gpioline_info_changed + +.. toctree:: + :hidden: + + error-codes diff --git a/Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst new file mode 100644 index 000000000000..7d0b932925c6 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst @@ -0,0 +1,78 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_GET_LINEEVENT_IOCTL: + +************************ +GPIO_GET_LINEEVENT_IOCTL +************************ + +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-get-line-ioctl.rst. + +Name +==== + +GPIO_GET_LINEEVENT_IOCTL - Request a line with edge detection from the kernel. + +Synopsis +======== + +.. c:macro:: GPIO_GET_LINEEVENT_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_LINEEVENT_IOCTL, struct gpioevent_request *request)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``request`` + The :c:type:`event_request` specifying the line + to request and its configuration. + +Description +=========== + +Request a line with edge detection from the kernel. + +On success, the requesting process is granted exclusive access to the line +value and may receive events when edges are detected on the line, as +described in gpio-lineevent-data-read.rst. + +The state of a line is guaranteed to remain as requested until the returned +file descriptor is closed. Once the file descriptor is closed, the state of +the line becomes uncontrolled from the userspace perspective, and may revert +to its default state. + +Requesting a line already in use is an error (**EBUSY**). + +Closing the ``chip_fd`` has no effect on existing line events. + +Configuration Rules +------------------- + +The following configuration rules apply: + +The line event is requested as an input, so no flags specific to output lines, +``GPIOHANDLE_REQUEST_OUTPUT``, ``GPIOHANDLE_REQUEST_OPEN_DRAIN``, or +``GPIOHANDLE_REQUEST_OPEN_SOURCE``, may be set. + +Only one bias flag, ``GPIOHANDLE_REQUEST_BIAS_xxx``, may be set. +If no bias flags are set then the bias configuration is not changed. + +The edge flags, ``GPIOEVENT_REQUEST_RISING_EDGE`` and +``GPIOEVENT_REQUEST_FALLING_EDGE``, may be combined to detect both rising +and falling edges. + +Requesting an invalid configuration is an error (**EINVAL**). + +Return Value +============ + +On success 0 and the :c:type:`request.fd` contains the file +descriptor for the request. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst new file mode 100644 index 000000000000..c8256afe306e --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst @@ -0,0 +1,86 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_GET_LINEHANDLE_IOCTL: + +************************* +GPIO_GET_LINEHANDLE_IOCTL +************************* + +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-get-line-ioctl.rst. + +Name +==== + +GPIO_GET_LINEHANDLE_IOCTL - Request a line or lines from the kernel. + +Synopsis +======== + +.. c:macro:: GPIO_GET_LINEHANDLE_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_LINEHANDLE_IOCTL, struct gpiohandle_request *request)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``request`` + The :c:type:`handle_request` specifying the lines to + request and their configuration. + +Description +=========== + +Request a line or lines from the kernel. + +While multiple lines may be requested, the same configuration applies to all +lines in the request. + +On success, the requesting process is granted exclusive access to the line +value and write access to the line configuration. + +The state of a line, including the value of output lines, is guaranteed to +remain as requested until the returned file descriptor is closed. Once the +file descriptor is closed, the state of the line becomes uncontrolled from +the userspace perspective, and may revert to its default state. + +Requesting a line already in use is an error (**EBUSY**). + +Closing the ``chip_fd`` has no effect on existing line handles. + +.. _gpio-get-linehandle-config-rules: + +Configuration Rules +------------------- + +The following configuration rules apply: + +The direction flags, ``GPIOHANDLE_REQUEST_INPUT`` and +``GPIOHANDLE_REQUEST_OUTPUT``, cannot be combined. If neither are set then the +only other flag that may be set is ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` and the +line is requested "as-is" to allow reading of the line value without altering +the electrical configuration. + +The drive flags, ``GPIOHANDLE_REQUEST_OPEN_xxx``, require the +``GPIOHANDLE_REQUEST_OUTPUT`` to be set. +Only one drive flag may be set. +If none are set then the line is assumed push-pull. + +Only one bias flag, ``GPIOHANDLE_REQUEST_BIAS_xxx``, may be set, and +it requires a direction flag to also be set. +If no bias flags are set then the bias configuration is not changed. + +Requesting an invalid configuration is an error (**EINVAL**). + +Return Value +============ + +On success 0 and the :c:type:`request.fd` contains the +file descriptor for the request. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-get-lineinfo-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-lineinfo-ioctl.rst new file mode 100644 index 000000000000..c895b8910b25 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-get-lineinfo-ioctl.rst @@ -0,0 +1,54 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_GET_LINEINFO_IOCTL: + +*********************** +GPIO_GET_LINEINFO_IOCTL +*********************** + +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-get-lineinfo-ioctl.rst. + +Name +==== + +GPIO_GET_LINEINFO_IOCTL - Get the publicly available information for a line. + +Synopsis +======== + +.. c:macro:: GPIO_GET_LINEINFO_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_LINEINFO_IOCTL, struct gpioline_info *info)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``info`` + The :c:type:`line_info` to be populated, with the + ``offset`` field set to indicate the line to be collected. + +Description +=========== + +Get the publicly available information for a line. + +This information is available independent of whether the line is in use. + +.. note:: + The line info does not include the line value. + + The line must be requested using gpio-get-linehandle-ioctl.rst or + gpio-get-lineevent-ioctl.rst to access its value. + +Return Value +============ + +On success 0 and ``info`` is populated with the chip info. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst index 2fec6f12e3bf..a82d0161daf8 100644 --- a/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst +++ b/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst @@ -33,7 +33,7 @@ Description Remove the line from the list of lines being watched on this ``chip_fd``. -This is the opposite of gpio-v2-get-lineinfo-watch-ioctl.rst (v2) and +This is the reverse of gpio-v2-get-lineinfo-watch-ioctl.rst (v2) and gpio-get-lineinfo-watch-ioctl.rst (v1). Unwatching a line that is not watched is an error (**EBUSY**). diff --git a/Documentation/userspace-api/gpio/gpio-get-lineinfo-watch-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-lineinfo-watch-ioctl.rst new file mode 100644 index 000000000000..f5c92b69a496 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-get-lineinfo-watch-ioctl.rst @@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_GET_LINEINFO_WATCH_IOCTL: + +***************************** +GPIO_GET_LINEINFO_WATCH_IOCTL +***************************** + +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-get-lineinfo-watch-ioctl.rst. + +Name +==== + +GPIO_GET_LINEINFO_WATCH_IOCTL - Enable watching a line for changes to its +request state and configuration information. + +Synopsis +======== + +.. c:macro:: GPIO_GET_LINEINFO_WATCH_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_LINEINFO_WATCH_IOCTL, struct gpioline_info *info)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``info`` + The :c:type:`line_info` struct to be populated, with + the ``offset`` set to indicate the line to watch + +Description +=========== + +Enable watching a line for changes to its request state and configuration +information. Changes to line info include a line being requested, released +or reconfigured. + +.. note:: + Watching line info is not generally required, and would typically only be + used by a system monitoring component. + + The line info does NOT include the line value. + + The line must be requested using gpio-get-linehandle-ioctl.rst or + gpio-get-lineevent-ioctl.rst to access its value, and the line event can + monitor a line for events using gpio-lineevent-data-read.rst. + +By default all lines are unwatched when the GPIO chip is opened. + +Multiple lines may be watched simultaneously by adding a watch for each. + +Once a watch is set, any changes to line info will generate events which can be +read from the ``chip_fd`` as described in +gpio-lineinfo-changed-read.rst. + +Adding a watch to a line that is already watched is an error (**EBUSY**). + +Watches are specific to the ``chip_fd`` and are independent of watches +on the same GPIO chip opened with a separate call to `open()`. + +First added in 5.7. + +Return Value +============ + +On success 0 and ``info`` is populated with the current line info. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst b/Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst new file mode 100644 index 000000000000..25263b8f0588 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIOHANDLE_GET_LINE_VALUES_IOCTL: + +******************************** +GPIOHANDLE_GET_LINE_VALUES_IOCTL +******************************** +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-line-get-values-ioctl.rst. + +Name +==== + +GPIOHANDLE_GET_LINE_VALUES_IOCTL - Get the values of all requested lines. + +Synopsis +======== + +.. c:macro:: GPIOHANDLE_GET_LINE_VALUES_IOCTL + +``int ioctl(int handle_fd, GPIOHANDLE_GET_LINE_VALUES_IOCTL, struct gpiohandle_data *values)`` + +Arguments +========= + +``handle_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd` by gpio-get-linehandle-ioctl.rst. + +``values`` + The :c:type:`line_values` to be populated. + +Description +=========== + +Get the values of all requested lines. + +The values of both input and output lines may be read. + +For output lines, the value returned is driver and configuration dependent and +may be either the output buffer (the last requested value set) or the input +buffer (the actual level of the line), and depending on the hardware and +configuration these may differ. + +This ioctl can also be used to read the line value for line events, +substituting the ``event_fd`` for the ``handle_fd``. As there is only +one line requested in that case, only the one value is returned in ``values``. + +Return Value +============ + +On success 0 and ``values`` populated with the values read. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst b/Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst new file mode 100644 index 000000000000..8f1e748dccc8 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst @@ -0,0 +1,62 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIOHANDLE_SET_CONFIG_IOCTL: + +*************************** +GPIOHANDLE_SET_CONFIG_IOCTL +*************************** + +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-line-set-config-ioctl.rst. + +Name +==== + +GPIOHANDLE_SET_CONFIG_IOCTL - Update the configuration of previously requested lines. + +Synopsis +======== + +.. c:macro:: GPIOHANDLE_SET_CONFIG_IOCTL + +``int ioctl(int handle_fd, GPIOHANDLE_SET_CONFIG_IOCTL, struct gpiohandle_config *config)`` + +Arguments +========= + +``handle_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd` by gpio-get-linehandle-ioctl.rst. + +``config`` + The new :c:type:`configuration` to apply to the + requested lines. + +Description +=========== + +Update the configuration of previously requested lines, without releasing the +line or introducing potential glitches. + +The configuration applies to all requested lines. + +The same :ref:`gpio-get-linehandle-config-rules` that apply when requesting the +lines also apply when updating the line configuration. + +The motivating use case for this command is changing direction of +bi-directional lines between input and output, but it may be used more +generally move lines seamlessly from one configuration state to another. + +To only change the value of output lines, use +gpio-handle-set-line-values-ioctl.rst. + +First added in 5.5. + +Return Value +============ + +On success 0. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst b/Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst new file mode 100644 index 000000000000..0aa05e623a6c --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_HANDLE_SET_LINE_VALUES_IOCTL: + +********************************* +GPIO_HANDLE_SET_LINE_VALUES_IOCTL +********************************* +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-line-set-values-ioctl.rst. + +Name +==== + +GPIO_HANDLE_SET_LINE_VALUES_IOCTL - Set the values of all requested output lines. + +Synopsis +======== + +.. c:macro:: GPIO_HANDLE_SET_LINE_VALUES_IOCTL + +``int ioctl(int handle_fd, GPIO_HANDLE_SET_LINE_VALUES_IOCTL, struct gpiohandle_data *values)`` + +Arguments +========= + +``handle_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd` by gpio-get-linehandle-ioctl.rst. + +``values`` + The :c:type:`line_values` to set. + +Description +=========== + +Set the values of all requested output lines. + +Only the values of output lines may be set. +Attempting to set the value of input lines is an error (**EPERM**). + +Return Value +============ + +On success 0. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst b/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst new file mode 100644 index 000000000000..68b8d4f9f604 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst @@ -0,0 +1,84 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_LINEEVENT_DATA_READ: + +************************ +GPIO_LINEEVENT_DATA_READ +************************ + +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-line-event-read.rst. + +Name +==== + +GPIO_LINEEVENT_DATA_READ - Read edge detection events from a line event. + +Synopsis +======== + +``int read(int event_fd, void *buf, size_t count)`` + +Arguments +========= + +``event_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd` by gpio-get-lineevent-ioctl.rst. + +``buf`` + The buffer to contain the :c:type:`events`. + +``count`` + The number of bytes available in ``buf``, which must be at + least the size of a :c:type:`gpioevent_data`. + +Description +=========== + +Read edge detection events for a line from a line event. + +Edge 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. + +The 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()`. + +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. + +Events read from the buffer are always in the same order that they were +detected by the kernel. + +The size of the kernel event buffer is fixed at 16 events. + +The 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. + +To 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``). + +The `read()` will block if no event is available and the ``event_fd`` has not +been set **O_NONBLOCK**. + +The presence of an event can be tested for by checking that the ``event_fd`` is +readable using `poll()` or an equivalent. + +Return Value +============ + +On success the number of bytes read, which will be a multiple of the size of +a :c:type:`gpio_lineevent_data` event. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-lineinfo-changed-read.rst b/Documentation/userspace-api/gpio/gpio-lineinfo-changed-read.rst new file mode 100644 index 000000000000..c4f5e1787a9d --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-lineinfo-changed-read.rst @@ -0,0 +1,87 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_LINEINFO_CHANGED_READ: + +************************** +GPIO_LINEINFO_CHANGED_READ +************************** + +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-lineinfo-changed-read.rst. + +Name +==== + +GPIO_LINEINFO_CHANGED_READ - Read line info change events for watched lines +from the chip. + +Synopsis +======== + +``int read(int chip_fd, void *buf, size_t count)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``buf`` + The buffer to contain the :c:type:`events`. + +``count`` + The number of bytes available in ``buf``, which must be at least the size + of a :c:type:`gpioline_info_changed` event. + +Description +=========== + +Read line info change events for watched lines from the chip. + +.. note:: + Monitoring line info changes is not generally required, and would typically + only be performed by a system monitoring component. + + These events relate to changes in a line's request state or configuration, + not its value. Use gpio-lineevent-data-read.rst to receive events when a + line changes value. + +A line must be watched using gpio-get-lineinfo-watch-ioctl.rst to generate +info changed events. Subsequently, a request, release, or reconfiguration +of the line will generate an info changed event. + +The kernel timestamps events when they occur and stores them in a buffer +from where they can be read by userspace at its convenience using `read()`. + +The size of the kernel event buffer is fixed at 32 events per ``chip_fd``. + +The 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. + +Events read from the buffer are always in the same order that they were +detected by the kernel, including when multiple lines are being monitored by +the one ``chip_fd``. + +To 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``). + +A `read()` will block if no event is available and the ``chip_fd`` has not +been set **O_NONBLOCK**. + +The presence of an event can be tested for by checking that the ``chip_fd`` is +readable using `poll()` or an equivalent. + +First added in 5.7. + +Return Value +============ + +On success the number of bytes read, which will be a multiple of the size of +a :c:type:`gpioline_info_changed` event. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/obsolete.rst b/Documentation/userspace-api/gpio/obsolete.rst index c27bd6014a3d..c42538b44ec8 100644 --- a/Documentation/userspace-api/gpio/obsolete.rst +++ b/Documentation/userspace-api/gpio/obsolete.rst @@ -7,4 +7,5 @@ Obsolete GPIO Userspace APIs .. toctree:: :maxdepth: 1 + Character Device Userspace API (v1) Sysfs Interface From patchwork Mon Jan 15 00:48:45 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Kent Gibson X-Patchwork-Id: 763180 Received: from mail-pg1-f172.google.com (mail-pg1-f172.google.com [209.85.215.172]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id A24D546BF; Mon, 15 Jan 2024 00:50:23 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="Gyj7uimZ" Received: by mail-pg1-f172.google.com with SMTP id 41be03b00d2f7-5cd8667c59eso5467457a12.2; Sun, 14 Jan 2024 16:50:23 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1705279823; x=1705884623; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=ub9tHuBOLopgebfbkbwN/PTiEyrZi756Wca/FmKuvAc=; b=Gyj7uimZ78FlwUQB4Yps6xZH1P1VBheXajUsRptvd+Vi+eFZ7kvZpv89HluoqwESt1 j1bb9trpah6Rw9VDrWQ0i67IqsG62LNp83u4/qAhIxH57wZuW3chpdffvrzzNgSNdQ5W hPoScJgZK59XjcPHpuIgqcbrX2JngbzvkL1bfBN0FiQG4Pa22Q2lRC4SxrSCIf6LwBjH HP3Nm85riPXoN7DShCv/qPVzRgNqRcZPEdjCFkOWzcABSxSgpl83NXvhjM2cLJPHwfnU BFrPjSQw5AQ9wjSG0zuVU8IU+U6V3I3FUFokmiwsu1PJChIrhKg6/hCkKn7kicq+lJGZ gCrw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1705279823; x=1705884623; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=ub9tHuBOLopgebfbkbwN/PTiEyrZi756Wca/FmKuvAc=; b=ghzvQ++pl6rmAA+ZV9EcFEsWQoXqcrIQM0VHG3+hGca4XjS1LItke/ZasYF6BV2GDz 7ydnIISIRAggxgCZPCMV7PjyhZhyxO+6mrFY4uuGHVSd/hAA2BfjmJM64gHIEoUS2ojS Z074KcxPhIxHzMZFqw2qaclTmok+lFBkDnwIvuCa7vsBzOL1lqsMRZJ8x5goYkCdguV/ nhRduwBNGbJoxDYx5WXC2j4532edzIx9KjXbn6BgUIOg7fwV+iJMF0bNBuB4NecoKsVi mOcIjlUoa+ZLcnrpQFWfLYb08DBvQZz7iLWyKIVro5ZIA6hL2ReN3fjEqK70arnEkc1/ nvmQ== X-Gm-Message-State: AOJu0YxKEurPqUNkxXV1AQpKujydqn1N8UhqAceWOPCZOiV6ag0xaMJ/ WZuqjjODHZkwiBLAhhxUyTvr1oGUlA3wzQ== X-Google-Smtp-Source: AGHT+IGseLMXKhWLBUojJXb7wJXqWDNudH9a6HbzGocmaTP7IA2BkZlI+U55w8xqjAhTbVdENbpQtA== X-Received: by 2002:a05:6a20:e11b:b0:19a:4073:e178 with SMTP id kr27-20020a056a20e11b00b0019a4073e178mr5829117pzb.25.1705279822938; Sun, 14 Jan 2024 16:50:22 -0800 (PST) Received: from rigel.home.arpa (60-241-235-125.tpgi.com.au. [60.241.235.125]) by smtp.gmail.com with ESMTPSA id 4-20020aa79204000000b006d999f4a3c0sm6538365pfo.152.2024.01.14.16.50.19 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 14 Jan 2024 16:50:22 -0800 (PST) From: Kent Gibson To: linux-kernel@vger.kernel.org, linux-gpio@vger.kernel.org, linux-doc@vger.kernel.org, brgl@bgdev.pl, linus.walleij@linaro.org, andy@kernel.org, corbet@lwn.net Cc: Kent Gibson Subject: [PATCH v2 7/9] Documentation: gpio: capitalize GPIO in index title Date: Mon, 15 Jan 2024 08:48:45 +0800 Message-Id: <20240115004847.22369-8-warthog618@gmail.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240115004847.22369-1-warthog618@gmail.com> References: <20240115004847.22369-1-warthog618@gmail.com> Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Capitalise the title of the GPIO documentation page to match other subsystems. Signed-off-by: Kent Gibson --- Documentation/admin-guide/gpio/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst index 3ac3aa15fa8b..3f6d5a76702b 100644 --- a/Documentation/admin-guide/gpio/index.rst +++ b/Documentation/admin-guide/gpio/index.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 ==== -gpio +GPIO ==== .. toctree:: From patchwork Mon Jan 15 00:48:46 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Kent Gibson X-Patchwork-Id: 762902 Received: from mail-ot1-f48.google.com (mail-ot1-f48.google.com [209.85.210.48]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 77CDF17E1; Mon, 15 Jan 2024 00:50:39 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="fI47bTdg" Received: by mail-ot1-f48.google.com with SMTP id 46e09a7af769-6e0a64d94d1so1018254a34.3; Sun, 14 Jan 2024 16:50:39 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1705279838; x=1705884638; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=ztYy0pG5mb/EUI1krEp4S/p84wNzOo5hR+tihGh7i4s=; b=fI47bTdg2z5P/ltzoEk0O79OgILimADacLnLNLJZ1/vZmqel++2SzOKLJc0z3xIgYc mn4SmVMDr7kFcGiGfTJFq0OMXmZL5FhHZbpPF/T6bgYPnJ0iYkC/JkWQnlgvEMtgHCGU 1+vlcqV2hm+KE9JQVbvmF1/S4HPJmP3kpp2qnmFWYnPZGyf4Io7L9qInqfG+nB7dZAZg 8c4KXwotq2sRps94y3lrHMtKiYuJdYc132R0aWQXRLWTZ0Q/UIpTFLxpfrt6QpvFDxT8 tYht2n/dICwHub8IIbrPL8uRJbkECfz1r8GUI8+b95I/HXFUq4nxBBcNVm/qvk3fNoPD fjzQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1705279838; x=1705884638; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=ztYy0pG5mb/EUI1krEp4S/p84wNzOo5hR+tihGh7i4s=; b=lN7qxxi5olOvL+HMAQ1N2rbia/tsWs0aEcs5oQ19jctYng3G/3cXsUdaGHvb+cdrZw NKPv4ErFJTjEB8rY7y+F0FDVCv1GMBEKH9BILNFaPtydxCzBoI+oMz11BrQfVKmPnLDD fKaVl79U0J1O5kbEIng4t5LhMoX25iS5FQyj+svIKXAMBYxbLfERaD5ULuP/ydPNpnhC U1KGfwOZNzTHaU97z6ZStGc3nh3+tv/Hz8I15gNWfE9/9rFmoVN82ntItK5c3IfMdr9s 1cGltdtV2agjo1i/+SVXWjrOKh7wlKnt3BFnDbHeKm45kfEQj+q8aDaA+cuuBLFgsEBA qC9Q== X-Gm-Message-State: AOJu0YxiB944/qSKDzXGn0KbC5lZMZ08HpVkS7EflSvpaoPOBt5SAjcP 02/obIdd5iaXfykSLz1yc9dvQU2T2+eW1Q== X-Google-Smtp-Source: AGHT+IH7WSB22r8uoRQvcq4B6pj5YoOyXfaHdex0itxKWmpW2sku/C5pcVcaaHBnbyZkJAvcVnWICg== X-Received: by 2002:a05:6830:1e4f:b0:6db:f6c5:e8d9 with SMTP id e15-20020a0568301e4f00b006dbf6c5e8d9mr4141813otj.17.1705279838372; Sun, 14 Jan 2024 16:50:38 -0800 (PST) Received: from rigel.home.arpa (60-241-235-125.tpgi.com.au. [60.241.235.125]) by smtp.gmail.com with ESMTPSA id 4-20020aa79204000000b006d999f4a3c0sm6538365pfo.152.2024.01.14.16.50.34 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 14 Jan 2024 16:50:38 -0800 (PST) From: Kent Gibson To: linux-kernel@vger.kernel.org, linux-gpio@vger.kernel.org, linux-doc@vger.kernel.org, brgl@bgdev.pl, linus.walleij@linaro.org, andy@kernel.org, corbet@lwn.net Cc: Kent Gibson Subject: [PATCH v2 8/9] Documentation: gpio: document gpio-mockup as obsoleted by gpio-sim Date: Mon, 15 Jan 2024 08:48:46 +0800 Message-Id: <20240115004847.22369-9-warthog618@gmail.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240115004847.22369-1-warthog618@gmail.com> References: <20240115004847.22369-1-warthog618@gmail.com> Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Update the gpio-mockup documentation to note that is has been obsoleted by the gpio-sim. Signed-off-by: Kent Gibson --- Documentation/admin-guide/gpio/gpio-mockup.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Documentation/admin-guide/gpio/gpio-mockup.rst b/Documentation/admin-guide/gpio/gpio-mockup.rst index 493071da1738..d6e7438a7550 100644 --- a/Documentation/admin-guide/gpio/gpio-mockup.rst +++ b/Documentation/admin-guide/gpio/gpio-mockup.rst @@ -3,6 +3,14 @@ GPIO Testing Driver =================== +.. note:: + + This module has been obsoleted by the more flexible gpio-sim.rst. + New developments should use that API and existing developments are + encouraged to migrate as soon as possible. + This module will continue to be maintained but no new features will be + added. + The GPIO Testing Driver (gpio-mockup) provides a way to create simulated GPIO chips for testing purposes. The lines exposed by these chips can be accessed using the standard GPIO character device interface as well as manipulated From patchwork Mon Jan 15 00:48:47 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Kent Gibson X-Patchwork-Id: 763179 Received: from mail-oi1-f171.google.com (mail-oi1-f171.google.com [209.85.167.171]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 96A436AA4; Mon, 15 Jan 2024 00:50:49 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="kQgjgKcb" Received: by mail-oi1-f171.google.com with SMTP id 5614622812f47-3bd7c15a745so303924b6e.2; Sun, 14 Jan 2024 16:50:49 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1705279848; x=1705884648; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=2eW8RN7A3SvV8/GoRhnzwM9t4e+MIpt3wvyYqQPSvIo=; b=kQgjgKcbZOW517br8OlFUZ+UCr0vTJQD0pE9j+HNfEoPovv/XzImM0rHMvJoq65Mxl w28V8k2/hFg6AwRmHZRqdrft/ardtma8FdnFexfYivkkwCLjjrmkSGI/xfpliX7nBNV5 JrzWiqpTwd8NdInJOkM5wb45UvykAuGRVsJFLQPB68/YztzSH017QKkzBwQJpIKQPndY 579FMjryprGr/v3mUWJy0qFv1QH0TfT4QsA7B/fhgRk/XuVvHDtry/KC0QCTxsFSwYjQ /YzjZ7ZKx9VdMlw+41ufMpNZ5bD1mbjsMp6EitTV/CLWkQxC0EDu9fDqli+o64SiGwDr fR1g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1705279848; x=1705884648; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=2eW8RN7A3SvV8/GoRhnzwM9t4e+MIpt3wvyYqQPSvIo=; b=do/pG018a1lnM3XSRAnfUjjyDyBCE9yAWlgnsM3PcpSoGqUgPa/NDQQPSFmeb5EnbH 8xjWnwH867Al26bihwgmrNNfe0RUmkhT0Mm3Q6BXs2a9No7EWmbFqf/g9WIpU/Sqrh92 y7JIgHxXpk1xzEUXfLiCrvxdfWspqVFuP81fH+eklWX5JW7jZ3UoaNp5Y2+o9efIGbnG wRNIH7wBjR0Uh5huf9p/smTC5y3bZ60KX29Wu2cQ4Vq8IqtXt7YbXttGyfAkIHdPp5iI xjcrr0+mV97S/nHrPJ+obv4epqxQVe9IhR+Uamwvvj/Ty42I0MPN0LgZbZnW/voZiy8C z+tA== X-Gm-Message-State: AOJu0Yx0VJS/kA1ZEvYrmK0/oJyS/vTPiSOYmkqMyS+7vIZuHly6UTQX L6WFHFchjm+qWAWYKPGufur4TQLvU6g3Ig== X-Google-Smtp-Source: AGHT+IH64aw0gyf05YyzW2NTTWATWT0U5XUetej+yejvQN2zs/duC1Ed49DUXWUK6dql2zMKfayPqA== X-Received: by 2002:a05:6808:150c:b0:3bd:46b6:45b with SMTP id u12-20020a056808150c00b003bd46b6045bmr6285952oiw.0.1705279848550; Sun, 14 Jan 2024 16:50:48 -0800 (PST) Received: from rigel.home.arpa (60-241-235-125.tpgi.com.au. [60.241.235.125]) by smtp.gmail.com with ESMTPSA id 4-20020aa79204000000b006d999f4a3c0sm6538365pfo.152.2024.01.14.16.50.45 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 14 Jan 2024 16:50:48 -0800 (PST) From: Kent Gibson To: linux-kernel@vger.kernel.org, linux-gpio@vger.kernel.org, linux-doc@vger.kernel.org, brgl@bgdev.pl, linus.walleij@linaro.org, andy@kernel.org, corbet@lwn.net Cc: Kent Gibson Subject: [PATCH v2 9/9] Documentation: gpio: move gpio-mockup into obsolete section Date: Mon, 15 Jan 2024 08:48:47 +0800 Message-Id: <20240115004847.22369-10-warthog618@gmail.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240115004847.22369-1-warthog618@gmail.com> References: <20240115004847.22369-1-warthog618@gmail.com> Precedence: bulk X-Mailing-List: linux-gpio@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 The gpio-mockup has been obsoleted by the gpio-sim, so relocate its documentation into the obsolete section of the admin-guide book. Signed-off-by: Kent Gibson --- Documentation/admin-guide/gpio/index.rst | 1 - Documentation/admin-guide/gpio/obsolete.rst | 1 + 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst index 3f6d5a76702b..460afd29617e 100644 --- a/Documentation/admin-guide/gpio/index.rst +++ b/Documentation/admin-guide/gpio/index.rst @@ -9,7 +9,6 @@ GPIO Character Device Userspace API <../../userspace-api/gpio/chardev> gpio-aggregator - gpio-mockup gpio-sim Obsolete APIs diff --git a/Documentation/admin-guide/gpio/obsolete.rst b/Documentation/admin-guide/gpio/obsolete.rst index 5926e5440207..5adbff02d61f 100644 --- a/Documentation/admin-guide/gpio/obsolete.rst +++ b/Documentation/admin-guide/gpio/obsolete.rst @@ -9,4 +9,5 @@ Obsolete GPIO APIs Character Device Userspace API (v1) <../../userspace-api/gpio/chardev_v1> Sysfs Interface <../../userspace-api/gpio/sysfs> + Mockup Testing Module