> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs-staging.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AR Osal Shared Memory

> Defines public APIs for shared memory allocation for DSP.

**Header:** `ar_osal/api/ar_osal_shmem.h`

## Structures

### `ar_shmem_proc_info_t`

**Members**

<ParamField path="proc_id" type="uint8_t" />

<ParamField path="proc_type" type="ar_shmem_pd_type_t" />

<ParamField path="is_active" type="bool_t" />

### `ar_shmem_info_t`

Shared memory info structure.

**Members**

<ParamField path="cache_type" type="ar_shmem_cache_type_t">
  in, cache type, cached or uncached memory
</ParamField>

<ParamField path="buf_size" type="size_t">
  in, shared buffer size, should be a minimum of 4K and multiple of 4K only
</ParamField>

<ParamField path="mem_type" type="ar_shmem_memory_type_t">
  out, shmem memory type, virtual or physical for ar\_shmem\_alloc()
</ParamField>

<ParamField path="index_type" type="ar_shmem_buffer_index_type_t">
  out, DSP to operate on buffer offsets or on address pointers.
</ParamField>

<ParamField path="ipa_lsw" type="uint32_t">
  out, smmu mapped ipa lsw, output for ar\_shmem\_alloc()/ar\_shmem\_map()
</ParamField>

<ParamField path="ipa_msw" type="uint32_t">
  out, smmu mapped ipa msw, output for ar\_shmem\_alloc()/ar\_shmem\_map()
</ParamField>

<ParamField path="pa_lsw" type="uint32_t">
  out, physical address lsw, alignment requirements apply, like 4k, start address multiple of 64, output of ar\_shmem\_alloc()
</ParamField>

<ParamField path="pa_msw" type="uint32_t">
  out, physical address msw, alignment requirements apply, like 4k, start address multiple of 64, output of ar\_shmem\_alloc()
</ParamField>

<ParamField path="vaddr" type="void *">
  out, virtual address 64bit/32bit, alignment requirements apply, like 4k, start address multiple of 64, input for ar\_shmem\_alloc()
</ParamField>

<ParamField path="metadata" type="uint64_t">
  out opt, pointer address to metadata structure defined by each platform for ar\_shmem\_alloc()
</ParamField>

<ParamField path="num_sys_id" type="uint8_t">
  in, number of subsystem IDs provided with ar\_shmem\_alloc()/ar\_shmem\_map() call.
</ParamField>

<ParamField path="sys_id" type="ar_shmem_proc_info *">
  in, pointer to array of size num\_sys\_id for sub-system Ids provided in ar\_osal\_sys\_id.h, used to allocate shared memory between the given list of sys\_id provided with ar\_shmem\_alloc()/ar\_shmem\_map() call.
</ParamField>

<ParamField path="platform_info" type="uint32_t">
  in opt, optional field for passing platform specific data to OSAL, this can be used for example to communicate some heap properties provided only for ar\_shmem\_alloc()
</ParamField>

<ParamField path="flags" type="uint32_t">
  in, Bit field for flags.
</ParamField>

### `ar_shmem_hyp_assign_phys_addr_t`

Shared memory physical address and size details for hyp assign.

**Members**

<ParamField path="phys_addr" type="uint64_t">
  64-bit physical address.
</ParamField>

<ParamField path="size" type="size_t">
  size in bytes for the buffer pointed by phys\_addr
</ParamField>

### `ar_shmem_hyp_assign_dest_sys_info_t`

Destination sub system id details and permission required for hyp assign.

**Members**

<ParamField path="dest_sys_id" type="uint64_t">
  destination sub system id, refer to ar\_osal\_sys\_id.h
</ParamField>

<ParamField path="dest_perm" type="ar_shmem_hyp_assign_dest_sys_perm">
  destination permissions
</ParamField>

### `ar_shmem_hyp_assign_phys_info_t`

Hyp assign physical memory info structure.

**Members**

<ParamField path="phys_addr_list" type="ar_shmem_hyp_assign_phys_addr *">
  list of hyp\_assign\_phys\_addr structures.
