MTB IPC Library

| MTB IPC Library

Data Structures | Macros | Typedefs | Enumerations
IPC
IPC (Inter-Processor Communication)

## General Description

Implementation specific interface for using the IPC library.

## Data Structures
struct | _mtb_ipc_event_callback_data_t
| Event callback data object. More...
struct | _mtb_ipc_queue_process_info_t
| IPC notification info. More...
struct | _mtb_ipc_core_irq_data
| IRQ channel storage struct for holding data relevant for all cores to know. More...
struct | mtb_ipc_semaphore_data_t
| IPC Semaphore Data User should allocate but not modify anything in this struct. More...
struct | mtb_ipc_semaphore_t
| IPC Semaphore Handle User should allocate but not modify anything in this struct. More...
struct | mtb_ipc_mbox_data_t
| IPC mailbox data element User should allocate but not modify anything in this struct. More...
struct | mtb_ipc_mbox_t
| IPC mailbox handle element User should allocate but not modify anything in this struct. More...
struct | mtb_ipc_queue_data_t
| IPC queue data element User should allocate but not modify anything in this struct. More...
struct | mtb_ipc_queue_t
| IPC Queue handle object User should allocate but not modify anything in this struct. More...
struct | _mtb_ipc_rtos_semaphore_data
| RTOS/IPC semaphore linkage object to store info and block all semaphores trying to take that same IPC semaphore on same RTOS semaphore If active_count is 0, sema_idk will be set back to _MTB_IPC_UNUSED_SEMAPHORE. More...
struct | mtb_ipc_shared_t
| IPC Shared Memory Object. More...
struct | mtb_ipc_t
| IPC Instance object This is the per-core obj for tracking shared memory and initialized queues/semaphores. More...

## Macros
#define | MTB_IPC_IRQ_USER (0UL)
| Define the first available IRQ for use in MTB IPC.
#define | MTB_IPC_SEMAPHORE_DATA_ALLOC(semaphore_data) do { CY_SECTION_SHAREDMEM static mtb_ipc_semaphore_data_t _mtb_ipc_semaphore_data _MTB_IPC_DATA_ALIGN; semaphore_data = &_mtb_ipc_semaphore_data; } while (0)
| Macro for semaphore data shared memory allocation. More...
#define | MTB_IPC_MBOX_DATA_ALLOC(mailbox_data) do { CY_SECTION_SHAREDMEM static mtb_ipc_mbox_data_t _mtb_ipc_mailbox_data _MTB_IPC_DATA_ALIGN; mailbox_data = &_mtb_ipc_mailbox_data; } while (0)
| Macro for mailbox data shared memory allocation. More...
#define | MTB_IPC_QUEUE_POOL_ALLOC(queue_pool, NUM_ITEMS, ITEMSIZE) do { CY_SECTION_SHAREDMEM static uint8_t _mtb_ipc_queue_pool[ITEMSIZE * NUM_ITEMS] _MTB_IPC_DATA_ALIGN; queue_pool = (void*)&_mtb_ipc_queue_pool; } while (0)
| Macro for Queue pool shared memory allocation. More...
#define | MTB_IPC_QUEUE_DATA_ALLOC(queue_data) do { CY_SECTION_SHAREDMEM static mtb_ipc_queue_data_t _mtb_ipc_queue_data _MTB_IPC_DATA_ALIGN; queue_data = &_mtb_ipc_queue_data; } while (0)
| Macro for Queue data shared memory allocation. More...
#define | MTB_IPC_SHARED_DATA_ALLOC(shared) do { CY_SECTION_SHAREDMEM static mtb_ipc_shared_t _mtb_ipc_shared_data _MTB_IPC_DATA_ALIGN; shared = &_mtb_ipc_shared_data; } while (0)
| Macro for Shared data region shared memory allocation. More...
#define | MTB_IPC_POLLING_INTERVAL_uS (1000u)
| Polling interval, that will be used in blocking mtb_ipc_* functions.
#define | MTB_IPC_RTOS_SEMA_NUM (10u)
| Number of RTOS semaphores that will be allocated and used by driver in RTOS environment (CY_RTOS_AWARE or COMPONENT_RTOS_AWARE should be defined). More...
#define | MTB_IPC_SEMAPHORE_WAIT_MASK (0xFFUL)
| Define a mask for signaling on NON-RTOS cores that a semaphore was given. More...
#define | MTB_IPC_MAX_MBOXES (16UL)
| Maximum number of mailboxes. More...
#define | _MTB_IPC_MAX_PROCESSES_PER_QUEUE (2UL)
| The maximum number of Processes per Queue.
#define | _MTB_IPC_SEMA_COUNT (128u)
| Number of semaphores, that can be used.
#define | MTB_IPC_USER_SEMA_COUNT (_MTB_IPC_SEMA_COUNT)
| External variable of available semaphores.
#define | _MTB_IPC_UNUSED_SEMAPHORE (0xFFFFUL)
| Indicate an unused semaphore that can be allocated.

