Reset controller API

Reset controller API 문서 정보

이 문서는 `GPL-2.0-only` 라이선스를 따르며 Linux reset controller API를 설명합니다.

.. SPDX-License-Identifier: GPL-2.0-only

====================
Reset controller API
====================

Consumer와 controller interface

Reset controller는 여러 peripheral로 전달되는 reset signal을 제어하는 중앙 장치입니다.

Reset controller API는 두 부분으로 나뉩니다. Consumer driver interface는 peripheral driver가 자신의 reset input signal 제어권을 요청하게 하고, reset controller driver interface는 controller device driver가 reset control을 등록해 consumer에 제공하게 합니다. 각 interface에는 별도의 API reference가 있습니다.

일부 reset controller hardware가 system restart 기능도 구현하지만 restart handler는 reset controller API의 범위에 포함되지 않습니다.

Introduction
============

Reset controllers are central units that control the reset signals to multiple
peripherals.
The reset controller API is split 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.

Reset subsystem 용어

Reset line은 reset controller hardware unit에서 peripheral module로 reset signal을 전달하는 물리 선입니다.

Reset control은 하나 이상의 reset line 상태를 결정하는 제어 방식입니다. 흔히 controller register space의 단일 bit이며, 물리 line 상태를 직접 제어하거나 self-clearing 동작으로 미리 정해진 pulse를 발생시킵니다. 더 복잡한 control은 한 번의 trigger로 여러 reset line에 정밀하게 timing된 pulse sequence를 시작할 수도 있습니다.

Reset controller는 여러 reset line을 제어할 수 있는 reset control 집합을 제공하는 hardware module입니다. Reset consumer는 reset line의 signal로 reset 상태에 들어가는 peripheral module 또는 external IC입니다.

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 개요

Consumer interface는 kernel clock framework와 비슷합니다. Consumer driver는 get과 put operation으로 reset control을 획득하고 반환합니다.

제공되는 function으로 제어 대상 reset line을 assert·deassert하거나 reset pulse를 trigger하고, reset line status를 조회할 수 있습니다.

Consumer는 reset input을 symbolic name으로 요청할 수 있습니다. Core가 이 이름을 기존 reset controller device의 실제 reset control에 mapping합니다.

Reset controller framework를 사용하지 않는 configuration에서도 ifdef 사용을 최소화할 수 있도록 이 API의 stub version을 제공합니다.

Consumer driver interface
=========================

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 minimize the need to use ifdefs.

Shared와 exclusive reset

Reset controller API는 reference-counted deassertion·assertion 또는 직접적인 exclusive control을 제공합니다. Reset control을 요청할 때 `devm_reset_control_get_shared()`나 `devm_reset_control_get_exclusive()`를 선택하며, 이 선택이 이후 API call의 동작을 결정합니다.

Shared reset은 clock framework와 비슷합니다. Deassertion reference count가 0에서 1이 되는 첫 deassert와 1에서 0이 되는 마지막 assert만 reset line에 물리적 효과를 냅니다.

Exclusive reset은 직접 제어를 보장합니다. Assert call은 즉시 reset line을 assert하고 deassert call은 즉시 deassert합니다.

Shared and exclusive resets
---------------------------

The reset controller API provides either reference counted deassertion and
assertion or direct, exclusive control.
The distinction between shared and exclusive reset controls is made at the time
the reset control is requested, either via devm_reset_control_get_shared() or
via devm_reset_control_get_exclusive().
This choice determines the behavior of the API calls made with the reset
control.

Shared resets behave similarly to clocks in the kernel clock framework.
They provide reference counted deassertion, where only the first deassert,
which increments the deassertion reference count to one, and the last assert
which decrements the deassertion reference count back to zero, have a physical
effect on the reset line.

Exclusive resets on the other hand guarantee direct control.
That is, an assert causes the reset line to be asserted immediately, and a
deassert causes the reset line to be deasserted immediately.

Assertion과 deassertion

Consumer driver는 `reset_control_assert()`와 `reset_control_deassert()`로 reset line을 assert하거나 deassert합니다. Shared reset control에서는 두 function의 call 수가 균형을 이뤄야 합니다.

여러 consumer가 shared reset control을 사용할 수 있으므로 한 consumer가 `reset_control_assert()`를 호출해도 reset line이 실제로 assert된다는 보장은 없습니다. Shared consumer는 line이 계속 deassert 상태일 수 있다고 가정해야 합니다.

API가 보장하는 것은 어느 consumer든 deassert를 요청한 동안에는 reset line을 assert할 수 없다는 점입니다.

Assertion and deassertion
-------------------------

Consumer drivers use the reset_control_assert() and reset_control_deassert()
functions to assert and deassert reset lines.
For shared reset controls, calls to the two functions must be balanced.

Note that since multiple consumers may be using a shared reset control, there
is no guarantee that calling reset_control_assert() on a shared reset control
will actually cause the reset line to be asserted.
Consumer drivers using shared reset controls should assume that the reset line
may be kept deasserted at all times.
The API only guarantees that the reset line can not be asserted as long as any
consumer has requested it to be deasserted.

Self-deasserting reset pulse

Consumer driver는 `reset_control_reset()`으로 self-deasserting reset control의 reset pulse를 trigger합니다. 일반적으로 한 consumer의 pulse 요청이 연결된 모든 peripheral을 reset하므로 이런 reset은 여러 consumer가 공유할 수 없습니다.

API는 self-deasserting reset control을 shared로 요청하는 것도 허용합니다. 이 경우 첫 trigger 요청만 실제 pulse를 내보내며, 모든 consumer가 `reset_control_rearm()`을 호출할 때까지 이후 `reset_control_reset()` 호출은 효과가 없습니다.

