services/resource_management/index.html · services/resource_management/index.rst 공식 원문 ↗

Zephyr 3.7.0 · OS Services · Coordination

Resource Management

여러 client가 binary resource를 안전하게 공유하도록 첫 request와 마지막 release에서 상태를 전환합니다.

Official pathservices/resource_management/index.html
Source fileservices/resource_management/index.rst
Source versionZephyr 3.7.0
TranslationFull · reviewed

본문 기준: Zephyr 3.7.0 LTS3 · 이후 유지보수 패치는 별도입니다.

Part 1

요약·해설

Power rail·clock·device PM에 쓰는 on-off policy와 공식 렌더링의 45개 macro·callback·function·structure를 설명합니다.

Operations

Request · release · reset

States

Off · on · error

Observe

Client · monitor

Part 2

접을 수 있는 영어 원문 전체

영어 원문 전체 펼치기
원문 SHA-256 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에 알립니다.
On-off manager state와 client reference 흐름
OFF · refs=0첫 request가 start transition을 시작
첫 request
ONOFF_STATE_TO_ONstart function이 비동기로 on 전환을 수행
성공
ON · refs≥1추가 request는 reference count만 증가
마지막 release
ONOFF_STATE_TO_OFF대기 request가 있으면 off 완료 뒤 즉시 다시 start
성공하면 OFF · 실패하면 ERROR
ERROR실패 기록, reset 전 request/release 금지
RESETTINGoptional reset transition으로 error를 clear
reset 성공 → OFF

Transition 실패는 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_notify flag를 확장해 사용할 수 있는 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하는 optional reset function 집합입니다.
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

출처

영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.