## Typedefs
typedef mtb_ipc_mbox_t | mtb_ipc_mbox_sender_t
| IPC mailbox sender handle We provide distinct type names to distinguish which role can call which functions. More...
typedef mtb_ipc_mbox_t | mtb_ipc_mbox_receiver_t
| IPC mailbox receiver handle We provide distinct type names to distinguish which role can call which functions. More...

## Enumerations
enum | mtb_ipc_channel_t { MTB_IPC_CHAN_0 = (_MTB_IPC_CHAN_USER) }
| Number of IPC Channels available to Applications. More...

## Data Structure Documentation

## ◆ _mtb_ipc_event_callback_data_t

struct _mtb_ipc_event_callback_data_t

Data Fields
cy_israddress | callback |
void * | callback_arg |

## ◆ _mtb_ipc_queue_process_info_t

struct _mtb_ipc_queue_process_info_t

Data Fields
uint32_t | mask | Process-specific notification mask for this Queue.
uint32_t | flags | Process-specific active notification flags for this Queue.

## ◆ _mtb_ipc_core_irq_data

struct _mtb_ipc_core_irq_data

Data Fields
uint32_t | sema_irq | Semaphore IRQ for this core.
uint32_t | queue_irq | Queue IRQ for this core.

## ◆ mtb_ipc_semaphore_data_t

struct mtb_ipc_semaphore_data_t

Data Fields
bool | sema_preemptable | if true, allow preemption
uint32_t | sema_number | semaphore number in IPC system
struct mtb_ipc_semaphore_data_s * | next_sema | Next Semaphore in linked list.

## ◆ mtb_ipc_semaphore_t

struct mtb_ipc_semaphore_t

Data Fields
mtb_ipc_semaphore_data_t * | sema_obj | Pointer to data in shared memory for this semaphore.
struct mtb_ipc_t * | instance | Pointer to the IPC instance.

## ◆ mtb_ipc_mbox_data_t

struct mtb_ipc_mbox_data_t

Data Fields
uint32_t | mbox_idx | from 0-MTB_IPC_MAX_MBOXES
void * | payload | Payload address that will be protected by mailbox.
mtb_ipc_semaphore_data_t | sema_read | The semaphore for protecting read ops.
mtb_ipc_semaphore_data_t | sema_write | The semaphore for protecting write ops.
uint8_t | core_id_sender | Core ID of the sender.
uint8_t | core_id_receiver | Core ID of the receiver.

## ◆ mtb_ipc_mbox_t

struct mtb_ipc_mbox_t

Data Fields
mtb_ipc_mbox_data_t * | mbox_obj | Pointer to mailbox shared data.
_mtb_ipc_event_callback_data_t | callback_data | Pointer to callback data on this core.
mtb_ipc_semaphore_t | sema_read_handle | Handle for the read semaphore.
mtb_ipc_semaphore_t | sema_write_handle | Handle for write semaphore.
struct mtb_ipc_t * | instance | Pointer to the IPC instance.

## ◆ mtb_ipc_queue_data_t

struct mtb_ipc_queue_data_t

