services/ipc/ipc_service/ipc_service.html · services/ipc/ipc_service/ipc_service.rst 공식 원문 ↗

Zephyr 3.7.0 · OS Services · IPC

IPC Service

Physical channel은 instance로, application의 독립 data stream은 endpoint로 표현합니다.

Official pathservices/ipc/ipc_service/ipc_service.html
Source fileservices/ipc/ipc_service/ipc_service.rst
Source versionZephyr 3.7.0
TranslationFull · reviewed

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

Part 1

요약·해설

Open-before-register 순서, bound callback, RX buffer hold/release, TX buffer ownership과 backend 최소 기능을 설명합니다.

Channel

Instance

Stream

Endpoint

Transfer

Send · no-copy

Part 2

접을 수 있는 영어 원문 전체

영어 원문 전체 펼치기
원문 SHA-256 74D3429DA55C40697F80280CF88FC2628359A9269537D9B43F0AE5DE32485D37
.. _ipc_service:

IPC service
###########

.. contents::
    :local:
    :depth: 2

The IPC service API provides an interface to exchange data between two domains
or CPUs.

Overview
========

An IPC service communication channel consists of one instance and one or
several endpoints associated with the instance.

An instance is the external representation of a physical communication channel
between two domains or CPUs. The actual implementation and internal
representation of the instance is peculiar to each backend.

An individual instance is not used to send data between domains/CPUs. To send
and receive the data, the user must create (register) an endpoint in the
instance. This allows for the connection of the two domains of interest.

It is possible to have zero or multiple endpoints for one single instance,
possibly with different priorities, and to use each to exchange data.
Endpoint prioritization and multi-instance ability highly depend on the backend
used.

The endpoint is an entity the user must use to send and receive data between
two domains (connected by the instance). An endpoint is always associated to an
instance.

The creation of the instances is left to the backend, usually at init time.
The registration of the endpoints is left to the user, usually at run time.

The API does not mandate a way for the backend to create instances but it is
strongly recommended to use the devicetree to retrieve the configuration
parameters for an instance. Currently, each backend defines its own
DT-compatible configuration that is used to configure the interface at boot
time.

The following usage scenarios are supported:

* Simple data exchange.
* Data exchange using the no-copy API.

Simple data exchange
====================

To send data between domains or CPUs, an endpoint must be registered onto
an instance.

See the following example:

.. note::

   Before registering an endpoint, the instance must be opened using the
   :c:func:`ipc_service_open_instance` function.


.. code-block:: c

   #include <zephyr/ipc/ipc_service.h>

   static void bound_cb(void *priv)
   {
      /* Endpoint bounded */
   }

   static void recv_cb(const void *data, size_t len, void *priv)
   {
      /* Data received */
   }

   static struct ipc_ept_cfg ept0_cfg = {
      .name = "ept0",
      .cb = {
         .bound    = bound_cb,
         .received = recv_cb,
      },
   };

   int main(void)
   {
      const struct device *inst0;
      struct ipc_ept ept0;
      int ret;

      inst0 = DEVICE_DT_GET(DT_NODELABEL(ipc0));
      ret = ipc_service_open_instance(inst0);
      ret = ipc_service_register_endpoint(inst0, &ept0, &ept0_cfg);

      /* Wait for endpoint bound (bound_cb called) */

      unsigned char message[] = "hello world";
      ret = ipc_service_send(&ept0, &message, sizeof(message));
   }

Data exchange using the no-copy API
===================================

If the backend supports the no-copy API you can use it to directly write and
read to and from shared memory regions.

See the following example:

