d04578b40c
Make explicit an important promise made by rtapi_shmem_new(): When a
block of memory is first allocated, it is initialized to all zero bytes.
On Uspace rtapi_shmem_new() calls shmget(), which zeros the memory when
creating a new shared memory block:
https://man7.org/linux/man-pages/man2/shmget.2.html#DESCRIPTION
On RTAI rtapi_shmem_new() calls rtai_kmalloc() and rtai_malloc(), which
both end up calling _rt_shmem_new(). The documentation does not say
anything about initialization of freshly allocated memory buffers, but
Paolo Mantegazza (one of the main RTAI developers) said that RTAI *does*
zeros shmem buffers, and pointed to this code:
https://mail.rtai.org/pipermail/rtai/2022-January/028282.html
http://cvs.savannah.nongnu.org/viewvc/rtai/magma/base/ipc/shm/shm.c?view=markup#l69
63 lines
2.1 KiB
Text
63 lines
2.1 KiB
Text
.TH rtapi_shmem "3rtapi" "2006-10-12" "LinuxCNC Documentation" "RTAPI"
|
|
.SH NAME
|
|
|
|
rtapi_shmem \- Functions for managing shared memory blocks
|
|
|
|
.SH SYNTAX
|
|
.HP
|
|
int rtapi_shmem_new(int \fIkey\fR, int \fImodule_id\fR, unsigned long int \fIsize\fR)
|
|
|
|
.HP
|
|
int rtapi_shmem_delete(int \fIshmem_id\fR, int \fImodule_id\fR)
|
|
|
|
.HP
|
|
int rtapi_shmem_getptr(int \fIshmem_id\fR, void ** \fIptr\fR)
|
|
|
|
.SH ARGUMENTS
|
|
.IP \fIkey\fB
|
|
Identifies the memory block. Key must be nonzero. All modules wishing to use the same memory must use the same key.
|
|
|
|
.IP \fImodule_id\fB
|
|
Module identifier returned by a prior call to \fBrtapi_init\fR.
|
|
|
|
.IP \fIsize\fB
|
|
The desired size of the shared memory block, in bytes
|
|
|
|
.IP \fIptr\fB
|
|
The pointer to the shared memory block. Note that the block may be mapped
|
|
at a different address for different modules.
|
|
|
|
.SH DESCRIPTION
|
|
|
|
\fBrtapi_shmem_new\fR allocates a block of shared memory. \fIkey\fR
|
|
identifies the memory block, and must be non-zero. All modules
|
|
wishing to access the same memory must use the same key.
|
|
\fImodule_id\fR is the ID of the module that is making the call (see
|
|
rtapi_init). The block will be at least \fIsize\fR bytes, and may
|
|
be rounded up. Allocating many small blocks may be very wasteful.
|
|
When a particular block is allocated for the first time, the contents
|
|
are zeroed. Subsequent allocations of the same block
|
|
by other modules or processes will not touch the contents of the
|
|
block. Applications can use those bytes to see if they need to
|
|
initialize the block, or if another module already did so.
|
|
On success, it returns a positive integer ID, which is used for
|
|
all subsequent calls dealing with the block. On failure it
|
|
returns a negative error code.
|
|
|
|
\fBrtapi_shmem_delete\fR frees the shared memory block associated
|
|
with \fIshmem_id\fR. \fImodule_id\fR is the ID of the calling module.
|
|
Returns a status code.
|
|
|
|
\fBrtapi_shmem_getptr\fR sets \fI*ptr\fR to point to shared memory block
|
|
associated with \fIshmem_id\fR.
|
|
|
|
.SH REALTIME CONSIDERATIONS
|
|
|
|
\fBrtapi_shmem_getptr\fR may be called from user code, init/cleanup code,
|
|
or realtime tasks.
|
|
|
|
\fBrtapi_shmem_new\fR and \fBrtapi_shmem_dete\fR may not be called from
|
|
realtime tasks.
|
|
|
|
.SH RETURN VALUE
|
|
|