</ParamField>

<ParamField path="phys_addr_list_size" type="uint32_t">
  number of phys\_addr\_list entries.
</ParamField>

<ParamField path="src_sys_list" type="uint64_t *">
  source sub system Id list, refer to ar\_osal\_sys\_id.h for sys ids.
</ParamField>

<ParamField path="src_sys_list_size" type="uint32_t">
  number of src\_sys\_list entries.
</ParamField>

<ParamField path="dest_sys_list" type="ar_shmem_hyp_assign_dest_sys_info *">
  destination sys list hyp\_assign\_dest\_sys\_info.
</ParamField>

<ParamField path="dest_sys_list_size" type="uint32_t">
  number of destination sys list/dest\_sys\_list entires.
</ParamField>

<ParamField path="metadata" type="uint64_t">
  in opt, pointer address to metadata structure defined by platform during ar\_shmem\_alloc() call.
</ParamField>

## Functions

### `ar_shmem_init`

Initialize the shared memory interface (V1 API).

This function initializes the shared memory interface using the default configuration. It performs the legacy initialization flow.

```cpp theme={null}
int32_t ar_shmem_init()
```

**Returns**

0  Success Nonzero  Failure

### `ar_shmem_init_v2`

Initialize the shared memory interface using a list of processor domains (V2 API).

This V2 API selects the appropriate shared memory implementation based on the provided list of processor domain IDs.

Passing num\_master\_procs = 0 results in behavior equivalent to the V1 API (ar\_shmem\_init), allowing a smooth transition from V1 to V2.

```cpp theme={null}
int32_t ar_shmem_init_v2(uint32_t num_master_procs, uint32_t *master_procs)
```

**Parameters**

<ParamField path="num_master_procs" type="uint32_t">
  Number of processor domain IDs.
</ParamField>

<ParamField path="master_procs" type="uint32_t *">
  Pointer to an array of processor domain IDs.
</ParamField>

**Returns**

0  Success Nonzero  Failure

### `ar_shmem_alloc`

Allocates shared memory.

Only non cached memory allocation supported. Size if multiple of 4KB and the returned is aligned to 4KB boundary. Buffer start address should be atleast 64bit multiple aligned.

```cpp theme={null}
int32_t ar_shmem_alloc(ar_shmem_info *info)
```

**Parameters**

<ParamField path="[in_out]" type="">
  info: pointer to ar\_shmem\_info.
</ParamField>

**Returns**

0  Success Nonzero  Failure

### `ar_shmem_free`

Frees shared memory.

```cpp theme={null}
int32_t ar_shmem_free(ar_shmem_info *info)
```

**Parameters**

<ParamField path="info" type="ar_shmem_info *">
  pointer to ar\_shmem\_info.
</ParamField>

**Returns**

0  Success Nonzero  Failure

### `ar_shmem_map`

Helps map memory with SMMU an already allocated shared memory for a give sub system.

Size should be multiple of 4KB boundary. Buffer start address should be 64bit aligned.

```cpp theme={null}
int32_t ar_shmem_map(ar_shmem_info *info)
```

**Parameters**

<ParamField path="[in_out]" type="">
  info: pointer to ar\_shmem\_info. required input parameters in ar\_shmem\_info ar\_shmem\_info\_t.cache\_type ar\_shmem\_info\_t.buf\_size ar\_shmem\_info\_t.mem\_type ar\_shmem\_info\_t.pa\_lsw ar\_shmem\_info\_t.pa\_msw ar\_shmem\_info\_t.num\_sys\_id ar\_shmem\_info\_t.sys\_id required output parameters in ar\_shmem\_info ar\_shmem\_info\_t.ipa\_lsw ar\_shmem\_info\_t.ipa\_msw
</ParamField>

**Returns**

0  Success Nonzero  Failure

### `ar_shmem_unmap`

Helps unmap the shared memory allocated externally with SMMU.

```cpp theme={null}
int32_t ar_shmem_unmap(ar_shmem_info *info)
```

