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
  45 /*
  46  * The alignment between the consumer and producer parts of the vring.
  47  * Note: this is part of the "wire" protocol. If you change this, you need
  48  * to update your peers too.
  49  */
  50 #define AMP_VRING_ALIGN (4096)
  51
  52 /**
  53  * struct fw_resource - describes an entry from the resource section
  54  * @type: resource type
  55  * @id: index number of the resource
  56  * @da: device address of the resource
  57  * @pa: physical address of the resource
  58  * @len: size, in bytes, of the resource
  59  * @flags: properties of the resource, e.g. iommu protection required
  60  * @reserved: must be 0 atm
  61  * @name: name of resource
  62  *
  63  * The remote processor firmware should contain a "resource table":
  64  * array of 'struct fw_resource' entries.
  65  *
  66  * Some resources entries are mere announcements, where the host is informed
  67  * of specific remoteproc configuration. Other entries require the host to
  68  * do something (e.g. reserve a requested resource) and possibly also reply
  69  * by overwriting a member inside 'struct fw_resource' with info about the
  70  * allocated resource.
  71  *
  72  * Different resource entries use different members of this struct,
  73  * with different meanings. This is pretty limiting and error-prone,
  74  * so the plan is to move to variable-length TLV-based resource entries,
  75  * where each resource type will have its own structure.
  76  */
  77 struct fw_resource {
  78         u32 type;
  79         u32 id;
  80         u64 da;
  81         u64 pa;
  82         u32 len;
  83         u32 flags;
  84         u8 reserved[16];
  85         u8 name[48];
  86 } __packed;
  87
  88 /**
  89  * enum fw_resource_type - types of resource entries
  90  *
  91  * @RSC_CARVEOUT:   request for allocation of a physically contiguous
  92  *                  memory region.
  93  * @RSC_DEVMEM:     request to iommu_map a memory-based peripheral.
  94  * @RSC_TRACE:      announces the availability of a trace buffer into which
  95  *                  the remote processor will be writing logs. In this case,
  96  *                  'da' indicates the device address where logs are written to,
  97  *                  and 'len' is the size of the trace buffer.
  98  * @RSC_VRING:      request for allocation of a virtio vring (address should
  99  *                  be indicated in 'da', and 'len' should contain the number
 100  *                  of buffers supported by the vring).
 101  * @RSC_VIRTIO_DEV: this entry declares about support for a virtio device,
 102  *                  and serves as the virtio header. 'da' holds the
 103  *                  the virtio device features, 'pa' holds the virtio guest
 104  *                  features, 'len' holds the virtio status, and 'flags' holds
 105  *                  the virtio id (currently only VIRTIO_ID_RPMSG is supported).
 106  *
 107  * Most of the resource entries share the basic idea of address/length
 108  * negotiation with the host: the firmware usually asks (on behalf of the
 109  * remote processor that will soon be booted with it) for memory
 110  * of size 'len' bytes, and the host needs to allocate it and provide
 111  * the device/physical address (when relevant) in 'da'/'pa' respectively.
 112  *
 113  * If the firmware is compiled with hard coded device addresses, and
 114  * can't handle dynamically allocated 'da' values, then the 'da' field
 115  * will contain the expected device addresses (today we actually only support
 116  * this scheme, as there aren't yet any use cases for dynamically allocated
 117  * device addresses).
 118  */
 119 enum fw_resource_type {
 120         RSC_CARVEOUT    = 0,
 121         RSC_DEVMEM      = 1,
 122         RSC_TRACE       = 2,
 123         RSC_VRING       = 3,
 124         RSC_VIRTIO_DEV  = 4,
 125 };
 126
 127 /**
 128  * struct rproc_mem_entry - memory entry descriptor
 129  * @va: virtual address
 130  * @dma: dma address
 131  * @len: length, in bytes
 132  * @da: device address
 133  * @priv: associated data
 134  * @node: list node
 135  */
 136 struct rproc_mem_entry {
 137         void *va;
 138         dma_addr_t dma;
 139         int len;
 140         u64 da;
 141         void *priv;
 142         struct list_head node;
 143 };
 144
 145 struct rproc;
 146
 147 /**
 148  * struct rproc_ops - platform-specific device handlers
 149  * @start:      power on the device and boot it
 150  * @stop:       power off the device
 151  * @kick:       kick a virtqueue (virtqueue id given as a parameter)
 152  */
 153 struct rproc_ops {
 154         int (*start)(struct rproc *rproc);
 155         int (*stop)(struct rproc *rproc);
 156         void (*kick)(struct rproc *rproc, int vqid);
 157 };
 158
 159 /**
 160  * enum rproc_state - remote processor states
 161  * @RPROC_OFFLINE:      device is powered off
 162  * @RPROC_SUSPENDED:    device is suspended; needs to be woken up to receive
 163  *                      a message.
 164  * @RPROC_RUNNING:      device is up and running
 165  * @RPROC_CRASHED:      device has crashed; need to start recovery
 166  * @RPROC_LAST:         just keep this one at the end
 167  *
 168  * Please note that the values of these states are used as indices
 169  * to rproc_state_string, a state-to-name lookup table,
 170  * so please keep the two synchronized. @RPROC_LAST is used to check
 171  * the validity of an index before the lookup table is accessed, so
 172  * please update it as needed too.
 173  */
 174 enum rproc_state {
 175         RPROC_OFFLINE   = 0,
 176         RPROC_SUSPENDED = 1,
 177         RPROC_RUNNING   = 2,
 178         RPROC_CRASHED   = 3,
 179         RPROC_LAST      = 4,
 180 };
 181
 182 /**
 183  * struct rproc - represents a physical remote processor device
 184  * @node: klist node of this rproc object
 185  * @domain: iommu domain
 186  * @name: human readable name of the rproc
 187  * @firmware: name of firmware file to be loaded
 188  * @priv: private data which belongs to the platform-specific rproc module
 189  * @ops: platform-specific start/stop rproc handlers
 190  * @dev: underlying device
 191  * @refcount: refcount of users that have a valid pointer to this rproc
 192  * @power: refcount of users who need this rproc powered up
 193  * @state: state of the device
 194  * @lock: lock which protects concurrent manipulations of the rproc
 195  * @dbg_dir: debugfs directory of this rproc device
 196  * @traces: list of trace buffers
 197  * @num_traces: number of trace buffers
 198  * @carveouts: list of physically contiguous memory allocations
 199  * @mappings: list of iommu mappings we initiated, needed on shutdown
 200  * @firmware_loading_complete: marks e/o asynchronous firmware loading
 201  * @bootaddr: address of first instruction to boot rproc with (optional)
 202  * @rvdev: virtio device (we only support a single rpmsg virtio device for now)
 203  */
 204 struct rproc {
 205         struct klist_node node;
 206         struct iommu_domain *domain;
 207         const char *name;
 208         const char *firmware;
 209         void *priv;
 210         const struct rproc_ops *ops;
 211         struct device *dev;
 212         struct kref refcount;
 213         atomic_t power;
 214         unsigned int state;
 215         struct mutex lock;
 216         struct dentry *dbg_dir;
 217         struct list_head traces;
 218         int num_traces;
 219         struct list_head carveouts;
 220         struct list_head mappings;
 221         struct completion firmware_loading_complete;
 222         u64 bootaddr;
 223         struct rproc_vdev *rvdev;
 224 };
 225
 226 /**
 227  * struct rproc_vdev - remoteproc state for a supported virtio device
 228  * @rproc: the rproc handle
 229  * @vdev: the virio device
 230  * @vq: the virtqueues for this vdev
 231  * @vring: the vrings for this vdev
 232  * @dfeatures: virtio device features
 233  * @gfeatures: virtio guest features
 234  */
 235 struct rproc_vdev {
 236         struct rproc *rproc;
 237         struct virtio_device vdev;
 238         struct virtqueue *vq[2];
 239         struct rproc_mem_entry vring[2];
 240         unsigned long dfeatures;
 241         unsigned long gfeatures;
 242 };
 243
 244 struct rproc *rproc_get_by_name(const char *name);
 245 void rproc_put(struct rproc *rproc);
 246
 247 struct rproc *rproc_alloc(struct device *dev, const char *name,
 248                                 const struct rproc_ops *ops,
 249                                 const char *firmware, int len);
 250 void rproc_free(struct rproc *rproc);
 251 int rproc_register(struct rproc *rproc);
 252 int rproc_unregister(struct rproc *rproc);
 253
 254 int rproc_boot(struct rproc *rproc);
 255 void rproc_shutdown(struct rproc *rproc);
 256
 257 static inline struct rproc *vdev_to_rproc(struct virtio_device *vdev)
 258 {
 259         struct rproc_vdev *rvdev = container_of(vdev, struct rproc_vdev, vdev);
 260
 261         return rvdev->rproc;
 262 }
 263
 264 #endif /* REMOTEPROC_H */