osCreateSharedMemory function
Declaration:
HANDLE osCreateSharedMemory(
  SYSNAME Name,
  UINT8 Mode, 
  PVOID Address,
  ULONG Size
);
Parameters:
Name

Name of the object (may be NULL).

Mode

Mode flags. See the description section below.

Address

Pointer to variable that receive a memory buffer address (it may be NULL).

Size

Size of the memory buffer specified in bytes.

Return value:

The return value is a handle to the created shared memory object when success or NULL_HANDLE on failure. Use osGetLastErrorfunction to obtain extended error information.

Description:

Function creates a shared memory object.

Shared memory objects create and control the access to memory space that is used simultaneously by many tasks.

During shared memory creation, an optional object name may be specified. It makes tasks able to open it by osOpenSharedMemory function. The non-used shared memory object should be closed with the osCloseHandle. Shared memory object will be deleted when it is closed by all tasks that opened it. More information you can find in the system objects management section.

If all of the osOpen* functions are not used, the system ignores an object name and the code used to name management will be removed. It will reduce final size of the output code. For more information about the names and object opening see the system objects managementsection.

When single object instance is created, it allocates a memory buffer. Its size is determined in Size parameter. Address of the memory buffer is stored in a variable, pointed by Address parameter.

Memory access synchronization can be performed in three ways and is described by Mode parameter during the object creation.

If as a mode flag was used OS_IPC_PROTECT_MUTEX, the memory is protected by a mutex object. It prevents the priority inversion occurrence. This feature is available only, when the OS_SH_MEM_PROTECT_MUTEX constant is set to 1. If it is a certainty that priority inversion will not occur, the memory can be protected by auto-reset event object by setting the OS_IPC_PROTECT_EVENT as a mode flag.

To acquire the shared memory, use one of wait functions. When the wait is completed, the task owns a shared memory. This time no other task will use memory. Releasing the shared memory is realized by osReleaseSharedMemory function. For more information on the specific method of synchronization, please refer to mutex and eventsection.

If the access to the memory is very short, the synchronization can be performed by disabling the interrupts with arLock and later restoring them by arRestore. In this case, the wait and the osReleaseSharedMemory functions are not to be used.

Function is available only, when the value of OS_USE_SHARED_MEM constant is set to 1.

SpaceShadow documentation