NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | RETURN VALUE | ERRORS | RESTRICTIONS | ATTRIBUTES | SEE ALSO
#include <pmm/chPmm.h>KnError pmmAllocate (VmAddr *addr, PmmName *blockName, size_t memSize, PmmDelKey delKey, size_t delKeySize);
The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.
See API(5FEA) for details.
HOT_RESTART
pmmAllocate() allocates or retrieves a persistent memory block and maps it into the caller's address space. A persistent memory block is identified in the system by a PmmName structure, defined as follows:
#include <chPmm.h> typedef struct { PmmMedium medium = "RAM"; PmmMemName name; } PmmName;
In a PmmName structure, medium
is a null-terminated character string that identifies the persistent memory
medium in which the block is to be allocated. The only medium supported is "RAM". It is a reserved, fixed-size bank of system memory. The size
of the bank is fixed by the pmm.rambankSize
tunable
system parameter. The contents of the bank persist across a hot restart but
not across a cold restart.
In a PmmName structure, name is a user-defined, null-terminated character string that uniquely identifies the memory block in the selected medium.
The blockName parameter passed to pmmAllocate() must be a valid PmmName structure. The size parameter specifies the size of the memory block, in bytes.
pmmAllocate() returns the mapping address of the block as the value of addr. If blockName does not identify an existing persistent memory block, the returned addr will be a pointer to a newly-allocated, zero-filled block of persistent memory. If blockName identifies an existing memory block, the returned addr will be a pointer to the existing block. As long as it is not destroyed, a persistent block is guaranteed to be mapped to the same address. In other words, addr will always point to the same address during the lifetime of the block. If this address is not available in the caller's space, the block cannot be mapped and an error is raised.
The deletion key delKey is a binary array that is used to group several blocks and destroy all of them at once, using pmmFreeAll(2RESTART). delKeySize is the size of the array, in bytes. If delKey is NULL or delKeySize is zero, pmmFreeAll() will not be able to destroy the block. The delKey and delKeySize parameters are taken into account only when a block is first allocated. If blockName identifies an existing memory block, the delKey and delKeySize parameters are ignored.
Passing the macros HR_GROUP_KEY() and HR_GROUP_KEY_SIZE() as the delKey and delKeySize parameters respectively, marks the persistent memory block for to be freed automatically by the Hot Restart Controller. Persistent memory blocks that use this special deletion key will be freed automatically when the calling actor's group terminates or is killed, and will not need to be freed explicitly.
Block names and deletion keys are stored in the same medium as the block with which they are associated. As the only medium is "RAM", all block names and deletion keys are deleted when a cold reboot occurs.
The actor using a persistent memory block at any given time is not necessarily the same actor that created the block, and is not necessarily related in any way to the actor that created the block. However, the following rules apply:
Persistent memory blocks can only be shared between supervisor actors. No support is provided for sharing blocks of persistent memory with user actors or trusted user actors.
It is the programmer's responsibility to ensure that this rule is respected. The system does not detect block sharing with user actors or trusted user actors.
To share areas of memory with user actors and/or trusted user actors, use the rgnMapFromActor(2K) system call.
pmmAllocate() guarantees that if the requested block of persistent memory already exists, it will be mapped to the same address as at creation. However, it is up to the invoker to make sure that the corresponding range of addresses is not already occupied. If the address range is occupied, pmmAllocate() will fail and the block will not be mapped at all.
Using a block of persistent memory created in a different address space is not supported.
On successful completion, a value of 0 is returned. Otherwise, a negative error code is returned.
delKeySize is larger than the size of delKey.
The medium name is invalid.
Some of the data provided is outside the current actor's address space.
blockName->name begins with "__SYS", that is, identifies a persistent memory block used internally by the system.
blockName identifies an existing block that was created by an actor with higher privileges than the invoking actor.
The system is out of resources.
There is no more persistent memory available on the specified medium.
blockName identifies an existing block whose address range would overlap with an existing region in the invoking actor's address space.
blockName identifies an existing block whose address range would be outside the valid address range of the invoking actor.
The system will not always detect that the same block of persistent memory is requested by more than one running actor, or by actors running in incompatible address spaces. As no support is provided for sharing persistent memory blocks with user actors or trusted user actors, it is the programmer's responsibility to ensure that this situation does not occur. This restriction does not apply to supervisor actors, as sharing persistent memory blocks between two or more supervisor actors is supported.
The system uses persistent memory blocks internally. Their blockName->name parameter and deletion key begin with "__SYS". Using these types of names and deletion keys in application code will cause unpredictable behavior.
Calling rgnFree(2K) with an argument that overlaps a memory block returned by pmmAllocate() will have unpredictable results.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | RETURN VALUE | ERRORS | RESTRICTIONS | ATTRIBUTES | SEE ALSO