From patchwork Tue Jan 23 13:38:28 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Kent Gibson X-Patchwork-Id: 190951 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7300:2553:b0:103:945f:af90 with SMTP id p19csp337696dyi; Tue, 23 Jan 2024 05:39:21 -0800 (PST) X-Google-Smtp-Source: AGHT+IGpmLQw30upwxdVDkPiGKrtf6eNA2DyIVXTJ6jc8AbpYj7tK6p1F4Czn4BOtUiwDLEbjYCN X-Received: by 2002:ad4:5f8f:0:b0:681:9434:5e9f with SMTP id jp15-20020ad45f8f000000b0068194345e9fmr1039326qvb.106.1706017161519; Tue, 23 Jan 2024 05:39:21 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1706017161; cv=pass; d=google.com; s=arc-20160816; b=bTekBNxazBMBIHR3963FWlZDU9bDHpfgSY0Fee5TJtF32WRWP7kFq7VA/+N+vkH2FH vow56ANvf939ihdg+kAPZrIV4sJUzlBxLYRaXyoGFy0btNlWAvEUzuIEa417/zwrOQvc ZGk+q7tv1ekcaWjFJzoi4B5voY4tYN9m7bfcdzWODA3PP45hoRCQbXQW2UXbEWBPEVLE 7x2zqchk3OqkuvLUu+jaHVkHw/QJreIPh5o/fi6y1YsIMNh7PCiKMS6PmwupH50sTKaA IfLhrlT5PzROg2q1ECJlMGiDIpCH/Ro9LO1QbBofFJksRWxlieDbshKIsoOfHjQuZd3+ oD0A== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:message-id:date:subject:cc:to :from:dkim-signature; bh=JGyd1fR1SCxmdaNNcPfqGPYdWi8z44bAjGbNFrHnciI=; fh=VAUkZTzChiIGUh6kITzrsogUwm1/k7LdkteM1zwsPa0=; b=s5jxqNYDmzu7dc2VEdXckLhelFRvIVByZTVY3muTlOpOgaJLmK0SIHA1fi5qbV7d3E RyJxuvmzaT5H4MnoA6VwsqLub+mzE1+NhjGsVoFt9OypQVuQ9R3rmjUFYMrvOsRnwdf9 UdItQJfuxxLRbecMfW7g6hU28vvzk/3VltUsiSsLo3UbFRFzgD+7BBJaU4Wz/S5PVsWR yVovVX3cqMggdWpUDxjCK3n5NAzbhIMZEf+SESRQGtg/igxo9dXZQKAY3oek62CySFSu DQz5trvgBorYDIe2AeKPs9wByNjkTW17X+jrkP12Yhug6ttA6kfKLZ98Xo0l9HbLL967 zV8A== ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@gmail.com header.s=20230601 header.b=k0sernFO; arc=pass (i=1 spf=pass spfdomain=gmail.com dkim=pass dkdomain=gmail.com dmarc=pass fromdomain=gmail.com); spf=pass (google.com: domain of linux-kernel+bounces-35393-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) smtp.mailfrom="linux-kernel+bounces-35393-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: from ny.mirrors.kernel.org (ny.mirrors.kernel.org. [147.75.199.223]) by mx.google.com with ESMTPS id h21-20020a0cab15000000b0068028d46496si7949088qvb.409.2024.01.23.05.39.21 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 23 Jan 2024 05:39:21 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-35393-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) client-ip=147.75.199.223; Authentication-Results: mx.google.com; dkim=pass header.i=@gmail.com header.s=20230601 header.b=k0sernFO; arc=pass (i=1 spf=pass spfdomain=gmail.com dkim=pass dkdomain=gmail.com dmarc=pass fromdomain=gmail.com); spf=pass (google.com: domain of linux-kernel+bounces-35393-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) smtp.mailfrom="linux-kernel+bounces-35393-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ny.mirrors.kernel.org (Postfix) with ESMTPS id 42CD71C21122 for ; Tue, 23 Jan 2024 13:39:21 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 3AC705F565; Tue, 23 Jan 2024 13:39:08 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="k0sernFO" Received: from mail-pl1-f180.google.com (mail-pl1-f180.google.com [209.85.214.180]) (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 A01295EE76; Tue, 23 Jan 2024 13:39:02 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.214.180 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1706017144; cv=none; b=jdBbuVFNa7BOa31vWu9DenGL/yR20o/wbWO/sLGfoQJog68FtISAfX+AtkiRqCARu90J/3l6cUB0z0WU84Hp4T3WiaB0uYxgZlPMB+kF6C40WBtzx0EjdiOoHM4SkIwnZ7417WvaUNyVxHV6xQFwRs1jpvYbIw3EmFdo9Ue4EK0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1706017144; c=relaxed/simple; bh=WBSKdUgV5cOeoZ1Fffr465L1E5/Iwt0hZoQjjcYdeug=; h=From:To:Cc:Subject:Date:Message-Id:MIME-Version; b=rR3pTVzwyQbyI1Y+X74YaZNkhmA+ZZyc/y9BMjqvXzBOInXouIap0cQ94866b+ASDCdvaEK4A5GYdPsPX8eG9ehBP3jnPYIQZ/q850usDDFkn5ZuztKkzY/Uc5B1PutgOYs1sTdebzUZ6hlMhg6jvONvpOAQ2Wtlh2usgr+9Hjc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=k0sernFO; arc=none smtp.client-ip=209.85.214.180 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 Received: by mail-pl1-f180.google.com with SMTP id d9443c01a7336-1d730b6943bso9876915ad.2; Tue, 23 Jan 2024 05:39:02 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1706017142; x=1706621942; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=JGyd1fR1SCxmdaNNcPfqGPYdWi8z44bAjGbNFrHnciI=; b=k0sernFO6sgNBeAX4fos6xcL5ztr0A+RoZUi+Wx31zMfUB5z7ZOLAkrvifH3yev5an ksRwTgFFdv6fN9n3J1+fq6IdESNbwwgA1aAoHM6dNE7qNVRX/asNkk7OvCQq9N6OS1Or rceysNgHaTJcsSI6su3EXJ2qcQAs1h+FcyLQeuw2nVXAvEB+9htAoe9H9QaLPEMEaCvY XjUxljKJcTW1MoxVpD25c8UDcwEexUZXkCSTAW1zZr7D9HEbpwgAXeyTvwyQ7pclnAcb tfgo0qnlUqxNwyV8ezIdew4r6eGp8rTDptAbXvAOCyv08RMmvjKT25IySseqZH00U0qh hqCQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1706017142; x=1706621942; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=JGyd1fR1SCxmdaNNcPfqGPYdWi8z44bAjGbNFrHnciI=; b=H0YJBAOmldxIc1p1O+ZRpgpOjOvsH2RPIahWxwV7x7XZfzXtL1aRPbcrBGiEU+PM// ZgFFwIsTVtf2XngbORCwrgSK+8WXmmVOj4XjYSN8KWY0mfa2gsviYRCJxAvW2H4vjNLM ObBiKq85zPh6Y/fdZNDMYri4sNmjAq5WpGAYROG3k2zPlNwa0UUdHlTIjaVGpFrjMhic 1yRKtIKFwu51SBu+aaQwvcE5D4DeLzL6O6NGBkz1K6/6b/dyZxVaw2xeVrSCLWOQ0wrj GRqO7PKSu6rrmtwn40++tJ/fWnwVmTKrF4hg9NnPzTRFDC/PsHf1WvjSt/xpHY81n+6a 8kKg== X-Gm-Message-State: AOJu0Yzt034Wjr4AL2t1zTiiXbS2c9QyHNTKAE2y2WUHog0A0+FaeeS+ pCd4qBbmjulpQ/jNJ4jyvbE6lUgWroonoVFB2dcS4DIWGQTfreOZFPon/zAT X-Received: by 2002:a17:903:48b:b0:1d4:be56:888b with SMTP id jj11-20020a170903048b00b001d4be56888bmr2924349plb.1.1706017141496; Tue, 23 Jan 2024 05:39:01 -0800 (PST) Received: from rigel.home.arpa ([220.235.35.85]) by smtp.gmail.com with ESMTPSA id h19-20020a170902f2d300b001d5f1005096sm8933818plc.55.2024.01.23.05.38.57 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 23 Jan 2024 05:39:00 -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] Documentation: gpio: describe uAPI behaviour when hardware doesn't support requested config Date: Tue, 23 Jan 2024 21:38:28 +0800 Message-Id: <20240123133828.141222-1-warthog618@gmail.com> X-Mailer: git-send-email 2.39.2 Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1788888651318295404 X-GMAIL-MSGID: 1788888651318295404 The existing uAPI documentation does not adequately describe how the kernel handles the case where the underlying hardware or driver does not support the requested configuration. Add a Configuration Support section describing that behaviour to both the v1 and v2 documentation, and better document the errors returned where the requested configuration cannot be supported. Signed-off-by: Kent Gibson --- My bad for this not being part of the recently applied documentation series, but it didn't occur to me that this wasn't described until about the time that was being applied. OTOH this patch is far smaller than a respin of that series would've been. I've kept it as a single patch as it is all related, even if it spans v1 and v2. There is also a trivial typo fix in gpio-handle-set-config-ioctl.rst that I noticed while I was there that in my eyes didn't warrant a separate patch. Cheers, Kent. .../userspace-api/gpio/error-codes.rst | 3 +- .../gpio/gpio-get-lineevent-ioctl.rst | 6 ++ .../gpio/gpio-get-linehandle-ioctl.rst | 39 +++++++++++++ .../gpio/gpio-handle-set-config-ioctl.rst | 5 +- .../gpio/gpio-v2-get-line-ioctl.rst | 57 ++++++++++++++++++- .../gpio/gpio-v2-line-set-config-ioctl.rst | 3 +- 6 files changed, 106 insertions(+), 7 deletions(-) diff --git a/Documentation/userspace-api/gpio/error-codes.rst b/Documentation/userspace-api/gpio/error-codes.rst index edf01f2cf9d2..6bf2948990cd 100644 --- a/Documentation/userspace-api/gpio/error-codes.rst +++ b/Documentation/userspace-api/gpio/error-codes.rst @@ -65,7 +65,8 @@ GPIO Error Codes - - ``ENXIO`` - - No device corresponding to this device special file exists. + - Typically returned when a feature requiring interrupt support was + requested, but the line does not support interrupts. .. note:: diff --git a/Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst index 7d0b932925c6..09a9254f38cf 100644 --- a/Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst +++ b/Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst @@ -48,6 +48,12 @@ to its default state. Requesting a line already in use is an error (**EBUSY**). +Requesting edge detection on a line that does not support interrupts is an +error (**ENXIO**). + +As with the :ref:`line handle`, the +bias configuration is best effort. + Closing the ``chip_fd`` has no effect on existing line events. Configuration Rules diff --git a/Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst index c8256afe306e..9112a9d31174 100644 --- a/Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst +++ b/Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst @@ -76,6 +76,45 @@ If no bias flags are set then the bias configuration is not changed. Requesting an invalid configuration is an error (**EINVAL**). + +.. _gpio-get-linehandle-config-support: + +Configuration Support +--------------------- + +Where the requested configuration is not directly supported by the underlying +hardware and driver, the kernel applies one of these approaches: + + - reject the request + - emulate the feature in software + - treat the feature as best effort + +The approach applied depends on whether the feature can reasonably be emulated +in software, and the impact on the hardware and userspace if the feature is not +supported. +The approach applied for each feature is as follows: + +============== =========== +Feature Approach +============== =========== +Bias best effort +Direction reject +Drive emulate +============== =========== + +Bias is treated as best effort to allow userspace to apply the same +configuration for platforms that support internal bias as those that require +external bias. +Worst case the line floats rather than being biased as expected. + +Drive is emulated by switching the line to an input when the line should not +be driven. + +In all cases, the configuration reported by gpio-get-lineinfo-ioctl.rst +is the requested configuration, not the resulting hardware configuration. +Userspace cannot determine if a feature is supported in hardware, is +emulated, or is best effort. + Return Value ============ diff --git a/Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst b/Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst index 8f1e748dccc8..d002a84681ac 100644 --- a/Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst +++ b/Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst @@ -41,12 +41,13 @@ line or introducing potential glitches. The configuration applies to all requested lines. -The same :ref:`gpio-get-linehandle-config-rules` that apply when requesting the +The same :ref:`gpio-get-linehandle-config-rules` and +:ref:`gpio-get-linehandle-config-support` that apply when requesting the lines also apply when updating the line configuration. The motivating use case for this command is changing direction of bi-directional lines between input and output, but it may be used more -generally move lines seamlessly from one configuration state to another. +generally to 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. diff --git a/Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst index d76e614c8343..56b975801b6a 100644 --- a/Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst +++ b/Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst @@ -74,7 +74,8 @@ If no bias flags are set then the bias configuration is not changed. The edge flags, ``GPIO_V2_LINE_FLAG_EDGE_xxx``, require ``GPIO_V2_LINE_FLAG_INPUT`` to be set and may be combined to detect both rising -and falling edges. +and falling edges. Requesting edge detection from a line that does not support +it is an error (**ENXIO**). Only one event clock flag, ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_xxx``, may be set. If none are set then the event clock defaults to ``CLOCK_MONOTONIC``. @@ -86,11 +87,61 @@ The :c:type:`debounce_period_us` attribute may only be applied to lines with ``GPIO_V2_LINE_FLAG_INPUT`` set. When set, debounce applies to both the values returned by gpio-v2-line-get-values-ioctl.rst and the edges returned by gpio-v2-line-event-read.rst. If not -supported directly by hardware, the debouncing is performed in software by the -kernel. +supported directly by hardware, debouncing is emulated in software by the +kernel. Requesting debounce on a line that supports neither debounce in +hardware nor interrupts, as required for software emulation, is an error +(**ENXIO**). Requesting an invalid configuration is an error (**EINVAL**). +.. _gpio-v2-get-line-config-support: + +Configuration Support +--------------------- + +Where the requested configuration is not directly supported by the underlying +hardware and driver, the kernel applies one of these approaches: + + - reject the request + - emulate the feature in software + - treat the feature as best effort + +The approach applied depends on whether the feature can reasonably be emulated +in software, and the impact on the hardware and userspace if the feature is not +supported. +The approach applied for each feature is as follows: + +============== =========== +Feature Approach +============== =========== +Bias best effort +Debounce emulate +Direction reject +Drive emulate +Edge Detection reject +============== =========== + +Bias is treated as best effort to allow userspace to apply the same +configuration for platforms that support internal bias as those that require +external bias. +Worst case the line floats rather than being biased as expected. + +Debounce is emulated by applying a filter to hardware interrupts on the line. +An edge event is generated after an edge is detected and the line remains +stable for the debounce period. +The event timestamp corresponds to the end of the debounce period. + +Drive is emulated by switching the line to an input when the line should not +be actively driven. + +Edge detection requires interrupt support, and is rejected if that is not +supported. Emulation by polling can still be performed from userspace. + +In all cases, the configuration reported by gpio-v2-get-lineinfo-ioctl.rst +is the requested configuration, not the resulting hardware configuration. +Userspace cannot determine if a feature is supported in hardware, is +emulated, or is best effort. + Return Value ============ 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 index 126c2626ba6b..9b942a8a53ca 100644 --- a/Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst +++ b/Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst @@ -37,7 +37,8 @@ line or introducing potential glitches. The new configuration must specify the configuration of all requested lines. -The same :ref:`gpio-v2-get-line-config-rules` that apply when requesting the lines +The same :ref:`gpio-v2-get-line-config-rules` and +:ref:`gpio-v2-get-line-config-support` that apply when requesting the lines also apply when updating the line configuration. The motivating use case for this command is changing direction of