]> git.karo-electronics.de Git - karo-tx-linux.git/blob - include/linux/remoteproc.h
Merge tag 'for-linus-4.11b-rc4-tag' of git://git.kernel.org/pub/scm/linux/kernel...
[karo-tx-linux.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/mutex.h>
40 #include <linux/virtio.h>
41 #include <linux/completion.h>
42 #include <linux/idr.h>
43 #include <linux/of.h>
44
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;
78
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;
92
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 };
120
121 #define FW_RSC_ADDR_ANY (-1)
122
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;
174
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;
212
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;
235
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;
260
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;
307
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  * @node: list node
316  */
317 struct rproc_mem_entry {
318         void *va;
319         dma_addr_t dma;
320         int len;
321         u32 da;
322         void *priv;
323         struct list_head node;
324 };
325
326 struct rproc;
327
328 /**
329  * struct rproc_ops - platform-specific device handlers
330  * @start:      power on the device and boot it
331  * @stop:       power off the device
332  * @kick:       kick a virtqueue (virtqueue id given as a parameter)
333  * @da_to_va:   optional platform hook to perform address translations
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         void * (*da_to_va)(struct rproc *rproc, u64 da, int len);
340 };
341
342 /**
343  * enum rproc_state - remote processor states
344  * @RPROC_OFFLINE:      device is powered off
345  * @RPROC_SUSPENDED:    device is suspended; needs to be woken up to receive
346  *                      a message.
347  * @RPROC_RUNNING:      device is up and running
348  * @RPROC_CRASHED:      device has crashed; need to start recovery
349  * @RPROC_DELETED:      device is deleted
350  * @RPROC_LAST:         just keep this one at the end
351  *
352  * Please note that the values of these states are used as indices
353  * to rproc_state_string, a state-to-name lookup table,
354  * so please keep the two synchronized. @RPROC_LAST is used to check
355  * the validity of an index before the lookup table is accessed, so
356  * please update it as needed too.
357  */
358 enum rproc_state {
359         RPROC_OFFLINE   = 0,
360         RPROC_SUSPENDED = 1,
361         RPROC_RUNNING   = 2,
362         RPROC_CRASHED   = 3,
363         RPROC_DELETED   = 4,
364         RPROC_LAST      = 5,
365 };
366
367 /**
368  * enum rproc_crash_type - remote processor crash types
369  * @RPROC_MMUFAULT:     iommu fault
370  * @RPROC_WATCHDOG:     watchdog bite
371  * @RPROC_FATAL_ERROR   fatal error
372  *
373  * Each element of the enum is used as an array index. So that, the value of
374  * the elements should be always something sane.
375  *
376  * Feel free to add more types when needed.
377  */
378 enum rproc_crash_type {
379         RPROC_MMUFAULT,
380         RPROC_WATCHDOG,
381         RPROC_FATAL_ERROR,
382 };
383
384 /**
385  * struct rproc - represents a physical remote processor device
386  * @node: list node of this rproc object
387  * @domain: iommu domain
388  * @name: human readable name of the rproc
389  * @firmware: name of firmware file to be loaded
390  * @priv: private data which belongs to the platform-specific rproc module
391  * @ops: platform-specific start/stop rproc handlers
392  * @dev: virtual device for refcounting and common remoteproc behavior
393  * @fw_ops: firmware-specific handlers
394  * @power: refcount of users who need this rproc powered up
395  * @state: state of the device
396  * @lock: lock which protects concurrent manipulations of the rproc
397  * @dbg_dir: debugfs directory of this rproc device
398  * @traces: list of trace buffers
399  * @num_traces: number of trace buffers
400  * @carveouts: list of physically contiguous memory allocations
401  * @mappings: list of iommu mappings we initiated, needed on shutdown
402  * @bootaddr: address of first instruction to boot rproc with (optional)
403  * @rvdevs: list of remote virtio devices
404  * @subdevs: list of subdevices, to following the running state
405  * @notifyids: idr for dynamically assigning rproc-wide unique notify ids
406  * @index: index of this rproc device
407  * @crash_handler: workqueue for handling a crash
408  * @crash_cnt: crash counter
409  * @crash_comp: completion used to sync crash handler and the rproc reload
410  * @recovery_disabled: flag that state if recovery was disabled
411  * @max_notifyid: largest allocated notify id.
412  * @table_ptr: pointer to the resource table in effect
413  * @cached_table: copy of the resource table
414  * @has_iommu: flag to indicate if remote processor is behind an MMU
415  */
416 struct rproc {
417         struct list_head node;
418         struct iommu_domain *domain;
419         const char *name;
420         char *firmware;
421         void *priv;
422         const struct rproc_ops *ops;
423         struct device dev;
424         const struct rproc_fw_ops *fw_ops;
425         atomic_t power;
426         unsigned int state;
427         struct mutex lock;
428         struct dentry *dbg_dir;
429         struct list_head traces;
430         int num_traces;
431         struct list_head carveouts;
432         struct list_head mappings;
433         u32 bootaddr;
434         struct list_head rvdevs;
435         struct list_head subdevs;
436         struct idr notifyids;
437         int index;
438         struct work_struct crash_handler;
439         unsigned int crash_cnt;
440         struct completion crash_comp;
441         bool recovery_disabled;
442         int max_notifyid;
443         struct resource_table *table_ptr;
444         struct resource_table *cached_table;
445         bool has_iommu;
446         bool auto_boot;
447 };
448
449 /**
450  * struct rproc_subdev - subdevice tied to a remoteproc
451  * @node: list node related to the rproc subdevs list
452  * @probe: probe function, called as the rproc is started
453  * @remove: remove function, called as the rproc is stopped
454  */
455 struct rproc_subdev {
456         struct list_head node;
457
458         int (*probe)(struct rproc_subdev *subdev);
459         void (*remove)(struct rproc_subdev *subdev);
460 };
461
462 /* we currently support only two vrings per rvdev */
463
464 #define RVDEV_NUM_VRINGS 2
465
466 /**
467  * struct rproc_vring - remoteproc vring state
468  * @va: virtual address
469  * @dma: dma address
470  * @len: length, in bytes
471  * @da: device address
472  * @align: vring alignment
473  * @notifyid: rproc-specific unique vring index
474  * @rvdev: remote vdev
475  * @vq: the virtqueue of this vring
476  */
477 struct rproc_vring {
478         void *va;
479         dma_addr_t dma;
480         int len;
481         u32 da;
482         u32 align;
483         int notifyid;
484         struct rproc_vdev *rvdev;
485         struct virtqueue *vq;
486 };
487
488 /**
489  * struct rproc_vdev - remoteproc state for a supported virtio device
490  * @refcount: reference counter for the vdev and vring allocations
491  * @subdev: handle for registering the vdev as a rproc subdevice
492  * @id: virtio device id (as in virtio_ids.h)
493  * @node: list node
494  * @rproc: the rproc handle
495  * @vdev: the virio device
496  * @vring: the vrings for this vdev
497  * @rsc_offset: offset of the vdev's resource entry
498  */
499 struct rproc_vdev {
500         struct kref refcount;
501
502         struct rproc_subdev subdev;
503
504         unsigned int id;
505         struct list_head node;
506         struct rproc *rproc;
507         struct virtio_device vdev;
508         struct rproc_vring vring[RVDEV_NUM_VRINGS];
509         u32 rsc_offset;
510 };
511
512 struct rproc *rproc_get_by_phandle(phandle phandle);
513 struct rproc *rproc_alloc(struct device *dev, const char *name,
514                           const struct rproc_ops *ops,
515                           const char *firmware, int len);
516 void rproc_put(struct rproc *rproc);
517 int rproc_add(struct rproc *rproc);
518 int rproc_del(struct rproc *rproc);
519 void rproc_free(struct rproc *rproc);
520
521 int rproc_boot(struct rproc *rproc);
522 void rproc_shutdown(struct rproc *rproc);
523 void rproc_report_crash(struct rproc *rproc, enum rproc_crash_type type);
524
525 static inline struct rproc_vdev *vdev_to_rvdev(struct virtio_device *vdev)
526 {
527         return container_of(vdev, struct rproc_vdev, vdev);
528 }
529
530 static inline struct rproc *vdev_to_rproc(struct virtio_device *vdev)
531 {
532         struct rproc_vdev *rvdev = vdev_to_rvdev(vdev);
533
534         return rvdev->rproc;
535 }
536
537 void rproc_add_subdev(struct rproc *rproc,
538                       struct rproc_subdev *subdev,
539                       int (*probe)(struct rproc_subdev *subdev),
540                       void (*remove)(struct rproc_subdev *subdev));
541
542 void rproc_remove_subdev(struct rproc *rproc, struct rproc_subdev *subdev);
543
544 #endif /* REMOTEPROC_H */