Math Engine Reference: Capabilities

문서 탐색

개요

Compiled profile과 runtime mode 지원 범위를 조회하는 ABI를 선언한다.

실행 원본: include/math_engine/math_engine_capabilities.h
분류: 진입점·ABI·공통 계약

공개 API

Header 사용 시작

이 module의 public declaration을 사용하려면 installed SDK의 다음 header를 include한다.

#include <math_engine/math_engine_capabilities.h>

Type과 callback

`math_engine_capability_profile_t`

배포 artifact의 capability profile이다.

typedef enum math_engine_capability_profile {
    MATH_ENGINE_CAPABILITY_PROFILE_INVALID = 0, /**< 초기화되지 않았거나 알려지지 않은 profile sentinel이다. */
    MATH_ENGINE_CAPABILITY_PROFILE_FULL = 1, /**< 모든 desktop mode와 선택적 CAS/CAD backend를 수용하는 최대 profile이다. */
    MATH_ENGINE_CAPABILITY_PROFILE_COMPACT = 2, /**< 핵심 binary·fixed 기능을 유지하며 heavyweight backend를 줄인 profile이다. */
    MATH_ENGINE_CAPABILITY_PROFILE_MINIMAL = 3 /**< 제한된 resident module과 caller workspace를 전제로 하는 최소 profile이다. */
} math_engine_capability_profile_t;

math_engine_capability_profile_t.MATH_ENGINE_CAPABILITY_PROFILE_INVALID
초기화되지 않았거나 알려지지 않은 profile sentinel이다.
```
MATH_ENGINE_CAPABILITY_PROFILE_INVALID = 0,
```
math_engine_capability_profile_t.MATH_ENGINE_CAPABILITY_PROFILE_FULL
모든 desktop mode와 선택적 CAS/CAD backend를 수용하는 최대 profile이다.
```
MATH_ENGINE_CAPABILITY_PROFILE_FULL = 1,
```
math_engine_capability_profile_t.MATH_ENGINE_CAPABILITY_PROFILE_COMPACT
핵심 binary·fixed 기능을 유지하며 heavyweight backend를 줄인 profile이다.
```
MATH_ENGINE_CAPABILITY_PROFILE_COMPACT = 2,
```
math_engine_capability_profile_t.MATH_ENGINE_CAPABILITY_PROFILE_MINIMAL
제한된 resident module과 caller workspace를 전제로 하는 최소 profile이다.
```
MATH_ENGINE_CAPABILITY_PROFILE_MINIMAL = 3,
```

`math_engine_capability_descriptor_t`

Versioned compiled capability descriptor다. Precision은 significand bit 수고, fixed scale 범위는 inclusive decimal scale이다. 0인 feature field는 미지원이다.

typedef struct math_engine_capability_descriptor {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_capability_descriptor_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_CAPABILITY_DESCRIPTOR_VERSION_1=인 descriptor ABI version이다. */
    uint32_t profile; /**< 이 manifest가 대응하는 =math_engine_capability_profile_t= 값이다. */
    uint32_t flags; /**< Version 1 descriptor flag bitset이다. 정의되지 않은 bit는 0이어야 한다. */
    uint64_t capability_bits; /**< Scalar/backend와 runtime =MATH_ENGINE_CAPABILITY_*= bit의 합집합이다. */
    uint64_t supported_mode_bits; /**< 실행 가능한 =MATH_ENGINE_MODE_MASK_*= bit의 합집합이다. */
    uint32_t max_binary_precision_bits; /**< 지원 binary backend의 최대 significand precision(bit)이다. 미지원이면 0이다. */
    uint32_t max_arbitrary_precision_bits; /**< Arbitrary backend가 허용하는 최대 significand precision(bit)이다. 미지원이면 0이다. */
    int32_t fixed_scale_min; /**< 지원되는 decimal-fixed scale의 inclusive 최솟값이다. 미지원이면 scale 범위 계약은 비활성이다. */
    int32_t fixed_scale_max; /**< 지원되는 decimal-fixed scale의 inclusive 최댓값이며 =fixed_scale_min= 이상이다. */
    uint32_t heap_allowed; /**< 1이면 heap capability가 있고 0이면 runtime heap 사용이 금지된다. */
    uint32_t thread_count_limit; /**< 동시에 사용할 수 있는 worker thread ceiling이다. Threading 미지원이면 1이다. */
    uint32_t gpu_available; /**< 1이면 GPU capability bit와 일치하는 실행 path가 있고 0이면 없다. */
    uint32_t cas_available; /**< 1이면 CAS capability bit와 일치하는 component가 있고 0이면 없다. */
    uint32_t cad_available; /**< 1이면 CAD capability bit와 일치하는 component가 있고 0이면 없다. */
    uint32_t embedded_restricted; /**< 1이면 embedded-restricted capability와 resource ceiling이 적용된다. */
    uint64_t reserved; /**< 향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다. */
} math_engine_capability_descriptor_t;

