From nobody Sun Feb 8 01:30:39 2026 Received: from mx0a-001b2d01.pphosted.com (mx0a-001b2d01.pphosted.com [148.163.156.1]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 6F9F133ADA8; Sun, 1 Feb 2026 14:00:12 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=148.163.156.1 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769954414; cv=none; b=M/zCR/DOzHxG+6biHpv+Qnrv06qLZiGG2XZ2liNIE5sAxPLMCW/IwiKaNwHUWATRfg42qCyAh8G9NfXR9DfcUqUjg6LejCLaMeBctkr5UOhFGEw9o+JFuCohrnytiLHN3PtvtGZEusE/Vavq4FOxlh+PZyda0/0NkbFUazfDemY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1769954414; c=relaxed/simple; bh=h2rPnqdUjlC/2anIjbKI07xGV38lcrsncM4x8N/x+4s=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=WPhtjZPA9SrJX6Y9VkYhYQdSJIiVB3L7bbydoltfd9DGpG7UBF1NnIAgzsFtyXp16IMQbhfffiF7nxhm3aalUxuFfLfYS/Gec4PgrRKPE3nFv3u/zd6AS7xJVYkH6QYU3B0Jb0d2Ev3vH4MnKnZgYmuvYsZc/12fLlmPco0O/dw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linux.ibm.com; spf=pass smtp.mailfrom=linux.ibm.com; dkim=pass (2048-bit key) header.d=ibm.com header.i=@ibm.com header.b=ksL6SpQj; arc=none smtp.client-ip=148.163.156.1 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linux.ibm.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=linux.ibm.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=ibm.com header.i=@ibm.com header.b="ksL6SpQj" Received: from pps.filterd (m0353729.ppops.net [127.0.0.1]) by mx0a-001b2d01.pphosted.com (8.18.1.2/8.18.1.2) with ESMTP id 6119uCI6026510; Sun, 1 Feb 2026 13:59:44 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ibm.com; h=cc :content-transfer-encoding:date:from:in-reply-to:message-id :mime-version:references:subject:to; s=pp1; bh=1L34ePcbZI2PV75Rb gNaWlBUXbZOXn27dYGuhzId7PI=; b=ksL6SpQjp2AcDukLkqxA964l75LiGkUbY n6su4lKY/9Ak2huYql1RjvntMrlUY/YE7BQzIyAMfWwKC4U2LWYvo0OhhbYu87e3 9l55Dd4KX8D5UfiMwQtJswN7n/QFlb76CDu2mg4LnxyWOmT3stJCR6W2z5Mb51Mu wpZfo4sN41lQ27Ge1pSLv2krRL/OmjPIJy1WVvcH0RmJQi+LNqlQFuMylBIlJMcF 1MerOMsVgWnSI7ALyq3dJ0lTRQc/GuIn/eVAzFi0uut5UcEwT4dhTGMxllhzlh20 21PcK9nkEfPwwRYj45recTiccDdUDbQ6WnWaMTPKRekEMb97FxEVw== Received: from pps.reinject (localhost [127.0.0.1]) by mx0a-001b2d01.pphosted.com (PPS) with ESMTPS id 4c19dsvjax-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Sun, 01 Feb 2026 13:59:44 +0000 (GMT) Received: from m0353729.ppops.net (m0353729.ppops.net [127.0.0.1]) by pps.reinject (8.18.1.12/8.18.0.8) with ESMTP id 611Dxhvd011390; Sun, 1 Feb 2026 13:59:43 GMT Received: from ppma12.dal12v.mail.ibm.com (dc.9e.1632.ip4.static.sl-reverse.com [50.22.158.220]) by mx0a-001b2d01.pphosted.com (PPS) with ESMTPS id 4c19dsvjav-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Sun, 01 Feb 2026 13:59:43 +0000 (GMT) Received: from pps.filterd (ppma12.dal12v.mail.ibm.com [127.0.0.1]) by ppma12.dal12v.mail.ibm.com (8.18.1.2/8.18.1.2) with ESMTP id 611775Vu029082; Sun, 1 Feb 2026 13:59:42 GMT Received: from smtprelay03.fra02v.mail.ibm.com ([9.218.2.224]) by ppma12.dal12v.mail.ibm.com (PPS) with ESMTPS id 4c1v2s1rcq-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Sun, 01 Feb 2026 13:59:42 +0000 Received: from smtpav05.fra02v.mail.ibm.com (smtpav05.fra02v.mail.ibm.com [10.20.54.104]) by smtprelay03.fra02v.mail.ibm.com (8.14.9/8.14.9/NCO v10.0) with ESMTP id 611DxcZ141877908 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sun, 1 Feb 2026 13:59:38 GMT Received: from smtpav05.fra02v.mail.ibm.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id B0F0320040; Sun, 1 Feb 2026 13:59:38 +0000 (GMT) Received: from smtpav05.fra02v.mail.ibm.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id 24E372004D; Sun, 1 Feb 2026 13:59:35 +0000 (GMT) Received: from li-fc74f8cc-3279-11b2-a85c-ef5828687581.ibm.com.com (unknown [9.39.20.39]) by smtpav05.fra02v.mail.ibm.com (Postfix) with ESMTP; Sun, 1 Feb 2026 13:59:34 +0000 (GMT) From: Srish Srinivasan To: linux-integrity@vger.kernel.org, keyrings@vger.kernel.org, linuxppc-dev@lists.ozlabs.org Cc: maddy@linux.ibm.com, mpe@ellerman.id.au, npiggin@gmail.com, christophe.leroy@csgroup.eu, James.Bottomley@HansenPartnership.com, jarkko@kernel.org, zohar@linux.ibm.com, nayna@linux.ibm.com, rnsastry@linux.ibm.com, linux-kernel@vger.kernel.org, linux-security-module@vger.kernel.org, ssrish@linux.ibm.com Subject: [PATCH v6 1/6] pseries/plpks: fix kernel-doc comment inconsistencies Date: Sun, 1 Feb 2026 19:29:25 +0530 Message-ID: <20260201135930.898721-2-ssrish@linux.ibm.com> X-Mailer: git-send-email 2.52.0 In-Reply-To: <20260201135930.898721-1-ssrish@linux.ibm.com> References: <20260201135930.898721-1-ssrish@linux.ibm.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-TM-AS-GCONF: 00 X-Proofpoint-Spam-Details-Enc: AW1haW4tMjYwMjAxMDEyMCBTYWx0ZWRfX+DzDngfJNrcF E7DMQvCWgBb1wjqCvLX/bYXUNKm41KfNPWWzbv8Ixa8dVl9CLZJn+41A4gM3Do9cRy8x4mzj4Gm vjP0P6jgMxugTBuRTS98bi7ZfKf+2D+Zvu1lK8f+YxNo4pVy+XEIk1xXbAHWn9L2twfapYhRhOc dRdOch1ePBQrXuU8d9PIdZWW7NyBU+65DApE2eoXTlE+numgE1aH37GPDx497FonrZ7pMGf12Wh XkJQkZ4YvcH8yCSdCcgRjb+0HXrnId3UiiD06X2Ci+soFVyZvnvGNdP/4d8LutI7bDD6dHavIcv a+YDtLM4x0hEqQ0W1jQ4Ie99YgGLFgqxviEm/voRJRtAscyHWFZUXNcVGZ1d7fAyzv9EkVLGx8r 8obpVDiQ2s9i5uhFWxBBnPw2hPzS3nWDjZg+kdj/mYoR8DSzRUE7t+mxnrGGotTKC9JREPzPnWd zgY6/ijzoCw3RpJKSmA== X-Proofpoint-GUID: dCFHSulLfy8bkHMubi1HAtJU8iWnQhQQ X-Proofpoint-ORIG-GUID: kgFF0d8KXjCrX_ggS2JfyNgDrrRX_2wL X-Authority-Analysis: v=2.4 cv=LesxKzfi c=1 sm=1 tr=0 ts=697f5c50 cx=c_pps a=bLidbwmWQ0KltjZqbj+ezA==:117 a=bLidbwmWQ0KltjZqbj+ezA==:17 a=HzLeVaNsDn8A:10 a=VkNPw1HP01LnGYTKEx00:22 a=VnNF1IyMAAAA:8 a=_jD9v-G-JNOk7KggL9IA:9 a=tQW_-zY1P7yUjf7c:21 X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.293,Aquarius:18.0.1121,Hydra:6.1.51,FMLib:17.12.100.49 definitions=2026-02-01_05,2026-01-30_04,2025-10-01_01 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 bulkscore=0 impostorscore=0 spamscore=0 lowpriorityscore=0 clxscore=1015 adultscore=0 suspectscore=0 priorityscore=1501 phishscore=0 malwarescore=0 classifier=typeunknown authscore=0 authtc= authcc= route=outbound adjust=0 reason=mlx scancount=1 engine=8.19.0-2601150000 definitions=main-2602010120 Content-Type: text/plain; charset="utf-8" Fix issues with comments for all the applicable functions to be consistent with kernel-doc format. Move them before the function definition as opposed to the function prototype. Signed-off-by: Srish Srinivasan Reviewed-by: Nayna Jain Tested-by: Nayna Jain --- arch/powerpc/include/asm/plpks.h | 77 ------ arch/powerpc/platforms/pseries/plpks.c | 328 ++++++++++++++++++++++++- 2 files changed, 318 insertions(+), 87 deletions(-) diff --git a/arch/powerpc/include/asm/plpks.h b/arch/powerpc/include/asm/pl= pks.h index 7a84069759b0..f303922bf622 100644 --- a/arch/powerpc/include/asm/plpks.h +++ b/arch/powerpc/include/asm/plpks.h @@ -67,122 +67,45 @@ struct plpks_var_name_list { struct plpks_var_name varlist[]; }; =20 -/** - * Updates the authenticated variable. It expects NULL as the component. - */ int plpks_signed_update_var(struct plpks_var *var, u64 flags); =20 -/** - * Writes the specified var and its data to PKS. - * Any caller of PKS driver should present a valid component type for - * their variable. - */ int plpks_write_var(struct plpks_var var); =20 -/** - * Removes the specified var and its data from PKS. - */ int plpks_remove_var(char *component, u8 varos, struct plpks_var_name vname); =20 -/** - * Returns the data for the specified os variable. - * - * Caller must allocate a buffer in var->data with length in var->datalen. - * If no buffer is provided, var->datalen will be populated with the objec= t's - * size. - */ int plpks_read_os_var(struct plpks_var *var); =20 -/** - * Returns the data for the specified firmware variable. - * - * Caller must allocate a buffer in var->data with length in var->datalen. - * If no buffer is provided, var->datalen will be populated with the objec= t's - * size. - */ int plpks_read_fw_var(struct plpks_var *var); =20 -/** - * Returns the data for the specified bootloader variable. - * - * Caller must allocate a buffer in var->data with length in var->datalen. - * If no buffer is provided, var->datalen will be populated with the objec= t's - * size. - */ int plpks_read_bootloader_var(struct plpks_var *var); =20 -/** - * Returns if PKS is available on this LPAR. - */ bool plpks_is_available(void); =20 -/** - * Returns version of the Platform KeyStore. - */ u8 plpks_get_version(void); =20 -/** - * Returns hypervisor storage overhead per object, not including the size = of - * the object or label. Only valid for config version >=3D 2 - */ u16 plpks_get_objoverhead(void); =20 -/** - * Returns maximum password size. Must be >=3D 32 bytes - */ u16 plpks_get_maxpwsize(void); =20 -/** - * Returns maximum object size supported by Platform KeyStore. - */ u16 plpks_get_maxobjectsize(void); =20 -/** - * Returns maximum object label size supported by Platform KeyStore. - */ u16 plpks_get_maxobjectlabelsize(void); =20 -/** - * Returns total size of the configured Platform KeyStore. - */ u32 plpks_get_totalsize(void); =20 -/** - * Returns used space from the total size of the Platform KeyStore. - */ u32 plpks_get_usedspace(void); =20 -/** - * Returns bitmask of policies supported by the hypervisor. - */ u32 plpks_get_supportedpolicies(void); =20 -/** - * Returns maximum byte size of a single object supported by the hyperviso= r. - * Only valid for config version >=3D 3 - */ u32 plpks_get_maxlargeobjectsize(void); =20 -/** - * Returns bitmask of signature algorithms supported for signed updates. - * Only valid for config version >=3D 3 - */ u64 plpks_get_signedupdatealgorithms(void); =20 -/** - * Returns the length of the PLPKS password in bytes. - */ u16 plpks_get_passwordlen(void); =20 -/** - * Called in early init to retrieve and clear the PLPKS password from the = DT. - */ void plpks_early_init_devtree(void); =20 -/** - * Populates the FDT with the PLPKS password to prepare for kexec. - */ int plpks_populate_fdt(void *fdt); #else // CONFIG_PSERIES_PLPKS static inline bool plpks_is_available(void) { return false; } diff --git a/arch/powerpc/platforms/pseries/plpks.c b/arch/powerpc/platform= s/pseries/plpks.c index b1667ed05f98..03722fabf9c3 100644 --- a/arch/powerpc/platforms/pseries/plpks.c +++ b/arch/powerpc/platforms/pseries/plpks.c @@ -312,40 +312,107 @@ static int _plpks_get_config(void) return rc; } =20 +/** + * plpks_get_version() - Get the version of the PLPKS config structure. + * + * Successful execution of the H_PKS_GET_CONFIG HCALL during initialization + * reads the PLPKS config structure version and saves it in a file local s= tatic + * version variable. + * + * Returns: On success the saved PLPKS config structure version is returne= d, 0 + * if not. + */ u8 plpks_get_version(void) { return version; } =20 +/** + * plpks_get_objoverhead() - Get the hypervisor storage overhead per objec= t. + * + * Successful execution of the H_PKS_GET_CONFIG HCALL during initialization + * reads the per object hypervisor storage overhead in bytes into the local + * static objoverhead variable, excluding the size of the object or the la= bel. + * This value can be treated as valid only when the PLPKS config structure + * version >=3D 2. + * + * Returns: If PLPKS config structure version >=3D 2 then the storage over= head is + * returned, 0 otherwise. + */ u16 plpks_get_objoverhead(void) { return objoverhead; } =20 +/** + * plpks_get_maxpwsize() - Get the maximum password size. + * + * Successful execution of the H_PKS_GET_CONFIG HCALL during initialization + * reads the maximum password size and checks if it is 32 bytes at the lea= st + * before storing it in the local static maxpwsize variable. + * + * Returns: On success the maximum password size is returned, 0 if not. + */ u16 plpks_get_maxpwsize(void) { return maxpwsize; } =20 +/** + * plpks_get_maxobjectsize() - Get the maximum object size supported by the + * PLPKS. + * + * Successful execution of the H_PKS_GET_CONFIG HCALL during initialization + * reads the maximum object size into the file local static maxobjsize var= iable. + * + * Returns: On success the maximum object size is returned, 0 if not. + */ u16 plpks_get_maxobjectsize(void) { return maxobjsize; } =20 +/** + * plpks_get_maxobjectlabelsize() - Get the maximum object label size supp= orted + * by the PLPKS. + * + * Successful execution of the H_PKS_GET_CONFIG HCALL during initialization + * reads the maximum object label size into the local static maxobjlabelsi= ze + * variable. + * + * Returns: On success the maximum object label size is returned, 0 if not. + */ u16 plpks_get_maxobjectlabelsize(void) { return maxobjlabelsize; } =20 +/** + * plpks_get_totalsize() - Get the total size of the PLPKS that is configu= red. + * + * Successful execution of the H_PKS_GET_CONFIG HCALL during initialization + * reads the total size of the PLPKS that is configured for the LPAR into = the + * file local static totalsize variable. + * + * Returns: On success the total size of the PLPKS configured is returned,= 0 if + * not. + */ u32 plpks_get_totalsize(void) { return totalsize; } =20 +/** + * plpks_get_usedspace() - Get the used space from the total size of the P= LPKS. + * + * Invoke the H_PKS_GET_CONFIG HCALL to refresh the latest value for the u= sed + * space as this keeps changing with the creation and removal of objects i= n the + * PLPKS. + * + * Returns: On success the used space is returned, 0 if not. + */ u32 plpks_get_usedspace(void) { - // Unlike other config values, usedspace regularly changes as objects - // are updated, so we need to refresh. int rc =3D _plpks_get_config(); if (rc) { pr_err("Couldn't get config, rc: %d\n", rc); @@ -354,26 +421,84 @@ u32 plpks_get_usedspace(void) return usedspace; } =20 +/** + * plpks_get_supportedpolicies() - Get a bitmask of the policies supported= by + * the hypervisor. + * + * Successful execution of the H_PKS_GET_CONFIG HCALL during initialization + * reads a bitmask of the policies supported by the hypervisor into the fi= le + * local static supportedpolicies variable. + * + * Returns: On success the bitmask of the policies supported by the hyperv= isor + * are returned, 0 if not. + */ u32 plpks_get_supportedpolicies(void) { return supportedpolicies; } =20 +/** + * plpks_get_maxlargeobjectsize() - Get the maximum object size supported = for + * PLPKS config structure version >=3D 3 + * + * Successful execution of the H_PKS_GET_CONFIG HCALL during initialization + * reads the maximum object size into the local static maxlargeobjectsize + * variable for PLPKS config structure version >=3D 3. This was introduced + * starting with PLPKS config structure version 3 to allow for objects of + * size >=3D 64K. + * + * Returns: If PLPKS config structure version >=3D 3 then the new maximum = object + * size is returned, 0 if not. + */ u32 plpks_get_maxlargeobjectsize(void) { return maxlargeobjectsize; } =20 +/** + * plpks_get_signedupdatealgorithms() - Get a bitmask of the signature + * algorithms supported for signed updates. + * + * Successful execution of the H_PKS_GET_CONFIG HCALL during initialization + * reads a bitmask of the signature algorithms supported for signed update= s into + * the file local static signedupdatealgorithms variable. This is valid on= ly + * when the PLPKS config structure version >=3D 3. + * + * Returns: On success the bitmask of the signature algorithms supported f= or + * signed updates is returned, 0 if not. + */ u64 plpks_get_signedupdatealgorithms(void) { return signedupdatealgorithms; } =20 +/** + * plpks_get_passwordlen() - Get the length of the PLPKS password in bytes. + * + * The H_PKS_GEN_PASSWORD HCALL makes the hypervisor generate a random pas= sword + * for the specified consumer, apply that password to the PLPKS and return= it to + * the caller. In this process, the password length for the OS consumer is + * stored in the local static ospasswordlength variable. + * + * Returns: On success the password length for the OS consumer in bytes is + * returned, 0 if not. + */ u16 plpks_get_passwordlen(void) { return ospasswordlength; } =20 +/** + * plpks_is_available() - Get the PLPKS availability status for the LPAR. + * + * The availability of PLPKS is inferred based upon the successful executi= on of + * the H_PKS_GET_CONFIG HCALL provided the firmware supports this feature.= The + * H_PKS_GET_CONFIG HCALL reads the configuration and status information r= elated + * to the PLPKS. The configuration structure provides a version number to = inform + * the caller of the supported features. + * + * Returns: true is returned if PLPKS is available, false if not. + */ bool plpks_is_available(void) { int rc; @@ -425,6 +550,35 @@ static int plpks_confirm_object_flushed(struct label *= label, return pseries_status_to_err(rc); } =20 +/** + * plpks_signed_update_var() - Update the specified authenticated variable. + * @var: authenticated variable to be updated + * @flags: signed update request operation flags + * + * The H_PKS_SIGNED_UPDATE HCALL performs a signed update to an object in = the + * PLPKS. The object must have the signed update policy flag set. + * + * Possible reasons for the returned errno values: + * + * -ENXIO if PLPKS is not supported + * -EIO if PLPKS access is blocked due to the LPAR's state + * if PLPKS modification is blocked due to the LPAR's state + * if an error occurred while processing the request + * -EINVAL if invalid authorization parameter + * if invalid object label parameter + * if invalid object label len parameter + * if invalid or unsupported policy declaration + * if invalid signed update flags + * if invalid input data parameter + * if invalid input data len parameter + * if invalid continue token parameter + * -EPERM if access is denied + * -ENOMEM if there is inadequate memory to perform the operation + * -EBUSY if unable to handle the request or long running operation + * initiated, retry later + * + * Returns: On success 0 is returned, a negative errno if not. + */ int plpks_signed_update_var(struct plpks_var *var, u64 flags) { unsigned long retbuf[PLPAR_HCALL9_BUFSIZE] =3D {0}; @@ -481,6 +635,33 @@ int plpks_signed_update_var(struct plpks_var *var, u64= flags) return rc; } =20 +/** + * plpks_write_var() - Write the specified variable and its data to PLPKS. + * @var: variable to be written into the PLPKS + * + * The H_PKS_WRITE_OBJECT HCALL writes an object into the PLPKS. The calle= r must + * provide a valid component type for the variable, and the signed update = policy + * flag must not be set. + * + * Possible reasons for the returned errno values: + * + * -ENXIO if PLPKS is not supported + * -EIO if PLPKS access is blocked due to the LPAR's state + * if PLPKS modification is blocked due to the LPAR's state + * if an error occurred while processing the request + * -EINVAL if invalid authorization parameter + * if invalid object label parameter + * if invalid object label len parameter + * if invalid or unsupported policy declaration + * if invalid input data parameter + * if invalid input data len parameter + * -EPERM if access is denied + * -ENOMEM if unable to store the requested object in the space available + * -EBUSY if unable to handle the request + * -EEXIST if the object label already exists + * + * Returns: On success 0 is returned, a negative errno if not. + */ int plpks_write_var(struct plpks_var var) { unsigned long retbuf[PLPAR_HCALL_BUFSIZE] =3D { 0 }; @@ -520,6 +701,30 @@ int plpks_write_var(struct plpks_var var) return rc; } =20 +/** + * plpks_remove_var() - Remove the specified variable and its data from PL= PKS. + * @component: metadata prefix in the object label metadata structure + * @varos: metadata OS flags in the object label metadata structure + * @vname: object label for the object that needs to be removed + * + * The H_PKS_REMOVE_OBJECT HCALL removes an object from the PLPKS. The rem= oval + * is independent of the policy bits that are set. + * + * Possible reasons for the returned errno values: + * + * -ENXIO if PLPKS is not supported + * -EIO if PLPKS access is blocked due to the LPAR's state + * if PLPKS modification is blocked due to the LPAR's state + * if an error occurred while processing the request + * -EINVAL if invalid authorization parameter + * if invalid object label parameter + * if invalid object label len parameter + * -EPERM if access is denied + * -ENOENT if the requested object was not found + * -EBUSY if unable to handle the request + * + * Returns: On success 0 is returned, a negative errno if not. + */ int plpks_remove_var(char *component, u8 varos, struct plpks_var_name vnam= e) { unsigned long retbuf[PLPAR_HCALL_BUFSIZE] =3D { 0 }; @@ -619,21 +824,119 @@ static int plpks_read_var(u8 consumer, struct plpks_= var *var) return rc; } =20 +/** + * plpks_read_os_var() - Fetch the data for the specified variable that is + * owned by the OS consumer. + * @var: variable to be read from the PLPKS + * + * The consumer or the owner of the object is the os kernel. The + * H_PKS_READ_OBJECT HCALL reads an object from the PLPKS. The caller must + * allocate the buffer var->data and specify the length for this buffer in + * var->datalen. If no buffer is provided, var->datalen will be populated = with + * the requested object's size. + * + * Possible reasons for the returned errno values: + * + * -ENXIO if PLPKS is not supported + * -EIO if PLPKS access is blocked due to the LPAR's state + * if an error occurred while processing the request + * -EINVAL if invalid authorization parameter + * if invalid object label parameter + * if invalid object label len parameter + * if invalid output data parameter + * if invalid output data len parameter + * -EPERM if access is denied + * -ENOENT if the requested object was not found + * -EFBIG if the requested object couldn't be + * stored in the buffer provided + * -EBUSY if unable to handle the request + * + * Returns: On success 0 is returned, a negative errno if not. + */ int plpks_read_os_var(struct plpks_var *var) { return plpks_read_var(PLPKS_OS_OWNER, var); } =20 +/** + * plpks_read_fw_var() - Fetch the data for the specified variable that is + * owned by the firmware consumer. + * @var: variable to be read from the PLPKS + * + * The consumer or the owner of the object is the firmware. The + * H_PKS_READ_OBJECT HCALL reads an object from the PLPKS. The caller must + * allocate the buffer var->data and specify the length for this buffer in + * var->datalen. If no buffer is provided, var->datalen will be populated = with + * the requested object's size. + * + * Possible reasons for the returned errno values: + * + * -ENXIO if PLPKS is not supported + * -EIO if PLPKS access is blocked due to the LPAR's state + * if an error occurred while processing the request + * -EINVAL if invalid authorization parameter + * if invalid object label parameter + * if invalid object label len parameter + * if invalid output data parameter + * if invalid output data len parameter + * -EPERM if access is denied + * -ENOENT if the requested object was not found + * -EFBIG if the requested object couldn't be + * stored in the buffer provided + * -EBUSY if unable to handle the request + * + * Returns: On success 0 is returned, a negative errno if not. + */ int plpks_read_fw_var(struct plpks_var *var) { return plpks_read_var(PLPKS_FW_OWNER, var); } =20 +/** + * plpks_read_bootloader_var() - Fetch the data for the specified variable + * owned by the bootloader consumer. + * @var: variable to be read from the PLPKS + * + * The consumer or the owner of the object is the bootloader. The + * H_PKS_READ_OBJECT HCALL reads an object from the PLPKS. The caller must + * allocate the buffer var->data and specify the length for this buffer in + * var->datalen. If no buffer is provided, var->datalen will be populated = with + * the requested object's size. + * + * Possible reasons for the returned errno values: + * + * -ENXIO if PLPKS is not supported + * -EIO if PLPKS access is blocked due to the LPAR's state + * if an error occurred while processing the request + * -EINVAL if invalid authorization parameter + * if invalid object label parameter + * if invalid object label len parameter + * if invalid output data parameter + * if invalid output data len parameter + * -EPERM if access is denied + * -ENOENT if the requested object was not found + * -EFBIG if the requested object couldn't be + * stored in the buffer provided + * -EBUSY if unable to handle the request + * + * Returns: On success 0 is returned, a negative errno if not. + */ int plpks_read_bootloader_var(struct plpks_var *var) { return plpks_read_var(PLPKS_BOOTLOADER_OWNER, var); } =20 +/** + * plpks_populate_fdt(): Populates the FDT with the PLPKS password to prep= are + * for kexec. + * @fdt: pointer to the device tree blob + * + * Upon confirming the existence of the chosen node, invoke fdt_setprop to + * populate the device tree with the PLPKS password in order to prepare for + * kexec. + * + * Returns: On success 0 is returned, a negative value if not. + */ int plpks_populate_fdt(void *fdt) { int chosen_offset =3D fdt_path_offset(fdt, "/chosen"); @@ -647,14 +950,19 @@ int plpks_populate_fdt(void *fdt) return fdt_setprop(fdt, chosen_offset, "ibm,plpks-pw", ospassword, ospass= wordlength); } =20 -// Once a password is registered with the hypervisor it cannot be cleared = without -// rebooting the LPAR, so to keep using the PLPKS across kexec boots we ne= ed to -// recover the previous password from the FDT. -// -// There are a few challenges here. We don't want the password to be visi= ble to -// users, so we need to clear it from the FDT. This has to be done in ear= ly boot. -// Clearing it from the FDT would make the FDT's checksum invalid, so we h= ave to -// manually cause the checksum to be recalculated. +/** + * plpks_early_init_devtree() - Retrieves and clears the PLPKS password fr= om the + * DT in early init. + * + * Once a password is registered with the hypervisor it cannot be cleared + * without rebooting the LPAR, so to keep using the PLPKS across kexec boo= ts we + * need to recover the previous password from the FDT. + * + * There are a few challenges here. We don't want the password to be visi= ble to + * users, so we need to clear it from the FDT. This has to be done in ear= ly + * boot. Clearing it from the FDT would make the FDT's checksum invalid, s= o we + * have to manually cause the checksum to be recalculated. + */ void __init plpks_early_init_devtree(void) { void *fdt =3D initial_boot_params; --=20 2.47.3