[PATCH v3 28/28] dm: Update documentation for new sequence numbers

[Simon Glass]

Update the driver model documention to describe how sequence numbers now
work.

Signed-off-by: Simon Glass <sjg at chromium.org>
---

(no changes since v2)

Changes in v2:
- Update the docs to indicate all devices get a sequence number
- Update the docs to explain how aliases reserve sequence numbers
- Drop commit changing efi_uc_destroy()

 doc/driver-model/design.rst | 59 ++++++++++++++++++++++---------------
 1 file changed, 35 insertions(+), 24 deletions(-)

diff --git a/doc/driver-model/design.rst b/doc/driver-model/design.rst
index b0da3ada294..f26e4f14df0 100644
--- a/doc/driver-model/design.rst
+++ b/doc/driver-model/design.rst
@@ -515,11 +515,23 @@ cases. While it might be tempting to automatically renumber the devices
 where there are gaps in the sequence, this can lead to confusion and is
 not the way that U-Boot works.
 
-Each device can request a sequence number. If none is required then the
-device will be automatically allocated the next available sequence number.
+Where a device gets its sequence number is controlled by the DM_SEQ_ALIAS
+Kconfig option, which can have a different value in U-Boot proper and SPL.
+If this option is not set, aliases are ignored.
 
-To specify the sequence number in the device tree an alias is typically
-used. Make sure that the uclass has the DM_UC_FLAG_SEQ_ALIAS flag set.
+Even if CONFIG_DM_SEQ_ALIAS is enabled, the uclass must still have the
+DM_UC_FLAG_SEQ_ALIAS flag set, for its devices to be sequenced by aliases.
+
+With those options set, devices with an alias (e.g. "serial2") will get that
+sequence number (e.g. 2). Other devices get the next available number after all
+aliases and all existing numbers. This means that if there is just a single
+alias "serial2", unaliased serial devices will be assigned 3 or more, with 0 and
+1 being unused.
+
+If CONFIG_DM_SEQ_ALIAS or DM_UC_FLAG_SEQ_ALIAS are not set, all devices will get
+sequence numbers in a simple ordering starting from 0. To find the next number
+to allocate, driver model scans through to find the maximum existing number,
+then uses the next one. It does not attempt to fill in gaps.
 
 .. code-block:: none
 
@@ -546,12 +558,18 @@ More commonly you can use node references, which expand to the full path:
 The alias resolves to the same string in this case, but this version is
 easier to read.
 
-Device sequence numbers are resolved when a device is probed. Before then
-the sequence number is only a request which may or may not be honoured,
-depending on what other devices have been probed. However the numbering is
-entirely under the control of the board author so a conflict is generally
-an error.
+Device sequence numbers are resolved when a device is bound and the number does
+not change for the life of the device.
+
+There are some situations where the uclass must allocate sequence numbers,
+since a strictly increase sequence (with devicetree nodes bound first) is not
+suitable. An example of this is the PCI bus. In this case, you can set the
+uclass DM_UC_FLAG_NO_AUTO_SEQ flag. With this flag set, only devices with an
+alias will be assigned a number by driver model. The rest is left to the uclass
+to sort out, e.g. when enumerating the bus.
 
+Note that changing the sequence number for a device (e.g. in a driver) is not
+permitted. If it is felt to be necessary, ask on the mailing list.
 
 Bus Drivers
 -----------
@@ -673,6 +691,10 @@ plat will be NULL, but of_offset will be the offset of the device tree
 node that caused the device to be created. The uclass is set correctly for
 the device.
 
+The device's sequence number is assigned, either the requested one or the next
+available one (after all aliases are processed) if nothing particular is
+requested.
+
 The device's bind() method is permitted to perform simple actions, but
 should not scan the device tree node, not initialise hardware, nor set up
 structures or allocate memory. All of these tasks should be left for
@@ -780,11 +802,7 @@ as above and then following these steps (see device_probe()):
    This means (for example) that an I2C driver will require that its bus
    be activated.
 
-   2. The device's sequence number is assigned, either the requested one
-   (assuming no conflicts) or the next available one if there is a conflict
-   or nothing particular is requested.
-
-   4. The device's probe() method is called. This should do anything that
+   2. The device's probe() method is called. This should do anything that
    is required by the device to get it going. This could include checking
    that the hardware is actually present, setting up clocks for the
    hardware and setting up hardware registers to initial values. The code
@@ -799,9 +817,9 @@ as above and then following these steps (see device_probe()):
    allocate the priv space here yourself. The same applies also to
    plat_auto. Remember to free them in the remove() method.
 
-   5. The device is marked 'activated'
+   3. The device is marked 'activated'
 
-   10. The uclass's post_probe() method is called, if one exists. This may
+   4. The uclass's post_probe() method is called, if one exists. This may
    cause the uclass to do some housekeeping to record the device as
    activated and 'known' by the uclass.
 
@@ -850,14 +868,7 @@ remove it. This performs the probe steps in reverse:
         or preferably of_to_plat()) and the deallocation in remove()
         are the responsibility of the driver author.
 
-   5. The device sequence number is set to -1, meaning that it no longer
-   has an allocated sequence. If the device is later reactivated and that
-   sequence number is still free, it may well receive the name sequence
-   number again. But from this point, the sequence number previously used
-   by this device will no longer exist (think of SPI bus 2 being removed
-   and bus 2 is no longer available for use).
-
-   6. The device is marked inactive. Note that it is still bound, so the
+   5. The device is marked inactive. Note that it is still bound, so the
    device structure itself is not freed at this point. Should the device be
    activated again, then the cycle starts again at step 2 above.
 
-- 
2.29.2.684.gfbc64c5ab5-goog