From patchwork Mon Nov 30 01:54:02 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 1407949 X-Patchwork-Delegate: sjg@chromium.org Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=lists.denx.de (client-ip=2a01:238:438b:c500:173d:9f52:ddab:ee01; helo=phobos.denx.de; envelope-from=u-boot-bounces@lists.denx.de; receiver=) Authentication-Results: ozlabs.org; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=chromium.org header.i=@chromium.org header.a=rsa-sha256 header.s=google header.b=YDXGmNgh; dkim-atps=neutral Received: from phobos.denx.de (phobos.denx.de [IPv6:2a01:238:438b:c500:173d:9f52:ddab:ee01]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4CkpM80j7sz9sTc for ; Mon, 30 Nov 2020 12:59:32 +1100 (AEDT) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id EA52A827F2; Mon, 30 Nov 2020 02:57:41 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (1024-bit key; unprotected) header.d=chromium.org header.i=@chromium.org header.b="YDXGmNgh"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id CE32482786; Mon, 30 Nov 2020 02:55:38 +0100 (CET) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on phobos.denx.de X-Spam-Level: X-Spam-Status: No, score=-3.5 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,RCVD_IN_DNSWL_NONE,SPF_HELO_NONE autolearn=ham autolearn_force=no version=3.4.2 Received: from mail-il1-x144.google.com (mail-il1-x144.google.com [IPv6:2607:f8b0:4864:20::144]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 6A0A1827B1 for ; Mon, 30 Nov 2020 02:55:04 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=sjg@chromium.org Received: by mail-il1-x144.google.com with SMTP id t13so9838194ilp.2 for ; Sun, 29 Nov 2020 17:55:04 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=3bR0fbmBtpiCSyQltPPcGs1dJ/exSAEcysCguZU0epM=; b=YDXGmNghjTzseJYrkW2NnR8pv/x4TxU5atteHRDByem8pB2tHc5slHRf4FEAgDeJEh BH11UJq8BulFzRNeLGeNRMLgTow008acNA+/ydzx5GStwCbAH42ULv1fsbehM1GhkOvK kg6d6JvIEcYTtxOknOAdNrCIJnxT8Y7uzVrVo= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=3bR0fbmBtpiCSyQltPPcGs1dJ/exSAEcysCguZU0epM=; b=AR4JECzy63RZYkvaqQjrT3mgouVUFg52kjbY8jD28p8v+/2OH9GuOBDkkjZavLkIbF vnzThcLn3K1f0YEhYV3qVw5NpwEjMxLmzfYu0TFKIkysaagstuCVFtbVQYcRRXnRyzAt LH0SBPhgzZR3XQUBslktTJ+340GC7M9hcEj+jvb7sBd16G4Mb/rYad5Hlvon5BbRUG6S rmlRZTzr9RvhP2BxAf7nFuJCxXnYdVOzvlgqcQmHDYVA+27fZF3eWLFjox7AD8rBnWi+ FFtLnSrqiccP4Jdz9NEGscvy52muNJRJHL4xn9/Kklr5kjcHdlsRXhkGs+lTI1Gmq+UC v4Sw== X-Gm-Message-State: AOAM531x0hBYBYusXxGaycgkvRlN4KOCT0jfVdHwBg2bKBzugvwaKaYc YNsZ70B45HOemf/p2GPq7SPEwzqDK0427A== X-Google-Smtp-Source: ABdhPJwN5/Nk0qL3amFL8TkHiOI2xqxF+8lytlqY7PdAMTJ6R6Umni9+uOs1FhuZnkzWEz1N63/CjQ== X-Received: by 2002:a92:512:: with SMTP id q18mr7501868ile.147.1606701302741; Sun, 29 Nov 2020 17:55:02 -0800 (PST) Received: from localhost.localdomain (c-67-190-101-114.hsd1.co.comcast.net. [67.190.101.114]) by smtp.gmail.com with ESMTPSA id q5sm6543341ilg.62.2020.11.29.17.55.01 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 29 Nov 2020 17:55:02 -0800 (PST) From: Simon Glass To: U-Boot Mailing List Cc: Simon Glass , Marek Vasut , Pavel Herrmann Subject: [PATCH 27/27] dm: Update documentation for new sequence numbers Date: Sun, 29 Nov 2020 18:54:02 -0700 Message-Id: <20201130015402.2328621-26-sjg@chromium.org> X-Mailer: git-send-email 2.29.2.454.gaff20da3a2-goog In-Reply-To: <20201130015402.2328621-1-sjg@chromium.org> References: <20201130015402.2328621-1-sjg@chromium.org> MIME-Version: 1.0 X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.34 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.102.3 at phobos.denx.de X-Virus-Status: Clean Update the driver model documention to describe how sequence numbers now work. Signed-off-by: Simon Glass --- doc/driver-model/design.rst | 58 +++++++++++++++++++++---------------- 1 file changed, 33 insertions(+), 25 deletions(-) diff --git a/doc/driver-model/design.rst b/doc/driver-model/design.rst index 96525b6ccc5..2db00e660e1 100644 --- a/doc/driver-model/design.rst +++ b/doc/driver-model/design.rst @@ -515,11 +515,15 @@ 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. +Whether a device gets a 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 and no devices will get +sequence numbers. -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 DM_SEQ_ALIAS is enabled, the uclass must have the DM_UC_FLAG_SEQ_ALIAS +flag set, for its devices to be sequenced. If DM_UC_FLAG_SEQ_ALIAS is set for +the uclass, all devices in that uclass will get a sequence number, either one +set from the aliases, or the next available sequence number. .. code-block:: none @@ -546,12 +550,23 @@ 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. +When U-Boot initially binds all its devices, it sets a flag called +GD_FLG_DM_NO_SEQ. This makes it check the aliases first. Then the devices with +no alias fill in the gaps. + +For example, if aliases mmc2 and mmc3 are defined but there is a third mmc +device with no alias, it will be assigned a sequence number of 0. However once +the initial setup is complete, the GD_FLG_DM_NO_SEQ flag is cleared and further +devices will be assigned numbers after all existing ones for that uclass. So +in this case calling device_bind() for a fourth mmc device will cause it to +get a sequence number of 4, not 1. This helps separate the aliases (which are +considered officially allocated numbers) from ad-hoc devices. + +Note that changing the sequence number for a device (e.g. in driver) is not +permitted. If it is felt to be necessary, ask on the mailing list. Bus Drivers ----------- @@ -673,6 +688,10 @@ platdata 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 @@ -735,7 +754,7 @@ The steps are: that U-Boot will cache platform data for devices which are regularly de/activated). - 5. The device is marked 'platdata valid'. + 6. The device is marked 'platdata valid'. 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 @@ -780,11 +799,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 +814,9 @@ as above and then following these steps (see device_probe()): allocate the priv space here yourself. The same applies also to platdata_auto_alloc_size. 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 +865,7 @@ remove it. This performs the probe steps in reverse: or preferably ofdata_to_platdata()) 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.