[PATCH v2 3/4] doc: driver-model: state that of_to_plat() must not probe or claim

[Mehmet Fide <mehmet.fide@gmail.com>]

From: Mehmet Fide <mehmet.fide@screeningeagle.com>

The design document says decoding the devicetree belongs in
of_to_plat(), but not what the method must not do. Spell out the rule
that has always been implied by the phase separation: no probing of
other devices and no claiming of resources, and point at the
parse-now-request-later GPIO helpers as the pattern to follow, the
same shape clocks, resets and phys will want.

The paragraph a few lines further down allowed exactly the opposite,
probing GPIO, clock and reset providers from of_to_plat() to select a
resource. That is the pattern the helpers exist to remove, so drop it;
only its first sentence, that of_to_plat() must not probe the device
itself, is still true and stays.

Signed-off-by: Mehmet Fide <mehmet.fide@screeningeagle.com>
---

Notes:
    Changes in v2:
    - reword the sentence about the GPIO helpers, mention clocks, resets and
      phys (Simon Glass)
    - remove the paragraph that allowed probing providers from of_to_plat()
      (Simon Glass)

 doc/develop/driver-model/design.rst | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/doc/develop/driver-model/design.rst b/doc/develop/driver-model/design.rst
index 633545944d1..4b1fe0839a7 100644
--- a/doc/develop/driver-model/design.rst
+++ b/doc/develop/driver-model/design.rst
@@ -759,6 +759,16 @@ The steps are:
 
    6. The device is marked 'plat valid'.
 
+The of_to_plat() method must only read the devicetree. It must not probe
+other devices or claim resources such as GPIOs or clocks: ofdata is read
+before the device's pinctrl state is applied, so a pin claimed here can have
+its configuration undone a moment later, and probing another device from this
+method defeats the lazy-probing model. When a resource is named in the
+devicetree, read its description into the platform data here with
+gpio_parse_by_name() and claim it in probe() with gpio_request_parsed(). The
+same 'parse now, request later' shape applies to clocks, resets and phys,
+even though those helpers do not exist yet.
+
 Note that ofdata reading is always done (for a child and all its parents)
 before probing starts. Thus devices go through two distinct states when
 probing: reading platform data and actually touching the hardware to bring
@@ -778,11 +788,7 @@ present will cause an error on probe, yet we still must tell Linux about
 the SD card connector in case it is used while Linux is running.
 
 It is important that the of_to_plat() method does not actually probe
-the device itself. However there are cases where other devices must be probed
-in the of_to_plat() method. An example is where a device requires a
-GPIO for it to operate. To select a GPIO obviously requires that the GPIO
-device is probed. This is OK when used by common, core devices such as GPIO,
-clock, interrupts, reset and the like.
+the device itself.
 
 If your device relies on its parent setting up a suitable address space, so
 that dev_read_addr() works correctly, then make sure that the parent device
-- 
2.55.0