Staging: add initial memrar ABI document

Signed-off-by: Ossama Othman <ossama.othman@intel.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>

1 files changed, 89 insertions, 0 deletions

diff --git a/drivers/staging/memrar/memrar-abi b/drivers/staging/memrar/memrar-abi
new file mode 100644
index 000000000000..98a6bb158baf
--- /dev/null
+++ b/drivers/staging/memrar/memrar-abi
@@ -0,0 +1,89 @@
+What:		/dev/memrar
+Date:		March 2010
+KernelVersion:	Kernel version this feature first showed up in.
+Contact:	Ossama Othman <ossama.othman@intel.com>
+Description:	The Intel Moorestown Restricted Access Region (RAR)
+		Handler driver exposes an ioctl() based interface that
+		allows a user to reserve and release blocks of RAR
+		memory.
+
+		Note:  A sysfs based one was not appropriate for the
+		RAR handler's usage model.
+
+		=========================================================
+				ioctl() Requests
+		=========================================================
+		RAR_HANDLER_RESERVE
+		-------------------
+		Description:	Reserve RAR block.
+		Type:		struct RAR_block_info
+		Direction:	in/out
+		Errors:		EINVAL (invalid RAR type or size)
+				ENOMEM (not enough RAR memory)
+
+		RAR_HANDLER_STAT
+		----------------
+		Description:	Get RAR statistics.
+		Type:		struct RAR_stat
+		Direction:	in/out
+		Errors:		EINVAL (invalid RAR type)
+
+		RAR_HANDLER_RELEASE
+		-------------------
+		Description:	Release previously reserved RAR block.
+		Type:		32 bit unsigned integer
+				(e.g. uint32_t), i.e the RAR "handle".
+		Direction:	in
+		Errors:		EINVAL (invalid RAR handle)
+
+
+		=========================================================
+			ioctl() Request Parameter Types
+		=========================================================
+		The structures referred to above are defined as
+		follows:
+
+		/**
+		 * struct RAR_block_info - user space struct that
+		 *			   describes RAR buffer
+		 * @type:	Type of RAR memory (e.g.,
+		 *		RAR_TYPE_VIDEO or RAR_TYPE_AUDIO) [in]
+		 * @size:	Requested size of a block in bytes to
+		 *		be reserved in RAR. [in]
+		 * @handle:	Handle that can be used to refer to
+		 *		reserved block. [out]
+		 *
+		 * This is the basic structure exposed to the user
+		 * space that describes a given RAR buffer.  It used
+		 * as the parameter for the RAR_HANDLER_RESERVE ioctl.
+		 * 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;
+		};
+
+		/**
+		 * struct RAR_stat - RAR statistics structure
+		 * @type:		Type of RAR memory (e.g.,
+		 *			RAR_TYPE_VIDEO or
+		 *			RAR_TYPE_AUDIO) [in]
+		 * @capacity:		Total size of RAR memory
+		 *			region. [out]
+		 * @largest_block_size:	Size of the largest reservable
+		 *			block. [out]
+		 *
+		 * This structure is used for RAR_HANDLER_STAT ioctl.
+		 */
+		struct RAR_stat {
+			__u32 type;
+			__u32 capacity;
+			__u32 largest_block_size;
+		};
+
+		Lastly, the RAR_HANDLER_RELEASE ioctl expects a
+		"handle" to the RAR block of memory.  It is a 32 bit
+		unsigned integer.