staging: Intel Restricted Access Region Handler

The Intel Restricted Access Region Handler provides a buffer allocation
mechanism to RAR users.  Since the intended usage model is to lock out
CPU access to RAR (the CPU will not be able to access RAR memory), this
driver does not access RAR memory, and merely keeps track of what areas
of RAR memory are in use.  It has it's own simple allocator that does
not rely on existing kernel allocators (SLAB, etc) since those
allocators are too tightly coupled with the paging mechanism, which isn't
needed for the intended RAR use cases.

An mmap() implementation is provided for debugging purposes to simplify
RAR memory access from the user space.  However, it will effectively be
a no-op when RAR access control is enabled since the CPU will not be
able to access RAR.

This driver should not be confused with the rar_register driver.  That
driver exposes an interface to access RAR registers on the Moorestown
platform.  The RAR handler driver relies on the rar_register driver for
low level RAR register reads and writes.

This patch was generated and built against the latest linux-2.6 master
branch.
Signed-off-by: Ossama Othman <ossama.othman@intel.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>

drivers/staging/Kconfig

@@ -109,6 +109,8 @@ source "drivers/staging/vme/Kconfig"
 
 source "drivers/staging/rar_register/Kconfig"
 
+source "drivers/staging/memrar/Kconfig"
+
 source "drivers/staging/sep/Kconfig"
 
 source "drivers/staging/iio/Kconfig"

drivers/staging/Makefile

@@ -35,6 +35,7 @@ obj-$(CONFIG_FB_UDL)		+= udlfb/
 obj-$(CONFIG_HYPERV)		+= hv/
 obj-$(CONFIG_VME_BUS)		+= vme/
 obj-$(CONFIG_RAR_REGISTER)	+= rar_register/
+obj-$(CONFIG_MRST_RAR_HANDLER)	+= memrar/
 obj-$(CONFIG_DX_SEP)		+= sep/
 obj-$(CONFIG_IIO)		+= iio/
 obj-$(CONFIG_RAMZSWAP)		+= ramzswap/

drivers/staging/memrar/Kconfig

+config MRST_RAR_HANDLER
+	tristate "RAR handler driver for Intel Moorestown platform"
+	select RAR_REGISTER
+	---help---
+	  This driver provides a memory management interface to
+	  restricted access regions (RAR) available on the Intel
+	  Moorestown platform.
+
+	  Once locked down, restricted access regions are only
+	  accessible by specific hardware on the platform.  The x86
+	  CPU is typically not one of those platforms.  As such this
+	  driver does not access RAR, and only provides a buffer
+	  allocation/bookkeeping mechanism.
+
+	  If unsure, say N.

drivers/staging/memrar/Makefile

+obj-$(CONFIG_MRST_RAR_HANDLER)	+= memrar.o
+memrar-y			:= memrar_allocator.o memrar_handler.o

drivers/staging/memrar/TODO

