remoteproc: add an api to do pa to da conversion
[rpmsg/rpmsg.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  */
35 #ifndef REMOTEPROC_H
36 #define REMOTEPROC_H
38 #include <linux/types.h>
39 #include <linux/mutex.h>
40 #include <linux/virtio.h>
41 #include <linux/completion.h>
42 #include <linux/idr.h>
43 #include <linux/of.h>
45 /**
46  * struct resource_table - firmware resource table header
47  * @ver: version number
48  * @num: number of resource entries
49  * @reserved: reserved (must be zero)
50  * @offset: array of offsets pointing at the various resource entries
51  *
52  * A resource table is essentially a list of system resources required
53  * by the remote processor. It may also include configuration entries.
54  * If needed, the remote processor firmware should contain this table
55  * as a dedicated ".resource_table" ELF section.
56  *
57  * Some resources entries are mere announcements, where the host is informed
58  * of specific remoteproc configuration. Other entries require the host to
59  * do something (e.g. allocate a system resource). Sometimes a negotiation
60  * is expected, where the firmware requests a resource, and once allocated,
61  * the host should provide back its details (e.g. address of an allocated
62  * memory region).
63  *
64  * The header of the resource table, as expressed by this structure,
65  * contains a version number (should we need to change this format in the
66  * future), the number of available resource entries, and their offsets
67  * in the table.
68  *
69  * Immediately following this header are the resource entries themselves,
70  * each of which begins with a resource entry header (as described below).
71  */
72 struct resource_table {
73         u32 ver;
74         u32 num;
75         u32 reserved[2];
76         u32 offset[0];
77 } __packed;
79 /**
80  * struct fw_rsc_hdr - firmware resource entry header
81  * @type: resource type
82  * @data: resource data
83  *
84  * Every resource entry begins with a 'struct fw_rsc_hdr' header providing
85  * its @type. The content of the entry itself will immediately follow
86  * this header, and it should be parsed according to the resource type.
87  */
88 struct fw_rsc_hdr {
89         u32 type;
90         u8 data[0];
91 } __packed;
93 /**
94  * enum fw_resource_type - types of resource entries
95  *
96  * @RSC_CARVEOUT:   request for allocation of a physically contiguous
97  *                  memory region.
98  * @RSC_DEVMEM:     request to iommu_map a memory-based peripheral.
99  * @RSC_TRACE:      announces the availability of a trace buffer into which
100  *                  the remote processor will be writing logs.
101  * @RSC_VDEV:       declare support for a virtio device, and serve as its
102  *                  virtio header.
103  * @RSC_LAST:       just keep this one at the end
104  *
105  * For more details regarding a specific resource type, please see its
106  * dedicated structure below.
107  *
108  * Please note that these values are used as indices to the rproc_handle_rsc
109  * lookup table, so please keep them sane. Moreover, @RSC_LAST is used to
110  * check the validity of an index before the lookup table is accessed, so
111  * please update it as needed.
112  */
113 enum fw_resource_type {
114         RSC_CARVEOUT    = 0,
115         RSC_DEVMEM      = 1,
116         RSC_TRACE       = 2,
117         RSC_VDEV        = 3,
118         RSC_LAST        = 4,
119 };
121 #define FW_RSC_ADDR_ANY (-1)
123 /**
124  * struct fw_rsc_carveout - physically contiguous memory request
125  * @da: device address
126  * @pa: physical address
127  * @len: length (in bytes)
128  * @flags: iommu protection flags
129  * @reserved: reserved (must be zero)
130  * @name: human-readable name of the requested memory region
131  *
132  * This resource entry requests the host to allocate a physically contiguous
133  * memory region.
134  *
135  * These request entries should precede other firmware resource entries,
136  * as other entries might request placing other data objects inside
137  * these memory regions (e.g. data/code segments, trace resource entries, ...).
138  *
139  * Allocating memory this way helps utilizing the reserved physical memory
140  * (e.g. CMA) more efficiently, and also minimizes the number of TLB entries
141  * needed to map it (in case @rproc is using an IOMMU). Reducing the TLB
142  * pressure is important; it may have a substantial impact on performance.
143  *
144  * If the firmware is compiled with static addresses, then @da should specify
145  * the expected device address of this memory region. If @da is set to
146  * FW_RSC_ADDR_ANY, then the host will dynamically allocate it, and then
147  * overwrite @da with the dynamically allocated address.
148  *
149  * We will always use @da to negotiate the device addresses, even if it
150  * isn't using an iommu. In that case, though, it will obviously contain
151  * physical addresses.
152  *
153  * Some remote processors needs to know the allocated physical address
154  * even if they do use an iommu. This is needed, e.g., if they control
155  * hardware accelerators which access the physical memory directly (this
156  * is the case with OMAP4 for instance). In that case, the host will
157  * overwrite @pa with the dynamically allocated physical address.
158  * Generally we don't want to expose physical addresses if we don't have to
159  * (remote processors are generally _not_ trusted), so we might want to
160  * change this to happen _only_ when explicitly required by the hardware.
161  *
162  * @flags is used to provide IOMMU protection flags, and @name should
163  * (optionally) contain a human readable name of this carveout region
164  * (mainly for debugging purposes).
165  */
166 struct fw_rsc_carveout {
167         u32 da;
168         u32 pa;
169         u32 len;
170         u32 flags;
171         u32 reserved;
172         u8 name[32];
173 } __packed;
175 /**
176  * struct fw_rsc_devmem - iommu mapping request
177  * @da: device address
178  * @pa: physical address
179  * @len: length (in bytes)
180  * @flags: iommu protection flags
181  * @reserved: reserved (must be zero)
182  * @name: human-readable name of the requested region to be mapped
183  *
184  * This resource entry requests the host to iommu map a physically contiguous
185  * memory region. This is needed in case the remote processor requires
186  * access to certain memory-based peripherals; _never_ use it to access
187  * regular memory.
188  *
189  * This is obviously only needed if the remote processor is accessing memory
190  * via an iommu.
191  *
192  * @da should specify the required device address, @pa should specify
193  * the physical address we want to map, @len should specify the size of
194  * the mapping and @flags is the IOMMU protection flags. As always, @name may
195  * (optionally) contain a human readable name of this mapping (mainly for
196  * debugging purposes).
197  *
198  * Note: at this point we just "trust" those devmem entries to contain valid
199  * physical addresses, but this isn't safe and will be changed: eventually we
200  * want remoteproc implementations to provide us ranges of physical addresses
201  * the firmware is allowed to request, and not allow firmwares to request
202  * access to physical addresses that are outside those ranges.
203  */
204 struct fw_rsc_devmem {
205         u32 da;
206         u32 pa;
207         u32 len;
208         u32 flags;
209         u32 reserved;
210         u8 name[32];
211 } __packed;
213 /**
214  * struct fw_rsc_trace - trace buffer declaration
215  * @da: device address
216  * @len: length (in bytes)
217  * @reserved: reserved (must be zero)
218  * @name: human-readable name of the trace buffer
219  *
220  * This resource entry provides the host information about a trace buffer
221  * into which the remote processor will write log messages.
222  *
223  * @da specifies the device address of the buffer, @len specifies
224  * its size, and @name may contain a human readable name of the trace buffer.
225  *
226  * After booting the remote processor, the trace buffers are exposed to the
227  * user via debugfs entries (called trace0, trace1, etc..).
228  */
229 struct fw_rsc_trace {
230         u32 da;
231         u32 len;
232         u32 reserved;
233         u8 name[32];
234 } __packed;
236 /**
237  * struct fw_rsc_vdev_vring - vring descriptor entry
238  * @da: device address
239  * @align: the alignment between the consumer and producer parts of the vring
240  * @num: num of buffers supported by this vring (must be power of two)
241  * @notifyid is a unique rproc-wide notify index for this vring. This notify
242  * index is used when kicking a remote processor, to let it know that this
243  * vring is triggered.
244  * @pa: physical address
245  *
246  * This descriptor is not a resource entry by itself; it is part of the
247  * vdev resource type (see below).
248  *
249  * Note that @da should either contain the device address where
250  * the remote processor is expecting the vring, or indicate that
251  * dynamically allocation of the vring's device address is supported.
252  */
253 struct fw_rsc_vdev_vring {
254         u32 da;
255         u32 align;
256         u32 num;
257         u32 notifyid;
258         u32 pa;
259 } __packed;
261 /**
262  * struct fw_rsc_vdev - virtio device header
263  * @id: virtio device id (as in virtio_ids.h)
264  * @notifyid is a unique rproc-wide notify index for this vdev. This notify
265  * index is used when kicking a remote processor, to let it know that the
266  * status/features of this vdev have changes.
267  * @dfeatures specifies the virtio device features supported by the firmware
268  * @gfeatures is a place holder used by the host to write back the
269  * negotiated features that are supported by both sides.
270  * @config_len is the size of the virtio config space of this vdev. The config
271  * space lies in the resource table immediate after this vdev header.
272  * @status is a place holder where the host will indicate its virtio progress.
273  * @num_of_vrings indicates how many vrings are described in this vdev header
274  * @reserved: reserved (must be zero)
275  * @vring is an array of @num_of_vrings entries of 'struct fw_rsc_vdev_vring'.
276  *
277  * This resource is a virtio device header: it provides information about
278  * the vdev, and is then used by the host and its peer remote processors
279  * to negotiate and share certain virtio properties.
280  *
281  * By providing this resource entry, the firmware essentially asks remoteproc
282  * to statically allocate a vdev upon registration of the rproc (dynamic vdev
283  * allocation is not yet supported).
284  *
285  * Note: unlike virtualization systems, the term 'host' here means
286  * the Linux side which is running remoteproc to control the remote
287  * processors. We use the name 'gfeatures' to comply with virtio's terms,
288  * though there isn't really any virtualized guest OS here: it's the host
289  * which is responsible for negotiating the final features.
290  * Yeah, it's a bit confusing.
291  *
292  * Note: immediately following this structure is the virtio config space for
293  * this vdev (which is specific to the vdev; for more info, read the virtio
294  * spec). the size of the config space is specified by @config_len.
295  */
296 struct fw_rsc_vdev {
297         u32 id;
298         u32 notifyid;
299         u32 dfeatures;
300         u32 gfeatures;
301         u32 config_len;
302         u8 status;
303         u8 num_of_vrings;
304         u8 reserved[2];
305         struct fw_rsc_vdev_vring vring[0];
306 } __packed;
308 /**
309  * struct rproc_mem_entry - memory entry descriptor
310  * @va: virtual address
311  * @dma: dma address
312  * @len: length, in bytes
313  * @da: device address
314  * @priv: associated data
315  * @name: associated memory region name (optional)
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         char name[32];
325         struct list_head node;
326 };
328 struct rproc;
329 struct firmware;
331 /**
332  * struct rproc_ops - platform-specific device handlers
333  * @start:      power on the device and boot it
334  * @stop:       power off the device
335  * @kick:       kick a virtqueue (virtqueue id given as a parameter)
336  * @da_to_va:   optional platform hook to perform address translations
337  * @load_rsc_table:     load resource table from firmware image
338  * @find_loaded_rsc_table: find the loaded resouce table
339  * @load:               load firmeware to memory, where the remote processor
340  *                      expects to find it
341  * @sanity_check:       sanity check the fw image
342  * @get_boot_addr:      get boot address to entry point specified in firmware
343  */
344 struct rproc_ops {
345         int (*start)(struct rproc *rproc);
346         int (*stop)(struct rproc *rproc);
347         void (*kick)(struct rproc *rproc, int vqid);
348         void * (*da_to_va)(struct rproc *rproc, u64 da, int len);
349         int (*parse_fw)(struct rproc *rproc, const struct firmware *fw);
350         struct resource_table *(*find_loaded_rsc_table)(
351                                 struct rproc *rproc, const struct firmware *fw);
352         int (*load)(struct rproc *rproc, const struct firmware *fw);
353         int (*sanity_check)(struct rproc *rproc, const struct firmware *fw);
354         u32 (*get_boot_addr)(struct rproc *rproc, const struct firmware *fw);
355 };
357 /**
358  * enum rproc_state - remote processor states
359  * @RPROC_OFFLINE:      device is powered off
360  * @RPROC_SUSPENDED:    device is suspended; needs to be woken up to receive
361  *                      a message.
362  * @RPROC_RUNNING:      device is up and running
363  * @RPROC_CRASHED:      device has crashed; need to start recovery
364  * @RPROC_DELETED:      device is deleted
365  * @RPROC_LAST:         just keep this one at the end
366  *
367  * Please note that the values of these states are used as indices
368  * to rproc_state_string, a state-to-name lookup table,
369  * so please keep the two synchronized. @RPROC_LAST is used to check
370  * the validity of an index before the lookup table is accessed, so
371  * please update it as needed too.
372  */
373 enum rproc_state {
374         RPROC_OFFLINE   = 0,
375         RPROC_SUSPENDED = 1,
376         RPROC_RUNNING   = 2,
377         RPROC_CRASHED   = 3,
378         RPROC_DELETED   = 4,
379         RPROC_LAST      = 5,
380 };
382 /**
383  * enum rproc_crash_type - remote processor crash types
384  * @RPROC_MMUFAULT:     iommu fault
385  * @RPROC_WATCHDOG:     watchdog bite
386  * @RPROC_FATAL_ERROR   fatal error
387  *
388  * Each element of the enum is used as an array index. So that, the value of
389  * the elements should be always something sane.
390  *
391  * Feel free to add more types when needed.
392  */
393 enum rproc_crash_type {
394         RPROC_MMUFAULT,
395         RPROC_WATCHDOG,
396         RPROC_FATAL_ERROR,
397 };
399 /**
400  * struct rproc_dump_segment - segment info from ELF header
401  * @node:       list node related to the rproc segment list
402  * @da:         device address of the segment
403  * @size:       size of the segment
404  */
405 struct rproc_dump_segment {
406         struct list_head node;
408         dma_addr_t da;
409         size_t size;
411         loff_t offset;
412 };
414 /**
415  * struct rproc - represents a physical remote processor device
416  * @node: list node of this rproc object
417  * @domain: iommu domain
418  * @name: human readable name of the rproc
419  * @firmware: name of firmware file to be loaded
420  * @priv: private data which belongs to the platform-specific rproc module
421  * @ops: platform-specific start/stop rproc handlers
422  * @dev: virtual device for refcounting and common remoteproc behavior
423  * @power: refcount of users who need this rproc powered up
424  * @state: state of the device
425  * @lock: lock which protects concurrent manipulations of the rproc
426  * @dbg_dir: debugfs directory of this rproc device
427  * @traces: list of trace buffers
428  * @num_traces: number of trace buffers
429  * @carveouts: list of physically contiguous memory allocations
430  * @mappings: list of iommu mappings we initiated, needed on shutdown
431  * @bootaddr: address of first instruction to boot rproc with (optional)
432  * @rvdevs: list of remote virtio devices
433  * @subdevs: list of subdevices, to following the running state
434  * @notifyids: idr for dynamically assigning rproc-wide unique notify ids
435  * @index: index of this rproc device
436  * @crash_handler: workqueue for handling a crash
437  * @crash_cnt: crash counter
438  * @recovery_disabled: flag that state if recovery was disabled
439  * @max_notifyid: largest allocated notify id.
440  * @table_ptr: pointer to the resource table in effect
441  * @cached_table: copy of the resource table
442  * @table_sz: size of @cached_table
443  * @has_iommu: flag to indicate if remote processor is behind an MMU
444  * @dump_segments: list of segments in the firmware
445  */
446 struct rproc {
447         struct list_head node;
448         struct iommu_domain *domain;
449         const char *name;
450         char *firmware;
451         void *priv;
452         struct rproc_ops *ops;
453         struct device dev;
454         atomic_t power;
455         unsigned int state;
456         struct mutex lock;
457         struct dentry *dbg_dir;
458         struct list_head traces;
459         int num_traces;
460         struct list_head carveouts;
461         struct list_head mappings;
462         u32 bootaddr;
463         struct list_head rvdevs;
464         struct list_head subdevs;
465         struct idr notifyids;
466         int index;
467         struct work_struct crash_handler;
468         unsigned int crash_cnt;
469         bool recovery_disabled;
470         int max_notifyid;
471         struct resource_table *table_ptr;
472         struct resource_table *cached_table;
473         size_t table_sz;
474         bool has_iommu;
475         bool auto_boot;
476         struct list_head dump_segments;
477 };
479 /**
480  * struct rproc_subdev - subdevice tied to a remoteproc
481  * @node: list node related to the rproc subdevs list
482  * @prepare: prepare function, called before the rproc is started
483  * @start: start function, called after the rproc has been started
484  * @stop: stop function, called before the rproc is stopped; the @crashed
485  *          parameter indicates if this originates from a recovery
486  * @unprepare: unprepare function, called after the rproc has been stopped
487  */
488 struct rproc_subdev {
489         struct list_head node;
491         int (*prepare)(struct rproc_subdev *subdev);
492         int (*start)(struct rproc_subdev *subdev);
493         void (*stop)(struct rproc_subdev *subdev, bool crashed);
494         void (*unprepare)(struct rproc_subdev *subdev);
495 };
497 /* we currently support only two vrings per rvdev */
499 #define RVDEV_NUM_VRINGS 2
501 /**
502  * struct rproc_vring - remoteproc vring state
503  * @va: virtual address
504  * @dma: dma address
505  * @len: length, in bytes
506  * @da: device address
507  * @align: vring alignment
508  * @notifyid: rproc-specific unique vring index
509  * @rvdev: remote vdev
510  * @vq: the virtqueue of this vring
511  */
512 struct rproc_vring {
513         void *va;
514         dma_addr_t dma;
515         int len;
516         u32 da;
517         u32 align;
518         int notifyid;
519         struct rproc_vdev *rvdev;
520         struct virtqueue *vq;
521 };
523 /**
524  * struct rproc_vdev - remoteproc state for a supported virtio device
525  * @refcount: reference counter for the vdev and vring allocations
526  * @subdev: handle for registering the vdev as a rproc subdevice
527  * @id: virtio device id (as in virtio_ids.h)
528  * @node: list node
529  * @rproc: the rproc handle
530  * @vdev: the virio device
531  * @vring: the vrings for this vdev
532  * @rsc_offset: offset of the vdev's resource entry
533  */
534 struct rproc_vdev {
535         struct kref refcount;
537         struct rproc_subdev subdev;
539         unsigned int id;
540         struct list_head node;
541         struct rproc *rproc;
542         struct virtio_device vdev;
543         struct rproc_vring vring[RVDEV_NUM_VRINGS];
544         u32 rsc_offset;
545 };
547 struct rproc *rproc_get_by_phandle(phandle phandle);
548 struct rproc *rproc_get_by_child(struct device *dev);
550 struct rproc *rproc_alloc(struct device *dev, const char *name,
551                           const struct rproc_ops *ops,
552                           const char *firmware, int len);
553 void rproc_put(struct rproc *rproc);
554 int rproc_add(struct rproc *rproc);
555 int rproc_del(struct rproc *rproc);
556 void rproc_free(struct rproc *rproc);
558 int rproc_boot(struct rproc *rproc);
559 void rproc_shutdown(struct rproc *rproc);
560 void rproc_report_crash(struct rproc *rproc, enum rproc_crash_type type);
561 int rproc_coredump_add_segment(struct rproc *rproc, dma_addr_t da, size_t size);
562 int rproc_get_id(struct rproc *rproc);
563 int rproc_pa_to_da(struct rproc *rproc, phys_addr_t pa, u64 *da);
565 static inline struct rproc_vdev *vdev_to_rvdev(struct virtio_device *vdev)
567         return container_of(vdev, struct rproc_vdev, vdev);
570 static inline struct rproc *vdev_to_rproc(struct virtio_device *vdev)
572         struct rproc_vdev *rvdev = vdev_to_rvdev(vdev);
574         return rvdev->rproc;
577 void rproc_add_subdev(struct rproc *rproc, struct rproc_subdev *subdev);
579 void rproc_remove_subdev(struct rproc *rproc, struct rproc_subdev *subdev);
581 #endif /* REMOTEPROC_H */