Utility Services
[Driver Development API]

Functions
int	rtdm_mmap_to_user (rtdm_user_info_t *user_info, 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.
int	rtdm_iomap_to_user (rtdm_user_info_t *user_info, unsigned long 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.
int	rtdm_munmap (rtdm_user_info_t *user_info, void *ptr, size_t len)
	Unmap a user memory range.
void	rtdm_printk (const char *format,...)
	Real-time safe message printing on kernel console.
void *	rtdm_malloc (size_t size)
	Allocate memory block in real-time context.
void	rtdm_free (void *ptr)
	Release real-time memory block.
int	rtdm_read_user_ok (rtdm_user_info_t *user_info, const void __user *ptr, size_t size)
	Check if read access to user-space memory block is safe.
int	rtdm_rw_user_ok (rtdm_user_info_t *user_info, const void __user *ptr, size_t size)
	Check if read/write access to user-space memory block is safe.
int	rtdm_copy_from_user (rtdm_user_info_t *user_info, void *dst, const void __user *src, size_t size)
	Copy user-space memory block to specified buffer.
int	rtdm_safe_copy_from_user (rtdm_user_info_t *user_info, void *dst, const void __user *src, size_t size)
	Check if read access to user-space memory block and copy it to specified buffer.
int	rtdm_copy_to_user (rtdm_user_info_t *user_info, void __user *dst, const void *src, size_t size)
	Copy specified buffer to user-space memory block.
int	rtdm_safe_copy_to_user (rtdm_user_info_t *user_info, 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.
int	rtdm_strncpy_from_user (rtdm_user_info_t *user_info, char *dst, const char __user *src, size_t count)
	Copy user-space string to specified buffer.
int	rtdm_in_rt_context (void)
	Test if running in a real-time task.

---

Function Documentation

int rtdm_copy_from_user (  rtdm_user_info_t *  user_info, void *  dst, const void __user *  src, size_t  size )

Copy user-space memory block to specified buffer. Parameters: [in]  user_info  User information pointer as passed to the invoked device operation handler [in]  dst  Destination buffer address [in]  src  Address of the user-space memory block [in]  size  Size 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. Environments: This service can be called from: Kernel module initialization/cleanup code Kernel-based task User-space task (RT, non-RT) Rescheduling: never.

int rtdm_copy_to_user (  rtdm_user_info_t *  user_info, void __user *  dst, const void *  src, size_t  size )

Copy specified buffer to user-space memory block. Parameters: [in]  user_info  User information pointer as passed to the invoked device operation handler [in]  dst  Address of the user-space memory block [in]  src  Source buffer address [in]  size  Size 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. Environments: This service can be called from: Kernel module initialization/cleanup code Kernel-based task User-space task (RT, non-RT) Rescheduling: never.

void rtdm_free (  void *  ptr  )

Release real-time memory block. Parameters: [in]  ptr  Pointer to memory block as returned by rtdm_malloc() Environments: This service can be called from: Kernel module initialization/cleanup code Interrupt service routine (consider the overhead!) Kernel-based task User-space task (RT, non-RT) Rescheduling: never.

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. Environments: This service can be called from: Kernel module initialization/cleanup code Kernel-based task User-space task (RT, non-RT) Rescheduling: never.

int rtdm_iomap_to_user (  rtdm_user_info_t *  user_info, unsigned long  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]  user_info  User information pointer as passed to the invoked device operation handler [in]  src_addr  physical I/O address to be mapped [in]  len  Length of the memory range [in]  prot  Protection flags for the user's memory range, typically either PROT_READ or PROT_READ|PROT_WRITE [in,out]  pptr  Address of a pointer containing the desired user address or NULL on entry and the finally assigned address on return [in]  vm_ops  vm_operations to be executed on the vma_area of the user memory range or NULL [in]  vm_private_data  Private data to be stored in the vma_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 user memory range again. One is explicite unmapping via rtdm_munmap(), either performed when the user requests it via an IOCTL etc. or when the related device is closed. The other is automatic unmapping, triggered by the user invoking standard munmap() or by the termination of the related process. To track release of the mapping and therefore relinquishment of the referenced physical memory, the caller of rtdm_iomap_to_user() can pass a vm_operations_struct on invocation, defining a close handler for the vm_area. See Linux documentaion (e.g. Linux Device Drivers book) on virtual memory management for details. Environments: This service can be called from: Kernel module initialization/cleanup code User-space task (non-RT) Rescheduling: possible.

void* rtdm_malloc (  size_t  size  )

Allocate memory block in real-time context. Parameters: [in]  size  Requested size of the memory block Returns: The pointer to the allocated block is returned on success, NULL otherwise. Environments: This service can be called from: Kernel module initialization/cleanup code Interrupt service routine (consider the overhead!) Kernel-based task User-space task (RT, non-RT) Rescheduling: never.

int rtdm_mmap_to_user (  rtdm_user_info_t *  user_info, 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]  user_info  User information pointer as passed to the invoked device operation handler [in]  src_addr  Kernel virtual address to be mapped [in]  len  Length of the memory range [in]  prot  Protection flags for the user's memory range, typically either PROT_READ or PROT_READ|PROT_WRITE [in,out]  pptr  Address of a pointer containing the desired user address or NULL on entry and the finally assigned address on return [in]  vm_ops  vm_operations to be executed on the vma_area of the user memory range or NULL [in]  vm_private_data  Private data to be stored in the vma_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 user memory range again. One is explicite unmapping via rtdm_munmap(), either performed when the user requests it via an IOCTL etc. or when the related device is closed. The other is automatic unmapping, triggered by the user invoking standard munmap() or by the termination of the related process. To track release of the mapping and therefore relinquishment of the referenced physical memory, the caller of rtdm_mmap_to_user() can pass a vm_operations_struct on invocation, defining a close handler for the vm_area. See Linux documentaion (e.g. Linux Device Drivers book) on virtual memory management for details. Environments: This service can be called from: Kernel module initialization/cleanup code User-space task (non-RT) Rescheduling: possible.

int rtdm_munmap (  rtdm_user_info_t *  user_info, void *  ptr, size_t  len )

Unmap a user memory range. Parameters: [in]  user_info  User information pointer as passed to rtdm_mmap_to_user() when requesting to map the memory range [in]  ptr  User address or the memory range [in]  len  Length 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. Environments: This service can be called from: Kernel module initialization/cleanup code User-space task (non-RT) Rescheduling: possible.

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

Real-time safe message printing on kernel console. Parameters: [in]  format  Format 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. Environments: This service can be called from: Kernel module initialization/cleanup code Interrupt service routine (consider the overhead!) Kernel-based task User-space task (RT, non-RT) Rescheduling: never in real-time context, possible in non-real-time environments.

int rtdm_read_user_ok (  rtdm_user_info_t *  user_info, const void __user *  ptr, size_t  size )

Check if read access to user-space memory block is safe. Parameters: [in]  user_info  User information pointer as passed to the invoked device operation handler [in]  ptr  Address of the user-provided memory block [in]  size  Size of the memory block Returns: Non-zero is return when it is safe to read from the specified memory block, 0 otherwise. Environments: This service can be called from: Kernel module initialization/cleanup code Kernel-based task User-space task (RT, non-RT) Rescheduling: never.

int rtdm_rw_user_ok (  rtdm_user_info_t *  user_info, const void __user *  ptr, size_t  size )

Check if read/write access to user-space memory block is safe. Parameters: [in]  user_info  User information pointer as passed to the invoked device operation handler [in]  ptr  Address of the user-provided memory block [in]  size  Size 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. Environments: This service can be called from: Kernel module initialization/cleanup code Kernel-based task User-space task (RT, non-RT) Rescheduling: never.

int rtdm_safe_copy_from_user (  rtdm_user_info_t *  user_info, 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]  user_info  User information pointer as passed to the invoked device operation handler [in]  dst  Destination buffer address [in]  src  Address of the user-space memory block [in]  size  Size 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. Environments: This service can be called from: Kernel module initialization/cleanup code Kernel-based task User-space task (RT, non-RT) Rescheduling: never.

int rtdm_safe_copy_to_user (  rtdm_user_info_t *  user_info, 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]  user_info  User information pointer as passed to the invoked device operation handler [in]  dst  Address of the user-space memory block [in]  src  Source buffer address [in]  size  Size 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. Environments: This service can be called from: Kernel module initialization/cleanup code Kernel-based task User-space task (RT, non-RT) Rescheduling: never.

int rtdm_strncpy_from_user (  rtdm_user_info_t *  user_info, char *  dst, const char __user *  src, size_t  count )

Copy user-space string to specified buffer. Parameters: [in]  user_info  User information pointer as passed to the invoked device operation handler [in]  dst  Destination buffer address [in]  src  Address of the user-space string [in]  count  Maximum 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. Environments: This service can be called from: Kernel module initialization/cleanup code Kernel-based task User-space task (RT, non-RT) Rescheduling: never.

---