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 #if defined(CONFIG_MRST_RAR_HANDLER)
  99 /**
 100  * rar_reserve() - reserve RAR buffers
 101  * @buffers:    array of RAR_buffers where type and size of buffers to
 102  *              reserve are passed in, handle and bus address are
 103  *              passed out
 104  * @count:      number of RAR_buffers in the "buffers" array
 105  *
 106  * This function will reserve buffers in the restricted access regions
 107  * of given types.
 108  *
 109  * It returns the number of successfully reserved buffers.  Successful
 110  * buffer reservations will have the corresponding bus_address field
 111  * set to a non-zero value in the given buffers vector.
 112  */
 113 extern size_t rar_reserve(struct RAR_buffer *buffers,
 114                           size_t count);
 115
 116 /**
 117  * rar_release() - release RAR buffers
 118  * @buffers:    array of RAR_buffers where handles to buffers to be
 119  *              released are passed in
 120  * @count:      number of RAR_buffers in the "buffers" array
 121  *
 122  * This function will release RAR buffers that were retrieved through
 123  * a call to rar_reserve() or rar_handle_to_bus() by decrementing the
 124  * reference count.  The RAR buffer will be reclaimed when the
 125  * reference count drops to zero.
 126  *
 127  * It returns the number of successfully released buffers.  Successful
 128  * releases will have their handle field set to zero in the given
 129  * buffers vector.
 130  */
 131 extern size_t rar_release(struct RAR_buffer *buffers,
 132                           size_t count);
 133
 134 /**
 135  * rar_handle_to_bus() - convert a vector of RAR handles to bus addresses
 136  * @buffers:    array of RAR_buffers containing handles to be
 137  *              converted to bus_addresses
 138  * @count:      number of RAR_buffers in the "buffers" array
 139
 140  * This function will retrieve the RAR buffer bus addresses, type and
 141  * size corresponding to the RAR handles provided in the buffers
 142  * vector.
 143  *
 144  * It returns the number of successfully converted buffers.  The bus
 145  * address will be set to 0 for unrecognized handles.
 146  *
 147  * The reference count for each corresponding buffer in RAR will be
 148  * incremented.  Call rar_release() when done with the buffers.
 149  */
 150 extern size_t rar_handle_to_bus(struct RAR_buffer *buffers,
 151                                 size_t count);
 152
 153 #else
 154
 155 extern inline size_t rar_reserve(struct RAR_buffer *buffers, size_t count)
 156 {
 157         return 0;
 158 }
 159
 160 extern inline size_t rar_release(struct RAR_buffer *buffers, size_t count)
 161 {
 162         return 0;
 163 }
 164
 165 extern inline size_t rar_handle_to_bus(struct RAR_buffer *buffers,
 166                                 size_t count)
 167 {
 168         return 0;
 169 }
 170
 171 #endif  /* MRST_RAR_HANDLER */
 172 #endif  /* __KERNEL__ */
 173
 174 #endif  /* _MEMRAR_H */