Part 1
요약·해설
Power rail·clock·device PM에 쓰는 on-off policy와 공식 렌더링의 45개 macro·callback·function·structure를 설명합니다.
Request · release · reset
Off · on · error
Client · monitor
Part 2
접을 수 있는 영어 원문 전체
영어 원문 전체 펼치기
52EEDAAF6E07AA538DC43E4F04A5BF126599601F7213DEBD6737A0173B2C08AE
.. _resource_mgmt:
Resource Management
###################
There are various situations where it's necessary to coordinate resource
use at runtime among multiple clients. These include power rails,
clocks, other peripherals, and binary device power management. The
complexity of properly managing multiple consumers of a device in a
multithreaded system, especially when transitions may be asynchronous,
suggests that a shared implementation is desirable.
Zephyr provides managers for several coordination policies. These
managers are embedded into services that use them for specific
functions.
.. contents::
:local:
:depth: 2
.. _resource_mgmt_onoff:
On-Off Manager
**************
An on-off manager supports an arbitrary number of clients of a service
which has a binary state. Example applications are power rails, clocks,
and binary device power management.
The manager has the following properties:
* The stable states are off, on, and error. The service always begins
in the off state. The service may also be in a transition to a given
state.
* The core operations are request (add a dependency) and release (remove
a dependency). Supporting operations are reset (to clear an error
state) and cancel (to reclaim client data from an in-progress
transition). The service manages the state based on calls to
functions that initiate these operations.
* The service transitions from off to on when first client request is
received.
* The service transitions from on to off when last client release is
received.
* Each service configuration provides functions that implement the
transition from off to on, from on to off, and optionally from an
error state to off. Transitions must be invokable from both thread
and interrupt context.
* The request and reset operations are asynchronous using
:ref:`async_notification`. Both operations may be cancelled, but
cancellation has no effect on the in-progress transition.
* Requests to turn on may be queued while a transition to off is in
progress: when the service has turned off successfully it will be
immediately turned on again (where context allows) and waiting clients
notified when the start completes.
Requests are reference counted, but not tracked. That means clients are
responsible for recording whether their requests were accepted, and for
initiating a release only if they have previously successfully completed
a request. Improper use of the API can cause an active client to be
shut out, and the manager does not maintain a record of specific clients
that have been granted a request.
Failures in executing a transition are recorded and inhibit further
requests or releases until the manager is reset. Pending requests are
notified (and cancelled) when errors are discovered.
Transition operation completion notifications are provided through
:ref:`async_notification`.
Clients and other components interested in tracking all service state
changes, including when a service begins turning off or enters an error
state, can be informed of state transitions by registering a monitor
with onoff_monitor_register(). Notification of changes are provided
before issuing completion notifications associated with the new
state.
.. note::
A generic API may be implemented by multiple drivers where the common
case is asynchronous. The on-off client structure may be an
appropriate solution for the generic API. Where drivers that can
guarantee synchronous context-independent transitions a driver may
use :c:type:`onoff_sync_service` and its supporting API rather than
:c:type:`onoff_manager`, with only a small reduction in functionality
(primarily no support for the monitor API).
.. doxygengroup:: resource_mgmt_onoff_apis
Part 3
한국어 전문 번역
여러 client가 runtime에 power rail, clock, peripheral, binary device PM 같은 resource를 함께 사용할 때 coordination이 필요합니다. Multithreaded system에서 consumer가 많고 transition까지 asynchronous일 수 있으므로 공통 implementation이 유리합니다.
Zephyr는 여러 coordination policy용 manager를 제공하며 실제 service는 필요한 manager를 내부에 embed해 특정 기능을 구현합니다.
On-Off Manager
On-off manager는 binary state service를 임의 수의 client가 공유하도록 합니다. Power rail, clock과 binary device PM이 대표적인 사용처입니다.
- Stable state는 off, on, error이고 service는 항상 off에서 시작합니다. 각 state로 이동 중인 transition state도 있습니다.
- 핵심 operation은 dependency를 추가하는 request와 제거하는 release입니다. Error를 지우는 reset과 진행 중 client operation data를 회수하는 cancel도 제공합니다.
- 첫 client request에서 off→on, 마지막 client release에서 on→off로 전환합니다.
- Service configuration은 start, stop과 optional reset transition function을 제공합니다. 이 function은 thread와 interrupt context 모두에서 시작할 수 있어야 합니다.
- Request와 reset은 asynchronous notification을 사용합니다. Cancel은 client operation을 취소하지만 이미 진행 중인 hardware transition 자체를 중단하지 않습니다.
- Off transition 중에도 on request를 queue할 수 있습니다. Off가 성공하면 context가 허용하는 즉시 다시 on transition을 시작하고 완료 뒤 waiting client에 알립니다.
ONOFF_STATE_TO_ONstart function이 비동기로 on 전환을 수행ONOFF_STATE_TO_OFF대기 request가 있으면 off 완료 뒤 즉시 다시 startTransition 실패는 error state로 기록되고 reset될 때까지 추가 request와 release를 막습니다. Error 발견 시 pending request에도 실패 notification을 보내고 취소합니다. Transition completion은 asynchronous notification mechanism으로 전달합니다.
모든 state change, off transition 시작과 error 진입까지 관찰하려는 component는 onoff_monitor_register()로 monitor를 등록합니다. Monitor callback은 새 state에 연결된 client completion notification보다 먼저 호출됩니다.
ONOFF_FLAG_ERROR- Service가 error를 기록했음을 나타내는 flag입니다.
ONOFF_STATE_MASK- Manager flag에서 service state bit만 분리하는 mask입니다.
ONOFF_STATE_OFF- Service가 안정된 off 상태일 때 mask로 얻는 값입니다.
ONOFF_STATE_ON- Service가 안정된 on 상태일 때의 값입니다.
ONOFF_STATE_ERROR- Reset 중이 아닌 error state 값입니다.
ONOFF_STATE_TO_ON- Off에서 on으로 transition 중인 state 값입니다.
ONOFF_STATE_TO_OFF- On에서 off로 transition 중인 state 값입니다.
ONOFF_STATE_RESETTING- Error state를 reset하는 중인 값입니다.
ONOFF_TRANSITIONS_INITIALIZER(start, stop, reset)- Start·stop·optional reset function으로
onoff_transitions를 초기화합니다. ONOFF_CLIENT_EXTENSION_POS- Containing service가
sys_notifyflag를 확장해 사용할 수 있는 bit 위치입니다. onoff_notify_fn(mgr, res)- Transition implementation이 완료 결과를 manager에 알릴 때 사용하는 callback signature입니다.
onoff_transition_fn(mgr, notify)- Service가 start, stop 또는 reset transition을 실제로 시작하는 function signature입니다. 완료하면 notify를 반드시 호출합니다.
onoff_client_callback(mgr, cli, state, res)- Client operation 완료를 request/reset caller에 알리는 callback signature입니다.
onoff_monitor_callback(mgr, mon, state, res)- Error나 state transition 완료를 monitor에 알리는 callback signature입니다.
onoff_manager_init(mgr, transitions)- Transition function 집합으로 manager를 초기 off state에 설정합니다.
onoff_has_error(mgr)- Service가 reset이 필요한 error를 기록했는지 확인합니다.
onoff_request(mgr, cli)- Service 사용 reservation을 asynchronous request합니다. 첫 reference면 start transition을 시작하고 client notification으로 결과를 돌려줍니다.
onoff_release(mgr)- Accepted request의 reference를 하나 해제합니다. 마지막 reference면 stop transition을 시작합니다.
onoff_cancel(mgr, cli)- 아직 완료되지 않은 client request 또는 reset notification을 취소합니다. Hardware transition에는 영향을 주지 않습니다.
onoff_cancel_or_release(mgr, cli)- Request가 pending이면 cancel하고 이미 granted됐다면 release하는 안전 helper입니다.
onoff_reset(mgr, cli)- Error state를 clear하고 service를 off로 되돌리는 optional asynchronous reset을 요청합니다.
onoff_monitor_register(mgr, mon)- Manager의 모든 state change를 받을 monitor를 등록합니다.
onoff_monitor_unregister(mgr, mon)- 등록된 state monitor를 제거합니다.
onoff_sync_lock(srv)- Synchronous on-off service lock을 잡고 현재 reference/error state를 반환합니다.
onoff_sync_finalize(srv, key, on, res)- Lock 아래 시작한 synchronous transition 결과를 반영하고 lock을 해제합니다.
struct onoff_transitions- Service state를 on으로 바꾸는
start, off로 바꾸는stop, error를 clear하는 optionalresetfunction 집합입니다. onoff_transitions.start- Service를 on으로 전환하는 function입니다.
onoff_transitions.stop- Service를 off로 전환하는 function입니다.
onoff_transitions.reset- 지원되는 경우 service error state를 reset하는 function입니다.
struct onoff_manager- Waiting client, monitor, transition function과 state/reference 정보를 보관하는 asynchronous manager입니다.
onoff_manager.clients- Request 또는 reset completion을 기다리는 client list입니다.
onoff_manager.monitors- Error와 transition 완료를 포함한 state change를 받을 monitor list입니다.
onoff_manager.transitions- 이 service의 start·stop·reset function입니다.
onoff_manager.lock- 다른 manager field를 보호하는 spin lock입니다.
onoff_manager.last_res- 마지막 transition result입니다.
onoff_manager.flags- 현재 stable·transition·error state를 나타내는 flag입니다.
onoff_manager.refs- Service를 사용하는 active client reference 수입니다.
struct onoff_client- Client operation의 asynchronous notification configuration을 보관합니다.
onoff_client.notify- Callback, signal 또는 spin-wait completion을 설정하는
sys_notify객체입니다. struct onoff_monitor- Manager monitor list에 연결되는 node와 callback을 보관합니다.
onoff_monitor.node- Monitor set에 연결하기 위한 list node입니다.
onoff_monitor.callback- State change 때 호출할 monitor callback입니다.
struct onoff_sync_service- Synchronous on-off service의 lock과 reference/error count를 보관합니다.
onoff_sync_service.lock- Synchronous service field를 보호하는 lock입니다.
onoff_sync_service.count- 음수이면 error, 0 이상이면 active reference count입니다.
Source
출처
영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.