| Updated: October 28, 2024 |
Give special attributes to a shared memory object
#include <sys/mman.h>
int shm_ctl( int fd,
int flags,
uint64_t paddr,
uint64_t size );
int shm_ctl_special( int fd,
int flags,
uint64_t paddr,
uint64_t size,
unsigned special );
This flag is useful for learning if an object is assigned a physical address and hence, should not be given to unknown clients due to security risks, as explained in the paddr argument description below.
shm_ctl( fd, SHMCTL_PHYS, baseaddr, vstride );
shm_ctl( fd, SHMCTL_REPEAT, pstride, count );
For more information, see “Secure Buffer Management” in the “Shared Memory” chapter of the QNX Neutrino Programmer's Guide.
If you specify SHMCTL_TYMEM, you must also specify SHMCTL_ANON. If and only if you specified the POSIX_TYPED_MEM_ALLOCATE_CONTIG flag for posix_typed_mem_open(), you must specify SHMCTL_PHYS in addition to SHMCTL_ANON and SHMCTL_TYMEM.
For example, suppose process A allocates some memory, maps it, determines the physical address, and gives the address to process B so that it can map the memory. Process B uses direct mapping. Process A can free the memory or terminate, and the memory could then be given to another process, while process B continues to use it. This could cause a process or even the kernel to crash later.
If paddr is a physical address or a stride, its value must be a multiple of the page size (sysconf(_SC_PAGESIZE)).
For SHMCTL_REPEAT, this argument is the length, which is used to increment the offset within the object. The value must be a multiple of the page size.
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
The shm_ctl() function modifies the attributes of the shared memory object identified by the handle, fd. This handle is the value returned by shm_open(). The shm_ctl_special() function is similar to shm_ctl(), but has an additional, processor-specific argument.
| In order to use: | You need: |
|---|---|
| SHMCTL_GLOBAL | PROCMGR_AID_MEM_GLOBAL |
| SHMCTL_PHYS | PROCMGR_AID_MEM_PHYS |
| shm_ctl_special() | PROCMGR_AID_MEM_SPECIAL |
Typically, you can call shm_ctl() only once on a new object created with shm_open(). Reopening an existing object with the O_TRUNC flag doesn't make the object new again.
If you first initialized an object with shm_ctl_special(), all subsequent calls that follow the rules above must also be done with shm_ctl_special(), using the same special attributes.
Shared memory objects that are populated with shm_ctl() are implicitly locked, unless you use the SHMCTL_LAZY flag.
For x86 processors:
For ARM platforms, the special argument specifies the memory attributes that will be used when the object is mapped.
Non-RAM memory locations, that are mapped using mmap() with the PROT_NOCACHE protection type, are assigned as device-nGnRnE as a default.
All loads and stores must be aligned for the access size, otherwise a memory fault is triggered resulting in delivery of a SIGBUS signal.
Reads are performed using a single memory access with the size as specified by the load instruction.
Stores are performed using a single memory access with the size as specified by the load instruction.
An explicit memory barrier may be required after store operations to ensure visibility of the store to the memory system.
For an example on using this flag, see “Sharing device memory” below.
Loads and stores may be performed to unaligned addresses, except for those instructions that always require correct alignment.
Stores can be merged into a write buffer before being written to the memory system.
An explicit memory barrier may be required after store operations to ensure visibility of the store to the memory system.
Loads and stores may be performed to unaligned addresses, except for those instructions that always require correct alignment.
Loads allocate a cache line and return data from the cache.
Stores don't cause allocation of a cache line. If a store hits in the cache, the cache is modified and the data is written to memory via a write buffer. If a store misses in the cache, the data is written to memory via a write buffer. Multiple stores may be merged in the write buffer before being written to the memory system.
Loads and stores may be performed to unaligned addresses, except for those instructions that always require correct alignment.
Loads allocate a cache line and return data from the cache.
Stores don't cause allocation of a cache line. If a store hits in the cache, the cache is modified and the line is marked for write back to the memory system at a later time. If a store misses in the cache, the data is written to memory via a write buffer. Multiple stores may be merged in the write buffer before being written to the memory system.
Loads and stores may be performed to unaligned addresses, except for those instructions that always require correct alignment.
Loads allocate a cache line and return data from the cache.
Stores allocate a cache line and modify the cache, marking the line for write back to the memory system at a later time.
For ARM_SHMCTL_NC, accesses are coherent with respect to loads and stores, and the additional coherency applies to load/store exclusive operations.
For ARM_SHMCTL_WT, ARM_SHMCTL_WB, and ARM_SHMCTL_WBWA, this indicates that hardware cache coherency is required.
The level at which this coherency applies is system dependent, and it may still require explicit cache maintenance to enforce coherency for memory accesses by other bus masters (e.g., DMA operations).
You can find full details of the ARM memory attributes and ordering requirements in section A3.5, “Memory types and attributes and the memory order model,” in the ARM Architecture Reference Manual (ARM DDI 0406).
(QNX Neutrino 7.1 or later) For AArch64 platforms, the special argument specifies the memory and shareability attributes that will be used when the object is mapped.
You must specify one of the following memory attributes:
All loads and stores must be aligned for the access size, otherwise a memory fault is triggered resulting in delivery of a SIGBUS signal.
Reads are performed using a single memory access with the size as specified by the load instruction.
Stores are performed using a single memory access with the size as specified by the load instruction.
An explicit memory barrier may be required after store operations to ensure visibility of the store to the memory system.
Loads and stores may be performed to unaligned addresses, except for those instructions that always require correct alignment.
Stores can be merged into a write buffer before being written to the memory system.
An explicit memory barrier may be required after store operations to ensure visibility of the store to the memory system.
Non-RAM memory locations, that are mapped using mmap() with the PROT_NOCACHE protection type, are assigned as device-nGnRnE as a default.
All loads and stores must be aligned for the access size, otherwise a memory fault is triggered resulting in delivery of a SIGBUS signal.
Loads and stores may be performed to unaligned addresses, except for those instructions that always require correct alignment.
Loads allocate a cache line and return data from the cache.
Stores allocate a cache line and modify the cache, marking the line for write back to the memory system at a later time.
You can use a bitwise OR to include one of the following shareability attributes:
If you don't specify inner- or outer-shareable, the memory is non-shareable (AARCH64_PTE_NSH). This is almost never what you want for non-device memory (device memory is outer-shareable). Unless you have a reason not to, you should specify inner-shareable for non-device memory.
For more information, see the ARM Architecture Reference Manual.
/*
* create_device_shm.c
*/
#include <string.h>
#include <unistd.h>
#include <sys/mman.h>
#include <aarch64/mmu.h>
#include <stdint.h>
#include <assert.h>
#include <fcntl.h>
#define S1_SHM_NAME "shm_s1"
#define TOTAL_PAGE_SIZE (4096)
static char *src;
static int src_fd;
/** Remove the shared memory object and destroy the device memory */
void destroy_device_shm(int shm_fd, char *name)
{
close(shm_fd);
shm_unlink(name);
}
/**
* Create a shared memory object and configure it to simulate device memory.
* Return the file descriptor of the new object if successful, -1 otherwise.
*/
int create_device_shm(char *name, uint64_t size)
{
int fd;
int rc;
fd = shm_open(name, O_RDWR|O_CREAT|O_TRUNC, 0666);
if (fd < 0) {
return -1;
}
rc = shm_ctl_special(fd, SHMCTL_ANON | SHMCTL_PHYS, 0, size, ARM_SHMCTL_DEV);
if (rc != 0) {
destroy_device_shm(fd, name);
return -1;
}
return fd;
}
void cleanup()
{
munmap(src, TOTAL_PAGE_SIZE);
destroy_device_shm(src_fd, S1_SHM_NAME);
}
int main(void)
{
// Create device memory region
src_fd = create_device_shm(S1_SHM_NAME, TOTAL_PAGE_SIZE);
assert(src_fd >= 0);
// Map device memory into current address space
src = mmap(NULL, TOTAL_PAGE_SIZE, PROT_READ | PROT_WRITE, MAP_SHARED, src_fd, 0);
assert(src != (void *)MAP_FAILED);
// Your code goes here
// Destroy device memory region
cleanup();
return 0;
}
| Safety: | |
|---|---|
| Cancellation point | Yes |
| Interrupt handler | No |
| Signal handler | Yes |
| Thread | Yes |