From patchwork Wed Nov 16 17:03:39 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Winkler, Tomas" X-Patchwork-Id: 9432091 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id EBA4B60755 for ; Wed, 16 Nov 2016 16:07:32 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id D9D4728FB0 for ; Wed, 16 Nov 2016 16:07:32 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id CE46728FB9; Wed, 16 Nov 2016 16:07:32 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from lists.sourceforge.net (lists.sourceforge.net [216.34.181.88]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 4A90828FB3 for ; Wed, 16 Nov 2016 16:07:30 +0000 (UTC) Received: from localhost ([127.0.0.1] helo=sfs-ml-2.v29.ch3.sourceforge.com) by sfs-ml-2.v29.ch3.sourceforge.com with esmtp (Exim 4.76) (envelope-from ) id 1c72kC-0000P9-Ie; Wed, 16 Nov 2016 16:07:28 +0000 Received: from sog-mx-1.v43.ch3.sourceforge.com ([172.29.43.191] helo=mx.sourceforge.net) by sfs-ml-2.v29.ch3.sourceforge.com with esmtp (Exim 4.76) (envelope-from ) id 1c72kC-0000P3-61 for tpmdd-devel@lists.sourceforge.net; Wed, 16 Nov 2016 16:07:28 +0000 Received-SPF: fail (sog-mx-1.v43.ch3.sourceforge.com: domain of intel.com does not designate 192.55.52.120 as permitted sender) client-ip=192.55.52.120; envelope-from=tomas.winkler@intel.com; helo=mga04.intel.com; Received: from mga04.intel.com ([192.55.52.120]) by sog-mx-1.v43.ch3.sourceforge.com with esmtps (TLSv1:AES256-SHA:256) (Exim 4.76) id 1c72k9-00005a-U4 for tpmdd-devel@lists.sourceforge.net; Wed, 16 Nov 2016 16:07:28 +0000 Received: from fmsmga003.fm.intel.com ([10.253.24.29]) by fmsmga104.fm.intel.com with ESMTP; 16 Nov 2016 08:07:19 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.31,500,1473145200"; d="scan'208";a="787198967" Received: from twinkler-lnx.jer.intel.com ([10.12.87.167]) by FMSMGA003.fm.intel.com with ESMTP; 16 Nov 2016 08:07:17 -0800 From: Tomas Winkler To: tpmdd-devel@lists.sourceforge.net, Jason Gunthorpe , Jarkko Sakkinen Date: Wed, 16 Nov 2016 19:03:39 +0200 Message-Id: <1479315821-27349-2-git-send-email-tomas.winkler@intel.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1479315821-27349-1-git-send-email-tomas.winkler@intel.com> References: <1479315821-27349-1-git-send-email-tomas.winkler@intel.com> X-Headers-End: 1c72k9-00005a-U4 Cc: linux-kernel@vger.kernel.org Subject: [tpmdd-devel] [PATCH 2/4 v2] tpm/tpm2-chip: fix kdoc errors X-BeenThere: tpmdd-devel@lists.sourceforge.net X-Mailman-Version: 2.1.9 Precedence: list List-Id: Tpm Device Driver maintainance List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: tpmdd-devel-bounces@lists.sourceforge.net X-Virus-Scanned: ClamAV using ClamSMTP Use correct kdoc format, describe correct parameters and return values. Signed-off-by: Tomas Winkler Reviewed-by: Jarkko Sakkinen --- V2: rework and rebase of tpm_transmit_cmd kdoc fix drivers/char/tpm/tpm2-cmd.c | 104 ++++++++++++++++++++++++-------------------- 1 file changed, 57 insertions(+), 47 deletions(-) diff --git a/drivers/char/tpm/tpm2-cmd.c b/drivers/char/tpm/tpm2-cmd.c index da5b782a9731..6f9eea7eda7a 100644 --- a/drivers/char/tpm/tpm2-cmd.c +++ b/drivers/char/tpm/tpm2-cmd.c @@ -258,11 +258,9 @@ static const struct tpm_input_header tpm2_pcrread_header = { * tpm2_pcr_read() - read a PCR value * @chip: TPM chip to use. * @pcr_idx: index of the PCR to read. - * @ref_buf: buffer to store the resulting hash, + * @res_buf: buffer to store the resulting hash, * - * 0 is returned when the operation is successful. If a negative number is - * returned it remarks a POSIX error code. If a positive number is returned - * it remarks a TPM error. + * Return: same as with tpm_transmit_cmd */ int tpm2_pcr_read(struct tpm_chip *chip, int pcr_idx, u8 *res_buf) { @@ -304,13 +302,12 @@ static const struct tpm_input_header tpm2_pcrextend_header = { /** * tpm2_pcr_extend() - extend a PCR value + * * @chip: TPM chip to use. * @pcr_idx: index of the PCR. * @hash: hash value to use for the extend operation. * - * 0 is returned when the operation is successful. If a negative number is - * returned it remarks a POSIX error code. If a positive number is returned - * it remarks a TPM error. + * Return: same as with tpm_transmit_cmd */ int tpm2_pcr_extend(struct tpm_chip *chip, int pcr_idx, const u8 *hash) { @@ -348,13 +345,14 @@ static const struct tpm_input_header tpm2_getrandom_header = { /** * tpm2_get_random() - get random bytes from the TPM RNG + * * @chip: TPM chip to use * @out: destination buffer for the random bytes * @max: the max number of bytes to write to @out * - * 0 is returned when the operation is successful. If a negative number is - * returned it remarks a POSIX error code. If a positive number is returned - * it remarks a TPM error. + * Return: + * size of the output buffer; + * -EIO on error */ int tpm2_get_random(struct tpm_chip *chip, u8 *out, size_t max) { @@ -404,15 +402,16 @@ static const struct tpm_input_header tpm2_get_tpm_pt_header = { }; /** - * Append TPMS_AUTH_COMMAND to the buffer. The buffer must be allocated with - * tpm_buf_alloc(). - * - * @param buf: an allocated tpm_buf instance - * @param nonce: the session nonce, may be NULL if not used - * @param nonce_len: the session nonce length, may be 0 if not used - * @param attributes: the session attributes - * @param hmac: the session HMAC or password, may be NULL if not used - * @param hmac_len: the session HMAC or password length, maybe 0 if not used + * tpm_buf_alloc() - Append TPMS_AUTH_COMMAND to the buffer. + * The buffer must be allocated with + * + * @buf: an allocated tpm_buf instance + * @session_handle: session handle + * @nonce: the session nonce, may be NULL if not used + * @nonce_len: the session nonce length, may be 0 if not used + * @attributes: the session attributes + * @hmac: the session HMAC or password, may be NULL if not used + * @hmac_len: the session HMAC or password length, maybe 0 if not used */ static void tpm2_buf_append_auth(struct tpm_buf *buf, u32 session_handle, const u8 *nonce, u16 nonce_len, @@ -435,7 +434,8 @@ static void tpm2_buf_append_auth(struct tpm_buf *buf, u32 session_handle, /** * tpm2_seal_trusted() - seal the payload of a trusted key - * @chip_num: TPM chip to use + * + * @chip: TPM chip to use * @payload: the key data in clear and encrypted form * @options: authentication values and other options * @@ -540,11 +540,17 @@ int tpm2_seal_trusted(struct tpm_chip *chip, /** * tpm2_load_cmd() - execute a TPM2_Load command - * @chip_num: TPM chip to use + * + * @chip: TPM chip to use * @payload: the key data in clear and encrypted form * @options: authentication values and other options + * @blob_handle: returned blob handle + * @flags: tpm transmit flags * - * Return: same as with tpm_transmit_cmd + * Return: 0 on success + * -E2BIG on wrong payload size + * -EPERM on tpm error status + * < 0 error from tpm_transmit_cmd */ static int tpm2_load_cmd(struct tpm_chip *chip, struct trusted_key_payload *payload, @@ -600,9 +606,10 @@ static int tpm2_load_cmd(struct tpm_chip *chip, /** * tpm2_flush_context_cmd() - execute a TPM2_FlushContext command - * @chip_num: TPM chip to use - * @payload: the key data in clear and encrypted form - * @options: authentication values and other options + * + * @chip: TPM chip to use + * @handle: the key data in clear and encrypted form + * @flags: tpm transmit flags * * Return: same as with tpm_transmit_cmd */ @@ -632,11 +639,16 @@ static void tpm2_flush_context_cmd(struct tpm_chip *chip, u32 handle, /** * tpm2_unseal_cmd() - execute a TPM2_Unload command - * @chip_num: TPM chip to use + * + * @chip: TPM chip to use * @payload: the key data in clear and encrypted form * @options: authentication values and other options + * @blob_handle: blob handle + * @flags: tpm_transmit_cmd flags * - * Return: same as with tpm_transmit_cmd + * Return: 0 on success + * -EPERM on tpm error status + * < 0 error from tpm_transmit_cmd */ static int tpm2_unseal_cmd(struct tpm_chip *chip, struct trusted_key_payload *payload, @@ -681,11 +693,12 @@ static int tpm2_unseal_cmd(struct tpm_chip *chip, /** * tpm2_unseal_trusted() - unseal the payload of a trusted key - * @chip_num: TPM chip to use + * + * @chip: TPM chip to use * @payload: the key data in clear and encrypted form * @options: authentication values and other options * - * Return: < 0 on error and 0 on success. + * Return: same as with tpm_transmit_cmd */ int tpm2_unseal_trusted(struct tpm_chip *chip, struct trusted_key_payload *payload, @@ -715,9 +728,7 @@ int tpm2_unseal_trusted(struct tpm_chip *chip, * @value: output variable. * @desc: passed to tpm_transmit_cmd() * - * 0 is returned when the operation is successful. If a negative number is - * returned it remarks a POSIX error code. If a positive number is returned - * it remarks a TPM error. + * Return: same as with tpm_transmit_cmd */ ssize_t tpm2_get_tpm_pt(struct tpm_chip *chip, u32 property_id, u32 *value, const char *desc) @@ -750,13 +761,12 @@ static const struct tpm_input_header tpm2_startup_header = { /** * tpm2_startup() - send startup command to the TPM chip + * * @chip: TPM chip to use. - * @startup_type startup type. The value is either + * @startup_type: startup type. The value is either * TPM_SU_CLEAR or TPM_SU_STATE. * - * 0 is returned when the operation is successful. If a negative number is - * returned it remarks a POSIX error code. If a positive number is returned - * it remarks a TPM error. + * Return: same as with tpm_transmit_cmd */ static int tpm2_startup(struct tpm_chip *chip, u16 startup_type) { @@ -781,8 +791,9 @@ static const struct tpm_input_header tpm2_shutdown_header = { /** * tpm2_shutdown() - send shutdown command to the TPM chip + * * @chip: TPM chip to use. - * @shutdown_type shutdown type. The value is either + * @shutdown_type: shutdown type. The value is either * TPM_SU_CLEAR or TPM_SU_STATE. */ void tpm2_shutdown(struct tpm_chip *chip, u16 shutdown_type) @@ -805,12 +816,11 @@ void tpm2_shutdown(struct tpm_chip *chip, u16 shutdown_type) /* * tpm2_calc_ordinal_duration() - maximum duration for a command + * * @chip: TPM chip to use. * @ordinal: command code number. * - * 0 is returned when the operation is successful. If a negative number is - * returned it remarks a POSIX error code. If a positive number is returned - * it remarks a TPM error. + * Return: maximum duration for a command */ unsigned long tpm2_calc_ordinal_duration(struct tpm_chip *chip, u32 ordinal) { @@ -842,13 +852,12 @@ static const struct tpm_input_header tpm2_selftest_header = { /** * tpm2_continue_selftest() - start a self test + * * @chip: TPM chip to use * @full: test all commands instead of testing only those that were not * previously tested. * - * 0 is returned when the operation is successful. If a negative number is - * returned it remarks a POSIX error code. If a positive number is returned - * it remarks a TPM error. + * Return: same as with tpm_transmit_cmd with exception of RC_TESTING */ static int tpm2_start_selftest(struct tpm_chip *chip, bool full) { @@ -874,14 +883,13 @@ static int tpm2_start_selftest(struct tpm_chip *chip, bool full) /** * tpm2_do_selftest() - run a full self test + * * @chip: TPM chip to use * + * Return: same as with tpm_transmit_cmd + * * During the self test TPM2 commands return with the error code RC_TESTING. * Waiting is done by issuing PCR read until it executes successfully. - * - * 0 is returned when the operation is successful. If a negative number is - * returned it remarks a POSIX error code. If a positive number is returned - * it remarks a TPM error. */ static int tpm2_do_selftest(struct tpm_chip *chip) { @@ -928,6 +936,8 @@ static int tpm2_do_selftest(struct tpm_chip *chip) * tpm2_probe() - probe TPM 2.0 * @chip: TPM chip to use * + * Return: < 0 error and 0 on success. + * * Send idempotent TPM 2.0 command and see whether TPM 2.0 chip replied based on * the reply tag. */