/*
|
* Copyright (C) 2009 Philippe Gerum <rpm@xenomai.org>.
|
*
|
* Xenomai is free software; you can redistribute it and/or modify it
|
* under the terms of the GNU General Public License as published by
|
* the Free Software Foundation; either version 2 of the License, or
|
* (at your option) any later version.
|
*
|
* Xenomai is distributed in the hope that it will be useful, but
|
* WITHOUT ANY WARRANTY; without even the implied warranty of
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
* General Public License for more details.
|
*
|
* You should have received a copy of the GNU General Public License
|
* along with Xenomai; if not, write to the Free Software
|
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
|
* 02111-1307, USA.
|
*/
|
#include <cobalt/kernel/heap.h>
|
#include <cobalt/kernel/sched.h>
|
#include <cobalt/kernel/bufd.h>
|
#include <cobalt/kernel/assert.h>
|
#include <asm/xenomai/syscall.h>
|
|
/**
|
* @ingroup cobalt_core
|
* @defgroup cobalt_core_bufd Buffer descriptor
|
*
|
* Abstraction for copying data to/from different address spaces
|
*
|
* A buffer descriptor is a simple abstraction dealing with copy
|
* operations to/from memory buffers which may belong to different
|
* address spaces.
|
*
|
* To this end, the buffer descriptor library provides a small set of
|
* copy routines which are aware of address space restrictions when
|
* moving data, and a generic container type which can hold a
|
* reference to - or cover - a particular memory area, either present
|
* in kernel space, or in any of the existing user memory contexts.
|
*
|
* The goal of the buffer descriptor abstraction is to hide address
|
* space specifics from Xenomai services dealing with memory areas,
|
* allowing them to operate on multiple address spaces seamlessly.
|
*
|
* The common usage patterns are as follows:
|
*
|
* - Implementing a Xenomai syscall returning a bulk of data to the
|
* caller, which may have to be copied back to either kernel or user
|
* space:
|
*
|
* @code
|
* [Syscall implementation]
|
* ssize_t rt_bulk_read_inner(struct xnbufd *bufd)
|
* {
|
* ssize_t ret;
|
* size_t len;
|
* void *bulk;
|
*
|
* bulk = get_next_readable_bulk(&len);
|
* ret = xnbufd_copy_from_kmem(bufd, bulk, min(bufd->b_len, len));
|
* free_bulk(bulk);
|
*
|
* ret = this_may_fail();
|
* if (ret)
|
* xnbufd_invalidate(bufd);
|
*
|
* return ret;
|
* }
|
*
|
* [Kernel wrapper for in-kernel calls]
|
* int rt_bulk_read(void *ptr, size_t len)
|
* {
|
* struct xnbufd bufd;
|
* ssize_t ret;
|
*
|
* xnbufd_map_kwrite(&bufd, ptr, len);
|
* ret = rt_bulk_read_inner(&bufd);
|
* xnbufd_unmap_kwrite(&bufd);
|
*
|
* return ret;
|
* }
|
*
|
* [Userland trampoline for user syscalls]
|
* int __rt_bulk_read(struct pt_regs *regs)
|
* {
|
* struct xnbufd bufd;
|
* void __user *ptr;
|
* ssize_t ret;
|
* size_t len;
|
*
|
* ptr = (void __user *)__xn_reg_arg1(regs);
|
* len = __xn_reg_arg2(regs);
|
*
|
* xnbufd_map_uwrite(&bufd, ptr, len);
|
* ret = rt_bulk_read_inner(&bufd);
|
* xnbufd_unmap_uwrite(&bufd);
|
*
|
* return ret;
|
* }
|
* @endcode
|
*
|
* - Implementing a Xenomai syscall receiving a bulk of data from the
|
* caller, which may have to be read from either kernel or user
|
* space:
|
*
|
* @code
|
* [Syscall implementation]
|
* ssize_t rt_bulk_write_inner(struct xnbufd *bufd)
|
* {
|
* void *bulk = get_free_bulk(bufd->b_len);
|
* return xnbufd_copy_to_kmem(bulk, bufd, bufd->b_len);
|
* }
|
*
|
* [Kernel wrapper for in-kernel calls]
|
* int rt_bulk_write(const void *ptr, size_t len)
|
* {
|
* struct xnbufd bufd;
|
* ssize_t ret;
|
*
|
* xnbufd_map_kread(&bufd, ptr, len);
|
* ret = rt_bulk_write_inner(&bufd);
|
* xnbufd_unmap_kread(&bufd);
|
*
|
* return ret;
|
* }
|
*
|
* [Userland trampoline for user syscalls]
|
* int __rt_bulk_write(struct pt_regs *regs)
|
* {
|
* struct xnbufd bufd;
|
* void __user *ptr;
|
* ssize_t ret;
|
* size_t len;
|
*
|
* ptr = (void __user *)__xn_reg_arg1(regs);
|
* len = __xn_reg_arg2(regs);
|
*
|
* xnbufd_map_uread(&bufd, ptr, len);
|
* ret = rt_bulk_write_inner(&bufd);
|
* xnbufd_unmap_uread(&bufd);
|
*
|
* return ret;
|
* }
|
* @endcode
|
*
|
*@{*/
|
|
/**
|
* @fn void xnbufd_map_kread(struct xnbufd *bufd, const void *ptr, size_t len)
|
* @brief Initialize a buffer descriptor for reading from kernel memory.
|
*
|
* The new buffer descriptor may be used to copy data from kernel
|
* memory. This routine should be used in pair with
|
* xnbufd_unmap_kread().
|
*
|
* @param bufd The address of the buffer descriptor which will map a
|
* @a len bytes kernel memory area, starting from @a ptr.
|
*
|
* @param ptr The start of the kernel buffer to map.
|
*
|
* @param len The length of the kernel buffer starting at @a ptr.
|
*
|
* @coretags{unrestricted}
|
*/
|
|
/**
|
* @fn void xnbufd_map_kwrite(struct xnbufd *bufd, void *ptr, size_t len)
|
* @brief Initialize a buffer descriptor for writing to kernel memory.
|
*
|
* The new buffer descriptor may be used to copy data to kernel
|
* memory. This routine should be used in pair with
|
* xnbufd_unmap_kwrite().
|
*
|
* @param bufd The address of the buffer descriptor which will map a
|
* @a len bytes kernel memory area, starting from @a ptr.
|
*
|
* @param ptr The start of the kernel buffer to map.
|
*
|
* @param len The length of the kernel buffer starting at @a ptr.
|
*
|
* @coretags{unrestricted}
|
*/
|
void xnbufd_map_kmem(struct xnbufd *bufd, void *ptr, size_t len)
|
{
|
bufd->b_ptr = ptr;
|
bufd->b_len = len;
|
bufd->b_mm = NULL;
|
bufd->b_off = 0;
|
bufd->b_carry = NULL;
|
}
|
EXPORT_SYMBOL_GPL(xnbufd_map_kmem);
|
|
/**
|
* @fn void xnbufd_map_uread(struct xnbufd *bufd, const void __user *ptr, size_t len)
|
* @brief Initialize a buffer descriptor for reading from user memory.
|
*
|
* The new buffer descriptor may be used to copy data from user
|
* memory. This routine should be used in pair with
|
* xnbufd_unmap_uread().
|
*
|
* @param bufd The address of the buffer descriptor which will map a
|
* @a len bytes user memory area, starting from @a ptr. @a ptr is
|
* never dereferenced directly, since it may refer to a buffer that
|
* lives in another address space.
|
*
|
* @param ptr The start of the user buffer to map.
|
*
|
* @param len The length of the user buffer starting at @a ptr.
|
*
|
* @coretags{task-unrestricted}
|
*/
|
|
/**
|
* @fn void xnbufd_map_uwrite(struct xnbufd *bufd, void __user *ptr, size_t len)
|
* @brief Initialize a buffer descriptor for writing to user memory.
|
*
|
* The new buffer descriptor may be used to copy data to user
|
* memory. This routine should be used in pair with
|
* xnbufd_unmap_uwrite().
|
*
|
* @param bufd The address of the buffer descriptor which will map a
|
* @a len bytes user memory area, starting from @a ptr. @a ptr is
|
* never dereferenced directly, since it may refer to a buffer that
|
* lives in another address space.
|
*
|
* @param ptr The start of the user buffer to map.
|
*
|
* @param len The length of the user buffer starting at @a ptr.
|
*
|
* @coretags{task-unrestricted}
|
*/
|
|
void xnbufd_map_umem(struct xnbufd *bufd, void __user *ptr, size_t len)
|
{
|
bufd->b_ptr = ptr;
|
bufd->b_len = len;
|
bufd->b_mm = current->mm;
|
bufd->b_off = 0;
|
bufd->b_carry = NULL;
|
}
|
EXPORT_SYMBOL_GPL(xnbufd_map_umem);
|
|
/**
|
* @fn ssize_t xnbufd_copy_to_kmem(void *to, struct xnbufd *bufd, size_t len)
|
* @brief Copy memory covered by a buffer descriptor to kernel memory.
|
*
|
* This routine copies @a len bytes from the area referred to by the
|
* buffer descriptor @a bufd to the kernel memory area @a to.
|
* xnbufd_copy_to_kmem() tracks the read offset within the source
|
* memory internally, so that it may be called several times in a
|
* loop, until the entire memory area is loaded.
|
*
|
* The source address space is dealt with, according to the following
|
* rules:
|
*
|
* - if @a bufd refers to readable kernel area (i.e. see
|
* xnbufd_map_kread()), the copy is immediately and fully performed
|
* with no restriction.
|
*
|
* - if @a bufd refers to a readable user area (i.e. see
|
* xnbufd_map_uread()), the copy is performed only if that area
|
* lives in the currently active address space, and only if the
|
* caller may sleep Linux-wise to process any potential page fault
|
* which may arise while reading from that memory.
|
*
|
* - any attempt to read from @a bufd from a non-suitable context is
|
* considered as a bug, and will raise a panic assertion when the
|
* nucleus is compiled in debug mode.
|
*
|
* @param to The start address of the kernel memory to copy to.
|
*
|
* @param bufd The address of the buffer descriptor covering the user
|
* memory to copy data from.
|
*
|
* @param len The length of the user memory to copy from @a bufd.
|
*
|
* @return The number of bytes read so far from the memory area
|
* covered by @a ubufd. Otherwise:
|
*
|
* - -EINVAL is returned upon attempt to read from the user area from
|
* an invalid context. This error is only returned when the debug
|
* mode is disabled; otherwise a panic assertion is raised.
|
*
|
* @coretags{task-unrestricted}
|
*
|
* @note Calling this routine while holding the nklock and/or running
|
* with interrupts disabled is invalid, and doing so will trigger a
|
* debug assertion.
|
*
|
* This routine may switch the caller to secondary mode if a page
|
* fault occurs while reading from the user area. For that reason,
|
* xnbufd_copy_to_kmem() may only be called from a preemptible section
|
* (Linux-wise).
|
*/
|
ssize_t xnbufd_copy_to_kmem(void *to, struct xnbufd *bufd, size_t len)
|
{
|
caddr_t from;
|
|
thread_only();
|
|
if (len == 0)
|
goto out;
|
|
from = bufd->b_ptr + bufd->b_off;
|
|
/*
|
* If the descriptor covers a source buffer living in the
|
* kernel address space, we may read from it directly.
|
*/
|
if (bufd->b_mm == NULL) {
|
memcpy(to, from, len);
|
goto advance_offset;
|
}
|
|
/*
|
* We want to read data from user-space, check whether:
|
* 1) the source buffer lies in the current address space,
|
* 2) we may fault while reading from the buffer directly.
|
*
|
* If we can't reach the buffer, or the current context may
|
* not fault while reading data from it, copy_from_user() is
|
* not an option and we have a bug somewhere, since there is
|
* no way we could fetch the data to kernel space immediately.
|
*
|
* Note that we don't check for non-preemptible Linux context
|
* here, since the source buffer would live in kernel space in
|
* such a case.
|
*/
|
if (current->mm == bufd->b_mm) {
|
preemptible_only();
|
if (cobalt_copy_from_user(to, (void __user *)from, len))
|
return -EFAULT;
|
goto advance_offset;
|
}
|
|
XENO_BUG(COBALT);
|
|
return -EINVAL;
|
|
advance_offset:
|
bufd->b_off += len;
|
out:
|
return (ssize_t)bufd->b_off;
|
}
|
EXPORT_SYMBOL_GPL(xnbufd_copy_to_kmem);
|
|
/**
|
* @fn ssize_t xnbufd_copy_from_kmem(struct xnbufd *bufd, void *from, size_t len)
|
* @brief Copy kernel memory to the area covered by a buffer descriptor.
|
*
|
* This routine copies @a len bytes from the kernel memory starting at
|
* @a from to the area referred to by the buffer descriptor @a
|
* bufd. xnbufd_copy_from_kmem() tracks the write offset within the
|
* destination memory internally, so that it may be called several
|
* times in a loop, until the entire memory area is stored.
|
*
|
* The destination address space is dealt with, according to the
|
* following rules:
|
*
|
* - if @a bufd refers to a writable kernel area (i.e. see
|
* xnbufd_map_kwrite()), the copy is immediatly and fully performed
|
* with no restriction.
|
*
|
* - if @a bufd refers to a writable user area (i.e. see
|
* xnbufd_map_uwrite()), the copy is performed only if that area
|
* lives in the currently active address space, and only if the
|
* caller may sleep Linux-wise to process any potential page fault
|
* which may arise while writing to that memory.
|
*
|
* - if @a bufd refers to a user area which may not be immediately
|
* written to from the current context, the copy is postponed until
|
* xnbufd_unmap_uwrite() is invoked for @a ubufd, at which point the
|
* copy will take place. In such a case, the source memory is
|
* transferred to a carry over buffer allocated internally; this
|
* operation may lead to request dynamic memory from the nucleus
|
* heap if @a len is greater than 64 bytes.
|
*
|
* @param bufd The address of the buffer descriptor covering the user
|
* memory to copy data to.
|
*
|
* @param from The start address of the kernel memory to copy from.
|
*
|
* @param len The length of the kernel memory to copy to @a bufd.
|
*
|
* @return The number of bytes written so far to the memory area
|
* covered by @a ubufd. Otherwise,
|
*
|
* - -ENOMEM is returned when no memory is available from the nucleus
|
* heap to allocate the carry over buffer.
|
*
|
* @coretags{unrestricted}
|
*
|
* @note Calling this routine while holding the nklock and/or running
|
* with interrupts disabled is invalid, and doing so will trigger a
|
* debug assertion.
|
*
|
* This routine may switch the caller to secondary mode if a page
|
* fault occurs while reading from the user area. For that reason,
|
* xnbufd_copy_to_kmem() may only be called from a preemptible section
|
* (Linux-wise).
|
*/
|
ssize_t xnbufd_copy_from_kmem(struct xnbufd *bufd, void *from, size_t len)
|
{
|
caddr_t to;
|
|
thread_only();
|
|
if (len == 0)
|
goto out;
|
|
to = bufd->b_ptr + bufd->b_off;
|
|
/*
|
* If the descriptor covers a destination buffer living in the
|
* kernel address space, we may copy to it directly.
|
*/
|
if (bufd->b_mm == NULL)
|
goto direct_copy;
|
|
/*
|
* We want to pass data to user-space, check whether:
|
* 1) the destination buffer lies in the current address space,
|
* 2) we may fault while writing to the buffer directly.
|
*
|
* If we can't reach the buffer, or the current context may
|
* not fault while copying data to it, copy_to_user() is not
|
* an option and we have to convey the data from kernel memory
|
* through the carry over buffer.
|
*
|
* Note that we don't check for non-preemptible Linux context
|
* here: feeding a RT activity with data from a non-RT context
|
* is wrong in the first place, so never mind.
|
*/
|
if (current->mm == bufd->b_mm) {
|
preemptible_only();
|
if (cobalt_copy_to_user((void __user *)to, from, len))
|
return -EFAULT;
|
goto advance_offset;
|
}
|
|
/*
|
* We need a carry over buffer to convey the data to
|
* user-space. xnbufd_unmap_uwrite() should be called on the
|
* way back to user-space to update the destination buffer
|
* from the carry over area.
|
*/
|
if (bufd->b_carry == NULL) {
|
/*
|
* Try to use the fast carry over area available
|
* directly from the descriptor for short messages, to
|
* save a dynamic allocation request.
|
*/
|
if (bufd->b_len <= sizeof(bufd->b_buf))
|
bufd->b_carry = bufd->b_buf;
|
else {
|
bufd->b_carry = xnmalloc(bufd->b_len);
|
if (bufd->b_carry == NULL)
|
return -ENOMEM;
|
}
|
to = bufd->b_carry;
|
} else
|
to = bufd->b_carry + bufd->b_off;
|
|
direct_copy:
|
memcpy(to, from, len);
|
|
advance_offset:
|
bufd->b_off += len;
|
out:
|
return (ssize_t)bufd->b_off;
|
}
|
EXPORT_SYMBOL_GPL(xnbufd_copy_from_kmem);
|
|
/**
|
* @fn void xnbufd_unmap_uread(struct xnbufd *bufd)
|
* @brief Finalize a buffer descriptor obtained from xnbufd_map_uread().
|
*
|
* This routine finalizes a buffer descriptor previously initialized
|
* by a call to xnbufd_map_uread(), to read data from a user area.
|
*
|
* @param bufd The address of the buffer descriptor to finalize.
|
*
|
* @return The number of bytes read so far from the memory area
|
* covered by @a ubufd.
|
*
|
* @coretags{task-unrestricted}
|
*
|
* @note Calling this routine while holding the nklock and/or running
|
* with interrupts disabled is invalid, and doing so will trigger a
|
* debug assertion.
|
*/
|
ssize_t xnbufd_unmap_uread(struct xnbufd *bufd)
|
{
|
preemptible_only();
|
|
#ifdef CONFIG_XENO_OPT_DEBUG_COBALT
|
bufd->b_ptr = (caddr_t)-1;
|
#endif
|
return bufd->b_off;
|
}
|
EXPORT_SYMBOL_GPL(xnbufd_unmap_uread);
|
|
/**
|
* @fn void xnbufd_unmap_uwrite(struct xnbufd *bufd)
|
* @brief Finalize a buffer descriptor obtained from xnbufd_map_uwrite().
|
*
|
* This routine finalizes a buffer descriptor previously initialized
|
* by a call to xnbufd_map_uwrite(), to write data to a user area.
|
*
|
* The main action taken is to write the contents of the kernel memory
|
* area passed to xnbufd_copy_from_kmem() whenever the copy operation
|
* was postponed at that time; the carry over buffer is eventually
|
* released as needed. If xnbufd_copy_from_kmem() was allowed to copy
|
* to the destination user memory at once, then xnbufd_unmap_uwrite()
|
* leads to a no-op.
|
*
|
* @param bufd The address of the buffer descriptor to finalize.
|
*
|
* @return The number of bytes written so far to the memory area
|
* covered by @a ubufd.
|
*
|
* @coretags{task-unrestricted}
|
*
|
* @note Calling this routine while holding the nklock and/or running
|
* with interrupts disabled is invalid, and doing so will trigger a
|
* debug assertion.
|
*/
|
ssize_t xnbufd_unmap_uwrite(struct xnbufd *bufd)
|
{
|
ssize_t ret = 0;
|
void __user *to;
|
void *from;
|
size_t len;
|
|
preemptible_only();
|
|
len = bufd->b_off;
|
|
if (bufd->b_carry == NULL)
|
/* Copy took place directly. Fine. */
|
goto done;
|
|
/*
|
* Something was written to the carry over area, copy the
|
* contents to user-space, then release the area if needed.
|
*/
|
to = (void __user *)bufd->b_ptr;
|
from = bufd->b_carry;
|
ret = cobalt_copy_to_user(to, from, len);
|
|
if (bufd->b_len > sizeof(bufd->b_buf))
|
xnfree(bufd->b_carry);
|
done:
|
#ifdef CONFIG_XENO_OPT_DEBUG_COBALT
|
bufd->b_ptr = (caddr_t)-1;
|
#endif
|
return ret ?: (ssize_t)len;
|
}
|
EXPORT_SYMBOL_GPL(xnbufd_unmap_uwrite);
|
|
/**
|
* @fn void xnbufd_reset(struct xnbufd *bufd)
|
* @brief Reset a buffer descriptor.
|
*
|
* The buffer descriptor is reset, so that all data already copied is
|
* forgotten. Any carry over buffer allocated is kept, though.
|
*
|
* @param bufd The address of the buffer descriptor to reset.
|
*
|
* @coretags{unrestricted}
|
*/
|
|
/**
|
* @fn void xnbufd_invalidate(struct xnbufd *bufd)
|
* @brief Invalidate a buffer descriptor.
|
*
|
* The buffer descriptor is invalidated, making it unusable for
|
* further copy operations. If an outstanding carry over buffer was
|
* allocated by a previous call to xnbufd_copy_from_kmem(), it is
|
* immediately freed so that no data transfer will happen when the
|
* descriptor is finalized.
|
*
|
* The only action that may subsequently be performed on an
|
* invalidated descriptor is calling the relevant unmapping routine
|
* for it. For that reason, xnbufd_invalidate() should be invoked on
|
* the error path when data may have been transferred to the carry
|
* over buffer.
|
*
|
* @param bufd The address of the buffer descriptor to invalidate.
|
*
|
* @coretags{unrestricted}
|
*/
|
void xnbufd_invalidate(struct xnbufd *bufd)
|
{
|
#ifdef CONFIG_XENO_OPT_DEBUG_COBALT
|
bufd->b_ptr = (caddr_t)-1;
|
#endif
|
if (bufd->b_carry) {
|
if (bufd->b_len > sizeof(bufd->b_buf))
|
xnfree(bufd->b_carry);
|
bufd->b_carry = NULL;
|
}
|
bufd->b_off = 0;
|
}
|
EXPORT_SYMBOL_GPL(xnbufd_invalidate);
|
|
/**
|
* @fn void xnbufd_unmap_kread(struct xnbufd *bufd)
|
* @brief Finalize a buffer descriptor obtained from xnbufd_map_kread().
|
*
|
* This routine finalizes a buffer descriptor previously initialized
|
* by a call to xnbufd_map_kread(), to read data from a kernel area.
|
*
|
* @param bufd The address of the buffer descriptor to finalize.
|
*
|
* @return The number of bytes read so far from the memory area
|
* covered by @a ubufd.
|
*
|
* @coretags{task-unrestricted}
|
*/
|
ssize_t xnbufd_unmap_kread(struct xnbufd *bufd)
|
{
|
#ifdef CONFIG_XENO_OPT_DEBUG_COBALT
|
bufd->b_ptr = (caddr_t)-1;
|
#endif
|
return bufd->b_off;
|
}
|
EXPORT_SYMBOL_GPL(xnbufd_unmap_kread);
|
|
/**
|
* @fn void xnbufd_unmap_kwrite(struct xnbufd *bufd)
|
* @brief Finalize a buffer descriptor obtained from xnbufd_map_kwrite().
|
*
|
* This routine finalizes a buffer descriptor previously initialized
|
* by a call to xnbufd_map_kwrite(), to write data to a kernel area.
|
*
|
* @param bufd The address of the buffer descriptor to finalize.
|
*
|
* @return The number of bytes written so far to the memory area
|
* covered by @a ubufd.
|
*
|
* @coretags{task-unrestricted}
|
*/
|
ssize_t xnbufd_unmap_kwrite(struct xnbufd *bufd)
|
{
|
#ifdef CONFIG_XENO_OPT_DEBUG_COBALT
|
bufd->b_ptr = (caddr_t)-1;
|
#endif
|
return bufd->b_off;
|
}
|
EXPORT_SYMBOL_GPL(xnbufd_unmap_kwrite);
|
|
/** @} */
|
