Xenomai  3.0.8
Collaboration diagram for Utility Services:

Functions

int rtdm_mmap_to_user (struct rtdm_fd *fd, void *src_addr, size_t len, int prot, void **pptr, struct vm_operations_struct *vm_ops, void *vm_private_data)
 Map a kernel memory range into the address space of the user. More...
 
int rtdm_iomap_to_user (struct rtdm_fd *fd, phys_addr_t src_addr, size_t len, int prot, void **pptr, struct vm_operations_struct *vm_ops, void *vm_private_data)
 Map an I/O memory range into the address space of the user. More...
 
int rtdm_mmap_kmem (struct vm_area_struct *vma, void *va)
 Map a kernel logical memory range to a virtual user area. More...
 
int rtdm_mmap_vmem (struct vm_area_struct *vma, void *va)
 Map a virtual memory range to a virtual user area. More...
 
int rtdm_mmap_iomem (struct vm_area_struct *vma, phys_addr_t pa)
 Map an I/O memory range to a virtual user area. More...
 
int rtdm_munmap (void *ptr, size_t len)
 Unmap a user memory range. More...
 
int rtdm_ratelimit (struct rtdm_ratelimit_state *rs, const char *func)
 Enforces a rate limit. More...
 
void rtdm_printk_ratelimited (const char *format,...)
 Real-time safe rate-limited message printing on kernel console. More...
 
void rtdm_printk (const char *format,...)
 Real-time safe message printing on kernel console. More...
 
void * rtdm_malloc (size_t size)
 Allocate memory block. More...
 
void rtdm_free (void *ptr)
 Release real-time memory block. More...
 
int rtdm_read_user_ok (struct rtdm_fd *fd, const void __user *ptr, size_t size)
 Check if read access to user-space memory block is safe. More...
 
int rtdm_rw_user_ok (struct rtdm_fd *fd, const void __user *ptr, size_t size)
 Check if read/write access to user-space memory block is safe. More...
 
int rtdm_copy_from_user (struct rtdm_fd *fd, void *dst, const void __user *src, size_t size)
 Copy user-space memory block to specified buffer. More...
 
int rtdm_safe_copy_from_user (struct rtdm_fd *fd, void *dst, const void __user *src, size_t size)
 Check if read access to user-space memory block and copy it to specified buffer. More...
 
int rtdm_copy_to_user (struct rtdm_fd *fd, void __user *dst, const void *src, size_t size)
 Copy specified buffer to user-space memory block. More...
 
int rtdm_safe_copy_to_user (struct rtdm_fd *fd, void __user *dst, const void *src, size_t size)
 Check if read/write access to user-space memory block is safe and copy specified buffer to it. More...
 
int rtdm_strncpy_from_user (struct rtdm_fd *fd, char *dst, const char __user *src, size_t count)
 Copy user-space string to specified buffer. More...
 
int rtdm_in_rt_context (void)
 Test if running in a real-time task. More...
 
int rtdm_rt_capable (struct rtdm_fd *fd)
 Test if the caller is capable of running in real-time context. More...
 

Detailed Description

Function Documentation

◆ rtdm_copy_from_user()

int rtdm_copy_from_user ( struct rtdm_fd *  fd,
void *  dst,
const void __user *  src,
size_t  size 
)

Copy user-space memory block to specified buffer.

Parameters
[in]fdRTDM file descriptor as passed to the invoked device operation handler
[in]dstDestination buffer address
[in]srcAddress of the user-space memory block
[in]sizeSize of the memory block
Returns
0 on success, otherwise:
  • -EFAULT is returned if an invalid memory area was accessed.
Note
Before invoking this service, verify via rtdm_read_user_ok() that the provided user-space address can securely be accessed.
Tags cobalt-core-tags "task-unrestricted"

◆ rtdm_copy_to_user()

int rtdm_copy_to_user ( struct rtdm_fd *  fd,
void __user *  dst,
const void *  src,
size_t  size 
)

Copy specified buffer to user-space memory block.

Parameters
[in]fdRTDM file descriptor as passed to the invoked device operation handler
[in]dstAddress of the user-space memory block
[in]srcSource buffer address
[in]sizeSize of the memory block
Returns
0 on success, otherwise:
  • -EFAULT is returned if an invalid memory area was accessed.