math_engine_capability_descriptor_t.struct_size
Caller가 sizeof(math_engine_capability_descriptor_t) 로 설정하는 byte 크기다.
```
uint32_t struct_size;
```
math_engine_capability_descriptor_t.struct_version
MATH_ENGINE_CAPABILITY_DESCRIPTOR_VERSION_1 인 descriptor ABI version이다.
```
uint32_t struct_version;
```
math_engine_capability_descriptor_t.profile
이 manifest가 대응하는 math_engine_capability_profile_t 값이다.
```
uint32_t profile;
```
math_engine_capability_descriptor_t.flags
Version 1 descriptor flag bitset이다. 정의되지 않은 bit는 0이어야 한다.
```
uint32_t flags;
```
math_engine_capability_descriptor_t.capability_bits
Scalar/backend와 runtime MATH_ENGINE_CAPABILITY_* bit의 합집합이다.
```
uint64_t capability_bits;
```
math_engine_capability_descriptor_t.supported_mode_bits
실행 가능한 MATH_ENGINE_MODE_MASK_* bit의 합집합이다.
```
uint64_t supported_mode_bits;
```
math_engine_capability_descriptor_t.max_binary_precision_bits
지원 binary backend의 최대 significand precision(bit)이다. 미지원이면 0이다.
```
uint32_t max_binary_precision_bits;
```
math_engine_capability_descriptor_t.max_arbitrary_precision_bits
Arbitrary backend가 허용하는 최대 significand precision(bit)이다. 미지원이면 0이다.
```
uint32_t max_arbitrary_precision_bits;
```
math_engine_capability_descriptor_t.fixed_scale_min
지원되는 decimal-fixed scale의 inclusive 최솟값이다. 미지원이면 scale 범위 계약은 비활성이다.
```
int32_t fixed_scale_min;
```
math_engine_capability_descriptor_t.fixed_scale_max
지원되는 decimal-fixed scale의 inclusive 최댓값이며 fixed_scale_min 이상이다.
```
int32_t fixed_scale_max;
```
math_engine_capability_descriptor_t.heap_allowed
1이면 heap capability가 있고 0이면 runtime heap 사용이 금지된다.
```
uint32_t heap_allowed;
```
math_engine_capability_descriptor_t.thread_count_limit
동시에 사용할 수 있는 worker thread ceiling이다. Threading 미지원이면 1이다.
```
uint32_t thread_count_limit;
```
math_engine_capability_descriptor_t.gpu_available
1이면 GPU capability bit와 일치하는 실행 path가 있고 0이면 없다.
```
uint32_t gpu_available;
```
math_engine_capability_descriptor_t.cas_available
1이면 CAS capability bit와 일치하는 component가 있고 0이면 없다.
```
uint32_t cas_available;
```
math_engine_capability_descriptor_t.cad_available
1이면 CAD capability bit와 일치하는 component가 있고 0이면 없다.
```
uint32_t cad_available;
```
math_engine_capability_descriptor_t.embedded_restricted
1이면 embedded-restricted capability와 resource ceiling이 적용된다.
```
uint32_t embedded_restricted;
```
math_engine_capability_descriptor_t.reserved
향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다.
```
uint64_t reserved;
```

