From patchwork Sun Nov 14 17:27:29 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stefano Babic X-Patchwork-Id: 1556019 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: bilbo.ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=googlegroups.com header.i=@googlegroups.com header.a=rsa-sha256 header.s=20210112 header.b=e3DFfEmf; dkim-atps=neutral Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=googlegroups.com (client-ip=2607:f8b0:4864:20::f3f; helo=mail-qv1-xf3f.google.com; envelope-from=swupdate+bncbaabbix52cgamgqetwhry4a@googlegroups.com; receiver=) Received: from mail-qv1-xf3f.google.com (mail-qv1-xf3f.google.com [IPv6:2607:f8b0:4864:20::f3f]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by bilbo.ozlabs.org (Postfix) with ESMTPS id 4Hv2Lq1XbGz9s5P for ; Wed, 17 Nov 2021 10:28:49 +1100 (AEDT) Received: by mail-qv1-xf3f.google.com with SMTP id n4-20020a0ce944000000b003bdcabf4cdfsf858550qvo.16 for ; Tue, 16 Nov 2021 15:28:49 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1637105325; cv=pass; d=google.com; s=arc-20160816; b=lrlcNjFw1Se9t4N9hmp9z5PmCNLIrDsgW354sJrenySAR3fdfhJ/OrRmSIXRjzY9c0 Y89AFlYjiyxD603gwpeVKH+eNwNCtN1vEgasg57xisAnE2HMWuNyY7OnbT14ADlAbxlf 93GavDKAzBMCMph2AHEmkpCLgl615HCm0/SuOyFEJbWGqkJDiDOeaGKzHIQjzrnYgJZp fH347FRLBUb254FAGNKBPig9uOvxGttmCnSqiqf8c6gKDqljgGwAqE9xIwbnJYmwVSEz cJcluWY+lUtslXA2g4EChM95QHD2lHZKAkczNzKgBM+r1L2WDIssK+jvpjGGYrtG0IYS sRpQ== 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:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:sender:dkim-signature; bh=/0W6y2ZhiC0GDvE0yXc8IIWjMCKpIiQl8s0HW+y5u1c=; b=AuuEHJjPZyvFR+AjkaD0kLsrhUPTZKPWyIztCDOiEgf+nwRBRumXcZ+z3Fs0PonpSe GvF7lf3kV+Ip3E3GLsXY5K+38vHgLDysq6X5Z3xauNk2T0wvqVEeVu9pzKsD8Y5Hue5u iB4L5oSgAG7tCUDP1hGQifH2TrtV7F7jR+/pmqfwWVbeAQN4DFDs0v9cOnSSNrrgINvS MCRbHeKpUAzqPFRuT7KCIL+MAF2i6ZEekcpqDLE9jS5yc/VG9iwMQ0EhE5oulTg4dogj MBz/NM4gPIMPnN36pFioLQQcZjCc04WUsjhiBtskPsLAJJXQndH5YQ92o25Kw2JgARSL AlVQ== ARC-Authentication-Results: i=2; gmr-mx.google.com; spf=neutral (google.com: 2001:a60:0:28:0:1:25:1 is neither permitted nor denied by domain of sbabic@denx.de) smtp.mailfrom=sbabic@denx.de DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlegroups.com; s=20210112; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:x-original-sender:x-original-authentication-results :precedence:mailing-list:list-id:list-post:list-help:list-archive :list-subscribe:list-unsubscribe; bh=/0W6y2ZhiC0GDvE0yXc8IIWjMCKpIiQl8s0HW+y5u1c=; b=e3DFfEmfxnMFZ/c2c49UYNtUZoHPYMHSXwXaMoZuMuz/hKHV2VJQd9SVqB2Wc0O7xn KnpY7Ig9g4oNPWIjswgMYvtAl2d8ymhW6DbneIqW+iQxyvCSjQo6R2UL4CYE9ULlPQGy VsJ/+nvzExCuRuLPi9m5ZohAhop9RudFGcHD5Pz4NEyjIpt03NsEkvrB0nx32dHv/rh/ AEyCjlqHM+Flp8O25HSWe0WNmWN6XKwGdoHLHNbuCg667v9nn7eqpBvwN5j8KSaVUn/Y jqQp6VrPIr7DpgLy48LCoJX5bnUtMpl3mOjEMe+3QoyfUdIkqK62u6vN4JSTfS0LzgLd K8GQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=sender:x-gm-message-state:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:x-original-sender :x-original-authentication-results:precedence:mailing-list:list-id :list-post:list-help:list-archive:list-subscribe:list-unsubscribe; bh=/0W6y2ZhiC0GDvE0yXc8IIWjMCKpIiQl8s0HW+y5u1c=; b=r8pVq2mX0+1J727pab830CJJv2LCCVXs3exOXv7cYHWTVgNndNWglz7u4NvpsSFXGq RPN4aw1ltWmDwDXcdE/oHf5EWfNrdE7wPV/g6ZdbEM/ACYeW2p37AyO5PtHOVcs7RK0C is3hhr5wfrxGrdlsryCNGywBMyLVZQ2NLKtbX/gn1ZFTNllhxXmuXsC1r2itsOL16E31 vUTQKsJNZOdgVIKBLJwUKdjw7R1Sh+7W2oLn3btwgFCTKnYyzNjNW/bnOQqmBc4QDbvI GVPk1UPVX03RUc3n/AH3RHJijuX7Uti5YXQH1EPk5cd+l8bnpYfVPaYXIxGPotC+4CaH 0goQ== Sender: swupdate@googlegroups.com X-Gm-Message-State: AOAM530jojbe32kDT5FKWT13v9yrdzJsQquwSGGYOzZYp9Ek7ka/wLZI +WV5dmpDvx2TdQhapgDU3r0= X-Google-Smtp-Source: ABdhPJzYPHONsR84A4IhvracEv4FPw1H3RxaHhe+8RV83xog+eh/b9s3y+6nQH3bwsE/3uKPwSyiKw== X-Received: by 2002:a05:620a:a45:: with SMTP id j5mr9535746qka.392.1637105315103; Tue, 16 Nov 2021 15:28:35 -0800 (PST) X-BeenThere: swupdate@googlegroups.com Received: by 2002:a05:620a:1926:: with SMTP id bj38ls10441634qkb.7.gmail; Tue, 16 Nov 2021 15:28:34 -0800 (PST) X-Received: by 2002:a05:620a:4481:: with SMTP id x1mr9401323qkp.423.1637105314742; Tue, 16 Nov 2021 15:28:34 -0800 (PST) Received: by 2002:a05:620a:15ec:b0:467:8880:b933 with SMTP id af79cd13be357-467df3c090fms85a; Sun, 14 Nov 2021 09:36:00 -0800 (PST) X-Received: by 2002:ac2:5d46:: with SMTP id w6mr27708860lfd.15.1636911359689; Sun, 14 Nov 2021 09:35:59 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1636911359; cv=none; d=google.com; s=arc-20160816; b=qxG9CbAO/tTowRBz4nYSQASuxocyUFQsGLEL5kTa4DJEmvHm8bAo7U5R6PbWqt6RvW MwoLJg+rsckDjI0aM3USNO1MZBuXLSdbY6Z4mDWXIvyrG6iIatX8GNGTOshRQbV/P5M6 xTordjbx98RetNPVaf71zS+wde8Xa8UfzfYhWr4PTX+T6maLZ5VhBcO2A7qctOu4kaet CubflJRTNW8CM40Y6hEkun37MWW0kVP+uxvfs+baynGxIYvpQ6UKv1kBy0kgEYZB4Oc9 QPiDUDBcFT0mnX6QNCGGc5TIfvup2l/8zRGSjdCElMQRwSRk/1GMwWTNonooJD/sEgdZ pG8g== 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=hDRYRXItDcBdo7ipv+VH8f65KkoOkLU+zOpwYg77FLY=; b=OXixqPhsm00zcJM2CydnS3IaQY3TLw10aieVDaGxsNlsWUcdwi8eErZSwUXjxLMx+6 Q2mrnv3Pu14YP+c0dIoIAJyHcV6fGTa6x4xMVJzNlA7gljpv1X0NyRB/TE6Dq9lAHSYQ hYiqC3GVjErj6CUBsKhrjDB0OTM2+LcLsQDFA/6W3FlxJBfJIWWch/BwQ29U2m7/nVqG DW9aWImE5+BM3L5sJFf6uVeLJaPfm/UKlXd77iynGY1y8422qhOlBb26n9MzN1mJ96Ep jg/J1HArCklh2AemCwvJ9a2Q1jRuqzHVMafbBaXdNjc6loAtQ2eGwh7wrkTovpj3k0Co 9Y8A== ARC-Authentication-Results: i=1; gmr-mx.google.com; spf=neutral (google.com: 2001:a60:0:28:0:1:25:1 is neither permitted nor denied by domain of sbabic@denx.de) smtp.mailfrom=sbabic@denx.de Received: from mail-out.m-online.net (mail-out.m-online.net. [2001:a60:0:28:0:1:25:1]) by gmr-mx.google.com with ESMTPS id b29si889726ljf.6.2021.11.14.09.35.59 for (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Sun, 14 Nov 2021 09:35:59 -0800 (PST) Received-SPF: neutral (google.com: 2001:a60:0:28:0:1:25:1 is neither permitted nor denied by domain of sbabic@denx.de) client-ip=2001:a60:0:28:0:1:25:1; Received: from frontend01.mail.m-online.net (unknown [192.168.8.182]) by mail-out.m-online.net (Postfix) with ESMTP id 4Hsfcb1Rhyz1s9RM; Sun, 14 Nov 2021 18:35:59 +0100 (CET) Received: from localhost (dynscan1.mnet-online.de [192.168.6.70]) by mail.m-online.net (Postfix) with ESMTP id 4Hsfcb1KwFz1qqkB; Sun, 14 Nov 2021 18:35:59 +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 tBvod08QEMuv; Sun, 14 Nov 2021 18:35:57 +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; Sun, 14 Nov 2021 18:35:57 +0100 (CET) Received: from localhost (mail.babic.homelinux.org [127.0.0.1]) by babic.homelinux.org (Postfix) with ESMTP id 4D69D4541B5B; Sun, 14 Nov 2021 18:28:44 +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 U8xokYM63sFn; Sun, 14 Nov 2021 18:28:41 +0100 (CET) Received: from paperino.fritz.box (paperino.fritz.box [192.168.178.48]) by babic.homelinux.org (Postfix) with ESMTP id 39D38454292B; Sun, 14 Nov 2021 18:27:47 +0100 (CET) From: Stefano Babic To: swupdate@googlegroups.com Cc: Stefano Babic Subject: [swupdate] [PATCH V2 32/36] doc: add documentation for delta handler Date: Sun, 14 Nov 2021 18:27:29 +0100 Message-Id: <20211114172733.71602-33-sbabic@denx.de> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20211114172733.71602-1-sbabic@denx.de> References: <20211114172733.71602-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: 2001:a60:0:28:0:1:25:1 is neither permitted nor denied by 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-Google-Group-Id: 605343134186 List-Post: , List-Help: , List-Archive: , List-Unsubscribe: , Explain attributes and properties for the delta update handler. Signed-off-by: Stefano Babic --- doc/source/handlers.rst | 80 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) diff --git a/doc/source/handlers.rst b/doc/source/handlers.rst index ed811e3..8d78bbd 100644 --- a/doc/source/handlers.rst +++ b/doc/source/handlers.rst @@ -936,3 +936,83 @@ found on the device. It is a partition handler and it runs before any image is i "18e12df1-d8e1-4283-8727-37727eb4261d"]; } }); + +Delta Update Handler +-------------------- + +The handler processes a ZCHUNK header and finds which chunks should be downloaded +after generating the corresponding header of the running artifact to be updated. +The handler uses just a couple of attributes from the main setup, and gets more information +from the properties. The attributes are then passed to a secondary handler that +will install the artefact after the delta handler has assembled it. +The handler requires ZST because this is the compression format for Zchunk. + +The SWU must just contain the ZCK's header, while the ZCK file is put as it is on the server. +The utilities in Zchunk project are used to build the zck file. + +:: + + zck -u -h sha256 + +This will generates a file .zck. To extract the header, use the `zck_read_header` +utility: + +:: + + HSIZE=`zck_read_header -v .zck | grep "Header size" | cut -d':' -f2` + dd if=.zck of=.header bs=1 count=$((HSIZE)) + +The resulting header file must be packed inside the SWU. + +.. table:: Properties for delta update handler + + +-------------+-------------+----------------------------------------------------+ + | Name | Type | Description | + +=============+=============+====================================================+ + | url | string | This is the URL from where the handler will | + | | | download the missing chunks. | + | | | The server must support byte range header. | + +-------------+-------------+----------------------------------------------------+ + | source | string | name of the device or file to be used for | + | | | the comparison. | + +-------------+-------------+----------------------------------------------------+ + | chain | string | this is the name (type) of the handler | + | | | that is called after reassembling | + | | | the artifact. | + +-------------+-------------+----------------------------------------------------+ + | max-ranges | string | Max number of ranges that a server can | + | | | accept. Default value (150) should be ok | + | | | for most servers. | + +-------------+-------------+----------------------------------------------------+ + | zckloglevel | string | this sets the log level of the zcklib. | + | | | Logs are intercepted by SWupdate and | + | | | appear in SWUpdate's log. | + | | | Value is one of debug,info | + | | | warn,error,none | + +-------------+-------------+----------------------------------------------------+ + | debug-chunks| string | "true", default is not set. | + | | | This activates more verbose debugging | + | | | output and the list of all chunks is | + | | | printed, and it reports if a chunk | + | | | is downloaded or copied from the source. | + +-------------+-------------+----------------------------------------------------+ + + +Example: + +:: + + { + filename = "software.header"; + type = "delta"; + + device = "/dev/mmcblk0p2"; + properties: { + url = "http://examples.com/software.zck"; + chain = "raw"; + source = "/dev/mmcblk0p3"; + zckloglevel = "error"; + /* debug-chunks = "true"; */ + }; + } +