From nobody Thu Sep 24 13:42:08 2026 Received: from mail-pj2-f13.google.com (mail-pj2-f13.google.com [74.125.227.141]) (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 50DBE42122B for ; Wed, 23 Sep 2026 17:47:35 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=74.125.227.141 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790185658; cv=none; b=Xfec+YhV2rTWEzH7tCLubXgt61aO2zI9/859T1vFcxWA1qvtVDX8JM4c1iaVvtGUWsCPZP0z4Vd/9UQG8cF8ZLWgJfJNEwCXpN8OnParWT3rKQ3Jk1I0e9gQY5mbmwBliEAINq7kuxeVTTGD2wKh5XJ9vLfT89D9LuGxdPK9VZM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790185658; c=relaxed/simple; bh=yVrM8sJaHGXl26LeCM8G7k1yqbumhmWeqCmDq5/L7Os=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=sQtksiFmkLuMRdNnHdu9ClW0Qq8Ot27udcdb4SIgOQJCkLw0AB5W4fT3GPc5yXJ+IoJJcnlEQP2YuR2u7jIWNUwAHA8xsQ5yHmgk7tBwnzSjqj3wrR/42IBUjg2DDPTr3NjA3esOhlJyO4L8vKFZHYCkFUGgmg3CDKruIeuGHKQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=chromium.org; spf=pass smtp.mailfrom=chromium.org; dkim=pass (1024-bit key) header.d=chromium.org header.i=@chromium.org header.b=WIWAqEv6; arc=none smtp.client-ip=74.125.227.141 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=chromium.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=chromium.org header.i=@chromium.org header.b="WIWAqEv6" Received: by mail-pj2-f13.google.com with SMTP id 98e67ed59e1d1-39dbdfaef3cso730808a91.1 for ; Wed, 23 Sep 2026 10:47:35 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; t=1790185653; x=1790790453; 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:content-type; bh=jAVRGQRwud/0zcQSf2CKVKNedLQyxLV6xXHev/2q8II=; b=WIWAqEv6u1l9XVKDQP1FMT2wvYLOp9REyDm5+m0uATBjDFDs1mJ+WJVSvNlpt0RtVL YuQW4QW8FfZCV8pM7pVDbmGhlg872Vyq/s+XoaAZwofyLs9W08rsyhnJOHZn1YqlH+Li 641VuNvd8PMCR1OCBVNLrYPnCtcFPsNIbyrnY= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20260707; t=1790185653; x=1790790453; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to:content-type; bh=jAVRGQRwud/0zcQSf2CKVKNedLQyxLV6xXHev/2q8II=; b=0wAzOpqi1a0wYv2EeXVstEgianVtmTkTf2o8IFXfBTG1wEQXQljH6dX/aVJxW8yC+0 nDy5rYRB30b/JWCIWC11D20C0JONF93adaimktanPIqPy+L0mWmNI+KR81Znz1nrJzBO ++sE2TJkgFqVNnB37EK+OZtt2+JRKCNBFtm8bqMiMUVKCjkZLGbRbkydCFthjPoqIAdy SyZ8aQt3SMOc3mn/3kwbz6r5Pjm2qXskZwmKp2M492URDD2cNOA4l3ZyEDZ9X7IbcEzE DYRiQKogzcAVEK8CGaXUQCpc8glbMT2ATwjhY9nduTr/zIFgJNfp5m9/yFSjB7SczJqj 66bA== X-Forwarded-Encrypted: i=1; AKwUvByzRJtOaalA8RJVUqZ9QZxZV1CHMhRkZ6NCoIKGLtCnDzSomh7zvwlBxrdBe79dPfU5r90xWj5ygA6oPdA=@vger.kernel.org X-Gm-Message-State: AFuF++mmA8QG6QrVUhzOcyi33MVmBkbc8fkaUDSJjTkebSpVwwzrpVap QoKbE6rOKK46zLlhwKMAcN3HTzYKEXZoq2frKIfT7yBtGtk+nJIjxP6ihG7VVGShrQ== X-Gm-Gg: AYBFou03q8/clD5S7uesStnsNEayJKovWaq29TV2y0LEmMg/FL8qeUaZ6H5rkTlZZAP U93W5EW4yy4NuZZzIQ0ZejshdKc/aCYrSZoq+vuf4K31ZUqPB/I1EI16j0Ze+mch90ox4O7Ljrl JJBENh6PoFvCBTGoNkJBvHm84i1z0hdWD+8Hhm31qY+DVAjR4MKDEOaFs4sSfLvCAeA0lwnHT9h 4MUUIZ/LFw2IuqlrL5GTa1qZjpZbdrN2XzyP5C0tIj8YBKDKAiCo56nVzoxsjzIUE1uFp7jioT5 McdFSGzsJbOZkimA5SwShDFtmnog91x0ya+f01N2NpzwINQstcLHEzbK4giH4++jeDbuoSAbbXu 9WAumCoPVKA4hgoe0vRzLfXQQusz+YQ7cUOHe3/k1umh9XsFgH+pS0apNCAp7Pe1txX5u/z8SSZ V8/xiNMjPAZiMA6+Mcq/GsbMcEedlvjE7fmcw3Mj4xaF6EpDQAxd/SQQQMBzo75p2/JlhbCwvfw 8+F/pWDCy05ReUym1rbb0T3DMjOvUX2LU+19A== X-Received: by 2002:a17:90b:37c3:b0:3a0:4146:2954 with SMTP id 98e67ed59e1d1-3a07e6be0b0mr2933474a91.27.1790185653491; Wed, 23 Sep 2026 10:47:33 -0700 (PDT) Received: from localhost ([2a00:79e0:2e7c:8:642b:a4c2:7ea5:5668]) by smtp.gmail.com with UTF8SMTPSA id 98e67ed59e1d1-3a097663e1dsm158337a91.7.2026.09.23.10.47.32 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 23 Sep 2026 10:47:32 -0700 (PDT) From: Brian Norris To: "Rafael J . Wysocki" Cc: linux-doc@vger.kernel.org, linux-pm@vger.kernel.org, Ulf Hansson , Len Brown , Pavel Machek , Doug Anderson , linux-kernel@vger.kernel.org, Brian Norris Subject: [PATCH v2 1/8] PM: runtime: Correct pm_runtime_autosuspend_expiration() doc Date: Wed, 23 Sep 2026 10:40:25 -0700 Message-ID: <20260923104031.v2.1.Ifc8b2d1742729cc82f46220d85c6382fdee1fc8b@changeid> X-Mailer: git-send-email 2.56.0.rc1.310.g51773c2048-goog In-Reply-To: <20260923174711.1283986-1-briannorris@chromium.org> References: <20260923174711.1283986-1-briannorris@chromium.org> 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 "adjusted to be nonzero" comment may be a relic from when this API previously used jiffies, although I'm not quite sure about that either. In any case, it doesn't seem correct today. Signed-off-by: Brian Norris --- Changes in v2: * New in v2 drivers/base/power/runtime.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/drivers/base/power/runtime.c b/drivers/base/power/runtime.c index bb008dfe85a1..7e75f6d5df07 100644 --- a/drivers/base/power/runtime.c +++ b/drivers/base/power/runtime.c @@ -169,7 +169,7 @@ static void pm_runtime_cancel_pending(struct device *de= v) * Compute the autosuspend-delay expiration time based on the device's * power.last_busy time. If the delay has already expired or is disabled * (negative) or the power.use_autosuspend flag isn't set, return 0. - * Otherwise return the expiration time in nanoseconds (adjusted to be non= zero). + * Otherwise return the expiration time in nanoseconds. * * This function may be called either with or without dev->power.lock held. * Either way it can be racy, since power.last_busy may be updated at any = time. --=20 2.56.0.rc1.310.g51773c2048-goog From nobody Thu Sep 24 13:42:08 2026 Received: from mail-pj2-f12.google.com (mail-pj2-f12.google.com [74.125.227.140]) (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 B7C2F42049E for ; Wed, 23 Sep 2026 17:47:36 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=74.125.227.140 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790185659; cv=none; b=YfqB5UZ1h/Hahs6O4tGFFuC09/5FrI8mfjRnwKki9Hze/+e5CmmTB1HNpsQoxoSTrz8Fc1au0VnMQnjh4T044ekim9NgJswGRUVwJEo8RShLI9e3BPcMbJvphul0Bp3WdvcGx5WiliEqA+5JiH2Lk1R4rMukk/qFCw76PJCz8z4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790185659; c=relaxed/simple; bh=0YvB+gKeMCEr52FU8yTn+OnBKkONI3/GywzbBevpz1I=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=dSXlo+8oBR4A2rDHacKptrg27+GAfiXJo3UJaWOfMg93l75Va8Pc00pJTSQcDmyMVkiLcWyuCR8zApD0oCaJ0eG8PfYggv4syXW3dVpdooJhYN5Xzfm9rbW14cSKHoF9mtZRigflco7NS019FQ7HI1pYhKJwbkEF5/VwosCUb7M= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=chromium.org; spf=pass smtp.mailfrom=chromium.org; dkim=pass (1024-bit key) header.d=chromium.org header.i=@chromium.org header.b=PfSyPLXS; arc=none smtp.client-ip=74.125.227.140 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=chromium.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=chromium.org header.i=@chromium.org header.b="PfSyPLXS" Received: by mail-pj2-f12.google.com with SMTP id 98e67ed59e1d1-398c066106cso777293a91.1 for ; Wed, 23 Sep 2026 10:47:36 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; t=1790185655; x=1790790455; 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:content-type; bh=6EyUYM067KGG+izocu2dLZC94FMAj+PnJ7z88RiTQs0=; b=PfSyPLXS0Z+lI2CM4fLhhiYK2nTqq1nLGWAipuVBh8oDa78h4+qkf4i2SfYnTxiIwK yFjyf6eETab1wVYQm5QtpUZRzK9DHG90NVjmct45J82t4alePvssUZ4JleXYtcTMyHsp qC09HR1Fz9oVVhXnUmFU5KIZ5ooom08IPRcZk= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20260707; t=1790185655; x=1790790455; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to:content-type; bh=6EyUYM067KGG+izocu2dLZC94FMAj+PnJ7z88RiTQs0=; b=Uwr/qp4w/Z6+7ytwbCCH3a+ghplthO1a1e3j7TRSYv5elZRp4CyQ8Y16KzpYjTiJPH oV9Z8tJkeT/uQ2iHlYjvjcZaiJef5Kf9pKkG7TrAPp0QvoYazl3Ysm/LaNx/qcx1rCvu 6jjrBcP1+NAe+IpYEqToX8P6Em2T7DosWd11+r3NSBTlZVTZAUiaQgbtZRwC4Y+mIy2V 0e/a8B+K/Bqd6sJrZ8zdIY0HbqVener+5aDyoThhg0josp00lZgJFPU0XuWtX8fZpHy4 kP8LBEfMpX+lOT87vY4S2avQ67LQNarUjw1PolrddIfDs26PrOdLrio+/EtRMLEXsha9 N/og== X-Forwarded-Encrypted: i=1; AKwUvBwtfAzs3M1orHV+LnO+6zt5KrnWiwX2UiT1WK4ukV25qz/L/WB6A2eVeOiKTxe1txtpwPuz+ZEI3SqS+E4=@vger.kernel.org X-Gm-Message-State: AFuF++nh2WNy3C9hMu4MY9OQzWxofxmGNfl86s3SnDwv+vritRnQ0vRN 2GRskFqOHN8O/4wfZKUZhwM8Cnd7fXQ7xIRdHvjIlVEsxat6sqVYThuMnk2J5rOGjA== X-Gm-Gg: AYBFou2g4v2jspfFYyOZvmW8Y75fiwcBMrnO9Kh2EY+fnCXxtK89NeZnYBPmtlCidAF CMaZgvuXUOKHrcEnby2/FhOsKq6wzV/vwLEfLuVPTQCnUj3ND0hcRrr6YCL8PvPGVZMwVrQGeFH 5UI0oob1tw0/IsCeIth+Vhfr50NS+dODu4f/j026e1Yd4nggCAmU/EJWng6HIDpdBth+yUlG6kH zNaDzW/Wjcheq9F5Tg9g5di2hiO6vjuSp4rO0rWf12cR1+CVmlED2j7YZbvrMSQuC3ooaIZgW89 F20kSdgu1j/6mYn6Gy7ptDdGdnbxjF5sYT6hFVzP1TECvurwf1brPEAD4MB22iqPSe/v88QcDYb uue4ateIZ+6xXFtzaxeNOoM+j4x8GHJYklbdLKVml6wuPdIMhAREgwiRXyb854IPW4x6i4tNfS/ gRsRkB1UuDbBS+F9xBmQRyXKfIrxTqQVifkXAeJCclMOxhnzY36yJQKcdQekkmDXvzz4o7RK01l Of3k9ZIt0gxL8ff30h5q8QxIFRrueP8jun6Vg== X-Received: by 2002:a17:90b:258b:b0:39d:f66e:1720 with SMTP id 98e67ed59e1d1-3a07e54e52fmr3089413a91.13.1790185655638; Wed, 23 Sep 2026 10:47:35 -0700 (PDT) Received: from localhost ([2a00:79e0:2e7c:8:642b:a4c2:7ea5:5668]) by smtp.gmail.com with UTF8SMTPSA id 98e67ed59e1d1-3a09773d402sm137703a91.16.2026.09.23.10.47.34 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 23 Sep 2026 10:47:35 -0700 (PDT) From: Brian Norris To: "Rafael J . Wysocki" Cc: linux-doc@vger.kernel.org, linux-pm@vger.kernel.org, Ulf Hansson , Len Brown , Pavel Machek , Doug Anderson , linux-kernel@vger.kernel.org, Brian Norris Subject: [PATCH v2 2/8] PM: runtime: More kerneldoc formatting Date: Wed, 23 Sep 2026 10:40:26 -0700 Message-ID: <20260923104031.v2.2.Ia1cae8a40a24662df11553c225f4438eab65b7db@changeid> X-Mailer: git-send-email 2.56.0.rc1.310.g51773c2048-goog In-Reply-To: <20260923174711.1283986-1-briannorris@chromium.org> References: <20260923174711.1283986-1-briannorris@chromium.org> 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" In taking another pass at these docs, I found some more inconsistencies. Signed-off-by: Brian Norris --- Changes in v2: * New in v2 drivers/base/power/runtime.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/drivers/base/power/runtime.c b/drivers/base/power/runtime.c index 7e75f6d5df07..dce7b6ff7e9d 100644 --- a/drivers/base/power/runtime.c +++ b/drivers/base/power/runtime.c @@ -1255,7 +1255,7 @@ static int pm_runtime_get_conditional(struct device *= dev, bool ign_usage_count) =20 /** * pm_runtime_get_if_active - Bump up runtime PM usage counter if the devi= ce is - * in active state + * in active state. * @dev: Target device. * * Increment the runtime PM usage counter of @dev if its runtime PM status= is @@ -1635,10 +1635,10 @@ static void pm_runtime_disable_action(void *data) /** * devm_pm_runtime_enable - devres-enabled version of pm_runtime_enable. * + * @dev: Device to handle. + * * NOTE: this will also handle calling pm_runtime_dont_use_autosuspend() f= or * you at driver exit time if needed. - * - * @dev: Device to handle. */ int devm_pm_runtime_enable(struct device *dev) { --=20 2.56.0.rc1.310.g51773c2048-goog From nobody Thu Sep 24 13:42:08 2026 Received: from mail-pj2-f13.google.com (mail-pj2-f13.google.com [74.125.227.141]) (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 231514218B6 for ; Wed, 23 Sep 2026 17:47:38 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=74.125.227.141 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790185661; cv=none; b=EBCQjqb1wlvzo6uz9BZ1emK2ebVR3lH+H0fyeO98n4481gSIcbsvhQncpXluv+9JEvKFw9N9M6H/cZU6aMp9FpYJEIpR7W0MmtRWCov7sSXz59vLR/rjntpTbqXyFz4S8MhoL8EbeoXj13oU30JQ15PsqUrqCMJko6gprxyHFsE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790185661; c=relaxed/simple; bh=HNhAwhGiJI8XpQjGibl8SR8njJRmYfryO09H5BYfZ0Y=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=gyu+azwUKkBWC+6gIA97lcrntM+OxU+5mGLSkjI14cpBMOocIAH5QLgi6+tR22svoberxkIqiPzdh8WUZdOR20D+Ew7edoCpYO9xfUjVWcOBO54cRtRaK5vPa6AuEdXAlh/+4PBctbkHrPrljN8v3P+1x5MwvkoicLKxiR1slOQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=chromium.org; spf=pass smtp.mailfrom=chromium.org; dkim=pass (1024-bit key) header.d=chromium.org header.i=@chromium.org header.b=P0wM+/QW; arc=none smtp.client-ip=74.125.227.141 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=chromium.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=chromium.org header.i=@chromium.org header.b="P0wM+/QW" Received: by mail-pj2-f13.google.com with SMTP id d9443c01a7336-2d8fdc579daso8405745ad.1 for ; Wed, 23 Sep 2026 10:47:38 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; t=1790185658; x=1790790458; 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:content-type; bh=F0FUTmKiKSraH2afuGbds8iMVikboWrVQOvL7iyG9Nc=; b=P0wM+/QWSeSzVyi+YQHCnDGANsNcwPJJsHTgEi4hdmql28QdXn9Kjr4zBZMvTkX8BE u28GTzBIkB9DHaRss7CGqt7LiKctj4yRuSdIiwaFMnKd4+Uis4AxvembmsniVYNlfJvm lOUPV676Yv/+nRPthUxAObnMIMjhTqfnk3qpc= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20260707; t=1790185658; x=1790790458; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to:content-type; bh=F0FUTmKiKSraH2afuGbds8iMVikboWrVQOvL7iyG9Nc=; b=iHh50iG1+W+8xuBctw1ENxdGZsU6weU1mwK1wpyOtqxMBYNwFcNwVTueBQw6gtWj0z 1EKFN4/Nc5Ta5+GyLIDZ7sYsv+S0or8/OgJQrMkv50MjuzIW5zSSkOn4Hg1r8ozC+9y/ 3wlg+0Jqj4Xjumxn7GvS29Wnhg6BsPi2QOVlrdhRVbiOEdhkPl0rqt+FojDje9/mq2Ca CjzE3rbjssm3+CGC1pjtPPR79gjGSA3Ym3kLeXxIQqrwuH1LlP2sIHZi8dpRXfR7g1ai Kcm0w59LynevP746Q76o4oBHUMcv3GMW1YEzeD9K23Xpij1ySouc/9fFK3zK2tEBCgKP FbIQ== X-Forwarded-Encrypted: i=1; AKwUvBy2fhbRFFRJqrRpp+K2U+D/G7Wkz1IyK7Nz5vhNsHDG25D8WVbXJeQ1d4/+w8+sS1dAZvWJ0KH5yBmGwY4=@vger.kernel.org X-Gm-Message-State: AFuF++mCnxe1Wu6WEr4OPC369bgdtz8/tKA0WdxvZAbsQNhaNEmjkXu4 z9q4I+OoaVHVHYWht3XzArQremfUnAoBd272SRtq3FI9XpyEFPBTI71SLM9x4QVs6w== X-Gm-Gg: AYBFou1R2BelTLZ0vlXoiKV5G4SHMtkwgVvKEp2V1farmLtqK1cHwQ13zzQ0LLTK8So IpgKpaISdP2umj4HaIKQPpCd1+tkR+HT+6bsMc65zxzVWps+abVOyUUHNVFOf7Myk2d9x+RZURl KeFh+9I2sEwgvhz2dlbqC6FaCoZIQAC0d+hubYkARI0wnBlAK4b2NeUS2wdLwUXDaM7BzCb5gJt jEC9vDTqKRe7KkaPLikobUyTAuvbb7He+JMl55vhjdnb/60mIjMzOWBqjt5wibzDbaI9iP4s6Nz 7HFy9S+nENwvbDNexX3rkKj1Kvw0VHitg1tvyvSnP9XpR8EXthRSYcQXd4KkMN16R2w5wr05fV8 ZguMkVRKD/DdrSfwMSw+nmQbOIHvfyFuZhIRxsbiHAiLIZEan2ezfnqAiuYMOAUd7vsrTLmnO3M D92TSPKjJEAXw6pvEpuWXXWgFNqNsof9E9G0BhW0ZwBolr9oEquv7WPEpD6COyPzirabUb4rwNH MbUQtzheiZjV883w4VZvfQ/K2MrCpYjEB/6+84NIcI4rTSo X-Received: by 2002:a17:902:ec81:b0:2dd:c100:3140 with SMTP id d9443c01a7336-2df69e015c9mr32107685ad.60.1790185658348; Wed, 23 Sep 2026 10:47:38 -0700 (PDT) Received: from localhost ([2a00:79e0:2e7c:8:642b:a4c2:7ea5:5668]) by smtp.gmail.com with UTF8SMTPSA id d9443c01a7336-2df6a60cc52sm15320815ad.83.2026.09.23.10.47.36 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 23 Sep 2026 10:47:37 -0700 (PDT) From: Brian Norris To: "Rafael J . Wysocki" Cc: linux-doc@vger.kernel.org, linux-pm@vger.kernel.org, Ulf Hansson , Len Brown , Pavel Machek , Doug Anderson , linux-kernel@vger.kernel.org, Brian Norris Subject: [PATCH v2 3/8] PM: runtime: Misc improvements to runtime_pm.rst Date: Wed, 23 Sep 2026 10:40:27 -0700 Message-ID: <20260923104031.v2.3.I383681b22c12d7caee976cb91aa90d1a94d4a591@changeid> X-Mailer: git-send-email 2.56.0.rc1.310.g51773c2048-goog In-Reply-To: <20260923174711.1283986-1-briannorris@chromium.org> References: <20260923174711.1283986-1-briannorris@chromium.org> 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" There are several small errors and omissions, as well as new updates (pm_runtime_resume_and_get(), devm_pm_runtime_enable()) we should incorporate. Signed-off-by: Brian Norris --- (no changes since v1) Documentation/power/runtime_pm.rst | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/Documentation/power/runtime_pm.rst b/Documentation/power/runti= me_pm.rst index 39fdeeda7a1e..352cdaf0650d 100644 --- a/Documentation/power/runtime_pm.rst +++ b/Documentation/power/runtime_pm.rst @@ -238,6 +238,9 @@ It is safe to execute the following helper functions fr= om interrupt context: - pm_runtime_set_active() - pm_runtime_set_suspended() - pm_runtime_suspended() +- pm_runtime_active() +- pm_runtime_status_suspended() +- pm_runtime_enabled() - pm_runtime_mark_last_busy() - pm_runtime_autosuspend_expiration() =20 @@ -249,6 +252,7 @@ functions may also be used in interrupt context: - pm_runtime_autosuspend() - pm_runtime_resume() - pm_runtime_get_sync() +- pm_runtime_resume_and_get() - pm_runtime_put_sync() - pm_runtime_put_sync_suspend() - pm_runtime_put_sync_autosuspend() @@ -258,7 +262,7 @@ functions may also be used in interrupt context: =20 Initially, the runtime PM is disabled for all devices, which means that the majority of the runtime PM helper functions described in Section 4 will re= turn --EAGAIN until pm_runtime_enable() is called for the device. +-EACCES until pm_runtime_enable() is called for the device. =20 In addition to that, the initial runtime PM status of all devices is 'suspended', but it need not reflect the actual physical state of the devi= ce. @@ -287,7 +291,7 @@ enabled earlier by calling pm_runtime_enable(). =20 Note, if the device may execute pm_runtime calls during the probe (such as if it is registered with a subsystem that may call back in) then the -pm_runtime_get_sync() call paired with a pm_runtime_put() call will be +pm_runtime_resume_and_get() call paired with a pm_runtime_put() call will = be appropriate to ensure that the device is not put back to sleep during the probe. This can happen with systems such as the network device layer. =20 @@ -315,7 +319,10 @@ removal of their drivers. =20 Drivers in ->remove() callback should undo the runtime PM changes done in ->probe(). Usually this means calling pm_runtime_disable(), -pm_runtime_dont_use_autosuspend() etc. +pm_runtime_dont_use_autosuspend() etc. Alternatively, drivers can use +devm_pm_runtime_enable() during probe, which automatically takes care of +calling pm_runtime_disable() and pm_runtime_dont_use_autosuspend() upon dr= iver +detachment. =20 The user space can effectively disallow the driver of the device to power = manage it at run time by changing the value of its /sys/devices/.../power/control @@ -426,7 +433,7 @@ out the following operations: =20 Subsystems may wish to conserve code space by using the set of generic pow= er management callbacks provided by the PM core, defined in -driver/base/power/generic_ops.c: +drivers/base/power/generic_ops.c: =20 .. kernel-doc:: drivers/base/power/generic_ops.c :export: @@ -441,8 +448,8 @@ subsystem-level dev_pm_ops structure. Device drivers that wish to use the same function as a system suspend, fre= eze, poweroff and runtime suspend callback, and similarly for system resume, th= aw, restore, and runtime resume, can achieve similar behaviour with the help o= f the -DEFINE_RUNTIME_DEV_PM_OPS() defined in include/linux/pm_runtime.h (possibl= y setting its -last argument to NULL). +DEFINE_RUNTIME_DEV_PM_OPS() macro defined in include/linux/pm_runtime.h +(possibly setting its last argument to NULL). =20 8. "No-Callback" Devices =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -505,7 +512,7 @@ registration the length should be controlled by user sp= ace, using the =20 In order to use autosuspend, subsystems or drivers must call pm_runtime_use_autosuspend() (preferably before registering the device), a= nd -thereafter they should use the various `*_autosuspend()` helper functions +thereafter they should use the various \*_autosuspend() helper functions instead of the non-autosuspend counterparts:: =20 Instead of: pm_runtime_suspend use: pm_runtime_autosuspend; @@ -515,7 +522,7 @@ instead of the non-autosuspend counterparts:: =20 Drivers may also continue to use the non-autosuspend helper functions; they will behave normally, which means sometimes taking the autosuspend delay i= nto -account (see pm_runtime_idle). The autosuspend variants of the functions a= lso +account (see pm_runtime_idle()). The autosuspend variants of the functions= also call pm_runtime_mark_last_busy(). =20 Under some circumstances a driver or subsystem may want to prevent a device @@ -558,7 +565,7 @@ Here is a schematic pseudo-code example:: =20 int foo_runtime_suspend(struct device *dev) { - struct foo_priv foo =3D container_of(dev, ...); + struct foo_priv *foo =3D container_of(dev, ...); int ret =3D 0; =20 lock(&foo->private_lock); @@ -574,7 +581,7 @@ Here is a schematic pseudo-code example:: =20 int foo_runtime_resume(struct device *dev) { - struct foo_priv foo =3D container_of(dev, ...); + struct foo_priv *foo =3D container_of(dev, ...); =20 lock(&foo->private_lock); /* ... resume the device ... */ --=20 2.56.0.rc1.310.g51773c2048-goog From nobody Thu Sep 24 13:42:08 2026 Received: from mail-pz2-f12.google.com (mail-pz2-f12.google.com [74.125.228.12]) (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 BEBDA421244 for ; Wed, 23 Sep 2026 17:47:43 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=74.125.228.12 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790185666; cv=none; b=oim449MWlfzOLLzyx2P1JkrhfiuyrFheTZwBWmGdFtYgfdIAAcyQTIXf/zprLEei42gTZbF4W/jX9FRn8JnAmBfsZTjfCdojF6xWWGli5VDheTbAVD5urnu5StOxYX6wSZEq2svjzMnKAIQjpRF76nMaAP6iarx2GXNSIdX+5BU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790185666; c=relaxed/simple; bh=2BonED8RnAqLes9QDCALEvgg2CW7qcUbWR78q6mNvsQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=ZaWgSY7xtJNvWqv0dbcsC+LohrtSspe7LRowJ6LSH3Tf4dHNqzoMOAsyoNKrV21q/KlDcfGvRf6LrCXD0//4Iy+WW2SB8hHFjpugdqFE78rqOamllD8iVpyqKiTMikmmmrcOszGSpUnKkYbIgA1BVybSKP/+kyiP7D2atZGXZc8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=chromium.org; spf=pass smtp.mailfrom=chromium.org; dkim=pass (1024-bit key) header.d=chromium.org header.i=@chromium.org header.b=PaN2aWOi; arc=none smtp.client-ip=74.125.228.12 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=chromium.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=chromium.org header.i=@chromium.org header.b="PaN2aWOi" Received: by mail-pz2-f12.google.com with SMTP id 41be03b00d2f7-cc1cebad4aeso671803a12.2 for ; Wed, 23 Sep 2026 10:47:43 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; t=1790185663; x=1790790463; 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:content-type; bh=e9iFgQ0s/mszVKUPGKbaxhv7W2jRsjbdiTzglblCdQc=; b=PaN2aWOimi3oPnarGVs15gLb/h73S1FSxCn8IWNVVzlqMNb99z/37L4FNukD7v84Ri tJ6Dd+3bLv6F+AfChI2ht02Eu5MXO6fgqwZe1rNlM3pcd7wcynNb1hsaTgax5PRgXZu2 s9yHgr56d7BB8cYOsqFvrb+108nyYJuiMxWqQ= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20260707; t=1790185663; x=1790790463; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to:content-type; bh=e9iFgQ0s/mszVKUPGKbaxhv7W2jRsjbdiTzglblCdQc=; b=XGxc8CIbWkJiDBUgpPqLjl0LXI/L533cBTCseuZdQleJsg6PbiigB+uSyZrOWbBFsB fm6Kx1PMrOWW7ExzsT+sVo8U/mVM+49ftXLWza7h/3dlKXSCXEeg7IGgUp7A4bOzXMkp bh/5QhsTCmwJlcIff9gl+bzKQ/A6vz/lsSNKm92FHr5hLAI84I2UWiqt3BGGfP4xDv34 diYBKEARfsyeBRMuB/Q5CwTKck7F61FAmICTw1xdwZaTzP6aC67VM4p3VbLExwKrU1/D TDuZF25BMOp9e2Q5OjqmmotrNbt01rZJq4BxEylEhDyoNqepsPVfxhUJyqIbFguza7KU Q3Gw== X-Forwarded-Encrypted: i=1; AKwUvByDd699CcmO2iuT+GxLWmss7Dx6kwZa6z/SFin0hVDGtWLP2tcTW/7qIjUskyNBRjfijEs9n1f9urlbXjs=@vger.kernel.org X-Gm-Message-State: AFuF++nNupiQ3EbRNW42XqLhzuhDjx8BaL9u+oUJeATMZkQ6z/SdWHKg jNgA4WWmELXsw8kM+rbGfAohZ76mPAKeLxKnfdqZwjfQ0A2AoBoPiE1gI5Tw9kc9gA== X-Gm-Gg: AYBFou1w8b6eV7APoLGtxUjIA6xdPK888mGVxMUBItIqLcBg5loK2DKFBUCmGDUrrFr 4papcTyIRxqilnoJrhQMjixAsqqNV9/bgei5ktioFmTgvvRQC1soJZMbcIHhlcrGxlcQk/+ZEZX lSvjpJ1rjETmngxn1mnO7bybg5ucGw357mtjgnwNZZWUx6mHhLdhFMWFZ2dKGU90+0axjxEWR1a ZbfP7rj6dXiLQyzSyJjKs9i/qK1qPSDXWuRpBN7u7uci99XDs9IOQ+bKwjBZcUtj2ZA3NXcyv5g bQ8wAi8BTz8saqaGEiSC5hSrWaGhgvU7eKOSnWtQMGrvsive/lwHNa7K7AC2wO1emg1RAhKk9QK 65YG1gsMNa++2ZDQp3jR+NDF37wnQhre06X6nrIiGsNciVFfc/pgkNT53C042W20yWYYVfgfIDE l8AEZAaizNm9UHfECA0XITBP1Fd8S30sJijRy1o2dZsEsfPNtjyhJuRPGFvzpjYBCUIYQnKWa9v 8ygyhOo3d6vBitD0v6e0q9XZ1O6NssfFDw8V0TVhlvOjQBtug== X-Received: by 2002:a05:6a20:734b:b0:3dd:a197:cf36 with SMTP id adf61e73a8af0-3ddf82e3484mr3304445637.90.1790185662903; Wed, 23 Sep 2026 10:47:42 -0700 (PDT) Received: from localhost ([2a00:79e0:2e7c:8:642b:a4c2:7ea5:5668]) by smtp.gmail.com with UTF8SMTPSA id 41be03b00d2f7-cc75f21f530sm1499260a12.2.2026.09.23.10.47.39 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 23 Sep 2026 10:47:40 -0700 (PDT) From: Brian Norris To: "Rafael J . Wysocki" Cc: linux-doc@vger.kernel.org, linux-pm@vger.kernel.org, Ulf Hansson , Len Brown , Pavel Machek , Doug Anderson , linux-kernel@vger.kernel.org, Brian Norris Subject: [PATCH v2 4/8] PM: runtime: Add "Section" hyperlinks Date: Wed, 23 Sep 2026 10:40:28 -0700 Message-ID: <20260923104031.v2.4.I7666a5802ea59359afce4ff7d0b1af668e5f5292@changeid> X-Mailer: git-send-email 2.56.0.rc1.310.g51773c2048-goog In-Reply-To: <20260923174711.1283986-1-briannorris@chromium.org> References: <20260923174711.1283986-1-briannorris@chromium.org> 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 reStructuredText targets for each section, and use them throughout to make the generated HTML more navigable. Signed-off-by: Brian Norris --- Changes in v2: * Rebase to put this earlier in the series Documentation/power/runtime_pm.rst | 48 ++++++++++++++++++++---------- 1 file changed, 33 insertions(+), 15 deletions(-) diff --git a/Documentation/power/runtime_pm.rst b/Documentation/power/runti= me_pm.rst index 352cdaf0650d..114c4a872cb1 100644 --- a/Documentation/power/runtime_pm.rst +++ b/Documentation/power/runtime_pm.rst @@ -8,6 +8,8 @@ Runtime Power Management Framework for I/O Devices =20 (C) 2014 Intel Corp., Rafael J. Wysocki =20 +.. _Section 1: + 1. Introduction =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 @@ -37,6 +39,8 @@ The runtime PM callbacks present in 'struct dev_pm_ops', = the device runtime PM fields of 'struct dev_pm_info' and the core helper functions provided for runtime PM are described below. =20 +.. _Section 2: + 2. Device Runtime PM Callbacks =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D =20 @@ -80,8 +84,8 @@ the PM core that it is safe to run the ->runtime_suspend(= ), ->runtime_resume() and ->runtime_idle() callbacks for the given device in atomic context with interrupts disabled. This implies that the callback routines in question = must not block or sleep, but it also means that the synchronous helper functions -listed at the end of Section 4 may be used for that device within an inter= rupt -handler or generally in an atomic context. +listed at the end of `Section 4`_ may be used for that device within an +interrupt handler or generally in an atomic context. =20 The subsystem-level suspend callback, if present, is _entirely_ _responsib= le_ for handling the suspend of the device as appropriate, which may, but need= not @@ -105,9 +109,9 @@ knows what to do to handle the device). =20 * If the suspend callback returns an error code different from -EBUSY and -EAGAIN, the PM core regards this as a fatal error and will refuse to = run - the helper functions described in Section 4 for the device until its s= tatus - is directly set to either 'active', or 'suspended' (the PM core provi= des - special helper functions for this purpose). + the helper functions described in `Section 4`_ for the device until its + status is directly set to either 'active', or 'suspended' (the PM core + provides special helper functions for this purpose). =20 In particular, if the driver requires remote wakeup capability (i.e. hardw= are mechanism allowing the device to request a change of its power state, such= as @@ -132,10 +136,10 @@ what to do to handle the device). 'active'. =20 * If the resume callback returns an error code, the PM core regards this= as a - fatal error and will refuse to run the helper functions described in S= ection - 4 for the device, until its status is directly set to either 'active',= or - 'suspended' (by means of special helper functions provided by the PM c= ore - for this purpose). + fatal error and will refuse to run the helper functions described in + `Section 4`_ for the device, until its status is directly set to either + 'active', or 'suspended' (by means of special helper functions provide= d by + the PM core for this purpose). =20 The idle callback (a subsystem-level one, if present, or the driver one) is executed by the PM core whenever the device appears to be idle, which is @@ -158,9 +162,9 @@ call to pm_runtime_autosuspend(). To prevent this (for = example, if the callback routine has started a delayed suspend), the routine must return a non-zero value. Negative error return codes are ignored by the PM core. =20 -The helper functions provided by the PM core, described in Section 4, guar= antee -that the following constraints are met with respect to runtime PM callback= s for -one device: +The helper functions provided by the PM core, described in `Section 4`_, +guarantee that the following constraints are met with respect to runtime PM +callbacks for one device: =20 (1) The callbacks are mutually exclusive (e.g. it is forbidden to execute ->runtime_suspend() in parallel with ->runtime_resume() or with another @@ -200,6 +204,8 @@ rules: scheduled requests to execute the other callbacks for the same device, except for scheduled autosuspends. =20 +.. _Section 3: + 3. Runtime PM Device Fields =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D =20 @@ -210,6 +216,8 @@ state. .. kernel-doc:: include/linux/pm.h :identifiers: dev_pm_info =20 +.. _Section 4: + 4. Runtime PM Device Helper Functions =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 =20 @@ -257,12 +265,14 @@ functions may also be used in interrupt context: - pm_runtime_put_sync_suspend() - pm_runtime_put_sync_autosuspend() =20 +.. _Section 5: + 5. Runtime PM Initialization, Device Probing and Removal =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=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D =20 Initially, the runtime PM is disabled for all devices, which means that the -majority of the runtime PM helper functions described in Section 4 will re= turn --EACCES until pm_runtime_enable() is called for the device. +majority of the runtime PM helper functions described in `Section 4`_ will +return -EACCES until pm_runtime_enable() is called for the device. =20 In addition to that, the initial runtime PM status of all devices is 'suspended', but it need not reflect the actual physical state of the devi= ce. @@ -285,7 +295,7 @@ pm_runtime_set_suspended(). If the default initial runtime PM status of the device (i.e. 'suspended') reflects the actual state of the device, its bus type's or its driver's ->probe() callback will likely need to wake it up using one of the PM core= 's -helper functions described in Section 4. In that case, pm_runtime_resume() +helper functions described in `Section 4`_. In that case, pm_runtime_resu= me() should be used. Of course, for this purpose the device's runtime PM has t= o be enabled earlier by calling pm_runtime_enable(). =20 @@ -336,6 +346,8 @@ value of /sys/devices/.../power/control to "auto" to al= low the driver to power manage the device at run time, the driver may confuse it by using pm_runtime_forbid() this way. =20 +.. _Section 6: + 6. Runtime PM and System Sleep =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D =20 @@ -428,6 +440,8 @@ out the following operations: callback and right after executing the subsystem-level .complete() cal= lback for it, respectively. =20 +.. _Section 7: + 7. Generic subsystem callbacks =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D =20 @@ -451,6 +465,8 @@ restore, and runtime resume, can achieve similar behavi= our with the help of the DEFINE_RUNTIME_DEV_PM_OPS() macro defined in include/linux/pm_runtime.h (possibly setting its last argument to NULL). =20 +.. _Section 8: + 8. "No-Callback" Devices =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 @@ -487,6 +503,8 @@ in subsystems/drivers, the PM core allows runtime PM ca= llbacks to be unassigned. More precisely, if a callback pointer is NULL, the PM core wil= l act as though there was a callback and it returned 0. =20 +.. _Section 9: + 9. Autosuspend, or automatically-delayed suspends =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=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 --=20 2.56.0.rc1.310.g51773c2048-goog From nobody Thu Sep 24 13:42:08 2026 Received: from mail-pz2-f43.google.com (mail-pz2-f43.google.com [74.125.228.43]) (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 E999A41DEDF for ; Wed, 23 Sep 2026 17:47:46 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=74.125.228.43 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790185668; cv=none; b=HHxxdFYC8/chDS4F+IlQBPPP0vzRinbf4c8/WkpuBsJiCQR14iNseN9HOd40rQDmQ+GrJCmtqLeEjqhisSApvwAPClI8t1hh9C3qTBhrZGzs8Eca4Zu7lA4BqU9nsxrIM3OGQ5cGuz1+kK5iqX1Ya2eSn3UzBscKCO6iyvN422M= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790185668; c=relaxed/simple; bh=n6MwkDMMmdyC7Dq+zcQ57KcdXHon0jUo2EcFcUF/B/s=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=k7La8+5nbAdqQv4g72n65sD0Ep24AY6+xAjTGRFCiemzMMpYBaKZSvLqGjP6/Oh4ridUD6Zeo+YWwBhVD83Q3awHqhF3Z9FYynBS2qpNGd1ooyduRaFF8xJr1FFNgXvkFxBZD1d6tVoGliqzkjEEVAg8Lr2WedhLwWLmZAkLePo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=chromium.org; spf=pass smtp.mailfrom=chromium.org; dkim=pass (1024-bit key) header.d=chromium.org header.i=@chromium.org header.b=GgvcH/p5; arc=none smtp.client-ip=74.125.228.43 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=chromium.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=chromium.org header.i=@chromium.org header.b="GgvcH/p5" Received: by mail-pz2-f43.google.com with SMTP id d2e1a72fcca58-85469e25187so550154b3a.2 for ; Wed, 23 Sep 2026 10:47:46 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; t=1790185666; x=1790790466; 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:content-type; bh=XdnundYlcaGdSnMUNx2jzVtyM7k47JsxnQCk7S9RVjw=; b=GgvcH/p5346HEawsy0JGKsAHE70EAhAMYTxamZ9JMrvMarXvx7U5LPAwMT96RMHCRW zcL2DC3nk//tbPB+OrZ3wnVAN7oCa8R8qyM6HHn223G7TXTQbxeIj4WBN4mQCJTdatzX eDLYKhf12zepHgIYjqKbbRN2Tf7tn9IupLv3I= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20260707; t=1790185666; x=1790790466; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to:content-type; bh=XdnundYlcaGdSnMUNx2jzVtyM7k47JsxnQCk7S9RVjw=; b=aZcW6rUNVCrLBUZHk+b67V8PJOpJ+L73j1KjfFEPgPkjZocjQappyPs83Rem2FdpFm B1OdSObaxcjfb2XXCFLPxqtCzyzdnPn5ILErWnrKK7V4Bp5HGoSHUg+/AZ/6+O3R6RXA uCzAFnH5QIERQzOslMlEBFuIOsuFLZmf2FJgFlOJJ6LjJ0/ORBWaahHARDtex3ZhpRDh iN25QVuZe5WTNopXoPg1pWTIo0MN7a203R0fejz1qR/n5J+z5tu9TlTfhvUhema/vZ5N objjauGezwHKiYJ6clfL2om3BmUH1xp9qjYjcmK3zlOrQRB/gHUhREchJajuITn3Rkgx bYCw== X-Forwarded-Encrypted: i=1; AKwUvBzn353Lc4PDGQh9GPD2uYFZhop+znjWNrVwv72rK25x33YHE7z1cYlntZY/ve/h2y3kMcjP2UU+8JsZfp0=@vger.kernel.org X-Gm-Message-State: AFuF++knw02+o/C1mXSfFPE5rj1woVBovZwObQp9gln2cl8j46Pyz6h8 ZYMyovlJir9UWbWLW/ymlYfU6/wj4cUmnBerpJPMILrnoBRKyV1WBu1Frku/35wv9g== X-Gm-Gg: AYBFou2rKrkXgQVeFDzYZKRI2Ap7TMz3O91w+VLmAyFkOTVrfggP6VXVA0yY3IyY9Ma 1NfX2SNYQd67zlsE7wbl2bkSNVBK/9Li5Epm24EiRmy5zzODxoIr+Y/730k4+zPRZI5IzS+TKWX 41GGNP9ePKCKkLIB+PCPPzBM9rlFhqzej2qr9DmCp4z23E/sPlOXIEGbnI88vhW81b1N2ujEeas DnU6Vs08ur0dYCkMG4xvRxytQtiP28VHqtl+fhOTu75PEKEhC2uDg7SqTjaY+zpwZF/LLFmaRQa scEBfLtMma8WXI6xb9LaO++vdDlZ/DnpOrIjVBuBfoSd9e/34o4erfEcQRuNh261l1tR6IkOX2W x/oNWF2UicK5yM64CX5xFnWMrafWmtlTYPJ5hwMttrKQiGfcJq1tmY60VEoNzgcH1GFMEqxLLXo EJc639H+FZolPukZWbnhDT0cWIVFbu5ZcvZ7ou7J44ikgUR7lrloYi88nvohNAphFWpJd29kxBl 8wws5VtkDhDGnwEdGW0COF28xZ2UOkfdAcK+Q== X-Received: by 2002:a05:6a00:887:b0:87b:b799:370d with SMTP id d2e1a72fcca58-87d1a0b08d8mr2987166b3a.9.1790185666306; Wed, 23 Sep 2026 10:47:46 -0700 (PDT) Received: from localhost ([2a00:79e0:2e7c:8:642b:a4c2:7ea5:5668]) by smtp.gmail.com with UTF8SMTPSA id d2e1a72fcca58-87d1cfbf839sm1796040b3a.13.2026.09.23.10.47.44 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 23 Sep 2026 10:47:45 -0700 (PDT) From: Brian Norris To: "Rafael J . Wysocki" Cc: linux-doc@vger.kernel.org, linux-pm@vger.kernel.org, Ulf Hansson , Len Brown , Pavel Machek , Doug Anderson , linux-kernel@vger.kernel.org, Brian Norris Subject: [PATCH v2 5/8] PM: runtime: Clarify ->runtime_idle() callback return value handling Date: Wed, 23 Sep 2026 10:40:29 -0700 Message-ID: <20260923104031.v2.5.If6e26acac7770c65446dd0b81f891948abb38973@changeid> X-Mailer: git-send-email 2.56.0.rc1.310.g51773c2048-goog In-Reply-To: <20260923174711.1283986-1-briannorris@chromium.org> References: <20260923174711.1283986-1-briannorris@chromium.org> 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" This doc says "Negative error return codes are ignored by the PM core" for ->runtime_idle(). This is misleading: any non-zero return value (including negative error codes such as -EBUSY or -EAGAIN) tells the PM core to abort automatic suspension of the device, which is commonly used by subsystems to prevent immediate runtime suspend. Clarify that unlike ->runtime_suspend() and ->runtime_resume(), the PM core does not treat negative return values from ->runtime_idle() as a fatal device error, and that any non-zero value stops the PM core from suspending the device. Signed-off-by: Brian Norris --- (no changes since v1) Documentation/power/runtime_pm.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/Documentation/power/runtime_pm.rst b/Documentation/power/runti= me_pm.rst index 114c4a872cb1..423287fce34a 100644 --- a/Documentation/power/runtime_pm.rst +++ b/Documentation/power/runtime_pm.rst @@ -158,9 +158,14 @@ suspending the device are satisfied) and to queue up a= suspend request for the device in that case. If there is no idle callback, or if the callback ret= urns 0, then the PM core will attempt to carry out a runtime suspend of the dev= ice, also respecting devices configured for autosuspend. In essence this means= a -call to pm_runtime_autosuspend(). To prevent this (for example, if the cal= lback -routine has started a delayed suspend), the routine must return a non-zero -value. Negative error return codes are ignored by the PM core. +call to pm_runtime_autosuspend(). + +To prevent this suspension (for example, if the callback routine has sched= uled +a delayed suspend or determined the device cannot be idle), the routine mu= st +return a non-zero value (typically -EBUSY or -EAGAIN). Unlike +->runtime_suspend() and ->runtime_resume(), the PM core does not treat neg= ative +return codes from ->runtime_idle() as a fatal device error; any non-zero v= alue +simply stops the PM core from suspending the device. =20 The helper functions provided by the PM core, described in `Section 4`_, guarantee that the following constraints are met with respect to runtime PM --=20 2.56.0.rc1.310.g51773c2048-goog From nobody Thu Sep 24 13:42:08 2026 Received: from mail-pj2-f28.google.com (mail-pj2-f28.google.com [74.125.227.156]) (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 E9E8B424D6B for ; Wed, 23 Sep 2026 17:47:50 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=74.125.227.156 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790185673; cv=none; b=E5jMPxvlsDHwmQN8ceQtQZR4avJT7CLUJyXyHfneWMi6VYd5AMwOflBUh2Qmtu33g4O0YU8I6koD98IPf3eZxJcuPxc9zM4deSys9y/KhU20K45pS9qNp2oAg5B9lR/l6NpB1qZYeDyxAPjFILWXA8c34FQHKnHWX0j+2bmCR54= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790185673; c=relaxed/simple; bh=cv3kk5egmQXlDJvzUveGMkYSNyw7O54onpjvk1Il9Oc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=cdbN9DMPyx7gWKcyy9YYLdeRu96rBrzZEYBjTZ7b3351neoFF8lrEu/FcU1WIs6JedCmtapb8/UKbbHF3YfBv9BkgPLwwEjwfezSgHWlCuoUIq1ucquyKCEMlgNLSk8ArlDp0AcX3P4+VFRq3kKEY97zvKJCSEb7DF/FLgeP/GA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=chromium.org; spf=pass smtp.mailfrom=chromium.org; dkim=pass (1024-bit key) header.d=chromium.org header.i=@chromium.org header.b=Iaf9aUu0; arc=none smtp.client-ip=74.125.227.156 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=chromium.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=chromium.org header.i=@chromium.org header.b="Iaf9aUu0" Received: by mail-pj2-f28.google.com with SMTP id d9443c01a7336-2d91c22d27dso5080755ad.1 for ; Wed, 23 Sep 2026 10:47:50 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; t=1790185670; x=1790790470; 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:content-type; bh=/uWDBb1uS4h5PTodUKMRyx5us4JzrXxHaBUn/GM73f4=; b=Iaf9aUu06v6e0eQd6pI/eOMsQP69vqOBTdlydzqbu2/seILSZtQLukOHaY/R3V1sfR NTYPzayxomPL6lprtGil60J6mrGqVrxvvu2xoNS1NUb3C2cqDcJ9eqJE9nobZo/xnQXg laU1OS+/p74F8C5aWoRYpSYYFddWm7y53Xp3c= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20260707; t=1790185670; x=1790790470; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to:content-type; bh=/uWDBb1uS4h5PTodUKMRyx5us4JzrXxHaBUn/GM73f4=; b=THN5uGpCx0ALQnpf4sc//HkMMaxGB6UU3HCpGWW56gczH0eNYebgrii86sB4m31yyC ZpdfII9UqREP36MwlE6n4EXffQlNIhuL6AFNqdr4QXV9vT9hIBKfzn6FbNyazdZ5v+kJ TIFMXFbWsPBrtgdiOAvRmOEotli5ncD6VtTbcgtF7xcV92cL4tdMcu8oRNCkahltGIyN GogeBJFTC8czxO/JAYC6IkYEjXiekrqMJAxkT4ENz6EoURhIwis+Ia2iUUgNAI62dOVK zs144LkVYvLUV8qjpJLMbdN2iNSVBLVz8tckavUrdRpA8mEHmmswLo4MhwVerpNxVHsn D0jg== X-Forwarded-Encrypted: i=1; AKwUvBy88hSoWjthQEIt25pMEgTHIZTf6m26rB0dsLP6vaiWElS75VWSGrqmhCaiVh5fJGZh3r6ilAVqHDly8Ko=@vger.kernel.org X-Gm-Message-State: AFuF++lerH+vlI2S8b8DYd36SVWYQ0NmExbWFk41YLzQaB+EeoYYc1qB r9J+JsJY8bmoYyxwy83n8OlZJEJYpTDBmtzVA/7Bm1P5BcXzSYcMX+g7AbajRAEnMw== X-Gm-Gg: AYBFou3IEkxeDlWQnuQNMTrRsPEf70wjUPF7YTGWzPgK1m9FWBtSbUTsKrh7c7qiNZK /fkTdAUdhnNIpxSZo+Qa7JvLczaX+Zi0Knnl9unQ7zfXmST3XeYcEm4wRlOGmhPkNiCG2TSZt/o FZFf78Kv8DCKPDx7lJINS03PAMVvGiSbIPwLzPU/+iqGXwQ6ThSXhFaodDVmIL/pqCdoG758kmX 0eh4oPfyMqtPkl4e3DyNa1Yt/JKEnBxQygLhblvk/dUwic14rnFHr7pIO751uY0nhlK5dtSiqNn rj6vEtgISbj1uER4Mn4dC6TvCZIXg7N5J43VYp/5X+ZKD8vSlJhEL01Ke9W5k9v/39O0KBtbCcd pUOVgCXeDzDotIOKwdlNOkCerox9k2eMZSpWy3pK3pnKRoXbT+7iwK6I2Z7c+HbHCKm8oi84bWF 5OZw1No0BdWkd40MUYON4JsqUeM3mhT6eQOaT0u2CVyICg6BgjxgS5ynhOqb+cmZTgXivvTiY7s T/6qIrW834itlxI06qd2HczcI1jVQ/8PyiApQ== X-Received: by 2002:a17:903:1847:b0:2d6:f6ba:263d with SMTP id d9443c01a7336-2df69d0b3a0mr29106195ad.7.1790185670158; Wed, 23 Sep 2026 10:47:50 -0700 (PDT) Received: from localhost ([2a00:79e0:2e7c:8:642b:a4c2:7ea5:5668]) by smtp.gmail.com with UTF8SMTPSA id d9443c01a7336-2df6a5f4219sm15306515ad.68.2026.09.23.10.47.47 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 23 Sep 2026 10:47:49 -0700 (PDT) From: Brian Norris To: "Rafael J . Wysocki" Cc: linux-doc@vger.kernel.org, linux-pm@vger.kernel.org, Ulf Hansson , Len Brown , Pavel Machek , Doug Anderson , linux-kernel@vger.kernel.org, Brian Norris Subject: [PATCH v2 6/8] PM: runtime: Clarify driver callback expectations and structure Section 2 Date: Wed, 23 Sep 2026 10:40:30 -0700 Message-ID: <20260923104031.v2.6.If19ee35d3b80d115f264484b21fb003a962762fa@changeid> X-Mailer: git-send-email 2.56.0.rc1.310.g51773c2048-goog In-Reply-To: <20260923174711.1283986-1-briannorris@chromium.org> References: <20260923174711.1283986-1-briannorris@chromium.org> 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" Section 2 describes the three runtime callbacks, but: 1) it's fairly dense to read (150+ lines); and 2) it glosses over a big point -- that it's uncommon for drivers to implement ->runtime_idle() Add a note up-front to help direct the reader about #2, and add headings to try to break up the text a bit. Signed-off-by: Brian Norris --- (no changes since v1) Documentation/power/runtime_pm.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/Documentation/power/runtime_pm.rst b/Documentation/power/runti= me_pm.rst index 423287fce34a..e0c20132dabd 100644 --- a/Documentation/power/runtime_pm.rst +++ b/Documentation/power/runtime_pm.rst @@ -54,6 +54,14 @@ There are three device runtime PM callbacks defined in '= struct dev_pm_ops':: ... }; =20 +Most device drivers only need to implement ->runtime_suspend() and +->runtime_resume(). The ->runtime_idle() callback is optional and rarely +implemented by peripheral device drivers, as the PM core automatically han= dles +suspension and autosuspend when ->runtime_idle() is omitted (or returns 0). + +Subsystem and Driver Callbacks +------------------------------ + The ->runtime_suspend(), ->runtime_resume() and ->runtime_idle() callbacks are executed by the PM core for the device's subsystem that may be either = of the following: @@ -87,6 +95,9 @@ not block or sleep, but it also means that the synchronou= s helper functions listed at the end of `Section 4`_ may be used for that device within an interrupt handler or generally in an atomic context. =20 +Callback Semantics +------------------ + The subsystem-level suspend callback, if present, is _entirely_ _responsib= le_ for handling the suspend of the device as appropriate, which may, but need= not include executing the device driver's own ->runtime_suspend() callback (fr= om the @@ -167,6 +178,9 @@ return a non-zero value (typically -EBUSY or -EAGAIN). = Unlike return codes from ->runtime_idle() as a fatal device error; any non-zero v= alue simply stops the PM core from suspending the device. =20 +Core Guarantees and Synchronization Rules +----------------------------------------- + The helper functions provided by the PM core, described in `Section 4`_, guarantee that the following constraints are met with respect to runtime PM callbacks for one device: --=20 2.56.0.rc1.310.g51773c2048-goog From nobody Thu Sep 24 13:42:08 2026 Received: from mail-pz2-f12.google.com (mail-pz2-f12.google.com [74.125.228.12]) (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 0F0CB4248A0 for ; Wed, 23 Sep 2026 17:47:55 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=74.125.228.12 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790185678; cv=none; b=YxeqI4k9GkGGrESloUTn/8/6sPyouseTh+zstl4q2CwiQzWXRLuzN0fUlu5fuMgCvF2+icLH/YSjvoVC/wvqYKaTVHxMtJcXDDuc5+XPh6QPKeWja+7KOs61YxjqGKDGUvOf/JvIHhMK6599JNf/yMWu1zwIRx3ixyG0VdtBjMg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790185678; c=relaxed/simple; bh=ccdYWN4uO+fXp6GWBAaFVGwPrdESUwDVjL7T/+movy0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=PxUAWuHQufkOHIYpkAQ1vaYtBq/zZnn3cO9LTXcS2dqskqypUzbadWeFzhHnEcZqJKMrvp2tQKgatKaAEJN2BbivpT2cQ6wgiuzCO8fdNGNlK1a1CfRrCkKJY9+s52AuwtlI72/RhqtKxDCWAsjtOzSO4vUSPJTqZ5mAng2G4qQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=chromium.org; spf=pass smtp.mailfrom=chromium.org; dkim=pass (1024-bit key) header.d=chromium.org header.i=@chromium.org header.b=G6yUe4AJ; arc=none smtp.client-ip=74.125.228.12 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=chromium.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=chromium.org header.i=@chromium.org header.b="G6yUe4AJ" Received: by mail-pz2-f12.google.com with SMTP id 41be03b00d2f7-cc1cea34f01so783781a12.1 for ; Wed, 23 Sep 2026 10:47:55 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; t=1790185675; x=1790790475; darn=vger.kernel.org; h=content-transfer-encoding:content-type:mime-version:references :in-reply-to:message-id:date:subject:cc:to:from:from:to:cc:subject :date:message-id:reply-to:content-type; bh=LcVXpdi1RtlLWtUvQyxzQWA8IBu8z+++v+33eMLlNCI=; b=G6yUe4AJWPgHHRcUvA5J6svDHAVjUGYfx9gl037ZKs+zo8VcH91ZgAbBYsBS42QZQD Qx4j87uYZXmUM+MugEsLszafaxYZCRKNSDDyQr0yd/j5L9vqd0GAKJvgxyY0eSRs2cou M7n4YpXQ+4MJkWUzyFzpJX7a6Gz6fnW7qbU+Q= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20260707; t=1790185675; x=1790790475; h=content-transfer-encoding:content-type:mime-version:references :in-reply-to:message-id:date:subject:cc:to:from:x-gm-gg :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to :content-type; bh=LcVXpdi1RtlLWtUvQyxzQWA8IBu8z+++v+33eMLlNCI=; b=vaw5Aqin7bIsiS0DNX/USQu+Y9YbOk7CkhL8BMCvPPZc5CGrgDtnXyvB7OQkDGtQBu Xrnj8Ga2wXR0N0b5WOVdlD0zIbpX9lCpd7FHzjetDjWLN3flBtPXTXA/AvWc8tQOTgAm R+JXM+w+tgFs4wv5Zb+/rrIq0jhUg4AtStBcevsMxMGstsUoGTMpGufbTOUf/0BUz24U tqoh1S5rOOabjfY1j30xeCXYtIJ0n7LhYPvEMb+Ngzx/R+WGNcPajXKesGwcR/6MKkhw N6h+utAGQO29jtZOqa0EJpkGxqpJgiZklucdLSVxHpZpNO+Lc2fcg4jHGnBb1HOLPcZy Etkg== X-Forwarded-Encrypted: i=1; AKwUvBywKGr8ZrOXC5STfK9QeurjqsPG9kWOSXHKxkFvaZYL963AWlZUsgpYDZCab87Dpko9Mtz6PxhObPUpkPc=@vger.kernel.org X-Gm-Message-State: AFuF++nFqgcDySzmgjFEOuWKD/rwAVRcpjPxAI8XxAKnm2DJWlABEiRx yG9FffWvCSXpWpPmC1sE6BpO09SGuQ6BNd0NzgZnol1J8zP9uXr9TW7depED/ZXoag7aXTfWUel VFtw= X-Gm-Gg: AYBFou3Gq2DCdMCAxUpzXbdF42ax3fN0m3YjF8/SPJGdqWpYitBWRcaJ4tCHJ/JQgOA MXBxQmia/yA2AYIlD7AdUClBSTL09vZzvEFMnkh2WwGvPqvMXj1k5//8fXhS1eBYhrC7QcpoXO4 TzqZlM+9cA8KpMwO9qu5ZEqVnX2wGow/VLt3E1lj5lVHDbREc+tCM+FNzc1dFHynHCC+7+zm2mE F3cFIC0aXW9tMHU83GIFyGAbagcrdL2/BgjG6MZVGOwZ9REuiml1IGx+Y+/EWy3YC2bV0lS0bMW pxc8x77fI5Wwb//Wi0ZX4PgpH+vpzhezIeOkoqC2YlayjiqoHhl3/TpiQBGH0csCTCgZT8+X/8a Y3AAxdIJQCBb8rE2j/wjOc36nFIqCKoYsXF1I+GQPs2NgPOVC3RCjO3TRKj6bGnD80C0BUSwRZG n95kUjj/G5EYqhhgeEfVTxe+PFHgXnlJuIelWyRsljam8tBLNLpweLlO+Hm/b5qRaet9mlbYFrK tpNLoKy0nPjs04Fo8eT0AzJRMm5YE048VIc9w== X-Received: by 2002:a17:90a:d60c:b0:39e:6c69:9b8d with SMTP id 98e67ed59e1d1-3a07e690cecmr3110112a91.50.1790185675217; Wed, 23 Sep 2026 10:47:55 -0700 (PDT) Received: from localhost ([2a00:79e0:2e7c:8:642b:a4c2:7ea5:5668]) by smtp.gmail.com with UTF8SMTPSA id 98e67ed59e1d1-3a09733f49asm205130a91.9.2026.09.23.10.47.51 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 23 Sep 2026 10:47:52 -0700 (PDT) From: Brian Norris To: "Rafael J . Wysocki" Cc: linux-doc@vger.kernel.org, linux-pm@vger.kernel.org, Ulf Hansson , Len Brown , Pavel Machek , Doug Anderson , linux-kernel@vger.kernel.org, Brian Norris Subject: [PATCH v2 7/8] PM: runtime: Expand introduction with core concepts and structure Date: Wed, 23 Sep 2026 10:40:31 -0700 Message-ID: <20260923104031.v2.7.I45a794e4452e3df22419acdd8f11e2b788b3413f@changeid> X-Mailer: git-send-email 2.56.0.rc1.310.g51773c2048-goog In-Reply-To: <20260923174711.1283986-1-briannorris@chromium.org> References: <20260923174711.1283986-1-briannorris@chromium.org> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable I commonly see people have difficulty learning how runtime PM works because of the following key points [*]: 1) there are several boolean concepts in runtime PM, with somewhat similar meanings: enabled / disabled active / suspended allowed / forbidden 2) if these concepts are documented at all, they're scattered across the kerneldoc or Documentation/ 3) the runtime_pm.rst docs don't make any attempt to ease a reader into understanding the concepts, and instead jump straight into how it's implemented (queues, 'struct device' fields, helpers). Let's try to remedy this a bit by discussing the core concepts and highlights at the top of the introduction, and introduce a few sub-headings, so it's easier to navigate different aspects of the introduction. While shuffling the intro around, I also see that the existing text largely mirrors the layout of the following sections (2, 3, and 4), but does so out of order. Reorder those, and point to section numbers. [*] In addition to API complexity. I count 61 pm_*() helpers, 7 of which are variations of put() and 8 of which are variations of get(). Signed-off-by: Brian Norris --- Changes in v2: Address review feedback around descriptions of "enabled" and "active". I know not every point of discussion was settled, but I hope this updated version resolves many of them and provides a better basis for further improvement. * Avoid calling enabled and active "orthogonal" * Describe more of their inter-relationship * Prioritize talking about "enabled" first, since that's the first concept a reader should know about * Brief mentions of parent/child and supplier/consumer, and dependency handling * Other tweaks Documentation/power/runtime_pm.rst | 103 +++++++++++++++++++++++------ 1 file changed, 84 insertions(+), 19 deletions(-) diff --git a/Documentation/power/runtime_pm.rst b/Documentation/power/runti= me_pm.rst index e0c20132dabd..7bb64d793cdd 100644 --- a/Documentation/power/runtime_pm.rst +++ b/Documentation/power/runtime_pm.rst @@ -13,31 +13,96 @@ Runtime Power Management Framework for I/O Devices 1. Introduction =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -Support for runtime power management (runtime PM) of I/O devices is provid= ed -at the power management core (PM core) level by means of: - -* The power management workqueue pm_wq in which bus types and device drive= rs can - put their PM-related work items. It is strongly recommended that pm_wq = be - used for queuing all work items related to runtime PM, because this allo= ws - them to be synchronized with system-wide power transitions (suspend to R= AM, - hibernation and resume from system sleep states). pm_wq is declared in - include/linux/pm_runtime.h and defined in kernel/power/main.c. - -* A number of runtime PM fields in the 'power' member of 'struct device' (= which - is of the type 'struct dev_pm_info', defined in include/linux/pm.h) that= can - be used for synchronizing runtime PM operations with one another. +Runtime power management (or runtime PM, sometimes shortened to RPM) allows +individual I/O devices to transition between high and low-power states +dynamically while the system is running, conserving power without waiting = for a +system-wide sleep state. + +Core Concepts +------------- + +Understanding runtime PM requires distinguishing between several pairs of +related but distinct concepts that apply to each device: **enabled** / +**disabled**, **active** / **suspended**, and **allowed** / **forbidden**. + +* **Enabled**: To use runtime PM to manage a device's power states, it must + first be **enabled**. If RPM is never enabled for a device, it generally + stays inactive from an RPM perspective, and the PM core will ignore it. + If it is enabled, the PM core can manage the device status (see **Active= ** + below) according to its understanding of whether the device is in use, a= nd + perform state transitions via the appropriate PM callbacks + (->runtime_suspend(), ->runtime_resume()). + + Each device has an internal disable counter (``disable_depth``) which + determines whether runtime PM is currently enabled. Devices are initially + registered with runtime PM disabled (``disable_depth =3D=3D 1``), though= some bus + types (such as PCI) may enable it before driver probe. + + To opt into runtime PM, a driver first ensures that the device's recorded + status matches its actual physical state (for example, by calling + pm_runtime_set_active() if the device was powered on at probe) and then = calls + pm_runtime_enable(), decrementing ``disable_depth`` to zero (i.e., + **enabled**). Runtime PM may be disabled again explicitly via + pm_runtime_disable() or temporarily during system sleep transitions. + +* **Active**: The PM core tracks a device's runtime status as either **act= ive** + (the device is operational, having completed its resume callback or othe= rwise + marked active) or **suspended** (the device is idle or in a low-power st= ate, + having completed its suspend callback or otherwise marked suspended), al= ong + with transitional **suspending** and **resuming** phases. When runtime P= M is + **enabled**, state transitions are primarily driven by reference countin= g: + drivers call pm_runtime_resume_and_get() (or related variants) before us= ing + the hardware, to ensure the device is active; and pm_runtime_put() (or + related variants) once work completes. When a device's usage counter dro= ps to + zero and its dependencies (children or consumers) are suspended, the PM = core + can suspend the device immediately or after an autosuspend delay. + + Besides driving the state of the device in question, a device's runtime + status also affects those of its dependencies =E2=80=94 its parent (if t= he parent's + ``power.ignore_children`` is false) and its linked supplier device(s) (f= or + links with the ``DL_FLAG_PM_RUNTIME`` flag). An **active** device holds + reference counts on its dependencies, preventing them from suspending. + +* **Allowed**: System policy and user space govern whether dynamic suspens= ion + is permitted through the concepts of **allowed** and **forbidden**, + manipulated in-kernel via pm_runtime_allow() and pm_runtime_forbid() and + exposed to user space through the ``/sys/devices/.../power/control`` + attribute. When runtime PM is forbidden (``control`` set to ``on``), the= PM + core increments the device's usage counter, forcing the device to remain + active regardless of whether the driver is idle. When runtime PM is allo= wed + (``control`` set to ``auto``), this reference is dropped, permitting the= PM + core to automatically suspend the device whenever its driver and child + devices are no longer using it. + +Notably, runtime PM also has a feature called "autosuspend." This is diffe= rent +than the ``control`` notion of "auto" (i.e., "allowed"). Autosuspend is +described in more detail in `Section 9`_. + +Implementation Structure +------------------------ + +Support for runtime power management is provided at the power management c= ore +(PM core) level by means of: =20 * Three device runtime PM callbacks in 'struct dev_pm_ops' (defined in - include/linux/pm.h). + include/linux/pm.h). See `Section 2`_. + +* A number of runtime PM fields in the 'power' member of 'struct device' t= hat + can be used for synchronizing runtime PM operations with one another. Th= ese + are covered in `Section 3`_. =20 * A set of helper functions defined in drivers/base/power/runtime.c that c= an be used for carrying out runtime PM operations in such a way that the - synchronization between them is taken care of by the PM core. Bus types= and - device drivers are encouraged to use these functions. + synchronization between them is taken care of by the PM core. Bus types = and + device drivers are encouraged to use these functions. They are covered in + `Section 4`_. =20 -The runtime PM callbacks present in 'struct dev_pm_ops', the device runtim= e PM -fields of 'struct dev_pm_info' and the core helper functions provided for -runtime PM are described below. +* The power management workqueue pm_wq in which bus types and device drive= rs can + put their PM-related work items. It is strongly recommended that pm_wq be + used for queuing all work items related to runtime PM, because this allo= ws + them to be synchronized with system-wide power transitions (suspend to R= AM, + hibernation and resume from system sleep states). pm_wq is declared in + include/linux/pm_runtime.h and defined in kernel/power/main.c. =20 .. _Section 2: =20 --=20 2.56.0.rc1.310.g51773c2048-goog From nobody Thu Sep 24 13:42:08 2026 Received: from mail-pj2-f13.google.com (mail-pj2-f13.google.com [74.125.227.141]) (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 5FAD240DB53 for ; Wed, 23 Sep 2026 17:48:01 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=74.125.227.141 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790185684; cv=none; b=RnqMSObWNJ7UWOZgI+ME7KOoMkWUo4UaYwmu95wxkkGZGuchfo3bms/iY7R4PCeqbx7Kbl4Cbuu2AESs85geQyh6C0Ss1Lh0Jy9mqqUERiDYXg4Veeu5U+4MwXAy8CC8g/YtG17QNhz1W6iZs0YIHsME8+FjUEWzhjHR/GU+13A= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790185684; c=relaxed/simple; bh=kGdswbKWUnh/5oiqXUgwaChvMJJR5rTLM1IBnURhykg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=UxuwKlmE0utbKDKobQvcaEuvtUWJzOZfhmcLLnLuMCZw5JR7nDbHXsiuwSlt2xQ4rKyL9CetqDjVFdeq2ybuhgBnWs0SZrgWetfkRl3Mu1DZcUOqe/lT0XRJ+uh4+kNcVkfx6tDk8vvfW01tlzwbcax9nqKkJ2i+Efd5ycxhnTQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=chromium.org; spf=pass smtp.mailfrom=chromium.org; dkim=pass (1024-bit key) header.d=chromium.org header.i=@chromium.org header.b=PDkaNtHs; arc=none smtp.client-ip=74.125.227.141 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=chromium.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=chromium.org header.i=@chromium.org header.b="PDkaNtHs" Received: by mail-pj2-f13.google.com with SMTP id 98e67ed59e1d1-39b2ad83dc6so899701a91.0 for ; Wed, 23 Sep 2026 10:48:01 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; t=1790185681; x=1790790481; 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:content-type; bh=TuS/hiw82xHN2Jmis0MyKFIEJvuWhPa9iLIYrihg8LE=; b=PDkaNtHsSOG3mCBnsXa5/kMXYCJxUhVRQ7/ca3BcE3zeZcBdPf+S/6f5zXIl9ywnaA 0Q2jG7z5f0ECVg3NeVxzqSrDQkuXftVSAWVE9F6Yfde6DbsmvY38IXl2XzB3ApDu6wfq dU3i5rAFfh7BSAsnnMoZO4IyXZ/F/slhwdRSw= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20260707; t=1790185681; x=1790790481; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to:content-type; bh=TuS/hiw82xHN2Jmis0MyKFIEJvuWhPa9iLIYrihg8LE=; b=UqSVJ0kFH4IT6CWY7SUlwYhCW/ut58Q9B2+e63z6SCrBAVst7VJcH7SjEycNwCO8ju +17BWxGW4lAJHunu+CCdbHFZSj7Y284y/p6bSKmllF196ibyz7h3nBuAvzRRfLTT0bH2 rtsAym9hE49k9f/I6HC/OMuMN00+Aynx9cd6gL7R6bD+0JCFmGK0ycQPXiaFOhyGm1K+ ZixmW+4Hwzn+nk1IT5iM9X1LsyB2EUYANZnY/D2Um3c86yt+Utb1eM+dCHeQPKpdbMR9 DIV3txtFkx6SL2GSxqJYXwWvazOBMvN5tIZLvCFqVegSFQc8SA4eFVqvzTmGEH45l9B8 AFLw== X-Forwarded-Encrypted: i=1; AKwUvBxQwxydWUGTot7WU0P9kj+Yt09ZOOlXPgyNGR+8sE4ntzMutRHQxXja29L+wN2Cr7zX1VcFKsqiA4WnKrc=@vger.kernel.org X-Gm-Message-State: AFuF++kpynksFjAJcsk9nJD8dX/H5FYVjVtS22kkZFwcHrWFI6Lof9BN V2zcsS5mcAOxWAc4/6PgxTEOe9521OkYGjzHb2QRqHRnMxzIXzQT5/l5T4csmjjkuQ== X-Gm-Gg: AYBFou12vfWlYgkL5ssRDtu9+c3K2MhpHPCis8moQV2LK38NRqZe/dh94NKylANxSfy d/06iss4cqcClLcw7qFN1YUv9uF2RgDMsKmZMUMJkrzaOyu0cw95iPVZWZyJWCx+peUM6088hKB QfKdcKNDl8bTFloUFwXg+0PF3r6sjSqgYdNaSIoehgQlCHUrjhFudT7k3YOC+4W3NlK3r5o92/q mVguD75kRewiobEg1EOhRo6AUx5jkcUs0tJVDVslm0kiAAeKx/ktXxxpQ9Rhqvog1ce9O7LqbQg x6srlUOCXfs3FQDHy+tPXKjEY6wtT6NJI+yDurao+xKhKy+d7AiHltPGcZS/yiHEqy+KDwwWl3F nGlJXwtoMJ6NX7GrQVwhc5fvJmJM2z+c6fG94+lp95A3LKrsFvAvJxky//ig0ZDKRTtfabZcC/M AjDt6yCCPx8tFiNuqD1O4Ty3IYp4mV7FO/nD1fuzf/q7a6dFVuAjibDfTbc+uwE87eBtf8evQ2W JcwfKPiWPJ1YkussiH6lpKGz+PvOMrjC/5Abyax8I5m34yE X-Received: by 2002:a17:90b:520f:b0:39e:4c7e:f040 with SMTP id 98e67ed59e1d1-3a07e583271mr3102837a91.29.1790185681194; Wed, 23 Sep 2026 10:48:01 -0700 (PDT) Received: from localhost ([2a00:79e0:2e7c:8:642b:a4c2:7ea5:5668]) by smtp.gmail.com with UTF8SMTPSA id 98e67ed59e1d1-3a0976c8f8dsm151602a91.12.2026.09.23.10.47.56 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 23 Sep 2026 10:47:57 -0700 (PDT) From: Brian Norris To: "Rafael J . Wysocki" Cc: linux-doc@vger.kernel.org, linux-pm@vger.kernel.org, Ulf Hansson , Len Brown , Pavel Machek , Doug Anderson , linux-kernel@vger.kernel.org, Brian Norris Subject: [PATCH v2 8/8] PM: runtime: Add Example Driver Patterns section Date: Wed, 23 Sep 2026 10:40:32 -0700 Message-ID: <20260923104031.v2.8.I75ceea7b1afd016e08922e47b82e6eb36de144fe@changeid> X-Mailer: git-send-email 2.56.0.rc1.310.g51773c2048-goog In-Reply-To: <20260923174711.1283986-1-briannorris@chromium.org> References: <20260923174711.1283986-1-briannorris@chromium.org> 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 runtime PM API surface is pretty large, but there are a few common patterns that many drivers should follow. Add some illustrative examples, to help guide the most common audience for runtime PM docs -- driver writers. Signed-off-by: Brian Norris --- Changes in v2: * Add appropriate teardown to "Probe with Hardware Powered Off" Example, as the remove() + power-off behavior is subtle here, and easy to get wrong Documentation/power/runtime_pm.rst | 367 ++++++++++++++++++++++++++++- 1 file changed, 366 insertions(+), 1 deletion(-) diff --git a/Documentation/power/runtime_pm.rst b/Documentation/power/runti= me_pm.rst index 7bb64d793cdd..3a615d2de103 100644 --- a/Documentation/power/runtime_pm.rst +++ b/Documentation/power/runtime_pm.rst @@ -641,7 +641,9 @@ The implementation is well suited for asynchronous use = in interrupt contexts. However such use inevitably involves races, because the PM core can't synchronize ->runtime_suspend() callbacks with the arrival of I/O requests. This synchronization must be handled by the driver, using its private lock. -Here is a schematic pseudo-code example:: +Here is a schematic pseudo-code example: + +.. code-block:: c =20 foo_read_or_write(struct foo_priv *foo, void *data) { @@ -707,3 +709,366 @@ pm_runtime_autosuspend_expiration() from within the -= >runtime_suspend() callback while holding its private lock. If the function returns a nonzero value then the delay has not yet expired and the callback should return -EAGAIN. + +.. _Section 10: + +10. Example Driver Patterns +=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 + +The runtime PM API is large and complex, but most device drivers follow a = small +set of canonical patterns when interacting with runtime PM. This section +illustrates standard patterns for device probing, performing I/O, and hand= ling +interrupts. + +Probe and Initialization +------------------------ + +Basic Probe +~~~~~~~~~~~ + +A driver that powers on its hardware during probe and does not use autosus= pend +can initialize runtime PM using device-managed helpers: + +.. code-block:: c + + static int foo_probe(struct platform_device *pdev) + { + struct device *dev =3D &pdev->dev; + struct foo_priv *priv; + int ret; + + priv =3D devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL); + if (!priv) + return -ENOMEM; + + /* Power on and initialize hardware registers... */ + + /* + * The code above left hardware powered on and operational, so + * tell the PM core that the device is active before enabling + * runtime PM. + */ + pm_runtime_set_active(dev); + + ret =3D devm_pm_runtime_enable(dev); + if (ret) + return ret; + + /* + * Alternatively, the above two calls can be combined into: + * ret =3D devm_pm_runtime_set_active_enabled(dev); + * if (ret) + * return ret; + */ + + /* + * Upon successful return from ->probe(), the driver core + * automatically executes pm_request_idle(dev), allowing the + * device to suspend asynchronously if its usage counter is zero. + */ + return 0; + } + +Probe with Hardware Powered Off +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Many drivers prefer to keep hardware powered off or in low power until +actually needed, avoiding duplicate power sequencing logic between ->probe= () +and ->runtime_resume(). Because the initial runtime PM state of a device is +suspended by default, the driver can enable runtime PM directly and rely on +pm_runtime_resume_and_get() to trigger the ->runtime_resume() callback when +probe needs to access hardware: + +.. code-block:: c + + static int foo_runtime_suspend(struct device *dev) + { + struct foo_priv *priv =3D dev_get_drvdata(dev); + + clk_disable_unprepare(priv->clk); + regulator_disable(priv->supply); + + return 0; + } + + static int foo_runtime_resume(struct device *dev) + { + struct foo_priv *priv =3D dev_get_drvdata(dev); + int ret; + + ret =3D regulator_enable(priv->supply); + if (ret) + return ret; + + ret =3D clk_prepare_enable(priv->clk); + if (ret) { + regulator_disable(priv->supply); + return ret; + } + + return 0; + } + + static int foo_probe(struct platform_device *pdev) + { + struct device *dev =3D &pdev->dev; + struct foo_priv *priv; + int ret; + + priv =3D devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL); + if (!priv) + return -ENOMEM; + + platform_set_drvdata(pdev, priv); + + /* Acquire regulators, clocks, GPIOs, and register map... */ + + /* + * Hardware starts powered off. The default state is + * RPM_SUSPENDED, so no need for: + * pm_runtime_set_suspended(dev); + */ + + pm_runtime_enable(dev); + + /* + * Power on the device via ->runtime_resume() to verify device + * ID or perform initial hardware configuration. + */ + ret =3D pm_runtime_resume_and_get(dev); + if (ret < 0) + goto err_pm_disable; + + ret =3D foo_verify_hardware_id(priv); + if (ret) { + pm_runtime_put_sync(dev); + goto err_pm_disable; + } + + /* + * Drop the usage counter, allowing ->runtime_suspend() to + * power off the device until an I/O request arrives. + */ + pm_runtime_put(dev); + + return 0; + + err_pm_disable: + pm_runtime_disable(dev); + return ret; + } + + static void foo_remove(struct platform_device *pdev) + { + struct device *dev =3D &pdev->dev; + + pm_runtime_disable(dev); + if (!pm_runtime_status_suspended(dev)) + foo_runtime_suspend(dev); + } + +Note that this pattern requires ``CONFIG_PM``. When ``CONFIG_PM`` is +disabled, pm_runtime_resume_and_get() returns 0 without calling +->runtime_resume(), leaving hardware unpowered. Drivers using this pattern +should typically depend on ``CONFIG_PM``. + +Drivers using this pattern should also ensure that hardware is powered off +cleanly upon driver unbind. If the device was still active when detached (= for +example, if user space configured ``/sys/devices/.../power/control`` to +``on``, or if an operation was ongoing), the ->remove() callback disables +runtime PM, checks whether the device is not yet suspended using +pm_runtime_status_suspended(), and manually invokes foo_runtime_suspend(). + +Autosuspend Probe +~~~~~~~~~~~~~~~~~ + +If the driver uses autosuspend, it configures the autosuspend delay and en= ables +autosuspend before enabling runtime PM: + +.. code-block:: c + + static int foo_probe(struct platform_device *pdev) + { + struct device *dev =3D &pdev->dev; + struct foo_priv *priv; + int ret; + + priv =3D devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL); + if (!priv) + return -ENOMEM; + + /* Power on and initialize hardware registers... */ + + /* Set autosuspend delay (e.g. 2000 ms) and enable autosuspend */ + pm_runtime_set_autosuspend_delay(dev, 2000); + pm_runtime_use_autosuspend(dev); + + pm_runtime_set_active(dev); + + /* + * Update last busy timestamp so the driver core's post-probe + * pm_request_idle() respects the autosuspend delay. + */ + pm_runtime_mark_last_busy(dev); + + /* + * devm_pm_runtime_enable() ensures that pm_runtime_disable() + * and pm_runtime_dont_use_autosuspend() are called upon driver + * unbind. + */ + ret =3D devm_pm_runtime_enable(dev); + if (ret) + return ret; + + return 0; + } + +Performing I/O Operations +------------------------- + +Before accessing hardware registers or initiating I/O transfers, drivers m= ust +ensure the device is active by calling pm_runtime_resume_and_get() or simi= lar. + +Basic I/O +~~~~~~~~~ + +For devices without autosuspend, work completion is signaled with +pm_runtime_put(), which drops the usage counter and queues an asynchronous= idle +check once the counter reaches zero: + +.. code-block:: c + + int foo_do_transfer(struct foo_priv *priv, void *buf, size_t count) + { + int ret; + + ret =3D pm_runtime_resume_and_get(priv->dev); + if (ret < 0) + return ret; + + /* Access hardware registers or perform data transfer... */ + ret =3D foo_hardware_transfer(priv, buf, count); + + /* + * Drop usage counter and request asynchronous idle check (and + * suspend, if possible). + */ + pm_runtime_put(priv->dev); + + return ret; + } + +Autosuspend I/O +~~~~~~~~~~~~~~~ + +For devices using autosuspend, work completion is signaled with +pm_runtime_put_autosuspend(), which drops the usage counter and defers +suspension until the autosuspend delay expires: + +.. code-block:: c + + int foo_do_transfer(struct foo_priv *priv, void *buf, size_t count) + { + int ret; + + ret =3D pm_runtime_resume_and_get(priv->dev); + if (ret < 0) + return ret; + + /* Access hardware registers or perform data transfer... */ + ret =3D foo_hardware_transfer(priv, buf, count); + + /* + * Drop the usage counter and schedule an autosuspend once + * the delay expires. Note that pm_runtime_put_autosuspend() + * updates the last-access timestamp automatically. + */ + pm_runtime_put_autosuspend(priv->dev); + + return ret; + } + +Synchronous Completion +~~~~~~~~~~~~~~~~~~~~~~ + +When immediate suspension is desired -- such as before unregistering a +device or during shutdown -- synchronous put helpers can be used instead of +their asynchronous counterparts. Which helper to use depends on whether +autosuspend is configured: + +* For non-autosuspend devices, use pm_runtime_put_sync(). +* For devices that use autosuspend, use pm_runtime_put_sync_suspend(), whi= ch + ignores any configured autosuspend delay and forces immediate suspension. + +However, note several important caveats when relying on synchronous runtime +PM helpers for power-down: + +* **Parents and Suppliers**: While the target device itself is suspended + synchronously, the PM core handles idle notifications for parents and + device link suppliers asynchronously. As a result, parent devices or + power domain suppliers are not guaranteed to be powered off when the + function returns. +* **User Policy ("Forbidden")**: Runtime PM helpers respect system policy. + If user space has set ``/sys/devices/.../power/control`` to ``on`` + (pm_runtime_forbid()), the PM core holds an extra reference on the + device, meaning dropping the driver's usage counter will not trigger a + suspend. + +Because of these constraints, synchronous put helpers may not be suitable +when a driver functionally requires hardware to be powered off +synchronously (for example, to perform a hardware reset or power cycle). +Such requirements may necessitate other methods, such as disabling runtime +PM with pm_runtime_disable() and explicitly executing the hardware +power-down sequence. + +Interrupt Handling with Conditional Get +--------------------------------------- + +Interrupt handlers (especially in atomic or hardirq context) cannot typica= lly +invoke pm_runtime_resume_and_get(), because runtime-resume may sleep. More= over, +if an interrupt arrives while the device is suspended or transitioning to = low +power (e.g., on a shared interrupt line or spurious wakeups), attempting to +read hardware registers could trigger a bus fault or system hang. + +To handle this safely, drivers can conditionally acquire a runtime PM refe= rence +using pm_runtime_get_if_in_use() or pm_runtime_get_if_active(): + +.. code-block:: c + + static irqreturn_t foo_irq_handler(int irq, void *dev_id) + { + struct foo_priv *priv =3D dev_id; + irqreturn_t ret =3D IRQ_NONE; + + /* + * Check if the device is active before reading hardware + * registers. If the device is suspended, this interrupt + * cannot belong to us (or was already serviced). + * + * Note that this also will drop interrupts while runtime PM is + * disabled. + */ + if (pm_runtime_get_if_active(priv->dev) <=3D 0) + return IRQ_NONE; + + /* Hardware is active and usage count is incremented */ + if (foo_has_pending_irq(priv)) { + foo_service_irq(priv); + ret =3D IRQ_HANDLED; + } + + /* + * Release the reference acquired by pm_runtime_get_if_active(). + * For autosuspend devices, use pm_runtime_put_autosuspend(); + * for non-autosuspend devices, use pm_runtime_put(). + */ + pm_runtime_put_autosuspend(priv->dev); + + return ret; + } + +Both pm_runtime_get_if_in_use() and pm_runtime_get_if_active() are safe to= use +from an interrupt routine. One example where a device might be active but = not +"in use" is if autosuspend is used. A device will stay active for a while = with +no users. If interrupts should still be serviced for a device in this stat= e, +pm_runtime_get_if_active() should be used. --=20 2.56.0.rc1.310.g51773c2048-goog