From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-18.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED, USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 5A5B5C433F5 for ; Thu, 23 Sep 2021 09:13:08 +0000 (UTC) Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 9380B611B0 for ; Thu, 23 Sep 2021 09:13:07 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 9380B611B0 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=canonical.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=lists.denx.de Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id B2B5E8336A; Thu, 23 Sep 2021 11:13:04 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=canonical.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (2048-bit key; unprotected) header.d=canonical.com header.i=@canonical.com header.b="DKZs1fUi"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 1F77383394; Thu, 23 Sep 2021 11:13:01 +0200 (CEST) Received: from smtp-relay-canonical-0.canonical.com (smtp-relay-canonical-0.canonical.com [185.125.188.120]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id A6016831D3 for ; Thu, 23 Sep 2021 11:12:56 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=canonical.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=heinrich.schuchardt@canonical.com Received: from workstation5.fritz.box (ip-88-152-144-157.hsi03.unitymediagroup.de [88.152.144.157]) (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 smtp-relay-canonical-0.canonical.com (Postfix) with ESMTPSA id 1F8A240186; Thu, 23 Sep 2021 09:12:55 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=canonical.com; s=20210705; t=1632388375; bh=7wfR/GKCmuc+UhA6oEscP5fGYLMvWrAvmAkAsT1TK0g=; h=From:To:Cc:Subject:Date:Message-Id:MIME-Version; b=DKZs1fUig/Br+vu9Je0JagzmWNdG6UaYQef1me9D0CL9kKUvIqEzu0X2rbnqjvgjO tPVJeetW+iYWc1XorqEiBE5JVsgAp0f6uo6QQ7lNnexOTxdU1cZH+oQyUe9lrpNN2n Nq/aQZca4BdA/wNclJLHv/RpPKJmId7OEgswC8iIYZDt4q2U1FGiYaaDbejCj83J07 NkUr4kv1IBXh8sATrAtk5wUUxZDjrO5vyUBkviRIC0tJJLfQLHSEBVPyd6UM7zR/MV T+0jXYw5s7y4uiPRQE/gwAxbnxoF6Svk/ux3fVdRtu//WvLHXpkYq/eRujW5oxFX7n HqYKj6E+YcisA== From: Heinrich Schuchardt To: Tom Rini , u-boot@lists.denx.de Cc: Sean Anderson , Alexandre Ghiti , Simon Glass , Harald Seiler , Heinrich Schuchardt Subject: [PATCH 1/1] doc: add system reset to API documentation Date: Thu, 23 Sep 2021 11:12:47 +0200 Message-Id: <20210923091247.14191-1-heinrich.schuchardt@canonical.com> X-Mailer: git-send-email 2.32.0 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.34 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.103.2 at phobos.denx.de X-Virus-Status: Clean Complete the Sphinx documentation in include/sysreset.h Add the include to the generated HTML documentation of the U-Boot API. Signed-off-by: Heinrich Schuchardt --- doc/api/index.rst | 1 + doc/api/sysreset.rst | 7 ++++++ include/sysreset.h | 53 ++++++++++++++++++++++++++++---------------- 3 files changed, 42 insertions(+), 19 deletions(-) create mode 100644 doc/api/sysreset.rst diff --git a/doc/api/index.rst b/doc/api/index.rst index ea02aa5715..281d1dca96 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -15,5 +15,6 @@ U-Boot API documentation rng sandbox serial + sysreset timer unicode diff --git a/doc/api/sysreset.rst b/doc/api/sysreset.rst new file mode 100644 index 0000000000..a51b06c387 --- /dev/null +++ b/doc/api/sysreset.rst @@ -0,0 +1,7 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +System reset +============ + +.. kernel-doc:: include/sysreset.h + :internal: diff --git a/include/sysreset.h b/include/sysreset.h index 701e4f5c86..e8411f9664 100644 --- a/include/sysreset.h +++ b/include/sysreset.h @@ -9,43 +9,55 @@ struct udevice; +/** + * enum systreset_t - system reset types + */ enum sysreset_t { - SYSRESET_WARM, /* Reset CPU, keep GPIOs active */ - SYSRESET_COLD, /* Reset CPU and GPIOs */ - SYSRESET_POWER, /* Reset PMIC (remove and restore power) */ - SYSRESET_POWER_OFF, /* Turn off power */ - + /** @SYSRESET_WARM: reset CPU, keep GPIOs active */ + SYSRESET_WARM, + /** @SYSRESET_COLD: reset CPU and GPIOs */ + SYSRESET_COLD, + /** @SYSRESET_POWER: reset PMIC (remove and restore power) */ + SYSRESET_POWER, + /** @SYSRESET_POWER_OFF: turn off power */ + SYSRESET_POWER_OFF, + /** @SYSRESET_COUNT: number of available reset types */ SYSRESET_COUNT, }; +/** + * struct sysreset_ops - operations of system reset drivers + */ struct sysreset_ops { /** - * request() - request a sysreset of the given type + * @request: request a sysreset of the given type * * Note that this function may return before the reset takes effect. * + * @dev: Device to be used for system reset * @type: Reset type to request - * @return -EINPROGRESS if the reset has been started and - * will complete soon, -EPROTONOSUPPORT if not supported - * by this device, 0 if the reset has already happened - * (in which case this method will not actually return) + * Return: + * -EINPROGRESS if the reset has been started and + * will complete soon, -EPROTONOSUPPORT if not supported + * by this device, 0 if the reset has already happened + * (in which case this method will not actually return) */ int (*request)(struct udevice *dev, enum sysreset_t type); /** - * get_status() - get printable reset status information + * @get_status: get printable reset status information * * @dev: Device to check * @buf: Buffer to receive the textual reset information * @size: Size of the passed buffer - * @return 0 if OK, -ve on error + * Return: 0 if OK, -ve on error */ int (*get_status)(struct udevice *dev, char *buf, int size); /** - * get_last() - get information on the last reset + * @get_last: get information on the last reset * * @dev: Device to check - * @return last reset state (enum sysreset_t) or -ve error + * Return: last reset state (enum :enum:`sysreset_t`) or -ve error */ int (*get_last)(struct udevice *dev); }; @@ -55,8 +67,9 @@ struct sysreset_ops { /** * sysreset_request() - request a sysreset * + * @dev: Device to be used for system reset * @type: Reset type to request - * @return 0 if OK, -EPROTONOSUPPORT if not supported by this device + * Return: 0 if OK, -EPROTONOSUPPORT if not supported by this device */ int sysreset_request(struct udevice *dev, enum sysreset_t type); @@ -66,7 +79,7 @@ int sysreset_request(struct udevice *dev, enum sysreset_t type); * @dev: Device to check * @buf: Buffer to receive the textual reset information * @size: Size of the passed buffer - * @return 0 if OK, -ve on error + * Return: 0 if OK, -ve on error */ int sysreset_get_status(struct udevice *dev, char *buf, int size); @@ -74,7 +87,7 @@ int sysreset_get_status(struct udevice *dev, char *buf, int size); * sysreset_get_last() - get information on the last reset * * @dev: Device to check - * @return last reset state (enum sysreset_t) or -ve error + * Return: last reset state (enum sysreset_t) or -ve error */ int sysreset_get_last(struct udevice *dev); @@ -88,7 +101,7 @@ int sysreset_get_last(struct udevice *dev); * If this function fails to reset, it will display a message and halt * * @type: Reset type to request - * @return -EINPROGRESS if a reset is in progress, -ENOSYS if not available + * Return: -EINPROGRESS if a reset is in progress, -ENOSYS if not available */ int sysreset_walk(enum sysreset_t type); @@ -101,7 +114,7 @@ int sysreset_walk(enum sysreset_t type); * * If no device prives the information, this function returns -ENOENT * - * @return last reset state (enum sysreset_t) or -ve error + * Return: last reset state (enum sysreset_t) or -ve error */ int sysreset_get_last_walk(void); @@ -110,6 +123,8 @@ int sysreset_get_last_walk(void); * * This calls sysreset_walk(). If it returns, indicating that reset is not * supported, it prints a message and halts. + * + * @type: Reset type to request */ void sysreset_walk_halt(enum sysreset_t type); -- 2.32.0