.. code-block:: c

   #include <zephyr/ipc/ipc_service.h>
   #include <stdint.h>
   #include <string.h>

   static struct ipc_ept ept0;

   static void bound_cb(void *priv)
   {
      /* Endpoint bounded */
   }

   static void recv_cb_nocopy(const void *data, size_t len, void *priv)
   {
      int ret;

      ret = ipc_service_hold_rx_buffer(&ept0, (void *)data);
      /* Process directly or put the buffer somewhere else and release. */
      ret = ipc_service_release_rx_buffer(&ept0, (void *)data);
   }

   static struct ipc_ept_cfg ept0_cfg = {
      .name = "ept0",
      .cb = {
         .bound    = bound_cb,
         .received = recv_cb,
      },
   };

   int main(void)
   {
      const struct device *inst0;
      int ret;

      inst0 = DEVICE_DT_GET(DT_NODELABEL(ipc0));
      ret = ipc_service_open_instance(inst0);
      ret = ipc_service_register_endpoint(inst0, &ept0, &ept0_cfg);

      /* Wait for endpoint bound (bound_cb called) */
      void *data;
      unsigned char message[] = "hello world";
      uint32_t len = sizeof(message);

      ret = ipc_service_get_tx_buffer(&ept0, &data, &len, K_FOREVER);

      memcpy(data, message, len);

      ret = ipc_service_send_nocopy(&ept0, data, sizeof(message));
   }

Backends
********

The requirements needed for implementing backends give flexibility to the IPC
service. These allow for the addition of dedicated backends having only a
subsets of features for specific use cases.

The backend must support at least the following:

* The init-time creation of instances.
* The run-time registration of an endpoint in an instance.

Additionally, the backend can also support the following:

* The run-time deregistration of an endpoint from the instance.
* The run-time closing of an instance.
* The no-copy API.

Each backend can have its own limitations and features that make the backend
unique and dedicated to a specific use case. The IPC service API can be used
with multiple backends simultaneously, combining the pros and cons of each
backend.

.. toctree::
   :maxdepth: 1

   backends/ipc_service_icmsg.rst
   backends/ipc_service_icbmsg.rst

API Reference
*************

IPC service API
===============

.. doxygengroup:: ipc_service_api

IPC service backend API
=======================

.. doxygengroup:: ipc_service_backend

Part 3

한국어 전문 번역

IPC service API는 두 domain 또는 CPU 사이에서 data를 교환하는 interface를 제공합니다.

Overview

IPC service communication channel은 instance 하나와 그 instance에 연결된 endpoint 하나 이상으로 구성됩니다.

Instance는 두 domain 또는 CPU 사이의 물리 communication channel을 외부에 나타내는 객체입니다. 실제 구현과 내부 표현은 backend마다 다릅니다.

Instance 자체로 data를 보내지는 않습니다. Data를 송수신하려면 user가 instance에 endpoint를 생성, 즉 등록해야 합니다. Endpoint가 관심 있는 두 domain을 연결합니다.

Instance 하나에 endpoint가 없을 수도 있고 여러 개 있을 수도 있으며, endpoint마다 priority가 다를 수 있습니다. Endpoint priority와 multi-instance 지원 수준은 사용하는 backend에 크게 의존합니다.

Endpoint는 instance로 연결된 두 domain 사이에서 user가 실제 data를 송수신할 때 사용하는 entity이며 항상 instance 하나에 연결됩니다.

Instance 생성은 보통 init time에 backend가 담당하고, endpoint 등록은 보통 runtime에 user가 담당합니다.

API는 backend의 instance 생성 방식을 강제하지 않지만, instance configuration parameter는 devicetree에서 가져오기를 강하게 권장합니다. 현재 각 backend는 boot time interface 설정에 사용하는 자체 DT-compatible configuration을 정의합니다.

지원 scenario는 일반 data exchange와 no-copy API를 사용하는 data exchange입니다.

일반 data exchange

Domain 또는 CPU 사이에서 data를 보내려면 endpoint를 instance에 등록해야 합니다.

#include <zephyr/ipc/ipc_service.h>

static void bound_cb(void *priv)
{
   /* Endpoint bounded */
}

static void recv_cb(const void *data, size_t len, void *priv)
{
   /* Data received */
}