**Parameters**

<ParamField path="info" type="ar_shmem_info *">
  pointer to ar\_shmem\_info. required input parameters in ar\_shmem\_info ar\_shmem\_info\_t.cache\_type ar\_shmem\_info\_t.buf\_size ar\_shmem\_info\_t.mem\_type ar\_shmem\_info\_t.pa\_lsw ar\_shmem\_info\_t.pa\_msw ar\_shmem\_info\_t.num\_sys\_id ar\_shmem\_info\_t.sys\_id
</ParamField>

**Returns**

0  Success Nonzero  Failure

### `ar_shmem_hyp_assign_phys`

Helps to hyp assign physical memory between source and destination sub systems.

```cpp theme={null}
int32_t ar_shmem_hyp_assign_phys(ar_shmem_hyp_assign_phys_info *info)
```

**Parameters**

<ParamField path="info" type="ar_shmem_hyp_assign_phys_info *">
  pointer to ar\_shmem\_hyp\_assign\_phys\_info.
</ParamField>

**Returns**

0  Success Nonzero  Failure

### `ar_shmem_get_uid`

ar\_shmem\_get\_uid.

Get associated unique identifier(UID) for the shared memory pointed by alloc\_handle, platform which doesn\`t support UID should return alloc\_handle as UID with expectation of alloc\_handle being unique.

```cpp theme={null}
int32_t ar_shmem_get_uid(uint64_t alloc_handle, uint64_t *uid)
```

**Parameters**

<ParamField path="alloc_handle" type="uint64_t">
  handle for the shared memory.
</ParamField>

<ParamField path="uid" type="uint64_t *">
  unique identifier to the shmem.
</ParamField>

**Returns**

0  Success Nonzero  Failure

### `ar_shmem_deinit`

ar\_shmem\_deinit.

```cpp theme={null}
int32_t ar_shmem_deinit(void)
```

**Returns**

0  Success Nonzero  Failure

## Type Definitions

### `ar_shmem_memory_type_t`

enum for shmem memory type

```cpp theme={null}
typedef enum ar_shmem_memory_type ar_shmem_memory_type_t
```

### `ar_shmem_cache_type_t`

enum for shmem cache type

```cpp theme={null}
typedef enum ar_shmem_cache_type ar_shmem_cache_type_t
```

### `ar_shmem_buffer_index_type_t`

enum for shmem offset/address buffer index type

```cpp theme={null}
typedef enum ar_shmem_buffer_index_type ar_shmem_buffer_index_type_t
```

### `ar_shmem_pd_type_t`

Bits to indicate if hardware accelerator is enabled/disabled.

```cpp theme={null}
typedef enum ar_shmem_pd_type ar_shmem_pd_type_t
```

### `ar_shmem_proc_info`

```cpp theme={null}
typedef struct ar_shmem_proc_info_t ar_shmem_proc_info
```

### `ar_shmem_info`

Shared memory info structure.

```cpp theme={null}
typedef struct ar_shmem_info_t ar_shmem_info
```

### `ar_shmem_hyp_assign_phys_addr`

Shared memory physical address and size details for hyp assign.

```cpp theme={null}
typedef struct ar_shmem_hyp_assign_phys_addr_t ar_shmem_hyp_assign_phys_addr
```

### `ar_shmem_hyp_assign_dest_sys_perm`

Destination sub system permission bit mask types supported.

```cpp theme={null}
typedef enum ar_shmem_hyp_assign_dest_sys_perm_t ar_shmem_hyp_assign_dest_sys_perm
```

### `ar_shmem_hyp_assign_dest_sys_info`

Destination sub system id details and permission required for hyp assign.

```cpp theme={null}
typedef struct ar_shmem_hyp_assign_dest_sys_info_t ar_shmem_hyp_assign_dest_sys_info
```

### `ar_shmem_hyp_assign_phys_info`

Hyp assign physical memory info structure.

```cpp theme={null}
typedef struct ar_shmem_hyp_assign_phys_info_t ar_shmem_hyp_assign_phys_info
```

## Enumerations

### `ar_shmem_memory_type`

enum for shmem memory type

#### Values

| Name                       | Value | Description                          |
| -------------------------- | ----- | ------------------------------------ |
| `AR_SHMEM_PHYSICAL_MEMORY` | = 0   | 0 Shared physical memory allocation. |
| `AR_SHMEM_VIRTUAL_MEMORY`  | = 1   | 1 Shared virtual memory allocation   |

### `ar_shmem_cache_type`

enum for shmem cache type

#### Values

| Name                | Value | Description |
| ------------------- | ----- | ----------- |
| `AR_SHMEM_CACHED`   | = 0   | 0 cached.   |
| `AR_SHMEM_UNCACHED` | = 1   | 1 uncached. |

### `ar_shmem_buffer_index_type`

enum for shmem offset/address buffer index type

#### Values

| Name                      | Value | Description                                         |
| ------------------------- | ----- | --------------------------------------------------- |
| `AR_SHMEM_BUFFER_ADDRESS` | = 0   | 0 use physical or virtual addresses.                |
| `AR_SHMEM_BUFFER_OFFSET`  | = 1   | 1 use offsets, the offset is from the base address. |

### `ar_shmem_pd_type`

#### Values

| Name         | Value | Description |
| ------------ | ----- | ----------- |
| `STATIC_PD`  | = 1   |             |
| `DYNAMIC_PD` | = 2   |             |

### `ar_shmem_hyp_assign_dest_sys_perm_t`

Destination sub system permission bit mask types supported.

#### Values

| Name                            | Value                                                                                    | Description                         |
| ------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------- |
| `DEST_SYS_PERM_INVALID`         | = 0x0                                                                                    | Invalid permission bit mask.        |
| `DEST_SYS_PERM_EXEC`            | = 0x1                                                                                    | Execute permission bit mask.        |
| `DEST_SYS_PERM_WRITE_ONLY`      | = 0x2                                                                                    | Write only permission bit mask.     |
| `DEST_SYS_PERM_EXEC_WRITE`      | = (DEST\_SYS\_PERM\_EXEC \| DEST\_SYS\_PERM\_WRITE\_ONLY)                                | Execute and Write permission.       |
| `DEST_SYS_PERM_READ_ONLY`       | = 0x4                                                                                    | Read only permission bit mask.      |
| `DEST_SYS_PERM_EXEC_READ`       | = (DEST\_SYS\_PERM\_EXEC \| DEST\_SYS\_PERM\_READ\_ONLY)                                 | Execute and Read permission.        |
| `DEST_SYS_PERM_WRITE_READ`      | = (DEST\_SYS\_PERM\_WRITE\_ONLY \| DEST\_SYS\_PERM\_READ\_ONLY)                          | Write and Read permission.          |
| `DEST_SYS_PERM_EXEC_WRITE_READ` | = (DEST\_SYS\_PERM\_EXEC \| DEST\_SYS\_PERM\_WRITE\_ONLY \| DEST\_SYS\_PERM\_READ\_ONLY) | Execute, Write and Read permission. |

## Macros

### `AR_SHMEM_HW_ACCELERATOR_ENABLED`

```c theme={null}
#define AR_SHMEM_HW_ACCELERATOR_ENABLED 0x1
```

### `AR_SHMEM_HW_ACCELERATOR_DISABLED`

Bit mask for hardware accelerator flag.

```c theme={null}
#define AR_SHMEM_HW_ACCELERATOR_DISABLED 0x0
```

### `AR_SHMEM_BIT_MASK_HW_ACCELERATOR_FLAG`

Shift amount for hardware accelerator setup flag.

```c theme={null}
#define AR_SHMEM_BIT_MASK_HW_ACCELERATOR_FLAG 0x1
```

### `AR_SHMEM_SHIFT_HW_ACCELERATOR_FLAG`

```c theme={null}
#define AR_SHMEM_SHIFT_HW_ACCELERATOR_FLAG 0x0
```