Data Fields
uint32_t | channel_num | IPC channel number (e.g. MTB_IPC_CHAN_0) Please refer to implementation specific documentation for number of available IPC channels for particular device.
uint32_t | queue_num | Queue number, which must be unique for each queue in scope of one IPC channel.
uint32_t | max_num_items | Maximum number of items (packets) allowed in the queue.
uint32_t | item_size | Size of each item (packet) in the Queue.
void * | queue_pool | Pointer to the queue packets in shared memory. This memory will be cleared by IPC library Queue Initialization. Packet list is an array of packets of max_num_items. It is used as a circular array, first_item is an index to first item stored.
uint32_t | curr_items | Current number of items (packets) in the queue. Set to 0x00.
uint32_t | first_item | Index of the first item in the queue array, INVALID if curr_items is 0x00.
mtb_ipc_semaphore_data_t | queue_semaphore | IPC Semaphore - covers all items in the queue EXCEPT for notifications, which use the channel of the queue's lock.
_mtb_ipc_queue_process_info_t | notifications[_MTB_IPC_MAX_PROCESSES_PER_QUEUE] | Notification structure per Process. Changed when user calls mtb_ipc_queue_enable_event and mtb_ipc_queue_register_callback. Modified by IPC library during execution (not expected to be modified by user directly).
struct mtb_ipc_queue_data_t * | next | Linked List is used to avoid excessive memory use. These are arranged per channel in the shared struct. Pointer to next queue data element in per-channel linked-list

## ◆ mtb_ipc_queue_t

struct mtb_ipc_queue_t

Data Fields
_mtb_ipc_event_callback_data_t | callback_data | Pointer to related callback data for this queue.
mtb_ipc_queue_data_t * | queue_obj | Pointer to the queue data for this handle.
mtb_ipc_semaphore_t | semaphore_handle | IPC Semaphore - covers all items in the queue EXCEPT for notifications, which use the channel lock.
struct mtb_ipc_queue_t * | next | Pointer to next node in linked list.
struct mtb_ipc_t * | instance | Pointer to the IPC instance.
uint32_t | events_fired | Events fired to compare against events being waited for.
uint32_t | events_enabled | Process-specific notification mask for this Queue.
uint8_t | pending_reads | # of pending reads
uint8_t | pending_writes | # of pending writes
cy_event_t | queue_rtos_event | RTOS event to sleep while queue is empty/full.
uint32_t | rtos_event_waiting_count | Counter of how many threads are waiting on RTOS events.

## ◆ _mtb_ipc_rtos_semaphore_data

struct _mtb_ipc_rtos_semaphore_data

Data Fields
uint32_t | active_count | Counter for threads allocated to this semaphore.
uint32_t | sema_idx | Index of the IPC semaphore linked to this RTOS semaphore.

## ◆ mtb_ipc_shared_t

struct mtb_ipc_shared_t

Data Fields
mtb_ipc_semaphore_data_t | ipc_driver_semaphore | Local data for the IPC library Semaphore for changing any IPC library variables.
mtb_ipc_semaphore_data_t * | ipc_semaphore_list | IPC library Semaphore linked list for lookup of already initialized semaphores.
mtb_ipc_queue_data_t * | ipc_queue_array[MTB_IPC_USR_CHANNELS] | List of initialized array of IPC library Queue pointers – protect with _mtb_ipc_semaphore Arranged by Channel to efficiently scan through list when ISR occurs on a channel. Some devices have first User Channel > 0. To access, use the function _mtb_ipc_queue_array_get_pointer(channel_num, queue_num);
_mtb_ipc_core_irq_data | irq_channels[_MTB_IPC_MAX_PROCESSES_PER_QUEUE] | Shared data object to store all assigned interrupt channels for use in interrupt processing These are used in correctly sending to all cores the required event(s) Each _mtb_ipc_core_irq_data is indexed to its respective core.
uint32_t | ipc_pdl_sema_array[_MTB_IPC_SEMA_COUNT/CY_IPC_SEMA_PER_WORD] | Allocated memory for PDL semaphores. This is passed into PDL semaphore init on the boot core for non-PSOC6 devices. PSOC6 devices instead handle this in their startup code.
mtb_ipc_mbox_data_t * | ipc_mailbox_array[MTB_IPC_MAX_MBOXES] | Array to keep track of shared mailbox data.
_mtb_ipc_rtos_semaphore_data | rtos_semaphore_idx[_MTB_IPC_CORE_NUM][MTB_IPC_RTOS_SEMA_NUM] | Associated RTOS semaphore list. Each entry is _MTB_IPC_UNUSED_SEMAPHORE until assigned to a semaphore.
uint32_t | wait_semaphore_idx[_MTB_IPC_CORE_NUM] | Value of semaphore (per core) that is currently waiting for a give. The value is _MTB_IPC_UNUSED_SEMAPHORE until assigned to a semaphore.