static struct ipc_ept_cfg ept0_cfg = {
   .name = "ept0",
   .cb = {
      .bound    = bound_cb,
      .received = recv_cb,
   },
};

int main(void)
{
   const struct device *inst0;
   struct ipc_ept ept0;
   int ret;

   inst0 = DEVICE_DT_GET(DT_NODELABEL(ipc0));
   ret = ipc_service_open_instance(inst0);
   ret = ipc_service_register_endpoint(inst0, &ept0, &ept0_cfg);

   /* Wait for endpoint bound (bound_cb called) */

   unsigned char message[] = "hello world";
   ret = ipc_service_send(&ept0, &message, sizeof(message));
}

예제는 devicetree의 ipc0 device를 가져와 instance를 열고, bound·received callback이 있는 ept0를 등록합니다. 양쪽 endpoint가 bound된 뒤 ipc_service_send()로 message를 보냅니다.

No-copy API를 사용하는 data exchange

Backend가 no-copy API를 지원하면 shared memory region을 직접 읽고 쓸 수 있습니다.

#include <zephyr/ipc/ipc_service.h>
#include <stdint.h>
#include <string.h>

static struct ipc_ept ept0;

static void bound_cb(void *priv)
{
   /* Endpoint bounded */
}

static void recv_cb_nocopy(const void *data, size_t len, void *priv)
{
   int ret;

   ret = ipc_service_hold_rx_buffer(&ept0, (void *)data);
   /* Process directly or put the buffer somewhere else and release. */
   ret = ipc_service_release_rx_buffer(&ept0, (void *)data);
}

static struct ipc_ept_cfg ept0_cfg = {
   .name = "ept0",
   .cb = {
      .bound    = bound_cb,
      .received = recv_cb,
   },
};

int main(void)
{
   const struct device *inst0;
   int ret;

   inst0 = DEVICE_DT_GET(DT_NODELABEL(ipc0));
   ret = ipc_service_open_instance(inst0);
   ret = ipc_service_register_endpoint(inst0, &ept0, &ept0_cfg);

   /* Wait for endpoint bound (bound_cb called) */
   void *data;
   unsigned char message[] = "hello world";
   uint32_t len = sizeof(message);

   ret = ipc_service_get_tx_buffer(&ept0, &data, &len, K_FOREVER);

   memcpy(data, message, len);

   ret = ipc_service_send_nocopy(&ept0, data, sizeof(message));
}

Receive callback은 ipc_service_hold_rx_buffer()로 buffer 소유 기간을 늘리고 처리가 끝나면 ipc_service_release_rx_buffer()로 반환합니다. 송신 쪽은 ipc_service_get_tx_buffer()로 shared buffer를 받아 직접 채운 뒤 ipc_service_send_nocopy()로 전송합니다.

Backends

Backend implementation requirement는 특정 use case에 필요한 기능 subset만 가진 전용 backend를 추가할 수 있도록 IPC service에 유연성을 제공합니다.

Backend가 반드시 지원해야 하는 기능은 다음과 같습니다.

  • Init time instance 생성
  • Runtime endpoint 등록

선택적으로 다음 기능도 지원할 수 있습니다.

  • Runtime endpoint 등록 해제
  • Runtime instance close
  • No-copy API

Backend마다 고유한 제약과 기능이 있어 특정 use case에 맞게 선택할 수 있습니다. IPC service API는 backend 여러 개를 동시에 사용할 수 있으므로 각 backend의 장단점을 조합할 수 있습니다. Zephyr 3.7.0 문서는 ICMsg와 dynamically allocated buffer 기반 ICBMsg backend를 함께 제공합니다.

API Reference

IPC service API

Application-facing API는 ipc_service_api Doxygen group에 정의돼 있습니다.

IPC service backend API

Backend implementation API는 ipc_service_backend Doxygen group에 정의돼 있습니다.

Source

출처

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