From patchwork Wed Jun 29 18:32:07 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Storm, Christian" X-Patchwork-Id: 1650325 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=ClM/H9r1; dkim-atps=neutral Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=googlegroups.com (client-ip=2a00:1450:4864:20::537; helo=mail-ed1-x537.google.com; envelope-from=swupdate+bncbdd6bwv65qpbbzfu6kkqmgqeq24pfwi@googlegroups.com; receiver=) Received: from mail-ed1-x537.google.com (mail-ed1-x537.google.com [IPv6:2a00:1450:4864:20::537]) (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 bilbo.ozlabs.org (Postfix) with ESMTPS id 4LY95R1CjNz9sGP for ; Thu, 30 Jun 2022 04:31:05 +1000 (AEST) Received: by mail-ed1-x537.google.com with SMTP id h16-20020a05640250d000b00435bab1a7b4sf12561888edb.10 for ; Wed, 29 Jun 2022 11:31:05 -0700 (PDT) ARC-Seal: i=3; a=rsa-sha256; t=1656527461; cv=pass; d=google.com; s=arc-20160816; b=NqoVBfm5vsAz8BYqAQVunKPzUztcrGCK3YAJzzauto2xwCsZidme2j+2n62mJV6om4 jaXDrKW3wy9/4e7RmYYC8IQQG5a36fe2/uaRSSE2D82+MEAJypi7GfHEoYDRGQjWF/Nu OYDaG9H9R7IP5q2sXqj2/ibpfCeq5mcu3+laMPHPHwj2VmVrGCV117pQYz2Zz441Pzj6 sBRTV/p+TZpYSFtmiTFfzQGB886wHGwfU72cLUbQeOsafO0+NmBkIjtjOx7Px65NXlMS ca2oitLwVmDl9NmFGzqhzuc3CVsLnR/J8E2oaY8NaqyGB+RobGTGNe/FWl3JwcPikCp8 oZRg== ARC-Message-Signature: i=3; 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=d1rlEAGeuhI+zHARUOG42uVt6ECr7Z4rs1r+OjEFUq0=; b=dEXzRAa3CGyam3fjGcKr2IsHtOGhJtNBKaNRDw3aCr9yo3bWWhWO5ygc5Yurz/MHpl SHN9p6ienAyShIByJ2TYiraB4BIl9wK3kzTK9IOBYnZHKBHyPKdmI8mDzChGsMaCKKyY WcIYgOE6qE/vv92Jgg/VvO46ICicY+eHkdVgs1P2Vrz0U21e1U+BdUz6T0IeowZvGWeT nikvEjhptxzaxnKaOk5grdyxs63uTGZyPGcSokcoqejJiWI1SWYGsJRkMXUsFbaotxeL 2l9jFkF4OAFi35jWw8X5eWMBW1/V5pwYkHIucpGwlJTokBNCKX6WfSjd7pw4viz3B5iS qmjQ== ARC-Authentication-Results: i=3; gmr-mx.google.com; dkim=pass header.i=@siemens.com header.s=selector2 header.b=SwzHnVBX; arc=pass (i=1); spf=pass (google.com: domain of christian.storm@siemens.com designates 40.107.6.73 as permitted sender) smtp.mailfrom=christian.storm@siemens.com; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=siemens.com 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=d1rlEAGeuhI+zHARUOG42uVt6ECr7Z4rs1r+OjEFUq0=; b=ClM/H9r1aWff19+15Zgke5pn0V1pfS0PPGoUfxdHyfiQP+OJdwzm593w0v1XmAdwlp 49TTsCPG/nHrNW6YuXpJ5ulpcsA7sCYqhw5Rvb+Ky65kBiTP82i45CVY4PPZCaooUJu6 RGhe6mlbNaEL6INP5IudaVopfATcC+eomHD56CIiVp3GsFh+g/deTt5omRgfP6luEBO7 +1dI5A3QDXKYdxm2tvHMnWmwWv/+/eD5zFGX4Y2VKT28EplOpbXVOShYhxHXO598U2OV LAuHNZ5pOhMnt4VyoRbZCgDtKXmgt++fb2K+zYqUq568LjFV+vXyO+89KwiSwbMCwR5H 0xrw== 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 :x-spam-checked-in-group:list-post:list-help:list-archive :list-subscribe:list-unsubscribe; bh=d1rlEAGeuhI+zHARUOG42uVt6ECr7Z4rs1r+OjEFUq0=; b=L2pAj7qY/UfdWKv3QmfwH14FrDmZ86zh0Pi+9UTH+eJ5qJveGFAIW81mVCmYxfMeUK 7eUIDPI0Ev/WO9qIySgu01YbQEWMX1apl4fupNfMW798SPUM+4yXHpwWYK46IpEwPCPj xS84yso2iODM0S9c1UO0BVmZ04cRliZI0OhKopl1eJS25PBWl/0khBr0r11aWawjjXVw axTYOjtG1r64EUC3xyulpVMLs+uJV7i850YnBUOkCpmX8grtGB5ghkS+CMtMPlLv4cZN cJb+lIKi6LYs7tItN7soTrHWkJvvi9v25W0ZAOkFzeydX13wbRRO44eQ1SHtwexLJ7f6 cprA== Sender: swupdate@googlegroups.com X-Gm-Message-State: AJIora8TrLarNUXfc2Aky3aHe0ETu7K8yYfGE1JGlXhehbNZ3Cf8WULr ZnQxy3chHxZ1/bL0795t8mA= X-Google-Smtp-Source: AGRyM1uP6Duu/oaJ7IJ6VrHdPWGg39BWH2aTgx9uAR1fIyE0jDxMfsHFeOLR//stOQ4/oHpjx+O2Pg== X-Received: by 2002:a17:907:c1d:b0:726:3239:fe83 with SMTP id ga29-20020a1709070c1d00b007263239fe83mr4727658ejc.51.1656527461261; Wed, 29 Jun 2022 11:31:01 -0700 (PDT) X-BeenThere: swupdate@googlegroups.com Received: by 2002:a17:907:1c8e:b0:726:d066:4632 with SMTP id nb14-20020a1709071c8e00b00726d0664632ls246650ejc.3.gmail; Wed, 29 Jun 2022 11:31:00 -0700 (PDT) X-Received: by 2002:a17:907:d05:b0:6f4:3729:8e36 with SMTP id gn5-20020a1709070d0500b006f437298e36mr4691194ejc.475.1656527460107; Wed, 29 Jun 2022 11:31:00 -0700 (PDT) ARC-Seal: i=2; a=rsa-sha256; t=1656527460; cv=pass; d=google.com; s=arc-20160816; b=uP4qmsqVbcIhH3nKMNufXvL5c5n3oSYu4yKpklIvb/puDonxwNks7r63EKaK5FQOIB Y6YGoAl5VoFB/+ROkhposNUeElew591EysOPfDjlbLJMBWp8bqdS6xQKknRTAHW6TnWS Ej2DNjkZ5eDQW0XfQqiz9/UTXcex9jQ7AB4f0mogn8CXg+n3UJSjZEaAGHc85aVKbdde VbOg+krTk1urBGYI2/92bUpEpJ5fTDPdPZ7z9Cry60Ee0+dEPMg1LBv5svPVJN4O5Ugr FP/oPvt59vCrdUmRzyEjv02CyIpIPrQBLBKUcCqepXGGEi2szMn/EYFy+lZ+7LLgTRxp EsYQ== ARC-Message-Signature: i=2; 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:dkim-signature; bh=S5qB9wruDaEQpLApcw2QO7GageEVQZO+EPSJH8gnFMU=; b=v8MzrbGNxTaZU26Rlj1MQFk/Az1DfdZx1tUw5M6SSX73rRzTs+joeBCSRc3bF+IZn7 Amxkyk23YJvRqINF9RYuv9ICzJdjAhUD538qYEZZlRpEmMD2DvQpi9Q/GPoKM7aFuNMs 718WQODxcFiki5fft0jmEIGJoq/B2nzTDSkN3SyWIyMDICoyYEV0kA4qYIT900NSwHd6 dH2+iYna2vjJ99aB1hPH0JdbkKf5ZnG6Luns5uyhv1E4HQI0b6dyh4bLanULB+gDY1rm cvvBUHZ37lHRyHY8Okc3UcA4Ts9a2abThWQAFJfJ54Lh3/wuRJtLXlpTkm59Mob7yd/L INzg== ARC-Authentication-Results: i=2; gmr-mx.google.com; dkim=pass header.i=@siemens.com header.s=selector2 header.b=SwzHnVBX; arc=pass (i=1); spf=pass (google.com: domain of christian.storm@siemens.com designates 40.107.6.73 as permitted sender) smtp.mailfrom=christian.storm@siemens.com; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=siemens.com Received: from EUR04-DB3-obe.outbound.protection.outlook.com (mail-eopbgr60073.outbound.protection.outlook.com. [40.107.6.73]) by gmr-mx.google.com with ESMTPS id a22-20020a170906245600b0072695cb14f9si418258ejb.0.2022.06.29.11.31.00 for (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Wed, 29 Jun 2022 11:31:00 -0700 (PDT) Received-SPF: pass (google.com: domain of christian.storm@siemens.com designates 40.107.6.73 as permitted sender) client-ip=40.107.6.73; ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=Fe6tVU5Hgxsx3reKUlt2msShJfY222cExG9WQKXrYPN7b3utRV/Qn3Hcutxv+SN2GlJ3Puow5VcsZf3cEI/cYFGAuDR0E9gbi+iZM3uRRkl5NfHQgBX36G3Te273rT7wz2AWhX2gReSWDhwyHHR1rzyDS7FYrWEuwFMPY0jbee7z1hEZvN7yjnEpW6ue+IBr5LeErqx7+etCswvmXlKycrwWPaFRGmiGa4kaIoDaZ52I2OUmwx+nsHJjPqqfF0kRbetLWaglfezpPDMWFmZGY55YxrcvD2E8hKGtMZaYcVhHULwnGnqFaBPwfU5u1lx1AH88mnOlslAPx0JAwAhM7g== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=S5qB9wruDaEQpLApcw2QO7GageEVQZO+EPSJH8gnFMU=; b=gUXACgIDTKBBqapYyx4HMG4M+xw0F/SawWE6UNc1boU7E1StuQbUZaVW3M3iMSvqQXnaKEivU6fi0GwNHqDi1PEySHFFrmSLhiIukb79Mt26HLGCuqe0x33yWUzNRw1Sz2COxU25Y0XEmYfyAwH+tne2BHBdJx+TAVJRpWz0RjCD3F7ktGYtiGkb+th4dZXio5r6FswqtCNiC+eEeh4ApvWE0Rvfw8BM2GWRe8hzeGL02uWZQlfK2X6nb4ocueQxepkYtQ5ZMUyBlsfrTP/DGQAjrTEIBt8tlOMnvnsLiwK6xAZzMUAK3XV+UxDvgFO9CCL+imfusdTZtNS/rFs6QA== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=temperror (sender ip is 194.138.21.70) smtp.rcpttodomain=googlegroups.com smtp.mailfrom=siemens.com; dmarc=temperror action=none header.from=siemens.com; dkim=none (message not signed); arc=none Received: from OS6P279CA0045.NORP279.PROD.OUTLOOK.COM (2603:10a6:e10:32::18) by DB8PR10MB3161.EURPRD10.PROD.OUTLOOK.COM (2603:10a6:10:117::23) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5373.17; Wed, 29 Jun 2022 18:30:58 +0000 Received: from HE1EUR01FT013.eop-EUR01.prod.protection.outlook.com (2603:10a6:e10:32:cafe::7d) by OS6P279CA0045.outlook.office365.com (2603:10a6:e10:32::18) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5395.14 via Frontend Transport; Wed, 29 Jun 2022 18:30:58 +0000 X-MS-Exchange-Authentication-Results: spf=temperror (sender IP is 194.138.21.70) smtp.mailfrom=siemens.com; dkim=none (message not signed) header.d=none;dmarc=temperror action=none header.from=siemens.com; Received-SPF: TempError (protection.outlook.com: error in processing during lookup of siemens.com: DNS Timeout) Received: from hybrid.siemens.com (194.138.21.70) by HE1EUR01FT013.mail.protection.outlook.com (10.152.0.160) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5373.15 via Frontend Transport; Wed, 29 Jun 2022 18:30:58 +0000 Received: from DEMCHDC8A0A.ad011.siemens.net (139.25.226.106) by DEMCHDC9SJA.ad011.siemens.net (194.138.21.70) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.1.2507.9; Wed, 29 Jun 2022 20:30:57 +0200 Received: from cosmos.fritz.box.net (139.22.41.144) by DEMCHDC8A0A.ad011.siemens.net (139.25.226.106) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.1.2507.9; Wed, 29 Jun 2022 20:30:57 +0200 From: Christian Storm To: CC: Christian Storm Subject: [swupdate] [PATCH v2] handlers: Lua Handler interface specification Date: Wed, 29 Jun 2022 20:32:07 +0200 Message-ID: <20220629183207.94758-1-christian.storm@siemens.com> X-Mailer: git-send-email 2.37.0 In-Reply-To: <20220622150237.389634-1-christian.storm@siemens.com> References: <20220622150237.389634-1-christian.storm@siemens.com> MIME-Version: 1.0 X-Originating-IP: [139.22.41.144] X-ClientProxiedBy: DEMCHDC8A0A.ad011.siemens.net (139.25.226.106) To DEMCHDC8A0A.ad011.siemens.net (139.25.226.106) X-EOPAttributedMessage: 0 X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: a321be1b-86da-4b55-f6c3-08da59fd82f3 X-MS-TrafficTypeDiagnostic: DB8PR10MB3161:EE_ X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: /hqQf5TvyDTVDuWbqtJCTccqJAFs9DmFbE/oRSlXxgWcC8ko6gYg0VXuORuTxaa1b4VZ5NBHuCcIux2NuaOjaRjrVfMKQEkLadPc60KTJntY9RLfWj/Loeq12pT1B/R0rUT6XgD5cnwvObmEF05EmvfmUTujbcodHLN/ENh0bdFsInJyIR7oA/gwIQp6RwDgIETG1eukP+JpdCkgelViXsFURZGSdlJA/JkqB4xqqoVOs4iExaXgHLOC+2NN4Cu8po8YcOYxh3xvgYODgjF9GXlUhVqvaXoBRiEmx4crik/Y54XaeXk7oHdP2NP/kdEo4UXwrsRK+XiyvVgDp2czxPJbtobGjw0sdue1ggylg3gNEoSV/Mxp0FaW9NZgMTdjgTeAzOGozOrm+1P8BryWSqF0XDJS1gN/tPFgd6p1QgTcoUJu2CVqsi/tE0LAReq+DJhCyfBH443iFCX8iM8thEvk/rpcFw/EnzI1XPtDS69Vd+Voy8LVlFBVggEAPQaNhxo4ENXYmTf5Uzc9Nue8zCBCT6vz7F2onKABNwWgV43pVR5jVPf/Q3l1cAorJw4+KDfFvHriLiWJrtn7A2a4CQdQ/sTz8wcAqMli6mNbLAHHnQFE8YCTwXr33VeTjk1gfac1Ml37MiJACKVxAX/qkP+SsyKDfzsY2RV/3Wzbdh4nFOOdue1JiyvA3EfpY2enMWt3M0Kkuhu8PRC17XdFIr/edU2fvhl+lgekuVsIT1mffxthpQvwtFHSfZPu4XtaQcPRsJXV5W9mmMtftrPefd/NjH83GefqCaub/JpySKkObWjcZUvZcpBKdWeDcii9 X-Forefront-Antispam-Report: CIP:194.138.21.70;CTRY:DE;LANG:en;SCL:1;SRV:;IPV:NLI;SFV:NSPM;H:hybrid.siemens.com;PTR:hybrid.siemens.com;CAT:NONE;SFS:(13230016)(4636009)(136003)(396003)(39860400002)(376002)(346002)(40470700004)(46966006)(36840700001)(36860700001)(41300700001)(44832011)(4326008)(6666004)(47076005)(36756003)(2906002)(7636003)(8936002)(6916009)(8676002)(40480700001)(82310400005)(5660300002)(316002)(70206006)(40460700003)(30864003)(70586007)(956004)(86362001)(63370400001)(107886003)(478600001)(336012)(16526019)(2616005)(186003)(26005)(1076003)(7596003)(63350400001)(356005)(82740400003)(82960400001)(83380400001);DIR:OUT;SFP:1101; X-OriginatorOrg: siemens.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 29 Jun 2022 18:30:58.4189 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: a321be1b-86da-4b55-f6c3-08da59fd82f3 X-MS-Exchange-CrossTenant-Id: 38ae3bcd-9579-4fd4-adda-b42e1495d55a X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=38ae3bcd-9579-4fd4-adda-b42e1495d55a;Ip=[194.138.21.70];Helo=[hybrid.siemens.com] X-MS-Exchange-CrossTenant-AuthSource: HE1EUR01FT013.eop-EUR01.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: DB8PR10MB3161 X-Original-Sender: christian.storm@siemens.com X-Original-Authentication-Results: gmr-mx.google.com; dkim=pass header.i=@siemens.com header.s=selector2 header.b=SwzHnVBX; arc=pass (i=1); spf=pass (google.com: domain of christian.storm@siemens.com designates 40.107.6.73 as permitted sender) smtp.mailfrom=christian.storm@siemens.com; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=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: , Add the `swupdate` Lua module interface specification provided by SWUpdate's core to Lua Handlers. It serves as reference, for mocking purposes, and type checking thanks to the EmmyLua-inspired annotations. Signed-off-by: Christian Storm --- Full rewrite. doc/source/handlers.rst | 31 +++- handlers/swupdate.lua | 315 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 345 insertions(+), 1 deletion(-) create mode 100644 handlers/swupdate.lua diff --git a/doc/source/handlers.rst b/doc/source/handlers.rst index 45955e0..67fb2c7 100644 --- a/doc/source/handlers.rst +++ b/doc/source/handlers.rst @@ -298,13 +298,18 @@ In analogy to C handlers, the prototype for a Lua handler is :: + --- Lua Handler. + -- + --- @param image img_type Lua equivalent of `struct img_type` + --- @return number # 0 on success, 1 on error 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. +that describes a single artifact to be processed by the handler +(also see the Lua Handler Interface Specification in ``handlers/swupdate.lua``). Note that dashes in the attributes' names are replaced with underscores for the Lua domain to make them idiomatic, e.g., @@ -315,6 +320,11 @@ For a script handler written in Lua, the prototype is :: + --- Lua Handler. + -- + --- @param image img_type Lua equivalent of `struct img_type` + --- @param scriptfn string Type, one of `preinst` or `postinst` + --- @return number # 0 on success, 1 on error function lua_handler(image, scriptfn) ... end @@ -343,6 +353,10 @@ a simple handler chain-calling the ``rawfile`` C handler: :: + --- Lua Handler. + -- + --- @param image img_type Lua equivalent of `struct img_type` + --- @return number # 0 on success, 1 on error function lua_handler(image) if not swupdate.handler["rawfile"] then swupdate.error("rawfile handler not available") @@ -381,6 +395,10 @@ a simple handler calling ``image:copy2file()``: :: + --- Lua Handler. + -- + --- @param image img_type Lua equivalent of `struct img_type` + --- @return number # 0 on success, 1 on error function lua_handler(image) local err, msg = image:copy2file("/tmp/destination.path") if err ~= 0 then @@ -401,6 +419,10 @@ of a simple handler printing the artifact's content: :: + --- Lua Handler. + -- + --- @param image img_type Lua equivalent of `struct img_type` + --- @return number # 0 on success, 1 on error function lua_handler(image) err, msg = image:read(function(data) print(data) end) if err ~= 0 then @@ -422,6 +444,13 @@ returns. Chaining handlers, calling ``image:copy2file()``, or using ``image:read()`` satisfies this requirement. +The ``swupdate`` Lua module interface specification that details what +functionality is made available to Lua handlers by SWUpdate's +``corelib/lua_interface.c`` is found in ``handlers/swupdate.lua``. +It serves as reference, for mocking purposes, and type checking thanks +to the EmmyLua-inspired annotations. + + Note that although the dynamic nature of Lua handlers would technically allow one to embed them into a to be processed ``.swu`` image, this is not implemented as it carries some security diff --git a/handlers/swupdate.lua b/handlers/swupdate.lua new file mode 100644 index 0000000..b5ae92b --- /dev/null +++ b/handlers/swupdate.lua @@ -0,0 +1,315 @@ +--[[ + + SWUpdate Lua Handler Interface. + + Interface specification for the Lua module + provided by SWUpdate to Lua Handlers. + See: corelib/lua_interface.c + + Copyright (C) 2022, Siemens AG + Author: Christian Storm + + SPDX-License-Identifier: GPL-2.0-or-later + +--]] + +---@diagnostic disable: unused-local +-- luacheck: no unused args + + +--- SWUpdate Lua Handler Module. +--- @class swupdate +local swupdate = {} + + +--- @class swupdate.RECOVERY_STATUS +--- Lua equivalent of `RECOVERY_STATUS` as in `include/swupdate_status.h`. +--- @type table +swupdate.RECOVERY_STATUS = { + IDLE = 0, + START = 1, + RUN = 2, + SUCCESS = 3, + FAILURE = 4, + DOWNLOAD = 5, + DONE = 6, + SUBPROCESS = 7, + PROGRESS = 8 +} + +--- Lua equivalent of `ERROR(format, ...)`. +--- @param format string Format string +--- @param ... any Varargs as referenced in format string +swupdate.error = function(format, ...) end + +--- Lua equivalent of `TRACE(format, ...)`. +--- @param format string Format string +--- @param ... any Varargs as referenced in format string +swupdate.trace = function(format, ...) end + +--- Lua equivalent of `INFO(format, ...)`. +--- @param format string Format string +--- @param ... any Varargs as referenced in format string +swupdate.info = function(format, ...) end + +--- Lua equivalent of `WARN(format, ...)`. +--- @param format string Format string +--- @param ... any Varargs as referenced in format string +swupdate.warn = function(format, ...) end + +--- Lua equivalent of `DEBUG(format, ...)`. +--- @param format string Format string +--- @param ... any Varargs as referenced in format string +swupdate.debug = function(format, ...) end + +--- Lua equivalent of `notify(PROGRESS, ..., msg)`. +--- @param msg string Message to send to progress interface +swupdate.progress = function(msg) end + +--- Lua equivalent of `notify(status, error, INFOLEVEL, msg)`. +--- @param status number Current status, one of `swupdate.RECOVERY_STATUS`'s values +--- @param error number Error code +--- @param msg string Message +swupdate.notify = function(status, error, msg) end + + +--- Update progress. +-- +--- @param percent number Progress percent to set +swupdate.progress_update = function(percent) end + + +--- Mount a filesystem to a temporary mountpoint. +-- +--- @param device string Device to mount +--- @param filesystem string Device's filesystem +--- @return string # Mountpoint for use with `swupdate.umount(target)` +swupdate.mount = function(device, filesystem) end + +--- Unmount a mountpoint. +-- +--- @param target string Mountpoint to unmount +--- @return boolean # true if successful, nil on error +swupdate.umount = function(target) end + + +--- @class swupdate.ROOT_DEVICE +--- Lua equivalent of `root_dev_type` as in `include/lua_util.h`. +--- @type table +swupdate.ROOT_DEVICE = { + PATH = 0, + UUID = 1, + PARTUUID = 2, + PARTLABEL = 3 +} + + +--- Current root device information. +--- @class rootdev +--- @field type number Root device type, one of `swupdate.ROOT_DEVICE`'s values +--- @field value string Root device path +--- @field path string Full root device path, if identified, else nil + +--- Get current root device. +-- +--- @return rootdev # Table containing type, and (full) path to root device +swupdate.getroot = function() end + + +--- Get SWUpdate's TMPDIRSCRIPT directory. +-- +--- @return string # TMPDIRSCRIPT directory +swupdate.tmpdirscripts = function() end + +--- Get SWUpdate's TMPDIR directory. +-- +--- @return string # TMPDIR directory +swupdate.tmpdir = function() end + + +--- SWUpdate version information. +--- @class swupdate_version +--- @field [1] number SWUpdate's version +--- @field [2] number SWUpdate's patch level +--- @field version number SWUpdate's version +--- @field patchlevel number SWUpdate's patch level + +--- Get SWUpdate version. +-- +--- @return swupdate_version # Table with 'version' and 'patchlevel' fields +swupdate.getversion = function() end + + +--- Get software Selection and Mode. +-- +--- @return string # Selection +--- @return string # Mode +swupdate.get_selection = function() end + + +--- Set Bootloader environment key=value. +-- +--- @param key string Bootloader environment key to set +--- @param value string Value to set `key` to in bootloader environment +swupdate.set_bootenv = function(key, value) end + +--- Get Bootloader environment key's value. +-- +--- @param key string Bootloader environment's key to get value from +--- @return string # Bootloader environment key's value, empty if key absent +swupdate.get_bootenv = function(key) end + + +--- @class swupdate.HANDLER_MASK +--- Lua equivalent of `HANDLER_MASK` as in `include/handler.h`. +--- @type table +swupdate.HANDLER_MASK = { + IMAGE_HANDLER = 1, + FILE_HANDLER = 2, + SCRIPT_HANDLER = 4, + BOOTLOADER_HANDLER = 8, + PARTITION_HANDLER = 16, + NO_DATA_HANDLER = 32, + ANY_HANDLER = 1 + 2 + 4 + 8 + 16 + 32 +} + +--- Register a Lua function as Handler implementation. +-- +-- The signature of the function to be registered as Handler implementation is: +-- +-- --- @param image img_type Lua equivalent of `struct img_type` +-- --- @param fn? string `preinst` or `postinst` for `SCRIPT_HANDLER`s, else nil +-- --- @return number # 0 on success, 1 on error +-- function lua_handler(image, fn) +-- ... +-- end +-- +--- @param name string Registered Handler's name +--- @param funcptr function Function to register as Handler implementation +--- @param mask number Type(s) for which to register the Handler, one or more ORed values of `swupdate.HANDLER_MASK` +swupdate.register_handler = function(name, funcptr, mask) end + + +--- Lua equivalent of `struct img_type {...}` as in `include/swupdate.h` plus `read()` and `copy2file()` functions. +--- @class img_type +--- @field name string `sw-component` name to check with `sw-versions` +--- @field version string `sw-component` version to check with `sw-versions` +--- @field filename string File name in CPIO archive +--- @field volume string If handler is "ubivol", the UBI volume name +--- @field type string The Handler name +--- @field device string Device node to operate on for mounting, flashing, ... +--- @field path string For FILE_HANDLERs: the relative destination path +--- @field mtdname string MTD device where image must be installed +--- @field data string Handler-specific arbitrary data +--- @field filesystem string For FILE_HANDLERs: the filesystem to mount +--- @field ivt string IVT of an encrypted artifact +--- @field installed_directly boolean Whether to stream image to `device` w/o temporary copy +--- @field install_if_different boolean Whether to compare `name` and `version` accordingly +--- @field install_if_higher boolean Whether to compare `name` and `version` accordingly +--- @field encrypted boolean Whether the artifact is encrypted +--- @field partition boolean Whether the artifact is a partitioner +--- @field script boolean Whether the artifact is a script +--- @field preserve_attributes boolean Whether to preserve attributes in archives +--- @field offset number Offset to seek to in artifact +--- @field size number Artifact size +--- @field checksum number Computed checksum +--- @field skip number `skip_t` enum number as in `include/swupdate.h` +--- @field compressed string `zlib` or `zstd` (boolean value is deprecated) +--- @field properties table Properties Table equivalent as specified in `sw-description` +--- @field sha256 string sha256 hash of the image, file, or script +local img_type = { + --- Store the current image artifact to disk. + -- + --- @param self img_type This `img_type` instance + --- @param path string Path to store the current image artifact to + --- @return number # 0 on success, -1 on error + --- @return string | nil # nil on success, error message on failure + ['copy2file'] = function(self, path) end, + + --- Process the current image artifact in Lua. + -- + -- The `callback = function(chunk) ... end` is repeatedly called with + -- chunked artifact data of type `string` in its `chunk` parameter as + -- long as there is data available. + -- The callback function must completely consume the artifact data so + -- that SWUpdate can continue with the stream's next artifact after + -- the Lua Handler returns. + -- + --- @param self img_type This `img_type` instance + --- @param callback function Callback `function(chunk) ... end` that is fed the current image artifact in chunks. + --- @return number # 0 on success, -1 on error + --- @return string | nil # nil on success, error message on failure + ['read'] = function(self, callback) end, +} + + +--- @class swupdate.handler +--- Chain-callable SWUpdate Handlers (Non-exhaustive). +-- +-- Note: This list of built-in Handlers is non-exhaustive and +-- purely illustrative. At run-time, SWUpdate populates this +-- Table with the actually available Handlers according to its +-- compile-time configuration and Lua Handlers loaded. +-- +--- @type table +swupdate.handler = { + --- Archive Handler (See: `handlers/archive_handler.c`). + ["archive"] = 1, + --- `tar` Archive Handler (See: `handlers/archive_handler.c`). + ["tar"] = 1, + --- Bootloader Handler (See: `handlers/boot_handler.c`). + ["bootloader"] = 1, + --- "dummy" Handler (See: `handlers/dummy_handler.c`). + ["dummy"] = 1, + --- Delta Handler (See: `handlers/delta_handler.c`). + ["delta"] = 1, + --- Disk Format Handler (See: `handlers/diskformat_handler.c`). + ["diskformat"] = 1, + --- Disk Partition Handler (See: `handlers/diskpart_handler.c`). + ["diskpart"] = 1, + --- Toggle Boot Flag Handler (See: `handlers/diskpart_handler.c`). + ["toggleboot"] = 1, + --- Flash Hamming1 Handler (See: `handlers/flash_hamming1_handler.c`). + ["flash-hamming1"] = 1, + --- Flash Handler (See: `handlers/flash_handler.c`). + ["flash"] = 1, + --- Raw Image Handler (See: `handlers/raw_handler.c`). + ["raw"] = 1, + --- Raw File Handler (See: `handlers/raw_handler.c`). + ["rawfile"] = 1, + --- Raw Copy Handler (See: `handlers/raw_handler.c`). + ["rawcopy"] = 1, + --- rdiff Image Handler (See: `handlers/rdiff_handler.c`). + ["rdiff_image"] = 1, + --- rdiff File Handler (See: `handlers/rdiff_handler.c`). + ["rdiff_file"] = 1, + --- Readback Handler (See: `handlers/readback_handler.c`). + ["readback"] = 1, + --- Remote Handler (See: `handlers/remote_handler.c`). + ["remote"] = 1, + --- SSBL Handler (See: `handlers/ssbl_handler.c`). + ["ssblswitch"] = 1, + --- SWU Forward Handler (See: `handlers/swuforward_handler.c`). + ["swuforward"] = 1, + --- UBI Volume Handler (See: `handlers/ubivol_handler.c`). + ["ubivol"] = 1, + --- UBI Partition Handler (See: `handlers/ubivol_handler.c`). + ["ubipartition"] = 1, + --- UBI Swap Handler (See: `handlers/ubivol_handler.c`). + ["ubiswap"] = 1, + --- ucfw Handler (See: `handlers/ucfw_handler.c`). + ["ucfw"] = 1, + --- Unique UUID Handler (See: `handlers/uniqueuuid_handler.c`). + ["uniqueuuid"] = 1, +} + +--- Chain-call another Handler. +-- +--- @param handler string Chain-called Handler's name +--- @param image img_type Lua equivalent of `struct img_type` as in `include/swupdate.h` +--- @return number # 0 on success, 1 on failure +--- @return string | nil # nil on success, error message on failure +swupdate.call_handler = function(handler, image) end + + +return swupdate