+RAR Handler (memrar) Driver TODO Items
+======================================
+
+Maintainer: Ossama Othman <ossama.othman@intel.com>
+
+memrar.h
+--------
+1. This header exposes the driver's user space and kernel space
+   interfaces.  It should be moved to <linux/rar/memrar.h>, or
+   something along those lines, when this memrar driver is moved out
+   of `staging'.
+     a. It would be ideal if staging/rar_register/rar_register.h was
+        moved to the same directory.
+
+memrar_allocator.[ch]
+---------------------
+1. Address potential fragmentation issues with the memrar_allocator.
+
+2. Hide struct memrar_allocator details/fields.  They need not be
+   exposed to the user.
+     a. Forward declare struct memrar_allocator.
+     b. Move all three struct definitions to `memrar_allocator.c'
+        source file.
+     c. Add a memrar_allocator_largest_free_area() function, or
+        something like that to get access to the value of the struct
+        memrar_allocator "largest_free_area" field.  This allows the
+        struct memrar_allocator fields to be completely hidden from
+        the user.  The memrar_handler code really only needs this for
+        statistic gathering on-demand.
+     d. Do the same for the "capacity" field as the
+        "largest_free_area" field.
+
+3. Move memrar_allocator.* to kernel `lib' directory since it is HW
+   neutral.
+     a. Alternatively, use lib/genalloc.c instead.
+     b. A kernel port of Doug Lea's malloc() implementation may also
+        be an option.
+
+memrar_handler.c
+----------------
+1. Split user space interface (ioctl code) from core/kernel code,
+   e.g.:
+     memrar_handler.c -> memrar_core.c, memrar_user.c

drivers/staging/memrar/memrar.h

+/*
+ *      RAR Handler (/dev/memrar) internal driver API.
+ *      Copyright (C) 2010 Intel Corporation. All rights reserved.
+ *
+ *      This program is free software; you can redistribute it and/or
+ *      modify it under the terms of version 2 of the GNU General
+ *      Public License as published by the Free Software Foundation.
+ *
+ *      This program 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 this program; if not, write to the Free
+ *      Software Foundation, Inc., 59 Temple Place - Suite 330,
+ *      Boston, MA  02111-1307, USA.
+ *      The full GNU General Public License is included in this
+ *      distribution in the file called COPYING.
+ */
+
+
+#ifndef _MEMRAR_H
+#define _MEMRAR_H
+
+#include <linux/ioctl.h>
+#include <linux/types.h>
+
+
+/**
+ * struct RAR_stat - RAR statistics structure
+ * @type:		Type of RAR memory (e.g., audio vs. video)
+ * @capacity:		Total size of RAR memory region.
+ * @largest_block_size:	Size of the largest reservable block.
+ *
+ * This structure is used for RAR_HANDLER_STAT ioctl and for the
+ * RAR_get_stat() user space wrapper function.
+ */
+struct RAR_stat {
+	__u32 type;
+	__u32 capacity;
+	__u32 largest_block_size;
+};
+
+
+/**
+ * struct RAR_block_info - user space struct that describes RAR buffer
+ * @type:	Type of RAR memory (e.g., audio vs. video)
+ * @size:	Requested size of a block to be reserved in RAR.
+ * @handle:	Handle that can be used to refer to reserved block.
+ *
+ * This is the basic structure exposed to the user space that
+ * describes a given RAR buffer.  The buffer's underlying bus address
+ * is not exposed to the user.  User space code refers to the buffer
+ * entirely by "handle".
+ */
+struct RAR_block_info {
+	__u32 type;
+	__u32 size;
+	__u32 handle;
+};
+
+
+#define RAR_IOCTL_BASE 0xE0
+
+/* Reserve RAR block. */
+#define RAR_HANDLER_RESERVE _IOWR(RAR_IOCTL_BASE, 0x00, struct RAR_block_info)
+
+/* Release previously reserved RAR block. */
+#define RAR_HANDLER_RELEASE _IOW(RAR_IOCTL_BASE, 0x01, __u32)
+
+/* Get RAR stats. */
+#define RAR_HANDLER_STAT    _IOWR(RAR_IOCTL_BASE, 0x02, struct RAR_stat)
+
+
+#ifdef __KERNEL__
+
+/* -------------------------------------------------------------- */
+/*               Kernel Side RAR Handler Interface                */
+/* -------------------------------------------------------------- */
+
+/**
+ * struct RAR_buffer - kernel space struct that describes RAR buffer
+ * @info:		structure containing base RAR buffer information
+ * @bus_address:	buffer bus address
+ *
+ * Structure that contains all information related to a given block of
+ * memory in RAR.  It is generally only used when retrieving RAR
+ * related bus addresses.
+ *
+ * Note: This structure is used only by RAR-enabled drivers, and is
+ *       not intended to be exposed to the user space.
+ */
+struct RAR_buffer {
+	struct RAR_block_info info;
+	dma_addr_t bus_address;
+};
+
+/**
+ * rar_reserve() - reserve RAR buffers
+ * @buffers:	array of RAR_buffers where type and size of buffers to
+ *		reserve are passed in, handle and bus address are
+ *		passed out
+ * @count:	number of RAR_buffers in the "buffers" array
+ *
+ * This function will reserve buffers in the restricted access regions
+ * of given types.
+ *
+ * It returns the number of successfully reserved buffers.  Successful
+ * buffer reservations will have the corresponding bus_address field
+ * set to a non-zero value in the given buffers vector.
+ */
+extern size_t rar_reserve(struct RAR_buffer *buffers,
+			  size_t count);
+
+/**
+ * rar_release() - release RAR buffers
+ * @buffers:	array of RAR_buffers where handles to buffers to be
+ *		released are passed in
+ * @count:	number of RAR_buffers in the "buffers" array
+ *
+ * This function will release RAR buffers that were retrieved through
+ * a call to rar_reserve() or rar_handle_to_bus() by decrementing the
+ * reference count.  The RAR buffer will be reclaimed when the
+ * reference count drops to zero.
+ *
+ * It returns the number of successfully released buffers.  Successful
+ * releases will have their handle field set to zero in the given
+ * buffers vector.
+ */
+extern size_t rar_release(struct RAR_buffer *buffers,
+			  size_t count);
+
+/**
+ * rar_handle_to_bus() - convert a vector of RAR handles to bus addresses
+ * @buffers:	array of RAR_buffers containing handles to be
+ *		converted to bus_addresses
+ * @count:	number of RAR_buffers in the "buffers" array
+
+ * This function will retrieve the RAR buffer bus addresses, type and
+ * size corresponding to the RAR handles provided in the buffers
+ * vector.
+ *
+ * It returns the number of successfully converted buffers.  The bus
+ * address will be set to 0 for unrecognized handles.
+ *
+ * The reference count for each corresponding buffer in RAR will be
+ * incremented.  Call rar_release() when done with the buffers.
+ */
+extern size_t rar_handle_to_bus(struct RAR_buffer *buffers,
+				size_t count);
+
+
+#endif  /* __KERNEL__ */
+
+#endif  /* _MEMRAR_H */

drivers/staging/memrar/memrar_allocator.h

+/*
+ *      Copyright (C) 2010 Intel Corporation. All rights reserved.
+ *
+ *      This program is free software; you can redistribute it and/or
+ *      modify it under the terms of version 2 of the GNU General
+ *      Public License as published by the Free Software Foundation.
+ *
+ *      This program 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 this program; if not, write to the Free
+ *      Software Foundation, Inc., 59 Temple Place - Suite 330,
+ *      Boston, MA  02111-1307, USA.
+ *      The full GNU General Public License is included in this
+ *      distribution in the file called COPYING.
+ */
+
+#ifndef MEMRAR_ALLOCATOR_H
+#define MEMRAR_ALLOCATOR_H
+
+
+#include <linux/mutex.h>
+#include <linux/list.h>
+#include <linux/types.h>
+#include <linux/kernel.h>
+
+
+/**
+ * struct memrar_address_range - struct that describes a memory range
+ * @begin:	Beginning of available address range.
+ * @end:	End of available address range, one past the end,
+ *		i.e. [begin, end).
+ */
+struct memrar_address_range {
+/* private: internal use only */
+	unsigned long begin;
+	unsigned long end;
+};
+
+/**
+ * struct memrar_address_ranges - list of areas of memory.
+ * @list:	Linked list of address ranges.
+ * @range:	Memory address range corresponding to given list node.
+ */
+struct memrar_address_ranges {
+/* private: internal use only */
+	struct list_head list;
+	struct memrar_address_range range;
+};
+
+/**
+ * struct memrar_allocator - encapsulation of the memory allocator state
+ * @lock:		Lock used to synchronize access to the memory
+ *			allocator state.
+ * @base:		Base (start) address of the allocator memory
+ *			space.
+ * @capacity:		Size of the allocator memory space in bytes.
+ * @block_size:		The size in bytes of individual blocks within
+ *			the allocator memory space.
+ * @largest_free_area:	Largest free area of memory in the allocator
+ *			in bytes.
+ * @allocated_list:	List of allocated memory block address
+ *			ranges.
+ * @free_list:		List of free address ranges.
+ *
+ * This structure contains all memory allocator state, including the
+ * base address, capacity, free list, lock, etc.
+ */
+struct memrar_allocator {
+/* private: internal use only */
+	struct mutex lock;
+	unsigned long base;
+	size_t capacity;
+	size_t block_size;
+	size_t largest_free_area;
+	struct memrar_address_ranges allocated_list;
+	struct memrar_address_ranges free_list;
+};
+
+/**
+ * memrar_create_allocator() - create a memory allocator
+ * @base:	Address at which the memory allocator begins.
+ * @capacity:	Desired size of the memory allocator.  This value must
+ *		be larger than the block_size, ideally more than twice
+ *		as large since there wouldn't be much point in using a
+ *		memory allocator otherwise.
+ * @block_size:	The size of individual blocks within the memory
+ *		allocator.  This value must smaller than the
+ *		capacity.
+ *
+ * Create a memory allocator with the given capacity and block size.
+ * The capacity will be reduced to be a multiple of the block size, if
+ * necessary.
+ *
+ * Returns an instance of the memory allocator, if creation succeeds,
+ * otherwise zero if creation fails.  Failure may occur if not enough
+ * kernel memory exists to create the memrar_allocator instance
+ * itself, or if the capacity and block_size arguments are not
+ * compatible or make sense.
+ */
+struct memrar_allocator *memrar_create_allocator(unsigned long base,
+						 size_t capacity,
+						 size_t block_size);
+
+/**
+ * memrar_destroy_allocator() - destroy allocator
+ * @allocator:	The allocator being destroyed.
+ *
+ * Reclaim resources held by the memory allocator.  The caller must
+ * explicitly free all memory reserved by memrar_allocator_alloc()
+ * prior to calling this function.  Otherwise leaks will occur.
+ */
+void memrar_destroy_allocator(struct memrar_allocator *allocator);
+
+/**
+ * memrar_allocator_alloc() - reserve an area of memory of given size
+ * @allocator:	The allocator instance being used to reserve buffer.
+ * @size:	The size in bytes of the buffer to allocate.
+ *
+ * This functions reserves an area of memory managed by the given
+ * allocator.  It returns zero if allocation was not possible.
+ * Failure may occur if the allocator no longer has space available.
+ */
+unsigned long memrar_allocator_alloc(struct memrar_allocator *allocator,
+				     size_t size);
+
+/**
+ * memrar_allocator_free() - release buffer starting at given address
+ * @allocator:	The allocator instance being used to release the buffer.
+ * @address:	The address of the buffer being released.
+ *
+ * Release an area of memory starting at the given address.  Failure
+ * could occur if the given address is not in the address space
+ * managed by the allocator.  Returns zero on success or an errno
+ * (negative value) on failure.
+ */
+long memrar_allocator_free(struct memrar_allocator *allocator,
+			   unsigned long address);
+
+#endif  /* MEMRAR_ALLOCATOR_H */
+
+
+/*
+  Local Variables:
+    c-file-style: "linux"
+  End:
+*/