From patchwork Wed Nov 14 16:02:21 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Stefano Babic X-Patchwork-Id: 997811 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=googlegroups.com (client-ip=2a00:1450:4864:20::53f; helo=mail-ed1-x53f.google.com; envelope-from=swupdate+bncbcxploxj6ikrbhmowhpqkgqezk5igyi@googlegroups.com; receiver=) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=denx.de Authentication-Results: ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=googlegroups.com header.i=@googlegroups.com header.b="Rq4kP7co"; dkim-atps=neutral Received: from mail-ed1-x53f.google.com (mail-ed1-x53f.google.com [IPv6:2a00:1450:4864:20::53f]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 42w8Qm1yGnz9sBN for ; Thu, 15 Nov 2018 03:02:40 +1100 (AEDT) Received: by mail-ed1-x53f.google.com with SMTP id h24-v6sf8615510ede.9 for ; Wed, 14 Nov 2018 08:02:40 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1542211357; cv=pass; d=google.com; s=arc-20160816; b=AADFT7LZUQkyq6MXY2ZBa0PQWblsw6eA3+LELuSJIEeP0rEEZEmIRipTODSC+hXpMW AkWVNmeciCNh64bcjjN3qfkTLDNnxzftRIifX2lDbs0Zh11NFPH56aEfrAppJdBR93oB ov/GgRfWb1coMLB3D9xP78W/kIiRyXrXm+92wrln6uzMuUg3sqav8DcW4d52SewSkukP 0ftdxmiiekIBz7KMoMmsnqayImvZfkW/OG+zvMbEVnIno/8SD1P434zW3+tqAQoeIJMn pGn4Y443LNIv1dOO9ixyn0n7PhON27IScqEIjmyjlo/yknD/EGdwMXVlhR1to5BY0xIU HdKQ== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-unsubscribe:list-subscribe:list-archive:list-help:list-post :list-id:mailing-list:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from:sender:dkim-signature; bh=P2VTWFspMuGrMhUU89prrdXvLPbntRmCoIhpqsuzgiM=; b=RZ/7U4hbc5Krii+wTAIo1b4MiU16yZ19bIxs4ZAKo2EWUPJ1OzokaDm7ciCwH17XTh n5JUntVUgW+YM5xlvua+FBYFUcA/rmHF4DEq3w3QaZEqVYvoTdBe2L8H8LCjQ89pfLA9 YlsaFjQC7klynfICfuF9NP22OryOOxqXLiXyUl4atunfQzWcdY9oMfFem6QtUKLK3Cop rqfc++lVVv4JprG9FnqI9fXtqJgUjr1YS8hPwG6tCHSqsjjhNTa7sLOj9EWjjKnq4c6y ioRY1NTQ3jIg4lgxRFyGt0Ed541oizUaQDmWIqG4ZULBxmv8aS8m7vyVAoqtRIdFr2EZ IYNA== ARC-Authentication-Results: i=2; gmr-mx.google.com; spf=neutral (google.com: 212.18.0.9 is neither permitted nor denied by best guess record for domain of sbabic@denx.de) smtp.mailfrom=sbabic@denx.de DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlegroups.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding:x-original-sender :x-original-authentication-results:precedence:mailing-list:list-id :list-post:list-help:list-archive:list-subscribe:list-unsubscribe; bh=P2VTWFspMuGrMhUU89prrdXvLPbntRmCoIhpqsuzgiM=; b=Rq4kP7co8PwiVea7HrCV06dSLMi78v1WHxNeiRqwoiZQouL5D3+ZIlGRZZ1UtKZnh1 fSMw6LLCFYsBTGYtzWUlKqo3HMoI4oCRTP1eWqzJdnSrCO0ei5xqrfSFNNEu9F2ukHOk Uh+8UtfeL7LE7aoGwLVnfd8Io76QA1zq0kJaooU+dY4DUbOAf4wHW2tvRWRsL1hL/H+O LmwzGc9Nx6puIa9o5mEqr7TokeYa2rZ07xILCOusUIe3o64kCRaQjnKKCBYJgA+P/Vmj AtXUzEUEcsV8u5gnJh3sf7KLTGbixXfmyqG73385kjrUFFFSIuDMVA4q0L7G/is/xSKE K+2g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=sender:x-gm-message-state:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding :x-original-sender:x-original-authentication-results:precedence :mailing-list:list-id:x-spam-checked-in-group:list-post:list-help :list-archive:list-subscribe:list-unsubscribe; bh=P2VTWFspMuGrMhUU89prrdXvLPbntRmCoIhpqsuzgiM=; b=a2mGilaagH0vB+qzFJgDBjwcbFrHOWp09AK/LvkgbWdUvqcg9l9Xpp0iLRGEeqw8xS pA4RSLr+tUOga9ZfNL1GC6iU4uEk9B0ofz8riE+nTS9QVW58Yjtr9Hn4XI+eoasXFCvs U/R9I5S+j2VQqT9/tMt5DDBJFrvE/oMv5a1q6LA55nlaYZ8//ApqDQK4D937gRPmhzr9 tACNZEgHQbnBobclusvaQt+DflzV9wSCUVS0HCvInVBLkAq59pOTYhUC99CbiIapnrUl +QkMNdML86FypECkdRKOtZAwSOInIBynbzlUM++4KckicuSSwAy+/8ZVuN8ktwGS4QMj yD5g== Sender: swupdate@googlegroups.com X-Gm-Message-State: AGRZ1gJbtAZmwZNyzG1c0QKCNtX8YUEnBf7tx8rhtS+fLvpA5cP6eL3N sWWWl4Pu/s029paOrVzkuNs= X-Google-Smtp-Source: AJdET5fbnrUS69rcWXKeh+HFnHcCLd3qU85n9Eq2zj1/uDc8ftgBwstRKpgKaerfbhNlzXNjthdP0A== X-Received: by 2002:a17:906:70d1:: with SMTP id g17-v6mr7890ejk.2.1542211357786; Wed, 14 Nov 2018 08:02:37 -0800 (PST) X-BeenThere: swupdate@googlegroups.com Received: by 2002:a50:b362:: with SMTP id r31-v6ls3468871edd.0.gmail; Wed, 14 Nov 2018 08:02:37 -0800 (PST) X-Received: by 2002:a50:cb48:: with SMTP id h8-v6mr578338edi.3.1542211357304; Wed, 14 Nov 2018 08:02:37 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1542211357; cv=none; d=google.com; s=arc-20160816; b=nfAODA4GqONvwG+f5q2KsbN4zfg4ugAt6CMl0BGcweTG9Cz35C39b7s+xth5vwV1/X QH4FUNEvU6YEeJ6fX5eNhZO/cLnR2Reyf7MNBeAeDStwJvYAFUx0nMaxsiDbkXoMPcWm NITeqFVytJ7jvfySUQVAp1I/VHsDDB6z6XpQ4c9tsaZD73uIhNGKJwRJNsvNKJzYpqdi EOheFagOaAsZxKYpestAdd/Up0DZaRfqcqiQhRLY/oDFZJCAJcuQlB022v2A2U/7y6zl i720pYULhRBsnx9QhTYcI9ba28WsELK1NEthCkhNBDlAw5YfpDZnv3I6gTcSuo+pjbju XCUg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from; bh=pvOTfapSjntrmbzJitZvuEpKz21385AIm4mdCfReJpY=; b=oxDAlj3kWzj4qhMf5j0T5cOngsOe/ID0hI8UfPT48rbTvHjyXY2hL/RhEIN7CCCY9s R8KlQqrN5nXNxfbXAvc5RNUpVSNabpBg9zaDN0mXBwqaE1nSWzvuP/DFuV7/rD751yyP D6aST/SxdaMZh0kL5jqmRGFLkND5dw3maAyjLdEmKWGqZaqc3aEK+kaK2okgwzuhO8BB WqMn4/l2xBF99BPpWCwoHI2hmts+dODqOO8EUmgfHMdC8zzPvZKBsncvvESZQrAW5QIG 2ideQ5ueir5g/rOAxBk3XIRpfNJjqZP2mrr5MKaPqO/mfHoHXk/qLhS+E8T4dtr9qFS0 ub2g== ARC-Authentication-Results: i=1; gmr-mx.google.com; spf=neutral (google.com: 212.18.0.9 is neither permitted nor denied by best guess record for domain of sbabic@denx.de) smtp.mailfrom=sbabic@denx.de Received: from mail-out.m-online.net (mail-out.m-online.net. [212.18.0.9]) by gmr-mx.google.com with ESMTPS id a35-v6si1237064edd.1.2018.11.14.08.02.37 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 14 Nov 2018 08:02:37 -0800 (PST) Received-SPF: neutral (google.com: 212.18.0.9 is neither permitted nor denied by best guess record for domain of sbabic@denx.de) client-ip=212.18.0.9; Received: from frontend01.mail.m-online.net (unknown [192.168.8.182]) by mail-out.m-online.net (Postfix) with ESMTP id 42w8Qj0FS7z1r01X; Wed, 14 Nov 2018 17:02:37 +0100 (CET) Received: from localhost (dynscan1.mnet-online.de [192.168.6.70]) by mail.m-online.net (Postfix) with ESMTP id 42w8Qj04zBz1qsJK; Wed, 14 Nov 2018 17:02:37 +0100 (CET) X-Virus-Scanned: amavisd-new at mnet-online.de Received: from mail.mnet-online.de ([192.168.8.182]) by localhost (dynscan1.mail.m-online.net [192.168.6.70]) (amavisd-new, port 10024) with ESMTP id 0bO-UNPSeNjC; Wed, 14 Nov 2018 17:02:36 +0100 (CET) Received: from babic.homelinux.org (host-88-217-136-221.customer.m-online.net [88.217.136.221]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.mnet-online.de (Postfix) with ESMTPS; Wed, 14 Nov 2018 17:02:36 +0100 (CET) Received: from localhost (mail.babic.homelinux.org [127.0.0.1]) by babic.homelinux.org (Postfix) with ESMTP id AFD494540474; Wed, 14 Nov 2018 17:02:35 +0100 (CET) X-Virus-Scanned: Debian amavisd-new at babic.homelinux.org Received: from babic.homelinux.org ([127.0.0.1]) by localhost (mail.babic.homelinux.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id n_jw6oX6pyyP; Wed, 14 Nov 2018 17:02:32 +0100 (CET) Received: from papero.fritz.box (papero.fritz.box [192.168.178.132]) by babic.homelinux.org (Postfix) with ESMTP id 5E1D04540664; Wed, 14 Nov 2018 17:02:24 +0100 (CET) From: Stefano Babic To: swupdate@googlegroups.com Cc: Stefano Babic Subject: [swupdate] [PATCH v2 5/5] doc: explain usage of links in sw-description Date: Wed, 14 Nov 2018 17:02:21 +0100 Message-Id: <20181114160221.18242-6-sbabic@denx.de> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20181114160221.18242-1-sbabic@denx.de> References: <20181114160221.18242-1-sbabic@denx.de> MIME-Version: 1.0 X-Original-Sender: sbabic@denx.de X-Original-Authentication-Results: gmr-mx.google.com; spf=neutral (google.com: 212.18.0.9 is neither permitted nor denied by best guess record for domain of sbabic@denx.de) smtp.mailfrom=sbabic@denx.de Precedence: list Mailing-list: list swupdate@googlegroups.com; contact swupdate+owners@googlegroups.com List-ID: X-Spam-Checked-In-Group: swupdate@googlegroups.com X-Google-Group-Id: 605343134186 List-Post: , List-Help: , List-Archive: , List-Unsubscribe: , Signed-off-by: Stefano Babic --- Changes in v2: None doc/source/sw-description.rst | 225 ++++++++++++++++++++++++++++++++++ 1 file changed, 225 insertions(+) diff --git a/doc/source/sw-description.rst b/doc/source/sw-description.rst index 36c02b2..51fe670 100644 --- a/doc/source/sw-description.rst +++ b/doc/source/sw-description.rst @@ -318,6 +318,231 @@ while another device can have raw flash and install an UBI filesystem. Neverthel both just a different format of the same release and they could be described together in sw-description. It is important to understand the priorities how SWUpdate scans for entries during the parsing. +Using links +----------- + +sw-description can become very complex. Let's think to have just one board, but in multiple +hw revision and they differ in Hardware. Some of them can be grouped together, some of them +require a dedicated section. A way (but not the only one !) could be to add *mode* and selects +the section with `-e stable,`. + +:: + + software = + { + version = "0.1.0"; + + myboard = { + stable = { + + hardware-compatibility: ["1.0", "1.2", "2.0", "1.ยง, "3.0", "3.1"]; + rev-1.0: { + images: ( + ... + ); + scripts: ( + ... + ); + } + rev-1.2: { + hardware-compatibility: ["1.2"]; + images: ( + ... + ); + scripts: ( + ... + ); + } + rev-2.0: { + hardware-compatibility: ["2.0"]; + images: ( + ... + ); + scripts: ( + ... + ); + } + rev-1.3: { + hardware-compatibility: ["1.3"]; + images: ( + ... + ); + scripts: ( + ... + ); + } + + rev-3.0: + { + hardware-compatibility: ["3.0"]; + images: ( + ... + ); + scripts: ( + ... + ); + } + rev-3.1: + { + hardware-compatibility: ["3.1"]; + images: ( + ... + ); + scripts: ( + ... + ); + } + } + } + } + +If each of them requires an own section, it is the way to do. Anyway, it is more probable +than revisions can be grouped together, for example board with the same major revision +number could have the same installation instructions. This leads in the example to 3 groups +for rev1.X, rev2.X and rev3.X. Links allow to group section together. When a string is found +when SWUpdate searches for a group (images, files, script, bootenv), it replaces the current path +in the tree with the value of the string. In this way, the example above can be written in this way: + +:: + + software = + { + version = "0.1.0"; + + myboard = { + stable = { + + hardware-compatibility: ["1.0", "1.2", "2.0", "1.3, "3.0", "3.1"]; + rev-1x: { + images: ( + ... + ); + scripts: ( + ... + ); + } + rev1.0 = { + ref = "#../rev-1x"; + } + rev1.2 = { + ref = "#../rev-1x"; + } + rev1.3 = { + ref = "#../rev-1x"; + } + rev-2x: { + images: ( + ... + ); + scripts: ( + ... + ); + } + rev2.0 = { + ref = "#../rev-2x"; + } + + rev-3x: + { + images: ( + ... + ); + scripts: ( + ... + ); + } + rev3.0 = { + ref = "#../rev-3x"; + } + rev3.1 = { + ref = "#../rev-3x"; + } + } + } + } + +The link can be absolute or relative. The keyword *"ref"* is used to indicate a link. If this is found, SWUpdate +will traverse the tree and replaces the current path with the values find in the string pointed by "ref". There are +simple rules for a link: + + - it must start with the character '#' + - "." points to the current level in the tree + - ".." points to the parent level in the tree + - "/" is used as filed separator in the link + + +A relative path has a number of +leading "../" to move the current cursor to the parent leaf of the tree. +In the following example, rev40 sets a link to a "common" section, where `images` +is found. This is sets via a link, too, to a section in the parent node. +The path `software.myboard.stable.common.images` is then replaced by +`software.myboard.stable.trythis` + +:: + + software = + { + version = { + ref = "#../commonversion"; + } + + hardware-compatibility = ["rev10", "rev11", "rev20"]; + + commonversion = "0.7-linked"; + + pc:{ + stable:{ + + common:{ + images = + { + ref = "#../../trythis"; + } + }; + + trythis:( + { + filename = "rootfs1.ext4"; + device = "/dev/mmcblk0p8"; + type = "raw"; + } , + { + filename = "rootfs5.ext4"; + device = "/dev/mmcblk0p7"; + type = "raw"; + } + ); + pdm3rev10: + { + images:( + { + filename = "rootfs.ext3"; device = "/dev/mmcblk0p2";} + ); + uboot:( + { name = "bootpart"; + value = "0:2";} + ); + }; + pdm3rev11 = + { + ref = "#../pdm3rev10"; + } + pdm3rev20 = + { + ref = "#../pdm3rev10"; + } + pdm3rev40 = + { + ref = "#../common"; + } + }; + }; + } + + +Each entry in sw-description can be redirect by a link as in the above example for the +"version" attribute. + hardware-compatibility ----------------------