Returns a valid handle to the created shared memory object upon success, or NULL_HANDLE if the operation fails. To retrieve extended error information, call the osGetLastError function.

This function initializes and creates a new shared memory object.

Shared memory objects provide mechanisms for creating and managing access to a memory region that is accessed concurrently by multiple tasks.

During creation, an optional name may be assigned to the object, enabling other tasks to locate and open it using the osOpenSharedMemory function. When the shared memory region is no longer needed, the handle must be closed using osCloseHandle. The system destroys the object only after all tasks that opened it have closed their respective handles. For more information, refer to the System Objects Management section.

To optimize the final executable size, if no osOpen* functions are called within the application, the kernel ignores object names and excludes the name management code from the build. Detailed information on naming and object opening can be found in the System Objects Management section.

When a shared memory instance is created, the system allocates a buffer of the size specified by the Size parameter. The base address of this memory buffer is returned to the location pointed to by the Address parameter.

Memory access synchronization is determined by the Mode parameter during creation, supporting three distinct methods:

If the OS_IPC_PROTECT_MUTEX flag is specified, access is protected by a mutex object, which prevents priority inversion. This mode is available only when OS_SH_MEM_PROTECT_MUTEX is set to 1. If the application design guarantees that priority inversion will not occur, the region can instead be protected by an auto-reset event by using the OS_IPC_PROTECT_EVENT flag.

To acquire access to the shared memory, a task must use one of the system wait functions. Once the wait is satisfied, the task assumes exclusive ownership of the shared memory. Ownership is released by calling the osReleaseSharedMemory function. For further details on these synchronization primitives, see the Mutex and Event sections.

In cases where memory access is extremely brief, synchronization may be achieved by disabling interrupts via arLock and subsequently restoring them with arRestore. When using this approach, the standard wait and osReleaseSharedMemory functions are not utilized.

This function is available only when the OS_USE_SHARED_MEM configuration constant is set to 1.