From patchwork Sat Jan 14 11:51:51 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Heinrich Schuchardt X-Patchwork-Id: 1726573 X-Patchwork-Delegate: xypron.glpk@gmx.de Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=lists.denx.de (client-ip=85.214.62.61; helo=phobos.denx.de; envelope-from=u-boot-bounces@lists.denx.de; receiver=) Authentication-Results: legolas.ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=canonical.com header.i=@canonical.com header.a=rsa-sha256 header.s=20210705 header.b=cPr/GpjL; dkim-atps=neutral Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-384) server-digest SHA384) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4NvGqF1fQjz23fk for ; Sat, 14 Jan 2023 22:52:09 +1100 (AEDT) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 459A38118B; Sat, 14 Jan 2023 12:52:02 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=canonical.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (2048-bit key; unprotected) header.d=canonical.com header.i=@canonical.com header.b="cPr/GpjL"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 686F984B51; Sat, 14 Jan 2023 12:52:00 +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=-2.1 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,SPF_HELO_NONE, SPF_PASS autolearn=ham autolearn_force=no version=3.4.2 Received: from smtp-relay-canonical-1.canonical.com (smtp-relay-canonical-1.canonical.com [185.125.188.121]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 0BB1980F98 for ; Sat, 14 Jan 2023 12:51:58 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=canonical.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=heinrich.schuchardt@canonical.com Received: from LT2ubnt.fritz.box (ip-088-152-145-137.um26.pools.vodafone-ip.de [88.152.145.137]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by smtp-relay-canonical-1.canonical.com (Postfix) with ESMTPSA id 33BD343825; Sat, 14 Jan 2023 11:51:55 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=canonical.com; s=20210705; t=1673697115; bh=YRtornLgiszl7Ug8pg96qGGzNmr9KhwicRNrR+W9PBY=; h=From:To:Cc:Subject:Date:Message-Id:MIME-Version; b=cPr/GpjLSR/qQ9i//obSnjKicZH82IMK2VDi6E7fG1+eowe+foSrAj5s6wE8MZ6U3 qdpz9mPYu1acvITADVrFLGMQpTQ7Fy7z1Ef4SRqaS0gJBV6YiY4Xan79faQXxJYOnO 8nyZpNtBPTGIo1XgGJ/KpJHeGScuiJWTmuGMMcWMGKIODqWVPHYpxgJYlbE/rIkaW1 K5vze/iRSLODSZxc3Xd+tGGMFTWy5Xevcl98pWfuFR5190h3eFzjLZKIFTTFjSFfQD 4zDr4ftrdXUaEcLJMRQlP5F8vzt6U76+O2Z4hPVqDBxoKOFq8YehoS6/vSCxg3Gjkk vwofq7wgZMb0w== From: Heinrich Schuchardt To: u-boot@lists.denx.de Cc: Simon Glass , Sean Anderson , Heinrich Schuchardt Subject: [PATCH 1/1] doc: man-page for source command Date: Sat, 14 Jan 2023 12:51:51 +0100 Message-Id: <20230114115151.59487-1-heinrich.schuchardt@canonical.com> X-Mailer: git-send-email 2.37.2 MIME-Version: 1.0 X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.39 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.6 at phobos.denx.de X-Virus-Status: Clean Provide a man-page for the source command. Signed-off-by: Heinrich Schuchardt --- doc/usage/cmd/source.rst | 154 +++++++++++++++++++++++++++++++++++++++ doc/usage/index.rst | 1 + 2 files changed, 155 insertions(+) create mode 100644 doc/usage/cmd/source.rst diff --git a/doc/usage/cmd/source.rst b/doc/usage/cmd/source.rst new file mode 100644 index 0000000000..9622f1d5a8 --- /dev/null +++ b/doc/usage/cmd/source.rst @@ -0,0 +1,154 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2022, Heinrich Schuchardt + +source command +============== + +Synopsis +-------- + +:: + + source [][:[]|#[]] + +Description +----------- + +The *source* command is used to execute a script file from memory. + +Two formats for script files exist: + +* legacy U-Boot image format +* Flat Image Tree (FIT) + +Both formats can be created with the mkimage tool. + +addr + location of the script file in memory, defaults to CONFIG_SYS_LOAD_ADDR. + +image + name of an image in a FIT file + +config + name of a configuration in a FIT file + +Examples +-------- + +For creating a FIT image an image tree source file (\*.its) is needed. Here is +an example (source.its). + +.. code-block:: + + /dts-v1/; + + / { + description = "FIT image to test the source command"; + #address-cells = <1>; + + images { + default = "script-1"; + + script-1 { + data = "echo 1"; + type = "script"; + compression = "none"; + }; + + script-2 { + data = "echo 2"; + type = "script"; + compression = "none"; + }; + }; + + configurations { + default = "conf-2"; + + conf-1 { + script = "script-1"; + }; + + conf-2 { + script = "script-2"; + }; + }; + }; + +The FIT image file (boot.itb) is created with: + +.. code-block:: bash + + mkimage -f source.its boot.itb + +In U-Boot the script can be loaded and execute like this + +.. code-block:: + + => load host 0:1 $loadaddr boot.itb + 1552 bytes read in 0 ms + => source $loadaddr#conf-1 + ## Executing script at 00000000 + 1 + => source $loadaddr#conf-2 + ## Executing script at 00000000 + 2 + => source $loadaddr:script1 + ## Executing script at 00000000 + Can't find 'script1' FIT subimage + => source $loadaddr:script-1 + ## Executing script at 00000000 + 1 + => source $loadaddr:script-2 + ## Executing script at 00000000 + 2 + => source $loadaddr + ## Executing script at 00000000 + 2 + => source + ## Executing script at 00000000 + 2 + => + +A legacy boot script can be created starting with a text file. +Here is an example file (boot.txt): + +.. code-block:: bash + + echo Hello from a script + echo ------------------- + +The boot scripts (boot.scr) is created with: + +.. code-block:: bash + + mkimage -T script -n 'Test script' -d boot.txt boot.scr + +The script can be execute in U-boot like this: + +.. code-block:: + + => load host 0:1 $loadaddr boot.scr + 122 bytes read in 0 ms + => source $loadaddr + ## Executing script at 00000000 + Hello from a script + ------------------- + => source + ## Executing script at 00000000 + Hello from a script + ------------------- + => + +Configuration +------------- + +The source command is only available if CONFIG_CMD_SOURCE=y. +The FIT image file format requires CONFIG_FIT=y.# +The legacy U-Boot image file format requires CONFIG_LEGACY_IMAGE_FORMAT=y. + +Return value +------------ + +If the scripts is executed successfully, the return value $? is 0 (true). +Otherwise it is 1 (false). diff --git a/doc/usage/index.rst b/doc/usage/index.rst index bbd40a6e18..14457aba69 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -74,6 +74,7 @@ Shell commands cmd/setexpr cmd/size cmd/sound + cmd/source cmd/temperature cmd/tftpput cmd/true