Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Received-SPF: Pass (protection.outlook.com: domain of arm.com designates
 63.35.35.123 as permitted sender) receiver=protection.outlook.com;
 client-ip=63.35.35.123; helo=64aa7808-outbound-1.mta.getcheckrecipient.com;
Authentication-Results-Original: spf=none (sender IP is )
 smtp.mailfrom=Grant.Likely@arm.com; 
From:   Grant Likely <grant.likely@arm.com>
To:     linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
Cc:     nd@arm.com, Grant Likely <grant.likely@arm.com>,
        Jonathan Corbet <corbet@lwn.net>,
        Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
        Saravana Kannan <saravanak@google.com>,
        Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Subject: [PATCH] Add documentation on meaning of -EPROBE_DEFER
Date:   Fri, 27 Mar 2020 17:01:32 +0000
Message-Id: <20200327170132.17275-1-grant.likely@arm.com>
Content-Transfer-Encoding: 8bit
Content-Type: text/plain
MIME-Version: 1.0
X-MS-Exchange-MessageSentRepresentingType: 1
Received: from moist.secretlab.ca (92.40.174.1) by LO2P123CA0047.GBRP123.PROD.OUTLOOK.COM (2603:10a6:600::35) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.2856.20 via Frontend Transport; Fri, 27 Mar 2020 17:01:45 +0000
X-Mailer: git-send-email 2.20.1
X-Originating-IP: [92.40.174.1]
X-MS-PublicTrafficType: Email
X-MS-Office365-Filtering-HT: Tenant
X-MS-Office365-Filtering-Correlation-Id: b9a9b07f-eea9-48e2-2e07-08d7d2708d61
X-MS-TrafficTypeDiagnostic: DB8SPR01MB0016:|DB8SPR01MB0016:|HE1PR08MB2873:
X-MS-Exchange-Transport-Forked: True
X-Microsoft-Antispam-PRVS: <HE1PR08MB2873F217EB9B54B4D404788195CC0@HE1PR08MB2873.eurprd08.prod.outlook.com>
x-checkrecipientrouted: true
NoDisclaimer: true
X-MS-Oob-TLC-OOBClassifiers: OLM:9508;OLM:9508;
X-Forefront-PRVS: 0355F3A3AE
X-Forefront-Antispam-Report-Untrusted: CIP:255.255.255.255;CTRY:;LANG:en;SCL:1;SRV:;IPV:NLI;SFV:NSPM;H:DB8PR08MB4010.eurprd08.prod.outlook.com;PTR:;CAT:NONE;SFTY:;SFS:(10009020)(4636009)(136003)(396003)(376002)(39860400002)(346002)(366004)(4326008)(2906002)(8676002)(26005)(66556008)(66476007)(6506007)(66946007)(55236004)(1076003)(36756003)(6512007)(86362001)(5660300002)(8936002)(81156014)(81166006)(6666004)(186003)(478600001)(956004)(316002)(44832011)(2616005)(6486002)(52116002)(54906003)(16526019);DIR:OUT;SFP:1101;
Received-SPF: None (protection.outlook.com: arm.com does not designate
 permitted sender hosts)
X-MS-Exchange-SenderADCheck: 1
X-Microsoft-Antispam-Untrusted: BCL:0;
X-Microsoft-Antispam-Message-Info-Original: Qc3Q8VuOPWX90wCYXk/Mq2C2yNhaty3Gll0Q518+cpEuixPMUkELB0vrBLf0p4vn8Sec03B81Bb2nRANZW5A14bpuY3hzFMViVcyNp1Z/oCd4oSnAzLUTJXW7Ty0LvT8iG9RHn0FL0vUUdKIhnDPY/JsOIaLvyx0IbKxhbvKfnaQ5R07icZvS/IlbiCfX+jJuSX0uSlurywJtV6A+jG6+RlLae2/k2C/n479Ll8d/2HEk8kG8DSOUt+cbjBS8oB59r7x3+apfRm4eqJU3NsHw7MSQcgxDI6TwT/KRCiIzBjUgY5jwmlZnwT64KADpquSZ2hWKMRZn8kje1XLVVGbCBrD+Q1EgrvBHNkDBW+c2uoAz+UVOHVQq8VPxNDLhi+cLex4pV0bC1RjSZyCnLgPMicVHd1MUaL+QO2BHjvO0/Rraehich5Tq6EXnH+sCCet
X-MS-Exchange-AntiSpam-MessageData: lRcCVs+Pavytr2M6cpOsb7GrUWzir73ynlFhCABkrgJMzxE0xpJ5cmYiK1UFC9nuj38Y6bzniHFbaEci3DFBCd66vwg3w8HMXQsi6UlqZ1IyoBv0HlGhGGtWgK8QEeM+6QxUYyT3nZcwPHYEJ5nPpA==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: DB8SPR01MB0016
Original-Authentication-Results: spf=none (sender IP is )
 smtp.mailfrom=Grant.Likely@arm.com; 
