From nobody Fri Dec 26 05:29:08 2025 Received: from mail-pf1-f169.google.com (mail-pf1-f169.google.com [209.85.210.169]) (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 2B64539843; Tue, 9 Jan 2024 14:00:25 +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="YmuXzIlk" Received: by mail-pf1-f169.google.com with SMTP id d2e1a72fcca58-6d9bc8939d0so1450317b3a.0; Tue, 09 Jan 2024 06:00:25 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1704808825; x=1705413625; 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=wPj1JmbLmjHtnqKv3oV9vKUnkqBzc+Wz4DzteIaT/Hs=; b=YmuXzIlkJBlNN2GZBPLHhiyAATaSbN2grn6dlWm3QBeC43IoCMcw7oIb4CsYgxWYTf Ofw7jWJtj/3TIfHIn3M8ikJ41UHDENh9VaSs9Eh8Pmbn6ghfy2F8cEslnAopoC3qszUy jxqzeNMfL4C6EMA2hBwNS+oR0iDygW7VTwPudVkYBUcG5HsrRs1+0BY1HnT2D+wqDwGj LsiZT3CBXkYDiN4q5H1zMCfsKndu26DyZS+gAD4TkL3p9VSYIwNgtnNH9odFIFyfRrH1 V/ahim9O1slHiX2anzp1Q7RKZ/Mjpfybwq51Q4jqZ2+C9uMVXUziXvE/o3ApGH4w9mhY wk5g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1704808825; x=1705413625; 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=wPj1JmbLmjHtnqKv3oV9vKUnkqBzc+Wz4DzteIaT/Hs=; b=AxMuGhlQerViIU1Now/xhPrWFwwbLK2sqlxxG7jQ8NnISWaIBefzNUhkIhWkBhkIAm JMMOWln89PXmRC1AmKlWNuafyOiKOY5Vkxy9uC3el3plF2nqmeT0buANvuDz4D/M16B4 0BLjMEqR+cy55tetmkRp0+pMd8J9c5HecwRKMqEdOado8oPJg+J8aEg8D0vxk0vOEvtc CouISte4Kc5lxvZYkdSQVkPfqty/isiPKuG3vWHtMQhV6Kd2Is7+vm0qGfNZ/yj8TMUh 5ogn7fwWN2VOhgTj/ZlIovW5KUUI07jy5pxv63dE2e35SiPQfaOKpVAdq4T7ot33xnd9 Hg2Q== X-Gm-Message-State: AOJu0YxqLxEt7LKFTPbxSLUrAbUL/WeTUsGOdUq8jbjOqlCb48F1NPud ex3Wpts8ykSAFFScnEBb7x8s0XmS+ZNYRg== X-Google-Smtp-Source: AGHT+IGpqde5Zg03gO/mvZvCU3mbH34hXvPF/1xLxSrh0Pv38C+Jf2AiqWoOYFWDW/ez4DENukXScA== X-Received: by 2002:a05:6a00:3204:b0:6da:2f90:80d8 with SMTP id bm4-20020a056a00320400b006da2f9080d8mr2413815pfb.12.1704808824286; Tue, 09 Jan 2024 06:00:24 -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 m2-20020a62f202000000b006d9accac5c4sm1673697pfh.35.2024.01.09.06.00.20 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 09 Jan 2024 06:00:23 -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 1/7] Documentation: gpio: add chardev userspace API documentation Date: Tue, 9 Jan 2024 21:59:46 +0800 Message-Id: <20240109135952.77458-2-warthog618@gmail.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240109135952.77458-1-warthog618@gmail.com> References: <20240109135952.77458-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 | 114 ++++++++++++++++++ .../userspace-api/gpio/error-codes.rst | 78 ++++++++++++ .../gpio/gpio-get-chipinfo-ioctl.rst | 41 +++++++ .../gpio/gpio-get-lineinfo-unwatch-ioctl.rst | 47 ++++++++ .../gpio/gpio-v2-get-line-ioctl.rst | 99 +++++++++++++++ .../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, 834 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..af5f1753e565 --- /dev/null +++ b/Documentation/userspace-api/gpio/chardev.rst @@ -0,0 +1,114 @@ +.. 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.`` + +.. 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..ba6f9d00a40b --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst @@ -0,0 +1,47 @@ +.. 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**). + +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..4259c08779c1 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst @@ -0,0 +1,99 @@ +.. 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. + +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 Fri Dec 26 05:29:08 2025 Received: from mail-pf1-f181.google.com (mail-pf1-f181.google.com [209.85.210.181]) (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 09B1239876; Tue, 9 Jan 2024 14:00:34 +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="V95yhIDE" Received: by mail-pf1-f181.google.com with SMTP id d2e1a72fcca58-6d9a79a1ad4so1309163b3a.2; Tue, 09 Jan 2024 06:00:34 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1704808834; x=1705413634; 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=8BCKYEo6R3k+Quwcv5Ub6j7F0zuPGuRj4A0bC177gLY=; b=V95yhIDEajr3HmzJVrIwBY+e47asf0G2mjSiz4Au7AVBykOQXLfvgtG6S/mugCV4lA 6hQ3Cm3geXaR1Jxl48zE2/lEQimvbaH2i19p2kt3scLp3386dPMeyYYXS9EcX/3Fygzy UQZz+tuy5yV8e//1ELPvFZCUuPw03uKtfYbVfwlX1vPF9dUh0TQKCb6rSsAy/t8eVuH+ QmLk5opxZ1MnU9DrIClDvnn8wAUNfVYWcLjybBWcI1CYiI+nSFZsxTZI+z0i0LCz2bVC 6zgGYYyNPQ5AM8A5ZbQjGjwnhOWp0l0MixBIWmC+afm1OPBHPA0KsooqDaBybbixET7I ig3Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1704808834; x=1705413634; 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=8BCKYEo6R3k+Quwcv5Ub6j7F0zuPGuRj4A0bC177gLY=; b=qZ+PbPPwmhMsHY2EhL9j7+5h33ugCwLTahu/JKxH4ZF3ryvb1/BIVnVoUkMRe3R2q8 /1qovg1H6k7NNYmxVe4S7chCFfJ1Qq3q9oSwBsvmbQ+efdu/E0Gxx8riHT+ETldjE8/E t3S5TrKpkqHZRavax5HKnTlqCVG93AKdsT4LkR3vhM+33hDvQytgfggBzz/TrAnuvn/j 4SUQ1EDOoqY7IID1B2beHVi8k4B4yp5QZUnJ8e+g2jgVVeoV/Y5RRbLwb2ZpUSg/q32B Qwx3GipWv4bPtlmnrtzhq5hL383v5OxNRVQx8Q8p0FObkt9WZcEhGRGojTkMOTXNc46Z CqrA== X-Gm-Message-State: AOJu0YwmRfbNR/SB6zk84iZk6BSyWX1fZi/Gnp32BmD5t8epwf5hY2hI LD1useD2aFSLN10UgAvLCHG+jvnhjRytmA== X-Google-Smtp-Source: AGHT+IGtSWguF7q9VbOdESfHQUdcHFNHIIo25gfrQLm7+3M4oj3w0UNypF9mveF+o5k+Ezu3rOcpcg== X-Received: by 2002:a05:6a21:150d:b0:199:81a3:847 with SMTP id nq13-20020a056a21150d00b0019981a30847mr3033272pzb.57.1704808834018; Tue, 09 Jan 2024 06:00:34 -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 m2-20020a62f202000000b006d9accac5c4sm1673697pfh.35.2024.01.09.06.00.30 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 09 Jan 2024 06:00:33 -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 2/7] Documentation: gpio: move sysfs into a deprecated section Date: Tue, 9 Jan 2024 21:59:47 +0800 Message-Id: <20240109135952.77458-3-warthog618@gmail.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240109135952.77458-1-warthog618@gmail.com> References: <20240109135952.77458-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 deprecated, so highlight this even further by moving it into a deprecated APIs section in both the admin-guide and userspace-api books. Signed-off-by: Kent Gibson --- Documentation/admin-guide/gpio/deprecated.rst | 11 +++++++++++ Documentation/admin-guide/gpio/index.rst | 2 +- Documentation/userspace-api/gpio/deprecated.rst | 10 ++++++++++ Documentation/userspace-api/gpio/index.rst | 1 + .../{admin-guide =3D> userspace-api}/gpio/sysfs.rst | 0 5 files changed, 23 insertions(+), 1 deletion(-) create mode 100644 Documentation/admin-guide/gpio/deprecated.rst create mode 100644 Documentation/userspace-api/gpio/deprecated.rst rename Documentation/{admin-guide =3D> userspace-api}/gpio/sysfs.rst (100%) diff --git a/Documentation/admin-guide/gpio/deprecated.rst b/Documentation/= admin-guide/gpio/deprecated.rst new file mode 100644 index 000000000000..33f701294732 --- /dev/null +++ b/Documentation/admin-guide/gpio/deprecated.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=3D=3D +Deprecated GPIO APIs +=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 <../../userspace-api/gpio/sysfs> + diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin= -guide/gpio/index.rst index b40f0a2a6822..9b0630f30d3e 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 + Deprecated APIs =20 .. only:: subproject and html =20 diff --git a/Documentation/userspace-api/gpio/deprecated.rst b/Documentatio= n/userspace-api/gpio/deprecated.rst new file mode 100644 index 000000000000..4cc7c79d7c23 --- /dev/null +++ b/Documentation/userspace-api/gpio/deprecated.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=3D=3D +Deprecated 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=3D=3D + +.. toctree:: + :maxdepth: 1 + + Sysfs Interface diff --git a/Documentation/userspace-api/gpio/index.rst b/Documentation/use= rspace-api/gpio/index.rst index 072b9fa18aea..17f0f92db384 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 + Deprecated Userspace APIs =20 .. only:: subproject and html =20 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 Fri Dec 26 05:29:08 2025 Received: from mail-pf1-f177.google.com (mail-pf1-f177.google.com [209.85.210.177]) (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 7B22B39850; Tue, 9 Jan 2024 14:00: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="G0a1SQYU" Received: by mail-pf1-f177.google.com with SMTP id d2e1a72fcca58-6d9af1f52bcso1306472b3a.3; Tue, 09 Jan 2024 06:00:49 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1704808849; x=1705413649; 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=F8f5vyy0tPHI86sp2s5tsFXKkVf05GsuTSdlf4bjqw8=; b=G0a1SQYUFc3F/45LEUDRooiNuZwcVnWM11EC66C80iPeqrMz3/YaEuBPqWVbYEbhba TCvqMTG2t73vPl4IkzrvoYugfbVsoV94p2jPusOGLlrOSz2deLzgEYwlumXVElYKocSD qoEQQR3TS6z2mQrLJH95XsWgFrdYTQTLsDCtFyxFZ+p0b4sC6WoN66aIAoDrPVQh/j68 xIVSIM/7OFfIiLG59MeJrGxgNH2v4dl3UKSOi/3uzK8kFU+EsmiMW1q0FFMP/SEYnhSu raHlpKSWY1g3V88GmjnWPy3yAy0R/sy64GBinaBXAG8bm10PrJK0kz181aypXXlO6wmJ s4JA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1704808849; x=1705413649; 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=F8f5vyy0tPHI86sp2s5tsFXKkVf05GsuTSdlf4bjqw8=; b=FaOkLmOK5zA2OKMH88oZuuw6ax2Ep+NSTCTwCbCVLOkYN3zXQ1OY8PVc+2Eq0S6+WR 9GFPmZTz+VO1ut1xdhKKp/KrWCJap1UtdOrFmaT7rwuVOFCuvLgVVIoUQHK5pdhaVzoU VsYHD3znhE9ZoieRoURLwvnZ+xB6XEvMJcH8jgJVJNauLZHIUtdG3f4yCgoIU5iBdhdX cCHPRSmlMMcJsmpvIv2/DiecEWNrw/i3SFlPwECEXKqcxhWi6HCkvP/G4NbzCngI6wPY jKvUzc62JtAHcRlCF0Xpdy9FlnV90FK39l/xRk9dEVgpkFxF+GTJ7jUpSL2caOQtrTMs FKSg== X-Gm-Message-State: AOJu0Yxxwn7FUPRLG3nGOXj0beYsk00aum+0Xup7JxiO/0X0biHnx12+ 9WxY9sypFI92vNN4tcL5CWVWM8/5ieKAeQ== X-Google-Smtp-Source: AGHT+IFkkWND24KvGMQY0dL1e+re0wSJe275+ChZJ9ghrnuWVEp3d3qUALc5DGtNWpeqdrehsy7EiA== X-Received: by 2002:aa7:8543:0:b0:6d9:c7f2:841c with SMTP id y3-20020aa78543000000b006d9c7f2841cmr2387041pfn.35.1704808848641; Tue, 09 Jan 2024 06:00: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 m2-20020a62f202000000b006d9accac5c4sm1673697pfh.35.2024.01.09.06.00.45 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 09 Jan 2024 06:00: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 3/7] Documentation: gpio: update sysfs documentation to reference new chardev doc Date: Tue, 9 Jan 2024 21:59:48 +0800 Message-Id: <20240109135952.77458-4-warthog618@gmail.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240109135952.77458-1-warthog618@gmail.com> References: <20240109135952.77458-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 | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/Documentation/userspace-api/gpio/sysfs.rst b/Documentation/use= rspace-api/gpio/sysfs.rst index 35171d15f78d..ef080d811451 100644 --- a/Documentation/userspace-api/gpio/sysfs.rst +++ b/Documentation/userspace-api/gpio/sysfs.rst @@ -5,12 +5,10 @@ GPIO Sysfs Interface for Userspace =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. + SHOULD USE THE chardev.rst. =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 OLD SYSFS ABI WILL NOT BE DEVELOPED (NO NEW FEATURES), IT WILL JUST= BE + MAINTAINED. =20 The deprecated sysfs ABI ------------------------ @@ -34,7 +32,7 @@ standard kernels won't know about. And for some tasks, si= mple 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 +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 Fri Dec 26 05:29:08 2025 Received: from mail-pf1-f172.google.com (mail-pf1-f172.google.com [209.85.210.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 0DAE639AC4; Tue, 9 Jan 2024 14:01:04 +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="I6b9cdEb" Received: by mail-pf1-f172.google.com with SMTP id d2e1a72fcca58-6db0c49e93eso520059b3a.1; Tue, 09 Jan 2024 06:01:04 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1704808864; x=1705413664; 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=Z5q3upRIBT7s4nyLz9HFcCh082UKeyT493mljbMrE3o=; b=I6b9cdEbbLgICfpSl82zlVJ+TdWR2oPqU7/AnXCkD7G+ucjerN8rjd15or4Asx9eMk rhThhkak8ZqWjXvnDv4+OCgxd4kVRI72Vx0NoN+0FKwEHazt45JL+yASdvtzuCybAd5y Ie++YqMAH01Iw5J+4Bius9uJwP1Wkjd9ypPcwaisHkNkO9lmr2ZW7GGrgMc9p2riFEFK zq9FpI22Ki9ieufxhVnA2Bz6aeMTSR2+yE6WMIZvZCSu7LrtaTi9PiYPztbkmVGsnGjM hoaZf1XITlVYvvkBaAuEINVwHS1jCokY2LRPi9dri11TarUsPOp/dEnTi8ZUk3d4eh3Y /Q4A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1704808864; x=1705413664; 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=Z5q3upRIBT7s4nyLz9HFcCh082UKeyT493mljbMrE3o=; b=Qph9O4rJ9+N6pt3LcjGBdPr+gmSvs7yJ1c+LBykskvNkcJPjHM1ZW4UjIy+T1OCFdq D/RXsafsvtA6NH2uBrvMpj70P0R7g9P8j42kbZ73gc1CFc7+da+DQqGB7SdOPV6ubhxV 1O6l42eEDY6qxwXCQt+Ehfpvp/22lZKjnsFpG473GJLQi4AjZ7zdTPMpNk4n59cwxjB5 gzO3MoCkD4Mhw7+7SlRvDw+yB3v7l5GWQNcpMP2N+FLjXW4l+++tWQDwpBzp39YdtaSS YsGlgpXZE6CowkO4bgZBGDQkbQS+Schsz9VSlI5OtAvgGxTcAY2TV4s2Lu6sg6h7UjP+ dPIg== X-Gm-Message-State: AOJu0Yw8gnlldBERjoYV+ZktquGDz+Fd0NU9Hw1oZm9Lq5zpPrEYXPnw 1D+kndrIumCUuSwCQL3JYXoQ5e+QUA1+SQ== X-Google-Smtp-Source: AGHT+IFb5m4av0M0FoZV82QX6VqvcuoZu2or6hRcmmjyDpSGUnhIXEmQinKDANe8XSYSx+To2THsfA== X-Received: by 2002:a05:6a00:929a:b0:6db:1653:47a0 with SMTP id jw26-20020a056a00929a00b006db165347a0mr211395pfb.1.1704808863545; Tue, 09 Jan 2024 06:01:03 -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 m2-20020a62f202000000b006d9accac5c4sm1673697pfh.35.2024.01.09.06.00.59 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 09 Jan 2024 06:01:03 -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 4/7] Documentation: gpio: add chardev v1 userspace API documentation Date: Tue, 9 Jan 2024 21:59:49 +0800 Message-Id: <20240109135952.77458-5-warthog618@gmail.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240109135952.77458-1-warthog618@gmail.com> References: <20240109135952.77458-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 deprecated section of both the admin-guide and userspace-api books. Signed-off-by: Kent Gibson --- Documentation/admin-guide/gpio/deprecated.rst | 1 + .../userspace-api/gpio/chardev_v1.rst | 129 ++++++++++++++++++ .../userspace-api/gpio/deprecated.rst | 1 + .../gpio/gpio-get-lineevent-ioctl.rst | 76 +++++++++++ .../gpio/gpio-get-linehandle-ioctl.rst | 84 ++++++++++++ .../gpio/gpio-get-lineinfo-ioctl.rst | 54 ++++++++ .../gpio/gpio-get-lineinfo-unwatch-ioctl.rst | 2 +- .../gpio/gpio-get-lineinfo-watch-ioctl.rst | 72 ++++++++++ .../gpio-handle-get-line-values-ioctl.rst | 56 ++++++++ .../gpio/gpio-handle-set-config-ioctl.rst | 60 ++++++++ .../gpio-handle-set-line-values-ioctl.rst | 48 +++++++ .../gpio/gpio-lineevent-data-read.rst | 84 ++++++++++++ .../gpio/gpio-lineinfo-changed-read.rst | 85 ++++++++++++ 13 files changed, 751 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/deprecated.rst b/Documentation/= admin-guide/gpio/deprecated.rst index 33f701294732..683d7d23e62a 100644 --- a/Documentation/admin-guide/gpio/deprecated.rst +++ b/Documentation/admin-guide/gpio/deprecated.rst @@ -7,5 +7,6 @@ Deprecated 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..d5b01d919383 --- /dev/null +++ b/Documentation/userspace-api/gpio/chardev_v1.rst @@ -0,0 +1,129 @@ +.. 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. 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. + +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/deprecated.rst b/Documentatio= n/userspace-api/gpio/deprecated.rst index 4cc7c79d7c23..09ed40e6c7fa 100644 --- a/Documentation/userspace-api/gpio/deprecated.rst +++ b/Documentation/userspace-api/gpio/deprecated.rst @@ -7,4 +7,5 @@ Deprecated GPIO Userspace APIs .. toctree:: :maxdepth: 1 =20 + Character Device Userspace API (v1) Sysfs Interface 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..fe3bc37f1ab0 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst @@ -0,0 +1,76 @@ +.. 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. + +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..71abea9f7e4b --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst @@ -0,0 +1,84 @@ +.. 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. + +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 ba6f9d00a40b..13a833343ca4 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..1fda1d6900e3 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-get-lineinfo-watch-ioctl.rst @@ -0,0 +1,72 @@ +.. 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()`. + +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..a9501b3c04f3 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst @@ -0,0 +1,60 @@ +.. 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. + +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..9bfd6f6aada8 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-lineinfo-changed-read.rst @@ -0,0 +1,85 @@ +.. 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. + +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. --=20 2.39.2 From nobody Fri Dec 26 05:29:08 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 C70C239AC0; Tue, 9 Jan 2024 14:01:18 +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="TtKD7s6F" Received: by mail-pf1-f179.google.com with SMTP id d2e1a72fcca58-6d9b13fe9e9so2490045b3a.2; Tue, 09 Jan 2024 06:01:18 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1704808878; x=1705413678; 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=l8cU322h1T8euUzrnOuJXn7OTljQAN5GoNSLAaiJuHA=; b=TtKD7s6FEqUK0WZdyQN0FIMCNM02FJNPokEFfhRuPa7kUDrhUnuJVWHjm9LQfrPZR9 gIQiFl24w1XPLT5bYEeuH4pZaExdilZGw17o+xu7HfsKlsvIAXJrE5ATm+WprNTYysu3 ldUUBc0LWppXgJj2eBdzzZ355+iQXnGNYo4+4iS10ucWI8AdJOr+DU7xkyz1lC5nxVzm 2HZ0aytG/xZGWpMuABKcGwwKEGw33n/M7ia5D1gWPE4uXpGQqCBsPylignBflfcL3gIn rF3VVLrQyBCykO/BsR4vsTVnJeR7i4ZRBBjN5EGchPXet7u6IUIDklSk0kJa4qezFsnf h9zw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1704808878; x=1705413678; 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=l8cU322h1T8euUzrnOuJXn7OTljQAN5GoNSLAaiJuHA=; b=RYpP6kZffuVvZ5TcAKqy5za5uPCb56Vixr0uQGJV/hZ1ru4ME+3uCjPbxrGV88o10i qtn4C/6NWtezTcYUruoyBCoYoV+L4GvdD64DrqQSXNzmNLYLzclLJIj31XoApTVFLdG4 LclZeYu3Aw797FK9ZwtsXNn5cQ7U30wMVTtWJC9Cm1HXezFQOZGSvGEJNO+j6MC3Bn6M UwIAys1D4eZ67E1qWY2lORR9iYhQ57I2/oVwusCPaQhkQH8zCluroWZW+P+HTxod3WX7 OJO4HBEGikQ7NYNyDD5fgLwZ3Z2gernECL4b8shnUNQpRnrqZTBq+u9wvn1eZNf8bYEo dQSw== X-Gm-Message-State: AOJu0Yxvx4S/4HpwlXxIbhEQ+o+SM8gfCnKg5+bN9N6Mu9i2QSRMPNI7 BAM5EN1nthxuQ8zdBpesYI88n2oFFOgDCA== X-Google-Smtp-Source: AGHT+IGZGf9ihOaEtUP/bSov92VbNdkmIgqrMUgoZElHfLwK/P3e/DGRfGlHn1GwwF+/nD5tSDFOJg== X-Received: by 2002:aa7:9315:0:b0:6d9:a856:ec9b with SMTP id cz21-20020aa79315000000b006d9a856ec9bmr4873088pfb.25.1704808878005; Tue, 09 Jan 2024 06:01: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 m2-20020a62f202000000b006d9accac5c4sm1673697pfh.35.2024.01.09.06.01.14 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 09 Jan 2024 06:01:17 -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 5/7] Documentation: gpio: capitalize GPIO in index title Date: Tue, 9 Jan 2024 21:59:50 +0800 Message-Id: <20240109135952.77458-6-warthog618@gmail.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240109135952.77458-1-warthog618@gmail.com> References: <20240109135952.77458-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 9b0630f30d3e..8489b8a3991f 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 Fri Dec 26 05:29:08 2025 Received: from mail-pf1-f169.google.com (mail-pf1-f169.google.com [209.85.210.169]) (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 DFFC939AFC; Tue, 9 Jan 2024 14:01:33 +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="jpPkypit" Received: by mail-pf1-f169.google.com with SMTP id d2e1a72fcca58-6d9cdd0a5e6so1406603b3a.3; Tue, 09 Jan 2024 06:01:33 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1704808893; x=1705413693; 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=jpPkypit7AEo7Pmy36BF/kYIninjGgEwFsQO/oolRYoK+GsX3d748gEHHHUMuz5S7c 313RRLXAbo2leus1oBADuNXgHQE3V6B7fSy7ZJXnZup2wX7aV+pXnZo/yaIuOOnm9Dya RxH0MHwjwwknzeFs/SvcwGMuNOxahCEwQdhewNdKGXPVF0iP1z7g48ecorDan1IRMrMC L/3dITrSE3zEt5ZcUd1zPCe7qiNOEhvwmmPY3mpbIl12qIDWR8zdLj7O+tmfiFeA6b8C 7QzT/Sj5ND4AcETq5UgHeDpuknTvYOY0FNdoQRMH9r5yNXaaqxWwM7hVS1ZzSQL6tJle Gk2g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1704808893; x=1705413693; 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=bTjF/E5y9XDoGpylc3oDThlAlP3jj4MNl7z19a/fmiONcHUYqoMWNP34DnnnThmLO/ t3DYZtZP3LPdOWCY6YCGeHhFUxr47vQ8VhpbxjO2mq/g3CTFzWs/UY7H8EhXCpc56plk NIsKZJREMFpBONwA7TyKD0HrMxo/wTW2KbXFe35EjFFnYeXtWbUoWLFxQGP7u6rmqC/8 O5n2Eb54E7xN2lk3Bk3wu6i27QtEyXQw4lcx+/GV5t5bFLODbZKeYNaRNDaYr3neEa3C DeauzpECZFmMd9v0vaFJNBLOElEoSi2UlrkMLWOo/W5lmwgMee6t+RXVLfDu1ubUbW4+ g6qQ== X-Gm-Message-State: AOJu0YzVKq7qGe4eHLKiXPtFqnHZ7o53ckeaYLUKMOopFTDDDhm+JdID Fyy1tuRl7cJUWockhmsRKLQr3H3FYrBEeQ== X-Google-Smtp-Source: AGHT+IFu2wBrx1UlnwU1Rv4xXGxgKte8dxiYurI+14HILwPK7gzGiUnBH7pBmZ/pvr4ScLDC3x70vg== X-Received: by 2002:a05:6a00:9089:b0:6da:336f:a925 with SMTP id jo9-20020a056a00908900b006da336fa925mr3156965pfb.29.1704808893013; Tue, 09 Jan 2024 06:01:33 -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 m2-20020a62f202000000b006d9accac5c4sm1673697pfh.35.2024.01.09.06.01.29 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 09 Jan 2024 06:01:32 -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 6/7] Documentation: gpio: document gpio-mockup as obsoleted by gpio-sim Date: Tue, 9 Jan 2024 21:59:51 +0800 Message-Id: <20240109135952.77458-7-warthog618@gmail.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240109135952.77458-1-warthog618@gmail.com> References: <20240109135952.77458-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 Fri Dec 26 05:29:08 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 B994E38FB7; Tue, 9 Jan 2024 14:01:48 +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="eFqpjVcQ" Received: by mail-pf1-f179.google.com with SMTP id d2e1a72fcca58-6d9bd63ec7fso1411555b3a.2; Tue, 09 Jan 2024 06:01:48 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1704808908; x=1705413708; 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=FC/8g7ZpWpj5XGSBITdvk8s0jNFEaS2+hXn9GTWkyls=; b=eFqpjVcQc5nMDh1ei/DndWYaBYETtrbr4oYBhhImyay+qf7aBBC5efYEiOFPQuWqnP hUtZiR1C50aKiwGhjMgYWn6k5rh2/9oMXRRVbusM5vr4Ix8roufWhj9kL9nepPwEoS5l VWWsNsl9TpvxUu0lC9MTMBtWowUPPP2U6h/bWqZllZQPomHa4S7kD2ImGcWsu4N0Kxas 7fr6Kx3Pax8U8dtpy3oUQAqb1HyfDkdNEJbGIVUGju3z+5Nhtq/+aYAzgGS1wpF4lHs0 JM2ay59QLhOyvqW3b6RoyVEeEay2D9Qzi4z7lgYkFozAiMJ7CDEVSIGF/bQ/0FKgWPor SpaQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1704808908; x=1705413708; 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=FC/8g7ZpWpj5XGSBITdvk8s0jNFEaS2+hXn9GTWkyls=; b=P26wPCsSF9I4OUdcoY1APmjr94HYVn1YOnKKJGz3di4NuCt7/oLus67Qk+lzFFGh4Y A11gBEOvt8SV7Wq5RXF44OLlVM2mFhmwRoFBo7qA3LnqiMlzVzzqzfvbXAD7Mfh6548v kD5Z1AU+UH0kTAUfXb0Mr0MMdzpLznoTpSeu6YW9aPtZV5pQu+RKsqi4S5v1cPO6FOXg 7aH6HYPDYPcz0++R27lhLExvBluc0u6UdrG56FSokTHFfEyK/jE3MmhNlT1At0hC5oNm PaMFoink9r/rU1YcOIjytMEUfVcwhQViHzBUp6DtJu7p+wh0Ggqc4LMoCWqDJtah9aWw Ak1A== X-Gm-Message-State: AOJu0YxoJzhNG8kF5K3A4QLJyqp9N4rfLTCSW7majKPWnNDJgKZRnstg i76Lv+JW9EZFfX2Fc2xRCw5CDCajzHre8g== X-Google-Smtp-Source: AGHT+IEVssHtiESKXpR+knixhH3RM0dJ0WL/8knFJz8d2Ip0hq7H0EzMPLcgxXq5uGv49Ep0Qp4+pg== X-Received: by 2002:a05:6a21:1f25:b0:194:d82d:83cc with SMTP id ry37-20020a056a211f2500b00194d82d83ccmr2326988pzb.108.1704808907555; Tue, 09 Jan 2024 06:01:47 -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 m2-20020a62f202000000b006d9accac5c4sm1673697pfh.35.2024.01.09.06.01.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 09 Jan 2024 06:01:47 -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 7/7] Documentation: gpio: move gpio-mockup into deprecated section Date: Tue, 9 Jan 2024 21:59:52 +0800 Message-Id: <20240109135952.77458-8-warthog618@gmail.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240109135952.77458-1-warthog618@gmail.com> References: <20240109135952.77458-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 deprecated section of the admin-guide book. Signed-off-by: Kent Gibson --- Documentation/admin-guide/gpio/deprecated.rst | 1 + Documentation/admin-guide/gpio/index.rst | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/admin-guide/gpio/deprecated.rst b/Documentation/= admin-guide/gpio/deprecated.rst index 683d7d23e62a..8503ea2f54d5 100644 --- a/Documentation/admin-guide/gpio/deprecated.rst +++ b/Documentation/admin-guide/gpio/deprecated.rst @@ -9,4 +9,5 @@ Deprecated GPIO APIs =20 Character Device Userspace API (v1) <../../userspace-api/gpio/chardev_= v1> Sysfs Interface <../../userspace-api/gpio/sysfs> + Mockup Testing Module =20 diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin= -guide/gpio/index.rst index 8489b8a3991f..573682212a56 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 Deprecated APIs =20 --=20 2.39.2