From nobody Thu Dec 25 16:09:51 2025 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-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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-ioct= l.rst create mode 100644 Documentation/userspace-api/gpio/gpio-get-lineinfo-unwa= tch-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-i= octl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-w= atch-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-event-rea= d.rst create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-get-value= s-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-set-confi= g-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-set-value= s-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-v2-lineinfo-chang= ed-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 =20 + Character Device Userspace API <../../userspace-api/gpio/chardev> gpio-aggregator sysfs gpio-mockup diff --git a/Documentation/userspace-api/gpio/chardev.rst b/Documentation/u= serspace-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 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +GPIO Character Device Userspace API +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 existi= ng + kernel driver is sure to provide a superior solution to bitbashing + from userspace. + + Read Documentation/driver-api/gpio/drivers-on-gpio.rst to avoid reinven= ting + 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 +=3D=3D=3D=3D + +The Chip represents a single GPIO chip and is exposed to userspace using d= evice +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 usersp= ace +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 +=3D=3D=3D=3D=3D + +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/Documentati= on/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 n= ot + be retried without performing another action to fix the problem + first. + + - - ``EFAULT`` + + - There was a failure while copying data from/to userspace, probab= ly + 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 communicat= ing + 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 +=3D=3D=3D=3D + +GPIO_GET_CHIPINFO_IOCTL - Get the publicly available information for a chi= p. + +Synopsis +=3D=3D=3D=3D=3D=3D=3D=3D + +.. c:macro:: GPIO_GET_CHIPINFO_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_CHIPINFO_IOCTL, struct gpiochip_info *in= fo)`` + +Arguments +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``info`` + The :c:type:`chip_info` to be populated. + +Description +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Gets the publicly available information for a particular GPIO chip. + +Return Value +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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-ioc= tl.rst b/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.r= st 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 +=3D=3D=3D=3D + +GPIO_GET_LINEINFO_UNWATCH_IOCTL - Disable watching a line for changes to i= ts +requested state and configuration information. + +Synopsis +=3D=3D=3D=3D=3D=3D=3D=3D + +.. c:macro:: GPIO_GET_LINEINFO_UNWATCH_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_LINEINFO_UNWATCH_IOCTL, u32 *offset)`` + +Arguments +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``offset`` + The offset of the line to no longer watch. + +Description +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D + +GPIO_V2_GET_LINE_IOCTL - Request a line or lines from the kernel. + +Synopsis +=3D=3D=3D=3D=3D=3D=3D=3D + +.. c:macro:: GPIO_V2_GET_LINE_IOCTL + +``int ioctl(int chip_fd, GPIO_V2_GET_LINE_IOCTL, struct gpio_v2_line_reque= st *request)`` + +Arguments +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 r= ising +and falling edges. + +Only one event clock flag, ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_xxx``, may be s= et. +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, deboun= ce +applies to both the values returned by gpio-v2-line-get-values-ioctl.rst a= nd +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +On success 0 and the :c:type:`request.fd` contains t= he +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.rs= t 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 +=3D=3D=3D=3D + +GPIO_V2_GET_LINEINFO_IOCTL - Get the publicly available information for a = line. + +Synopsis +=3D=3D=3D=3D=3D=3D=3D=3D + +.. c:macro:: GPIO_V2_GET_LINEINFO_IOCTL + +``int ioctl(int chip_fd, GPIO_V2_GET_LINEINFO_IOCTL, struct gpio_v2_line_i= nfo *info)`` + +Arguments +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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-io= ctl.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 +=3D=3D=3D=3D + +GPIO_V2_GET_LINEINFO_WATCH_IOCTL - Enable watching a line for changes to i= ts +request state and configuration information. + +Synopsis +=3D=3D=3D=3D=3D=3D=3D=3D + +.. 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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 c= an 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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D + +GPIO_V2_LINE_EVENT_READ - Read edge detection events for lines from a requ= est. + +Synopsis +=3D=3D=3D=3D=3D=3D=3D=3D + +``int read(int req_fd, void *buf, size_t count)`` + +Arguments +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``req_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd` by gpio-v2-get-line-ioctl.r= st. + +``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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 the= ir +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 re= ad +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D + +GPIO_V2_LINE_GET_VALUES_IOCTL - Get the values of requested lines. + +Synopsis +=3D=3D=3D=3D=3D=3D=3D=3D + +.. 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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``req_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd` by gpio-v2-get-line-ioctl.r= st. + +``values`` + The :c:type:`line_values` to get with the ``mask`= ` set + to indicate the subset of requested lines to get. + +Description +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D + +GPIO_V2_LINE_SET_CONFIG_IOCTL - Update the configuration of previously req= uested lines. + +Synopsis +=3D=3D=3D=3D=3D=3D=3D=3D + +.. 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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``req_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd` by gpio-v2-get-line-ioctl.r= st. + +``config`` + The new :c:type:`configuration` to apply to the + requested lines. + +Description +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 line= s. + +The same :ref:`gpio-v2-get-line-config-rules` that apply when requesting t= he 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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D + +GPIO_V2_LINE_SET_VALUES_IOCTL - Set the values of requested output lines. + +Synopsis +=3D=3D=3D=3D=3D=3D=3D=3D + +.. 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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``req_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd` by gpio-v2-get-line-ioctl.r= st. + +``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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D + +GPIO_V2_LINEINFO_CHANGED_READ - Read line info changed events for watched +lines from the chip. + +Synopsis +=3D=3D=3D=3D=3D=3D=3D=3D + +``int read(int chip_fd, void *buf, size_t count)`` + +Arguments +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``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 s= ize + of a :c:type:`gpio_v2_line_info_changed` event. + +Description +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Read line info changed events for watched lines from the chip. + +.. note:: + Monitoring line info changes is not generally required, and would typi= cally + only be performed by a system monitoring component. + + These events relate to changes in a line's request state or configurat= ion, + 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 gener= ate +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 re= ad +by userspace. If an overflow occurs then the most recent event is discarde= d. +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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/use= rspace-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 + +=3D=3D=3D=3D +GPIO +=3D=3D=3D=3D + +.. toctree:: + :maxdepth: 1 + + Character Device Userspace API + +.. only:: subproject and html + + Indices + =3D=3D=3D=3D=3D=3D=3D + + * :ref:`genindex` diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspac= e-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 --=20 2.39.2 From nobody Thu Dec 25 16:09:51 2025 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-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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/testin= g/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. =20 - 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. =20 The following file operations are supported: =20 @@ -17,8 +18,8 @@ Description: ioctl(2) Initiate various actions. =20 - 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. =20 close(2) Stops and free up the I/O contexts that was associated --=20 2.39.2 From nobody Thu Dec 25 16:09:51 2025 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-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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/obso= lete/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) =20 - 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. --=20 2.39.2 From nobody Thu Dec 25 16:09:51 2025 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-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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 =3D> 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 =3D> 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 =20 Character Device Userspace API <../../userspace-api/gpio/chardev> gpio-aggregator - sysfs gpio-mockup gpio-sim + Obsolete APIs =20 .. only:: subproject and html =20 diff --git a/Documentation/admin-guide/gpio/obsolete.rst b/Documentation/ad= min-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 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Obsolete GPIO APIs +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. toctree:: + :maxdepth: 1 + + Sysfs Interface <../../userspace-api/gpio/sysfs> + diff --git a/Documentation/userspace-api/gpio/index.rst b/Documentation/use= rspace-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 =20 Character Device Userspace API + Obsolete Userspace APIs =20 .. only:: subproject and html =20 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 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D +Obsolete GPIO Userspace APIs +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D + +.. toctree:: + :maxdepth: 1 + + Sysfs Interface diff --git a/Documentation/admin-guide/gpio/sysfs.rst b/Documentation/users= pace-api/gpio/sysfs.rst similarity index 100% rename from Documentation/admin-guide/gpio/sysfs.rst rename to Documentation/userspace-api/gpio/sysfs.rst --=20 2.39.2 From nobody Thu Dec 25 16:09:51 2025 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-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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/use= rspace-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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 .. warning:: + This API is obsoleted by the chardev.rst and the ABI documentation has + been moved to Documentation/ABI/obsolete/sysfs-gpio. =20 - 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. =20 -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. =20 -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 configura= tion data that standard kernels won't know about. And for some tasks, simple userspace GPIO drivers could be all that the system really needs. =20 -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. =20 Paths in Sysfs -------------- --=20 2.39.2 From nobody Thu Dec 25 16:09:51 2025 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-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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-ioc= tl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-get-linehandle-io= ctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-get-lineinfo-ioct= l.rst create mode 100644 Documentation/userspace-api/gpio/gpio-get-lineinfo-watc= h-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-handle-get-line-v= alues-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-v= alues-ioctl.rst create mode 100644 Documentation/userspace-api/gpio/gpio-lineevent-data-re= ad.rst create mode 100644 Documentation/userspace-api/gpio/gpio-lineinfo-changed-= read.rst diff --git a/Documentation/admin-guide/gpio/obsolete.rst b/Documentation/ad= min-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 =20 + Character Device Userspace API (v1) <../../userspace-api/gpio/chardev_= v1> Sysfs Interface <../../userspace-api/gpio/sysfs> =20 diff --git a/Documentation/userspace-api/gpio/chardev_v1.rst b/Documentatio= n/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 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +GPIO Character Device Userspace API (v1) +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. 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 +=3D=3D=3D=3D + +The Chip represents a single GPIO chip and is exposed to userspace using d= evice +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.r= st +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 monit= or +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 userspa= ce +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D + +GPIO_GET_LINEEVENT_IOCTL - Request a line with edge detection from the ker= nel. + +Synopsis +=3D=3D=3D=3D=3D=3D=3D=3D + +.. c:macro:: GPIO_GET_LINEEVENT_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_LINEEVENT_IOCTL, struct gpioevent_reques= t *request)`` + +Arguments +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 reve= rt +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 li= nes, +``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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D + +GPIO_GET_LINEHANDLE_IOCTL - Request a line or lines from the kernel. + +Synopsis +=3D=3D=3D=3D=3D=3D=3D=3D + +.. c:macro:: GPIO_GET_LINEHANDLE_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_LINEHANDLE_IOCTL, struct gpiohandle_requ= est *request)`` + +Arguments +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Request a line or lines from the kernel. + +While multiple lines may be requested, the same configuration applies to a= ll +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 t= he +line is requested "as-is" to allow reading of the line value without alter= ing +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D + +GPIO_GET_LINEINFO_IOCTL - Get the publicly available information for a lin= e. + +Synopsis +=3D=3D=3D=3D=3D=3D=3D=3D + +.. c:macro:: GPIO_GET_LINEINFO_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_LINEINFO_IOCTL, struct gpioline_info *in= fo)`` + +Arguments +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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-ioc= tl.rst b/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.r= st 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 =20 Remove the line from the list of lines being watched on this ``chip_fd``. =20 -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). =20 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 +=3D=3D=3D=3D + +GPIO_GET_LINEINFO_WATCH_IOCTL - Enable watching a line for changes to its +request state and configuration information. + +Synopsis +=3D=3D=3D=3D=3D=3D=3D=3D + +.. c:macro:: GPIO_GET_LINEINFO_WATCH_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_LINEINFO_WATCH_IOCTL, struct gpioline_in= fo *info)`` + +Arguments +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 c= an + 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 c= an 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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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-i= octl.rst b/Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioc= tl.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 +=3D=3D=3D=3D + +GPIOHANDLE_GET_LINE_VALUES_IOCTL - Get the values of all requested lines. + +Synopsis +=3D=3D=3D=3D=3D=3D=3D=3D + +.. c:macro:: GPIOHANDLE_GET_LINE_VALUES_IOCTL + +``int ioctl(int handle_fd, GPIOHANDLE_GET_LINE_VALUES_IOCTL, struct gpioha= ndle_data *values)`` + +Arguments +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 ``value= s``. + +Return Value +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D + +GPIOHANDLE_SET_CONFIG_IOCTL - Update the configuration of previously reque= sted lines. + +Synopsis +=3D=3D=3D=3D=3D=3D=3D=3D + +.. c:macro:: GPIOHANDLE_SET_CONFIG_IOCTL + +``int ioctl(int handle_fd, GPIOHANDLE_SET_CONFIG_IOCTL, struct gpiohandle_= config *config)`` + +Arguments +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 requestin= g 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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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-i= octl.rst b/Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioc= tl.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 +=3D=3D=3D=3D + +GPIO_HANDLE_SET_LINE_VALUES_IOCTL - Set the values of all requested output= lines. + +Synopsis +=3D=3D=3D=3D=3D=3D=3D=3D + +.. c:macro:: GPIO_HANDLE_SET_LINE_VALUES_IOCTL + +``int ioctl(int handle_fd, GPIO_HANDLE_SET_LINE_VALUES_IOCTL, struct gpioh= andle_data *values)`` + +Arguments +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D + +GPIO_LINEEVENT_DATA_READ - Read edge detection events from a line event. + +Synopsis +=3D=3D=3D=3D=3D=3D=3D=3D + +``int read(int event_fd, void *buf, size_t count)`` + +Arguments +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``event_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd` by gpio-get-lineevent-ioctl.rs= t. + +``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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 the= ir +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 ke= rnel +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 re= ad +by userspace. If an overflow occurs then the most recent event is discarde= d. +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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.rs= t 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 +=3D=3D=3D=3D + +GPIO_LINEINFO_CHANGED_READ - Read line info change events for watched lines +from the chip. + +Synopsis +=3D=3D=3D=3D=3D=3D=3D=3D + +``int read(int chip_fd, void *buf, size_t count)`` + +Arguments +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +``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 s= ize + of a :c:type:`gpioline_info_changed` event. + +Description +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Read line info change events for watched lines from the chip. + +.. note:: + Monitoring line info changes is not generally required, and would typi= cally + only be performed by a system monitoring component. + + These events relate to changes in a line's request state or configurat= ion, + 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 re= ad +by userspace. If an overflow occurs then the most recent event is discarde= d. +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 =20 + Character Device Userspace API (v1) Sysfs Interface --=20 2.39.2 From nobody Thu Dec 25 16:09:51 2025 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-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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 =20 =3D=3D=3D=3D -gpio +GPIO =3D=3D=3D=3D =20 .. toctree:: --=20 2.39.2 From nobody Thu Dec 25 16:09:51 2025 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-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 +.. 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 G= PIO chips for testing purposes. The lines exposed by these chips can be access= ed using the standard GPIO character device interface as well as manipulated --=20 2.39.2 From nobody Thu Dec 25 16:09:51 2025 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-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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 =20 Character Device Userspace API <../../userspace-api/gpio/chardev> gpio-aggregator - gpio-mockup gpio-sim Obsolete APIs =20 diff --git a/Documentation/admin-guide/gpio/obsolete.rst b/Documentation/ad= min-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 =20 Character Device Userspace API (v1) <../../userspace-api/gpio/chardev_= v1> Sysfs Interface <../../userspace-api/gpio/sysfs> + Mockup Testing Module =20 --=20 2.39.2