Macro와 constant

`MATH_ENGINE_CAPABILITY_CAD`

Artifact에 CAD backend/component가 포함됐음을 나타내는 bit다.

#define MATH_ENGINE_CAPABILITY_CAD (UINT64_C(1) << 9u)

`MATH_ENGINE_CAPABILITY_CALLER_WORKSPACE`

Heap 없이 caller-provided scratch workspace를 받는 kernel이 있음을 나타내는 bit다.

#define MATH_ENGINE_CAPABILITY_CALLER_WORKSPACE (UINT64_C(1) << 4u)

`MATH_ENGINE_CAPABILITY_CAS`

Artifact에 computer-algebra component가 포함됐음을 나타내는 bit다.

#define MATH_ENGINE_CAPABILITY_CAS (UINT64_C(1) << 8u)

`MATH_ENGINE_CAPABILITY_DESCRIPTOR_VERSION_1`

math_engine_capability_descriptor_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_CAPABILITY_DESCRIPTOR_VERSION_1 1u

`MATH_ENGINE_CAPABILITY_EMBEDDED_RESTRICTED`

Artifact가 embedded resource·module 제한 profile임을 나타내는 bit다.

#define MATH_ENGINE_CAPABILITY_EMBEDDED_RESTRICTED (UINT64_C(1) << 10u)

`MATH_ENGINE_CAPABILITY_GPU`

Artifact에 지원되는 GPU execution path가 포함됐음을 나타내는 bit다.

#define MATH_ENGINE_CAPABILITY_GPU (UINT64_C(1) << 7u)

`MATH_ENGINE_CAPABILITY_HEAP`

Artifact가 계약된 연산에서 heap allocation을 사용할 수 있음을 나타내는 bit다.

#define MATH_ENGINE_CAPABILITY_HEAP (UINT64_C(1) << 5u)

`MATH_ENGINE_CAPABILITY_THREADING`

Artifact가 둘 이상의 worker thread 실행을 지원함을 나타내는 bit다.

#define MATH_ENGINE_CAPABILITY_THREADING (UINT64_C(1) << 6u)

`MATH_ENGINE_DESKTOP_THREAD_COUNT_LIMIT`

Desktop descriptor가 광고할 수 있는 worker thread 수의 안정된 상한이다.

#define MATH_ENGINE_DESKTOP_THREAD_COUNT_LIMIT UINT32_C(64)

`MATH_ENGINE_MODE_MASK_FINANCE_FIXED`

Descriptor가 FINANCE_FIXED mode를 지원함을 나타내는 stable mode-mask bit다.

#define MATH_ENGINE_MODE_MASK_FINANCE_FIXED (UINT64_C(1) << 2u)

`MATH_ENGINE_MODE_MASK_FULL`

Descriptor가 FULL hybrid mode를 지원함을 나타내는 stable mode-mask bit다.

#define MATH_ENGINE_MODE_MASK_FULL (UINT64_C(1) << 3u)

`MATH_ENGINE_MODE_MASK_GAME_FAST`

Descriptor가 GAME_FAST mode를 지원함을 나타내는 stable mode-mask bit다.

#define MATH_ENGINE_MODE_MASK_GAME_FAST (UINT64_C(1) << 0u)

`MATH_ENGINE_MODE_MASK_PC_PRECISION`

Descriptor가 PC_PRECISION mode를 지원함을 나타내는 stable mode-mask bit다.

#define MATH_ENGINE_MODE_MASK_PC_PRECISION (UINT64_C(1) << 1u)

