Utility Services
[Driver Development API]

Collaboration diagram for Utility Services:


Functions

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_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_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.

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.

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_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:
0 on success, 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.


Generated on Sat Sep 3 12:33:01 2005 for RTAI Fusion API by  doxygen 1.4.2