Data Structures | |
| struct | sivc_queue |
Macros | |
| #define | SIVC_ALIGN_SHIFT 6U |
| #define | SIVC_ALIGN (((uint32_t)1U) << SIVC_ALIGN_SHIFT) |
Typedefs | |
| typedef void(* | sivc_notify_function) (struct sivc_queue *queue) |
| Callback: signal the remote endpoint. More... | |
| typedef void(* | sivc_cache_invalidate_function) (const volatile void *addr, size_t size) |
| Callback: Invalidate cache for a given memory range. More... | |
| typedef void(* | sivc_cache_flush_function) (const volatile void *addr, size_t size) |
| Callback: Flush cache for a given memory range. More... | |
Functions | |
| uint32_t | sivc_align (uint32_t value) |
| Align a number. More... | |
| uint32_t | sivc_fifo_size (uint32_t nframes, uint32_t frame_size) |
| Calculate size of the memory needed for IVC fifo. More... | |
| int | sivc_init (struct sivc_queue *queue, uintptr_t recv_base, uintptr_t send_base, uint32_t nframes, uint32_t frame_size, sivc_notify_function notify, sivc_cache_invalidate_function cache_invalidate, sivc_cache_flush_function sivc_cache_flush) |
| Initialize IVC queue control structure. More... | |
| #define SIVC_ALIGN (((uint32_t)1U) << SIVC_ALIGN_SHIFT) |
Definition at line 39 of file sivc-instance.h.
| #define SIVC_ALIGN_SHIFT 6U |
Definition at line 32 of file sivc-instance.h.
Callback: Flush cache for a given memory range.
| [in] | addr | Start address |
| [in] | size | Memory range size |
Definition at line 104 of file sivc-instance.h.
Callback: Invalidate cache for a given memory range.
| [in] | addr | Start address |
| [in] | size | Memory range size |
Definition at line 94 of file sivc-instance.h.
| typedef void(* sivc_notify_function) (struct sivc_queue *queue) |
Callback: signal the remote endpoint.
| [in] | queue | IVC queue endpoint from which to signal. |
Definition at line 85 of file sivc-instance.h.
| uint32_t sivc_align | ( | uint32_t | value | ) |
Align a number.
| [in] | value | An unsigned integer |
@restriction @id{Init_Align} @asil{D} The caller must ensure that the argument is less than or equal to (UINT32_MAX - SIVC_ALIGN + 1).
value and divisible by SIVC_ALIGN.@outcome @id{Align_Result} @asil{D} sivc_align returns the closest integer that is greater than or equal to value and divisible by SIVC_ALIGN.
| uint32_t sivc_fifo_size | ( | uint32_t | nframes, |
| uint32_t | frame_size | ||
| ) |
Calculate size of the memory needed for IVC fifo.
| [in] | nframes | Number of IVC queue frames |
| [in] | frame_size | Size of one frame in bytes |
Function fails if:
frame_size is not a multiple of SIVC_ALIGN. @outcome @id{FifoSize_Success} @asil{D} If succeeded sivc_align returns number of bytes needed for IVC fifo memory area.
@outcome @id{FifoSize_Failure} @asil{D} In case of error sivc_align returns 0.
| int sivc_init | ( | struct sivc_queue * | queue, |
| uintptr_t | recv_base, | ||
| uintptr_t | send_base, | ||
| uint32_t | nframes, | ||
| uint32_t | frame_size, | ||
| sivc_notify_function | notify, | ||
| sivc_cache_invalidate_function | cache_invalidate, | ||
| sivc_cache_flush_function | sivc_cache_flush | ||
| ) |
Initialize IVC queue control structure.
| [in] | queue | IVC queue |
| [in] | recv_base | Shared memory address of receive IVC FIFO |
| [in] | send_base | Shared memory address of transmit IVC FIFO |
| [in] | nframes | Number of frames in a queue |
| [in] | frame_size | Frame size in bytes |
| [in] | notify | Notification callback, can be NULL |
| [in] | cache_invalidate | Memory cache invalidation callback, can be NULL |
| [in] | sivc_cache_flush | Memory cache flush callback, can be NULL |
IVC queue control structure is considered to be private, even though is is declared in public header. This function should be used to set it up.
Function fails if:
-EINVAL The queue is NULL -EINVAL recv_base or send_base are zero -EINVAL recv_base or send_base are not aligned to SIVC_ALIGN -EINVAL frame_size is not aligned to SIVC_ALIGN -EINVAL Receive FIFO memory area and send FIFO memory area overlap -EINVAL Expected IVC FIFO size is bigger than 2^32@restriction @id{Init_SharedMemoryMapping} @asil{D} The caller is responsible for ensuring that both IVC queue endpoints are compatibly initialized as specified by following preconditions: The IVC Library execution environment shall provide a region of memory that is mapped into the address space (execution domain) of both sides of the IVC channel with read-write access, of sufficient size to contain the two FIFOs described in the configuration information. This region shall be used exclusively by the IVC Library, except as documented by sivc_get_read_frame and sivc_get_write_frame. @rationale Both send and receive FIFOs require both read and write access for transitional, backwards compatibility with Legacy IVC implementations.
@restriction @id{Cfg_FifoSymmetry} @asil{D} Sending and receiving FIFO buffers at the local endpoint must correspond receiving and sending FIFO buffers at the remote endpoint:
recv_base must correspond to the same underlying physical memory as send_base for the other IVC queue endpoint. send_base must correspond to the same underlying physical memory as recv_base for the other IVC queue endpoint.@restriction @id{Cfg_MaxFrameCount} @asil{D} Number of frames in a queue nframes must be identical for both IVC queue endpoints.
@restriction @id{Cfg_FrameSize} @asil{D} Frame size frame_size must be identical for both IVC queue endpoints.
@restriction @id{Init_CacheCoherency} @asil{D} If hardware cache coherency is not guaranteed, cache_invalidate and sivc_cache_flush cache management callbacks must be supplied.
@restriction @id{Init_AtMostOnce} @asil{D} sivc_init shall be called at most once unless both endpoints do coordinated re-initialization. For example, on SC7 resume peers may call sivc_init to restart communication, but it must be done on both sides and before calling any other IVC function.
@restriction @id{Init_TheFirst} @asil{D} sivc_init must be called before invoking any other IVC function on the endpoint.
@restriction @id{Init_NotifyAfterData} @asil{D} notify callback must guarantee that all the changes in shared memory made by the local peer become visible to the remote peer before the remote peer receives the notification. @rationale sivc_init assumes that notify guarantees the completion order, with data access first and notification later. On some architectures, device-based notifications can cause race conditions between data access and notification, such as MSI-based notifications. To resolve the race condition, mechanisms like the ARM architecture DSB barrier can be used to enforce the correct completion order.
@outcome @id{Init_Error} @asil{D} If sivc_init cannot successfully performs endpoint initialization, it must return error.
@outcome @id{Init_ZeroedSharedMemory} @asil{B} When shared memory is initialized with zeros and sivc_init successfully performs endpoint initialization, the endpoint must be in Established state.