blob: 7750d8a309331f6b570a22d030b486378497a676 [file] [log] [blame]
Ohad Ben-Cohen400e64d2011-10-20 16:52:46 +02001/*
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>
Ohad Ben-Cohen7a186942012-02-13 22:30:39 +010044#include <linux/idr.h>
Ohad Ben-Cohen400e64d2011-10-20 16:52:46 +020045
46/*
47 * The alignment between the consumer and producer parts of the vring.
48 * Note: this is part of the "wire" protocol. If you change this, you need
49 * to update your peers too.
50 */
51#define AMP_VRING_ALIGN (4096)
52
53/**
Ohad Ben-Cohenfd2c15e2012-02-01 21:56:16 +020054 * struct resource_table - firmware resource table header
55 * @ver: version number
56 * @num: number of resource entries
57 * @reserved: reserved (must be zero)
58 * @offset: array of offsets pointing at the various resource entries
Ohad Ben-Cohen400e64d2011-10-20 16:52:46 +020059 *
Ohad Ben-Cohenfd2c15e2012-02-01 21:56:16 +020060 * A resource table is essentially a list of system resources required
61 * by the remote processor. It may also include configuration entries.
62 * If needed, the remote processor firmware should contain this table
63 * as a dedicated ".resource_table" ELF section.
Ohad Ben-Cohen400e64d2011-10-20 16:52:46 +020064 *
65 * Some resources entries are mere announcements, where the host is informed
66 * of specific remoteproc configuration. Other entries require the host to
Ohad Ben-Cohenfd2c15e2012-02-01 21:56:16 +020067 * do something (e.g. allocate a system resource). Sometimes a negotiation
68 * is expected, where the firmware requests a resource, and once allocated,
69 * the host should provide back its details (e.g. address of an allocated
70 * memory region).
Ohad Ben-Cohen400e64d2011-10-20 16:52:46 +020071 *
Ohad Ben-Cohenfd2c15e2012-02-01 21:56:16 +020072 * The header of the resource table, as expressed by this structure,
73 * contains a version number (should we need to change this format in the
74 * future), the number of available resource entries, and their offsets
75 * in the table.
76 *
77 * Immediately following this header are the resource entries themselves,
78 * each of which begins with a resource entry header (as described below).
Ohad Ben-Cohen400e64d2011-10-20 16:52:46 +020079 */
Ohad Ben-Cohenfd2c15e2012-02-01 21:56:16 +020080struct resource_table {
81 u32 ver;
82 u32 num;
83 u32 reserved[2];
84 u32 offset[0];
85} __packed;
86
87/**
88 * struct fw_rsc_hdr - firmware resource entry header
89 * @type: resource type
90 * @data: resource data
91 *
92 * Every resource entry begins with a 'struct fw_rsc_hdr' header providing
93 * its @type. The content of the entry itself will immediately follow
94 * this header, and it should be parsed according to the resource type.
95 */
96struct fw_rsc_hdr {
Ohad Ben-Cohen400e64d2011-10-20 16:52:46 +020097 u32 type;
Ohad Ben-Cohenfd2c15e2012-02-01 21:56:16 +020098 u8 data[0];
Ohad Ben-Cohen400e64d2011-10-20 16:52:46 +020099} __packed;
100
101/**
102 * enum fw_resource_type - types of resource entries
103 *
104 * @RSC_CARVEOUT: request for allocation of a physically contiguous
105 * memory region.
106 * @RSC_DEVMEM: request to iommu_map a memory-based peripheral.
107 * @RSC_TRACE: announces the availability of a trace buffer into which
Ohad Ben-Cohenfd2c15e2012-02-01 21:56:16 +0200108 * the remote processor will be writing logs.
109 * @RSC_VDEV: declare support for a virtio device, and serve as its
110 * virtio header.
Ohad Ben-Cohene12bc142012-01-31 16:07:27 +0200111 * @RSC_LAST: just keep this one at the end
Ohad Ben-Cohen400e64d2011-10-20 16:52:46 +0200112 *
Ohad Ben-Cohenfd2c15e2012-02-01 21:56:16 +0200113 * For more details regarding a specific resource type, please see its
114 * dedicated structure below.
Ohad Ben-Cohene12bc142012-01-31 16:07:27 +0200115 *
116 * Please note that these values are used as indices to the rproc_handle_rsc
117 * lookup table, so please keep them sane. Moreover, @RSC_LAST is used to
118 * check the validity of an index before the lookup table is accessed, so
119 * please update it as needed.
Ohad Ben-Cohen400e64d2011-10-20 16:52:46 +0200120 */
121enum fw_resource_type {
122 RSC_CARVEOUT = 0,
123 RSC_DEVMEM = 1,
124 RSC_TRACE = 2,
Ohad Ben-Cohenfd2c15e2012-02-01 21:56:16 +0200125 RSC_VDEV = 3,
126 RSC_LAST = 4,
Ohad Ben-Cohen400e64d2011-10-20 16:52:46 +0200127};
128
Ohad Ben-Cohenfd2c15e2012-02-01 21:56:16 +0200129#define FW_RSC_ADDR_ANY (0xFFFFFFFFFFFFFFFF)
130
131/**
132 * struct fw_rsc_carveout - physically contiguous memory request
133 * @da: device address
134 * @pa: physical address
135 * @len: length (in bytes)
136 * @flags: iommu protection flags
137 * @reserved: reserved (must be zero)
138 * @name: human-readable name of the requested memory region
139 *
140 * This resource entry requests the host to allocate a physically contiguous
141 * memory region.
142 *
143 * These request entries should precede other firmware resource entries,
144 * as other entries might request placing other data objects inside
145 * these memory regions (e.g. data/code segments, trace resource entries, ...).
146 *
147 * Allocating memory this way helps utilizing the reserved physical memory
148 * (e.g. CMA) more efficiently, and also minimizes the number of TLB entries
149 * needed to map it (in case @rproc is using an IOMMU). Reducing the TLB
150 * pressure is important; it may have a substantial impact on performance.
151 *
152 * If the firmware is compiled with static addresses, then @da should specify
153 * the expected device address of this memory region. If @da is set to
154 * FW_RSC_ADDR_ANY, then the host will dynamically allocate it, and then
155 * overwrite @da with the dynamically allocated address.
156 *
157 * We will always use @da to negotiate the device addresses, even if it
158 * isn't using an iommu. In that case, though, it will obviously contain
159 * physical addresses.
160 *
161 * Some remote processors needs to know the allocated physical address
162 * even if they do use an iommu. This is needed, e.g., if they control
163 * hardware accelerators which access the physical memory directly (this
164 * is the case with OMAP4 for instance). In that case, the host will
165 * overwrite @pa with the dynamically allocated physical address.
166 * Generally we don't want to expose physical addresses if we don't have to
167 * (remote processors are generally _not_ trusted), so we might want to
168 * change this to happen _only_ when explicitly required by the hardware.
169 *
170 * @flags is used to provide IOMMU protection flags, and @name should
171 * (optionally) contain a human readable name of this carveout region
172 * (mainly for debugging purposes).
173 */
174struct fw_rsc_carveout {
175 u32 da;
176 u32 pa;
177 u32 len;
178 u32 flags;
179 u32 reserved;
180 u8 name[32];
181} __packed;
182
183/**
184 * struct fw_rsc_devmem - iommu mapping request
185 * @da: device address
186 * @pa: physical address
187 * @len: length (in bytes)
188 * @flags: iommu protection flags
189 * @reserved: reserved (must be zero)
190 * @name: human-readable name of the requested region to be mapped
191 *
192 * This resource entry requests the host to iommu map a physically contiguous
193 * memory region. This is needed in case the remote processor requires
194 * access to certain memory-based peripherals; _never_ use it to access
195 * regular memory.
196 *
197 * This is obviously only needed if the remote processor is accessing memory
198 * via an iommu.
199 *
200 * @da should specify the required device address, @pa should specify
201 * the physical address we want to map, @len should specify the size of
202 * the mapping and @flags is the IOMMU protection flags. As always, @name may
203 * (optionally) contain a human readable name of this mapping (mainly for
204 * debugging purposes).
205 *
206 * Note: at this point we just "trust" those devmem entries to contain valid
207 * physical addresses, but this isn't safe and will be changed: eventually we
208 * want remoteproc implementations to provide us ranges of physical addresses
209 * the firmware is allowed to request, and not allow firmwares to request
210 * access to physical addresses that are outside those ranges.
211 */
212struct fw_rsc_devmem {
213 u32 da;
214 u32 pa;
215 u32 len;
216 u32 flags;
217 u32 reserved;
218 u8 name[32];
219} __packed;
220
221/**
222 * struct fw_rsc_trace - trace buffer declaration
223 * @da: device address
224 * @len: length (in bytes)
225 * @reserved: reserved (must be zero)
226 * @name: human-readable name of the trace buffer
227 *
228 * This resource entry provides the host information about a trace buffer
229 * into which the remote processor will write log messages.
230 *
231 * @da specifies the device address of the buffer, @len specifies
232 * its size, and @name may contain a human readable name of the trace buffer.
233 *
234 * After booting the remote processor, the trace buffers are exposed to the
235 * user via debugfs entries (called trace0, trace1, etc..).
236 */
237struct fw_rsc_trace {
238 u32 da;
239 u32 len;
240 u32 reserved;
241 u8 name[32];
242} __packed;
243
244/**
245 * struct fw_rsc_vdev_vring - vring descriptor entry
246 * @da: device address
247 * @align: the alignment between the consumer and producer parts of the vring
248 * @num: num of buffers supported by this vring (must be power of two)
249 * @notifyid is a unique rproc-wide notify index for this vring. This notify
250 * index is used when kicking a remote processor, to let it know that this
251 * vring is triggered.
252 * @reserved: reserved (must be zero)
253 *
254 * This descriptor is not a resource entry by itself; it is part of the
255 * vdev resource type (see below).
256 *
257 * Note that @da should either contain the device address where
258 * the remote processor is expecting the vring, or indicate that
259 * dynamically allocation of the vring's device address is supported.
260 */
261struct fw_rsc_vdev_vring {
262 u32 da;
263 u32 align;
264 u32 num;
265 u32 notifyid;
266 u32 reserved;
267} __packed;
268
269/**
270 * struct fw_rsc_vdev - virtio device header
271 * @id: virtio device id (as in virtio_ids.h)
272 * @notifyid is a unique rproc-wide notify index for this vdev. This notify
273 * index is used when kicking a remote processor, to let it know that the
274 * status/features of this vdev have changes.
275 * @dfeatures specifies the virtio device features supported by the firmware
276 * @gfeatures is a place holder used by the host to write back the
277 * negotiated features that are supported by both sides.
278 * @config_len is the size of the virtio config space of this vdev. The config
279 * space lies in the resource table immediate after this vdev header.
280 * @status is a place holder where the host will indicate its virtio progress.
281 * @num_of_vrings indicates how many vrings are described in this vdev header
282 * @reserved: reserved (must be zero)
283 * @vring is an array of @num_of_vrings entries of 'struct fw_rsc_vdev_vring'.
284 *
285 * This resource is a virtio device header: it provides information about
286 * the vdev, and is then used by the host and its peer remote processors
287 * to negotiate and share certain virtio properties.
288 *
289 * By providing this resource entry, the firmware essentially asks remoteproc
290 * to statically allocate a vdev upon registration of the rproc (dynamic vdev
291 * allocation is not yet supported).
292 *
293 * Note: unlike virtualization systems, the term 'host' here means
294 * the Linux side which is running remoteproc to control the remote
295 * processors. We use the name 'gfeatures' to comply with virtio's terms,
296 * though there isn't really any virtualized guest OS here: it's the host
297 * which is responsible for negotiating the final features.
298 * Yeah, it's a bit confusing.
299 *
300 * Note: immediately following this structure is the virtio config space for
301 * this vdev (which is specific to the vdev; for more info, read the virtio
302 * spec). the size of the config space is specified by @config_len.
303 */
304struct fw_rsc_vdev {
305 u32 id;
306 u32 notifyid;
307 u32 dfeatures;
308 u32 gfeatures;
309 u32 config_len;
310 u8 status;
311 u8 num_of_vrings;
312 u8 reserved[2];
313 struct fw_rsc_vdev_vring vring[0];
314} __packed;
315
Ohad Ben-Cohen400e64d2011-10-20 16:52:46 +0200316/**
317 * struct rproc_mem_entry - memory entry descriptor
318 * @va: virtual address
319 * @dma: dma address
320 * @len: length, in bytes
321 * @da: device address
322 * @priv: associated data
323 * @node: list node
324 */
325struct rproc_mem_entry {
326 void *va;
327 dma_addr_t dma;
328 int len;
Ohad Ben-Cohenfd2c15e2012-02-01 21:56:16 +0200329 u32 da;
Ohad Ben-Cohen400e64d2011-10-20 16:52:46 +0200330 void *priv;
331 struct list_head node;
332};
333
334struct rproc;
335
336/**
337 * struct rproc_ops - platform-specific device handlers
338 * @start: power on the device and boot it
339 * @stop: power off the device
340 * @kick: kick a virtqueue (virtqueue id given as a parameter)
341 */
342struct rproc_ops {
343 int (*start)(struct rproc *rproc);
344 int (*stop)(struct rproc *rproc);
345 void (*kick)(struct rproc *rproc, int vqid);
346};
347
348/**
349 * enum rproc_state - remote processor states
350 * @RPROC_OFFLINE: device is powered off
351 * @RPROC_SUSPENDED: device is suspended; needs to be woken up to receive
352 * a message.
353 * @RPROC_RUNNING: device is up and running
354 * @RPROC_CRASHED: device has crashed; need to start recovery
355 * @RPROC_LAST: just keep this one at the end
356 *
357 * Please note that the values of these states are used as indices
358 * to rproc_state_string, a state-to-name lookup table,
359 * so please keep the two synchronized. @RPROC_LAST is used to check
360 * the validity of an index before the lookup table is accessed, so
361 * please update it as needed too.
362 */
363enum rproc_state {
364 RPROC_OFFLINE = 0,
365 RPROC_SUSPENDED = 1,
366 RPROC_RUNNING = 2,
367 RPROC_CRASHED = 3,
368 RPROC_LAST = 4,
369};
370
371/**
372 * struct rproc - represents a physical remote processor device
373 * @node: klist node of this rproc object
374 * @domain: iommu domain
375 * @name: human readable name of the rproc
376 * @firmware: name of firmware file to be loaded
377 * @priv: private data which belongs to the platform-specific rproc module
378 * @ops: platform-specific start/stop rproc handlers
379 * @dev: underlying device
380 * @refcount: refcount of users that have a valid pointer to this rproc
381 * @power: refcount of users who need this rproc powered up
382 * @state: state of the device
383 * @lock: lock which protects concurrent manipulations of the rproc
384 * @dbg_dir: debugfs directory of this rproc device
385 * @traces: list of trace buffers
386 * @num_traces: number of trace buffers
387 * @carveouts: list of physically contiguous memory allocations
388 * @mappings: list of iommu mappings we initiated, needed on shutdown
389 * @firmware_loading_complete: marks e/o asynchronous firmware loading
390 * @bootaddr: address of first instruction to boot rproc with (optional)
Ohad Ben-Cohen7a186942012-02-13 22:30:39 +0100391 * @rvdevs: list of remote virtio devices
392 * @notifyids: idr for dynamically assigning rproc-wide unique notify ids
Ohad Ben-Cohen400e64d2011-10-20 16:52:46 +0200393 */
394struct rproc {
395 struct klist_node node;
396 struct iommu_domain *domain;
397 const char *name;
398 const char *firmware;
399 void *priv;
400 const struct rproc_ops *ops;
401 struct device *dev;
402 struct kref refcount;
403 atomic_t power;
404 unsigned int state;
405 struct mutex lock;
406 struct dentry *dbg_dir;
407 struct list_head traces;
408 int num_traces;
409 struct list_head carveouts;
410 struct list_head mappings;
411 struct completion firmware_loading_complete;
Ohad Ben-Cohenfd2c15e2012-02-01 21:56:16 +0200412 u32 bootaddr;
Ohad Ben-Cohen7a186942012-02-13 22:30:39 +0100413 struct list_head rvdevs;
414 struct idr notifyids;
415};
416
417/* we currently support only two vrings per rvdev */
418#define RVDEV_NUM_VRINGS 2
419
420/**
421 * struct rproc_vring - remoteproc vring state
422 * @va: virtual address
423 * @dma: dma address
424 * @len: length, in bytes
425 * @da: device address
426 * @notifyid: rproc-specific unique vring index
427 * @rvdev: remote vdev
428 * @vq: the virtqueue of this vring
429 */
430struct rproc_vring {
431 void *va;
432 dma_addr_t dma;
433 int len;
434 u32 da;
435 int notifyid;
Ohad Ben-Cohen400e64d2011-10-20 16:52:46 +0200436 struct rproc_vdev *rvdev;
Ohad Ben-Cohen7a186942012-02-13 22:30:39 +0100437 struct virtqueue *vq;
Ohad Ben-Cohen400e64d2011-10-20 16:52:46 +0200438};
439
440/**
441 * struct rproc_vdev - remoteproc state for a supported virtio device
Ohad Ben-Cohen7a186942012-02-13 22:30:39 +0100442 * @node: list node
Ohad Ben-Cohen400e64d2011-10-20 16:52:46 +0200443 * @rproc: the rproc handle
444 * @vdev: the virio device
Ohad Ben-Cohen400e64d2011-10-20 16:52:46 +0200445 * @vring: the vrings for this vdev
446 * @dfeatures: virtio device features
447 * @gfeatures: virtio guest features
448 */
449struct rproc_vdev {
Ohad Ben-Cohen7a186942012-02-13 22:30:39 +0100450 struct list_head node;
Ohad Ben-Cohen400e64d2011-10-20 16:52:46 +0200451 struct rproc *rproc;
452 struct virtio_device vdev;
Ohad Ben-Cohen7a186942012-02-13 22:30:39 +0100453 struct rproc_vring vring[RVDEV_NUM_VRINGS];
Ohad Ben-Cohen400e64d2011-10-20 16:52:46 +0200454 unsigned long dfeatures;
455 unsigned long gfeatures;
456};
457
458struct rproc *rproc_get_by_name(const char *name);
459void rproc_put(struct rproc *rproc);
460
461struct rproc *rproc_alloc(struct device *dev, const char *name,
462 const struct rproc_ops *ops,
463 const char *firmware, int len);
464void rproc_free(struct rproc *rproc);
465int rproc_register(struct rproc *rproc);
466int rproc_unregister(struct rproc *rproc);
467
468int rproc_boot(struct rproc *rproc);
469void rproc_shutdown(struct rproc *rproc);
470
Ohad Ben-Cohen7a186942012-02-13 22:30:39 +0100471static inline struct rproc_vdev *vdev_to_rvdev(struct virtio_device *vdev)
472{
473 return container_of(vdev, struct rproc_vdev, vdev);
474}
475
Ohad Ben-Cohen400e64d2011-10-20 16:52:46 +0200476static inline struct rproc *vdev_to_rproc(struct virtio_device *vdev)
477{
Ohad Ben-Cohen7a186942012-02-13 22:30:39 +0100478 struct rproc_vdev *rvdev = vdev_to_rvdev(vdev);
Ohad Ben-Cohen400e64d2011-10-20 16:52:46 +0200479
480 return rvdev->rproc;
481}
482
483#endif /* REMOTEPROC_H */