IPC

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.