VM: add "vm_munmap()" helper function
[pandora-kernel.git] / include / linux / remoteproc.h
1 /*
2  * Remote Processor Framework
3  *
4  * Copyright(c) 2011 Texas Instruments, Inc.
5  * Copyright(c) 2011 Google, Inc.
6  * All rights reserved.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * * Redistributions of source code must retain the above copyright
13  *   notice, this list of conditions and the following disclaimer.
14  * * Redistributions in binary form must reproduce the above copyright
15  *   notice, this list of conditions and the following disclaimer in
16  *   the documentation and/or other materials provided with the
17  *   distribution.
18  * * Neither the name Texas Instruments nor the names of its
19  *   contributors may be used to endorse or promote products derived
20  *   from this software without specific prior written permission.
21  *
22  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
23  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
24  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
25  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
26  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
27  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
28  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
29  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
30  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
31  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
32  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33  */
34
35 #ifndef REMOTEPROC_H
36 #define REMOTEPROC_H
37
38 #include <linux/types.h>
39 #include <linux/kref.h>
40 #include <linux/klist.h>
41 #include <linux/mutex.h>
42 #include <linux/virtio.h>
43 #include <linux/completion.h>
44 #include <linux/idr.h>
45
46 /**
47  * struct resource_table - firmware resource table header
48  * @ver: version number
49  * @num: number of resource entries
50  * @reserved: reserved (must be zero)
51  * @offset: array of offsets pointing at the various resource entries
52  *
53  * A resource table is essentially a list of system resources required
54  * by the remote processor. It may also include configuration entries.
55  * If needed, the remote processor firmware should contain this table
56  * as a dedicated ".resource_table" ELF section.
57  *
58  * Some resources entries are mere announcements, where the host is informed
59  * of specific remoteproc configuration. Other entries require the host to
60  * do something (e.g. allocate a system resource). Sometimes a negotiation
61  * is expected, where the firmware requests a resource, and once allocated,
62  * the host should provide back its details (e.g. address of an allocated
63  * memory region).
64  *
65  * The header of the resource table, as expressed by this structure,
66  * contains a version number (should we need to change this format in the
67  * future), the number of available resource entries, and their offsets
68  * in the table.
69  *
70  * Immediately following this header are the resource entries themselves,
71  * each of which begins with a resource entry header (as described below).
72  */
73 struct resource_table {
74         u32 ver;
75         u32 num;
76         u32 reserved[2];
77         u32 offset[0];
78 } __packed;
79
80 /**
81  * struct fw_rsc_hdr - firmware resource entry header
82  * @type: resource type
83  * @data: resource data
84  *
85  * Every resource entry begins with a 'struct fw_rsc_hdr' header providing
86  * its @type. The content of the entry itself will immediately follow
87  * this header, and it should be parsed according to the resource type.
88  */
89 struct fw_rsc_hdr {
90         u32 type;
91         u8 data[0];
92 } __packed;
93
94 /**
95  * enum fw_resource_type - types of resource entries
96  *
97  * @RSC_CARVEOUT:   request for allocation of a physically contiguous
98  *                  memory region.
99  * @RSC_DEVMEM:     request to iommu_map a memory-based peripheral.
100  * @RSC_TRACE:      announces the availability of a trace buffer into which
101  *                  the remote processor will be writing logs.
102  * @RSC_VDEV:       declare support for a virtio device, and serve as its
103  *                  virtio header.
104  * @RSC_LAST:       just keep this one at the end
105  *
106  * For more details regarding a specific resource type, please see its
107  * dedicated structure below.
108  *
109  * Please note that these values are used as indices to the rproc_handle_rsc
110  * lookup table, so please keep them sane. Moreover, @RSC_LAST is used to
111  * check the validity of an index before the lookup table is accessed, so
112  * please update it as needed.
113  */
114 enum fw_resource_type {
115         RSC_CARVEOUT    = 0,
116         RSC_DEVMEM      = 1,
117         RSC_TRACE       = 2,
118         RSC_VDEV        = 3,
119         RSC_LAST        = 4,
120 };
121
122 #define FW_RSC_ADDR_ANY (0xFFFFFFFFFFFFFFFF)
123
124 /**
125  * struct fw_rsc_carveout - physically contiguous memory request
126  * @da: device address
127  * @pa: physical address
128  * @len: length (in bytes)
129  * @flags: iommu protection flags
130  * @reserved: reserved (must be zero)
131  * @name: human-readable name of the requested memory region
132  *
133  * This resource entry requests the host to allocate a physically contiguous
134  * memory region.
135  *
136  * These request entries should precede other firmware resource entries,
137  * as other entries might request placing other data objects inside
138  * these memory regions (e.g. data/code segments, trace resource entries, ...).
139  *
140  * Allocating memory this way helps utilizing the reserved physical memory
141  * (e.g. CMA) more efficiently, and also minimizes the number of TLB entries
142  * needed to map it (in case @rproc is using an IOMMU). Reducing the TLB
143  * pressure is important; it may have a substantial impact on performance.
144  *
145  * If the firmware is compiled with static addresses, then @da should specify
146  * the expected device address of this memory region. If @da is set to
147  * FW_RSC_ADDR_ANY, then the host will dynamically allocate it, and then
148  * overwrite @da with the dynamically allocated address.
149  *
150  * We will always use @da to negotiate the device addresses, even if it
151  * isn't using an iommu. In that case, though, it will obviously contain
152  * physical addresses.
153  *
154  * Some remote processors needs to know the allocated physical address
155  * even if they do use an iommu. This is needed, e.g., if they control
156  * hardware accelerators which access the physical memory directly (this
157  * is the case with OMAP4 for instance). In that case, the host will
158  * overwrite @pa with the dynamically allocated physical address.
159  * Generally we don't want to expose physical addresses if we don't have to
160  * (remote processors are generally _not_ trusted), so we might want to
161  * change this to happen _only_ when explicitly required by the hardware.
162  *
163  * @flags is used to provide IOMMU protection flags, and @name should
164  * (optionally) contain a human readable name of this carveout region
165  * (mainly for debugging purposes).
166  */
167 struct fw_rsc_carveout {
168         u32 da;
169         u32 pa;
170         u32 len;
171         u32 flags;
172         u32 reserved;
173         u8 name[32];
174 } __packed;
175
176 /**
177  * struct fw_rsc_devmem - iommu mapping request
178  * @da: device address
179  * @pa: physical address
180  * @len: length (in bytes)
181  * @flags: iommu protection flags
182  * @reserved: reserved (must be zero)
183  * @name: human-readable name of the requested region to be mapped
184  *
185  * This resource entry requests the host to iommu map a physically contiguous
186  * memory region. This is needed in case the remote processor requires
187  * access to certain memory-based peripherals; _never_ use it to access
188  * regular memory.
189  *
190  * This is obviously only needed if the remote processor is accessing memory
191  * via an iommu.
192  *
193  * @da should specify the required device address, @pa should specify
194  * the physical address we want to map, @len should specify the size of
195  * the mapping and @flags is the IOMMU protection flags. As always, @name may
196  * (optionally) contain a human readable name of this mapping (mainly for
197  * debugging purposes).
198  *
199  * Note: at this point we just "trust" those devmem entries to contain valid
200  * physical addresses, but this isn't safe and will be changed: eventually we
201  * want remoteproc implementations to provide us ranges of physical addresses
202  * the firmware is allowed to request, and not allow firmwares to request
203  * access to physical addresses that are outside those ranges.
204  */
205 struct fw_rsc_devmem {
206         u32 da;
207         u32 pa;
208         u32 len;
209         u32 flags;
210         u32 reserved;
211         u8 name[32];
212 } __packed;
213
214 /**
215  * struct fw_rsc_trace - trace buffer declaration
216  * @da: device address
217  * @len: length (in bytes)
218  * @reserved: reserved (must be zero)
219  * @name: human-readable name of the trace buffer
220  *
221  * This resource entry provides the host information about a trace buffer
222  * into which the remote processor will write log messages.
223  *
224  * @da specifies the device address of the buffer, @len specifies
225  * its size, and @name may contain a human readable name of the trace buffer.
226  *
227  * After booting the remote processor, the trace buffers are exposed to the
228  * user via debugfs entries (called trace0, trace1, etc..).
229  */
230 struct fw_rsc_trace {
231         u32 da;
232         u32 len;
233         u32 reserved;
234         u8 name[32];
235 } __packed;
236
237 /**
238  * struct fw_rsc_vdev_vring - vring descriptor entry
239  * @da: device address
240  * @align: the alignment between the consumer and producer parts of the vring
241  * @num: num of buffers supported by this vring (must be power of two)
242  * @notifyid is a unique rproc-wide notify index for this vring. This notify
243  * index is used when kicking a remote processor, to let it know that this
244  * vring is triggered.
245  * @reserved: reserved (must be zero)
246  *
247  * This descriptor is not a resource entry by itself; it is part of the
248  * vdev resource type (see below).
249  *
250  * Note that @da should either contain the device address where
251  * the remote processor is expecting the vring, or indicate that
252  * dynamically allocation of the vring's device address is supported.
253  */
254 struct fw_rsc_vdev_vring {
255         u32 da;
256         u32 align;
257         u32 num;
258         u32 notifyid;
259         u32 reserved;
260 } __packed;
261
262 /**
263  * struct fw_rsc_vdev - virtio device header
264  * @id: virtio device id (as in virtio_ids.h)
265  * @notifyid is a unique rproc-wide notify index for this vdev. This notify
266  * index is used when kicking a remote processor, to let it know that the
267  * status/features of this vdev have changes.
268  * @dfeatures specifies the virtio device features supported by the firmware
269  * @gfeatures is a place holder used by the host to write back the
270  * negotiated features that are supported by both sides.
271  * @config_len is the size of the virtio config space of this vdev. The config
272  * space lies in the resource table immediate after this vdev header.
273  * @status is a place holder where the host will indicate its virtio progress.
274  * @num_of_vrings indicates how many vrings are described in this vdev header
275  * @reserved: reserved (must be zero)
276  * @vring is an array of @num_of_vrings entries of 'struct fw_rsc_vdev_vring'.
277  *
278  * This resource is a virtio device header: it provides information about
279  * the vdev, and is then used by the host and its peer remote processors
280  * to negotiate and share certain virtio properties.
281  *
282  * By providing this resource entry, the firmware essentially asks remoteproc
283  * to statically allocate a vdev upon registration of the rproc (dynamic vdev
284  * allocation is not yet supported).
285  *
286  * Note: unlike virtualization systems, the term 'host' here means
287  * the Linux side which is running remoteproc to control the remote
288  * processors. We use the name 'gfeatures' to comply with virtio's terms,
289  * though there isn't really any virtualized guest OS here: it's the host
290  * which is responsible for negotiating the final features.
291  * Yeah, it's a bit confusing.
292  *
293  * Note: immediately following this structure is the virtio config space for
294  * this vdev (which is specific to the vdev; for more info, read the virtio
295  * spec). the size of the config space is specified by @config_len.
296  */
297 struct fw_rsc_vdev {
298         u32 id;
299         u32 notifyid;
300         u32 dfeatures;
301         u32 gfeatures;
302         u32 config_len;
303         u8 status;
304         u8 num_of_vrings;
305         u8 reserved[2];
306         struct fw_rsc_vdev_vring vring[0];
307 } __packed;
308
309 /**
310  * struct rproc_mem_entry - memory entry descriptor
311  * @va: virtual address
312  * @dma: dma address
313  * @len: length, in bytes
314  * @da: device address
315  * @priv: associated data
316  * @node: list node
317  */
318 struct rproc_mem_entry {
319         void *va;
320         dma_addr_t dma;
321         int len;
322         u32 da;
323         void *priv;
324         struct list_head node;
325 };
326
327 struct rproc;
328
329 /**
330  * struct rproc_ops - platform-specific device handlers
331  * @start:      power on the device and boot it
332  * @stop:       power off the device
333  * @kick:       kick a virtqueue (virtqueue id given as a parameter)
334  */
335 struct rproc_ops {
336         int (*start)(struct rproc *rproc);
337         int (*stop)(struct rproc *rproc);
338         void (*kick)(struct rproc *rproc, int vqid);
339 };
340
341 /**
342  * enum rproc_state - remote processor states
343  * @RPROC_OFFLINE:      device is powered off
344  * @RPROC_SUSPENDED:    device is suspended; needs to be woken up to receive
345  *                      a message.
346  * @RPROC_RUNNING:      device is up and running
347  * @RPROC_CRASHED:      device has crashed; need to start recovery
348  * @RPROC_LAST:         just keep this one at the end
349  *
350  * Please note that the values of these states are used as indices
351  * to rproc_state_string, a state-to-name lookup table,
352  * so please keep the two synchronized. @RPROC_LAST is used to check
353  * the validity of an index before the lookup table is accessed, so
354  * please update it as needed too.
355  */
356 enum rproc_state {
357         RPROC_OFFLINE   = 0,
358         RPROC_SUSPENDED = 1,
359         RPROC_RUNNING   = 2,
360         RPROC_CRASHED   = 3,
361         RPROC_LAST      = 4,
362 };
363
364 /**
365  * struct rproc - represents a physical remote processor device
366  * @node: klist node of this rproc object
367  * @domain: iommu domain
368  * @name: human readable name of the rproc
369  * @firmware: name of firmware file to be loaded
370  * @priv: private data which belongs to the platform-specific rproc module
371  * @ops: platform-specific start/stop rproc handlers
372  * @dev: underlying device
373  * @refcount: refcount of users that have a valid pointer to this rproc
374  * @power: refcount of users who need this rproc powered up
375  * @state: state of the device
376  * @lock: lock which protects concurrent manipulations of the rproc
377  * @dbg_dir: debugfs directory of this rproc device
378  * @traces: list of trace buffers
379  * @num_traces: number of trace buffers
380  * @carveouts: list of physically contiguous memory allocations
381  * @mappings: list of iommu mappings we initiated, needed on shutdown
382  * @firmware_loading_complete: marks e/o asynchronous firmware loading
383  * @bootaddr: address of first instruction to boot rproc with (optional)
384  * @rvdevs: list of remote virtio devices
385  * @notifyids: idr for dynamically assigning rproc-wide unique notify ids
386  */
387 struct rproc {
388         struct klist_node node;
389         struct iommu_domain *domain;
390         const char *name;
391         const char *firmware;
392         void *priv;
393         const struct rproc_ops *ops;
394         struct device *dev;
395         struct kref refcount;
396         atomic_t power;
397         unsigned int state;
398         struct mutex lock;
399         struct dentry *dbg_dir;
400         struct list_head traces;
401         int num_traces;
402         struct list_head carveouts;
403         struct list_head mappings;
404         struct completion firmware_loading_complete;
405         u32 bootaddr;
406         struct list_head rvdevs;
407         struct idr notifyids;
408 };
409
410 /* we currently support only two vrings per rvdev */
411 #define RVDEV_NUM_VRINGS 2
412
413 /**
414  * struct rproc_vring - remoteproc vring state
415  * @va: virtual address
416  * @dma: dma address
417  * @len: length, in bytes
418  * @da: device address
419  * @align: vring alignment
420  * @notifyid: rproc-specific unique vring index
421  * @rvdev: remote vdev
422  * @vq: the virtqueue of this vring
423  */
424 struct rproc_vring {
425         void *va;
426         dma_addr_t dma;
427         int len;
428         u32 da;
429         u32 align;
430         int notifyid;
431         struct rproc_vdev *rvdev;
432         struct virtqueue *vq;
433 };
434
435 /**
436  * struct rproc_vdev - remoteproc state for a supported virtio device
437  * @node: list node
438  * @rproc: the rproc handle
439  * @vdev: the virio device
440  * @vring: the vrings for this vdev
441  * @dfeatures: virtio device features
442  * @gfeatures: virtio guest features
443  */
444 struct rproc_vdev {
445         struct list_head node;
446         struct rproc *rproc;
447         struct virtio_device vdev;
448         struct rproc_vring vring[RVDEV_NUM_VRINGS];
449         unsigned long dfeatures;
450         unsigned long gfeatures;
451 };
452
453 struct rproc *rproc_get_by_name(const char *name);
454 void rproc_put(struct rproc *rproc);
455
456 struct rproc *rproc_alloc(struct device *dev, const char *name,
457                                 const struct rproc_ops *ops,
458                                 const char *firmware, int len);
459 void rproc_free(struct rproc *rproc);
460 int rproc_register(struct rproc *rproc);
461 int rproc_unregister(struct rproc *rproc);
462
463 int rproc_boot(struct rproc *rproc);
464 void rproc_shutdown(struct rproc *rproc);
465
466 static inline struct rproc_vdev *vdev_to_rvdev(struct virtio_device *vdev)
467 {
468         return container_of(vdev, struct rproc_vdev, vdev);
469 }
470
471 static inline struct rproc *vdev_to_rproc(struct virtio_device *vdev)
472 {
473         struct rproc_vdev *rvdev = vdev_to_rvdev(vdev);
474
475         return rvdev->rproc;
476 }
477
478 #endif /* REMOTEPROC_H */