From: Randy Dunlap <rdunlap@infradead.org>
To: Philipp Zabel <p.zabel@pengutronix.de>, linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org, Jonathan Corbet <corbet@lwn.net>,
Vivek Gautam <vivek.gautam@codeaurora.org>,
Masahiro Yamada <yamada.masahiro@socionext.com>,
Bartosz Golaszewski <bgolaszewski@baylibre.com>,
Hans de Goede <hdegoede@redhat.com>,
Martin Blumenstingl <martin.blumenstingl@googlemail.com>,
Ramiro Oliveira <Ramiro.Oliveira@synopsys.com>,
Dinh Nguyen <dinguyen@kernel.org>,
Thierry Reding <treding@nvidia.com>,
Geert Uytterhoeven <geert@linux-m68k.org>,
Lee Jones <lee.jones@linaro.org>,
kernel@pengutronix.de
Subject: Re: [RFC] docs: add a reset controller chapter to the driver API docs
Date: Tue, 22 Oct 2019 20:56:45 -0700 [thread overview]
Message-ID: <8e964179-4515-33ea-bdc4-f27daa311267@infradead.org> (raw)
In-Reply-To: <20191022164547.22632-1-p.zabel@pengutronix.de>
On 10/22/19 9:45 AM, Philipp Zabel wrote:
> Add initial reset controller API documentation. This is mostly indented
intended
> to describe the concepts to users of the consumer API, and to tie the
> kerneldoc comments we already have into the driver API documentation.
>
> Signed-off-by: Philipp Zabel <p.zabel@pengutronix.de>
> ---
> Documentation/driver-api/index.rst | 1 +
> Documentation/driver-api/reset.rst | 217 +++++++++++++++++++++++++++++
> 2 files changed, 218 insertions(+)
> create mode 100644 Documentation/driver-api/reset.rst
>
> diff --git a/Documentation/driver-api/reset.rst b/Documentation/driver-api/reset.rst
> new file mode 100644
> index 000000000000..210ccd97c5f0
> --- /dev/null
> +++ b/Documentation/driver-api/reset.rst
> @@ -0,0 +1,217 @@
> +.. SPDX-License-Identifier: GPL-2.0-only
> +
> +====================
> +Reset controller API
> +====================
> +
> +Introduction
> +============
> +
> +Reset controllers are central units that control the reset signals to multiple
> +peripherals.
> +The reset controller API is split in two parts:
I prefer into two parts:
> +the `consumer driver interface <#consumer-driver-interface>`__ (`API reference
> +<#reset-consumer-api>`__), which allows peripheral drivers to request control
> +over their reset input signals, and the `reset controller driver interface
> +<#reset-controller-driver-interface>`__ (`API reference
> +<#reset-controller-driver-api>`__), which is used by drivers for reset
> +controller devices to register their reset controls to provide them to the
> +consumers.
> +
> +While some reset controller hardware units also implement system restart
> +functionality, restart handlers are out of scope for the reset controller API.
> +
> +Glossary
> +--------
> +
> +The reset controller API uses these terms with a specific meaning:
> +
> +Reset line
> +
> + Physical reset line carrying a reset signal from a reset controller
> + hardware unit to a peripheral module.
> +
> +Reset control
> +
> + Control method that determines the state of one or multiple reset lines.
> + Most commonly this is a single bit in reset controller register space that
> + either allows direct control over the physical state of the reset line, or
> + is self-clearing and can be used to trigger a predetermined pulse on the
> + reset line.
> + In more complicated reset controls, a single trigger action can launch a
> + carefully timed sequence of pulses on multiple reset lines.
> +
> +Reset controller
> +
> + A hardware module that provides a number of reset controls to control a
> + number of reset lines.
> +
> +Reset consumer
> +
> + Peripheral module or external IC that is put into reset by the signal on a
> + reset line.
> +
> +Consumer driver interface
> +=========================
> +
> +This interface offers a similar API to the kernel clock framework.
or:
This interface provides an API that is similar to the kernel clock framework.
> +Consumer drivers use get and put operations to acquire and release reset
> +controls.
> +Functions are provided to assert and deassert the controlled reset lines,
> +trigger reset pulses, or to query reset line status.
> +
> +When requesting reset controls, consumers can use symbolic names for their
> +reset inputs, which are mapped to an actual reset control on an existing reset
> +controller device by the core.
> +
> +A stub version of this API is provided when the reset controller framework is
> +not in use in order to minimise the need to use ifdefs.
> +
> +Shared and exclusive resets
> +---------------------------
[snip]
> +
> +API reference
> +=============
> +
> +The reset controller API is documented here in two parts:
> +the `reset consumer API <#reset-consumer-api>`__ and the `reset controller
> +driver API <#reset-controller-driver-api>`__.
> +
> +Reset consumer API
> +------------------
> +
> +Reset consumers can control a reset line using an opaque reset control handle,
> +which can be obtained from :c:func:`devm_reset_control_get_exclusive` or
> +:c:func:`devm_reset_control_get_shared`.
> +Given the reset control, consumers can call :c:func:`reset_control_assert` and
> +:c:func:`reset_control_deassert`, trigger a reset pulse using
> +:c:func:`reset_control_reset`, or query the reset line status using
> +:c:func:`reset_control_status`.
> +
> +.. kernel-doc:: include/linux/reset.h
> + :internal:
> +
> +.. kernel-doc:: drivers/reset/core.c
> + :functions: reset_control_reset
> + reset_control_assert
> + reset_control_deassert
> + reset_control_status
> + reset_control_acquire
> + reset_control_release
> + reset_control_put
> + of_reset_control_get_count
> + of_reset_control_array_get
> + devm_reset_control_array_get
> + reset_control_get_count
> +
> +Reset controller driver API
> +---------------------------
> +
> +Reset controller drivers are supposed to implement the necessary functions in
> +a static constant structure :c:type:`reset_control_ops`, allocate and fill out
> +a struct :c:type:`reset_controller_dev`, and register it using
> +:c:func:`devm_reset_controller_register`.
> +
> +.. kernel-doc:: include/linux/reset-controller.h
> + :internal:
> +
> +.. kernel-doc:: drivers/reset/core.c
> + :functions: of_reset_simple_xlate
> + reset_controller_register
> + reset_controller_unregister
> + devm_reset_controller_register
> + reset_controller_add_lookup
These header and source files cause a number of kernel-doc warnings
for which I am sending a patch.
thanks.
--
~Randy
next prev parent reply other threads:[~2019-10-23 3:57 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-10-22 16:45 [RFC] docs: add a reset controller chapter to the driver API docs Philipp Zabel
2019-10-22 17:00 ` Jonathan Corbet
2019-10-24 8:18 ` Philipp Zabel
2019-10-23 3:56 ` Randy Dunlap [this message]
2019-10-24 8:43 ` Philipp Zabel
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=8e964179-4515-33ea-bdc4-f27daa311267@infradead.org \
--to=rdunlap@infradead.org \
--cc=Ramiro.Oliveira@synopsys.com \
--cc=bgolaszewski@baylibre.com \
--cc=corbet@lwn.net \
--cc=dinguyen@kernel.org \
--cc=geert@linux-m68k.org \
--cc=hdegoede@redhat.com \
--cc=kernel@pengutronix.de \
--cc=lee.jones@linaro.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=martin.blumenstingl@googlemail.com \
--cc=p.zabel@pengutronix.de \
--cc=treding@nvidia.com \
--cc=vivek.gautam@codeaurora.org \
--cc=yamada.masahiro@socionext.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).