## ◆ mtb_ipc_t

struct mtb_ipc_t

Data Fields
uint32_t | internal_channel_index | IPC channel number (e.g. MTB_IPC_CHAN_0) Please refer to implementation specific documentation for number of available IPC channels for particular device. This must match the IPC object initialized on the other core for this core to access the shared memory.
uint32_t | semaphore_irq | User Defined IRQ for use on this core for all semaphores. A different IRQ Struct Number must be used for other cores.
uint32_t | queue_irq | User Defined IRQ for use on this core for all queues. A different IRQ Struct Number must be used for other cores.
uint32_t | trigger_mask | User to trigger interrupts on all cores to then check notifications.
mtb_ipc_semaphore_t | internal_ipc_semaphore | Internal semaphore to block access to the memory region.
cy_semaphore_t | rtos_semaphore_base[MTB_IPC_RTOS_SEMA_NUM] | Associated RTOS semaphore list. Each is assigned to an IPC semaphore when it is taken.
volatile uint32_t | wait_semaphore_idx | Value of semaphore that is currently waiting for a give. The value is _MTB_IPC_UNUSED_SEMAPHORE until assigned to a semaphore.
mtb_ipc_shared_t * | ipc_shared_vars | Shared memory region.
mtb_ipc_queue_t * | queue_array[MTB_IPC_USR_CHANNELS] | Local storage of all queue handles which each point to corresponding data in shared memory. This is an array indexed by channel of linked lists.
mtb_ipc_mbox_t * | mbox_array[MTB_IPC_MAX_MBOXES] | Local storage of all mailbox handles (sender or receiver) which each point to corresponding data in shared memory. Index determined at initialization of mailbox.

## Macro Definition Documentation

## ◆ MTB_IPC_SEMAPHORE_DATA_ALLOC

#define MTB_IPC_SEMAPHORE_DATA_ALLOC | ( |  | semaphore_data | ) | do { CY_SECTION_SHAREDMEM static mtb_ipc_semaphore_data_t _mtb_ipc_semaphore_data _MTB_IPC_DATA_ALIGN; semaphore_data = &_mtb_ipc_semaphore_data; } while (0)

Macro for semaphore data shared memory allocation.

It is not mandatory to use it for data allocation, user can allocate the memory in the more convenient for them way. Please refer to MTB IPC library documentation for the requirements for memory allocation if macro is not used.

Can be used only in function scope. Params: semaphore_data - pointer to mtb_ipc_semaphore_data_t data type, which will point to the shared memory

## ◆ MTB_IPC_MBOX_DATA_ALLOC

#define MTB_IPC_MBOX_DATA_ALLOC | ( |  | mailbox_data | ) | do { CY_SECTION_SHAREDMEM static mtb_ipc_mbox_data_t _mtb_ipc_mailbox_data _MTB_IPC_DATA_ALIGN; mailbox_data = &_mtb_ipc_mailbox_data; } while (0)

Macro for mailbox data shared memory allocation.

It is not mandatory to use it for data allocation, user can allocate the memory in the more convenient for them way. Please refer to MTB IPC library documentation for the requirements for memory allocation if macro is not used.

Can be used only in function scope. Params: mailbox_data - pointer to mtb_ipc_mbox_data_t data type, which will point to the shared memory

## ◆ MTB_IPC_QUEUE_POOL_ALLOC

#define MTB_IPC_QUEUE_POOL_ALLOC | ( |  | queue_pool,
|  |  | NUM_ITEMS,
|  |  | ITEMSIZE
| ) |  | do { CY_SECTION_SHAREDMEM static uint8_t _mtb_ipc_queue_pool[ITEMSIZE * NUM_ITEMS] _MTB_IPC_DATA_ALIGN; queue_pool = (void*)&_mtb_ipc_queue_pool; } while (0)

