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]	fd	RTDM file descriptor 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.

Tags: task-unrestricted

Referenced by rtdm_ratelimit().

◆ 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]	fd	RTDM file descriptor 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.

Tags: task-unrestricted

Referenced by rtdm_ratelimit().

◆ rtdm_free()

void rtdm_free ( void * ptr )

Release real-time memory block.

Parameters

[in] ptr Pointer to memory block as returned by rtdm_malloc()

Tags: unrestricted

Referenced by rtdm_ratelimit().

◆ 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: unrestricted

Referenced by rtdm_ratelimit().

◆ 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]	fd	RTDM file descriptor 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 vm_area of the user memory range or NULL
[in]	vm_private_data	Private 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: secondary-only

◆ rtdm_malloc()

void* rtdm_malloc ( size_t size )

Allocate memory block.

Parameters

[in] size Requested size of the memory block

Returns: The pointer to the allocated block is returned on success, NULL otherwise.

Tags: unrestricted

Referenced by a4l_alloc_subd(), and rtdm_ratelimit().

◆ 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]	vma	The VMA descriptor to receive the mapping.
[in]	pa	The 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: 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]	vma	The VMA descriptor to receive the mapping.
[in]	va	The 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: 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]	fd	RTDM file descriptor 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 vm_area of the user memory range or NULL
[in]	vm_private_data	Private 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: 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]	vma	The VMA descriptor to receive the mapping.
[in]	va	The 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: secondary-only

◆ rtdm_munmap()

int rtdm_munmap	(	void *	ptr,
		size_t	len
	)

Unmap a user memory range.

Parameters

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

Tags: secondary-only

◆ rtdm_printk()

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.

Tags: unrestricted

Referenced by rtdm_ratelimit().

◆ rtdm_printk_ratelimited()

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

Real-time safe rate-limited 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.

Tags: unrestricted

Referenced by rtdm_ratelimit().

◆ 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]	rs	rtdm_ratelimit_state data
[in]	func	name of calling function

Returns: 0 means callback will be suppressed and 1 means go ahead and do it

Tags: unrestricted

References rtdm_clock_read(), rtdm_copy_from_user(), rtdm_copy_to_user(), rtdm_free(), rtdm_in_rt_context(), rtdm_lock_get_irqsave, rtdm_lock_put_irqrestore(), rtdm_malloc(), rtdm_printk(), rtdm_printk_ratelimited(), rtdm_read_user_ok(), rtdm_rt_capable(), rtdm_rw_user_ok(), rtdm_safe_copy_from_user(), rtdm_safe_copy_to_user(), and rtdm_strncpy_from_user().

◆ 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]	fd	RTDM file descriptor 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.

Tags: task-unrestricted

Referenced by rtdm_ratelimit().

◆ 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] fd RTDM 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: unrestricted

Referenced by rtdm_ratelimit().

◆ 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]	fd	RTDM file descriptor 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.

Tags: task-unrestricted

Referenced by rtdm_ratelimit().

◆ 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]	fd	RTDM file descriptor 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.

Tags: task-unrestricted

Referenced by rtdm_ratelimit().

◆ 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]	fd	RTDM file descriptor 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.

Tags: task-unrestricted

Referenced by rtdm_ratelimit().

◆ 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]	fd	RTDM file descriptor 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.

Tags: task-unrestricted

Referenced by rtdm_ratelimit().

Functions

Detailed Description

Function Documentation

◆ rtdm_copy_from_user()

◆ rtdm_copy_to_user()

◆ rtdm_free()

◆ rtdm_in_rt_context()

◆ rtdm_iomap_to_user()

◆ rtdm_malloc()

◆ rtdm_mmap_iomem()

◆ rtdm_mmap_kmem()

◆ rtdm_mmap_to_user()

◆ rtdm_mmap_vmem()

◆ rtdm_munmap()

◆ rtdm_printk()

◆ rtdm_printk_ratelimited()

◆ rtdm_ratelimit()

◆ rtdm_read_user_ok()

◆ rtdm_rt_capable()

◆ rtdm_rw_user_ok()

◆ rtdm_safe_copy_from_user()

◆ rtdm_safe_copy_to_user()

◆ rtdm_strncpy_from_user()