Note
Before invoking this service, verify via rtdm_rw_user_ok() that the provided user-space address can securely be accessed.
Tags cobalt-core-tags "task-unrestricted"

◆ rtdm_free()

void rtdm_free ( void *  ptr)

Release real-time memory block.

Parameters
[in]ptrPointer to memory block as returned by rtdm_malloc()
Tags cobalt-core-tags "unrestricted"

◆ rtdm_in_rt_context()

int rtdm_in_rt_context ( void  )

Test if running in a real-time task.

Returns
Non-zero is returned if the caller resides in real-time context, 0 otherwise.
Tags cobalt-core-tags "unrestricted"

◆ rtdm_iomap_to_user()

int rtdm_iomap_to_user ( struct rtdm_fd *  fd,
phys_addr_t  src_addr,
size_t  len,
int  prot,
void **  pptr,
struct vm_operations_struct *  vm_ops,
void *  vm_private_data 
)

Map an I/O memory range into the address space of the user.

Parameters
[in]fdRTDM file descriptor as passed to the invoked device operation handler
[in]src_addrphysical I/O address to be mapped
[in]lenLength of the memory range
[in]protProtection flags for the user's memory range, typically either PROT_READ or PROT_READ|PROT_WRITE
[in,out]pptrAddress of a pointer containing the desired user address or NULL on entry and the finally assigned address on return
[in]vm_opsvm_operations to be executed on the vm_area of the user memory range or NULL
[in]vm_private_dataPrivate data to be stored in the vm_area, primarily useful for vm_operation handlers
Returns
0 on success, otherwise (most common values):
  • -EINVAL is returned if an invalid start address, size, or destination address was passed.
  • -ENOMEM is returned if there is insufficient free memory or the limit of memory mapping for the user process was reached.
  • -EAGAIN is returned if too much memory has been already locked by the user process.
  • -EPERM may be returned if an illegal invocation environment is detected.
Note
RTDM supports two models for unmapping the memory area:
  • manual unmapping via rtdm_munmap(), which may be issued from a driver in response to an IOCTL call, or by a call to the regular munmap() call from the application.
  • automatic unmapping, triggered by the termination of the process which owns the mapping. To track the number of references pending on the resource mapped, the driver can pass the address of a close handler for the vm_area considered, in the vm_ops descriptor. See the relevant Linux kernel programming documentation (e.g. Linux Device Drivers book) on virtual memory management for details.
Tags cobalt-core-tags "secondary-only"

◆ rtdm_malloc()

void* rtdm_malloc ( size_t  size)

Allocate memory block.

Parameters
[in]sizeRequested size of the memory block
Returns
The pointer to the allocated block is returned on success, NULL otherwise.
Tags cobalt-core-tags "unrestricted"

Referenced by a4l_alloc_subd().

◆ rtdm_mmap_iomem()

int rtdm_mmap_iomem ( struct vm_area_struct *  vma,
phys_addr_t  pa 
)

Map an I/O memory range to a virtual user area.

This routine is commonly used from a ->mmap() handler of a RTDM driver, for mapping an I/O memory area over the user address space referred to by vma.

Parameters
[in]vmaThe VMA descriptor to receive the mapping.
[in]paThe physical I/O address to be mapped.
Returns
0 on success, otherwise a negated error code is returned.
Note
To map a chunk of logical space obtained from kmalloc(), or a purely virtual area with no direct physical mapping to a VMA, call rtdm_mmap_kmem() or rtdm_mmap_vmem() respectively instead.
Tags cobalt-core-tags "secondary-only"

◆ rtdm_mmap_kmem()

int rtdm_mmap_kmem ( struct vm_area_struct *  vma,
void *  va 
)

Map a kernel logical memory range to a virtual user area.

This routine is commonly used from a ->mmap() handler of a RTDM driver, for mapping a virtual memory area with a direct physical mapping over the user address space referred to by vma.

Parameters
[in]vmaThe VMA descriptor to receive the mapping.
[in]vaThe kernel logical address to be mapped.
Returns
0 on success, otherwise a negated error code is returned.
Note
This service works on memory regions allocated via kmalloc(). To map a chunk of virtual space with no direct physical mapping, or a physical I/O memory to a VMA, call rtdm_mmap_vmem() or rtdm_mmap_iomem() respectively instead.
Tags cobalt-core-tags "secondary-only"