Macro for Queue pool shared memory allocation.

This macro can be used for the allocation of queue pool for each queue being initialized, but used can allocate the memory in the most convenient way for them. This macro can be used only in function scope. Please refer to MTB IPC library documentation for the requirements for memory allocation if macro is not used. Params: queue_pool - void pointer to point to the shared memory NUM_ITEMS - number of items, that are expected to fit into the queue ITEMSIZE - size of one queue item (in bytes)

## ◆ MTB_IPC_QUEUE_DATA_ALLOC

#define MTB_IPC_QUEUE_DATA_ALLOC | ( |  | queue_data | ) | do { CY_SECTION_SHAREDMEM static mtb_ipc_queue_data_t _mtb_ipc_queue_data _MTB_IPC_DATA_ALIGN; queue_data = &_mtb_ipc_queue_data; } while (0)

Macro for Queue data shared memory allocation.

It is not mandatory to use it for data allocation, user can allocate the memory in the more convenient for them way. Please refer to MTB IPC library documentation for the requirements for memory allocation if macro is not used.

Can be used only in function scope. Params: queue_data - pointer to mtb_ipc_queue_data_t data type, which will point to the shared memory

## ◆ MTB_IPC_SHARED_DATA_ALLOC

#define MTB_IPC_SHARED_DATA_ALLOC | ( |  | shared | ) | do { CY_SECTION_SHAREDMEM static mtb_ipc_shared_t _mtb_ipc_shared_data _MTB_IPC_DATA_ALIGN; shared = &_mtb_ipc_shared_data; } while (0)

Macro for Shared data region shared memory allocation.

It is not mandatory to use it for data allocation, user can allocate the memory in the more convenient for them way. Please refer to MTB IPC library documentation for the requirements for memory allocation if macro is not used.

Can be used only in function scope. Params: shared - pointer to mtb_ipc_shared_t data type, which will point to the shared memory

## ◆ MTB_IPC_RTOS_SEMA_NUM

#define MTB_IPC_RTOS_SEMA_NUM (10u)

Number of RTOS semaphores that will be allocated and used by driver in RTOS environment (CY_RTOS_AWARE or COMPONENT_RTOS_AWARE should be defined).

Usage of RTOS semaphores in IPC semaphores implementation helps to utilize waiting for semaphores times in RTOS environment more effectively by allowing other threads to run while waiting for a semaphore. To achieve most effectiveness, it is recommended to define MTB_IPC_RTOS_SEMA_NUM value to be greater-equal to the number of IPC semaphores, that are planned to be used. Only semaphores with `semaphore_num`, that is less than _MTB_IPC_RELEASE_BITS can benefit from this feature. Value of this define can be 0. In this case, IPC semaphores will not use RTOS semaphores.

## ◆ MTB_IPC_SEMAPHORE_WAIT_MASK

#define MTB_IPC_SEMAPHORE_WAIT_MASK (0xFFUL)

Define a mask for signaling on NON-RTOS cores that a semaphore was given.

This is used in conjuction with the wait_semaphore_idx on the shared memory region to signal that an ongoing operation may try again to take the semaphore.

## ◆ MTB_IPC_MAX_MBOXES

#define MTB_IPC_MAX_MBOXES (16UL)

Maximum number of mailboxes.

This is determined by size of the notify section of the IPC interrupt. 16 bits -> 16 mailboxes that can be signalled simultaneously.

## Typedef Documentation

## ◆ mtb_ipc_mbox_sender_t

typedef mtb_ipc_mbox_t mtb_ipc_mbox_sender_t

IPC mailbox sender handle We provide distinct type names to distinguish which role can call which functions.

ex: Sender puts.

## ◆ mtb_ipc_mbox_receiver_t

typedef mtb_ipc_mbox_t mtb_ipc_mbox_receiver_t

IPC mailbox receiver handle We provide distinct type names to distinguish which role can call which functions.

ex: Receiver gets.

## Enumeration Type Documentation

## ◆ mtb_ipc_channel_t

enum mtb_ipc_channel_t

Number of IPC Channels available to Applications.

Enumerator
MTB_IPC_CHAN_0 | User IPC channel 0.