Shared reset control에서는 trigger와 rearm 호출 수가 균형을 이뤄야 합니다. 이 semantics 덕분에 probe 또는 resume 전에 어느 시점에서든 한 번의 초기 reset만 필요로 하는 device들이 pulsed reset line을 공유할 수 있습니다.

Triggering
----------

Consumer drivers use reset_control_reset() to trigger a reset pulse on a
self-deasserting reset control.
In general, these resets can not be shared between multiple consumers, since
requesting a pulse from any consumer driver will reset all connected
peripherals.

The reset controller API allows requesting self-deasserting reset controls as
shared, but for those only the first trigger request causes an actual pulse to
be issued on the reset line.
All further calls to this function have no effect until all consumers have
called reset_control_rearm().
For shared reset controls, calls to the two functions must be balanced.
This allows devices that only require an initial reset at any point before the
driver is probed or resumed to share a pulsed reset line.

Reset line status 조회

현재 reset line 상태 조회는 일부 reset controller만 `reset_control_status()`를 통해 지원합니다. 지원되는 경우 주어진 line이 assert 상태이면 positive non-zero 값을 반환합니다.

`reset_control_status()`는 reset control array handle을 input parameter로 받지 않습니다.

Querying
--------

Only some reset controllers support querying the current status of a reset
line, via reset_control_status().
If supported, this function returns a positive non-zero value if the given
reset line is asserted.
The reset_control_status() function does not accept a
`reset control array <#reset-control-arrays>`__ handle as its input parameter.

Platform별 optional reset

Peripheral이 어떤 platform에서는 reset line을 필요로 하지만 다른 platform에서는 필요로 하지 않는 경우가 많습니다.

이때 `devm_reset_control_get_optional_exclusive()` 또는 `devm_reset_control_get_optional_shared()`로 optional reset control을 요청할 수 있습니다. Device tree에 요청한 reset control이 지정되지 않았으면 error 대신 `NULL` pointer를 반환합니다.

Reset control function에 `NULL` pointer를 전달하면 error 없이 조용히 반환하므로 동일한 consumer code를 reset line 유무와 관계없이 사용할 수 있습니다.

Optional resets
---------------

Often peripherals require a reset line on some platforms but not on others.
For this, reset controls can be requested as optional using
devm_reset_control_get_optional_exclusive() or
devm_reset_control_get_optional_shared().
These functions return a NULL pointer instead of an error when the requested
reset control is not specified in the device tree.
Passing a NULL pointer to the reset_control functions causes them to return
quietly without an error.

Reset control array

일부 driver는 특정 순서 없이 여러 reset line을 한꺼번에 assert해야 합니다. `devm_reset_control_array_get()`은 지정된 모든 reset control을 동시에 assert·deassert하거나 trigger하는 데 사용할 수 있는 opaque reset control handle을 반환합니다.

Reset control API는 array 안의 개별 control을 처리하는 순서를 보장하지 않습니다.

Reset control arrays
--------------------

Some drivers need to assert a bunch of reset lines in no particular order.
devm_reset_control_array_get() returns an opaque reset control handle that can
be used to assert, deassert, or trigger all specified reset controls at once.
The reset control API does not guarantee the order in which the individual
controls therein are handled.

Reset controller driver interface

Reset controller module driver는 reset signal을 assert·deassert하고, reset line에 pulse를 trigger하거나 현재 상태를 조회하는 데 필요한 기능을 제공합니다.

이 interface의 모든 function은 optional입니다. Hardware가 지원하고 driver가 제공해야 하는 operation만 구현할 수 있습니다.

Reset controller driver interface
=================================

Drivers for reset controller modules provide the functionality necessary to
assert or deassert reset signals, to trigger a reset pulse on a reset line, or
to query its current state.
All functions are optional.

Controller 등록과 callback

Driver는 `struct reset_controller_dev`를 채우고 probe function에서 `reset_controller_register()`로 등록합니다.

실제 reset 기능은 `struct reset_control_ops`에 연결한 callback function으로 구현합니다.

Initialization
--------------

Drivers fill a struct :c:type:`reset_controller_dev` and register it with
reset_controller_register() in their probe function.
The actual functionality is implemented in callback functions via a struct
:c:type:`reset_control_ops`.

API reference 구성

Reset controller API reference는 reset consumer API와 reset controller driver API의 두 부분으로 문서화됩니다.

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 reference

Reset consumer는 `devm_reset_control_get_exclusive()` 또는 `devm_reset_control_get_shared()`로 얻은 opaque reset control handle을 사용해 reset line을 제어합니다.

Handle로 `reset_control_assert()`와 `reset_control_deassert()`를 호출하고, `reset_control_reset()`으로 pulse를 trigger하거나 `reset_control_status()`로 line 상태를 조회할 수 있습니다.

Kernel-doc은 `include/linux/reset.h`의 internal declaration과 `drivers/reset/core.c`의 reset·assert·deassert·status·acquire·release·rearm·put 및 count·array 관련 function을 가져옵니다.

Reset consumer API
------------------

Reset consumers can control a reset line using an opaque reset control handle,
which can be obtained from devm_reset_control_get_exclusive() or
devm_reset_control_get_shared().
Given the reset control, consumers can call reset_control_assert() and
reset_control_deassert(), trigger a reset pulse using reset_control_reset(), or
query the reset line status using 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_rearm
               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 reference

Reset controller driver는 필요한 function을 static constant `struct reset_control_ops`에 구현하고, `struct reset_controller_dev`를 allocate·작성한 뒤 `devm_reset_controller_register()`로 등록해야 합니다.

Kernel-doc은 `include/linux/reset-controller.h`의 internal declaration과 `drivers/reset/core.c`의 simple translation, register·unregister, devm registration, lookup 추가 function을 가져옵니다.

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
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