From patchwork Fri Nov 3 12:30:09 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Storm, Christian" X-Patchwork-Id: 833837 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:400c:c0c::238; helo=mail-wr0-x238.google.com; envelope-from=swupdate+bncbdd6bwv65qpbbk6d6hhqkgqetjokzyy@googlegroups.com; receiver=) Authentication-Results: ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=googlegroups.com header.i=@googlegroups.com header.b="rEaDyXJl"; dkim-atps=neutral Received: from mail-wr0-x238.google.com (mail-wr0-x238.google.com [IPv6:2a00:1450:400c:c0c::238]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3yT1Xt4MY3z9sPs for ; Fri, 3 Nov 2017 23:31:42 +1100 (AEDT) Received: by mail-wr0-x238.google.com with SMTP id f27sf1523703wra.9 for ; Fri, 03 Nov 2017 05:31:42 -0700 (PDT) ARC-Seal: i=2; a=rsa-sha256; t=1509712299; cv=pass; d=google.com; s=arc-20160816; b=a1/Kq55ooulxquGEDdMpkGM3YUWoPU882/BCEvTJKz6TBboxocmvpFA1xRqjlkXmBu oUWdXpfuKIcJd7GAdRDI9bN35R5zhuj9qkfFAEaELs9rqjz5+if6eE2pkJf7yxVMNkZi oEAqlxU1WSGkuwt3vvMNKHKKLZxT4mNRkJdkmzF0hU1Xgxcyj0W5XAJRR7aZpB4RsbcV U+A46UwrIFR2q9Bj4hyeFGvF3gd4/hnFcKza84Cp+lDjVEQQFdB0HQ009EaIU7oGOlxz B8xWIxNYMeDG93n+IEnkbbNvcV9hS3tgUTeC+LBUSif4rnhryRU+zqRf7muC7vLb/hO5 mIaw== 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:references:in-reply-to:message-id :date:subject:cc:to:from:arc-authentication-results :arc-message-signature:mime-version:sender:dkim-signature :arc-authentication-results; bh=DxcVwy/BMDmfaDMHiSKt0/kKSNg1LlR6szcwkMKc14o=; b=FOcQRfjE5FJpytzVF3aIHWLYYDrS6Un7CuZhE8eprhswrNG+T+rEslqPE9yhD3BDab YymgwDnrz/U70RPZU47jcmub4E+s49radsRxDsCrzfR3hmteZ3VUlQZTY0QF+plRSo0P vBQa8Umv0UPlZpIgQWZI89RJdAiqwlSAOMGp6oNFRrWMkgy8gEPHOlxeLk/gaxoFBzqd bHsRRvL97SDA36yJWLXZqIe1psZPYtel00cYbtkhLlQxaNxuLxPcMLP1LghorpbIMCdO SKFJHGikDMsbOnyHVNRLRObyiiMb+S3RnprYTzGda4E7mJ92uBuceEdxu8QvXn/E9u7L ZWjA== ARC-Authentication-Results: i=2; gmr-mx.google.com; spf=pass (google.com: domain of christian.storm@siemens.com designates 192.35.17.2 as permitted sender) smtp.mailfrom=christian.storm@siemens.com DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlegroups.com; s=20161025; h=sender:mime-version:from:to:cc:subject:date:message-id:in-reply-to :references:x-original-sender:x-original-authentication-results :precedence:mailing-list:list-id:list-post:list-help:list-archive :list-subscribe:list-unsubscribe; bh=DxcVwy/BMDmfaDMHiSKt0/kKSNg1LlR6szcwkMKc14o=; b=rEaDyXJl6vfuQdPaAe05hPBIiUaweAN3S+aurE+vUQa/leQyu8vqJunJof1lDkMgkK DR22ydkWrdJ6D1p9rJe4fvGHIVa6I8pNUjqt3MB4MEzhuDznP5FYwTap+/42LTER/1m7 SvfcMx7EKwSyDyj+Obj45di9nwlQw4Q7haDkG6Kg+hXIz5rpld71eBwzv7LcfTkqnbqI PObmZwIQbY8ZJeAUnbjLuO7FLDzMqAtk5M1WLdv85zWrxR8P4Pm6dh1ev4Bd+KR3rewf V6tP3f0BAqjTPBj8p64aDNWRSVZ96pnGDHvNqm8YkvOaTKwvgUDFvYBU1+aI/lI+uawd deBQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=sender:x-gm-message-state:mime-version:from:to:cc:subject:date :message-id:in-reply-to:references: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=DxcVwy/BMDmfaDMHiSKt0/kKSNg1LlR6szcwkMKc14o=; b=GNDDaY3Z4kmv+IkI18p8ea2gq1DRw0wRc0FBS8zXhOHnN6SNfytESEYKfie10wxWnd IXcuN4INFM1RTV/mo2Ru7pkziIhnWrOEPJ4stbMf9MifvR283jSN+vQbyOkVDTnJBi6j t0p1KMKAHbmb4I8qpHAKGTksGEAxaOPrxnR2qqmQWnWbguAo20x/k+9Ny3M1ZFqWkWsS y4mRGLy3pAo+8bUFOT1aKxVqLu6KogiG2XsgWfLCf4qTtrTS1+1TrsXviAWLgBNvCGi6 ZGr8hjqRa8XQHLRZ/ImqG/b3Vkbo6efbyHokaBdfRsaUcZtP9+QHgVVAlX/riKyfGwsQ Ag/g== Sender: swupdate@googlegroups.com X-Gm-Message-State: AMCzsaUchSnrdBzFRboeG++jzUJ0kC0B/znXxZaOfVouxPybsdw4z2Ns g4cQiPrxNyBLqkNOgvxWyaE= X-Google-Smtp-Source: ABhQp+SiJEk1QR4IIsoHwUeao2jf25isKH/GT62LOyvgoWq+/MafujJ07eUsp0V+EyY/dRCzy2FV/Q== X-Received: by 10.28.136.149 with SMTP id k143mr70896wmd.3.1509712299722; Fri, 03 Nov 2017 05:31:39 -0700 (PDT) MIME-Version: 1.0 X-BeenThere: swupdate@googlegroups.com Received: by 10.80.244.25 with SMTP id r25ls2872718edm.2.gmail; Fri, 03 Nov 2017 05:31:39 -0700 (PDT) X-Received: by 10.80.206.3 with SMTP id y3mr2134772edi.11.1509712299294; Fri, 03 Nov 2017 05:31:39 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1509712299; cv=none; d=google.com; s=arc-20160816; b=0sCZNmh9N+WyO8DKGERd+FSzmnp+BormwfSQk9XtIBQ3B/5Ti9hEoReWG8shipGR+W EDlZl5NEXKDDRgc1e/whLRy03gXr5jSZanCngerrymYxUS/FOZmnTsXrwA6unVcwfdsT FFR0uEe221Wkzhg/MDI6c7gPb+W+BQZrskBVpMZN37j9nO83EFTHNxNZb0HSqk6cr0/N 7EAe5df8IRMS3Vi6+COea2Ho6vdQpblWKFpKFdy6dzQp2YLvOf+ZAslUio+Pdob7/Xx0 dojR6PZEhcqjR41d6ckeXJ+OQ+Jsm2VpPDTb2xQK+a2PigyFm0j2q01o1PLEBjzO1Zb2 UfJg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=references:in-reply-to:message-id:date:subject:cc:to:from :arc-authentication-results; bh=Ul6+qk5CEmIqBYwT+Ml7q3N9HtaYxi4BNEYPJPveTTE=; b=i/rRgTEaGf7bAqJTEzAiv8ziVFl4OoSMDTs4WN+IdllcsEdOsJdQMwyDY5ZeLt3ZIT /MdzxT6KFaiSBSVAw+pkHqfWmJoYSeWAKAa7diMobH9zHa9qKQ5TFDh8AA00d4Iw5Wg6 isIvfYgnJgc4EdsK0rg60e5Y2lWNfTUwZV4g6aKbUiPwe91TpdKnvzrhNNAb8hjY2eq6 qpvSh0zf4ustSRcC0gVJPKmGV/9T/2A2aNT7HLf5jVnTWKIaA4P5xj05z2gU42SCq+uN Rtscr6qCygFhZcMvJVxEQcLgApIrVmGm/Hvp3z5QOThVfSliqcq2UFyRLeUqzeRR6p8C CkiA== ARC-Authentication-Results: i=1; gmr-mx.google.com; spf=pass (google.com: domain of christian.storm@siemens.com designates 192.35.17.2 as permitted sender) smtp.mailfrom=christian.storm@siemens.com Received: from thoth.sbs.de (thoth.sbs.de. [192.35.17.2]) by gmr-mx.google.com with ESMTPS id i6si510871eda.1.2017.11.03.05.31.39 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 03 Nov 2017 05:31:39 -0700 (PDT) Received-SPF: pass (google.com: domain of christian.storm@siemens.com designates 192.35.17.2 as permitted sender) client-ip=192.35.17.2; Received: from mail2.siemens.de (mail2.siemens.de [139.25.208.11]) by thoth.sbs.de (8.15.2/8.15.2) with ESMTPS id vA3CVctY023726 (version=TLSv1.2 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Fri, 3 Nov 2017 13:31:38 +0100 Received: from MD1KR9XC.ww002.siemens.net ([139.25.69.251]) by mail2.siemens.de (8.15.2/8.15.2) with ESMTP id vA3CVcFu030106; Fri, 3 Nov 2017 13:31:38 +0100 From: Christian Storm To: swupdate@googlegroups.com Cc: Christian Storm Subject: [swupdate] [PATCH 11/11] Lua: document Lua handlers Date: Fri, 3 Nov 2017 13:30:09 +0100 Message-Id: <20171103123009.18705-11-christian.storm@siemens.com> X-Mailer: git-send-email 2.15.0 In-Reply-To: <20171103123009.18705-1-christian.storm@siemens.com> References: <20171103123009.18705-1-christian.storm@siemens.com> X-Original-Sender: christian.storm@siemens.com X-Original-Authentication-Results: gmr-mx.google.com; spf=pass (google.com: domain of christian.storm@siemens.com designates 192.35.17.2 as permitted sender) smtp.mailfrom=christian.storm@siemens.com 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: , Document how to extend SWUpdate with Lua handlers and elaborate on their new features. Signed-off-by: Christian Storm --- doc/source/handlers.rst | 144 +++++++++++++++++++++++++++++++++++++++--- doc/source/sw-description.rst | 2 + 2 files changed, 136 insertions(+), 10 deletions(-) diff --git a/doc/source/handlers.rst b/doc/source/handlers.rst index 51e087f..5536e0f 100644 --- a/doc/source/handlers.rst +++ b/doc/source/handlers.rst @@ -123,16 +123,140 @@ and create the volumes. This can be easy done with a preinstall script. Building with meta-SWUpdate, the original mtd-utils are available and can be called by a Lua script. -Extend SWUpdate with handlers in Lua ------------------------------------- - -In an experimental phase, it is possible to add handlers -that are not linked to SWUpdate but that are loaded by -the Lua interpreter. The handlers must be copied into the -root filesystem and are loaded only at the startup. -These handlers cannot be integrated into the image to be installed. -Even if this can be theoretical possible, arise a lot of -security questions, because it changes SWUpdate's behavior. +Lua Handlers +------------ + +In addition to the handlers written in C, it is possible to extend +SWUpdate with handlers written in Lua that get loaded at SWUpdate +startup. The Lua handler source code file may either be embedded +into the SWUpdate binary via the ``CONFIG_EMBEDDED_LUA_HANDLER`` +config option or has to be installed on the target system in Lua's +search path as ``swupdate_handlers.lua`` so that it can be loaded +by the embedded Lua interpreter at run-time. + +In analogy to C handlers, the prototype for a Lua handler is + +:: + + function lua_handler(image) + ... + end + +where ``image`` is a Lua table (with attributes according to +:ref:`sw-description's attribute reference `) +that describes a single artifact to be processed by the handler. + +Note that dashes in the attributes' names are replaced with +underscores for the Lua domain to make them idiomatic, e.g., +``installed-directly`` becomes ``installed_directly`` in the +Lua domain. + +To register a Lua handler, the ``swupdate`` module provides the +``swupdate.register_handler()`` method that takes the handler's +name, the Lua handler function to be registered under that name, +and, optionally, the types of artifacts for which the handler may +be called. If the latter is not given, the Lua handler is registered +for all types of artifacts. The following call registers the +above function ``lua_handler`` as *my_handler* which may be +called for images: + +:: + + swupdate.register_handler("my_handler", lua_handler, swupdate.HANDLER_MASK.IMAGE_HANDLER) + + +A Lua handler may call C handlers ("chaining") via the +``swupdate.call_handler()`` method. The callable and registered +C handlers are available (as keys) in the table +``swupdate.handler``. The following Lua code is an example of +a simple handler chain-calling the ``rawfile`` C handler: + +:: + + function lua_handler(image) + if not swupdate.handler["rawfile"] then + swupdate.error("rawfile handler not available") + return 1 + end + image.path = "/tmp/destination.path" + local err, msg = swupdate.call_handler("rawfile", image) + if err ~= 0 then + swupdate.error(string.format("Error chaining handlers: %s", msg)) + return 1 + end + return 0 + end + +Note that when chaining handlers and calling a C handler for +a different type of artifact than the Lua handler is registered +for, the ``image`` table's values must satisfy the called +C handler's expectations: Consider the above Lua handler being +registered for "images" (``swupdate.HANDLER_MASK.IMAGE_HANDLER``) +via the ``swupdate.register_handler()`` call shown above. As per the +:ref:`sw-description's attribute reference `, +the "images" artifact type doesn't have the ``path`` attribute +but the "file" artifact type does. So, for calling the ``rawfile`` +handler, ``image.path`` has to be set prior to chain-calling the +``rawfile`` handler, as done in the example above. Usually, however, +no such adaptation is necessary if the Lua handler is registered for +handling the type of artifact that ``image`` represents. + +In addition to calling C handlers, the ``image`` table passed as +parameter to a Lua handler has a ``image:copy2file()`` method that +implements the common use case of writing the input stream's data +to a file, which is passed as this method's argument. On success, +``image:copy2file()`` returns ``0`` or ``-1`` plus an error +message on failure. The following Lua code is an example of +a simple handler calling ``image:copy2file()``: + +:: + + function lua_handler(image) + local err, msg = image:copy2file("/tmp/destination.path") + if err ~= 0 then + swupdate.error(string.format("Error calling copy2file: %s", msg)) + return 1 + end + return 0 + end + +Beyond using ``image:copy2file()`` or chain-calling C handlers, +the ``image`` table passed as parameter to a Lua handler has +a ``image:read()`` method that reads from the input +stream and calls the Lua callback function ```` for +every chunk read, passing this chunk as parameter. On success, +``0`` is returned by ``image:read()``. On error, ``-1`` plus an +error message is returned. The following Lua code is an example +of a simple handler printing the artifact's content: + +:: + + function lua_handler(image) + err, msg = image:read(function(data) print(data) end) + if err ~= 0 then + swupdate.error(string.format("Error reading image: %s", msg)) + return 1 + end + return 0 + end + +Using the ``image:read()`` method, an artifact's contents may be +(post-)processed in and leveraging the power of Lua without relying +on preexisting C handlers for the purpose intended. + + +Just as C handlers, a Lua handler must consume the artifact +described in its ``image`` parameter so that SWUpdate can +continue with the next artifact in the stream after the Lua handler +returns. Chaining handlers, calling ``image:copy2file()``, or using +``image:read()`` satisfies this requirement. + + +Note that although the dynamic nature of Lua handlers would +technically allow to embed them into a to be processed ``.swu`` +image, this is not implemented as it carries some security +implications since the behavior of SWUpdate is changed +dynamically. Remote handlers --------------- diff --git a/doc/source/sw-description.rst b/doc/source/sw-description.rst index d8fd2f7..01b2e3e 100644 --- a/doc/source/sw-description.rst +++ b/doc/source/sw-description.rst @@ -789,6 +789,8 @@ Example: The example sets a version for the installed image. Generally, this is detected at runtime reading from the target. +.. _sw-description-attribute-reference: + Attribute reference -------------------