aboutsummaryrefslogtreecommitdiffstats
path: root/drivers/staging/memrar/memrar.h
blob: 07e6c36a6ceede8260da277faade36223063a3f9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
/*
 *      RAR Handler (/dev/memrar) internal driver API.
 *      Copyright (C) 2010 Intel Corporation. All rights reserved.
 *
 *      This program is free software; you can redistribute it and/or
 *      modify it under the terms of version 2 of the GNU General
 *      Public License as published by the Free Software Foundation.
 *
 *      This program is distributed in the hope that it will be
 *      useful, but WITHOUT ANY WARRANTY; without even the implied
 *      warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 *      PURPOSE.  See the GNU General Public License for more details.
 *      You should have received a copy of the GNU General Public
 *      License along with this program; if not, write to the Free
 *      Software Foundation, Inc., 59 Temple Place - Suite 330,
 *      Boston, MA  02111-1307, USA.
 *      The full GNU General Public License is included in this
 *      distribution in the file called COPYING.
 */


#ifndef _MEMRAR_H
#define _MEMRAR_H

#include <linux/ioctl.h>
#include <linux/types.h>


/**
 * struct RAR_stat - RAR statistics structure
 * @type:		Type of RAR memory (e.g., audio vs. video)
 * @capacity:		Total size of RAR memory region.
 * @largest_block_size:	Size of the largest reservable block.
 *
 * This structure is used for RAR_HANDLER_STAT ioctl and for the
 * RAR_get_stat() user space wrapper function.
 */
struct RAR_stat {
	__u32 type;
	__u32 capacity;
	__u32 largest_block_size;
};


/**
 * struct RAR_block_info - user space struct that describes RAR buffer
 * @type:	Type of RAR memory (e.g., audio vs. video)
 * @size:	Requested size of a block to be reserved in RAR.
 * @handle:	Handle that can be used to refer to reserved block.
 *
 * This is the basic structure exposed to the user space that
 * describes a given RAR buffer.  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;
};


#define RAR_IOCTL_BASE 0xE0

/* Reserve RAR block. */
#define RAR_HANDLER_RESERVE _IOWR(RAR_IOCTL_BASE, 0x00, struct RAR_block_info)

/* Release previously reserved RAR block. */
#define RAR_HANDLER_RELEASE _IOW(RAR_IOCTL_BASE, 0x01, __u32)

/* Get RAR stats. */
#define RAR_HANDLER_STAT    _IOWR(RAR_IOCTL_BASE, 0x02, struct RAR_stat)


#ifdef __KERNEL__

/* -------------------------------------------------------------- */
/*               Kernel Side RAR Handler Interface                */
/* -------------------------------------------------------------- */

/**
 * struct RAR_buffer - kernel space struct that describes RAR buffer
 * @info:		structure containing base RAR buffer information
 * @bus_address:	buffer bus address
 *
 * Structure that contains all information related to a given block of
 * memory in RAR.  It is generally only used when retrieving RAR
 * related bus addresses.
 *
 * Note: This structure is used only by RAR-enabled drivers, and is
 *       not intended to be exposed to the user space.
 */
struct RAR_buffer {
	struct RAR_block_info info;
	dma_addr_t bus_address;
};

#if defined(CONFIG_MRST_RAR_HANDLER) || defined(CONFIG_MRST_RAR_HANDLER_MODULE)

/**
 * rar_reserve() - reserve RAR buffers
 * @buffers:	array of RAR_buffers where type and size of buffers to
 *		reserve are passed in, handle and bus address are
 *		passed out
 * @count:	number of RAR_buffers in the "buffers" array
 *
 * This function will reserve buffers in the restricted access regions
 * of given types.
 *
 * It returns the number of successfully reserved buffers.  Successful
 * buffer reservations will have the corresponding bus_address field
 * set to a non-zero value in the given buffers vector.
 */
extern size_t rar_reserve(struct RAR_buffer *buffers,
			  size_t count);

/**
 * rar_release() - release RAR buffers
 * @buffers:	array of RAR_buffers where handles to buffers to be
 *		released are passed in
 * @count:	number of RAR_buffers in the "buffers" array
 *
 * This function will release RAR buffers that were retrieved through
 * a call to rar_reserve() or rar_handle_to_bus() by decrementing the
 * reference count.  The RAR buffer will be reclaimed when the
 * reference count drops to zero.
 *
 * It returns the number of successfully released buffers.  Successful
 * releases will have their handle field set to zero in the given
 * buffers vector.
 */
extern size_t rar_release(struct RAR_buffer *buffers,
			  size_t count);

/**
 * rar_handle_to_bus() - convert a vector of RAR handles to bus addresses
 * @buffers:	array of RAR_buffers containing handles to be
 *		converted to bus_addresses
 * @count:	number of RAR_buffers in the "buffers" array

 * This function will retrieve the RAR buffer bus addresses, type and
 * size corresponding to the RAR handles provided in the buffers
 * vector.
 *
 * It returns the number of successfully converted buffers.  The bus
 * address will be set to 0 for unrecognized handles.
 *
 * The reference count for each corresponding buffer in RAR will be
 * incremented.  Call rar_release() when done with the buffers.
 */
extern size_t rar_handle_to_bus(struct RAR_buffer *buffers,
				size_t count);

#else
#define rar_reserve(a, b) ((size_t)NULL)
#define rar_release(a, b) ((size_t)NULL)
#define rar_handle_to_bus(a, b) ((size_t)NULL)
#endif

#endif  /* __KERNEL__ */

#endif  /* _MEMRAR_H */