◆ rtdm_mmap_to_user()

int rtdm_mmap_to_user ( struct rtdm_fd *  fd,
void *  src_addr,
size_t  len,
int  prot,
void **  pptr,
struct vm_operations_struct *  vm_ops,
void *  vm_private_data 
)

Map a kernel memory range into the address space of the user.

Parameters
[in]fdRTDM file descriptor as passed to the invoked device operation handler
[in]src_addrKernel virtual address to be mapped
[in]lenLength of the memory range
[in]protProtection flags for the user's memory range, typically either PROT_READ or PROT_READ|PROT_WRITE
[in,out]pptrAddress of a pointer containing the desired user address or NULL on entry and the finally assigned address on return
[in]vm_opsvm_operations to be executed on the vm_area of the user memory range or NULL
[in]vm_private_dataPrivate data to be stored in the vm_area, primarily useful for vm_operation handlers
Returns
0 on success, otherwise (most common values):
  • -EINVAL is returned if an invalid start address, size, or destination address was passed.
  • -ENOMEM is returned if there is insufficient free memory or the limit of memory mapping for the user process was reached.
  • -EAGAIN is returned if too much memory has been already locked by the user process.
  • -EPERM may be returned if an illegal invocation environment is detected.
Note
This service only works on memory regions allocated via kmalloc() or vmalloc(). To map physical I/O memory to user-space use rtdm_iomap_to_user() instead.
RTDM supports two models for unmapping the memory area:
  • manual unmapping via rtdm_munmap(), which may be issued from a driver in response to an IOCTL call, or by a call to the regular munmap() call from the application.
  • automatic unmapping, triggered by the termination of the process which owns the mapping. To track the number of references pending on the resource mapped, the driver can pass the address of a close handler for the vm_area considered, in the vm_ops descriptor. See the relevant Linux kernel programming documentation (e.g. Linux Device Drivers book) on virtual memory management for details.
Tags cobalt-core-tags "secondary-only"

◆ rtdm_mmap_vmem()

int rtdm_mmap_vmem ( struct vm_area_struct *  vma,
void *  va 
)

Map a virtual memory range to a virtual user area.

This routine is commonly used from a ->mmap() handler of a RTDM driver, for mapping a purely virtual memory area over the user address space referred to by vma.

Parameters
[in]vmaThe VMA descriptor to receive the mapping.
[in]vaThe virtual address to be mapped.
Returns
0 on success, otherwise a negated error code is returned.
Note
This service works on memory regions allocated via vmalloc(). To map a chunk of logical space obtained from kmalloc(), or a physical I/O memory to a VMA, call rtdm_mmap_kmem() or rtdm_mmap_iomem() respectively instead.
Tags cobalt-core-tags "secondary-only"

◆ rtdm_munmap()

int rtdm_munmap ( void *  ptr,
size_t  len 
)

Unmap a user memory range.

Parameters
[in]ptrUser address or the memory range
[in]lenLength of the memory range
Returns
0 on success, otherwise:
  • -EINVAL is returned if an invalid address or size was passed.
  • -EPERM may be returned if an illegal invocation environment is detected.
Tags cobalt-core-tags "secondary-only"

◆ rtdm_printk()

void rtdm_printk ( const char *  format,
  ... 
)

Real-time safe message printing on kernel console.

Parameters
[in]formatFormat string (conforming standard printf())
...Arguments referred by format
Returns
On success, this service returns the number of characters printed. Otherwise, a negative error code is returned.
Tags cobalt-core-tags "unrestricted"

◆ rtdm_printk_ratelimited()

void rtdm_printk_ratelimited ( const char *  format,
  ... 
)

Real-time safe rate-limited message printing on kernel console.

Parameters
[in]formatFormat string (conforming standard printf())
...Arguments referred by format
Returns
On success, this service returns the number of characters printed. Otherwise, a negative error code is returned.
Tags cobalt-core-tags "unrestricted"

◆ rtdm_ratelimit()

int rtdm_ratelimit ( struct rtdm_ratelimit_state *  rs,
const char *  func 
)

Enforces a rate limit.