X-EOPAttributedMessage: 0
X-MS-Exchange-Transport-CrossTenantHeadersStripped: VE1EUR03FT036.eop-EUR03.prod.protection.outlook.com
X-Forefront-Antispam-Report: CIP:63.35.35.123;CTRY:IE;LANG:en;SCL:1;SRV:;IPV:CAL;SFV:NSPM;H:64aa7808-outbound-1.mta.getcheckrecipient.com;PTR:ec2-63-35-35-123.eu-west-1.compute.amazonaws.com;CAT:NONE;SFTY:;SFS:(10009020)(4636009)(346002)(136003)(396003)(376002)(39860400002)(46966005)(6506007)(336012)(81156014)(6666004)(82740400003)(2906002)(5660300002)(8676002)(70586007)(16526019)(26005)(356004)(1076003)(44832011)(81166006)(186003)(47076004)(8936002)(4326008)(70206006)(316002)(86362001)(36756003)(36906005)(26826003)(450100002)(956004)(478600001)(54906003)(2616005)(6486002)(107886003)(6512007);DIR:OUT;SFP:1101;
X-MS-Office365-Filtering-Correlation-Id-Prvs: f88f4bdf-2851-4d5c-9af4-08d7d2708828
X-Forefront-PRVS: 0355F3A3AE
X-Microsoft-Antispam: BCL:0;
X-Microsoft-Antispam-Message-Info: 13YW+75haqasC2wSI+2qE8LUI7JU8/Y0imdRGzsSP1fWo008pM8BtQXZDHWn587CtilzI+87z4VRyP8SXkO0fJYu0hMe73BwDiaAydbxmi7/Yex+L2OgTgywTUyekEe5Pci/saq36x07K680hBbIhJu0vXss1WYwCvuVtISdoxVVT1bURVtJohp+nxBvOAJvH4gUun0I5ytp4L74rCEmHbMbThHByk+L70m8j0xd8fIkljWPlFmMUeeZVLOUfucCRlkVqz4EBVm87RdyI+WG7YDaqhO1dh+S3p+xLuZGvv4zcswXmHTBB/cN3QDo/i/r0U8ACsXQAxMYymrK31cfKtWHZcsgWj8zwir2PQi2hwQMVcbD1dEyhOaWdvofZHYi+mPCwoDyUdIrrv+cYuTYgkDTbaxjDqOrmvwWkoNOg45Xmps932rtkbYN0kzWZCAjTOmOmNgl/AaN3IrpGpYF23QmSCareki2KdfcRVPoNuSz/vR7uSCpiysTyQ5RT4g/5aDdKGquozHXWW5w0jXN1A==
X-OriginatorOrg: arm.com
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 27 Mar 2020 17:01:54.4959
 (UTC)
X-MS-Exchange-CrossTenant-Network-Message-Id: b9a9b07f-eea9-48e2-2e07-08d7d2708d61
X-MS-Exchange-CrossTenant-Id: f34e5979-57d9-4aaa-ad4d-b122a662184d
X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=f34e5979-57d9-4aaa-ad4d-b122a662184d;Ip=[63.35.35.123];Helo=[64aa7808-outbound-1.mta.getcheckrecipient.com]
X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem
X-MS-Exchange-Transport-CrossTenantHeadersStamped: HE1PR08MB2873
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

Add a bit of documentation on what it means when a driver .probe() hook
returns the -EPROBE_DEFER error code, including the limitation that
-EPROBE_DEFER should be returned as early as possible, before the driver
starts to register child devices.

Also: minor markup fixes in the same file

Signed-off-by: Grant Likely <grant.likely@arm.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Saravana Kannan <saravanak@google.com>
Cc: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
---
 .../driver-api/driver-model/driver.rst        | 32 ++++++++++++++++---
 1 file changed, 27 insertions(+), 5 deletions(-)

diff --git a/Documentation/driver-api/driver-model/driver.rst b/Documentation/driver-api/driver-model/driver.rst
index baa6a85c8287..63057d9bc8a6 100644
--- a/Documentation/driver-api/driver-model/driver.rst
+++ b/Documentation/driver-api/driver-model/driver.rst
@@ -4,7 +4,6 @@ Device Drivers
 
 See the kerneldoc for the struct device_driver.
 
-
 Allocation
 ~~~~~~~~~~
 
@@ -167,9 +166,26 @@ the driver to that device.
 
 A driver's probe() may return a negative errno value to indicate that
 the driver did not bind to this device, in which case it should have
-released all resources it allocated::
+released all resources it allocated.
+
+Optionally, probe() may return -EPROBE_DEFER if the driver depends on
+resources that are not yet available (e.g., supplied by a driver that
+hasn't initialized yet).  The driver core will put the device onto the
+deferred probe list and will try to call it again later. If a driver
+must defer, it should return -EPROBE_DEFER as early as possible to
+reduce the amount of time spent on setup work that will need to be
+unwound and reexecuted at a later time.
+
+.. warning::
+      -EPROBE_DEFER must not be returned if probe() has already created
+      child devices, even if those child devices are removed again
+      in a cleanup path. If -EPROBE_DEFER is returned after a child
+      device has been registered, it may result in an infinite loop of
+      .probe() calls to the same driver.
+
+::
 
-	void (*sync_state)(struct device *dev);
+	void	(*sync_state)	(struct device *dev);
 
 sync_state is called only once for a device. It's called when all the consumer
 devices of the device have successfully probed. The list of consumers of the
@@ -212,6 +228,8 @@ over management of devices from the bootloader, the usage of sync_state() is
 not restricted to that. Use it whenever it makes sense to take an action after
 all the consumers of a device have probed.
 
+::
+
 	int 	(*remove)	(struct device *dev);
 
 remove is called to unbind a driver from a device. This may be
@@ -224,11 +242,15 @@ not. It should free any resources allocated specifically for the
 device; i.e. anything in the device's driver_data field.
 
 If the device is still present, it should quiesce the device and place
-it into a supported low-power state::
+it into a supported low-power state.
+
+::
 
 	int	(*suspend)	(struct device *dev, pm_message_t state);
 
-suspend is called to put the device in a low power state::
+suspend is called to put the device in a low power state.
+
+::
 
 	int	(*resume)	(struct device *dev);
 
-- 
2.20.1