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 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 smtp.lore.kernel.org (Postfix) with ESMTPS id C17E8C43334 for ; Sat, 25 Jun 2022 17:14:49 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 73564844C6; Sat, 25 Jun 2022 19:13:03 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmail.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=gmail.com header.i=@gmail.com header.b="Xg4H9IUo"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 66BE88439F; Sat, 25 Jun 2022 19:12:43 +0200 (CEST) Received: from mail-qv1-xf30.google.com (mail-qv1-xf30.google.com [IPv6:2607:f8b0:4864:20::f30]) (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 B5C1184488 for ; Sat, 25 Jun 2022 19:12:37 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=seanga2@gmail.com Received: by mail-qv1-xf30.google.com with SMTP id q4so9108218qvq.8 for ; Sat, 25 Jun 2022 10:12:37 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=vOtLgWzB1jrk5/TBOM1cXgnFE8ncVHo6Bgo/vDMAnPY=; b=Xg4H9IUoZiLhm8wPsfjBv2KmtNZ++7FvQ8/dJWL3u0kXKByDiLLyYbhLp/NfbIjvzu xWLNkSuIUO9hKpgNJ4JVY42eWFg+3zDs0ORoTu7xttvnbncmI4+NvSvxuj9iwG8bbirg JiN+cpE/tf1vTnLCqN/+/gRF3ncbPOOizL3A7djtFiO9iiC4IE55LLulUdf8g/fcQMRC fKDXgd3TOGIuDh74o3JGHdxn9c5sojOnKkxDDkihh4/u//iEu2Tte4J0Ow2voWeou3uG RCl9fyT8mDxRRJkupVbo6+pMGHCFPA4iSevu780ebUP2tlKNEBtlJcxZ0h8oMpfwr/RO H2VQ== 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=vOtLgWzB1jrk5/TBOM1cXgnFE8ncVHo6Bgo/vDMAnPY=; b=qGWUeEuaj7tNpyUzgiaLRndiJQ97GHV8j8H3gGFu1CE8JWGkSthFe26JK3OHdPNWri zmcpbT1mhwiX4a0k7uJ2Qh3eSxmwttT2F+9nCpho4LeELJCnh+qxSLQW+FxdkZl63VHO zpc9SAGjvNX3RarlXopratEoW6zmsHh1nhwZkEQXdHJVzzv1IsZOjOUPETuHamM0TFrB OT7BvsFJ7FB96k5wo7C+OqMbn/XwRPg7VLHoUrnAnXkRvXVr7wVd57zGCaV9WLL750ZT 9vAGAbqCmKnH0SNdjKLgJKTOhyQdn3eynoTSELQQi3VvS65Um5OVK0UxoWSyERDAzW6e e5nA== X-Gm-Message-State: AJIora+uzFMgxGqy8x171bYJCU9RYAp1EXMhBiG69JyqukOxQU2opxjA Q68aL7dAGhq4gPSnmbkGk571HOymhnm8TVpK X-Google-Smtp-Source: AGRyM1vNwlFHNgb9qLpyJSjj+rZbqVDOusHPbJnGF/5T9mqabP3c4SBizB9lokP+gYhHHe+ej8V59A== X-Received: by 2002:a05:6214:300d:b0:470:4530:79f1 with SMTP id ke13-20020a056214300d00b00470453079f1mr3412260qvb.121.1656177157048; Sat, 25 Jun 2022 10:12:37 -0700 (PDT) Received: from localhost (pool-173-73-95-180.washdc.fios.verizon.net. [173.73.95.180]) by smtp.gmail.com with UTF8SMTPSA id c7-20020a05620a268700b006aef1e5eb87sm4640921qkp.24.2022.06.25.10.12.36 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Sat, 25 Jun 2022 10:12:36 -0700 (PDT) From: Sean Anderson To: u-boot@lists.denx.de, Heinrich Schuchardt Cc: Simon Glass , Sean Anderson Subject: [PATCH v3 13/14] doc: mkimage: Further document -o and -R Date: Sat, 25 Jun 2022 13:12:20 -0400 Message-Id: <20220625171221.2391284-14-seanga2@gmail.com> X-Mailer: git-send-email 2.35.1 In-Reply-To: <20220625171221.2391284-1-seanga2@gmail.com> References: <20220625171221.2391284-1-seanga2@gmail.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit 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 Despite the original description of these options, they are not always image names, or even files. Some image types use these options to convey configuration directly. Re-document these options as configuration options. Additionally, add a new section documenting the format of the configuration for each image type which uses it. In general, if configuration is used directly (without a separate file) I have added documentation for it. If the configuration points to a separate file, I have referenced that file's documentation. Where there is no such documentation, I have added it. Signed-off-by: Sean Anderson --- (no changes since v2) Changes in v2: - New doc/mkimage.1 | 270 +++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 236 insertions(+), 34 deletions(-) diff --git a/doc/mkimage.1 b/doc/mkimage.1 index c310b01bb9..353ea8b2f7 100644 --- a/doc/mkimage.1 +++ b/doc/mkimage.1 @@ -194,44 +194,22 @@ command will jump to this address after loading the image. will be interpreted as a hexadecimal number. . .TP -.BI \-n " image-name" +.BI \-n " primary-configuration" .TQ -.BI \-\-primary\-image " image-name" -Set the image name to -.IR image-name . +.BI \-\-config " primary-configuration" +Images may require additional configuration not specified with other options, +often in a image-type-specific format. The image types which support this +option and the format of their configuration are listed in +.BR CONFIGURATION . . .TP -.BI \-R " secondary-image-name" +.BI \-R " secondary-configuration" .TQ -.BI \-\-secondary\-image " image-name" -Some image types support a second image for additional data. For these types, -use -.B \-R -to specify this second image. -.TS -allbox; -lb lbx -l l. -Image Type Secondary Image Description -pblimage Additional RCW-style header, typically used for PBI commands. -zynqimage, zynqmpimage T{ -Initialization parameters, one per line. Each parameter has the form -.sp -.ti 4 -.I address data -.sp -where -.I address -and -.I data -are hexadecimal integers. The boot ROM will write each -.I data -to -.I address -when loading the image. At most 256 parameters may be specified in this -manner. -T} -.TE +.BI \-\-secondary\-config " secondary-configuration" +Some image types support a second set of configuration data. The image types +which support secondary configuration and the formap of their configuration are +listed in +.BR CONFIGURATION . . .TP .BI \-d " image-data-file" @@ -470,6 +448,230 @@ using But if the original input to mkimage is a binary file (already compiled), then the timestamp is assumed to have been set previously. . +.SH CONFIGURATION +This section documents the formats of the primary and secondary configuration +options for each image type which supports them. +. +.SS aisimage +The primary configuration is a file containing a series of +.I AIS +(Application Image Script) commands, one per line. Each command has the form +.RS +.P +.IR "command argument " .\|.\|. +.RE +.P +See +.UR https://\:www\:.ti\:.com/\:lit/\:pdf/\:spraag0 +TI application report SPRAAG0E +.UE +for details. +. +.SS atmelimage +The primary configuration is a comma-separated list of NAND Flash parameters of +the form +.RS +.P +\fIparameter\fB=\fIvalue\fR[\fB,\fIparameter\fB=\fIvalue\fR.\|.\|.\&] +.RE +.P +Valid +.IR parameter s +are +.RS +.P +.TS +lb. +usePmecc +nbSectorPerPage +spareSize +eccBitReq +sectorSize +eccOffset +.TE +.RE +.P +and valid +.IR value s +are decimal numbers. See section 11.4.4.1 of the SAMA5D3 Series Data Sheet for +valid values for each parameter. +. +.SS imximage +The primary configuration is a file containing configuration commands, as +documented in doc/\:imx/\:mkimage/\:imximage.txt of the U-Boot source. +. +.SS imx8image and imx8mimage +The primary configuration is a file containing configuration commands, as +documented in doc/\:imx/\:mkimage/\:imx8image.txt of the U-Boot source. +. +.SS kwbimage +The primary configuration is a file containing configuration commands, as +documented in doc/\:imx/\:mkimage/\:kwbimage.txt of the U-Boot source. +. +.SS mtk_image +The primary configuration is a semicolon-separated list of header options of the +form +.RS +.P +\fIkey\fB=\fIvalue\fR[\fB;\fIkey\fB=\fIvalue\fR.\|.\|.\&] +.RE +.P +where the valid keys are: +.RS +.P +.TS +lb lbx +lb l. +Key Description +_ +lk T{ +If \fB1\fP, then an \fILK\fP (legacy) image header is used. Otherwise, a +\fIBootROM\fP image header is used. +T} +lkname T{ +The name of the LK image header. The maximum length is 32 ASCII characters. If +not specified, the default value is \fBU-Boot\fP. +T} +media The boot device. See below for valid values. +nandinfo The desired NAND device type. See below for valid values. +arm64 If \fB1\fP, then this denotes an AArch64 image. +hdroffset Increase the reported size of the BRLYT header by this amount. +.TE +.RE +.P +Valid values for +.B media +are: +.RS +.P +.TS +lb lb +lb l. +Value Description +_ +nand Parallel NAND flash +snand Serial NAND flash +nor Serial NOR flash +emmc \fIeMMC\fP (Embedded Multi-Media Card) +sdmmc \fISD\fP (Secure Digital) card +.TE +.RE +.P +Valid values for +.B nandinfo +are: +.RS +.P +.TS +lb lb lb lb lb +lb l l l l. +Value NAND type Page size OOB size Total size +_ +2k+64 Serial 2KiB 64B +2k+120 Serial 2KiB 120B +2k+128 Serial 2KiB 128B +4k+256 Serial 4KiB 256B +1g:2k+64 Parallel 2KiB 64B 1Gbit +2g:2k+64 Parallel 2KiB 64B 2Gbit +4g:2k+64 Parallel 2KiB 64B 4Gbit +2g:2k+128 Parallel 2KiB 128B 2Gbit +4g:2k+128 Parallel 2KiB 128B 4Gbit +.TE +.RE +. +.SS mxsimage +The primary configuration is a file containing configuration commands, as +documented in doc/\:imx/\:mkimage/\:mxsimage.txt of the U-Boot source. +. +.SS omapimage +The primary configuration is the optional value +.BR byteswap . +If present, each 32-bit word of the image will have its bytes swapped +(converting from little-endian to big-endian, or vice versa). +. +.SS pblimage +The primary configuration is a file containing the +.I PBI +(Pre-Boot Image) header. Each line of the configuration has the format +.RS +.P +.IR value "[ " value .\|.\|.\&] +.RE +.P +Where +.I value +is a 32-bit hexadecimal integer. Each +.I value +will, after being converted to raw bytes, be literally prepended to the PBI. +.P +The secondary configuration is a file with the same format as the primary +configuration file. It will be inserted into the image after the primary +configuration data and before the image data. +.P +It is traditional to use the primary configuration file for the +.I RCW +(Reset Configuration Word), and the secondary configuration file for any +additional PBI commands. However, it is also possible to convert an existing PBI +to the above format and \(lqchain\(rq additional data onto the end of the +image. This may be especially useful for creating secure boot images. +. +.SS rkimage +The primary configuration is the name of the processor to generate the image +for. Valid values are: +.RS +.P +.TS +lb. +px30 +rk3036 +rk3066 +rk3128 +rk3188 +rk322x +rk3288 +rk3308 +rk3328 +rk3368 +rk3399 +rv1108 +rk3568 +.TE +.RE +. +.SS sunxi_egon +The primary configuration is the name to use for the device tree. +. +.SS ublimage +The primary configuration is a file containing configuration commands, as +documented in doc/\:README.ublimage of the U-Boot source. +. +.SS zynqimage and zynqmpimage +For +.BR zynqmpimage , +the primary configuration is a file containing the +.I PMUFW +(Power Management Unit Firmware). +.B zynqimage +does not use the primary configuration. +.P +For both image types, the secondary configuration is a file containinig +initialization parameters, one per line. Each parameter has the form +.RS +.P +.I address data +.RE +.P +where +.I address +and +.I data +are hexadecimal integers. The boot ROM will write each +.I data +to +.I address +when loading the image. At most 256 parameters may be specified in this +manner. +. .SH BUGS Please report bugs to the .UR https://\:source\:.denx\:.de/\:u-boot/\:u-boot/\:issues -- 2.35.1