drivers/staging/memrar/memrar.h

   1 /*
   2  *      RAR Handler (/dev/memrar) internal driver API.
   3  *      Copyright (C) 2010 Intel Corporation. All rights reserved.
   4  *
   5  *      This program is free software; you can redistribute it and/or
   6  *      modify it under the terms of version 2 of the GNU General
   7  *      Public License as published by the Free Software Foundation.
   8  *
   9  *      This program is distributed in the hope that it will be
  10  *      useful, but WITHOUT ANY WARRANTY; without even the implied
  11  *      warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  12  *      PURPOSE.  See the GNU General Public License for more details.
  13  *      You should have received a copy of the GNU General Public
  14  *      License along with this program; if not, write to the Free
  15  *      Software Foundation, Inc., 59 Temple Place - Suite 330,
  16  *      Boston, MA  02111-1307, USA.
  17  *      The full GNU General Public License is included in this
  18  *      distribution in the file called COPYING.
  19  */
  20
  21
  22 #ifndef _MEMRAR_H
  23 #define _MEMRAR_H
  24
  25 #include <linux/ioctl.h>
  26 #include <linux/types.h>
  27
  28
  29 /**
  30  * struct RAR_stat - RAR statistics structure
  31  * @type:               Type of RAR memory (e.g., audio vs. video)
  32  * @capacity:           Total size of RAR memory region.
  33  * @largest_block_size: Size of the largest reservable block.
  34  *
  35  * This structure is used for RAR_HANDLER_STAT ioctl and for the
  36  * RAR_get_stat() user space wrapper function.
  37  */
  38 struct RAR_stat {
  39         __u32 type;
  40         __u32 capacity;
  41         __u32 largest_block_size;
  42 };
  43
  44
  45 /**
  46  * struct RAR_block_info - user space struct that describes RAR buffer
  47  * @type:       Type of RAR memory (e.g., audio vs. video)
  48  * @size:       Requested size of a block to be reserved in RAR.
  49  * @handle:     Handle that can be used to refer to reserved block.
  50  *
  51  * This is the basic structure exposed to the user space that
  52  * describes a given RAR buffer.  The buffer's underlying bus address
  53  * is not exposed to the user.  User space code refers to the buffer
  54  * entirely by "handle".
  55  */
  56 struct RAR_block_info {
  57         __u32 type;
  58         __u32 size;
  59         __u32 handle;
  60 };
  61
  62
  63 #define RAR_IOCTL_BASE 0xE0
  64
  65 /* Reserve RAR block. */
  66 #define RAR_HANDLER_RESERVE _IOWR(RAR_IOCTL_BASE, 0x00, struct RAR_block_info)
  67
  68 /* Release previously reserved RAR block. */
  69 #define RAR_HANDLER_RELEASE _IOW(RAR_IOCTL_BASE, 0x01, __u32)
  70
  71 /* Get RAR stats. */
  72 #define RAR_HANDLER_STAT    _IOWR(RAR_IOCTL_BASE, 0x02, struct RAR_stat)
  73
  74
  75 #ifdef __KERNEL__
  76
  77 /* -------------------------------------------------------------- */
  78 /*               Kernel Side RAR Handler Interface                */
  79 /* -------------------------------------------------------------- */
  80
  81 /**
  82  * struct RAR_buffer - kernel space struct that describes RAR buffer
  83  * @info:               structure containing base RAR buffer information
  84  * @bus_address:        buffer bus address
  85  *
  86  * Structure that contains all information related to a given block of
  87  * memory in RAR.  It is generally only used when retrieving RAR
  88  * related bus addresses.
  89  *
  90  * Note: This structure is used only by RAR-enabled drivers, and is
  91  *       not intended to be exposed to the user space.
  92  */
  93 struct RAR_buffer {
  94         struct RAR_block_info info;
  95         dma_addr_t bus_address;
  96 };
  97
  98 /**
  99  * rar_reserve() - reserve RAR buffers
 100  * @buffers:    array of RAR_buffers where type and size of buffers to
 101  *              reserve are passed in, handle and bus address are
 102  *              passed out
 103  * @count:      number of RAR_buffers in the "buffers" array
 104  *
 105  * This function will reserve buffers in the restricted access regions
 106  * of given types.
 107  *
 108  * It returns the number of successfully reserved buffers.  Successful
 109  * buffer reservations will have the corresponding bus_address field
 110  * set to a non-zero value in the given buffers vector.
 111  */
 112 extern size_t rar_reserve(struct RAR_buffer *buffers,
 113                           size_t count);
 114
 115 /**
 116  * rar_release() - release RAR buffers
 117  * @buffers:    array of RAR_buffers where handles to buffers to be
 118  *              released are passed in
 119  * @count:      number of RAR_buffers in the "buffers" array
 120  *
 121  * This function will release RAR buffers that were retrieved through
 122  * a call to rar_reserve() or rar_handle_to_bus() by decrementing the
 123  * reference count.  The RAR buffer will be reclaimed when the
 124  * reference count drops to zero.
 125  *
 126  * It returns the number of successfully released buffers.  Successful
 127  * releases will have their handle field set to zero in the given
 128  * buffers vector.
 129  */
 130 extern size_t rar_release(struct RAR_buffer *buffers,
 131                           size_t count);
 132
 133 /**
 134  * rar_handle_to_bus() - convert a vector of RAR handles to bus addresses
 135  * @buffers:    array of RAR_buffers containing handles to be
 136  *              converted to bus_addresses
 137  * @count:      number of RAR_buffers in the "buffers" array
 138
 139  * This function will retrieve the RAR buffer bus addresses, type and
 140  * size corresponding to the RAR handles provided in the buffers
 141  * vector.
 142  *
 143  * It returns the number of successfully converted buffers.  The bus
 144  * address will be set to 0 for unrecognized handles.
 145  *
 146  * The reference count for each corresponding buffer in RAR will be
 147  * incremented.  Call rar_release() when done with the buffers.
 148  */
 149 extern size_t rar_handle_to_bus(struct RAR_buffer *buffers,
 150                                 size_t count);
 151
 152
 153 #endif  /* __KERNEL__ */
 154
 155 #endif  /* _MEMRAR_H */