`MATH_ENGINE_MODE_MASK_UNLIMITED`

@deprecated Source compatibility alias. Use MATH_ENGINE_MODE_MASK_FULL.

#define MATH_ENGINE_MODE_MASK_UNLIMITED MATH_ENGINE_MODE_MASK_FULL

Function

`math_engine_capability_profile_describe`

Full/compact/minimal profile의 canonical manifest를 조회한다.

매개변수 profile: 설명할 canonical capability profile.
매개변수 out_descriptor: size/version을 설정한 caller-owned output.
반환: 성공 시 OK. 잘못된 profile, size/version 또는 NULL에서는 output을 보존한다.

결과는 process 상태와 무관하며 같은 profile에 항상 같은 값을 반환한다.

Math Engine ownership: out_descriptor=caller
Math Engine nullable: out_descriptor=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_capability_profile_describe(
    math_engine_capability_profile_t profile,
    math_engine_capability_descriptor_t* out_descriptor);

`math_engine_capabilities_get`

현재 linked library의 compiled capability manifest를 조회한다.

매개변수 out_descriptor: size/version을 설정한 caller-owned output.
반환: 성공 시 OK. 현재 artifact가 full인지 embedded인지에 따른 immutable manifest를

반환하며 ABI 오류에서는 output을 보존한다.

Math Engine ownership: out_descriptor=caller
Math Engine nullable: out_descriptor=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_capabilities_get(
    math_engine_capability_descriptor_t* out_descriptor);

`math_engine_capabilities_validate`

외부에서 받은 descriptor의 size/version과 내부 조합을 검증한다.

매개변수 descriptor: 검증할 immutable capability descriptor.
반환: 유효하면 OK. 알 수 없는 bit, 모순된 boolean/precision/scale/mode 조합과

잘못된 ABI를 거부하며 입력을 변경하지 않는다.

Math Engine ownership: descriptor=borrowed
Math Engine nullable: descriptor=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_capabilities_validate(
    const math_engine_capability_descriptor_t* descriptor);

`math_engine_capabilities_support_mode`

Descriptor가 mode를 실행할 수 있는지 symbol 추측 없이 조회한다.

매개변수 descriptor: 검증할 immutable capability descriptor.
매개변수 mode: 지원 여부를 조회할 mode.
매개변수 out_supported: 성공 시 지원하면 1, 아니면 0을 받는 caller output.
반환: 조회가 유효하면 OK. Descriptor 또는 mode 오류에서는 out_supported 를 보존한다.
Math Engine ownership: descriptor=borrowed out_supported=caller
Math Engine nullable: descriptor=false out_supported=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_capabilities_support_mode(
    const math_engine_capability_descriptor_t* descriptor,
    math_engine_mode_t mode,
    uint32_t* out_supported);

Math Engine Reference: Capabilities

문서 탐색

개요

관련 public header

공개 API

Header 사용 시작

Type과 callback

math_engine_capability_profile_t

math_engine_capability_descriptor_t

Macro와 constant

MATH_ENGINE_CAPABILITY_CAD

MATH_ENGINE_CAPABILITY_CALLER_WORKSPACE

MATH_ENGINE_CAPABILITY_CAS

MATH_ENGINE_CAPABILITY_DESCRIPTOR_VERSION_1

MATH_ENGINE_CAPABILITY_EMBEDDED_RESTRICTED

MATH_ENGINE_CAPABILITY_GPU

MATH_ENGINE_CAPABILITY_HEAP

MATH_ENGINE_CAPABILITY_THREADING

MATH_ENGINE_DESKTOP_THREAD_COUNT_LIMIT

MATH_ENGINE_MODE_MASK_FINANCE_FIXED

MATH_ENGINE_MODE_MASK_FULL

MATH_ENGINE_MODE_MASK_GAME_FAST

MATH_ENGINE_MODE_MASK_PC_PRECISION

MATH_ENGINE_MODE_MASK_UNLIMITED