From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 1D75BC433F5 for ; Thu, 14 Oct 2021 18:24:07 +0000 (UTC) Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 73150611C7 for ; Thu, 14 Oct 2021 18:24:06 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 73150611C7 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=chromium.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=lists.denx.de Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 924A783677; Thu, 14 Oct 2021 20:24:04 +0200 (CEST) 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="U6k1zKwR"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 637BA83649; Thu, 14 Oct 2021 20:23:36 +0200 (CEST) Received: from mail-io1-xd31.google.com (mail-io1-xd31.google.com [IPv6:2607:f8b0:4864:20::d31]) (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 2E4C9837CF for ; Thu, 14 Oct 2021 20:23:15 +0200 (CEST) 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-io1-xd31.google.com with SMTP id 188so4834654iou.12 for ; Thu, 14 Oct 2021 11:23:15 -0700 (PDT) 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=HQrbbJF/Q65TIi/PEVzyk78UhnVphzjs5BrhnbRbf4U=; b=U6k1zKwRCp2fSNeFehQwqwQ43GuaJ65FeOp8q2UIZ3aCnnS7PXbt55VzV4hzkKpiIM HTN3LM6Uhmf8bC3Sc0ldKfvTts2thOCNLAgExgJUSHSkwgoyCCOj4I1vhZzFKt2G6oNt rH/7uDWCCzMnMHybkX6b9sLnOTqmMWGWiKaj8= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=HQrbbJF/Q65TIi/PEVzyk78UhnVphzjs5BrhnbRbf4U=; b=ygow2lbrKBxF2sLslNoAhM80kTvZabPyN0D315Ji3hPGNmn2qLChOsdRRpuqS7q4Gm kzNwIIcNvpNcVvVqaiZ2KEaM+rJ1LSzk1ihy+HiahdnhdGhaMFdhZSlbfQyytIpjqvys 0/pCyXJx7GhaxyShZL2FErfvK9KkBbhIwm+4LGQu03DqF+kSS07eDYUhgwdGd11zJAdE jBVDgxe3c81nMa51kkj1s90jY50eqOqHlAQwTStTEBxMmj83GfX3chHZV2MpE/9sj4HS HmXEX3VQrQOu8ZmTOU6GVo/JnAdbbHXD8FmdUXqtyyU/m7CClRO1o2rv0xPKidpowIQl fpyg== X-Gm-Message-State: AOAM530MIk5EZan9gjDe6bPX8dqlwFj4rhb9ARHYEQg9oQvqqjDKD69h VHsqvk45bvoPXFv4Y2XhuEM1xFFSLPjuUw== X-Google-Smtp-Source: ABdhPJwU3D2XlqZra4NAn842o+6woe2906r+29H609gm4ssqZoKlqbuXLMnUmYf8KmNc/nKF3FySxw== X-Received: by 2002:a6b:7107:: with SMTP id q7mr396204iog.63.1634235788662; Thu, 14 Oct 2021 11:23:08 -0700 (PDT) Received: from kiwi.bld.corp.google.com (c-67-190-101-114.hsd1.co.comcast.net. [67.190.101.114]) by smtp.gmail.com with ESMTPSA id h26sm1717536ila.4.2021.10.14.11.23.07 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 14 Oct 2021 11:23:08 -0700 (PDT) From: Simon Glass To: U-Boot Mailing List Cc: Heinrich Schuchardt , Tom Rini , Wolfgang Denk , Simon Glass Subject: [PATCH v6 6/7] doc: Improve environment documentation Date: Thu, 14 Oct 2021 12:22:56 -0600 Message-Id: <20211014182257.468649-5-sjg@chromium.org> X-Mailer: git-send-email 2.33.0.1079.g6e70778dc9-goog In-Reply-To: <20211014182257.468649-1-sjg@chromium.org> References: <20211014182257.468649-1-sjg@chromium.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit 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.103.2 at phobos.denx.de X-Virus-Status: Clean Make various updates suggested during review of the rST conversion. Signed-off-by: Simon Glass Suggested-by: Wolfgang Denk --- Changes in v6: - Move all updates to a separate patch - More updates and improvements Changes in v5: - Minor updates as suggested by Wolfgang Changes in v4: - Add new patch to move environment documentation to rST doc/usage/environment.rst | 35 ++++++++++++++++++++++++++--------- doc/usage/index.rst | 1 + 2 files changed, 27 insertions(+), 9 deletions(-) diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst index 76915484b85..ef9cd20715a 100644 --- a/doc/usage/environment.rst +++ b/doc/usage/environment.rst @@ -5,16 +5,20 @@ Environment Variables U-Boot supports user configuration using Environment Variables which -can be made persistent by saving to Flash memory. +can be made persistent by saving to persistent storage, for example flash +memory. -Environment Variables are set using "setenv", printed using -"printenv", and saved to Flash using "saveenv". Using "setenv" +Environment Variables are set using "env set" (alias "setenv"), printed using +"env print" (alias "printenv"), and saved to persistent storage using +"env save" (alias "saveenv"). Using "env set" without a value can be used to delete a variable from the environment. As long as you don't save the environment you are working with an in-memory copy. In case the Flash area containing the environment is erased by accident, a default environment is provided. -Some configuration options can be set using Environment Variables. +Some configuration is controlled by Environment Variables, so that setting the +variable can adjust the behaviour of U-Boot (e.g. autoboot delay, autoloading +from tftp). The default environment is created in `include/env_default.h`, and can be augmented by various `CONFIG` defines. See that file for details. In @@ -68,18 +72,25 @@ Example:: echo CONFIG_SYS_BOARD boot failed - please check your image echo Load address is CONFIG_SYS_LOAD_ADDR -Some configuration options can be set using Environment Variables. +Some configuration options can be set using Environment Variables. In many cases +the value in the default environment comes from a CONFIG option - see +`include/env_default.h`) for this. + List of environment variables (most likely not complete): baudrate - see CONFIG_BAUDRATE + Current baud rate used by the serial console. The built-in value is set by + CONFIG_BAUDRATE (see `drivers/serial/Kconfig`) bootdelay - see CONFIG_BOOTDELAY + Current autoboot delay. The built-in value is set by CONFIG_BOOTDELAY (see + `common/Kconfig`) bootcmd - see CONFIG_BOOTCOMMAND + Defines a command string that is automatically executed when no character + is read on the console interface within a cetain boot delay after reset. + The built-in value is set by CONFIG_BOOTCOMMAND (see `common/Kconfig`) bootargs Boot arguments when booting an RTOS image @@ -125,7 +136,7 @@ autoload if set to "no" (any string beginning with 'n'), "bootp" will just load perform a lookup of the configuration from the BOOTP server, but not try to - load any image using TFTP + load any image using TFTP or DHCP. autostart if set to "yes", an image loaded using the "bootp", @@ -291,6 +302,8 @@ vlan Ethernet is encapsulated/received over 802.1q VLAN tagged frames. + Note: This appears not to be used in U-Boot. See `README.VLAN`. + bootpretryperiod Period during which BOOTP/DHCP sends retries. Unsigned value, in milliseconds. If not set, the period will @@ -332,6 +345,10 @@ flash or offset in NAND flash. boards currently use other variables for these purposes, and some boards use these variables for other purposes. +Also note that most of these variables are just a commonly used set of variable +names, used in some other variable definitions, but are not hard-coded anywhere +in U-Boot code. + ================= ============== ================ ============== Image File Name RAM Address Flash Location ================= ============== ================ ============== diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 356f2a56181..1a79d1c03eb 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -5,6 +5,7 @@ Use U-Boot :maxdepth: 1 dfu + environment fdt_overlays fit netconsole -- 2.33.0.1079.g6e70778dc9-goog