Iterable Sections 한국어 번역

Part 1

요약·해설

RAM/ROM 여부, 이름·숫자 정렬, garbage collection 정책을 linker output macro로 정하고 element macro와 foreach macro로 접근합니다.

Placement

ROM · RAM

Ordering

name · numeric

Access

foreach · get · count

Part 2

접을 수 있는 영어 원문 전체

영어 원문 전체 펼치기

원문 SHA-256 7F5DA3B74D1A9C83F03D5D31F53709F935B83C07B6AE413CAD79A1895EBFBE8D

.. _iterable_sections_api:

Iterable Sections
#################

This page contains the reference documentation for the iterable sections APIs,
which can be used for defining iterable areas of equally-sized data structures,
that can be iterated on using :c:macro:`STRUCT_SECTION_FOREACH`.

Usage
*****

Iterable section elements are typically used by defining the data structure and
associated initializer in a common header file, so that they can be
instantiated anywhere in the code base.

.. code-block:: c

    struct my_data {
             int a, b;
    };

    #define DEFINE_DATA(name, _a, _b) \
             STRUCT_SECTION_ITERABLE(my_data, name) = { \
                     .a = _a, \
                     .b = _b, \
             }

    ...

    DEFINE_DATA(d1, 1, 2);
    DEFINE_DATA(d2, 3, 4);
    DEFINE_DATA(d3, 5, 6);

Then the linker has to be setup to place the place the structure in a
contiguous segment using one of the linker macros such as
:c:macro:`ITERABLE_SECTION_RAM` or :c:macro:`ITERABLE_SECTION_ROM`. Custom
linker snippets are normally declared using one of the
``zephyr_linker_sources()`` CMake functions, using the appropriate section
identifier, ``DATA_SECTIONS`` for RAM structures and ``SECTIONS`` for ROM ones.

.. code-block:: cmake

   # CMakeLists.txt
   zephyr_linker_sources(DATA_SECTIONS iterables.ld)

.. code-block:: c

   # iterables.ld
   ITERABLE_SECTION_RAM(my_data, 4)

The data can then be accessed using :c:macro:`STRUCT_SECTION_FOREACH`.

.. code-block:: c

   STRUCT_SECTION_FOREACH(my_data, data) {
           printk("%p: a: %d, b: %d\n", data, data->a, data->b);
   }

.. note::
   The linker is going to place the entries sorted by name, so the example
   above would visit ``d1``, ``d2`` and ``d3`` in that order, regardless of how
   they were defined in the code.

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

.. doxygengroup:: iterable_section_apis

Part 3

한국어 전문 번역

이 페이지는 같은 크기의 data structure를 연속 영역에 정의하고 STRUCT_SECTION_FOREACH로 순회하는 iterable section API 참고 문서입니다.

사용법

Iterable section element는 보통 공통 header에 data structure와 initializer를 정의해 code base 어느 곳에서나 instance를 만들 수 있게 합니다.

struct my_data {
         int a, b;
};

#define DEFINE_DATA(name, _a, _b) \
         STRUCT_SECTION_ITERABLE(my_data, name) = { \
                 .a = _a, \
                 .b = _b, \
         }

...

DEFINE_DATA(d1, 1, 2);
DEFINE_DATA(d2, 3, 4);
DEFINE_DATA(d3, 5, 6);

Linker가 structure를 contiguous segment에 배치하도록 ITERABLE_SECTION_RAM 또는 ITERABLE_SECTION_ROM 같은 linker macro를 설정해야 합니다. Custom linker snippet은 보통 zephyr_linker_sources() CMake 함수에 적절한 section identifier를 넘겨 선언합니다. RAM structure는 DATA_SECTIONS, ROM structure는 SECTIONS를 사용합니다.

# CMakeLists.txt
zephyr_linker_sources(DATA_SECTIONS iterables.ld)

# iterables.ld
ITERABLE_SECTION_RAM(my_data, 4)

그 뒤 STRUCT_SECTION_FOREACH로 data를 순회합니다.

STRUCT_SECTION_FOREACH(my_data, data) {
        printk("%p: a: %d, b: %d\n", data, data->a, data->b);
}

API 참고

iterable_section_apis는 ROM/RAM output section, generic type와 struct element 선언, start/end symbol, 순회·index·count macro를 제공합니다.

ITERABLE_SECTION_ROM(struct_type, subalign)

같은 크기 구조체의 read-only iterable output section을 정의합니다. STRUCT_SECTION_ITERABLE()과 함께 사용하며 ld SORT_BY_NAME 규칙으로 input section을 이름순 정렬합니다. 직접 reference가 없어도 image에서 symbol을 유지하므로 section 순회로 간접 접근할 때 사용합니다.

ITERABLE_SECTION_ROM_NUMERIC(struct_type, subalign)

Read-only iterable section을 numeric 순서로 정렬합니다. SECNAME_10이 SECNAME_2 뒤에 오며 underscore separator가 필요하고 0~99 두 자리까지 처리합니다.

ITERABLE_SECTION_ROM_GC_ALLOWED(struct_type, subalign)

같은 크기 구조체용 read-only iterable output section을 이름순으로 정의하지만 section 안 symbol의 garbage collection을 허용합니다.

ITERABLE_SECTION_RAM(struct_type, subalign)

Runtime에 수정하는 read-write data용 iterable output section을 정의합니다. Input은 이름순이며 직접 reference가 없어도 symbol을 image에 유지합니다.

ITERABLE_SECTION_RAM_NUMERIC(struct_type, subalign)

