Received: by 2002:a05:6a10:eb17:0:0:0:0 with SMTP id hx23csp3828820pxb; Tue, 7 Sep 2021 08:26:11 -0700 (PDT) X-Google-Smtp-Source: ABdhPJwqFCOmmOulBohUE9mrt/lK1VnEKbCN5pIWas33TgiudnKJPze9pq6fKi50dt4uCLLy9MZK X-Received: by 2002:a05:6402:1d2d:: with SMTP id dh13mr19395295edb.281.1631028371165; Tue, 07 Sep 2021 08:26:11 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1631028371; cv=none; d=google.com; s=arc-20160816; b=AKcxQgtQtMpEU7znrWldKb2uk5g6NxlaoDpmOMNYcVKbclW6fcVyCLeQZv+5Wrn5EQ E7TfB6FtD9AJcZJ1zlTEC7ZfpXUBMoIegRoHcm6X2GTAzBVpkNc8l0ElKLNKw3l3hGyh wvdRpKsjGpgPytWrohorF2oVwr0PKql7cjd0j+RJlgcBK4Do3QkPsUJvp5389jJvHWGy MmSuYXxx9M9elngZXCKShHktwUla96UxqP82YI0dAXCewkNXkZ0wyB+jIBYX1KmN30mz ZbX/3ObGmyxPXO7erSziivjNsJ+V6vD7eIiDzEL0Vq8Bl6LPhjdBMtlHvY9bvI94zObH jxyw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:mime-version:message-id:date:references :in-reply-to:subject:cc:to:from:dkim-signature:dkim-filter; bh=tceuoqLCbBFi1wF26LSs4mfr8Ji5ZyYIiWgS4g2Nw28=; b=OjjXrTM5vzl/niUnOfYTlJOev/mO5sZfPPU0WPdfeHnoLa2jzbYasTAWtIOyEFCCjQ iZJUW0+oUnaA4PRggYJ6a+RA11dZpNOKvuuDmd38/UCUuizxVZNZXmWMfP/+mJfeil+j xSlb91TK22arNrKQlvnze8w+0aCJGIaZhTVNHLTMDqI6SPs6XGqBDLR9eua3PQdkjdbm 5wM0XiLVsu7wEBt37x9706OTFyR1xu7KLr3HPQtZi7lapYoYr608WojrEyj90sULj4ou BdDST4rLv5xpqxQ1yIOrotc/Hhn8mVPv+WJjA7kJAgyZ47T6uaafr8FhViiKet+8OKHg WLGQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@lwn.net header.s=20201203 header.b="Y3UwR/UC"; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [23.128.96.18]) by mx.google.com with ESMTP id f25si12614021ejh.250.2021.09.07.08.25.47; Tue, 07 Sep 2021 08:26:11 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18; Authentication-Results: mx.google.com; dkim=pass header.i=@lwn.net header.s=20201203 header.b="Y3UwR/UC"; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1345088AbhIGPZE (ORCPT + 99 others); Tue, 7 Sep 2021 11:25:04 -0400 Received: from ms.lwn.net ([45.79.88.28]:47170 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1345168AbhIGPZA (ORCPT ); Tue, 7 Sep 2021 11:25:00 -0400 Received: from localhost (unknown [IPv6:2601:281:8300:104d::5f6]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ms.lwn.net (Postfix) with ESMTPSA id D7D46735; Tue, 7 Sep 2021 15:23:53 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net D7D46735 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1631028234; bh=tceuoqLCbBFi1wF26LSs4mfr8Ji5ZyYIiWgS4g2Nw28=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=Y3UwR/UCsHOVfoocFGfI8/D0TdbxHDngUtgeoq/0/QrYbVbUU2MiSF3TVHCcqk0em eJArinU/agJlFsU8Pi/2WQKW+jIgfTbPSWgqif6Na9MoPDL+mdssmr/RD+OpPORljy BIUb5NyGap0D4LghrmCCuj8UnYsufEWADl4YNCV0XJRrbjff+haY0w94KD/znFD6Ce FonzB9IoSYW6KdprtCm2mW5Pd9UifctoAVsS6q1hPoN869X3fllOfYCufIVEpByn8+ gVE7wdhzIXnoJvnql360vQRZXSTkFq+pjQrNYNbkd39bfrygVXp9igEg3IOR8hdpTf OWQKkkUHvZKpw== From: Jonathan Corbet To: Chen Yu , linux-acpi@vger.kernel.org Cc: linux-kernel@vger.kernel.org, "Rafael J. Wysocki" , Len Brown , Dan Williams , Andy Shevchenko , Aubrey Li , Ashok Raj , Chen Yu , Thomas Gleixner , Ingo Molnar , Borislav Petkov , "H. Peter Anvin" , linux-doc@vger.kernel.org, x86@kernel.org Subject: Re: [PATCH 1/5][RFC] Documentation: Introduce Platform Firmware Runtime Update documentation In-Reply-To: References: Date: Tue, 07 Sep 2021 09:23:53 -0600 Message-ID: <87sfygtnna.fsf@meer.lwn.net> MIME-Version: 1.0 Content-Type: text/plain Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Thanks for adding to the documentation. I have a few nits for you... Chen Yu writes: > Add the Platform Firmware Runtime Update/Telemetry documentation. > > Signed-off-by: Chen Yu > --- > Documentation/x86/pfru.rst | 98 ++++++++++++++++++++++++++++++++++++++ > 1 file changed, 98 insertions(+) > create mode 100644 Documentation/x86/pfru.rst When you add a new RST file, you also need to find a spot for it in index.rst so it becomes part of the docs build. > diff --git a/Documentation/x86/pfru.rst b/Documentation/x86/pfru.rst > new file mode 100644 > index 000000000000..321729f46737 > --- /dev/null > +++ b/Documentation/x86/pfru.rst > @@ -0,0 +1,98 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +======================================================== > +The Linux Platform Firmware Runtime Update and Telemetry > +======================================================== > + > +According to the specification of [1], > +certain computing systems require high Service Level Agreements (SLAs) where > +system reboot fewer firmware updates are required to deploy firmware changes > +to address bug fixes, security updates and to debug and root cause issues. This > +technology is called Intel Seamless Update. The management mode (MM), > +UEFI runtime services and ACPI services handle most of the system runtime > +functions. Changing the MM code execution during runtime is called MM Runtime > +Update. Since the "MM" acronyms might be misunderstood as "Memory Management", > +this driver uses "Platform Firmware Runtime Update"(PFRU) > + > +PFRU provides the following facilities: Performs a runtime firmware driver update > +and activate. Ability to inject firmware code at runtime, for dynamic instrumentation. > +PFRU Telemetry is a service which allows Runtime Update handler to produce telemetry > +data to upper layer OS consumer at runtime. The OS provides interfaces to let the > +users query the telemetry data via read operations. The specification specifies the > +interface and recommended policy to extract the data, the format and use are left to > +individual OEM's and BIOS implementations on what that data represents. Sticking to the 80-column limit is preferable; it keeps the text readable. > +PFRU interfaces > +===================== Underline lengths should match the title text, or Sphinx will get grumpy with you. > +The user space tool manipulates on /dev/pfru/update for code injection and > +driver update. PFRU stands for Platform Firmware Runtime Update, and the /dev/pfru > +directory might be reserved for future usage. > + > + 1. mmap the capsule file > + fd_capsule = open("capsule.cap", O_RDONLY); > + fstat(fd_capsule, &stat); > + addr = mmap(0, stat.st_size, PROT_READ, fd_capsule); These will not render the way you would like; you'll want to use literal blocks for the code samples. > + 2. Get the capability information(version control, etc) from BIOS via > + read() and do sanity check in user space. > + fd_update = open("/dev/pfru/update", O_RDWR); > + read(fd_update, &cap, sizeof(cap)); > + sanity_check(&cap); > + > + 3. Write the capsule file to runtime update communication buffer > + //kernel might return error if capsule file size is longer than > + //communication buffer > + write(fd_update, addr, stat.st_size); > + > + 4. Stage the code injection > + ioctl(fd_update, PFRU_IOC_STATGE); > + > + 5. Activate the code injection > + ioctl(fd_update, PFRU_IOC_ACTIVATE); > + > + 6. Stage and activate the code injection > + ioctl(fd_update, PFRU_IOC_STAGE_ACTIVATE); > + > + PFRU_IOC_STATGE: Stage a capsule image from communication buffer > + and perform authentication. > + PFRU_IOC_ACTIVATE: Activate a previous staged capsule image. > + PFRU_IOC_STAGE_ACTIVATE: Perform both stage and activation actions. > + > +PFRU Telemetry > +============= > + > +The user space tool manipulates on /dev/pfru/telemetry for PFRU telemetry log. > +Sample code: > + > + 1. Open telemetry device > + fd_log = open("/dev/pfru/telemetry", O_RDWR); > + > + 2. Get log level, log type, revision_id via one ioctl invoke > + ioctl(fd_log, PFRU_IOC_GET_LOG_INFO, &info); > + > + 3. Set log level, log type, revision_id > + ioctl(fd_log, PFRU_IOC_SET_LOG_INFO, &info); > + > + 4. ioctl(fd_log, PFRU_IOC_GET_DATA_INFO, &data_info); > + Query the information of PFRU telemetry log buffer. The user is > + responsible for parsing the result per the specification. > + > + 5. Read the telemetry data: > + read(fd_log, buf, data_info.size); > + > +Please refer to tools/testing/selftests/pfru/pfru_test.c for detail. > + > +According to [1], the telemetry > +buffer is a wrap around buffer. If the telemetry buffer gets full, most recent > +log data will overwrite old log data. Besides, it is required in the spec that > +the read of telemetry should support both full data retrieval and delta telemetry > +data retrieval. Since this requirement is more likely a policy we leave this > +implementation in user space. That is to say, it is recommended for the user > +to double-read the telemetry parameters such as chunk1_size, chunk2_size, > +rollover_cnt in data_info structure to make sure that there is no more data appended > +while the user is reading the buffer. Besides, only after the runtime update has > +been run at least once, the telemetry log would have valid data, otherwise errno code > +of EBUSY would be returned. > + > +[1] https://uefi.org/sites/default/files/resources/Intel_MM_OS_Interface_Spec_Rev100.pdf > -- > 2.25.1 Thanks, jon