From nobody Thu Feb 12 17:26:24 2026 Received: from mail-pl1-f173.google.com (mail-pl1-f173.google.com [209.85.214.173]) (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 4AE4F7405A; Mon, 10 Jun 2024 09:23:26 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.214.173 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1718011407; cv=none; b=tbfczKr9JLESXmYGNMHWBpICvBQm9gMJJxLanKPSCf8FK7o0GtpIrGxMQT8y2Y3ls9hCNQQoGWM9FQHOoGWBdxLZBWvnfKfHjxnrHhwTMTxZQVtr7/R/8StEmuI2DfvArC9ktnIpdGYUwG5M6pr4JXtVUl+AfeP8E6QQPkSl7TU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1718011407; c=relaxed/simple; bh=UqifGwsa5V3qAgI3sBE972ce5Y4RiqiZIkr/hHJjXZ8=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=feHMQ3sBGdeldlssgpNcdGjUnWqiVc0zxEy4LRPrzLH97sFnREj/fSGnuucR+tp6/tYoK1LrvnvHPQbyVl7Wg83EQ0dBMomw+VFgHmCmqIzKe0QfGROUStmO22uOVZJ5wbyfOHZOap41IyxqV/y6hWRJVF9jASHBAmRipNY/baU= 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=De/qqiqv; arc=none smtp.client-ip=209.85.214.173 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="De/qqiqv" Received: by mail-pl1-f173.google.com with SMTP id d9443c01a7336-1f6f38b1ab0so9533235ad.1; Mon, 10 Jun 2024 02:23:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1718011405; x=1718616205; 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=LMdqBsK8w4kuL70mSvHWdMfIDmzORHU7zll5kBEl/+4=; b=De/qqiqvG9KDOTqf6rbjVm6tmGUuFBHMlnlulbxbKYudzREdkMsz0zssDwz9MmpUPA oP7G9BjjfOY2R3/8p6wBuCMtbw99mFFX3KGiPJsXVSEQlKuATwCIa1JvlkK5uYElTflU tcwhR+Mn9ZqzgBiuWcWtEkbsjMg8BQzYPI9MZbZCVg46aDeXkGBZ5lIYI55uX3xiIf+z gbj9UdqiRe5Iq1ae/RL2EUfQ3Pgf9HVKZv5iEuH11pG3dexsYccH5RUgTZeAj6xNYNJR NGERbAtPiaKbFjFPaaqGamRP8PLe8KK1z9hTTg8jR+xDgcUpYo4e1fZYtbkieaR6G55s MkzQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1718011405; x=1718616205; 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=LMdqBsK8w4kuL70mSvHWdMfIDmzORHU7zll5kBEl/+4=; b=S41RGq+6DpE4doM+iCvJOe9OW4V/6Ev6GwwzPLWi3fmOtX6/ksu7V331FlTJJisuth q1aiBs3qKuupvwnw9qIoTfUEw5aWQDU4ucaoOCnfJfjGkFon82ILlU5od+zC7sG0P84N hw5pBkDw8JGF5JLVLIKGzV5IMV7Eciss4N4PJs+xXH6Z5BP5Bpk8WX6DrrjMQ5+9k9h5 MbQXB48IwqMDG7r9q7k3iK7/0nooMQzTvyuyKjNL8z4vqV8AQaQP9v1UECbP9cmVUVrP zTOw+NmmTJFmitidPHHZ4kzPDphk7bR8LPeuaMNO6MAfbfe449WIqTS0GbiPdOHZwt03 Z3Iw== X-Forwarded-Encrypted: i=1; AJvYcCWlRIfGHUzge2W260OQoGkiGez6QJEMOFuKMp6415m+opUfwHizz0H8agI1Mm+85roy/1MsLs2w0KcdKLCm3mcA7QK5feMyvyZ1b+Ce/G57jFqNWW2luKLrSxJNAhHdrAP7NNbBkg== X-Gm-Message-State: AOJu0YwblAcsXd7SBcdNZsXIzmTjg9f0XkWjmvvmHCKtNyit91qR1vPq k1ExADqjK72/DhAmms0cgpQu2GsQDxvMTwVvkRJVCvf6OzzaTDWIS6WwqA== X-Google-Smtp-Source: AGHT+IFSeIuTazoVgk+XF0m8e4wO5bbTu4ZSfFPS+19z8TcZqNEv8Ra3K6FGsykJZ2pGzbV9BEp+BA== X-Received: by 2002:a17:902:8c8e:b0:1f6:8290:175a with SMTP id d9443c01a7336-1f6d031cf18mr76950545ad.40.1718011405128; Mon, 10 Jun 2024 02:23:25 -0700 (PDT) Received: from rigel.home.arpa ([118.209.204.19]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-1f6efa2a319sm41318395ad.108.2024.06.10.02.23.22 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Jun 2024 02:23:24 -0700 (PDT) From: Kent Gibson To: linux-kernel@vger.kernel.org, linux-gpio@vger.kernel.org, linux-doc@vger.kernel.org, brgl@bgdev.pl, corbet@lwn.net, drankinatty@gmail.com Cc: Kent Gibson Subject: [PATCH 1/2] Documentation: gpio: Clarify effect of active low flag on line values Date: Mon, 10 Jun 2024 17:21:56 +0800 Message-Id: <20240610092157.9147-2-warthog618@gmail.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240610092157.9147-1-warthog618@gmail.com> References: <20240610092157.9147-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 documentation does not make sufficiently clear that the uAPI deals with logical line values, nor does it describe the influence of the active low flag on the mapping between physical and logical line values. Clarify the relationship between physical and logical line values and the effect of the active low flag for ioctls passing line values. Suggested-by: David C. Rankin Signed-off-by: Kent Gibson --- .../gpio/gpio-handle-get-line-values-ioctl.rst | 7 +++++++ .../gpio/gpio-handle-set-line-values-ioctl.rst | 7 +++++++ .../userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst | 7 +++++++ .../userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst | 7 +++++++ 4 files changed, 28 insertions(+) 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 index 25263b8f0588..2e3a52c113d5 100644 --- a/Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst +++ b/Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst @@ -36,6 +36,13 @@ Description =20 Get the values of all requested lines. =20 +The values returned are logical, indicating if the line is active or inact= ive. +The ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` flag controls the mapping between ph= ysical +values (high/low) and logical values (active/inactive). +If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is not set then high is active and +low is inactive. If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is set then low is a= ctive +and high is inactive. + The values of both input and output lines may be read. =20 For output lines, the value returned is driver and configuration dependent= and 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 index 0aa05e623a6c..12862132b420 100644 --- a/Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst +++ b/Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst @@ -36,6 +36,13 @@ Description =20 Set the values of all requested output lines. =20 +The values set are logical, indicating if the line is to be active or inac= tive. +The ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` flag controls the mapping between lo= gical +values (active/inactive) and physical values (high/low). +If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is not set then active is high and +inactive is low. If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is set then active i= s low +and inactive is high. + Only the values of output lines may be set. Attempting to set the value of input lines is an error (**EPERM**). =20 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 index e4e74a1926d8..d7defd4ca397 100644 --- a/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst +++ b/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst @@ -34,6 +34,13 @@ Description =20 Get the values of requested lines. =20 +The values returned are logical, indicating if the line is active or inact= ive. +The ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` flag controls the mapping between phy= sical +values (high/low) and logical values (active/inactive). +If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` is not set then high is active and low= is +inactive. If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` is set then low is active a= nd +high is inactive. + The values of both input and output lines may be read. =20 For output lines, the value returned is driver and configuration dependent= and 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 index 6d2d1886950b..16dd50fc60ca 100644 --- a/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst +++ b/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst @@ -35,6 +35,13 @@ Description =20 Set the values of requested output lines. =20 +The values set are logical, indicating if the line is to be active or inac= tive. +The ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` flag controls the mapping between log= ical +values (active/inactive) and physical values (high/low). +If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` is not set then active is high and ina= ctive +is low. If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` is set then active is low and +inactive is high. + Only the values of output lines may be set. Attempting to set the value of an input line is an error (**EPERM**). =20 --=20 2.39.2 From nobody Thu Feb 12 17:26:24 2026 Received: from mail-pg1-f173.google.com (mail-pg1-f173.google.com [209.85.215.173]) (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 5F3817406A; Mon, 10 Jun 2024 09:23:40 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.215.173 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1718011421; cv=none; b=QZsRRecUapmVhWUPVRC5UXlayux/h4du6CADwxaiUNi69LkdhzQoSmhKEvcqYwF4YenqOor5Lo7MIGedzpSP2CP8JEWsgtboW7sNJivJ5RbSbi/H8JAhUe6bMJHnk0ENfYHUi74PD5h5jvn3MC959Nq9xdL4lZcGHTlw3rK73us= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1718011421; c=relaxed/simple; bh=MIk+bEBU0QLUp/D8INS2W8Ha6kIdaCi6god1JOJ+eWQ=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=nKhPxgSTyUOHQTlmA4UekbNaTDTTmDJrbbMY7io/cABV0QcPYn81VmCLsoDqM0NfKObpceWSB2EAFJrnGRYoy5n7bSV3dz7IFSLscSm39xqFPUqnu+OgpC4U/69UVHVeb2cQRqWMWzDOUqwaxr45oBxQ0GGo9AVifwjXWvUk1w0= 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=QNe1029m; arc=none smtp.client-ip=209.85.215.173 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="QNe1029m" Received: by mail-pg1-f173.google.com with SMTP id 41be03b00d2f7-652fd0bb5e6so3656334a12.0; Mon, 10 Jun 2024 02:23:40 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1718011419; x=1718616219; 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=URK2Ozhs5KbL4aw49CG/ifndI/mBkWV5rsNcJfrG55c=; b=QNe1029mkxV69vPioEE9fEITcNr8hoi7ar05ONga2XMK+Hs8I+M30TUCbAIw2n3yvm jioRriuxDkcXLfMFFstkvg5NbjSmsytxle50bQpKbugqm02m01eqNY4pv7xkJdOqWzVq M0FMHp7JYltBOcf6b48O33lx8XuFpJZsBNnvWyQAuopi7LkTm7FD9WSAuAm+4LQlUBjQ I0B3y/DiDu1DBghkwzI2BxkqRvVaAmLtj/BlFwk8/Mce+N+XiG+ugSDr/lcrKzfOAwnQ RpnF/7/RQnEEFMt0XKIj4olaUmYku0/Xw34k5+JjEU9s2FAB1WX06Lg38+5qM+7C6Nan qfgg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1718011419; x=1718616219; 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=URK2Ozhs5KbL4aw49CG/ifndI/mBkWV5rsNcJfrG55c=; b=HY9kJSscF64pW7krhbgOH2Y93ObMrslQU3DunAVZaNE9lBh5NpQ1RAuQis06TEkcBg mHrRL/7uwYg0n1T9C+sXGk/5xu/7vtIG6E+Tq17emoUGRC6UEKygjoZlx+TFurIYr/XP pAl2igKczYo0i+BrnkQ2ZSeFWA2TSOwLsnU6VgDqm+rMUzhZ44gUvLNFNrLiEpzpvh9v U1Z1UBTrEcmeuXrmfz8QZ2Jo1CnZTjoMeIg3GSZPwkRNESEr40G/pWjYR0Pyw3mvkztW Bnri7s22t0FDmf8uGIZZPkQFnaV5jfj4VzY97VqzEzO+BoRzGvSBPJMj7IUTKKqo33s2 zLNA== X-Forwarded-Encrypted: i=1; AJvYcCVu4wD9FfhZqMlfgGkmjInVhZ4q+cucALh4pt37itlIsWjDXzdl8JNbuRHflgFvzZc7QIPuX6t0So+YbdC8+PYC2hd2RE+mYpl3XJ2Yfgh3lQdhBR21MiBIYR14HRggBsRtpM513Q== X-Gm-Message-State: AOJu0YzPsvZM6dSLTieo24DuxVd7FQb/2JUGL49OBB+iivU4zeeS3Jnp w3QlgOq684c5c2ZE3Dss3gVEJLCkRf4OE6oeByOXQFOqjvncewWvqth1lg== X-Google-Smtp-Source: AGHT+IEO3yv96Ra6/QmPyXyRqSF9S1kCV/k0qKCG3xgA2PNgHVyBcfDM6auP59WUvB6KjKmv3/UDzg== X-Received: by 2002:a05:6a20:8417:b0:1b2:b60a:a42d with SMTP id adf61e73a8af0-1b2f968d9f8mr10458016637.4.1718011419450; Mon, 10 Jun 2024 02:23:39 -0700 (PDT) Received: from rigel.home.arpa ([118.209.204.19]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-1f6efa2a319sm41318395ad.108.2024.06.10.02.23.36 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Jun 2024 02:23:39 -0700 (PDT) From: Kent Gibson To: linux-kernel@vger.kernel.org, linux-gpio@vger.kernel.org, linux-doc@vger.kernel.org, brgl@bgdev.pl, corbet@lwn.net, drankinatty@gmail.com Cc: Kent Gibson Subject: [PATCH 2/2] Documentation: gpio: Clarify effect of active low flag on line edges Date: Mon, 10 Jun 2024 17:21:57 +0800 Message-Id: <20240610092157.9147-3-warthog618@gmail.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240610092157.9147-1-warthog618@gmail.com> References: <20240610092157.9147-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 documentation does not make sufficiently clear that edge polarity is based on changes to the logical line values, and that the physical polarity of edges is dependent on the active low flag. Clarify the relationship between the active low flag and edge polarity for the functions that read edge events. Suggested-by: David C. Rankin Signed-off-by: Kent Gibson --- .../userspace-api/gpio/gpio-lineevent-data-read.rst | 5 +++++ Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst | 5 +++++ 2 files changed, 10 insertions(+) diff --git a/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst = b/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst index 68b8d4f9f604..d1e7e2383b0d 100644 --- a/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst +++ b/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst @@ -44,6 +44,11 @@ Edge detection must be enabled for the input line using = either both. Edge events are then generated whenever edge interrupts are detected= on the input line. =20 +Edges are defined in terms of changes to the logical line value, so an ina= ctive +to active transition is a rising edge. If ``GPIOHANDLE_REQUEST_ACTIVE_LOW= `` is +set then logical polarity is the opposite of physical polarity, and +``GPIOEVENT_REQUEST_RISING_EDGE`` then corresponds to a falling physical e= dge. + 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()`. diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst b= /Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst index 6513c23fb7ca..1312668e0f6a 100644 --- a/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst +++ b/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst @@ -40,6 +40,11 @@ Edge detection must be enabled for the input line using = either both. Edge events are then generated whenever edge interrupts are detected= on the input line. =20 +Edges are defined in terms of changes to the logical line value, so an ina= ctive +to active transition is a rising edge. If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`= ` is +set then logical polarity is the opposite of physical polarity, and +``GPIO_V2_LINE_FLAG_EDGE_RISING`` then corresponds to a falling physical e= dge. + 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()`. --=20 2.39.2