~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/include/linux/remoteproc.h

Version: ~ [ linux-5.4-rc3 ] ~ [ linux-5.3.6 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.79 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.149 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.196 ] ~ [ linux-4.8.17 ] ~ [ linux-4.7.10 ] ~ [ linux-4.6.7 ] ~ [ linux-4.5.7 ] ~ [ linux-4.4.196 ] ~ [ linux-4.3.6 ] ~ [ linux-4.2.8 ] ~ [ linux-4.1.52 ] ~ [ linux-4.0.9 ] ~ [ linux-3.19.8 ] ~ [ linux-3.18.140 ] ~ [ linux-3.17.8 ] ~ [ linux-3.16.75 ] ~ [ linux-3.15.10 ] ~ [ linux-3.14.79 ] ~ [ linux-3.13.11 ] ~ [ linux-3.12.74 ] ~ [ linux-3.11.10 ] ~ [ linux-3.10.108 ] ~ [ linux-3.9.11 ] ~ [ linux-3.8.13 ] ~ [ linux-3.7.10 ] ~ [ linux-3.6.11 ] ~ [ linux-3.5.7 ] ~ [ linux-3.4.113 ] ~ [ linux-3.3.8 ] ~ [ linux-3.2.102 ] ~ [ linux-3.1.10 ] ~ [ linux-3.0.101 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.5 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

  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/klist.h>
 40 #include <linux/mutex.h>
 41 #include <linux/virtio.h>
 42 #include <linux/completion.h>
 43 #include <linux/idr.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 (0xFFFFFFFFFFFFFFFF)
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  * @reserved: reserved (must be zero)
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 reserved;
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  */
334 struct rproc_ops {
335         int (*start)(struct rproc *rproc);
336         int (*stop)(struct rproc *rproc);
337         void (*kick)(struct rproc *rproc, int vqid);
338 };
339 
340 /**
341  * enum rproc_state - remote processor states
342  * @RPROC_OFFLINE:      device is powered off
343  * @RPROC_SUSPENDED:    device is suspended; needs to be woken up to receive
344  *                      a message.
345  * @RPROC_RUNNING:      device is up and running
346  * @RPROC_CRASHED:      device has crashed; need to start recovery
347  * @RPROC_LAST:         just keep this one at the end
348  *
349  * Please note that the values of these states are used as indices
350  * to rproc_state_string, a state-to-name lookup table,
351  * so please keep the two synchronized. @RPROC_LAST is used to check
352  * the validity of an index before the lookup table is accessed, so
353  * please update it as needed too.
354  */
355 enum rproc_state {
356         RPROC_OFFLINE   = 0,
357         RPROC_SUSPENDED = 1,
358         RPROC_RUNNING   = 2,
359         RPROC_CRASHED   = 3,
360         RPROC_LAST      = 4,
361 };
362 
363 /**
364  * enum rproc_crash_type - remote processor crash types
365  * @RPROC_MMUFAULT:     iommu fault
366  *
367  * Each element of the enum is used as an array index. So that, the value of
368  * the elements should be always something sane.
369  *
370  * Feel free to add more types when needed.
371  */
372 enum rproc_crash_type {
373         RPROC_MMUFAULT,
374 };
375 
376 /**
377  * struct rproc - represents a physical remote processor device
378  * @node: klist node of this rproc object
379  * @domain: iommu domain
380  * @name: human readable name of the rproc
381  * @firmware: name of firmware file to be loaded
382  * @priv: private data which belongs to the platform-specific rproc module
383  * @ops: platform-specific start/stop rproc handlers
384  * @dev: virtual device for refcounting and common remoteproc behavior
385  * @fw_ops: firmware-specific handlers
386  * @power: refcount of users who need this rproc powered up
387  * @state: state of the device
388  * @lock: lock which protects concurrent manipulations of the rproc
389  * @dbg_dir: debugfs directory of this rproc device
390  * @traces: list of trace buffers
391  * @num_traces: number of trace buffers
392  * @carveouts: list of physically contiguous memory allocations
393  * @mappings: list of iommu mappings we initiated, needed on shutdown
394  * @firmware_loading_complete: marks e/o asynchronous firmware loading
395  * @bootaddr: address of first instruction to boot rproc with (optional)
396  * @rvdevs: list of remote virtio devices
397  * @notifyids: idr for dynamically assigning rproc-wide unique notify ids
398  * @index: index of this rproc device
399  * @crash_handler: workqueue for handling a crash
400  * @crash_cnt: crash counter
401  * @crash_comp: completion used to sync crash handler and the rproc reload
402  * @recovery_disabled: flag that state if recovery was disabled
403  * @max_notifyid: largest allocated notify id.
404  */
405 struct rproc {
406         struct klist_node node;
407         struct iommu_domain *domain;
408         const char *name;
409         const char *firmware;
410         void *priv;
411         const struct rproc_ops *ops;
412         struct device dev;
413         const struct rproc_fw_ops *fw_ops;
414         atomic_t power;
415         unsigned int state;
416         struct mutex lock;
417         struct dentry *dbg_dir;
418         struct list_head traces;
419         int num_traces;
420         struct list_head carveouts;
421         struct list_head mappings;
422         struct completion firmware_loading_complete;
423         u32 bootaddr;
424         struct list_head rvdevs;
425         struct idr notifyids;
426         int index;
427         struct work_struct crash_handler;
428         unsigned crash_cnt;
429         struct completion crash_comp;
430         bool recovery_disabled;
431         int max_notifyid;
432 };
433 
434 /* we currently support only two vrings per rvdev */
435 #define RVDEV_NUM_VRINGS 2
436 
437 /**
438  * struct rproc_vring - remoteproc vring state
439  * @va: virtual address
440  * @dma: dma address
441  * @len: length, in bytes
442  * @da: device address
443  * @align: vring alignment
444  * @notifyid: rproc-specific unique vring index
445  * @rvdev: remote vdev
446  * @vq: the virtqueue of this vring
447  */
448 struct rproc_vring {
449         void *va;
450         dma_addr_t dma;
451         int len;
452         u32 da;
453         u32 align;
454         int notifyid;
455         struct rproc_vdev *rvdev;
456         struct virtqueue *vq;
457 };
458 
459 /**
460  * struct rproc_vdev - remoteproc state for a supported virtio device
461  * @node: list node
462  * @rproc: the rproc handle
463  * @vdev: the virio device
464  * @vring: the vrings for this vdev
465  * @dfeatures: virtio device features
466  * @gfeatures: virtio guest features
467  */
468 struct rproc_vdev {
469         struct list_head node;
470         struct rproc *rproc;
471         struct virtio_device vdev;
472         struct rproc_vring vring[RVDEV_NUM_VRINGS];
473         unsigned long dfeatures;
474         unsigned long gfeatures;
475 };
476 
477 struct rproc *rproc_alloc(struct device *dev, const char *name,
478                                 const struct rproc_ops *ops,
479                                 const char *firmware, int len);
480 void rproc_put(struct rproc *rproc);
481 int rproc_add(struct rproc *rproc);
482 int rproc_del(struct rproc *rproc);
483 
484 int rproc_boot(struct rproc *rproc);
485 void rproc_shutdown(struct rproc *rproc);
486 void rproc_report_crash(struct rproc *rproc, enum rproc_crash_type type);
487 
488 static inline struct rproc_vdev *vdev_to_rvdev(struct virtio_device *vdev)
489 {
490         return container_of(vdev, struct rproc_vdev, vdev);
491 }
492 
493 static inline struct rproc *vdev_to_rproc(struct virtio_device *vdev)
494 {
495         struct rproc_vdev *rvdev = vdev_to_rvdev(vdev);
496 
497         return rvdev->rproc;
498 }
499 
500 #endif /* REMOTEPROC_H */
501 

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | Wiki (Japanese) | Wiki (English) | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

osdn.jp