Staging: add initial memrar ABI document

Signed-off-by: Ossama Othman <ossama.othman@intel.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
This commit is contained in:
Ossama Othman 2010-03-26 15:11:11 -07:00 committed by Greg Kroah-Hartman
parent d82f139b58
commit 933025b608

View file

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