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 */ 38struct 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 */ 56struct 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 */ 93struct 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 */ 112extern 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 */ 130extern 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 */ 149extern size_t rar_handle_to_bus(struct RAR_buffer *buffers, 150 size_t count); 151 152 153#endif /* __KERNEL__ */ 154 155#endif /* _MEMRAR_H */ 156