This function enforces a rate limit: not more than rs->burst callbacks in every rs->interval.

Parameters
[in,out]rsrtdm_ratelimit_state data
[in]funcname of calling function
Returns
0 means callback will be suppressed and 1 means go ahead and do it
Tags cobalt-core-tags "unrestricted"

References rtdm_clock_read(), rtdm_lock_get_irqsave, and rtdm_lock_put_irqrestore().

◆ rtdm_read_user_ok()

int rtdm_read_user_ok ( struct rtdm_fd *  fd,
const void __user *  ptr,
size_t  size 
)

Check if read access to user-space memory block is safe.

Parameters
[in]fdRTDM file descriptor as passed to the invoked device operation handler
[in]ptrAddress of the user-provided memory block
[in]sizeSize of the memory block
Returns
Non-zero is return when it is safe to read from the specified memory block, 0 otherwise.
Tags cobalt-core-tags "task-unrestricted"

◆ rtdm_rt_capable()

int rtdm_rt_capable ( struct rtdm_fd *  fd)

Test if the caller is capable of running in real-time context.

Parameters
[in]fdRTDM file descriptor as passed to the invoked device operation handler
Returns
Non-zero is returned if the caller is able to execute in real-time context (independent of its current execution mode), 0 otherwise.
Note
This function can be used by drivers that provide different implementations for the same service depending on the execution mode of the caller. If a caller requests such a service in non-real-time context but is capable of running in real-time as well, it might be appropriate for the driver to reject the request via -ENOSYS so that RTDM can switch the caller and restart the request in real-time context.
Tags cobalt-core-tags "unrestricted"

◆ rtdm_rw_user_ok()

int rtdm_rw_user_ok ( struct rtdm_fd *  fd,
const void __user *  ptr,
size_t  size 
)

Check if read/write access to user-space memory block is safe.

Parameters
[in]fdRTDM file descriptor as passed to the invoked device operation handler
[in]ptrAddress of the user-provided memory block
[in]sizeSize of the memory block
Returns
Non-zero is return when it is safe to read from or write to the specified memory block, 0 otherwise.
Tags cobalt-core-tags "task-unrestricted"

◆ rtdm_safe_copy_from_user()

int rtdm_safe_copy_from_user ( struct rtdm_fd *  fd,
void *  dst,
const void __user *  src,
size_t  size 
)

Check if read access to user-space memory block and copy it to specified buffer.

Parameters
[in]fdRTDM file descriptor as passed to the invoked device operation handler
[in]dstDestination buffer address
[in]srcAddress of the user-space memory block
[in]sizeSize of the memory block
Returns
0 on success, otherwise:
  • -EFAULT is returned if an invalid memory area was accessed.
Note
This service is a combination of rtdm_read_user_ok and rtdm_copy_from_user.
Tags cobalt-core-tags "task-unrestricted"

◆ rtdm_safe_copy_to_user()

int rtdm_safe_copy_to_user ( struct rtdm_fd *  fd,
void __user *  dst,
const void *  src,
size_t  size 
)

Check if read/write access to user-space memory block is safe and copy specified buffer to it.

Parameters
[in]fdRTDM file descriptor as passed to the invoked device operation handler
[in]dstAddress of the user-space memory block
[in]srcSource buffer address
[in]sizeSize of the memory block
Returns
0 on success, otherwise:
  • -EFAULT is returned if an invalid memory area was accessed.
Note
This service is a combination of rtdm_rw_user_ok and rtdm_copy_to_user.
Tags cobalt-core-tags "task-unrestricted"

◆ rtdm_strncpy_from_user()

int rtdm_strncpy_from_user ( struct rtdm_fd *  fd,
char *  dst,
const char __user *  src,
size_t  count 
)

Copy user-space string to specified buffer.

Parameters
[in]fdRTDM file descriptor as passed to the invoked device operation handler
[in]dstDestination buffer address
[in]srcAddress of the user-space string
[in]countMaximum number of bytes to copy, including the trailing '0'
Returns
Length of the string on success (not including the trailing '0'), otherwise:
  • -EFAULT is returned if an invalid memory area was accessed.
Note
This services already includes a check of the source address, calling rtdm_read_user_ok() for src explicitly is not required.
Tags cobalt-core-tags "task-unrestricted"