Read-write iterable section을 numeric 순서로 정렬합니다. SECNAME10은 SECNAME2 뒤에 오며 0~99 두 자리까지 처리합니다.

ITERABLE_SECTION_RAM_GC_ALLOWED(struct_type, subalign)

Runtime 수정용 read-write iterable output section을 이름순으로 정의하되 section symbol의 garbage collection을 허용합니다.

TYPE_SECTION_ITERABLE(type, varname, secname, section_postfix)

Generic type용 iterable section element를 정의하는 __in_section()과 Z_DECL_ALIGN() 결합 helper입니다. Section 이름은 .[SECNAME].static.[SECTION_POSTFIX]이며 linker script에서 ITERABLE_SECTION_ROM() 또는 ITERABLE_SECTION_RAM() output을 만들어야 합니다. ROM에 저장하려면 declaration에 const를 붙입니다.

매개변수

type: variable data type
varname: section에 둘 variable 이름
secname: iterable section type 이름
section_postfix: section 이름 postfix

TYPE_SECTION_START(secname)

Generic type iterable section의 start symbol __list_start를 만듭니다.

매개변수

secname: iterable section type 이름

TYPE_SECTION_END(secname)

Generic type iterable section의 end symbol __list_end를 만듭니다.

매개변수

secname: iterable section type 이름

TYPE_SECTION_START_EXTERN(type, secname)

Generic type iterable section start symbol의 extern declaration을 만듭니다. Type과 section 이름이 다를 수 있는 경우도 처리합니다.

매개변수

type: section data type
secname: output section 이름

TYPE_SECTION_END_EXTERN(type, secname)

Generic type iterable section end symbol의 extern declaration을 만듭니다.

매개변수

type: section data type
secname: output section 이름

TYPE_SECTION_FOREACH(type, secname, iterator)

TYPE_SECTION_ITERABLE()로 모은 generic type instance를 순회합니다. Linker가 __list_start와 __list_end를 제공해야 하며 보통 ITERABLE_SECTION_ROM() 또는 ITERABLE_SECTION_RAM()이 만듭니다.

TYPE_SECTION_GET(type, secname, i, dst)

Generic type section의 index i element pointer를 얻습니다. Section 경계 밖 읽기를 막는 보호가 없습니다.

매개변수

type: element type
secname: output section 이름
i: index
dst: [out] element pointer를 쓸 위치

TYPE_SECTION_COUNT(type, secname, dst)

Generic type section의 element 수를 계산합니다.

매개변수

type: element type
secname: output section 이름
dst: [out] 결과를 쓸 위치

STRUCT_SECTION_START(struct_type)

Struct type iterable section의 start symbol을 만듭니다.

매개변수

struct_type: section data type

STRUCT_SECTION_START_EXTERN(struct_type)

Struct iterable section start symbol의 extern declaration을 만듭니다.

매개변수

struct_type: section data type

STRUCT_SECTION_END(struct_type)

Struct type iterable section의 end symbol을 만듭니다.

매개변수

struct_type: section data type

STRUCT_SECTION_END_EXTERN(struct_type)

Struct iterable section end symbol의 extern declaration을 만듭니다.

매개변수

struct_type: section data type

STRUCT_SECTION_ITERABLE_ALTERNATE(secname, struct_type, varname)

특정 data type의 iterable section에 alternate data type element를 넣습니다. 두 data type의 크기와 의미가 반드시 같아야 합니다.

STRUCT_SECTION_ITERABLE_ARRAY_ALTERNATE(secname, struct_type, varname, size)

Iterable section에 alternate data type element 배열을 정의합니다. STRUCT_SECTION_ITERABLE_ALTERNATE의 배열 변형입니다.

STRUCT_SECTION_ITERABLE(struct_type, varname)

Struct iterable section element를 정의하는 __in_section()과 Z_DECL_ALIGN() 결합 helper입니다. Section 이름은 struct type 앞에 underscore를 붙이고 subsection은 static, subsubsection은 variable 이름입니다. ROM에 저장하려면 declaration에 const를 붙입니다.

STRUCT_SECTION_ITERABLE_ARRAY(struct_type, varname, size)

Iterable section에 동일 struct element 배열을 정의합니다.

STRUCT_SECTION_ITERABLE_NAMED(struct_type, name, varname)

Custom name을 가진 iterable section element를 정의하며 name으로 entry 정렬 순서를 조절할 수 있습니다.

STRUCT_SECTION_ITERABLE_NAMED_ALTERNATE(struct_type, secname, name, varname)

Custom section과 custom sort name에 alternate element를 정의합니다.

STRUCT_SECTION_FOREACH_ALTERNATE(secname, struct_type, iterator)

Alternate section의 structure instance를 순회합니다. Linker가 __list_start와 __list_end 경계 symbol을 제공해야 합니다.

STRUCT_SECTION_FOREACH(struct_type, iterator)

STRUCT_SECTION_ITERABLE()로 모은 struct instance를 순회합니다. Linker가 __list_start와 __list_end를 제공해야 합니다.

STRUCT_SECTION_GET(struct_type, i, dst)

Struct section의 index i element pointer를 얻습니다. Section 경계 밖 읽기를 막는 보호가 없습니다.

매개변수

struct_type: struct type
i: index
dst: [out] element pointer를 쓸 위치

STRUCT_SECTION_COUNT(struct_type, dst)

Struct section의 element 수를 계산합니다.

매개변수

struct_type: struct type
dst: [out] 결과를 쓸 위치

Source

출처

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

Iterable Sections

2.7.0 LTS2 · 준비 중

요약·해설

접을 수 있는 영어 원문 전체

한국어 전문 번역

사용법

API 참고

출처