remoteproc: add framework for controlling remote processors

Modern SoCs typically employ a central symmetric multiprocessing (SMP)
application processor running Linux, with several other asymmetric
multiprocessing (AMP) heterogeneous processors running different instances
of operating system, whether Linux or any other flavor of real-time OS.

Booting a remote processor in an AMP configuration typically involves:
- Loading a firmware which contains the OS image
- Allocating and providing it required system resources (e.g. memory)
- Programming an IOMMU (when relevant)
- Powering on the device

This patch introduces a generic framework that allows drivers to do
that. In the future, this framework will also include runtime power
management and error recovery.

Based on (but now quite far from) work done by Fernando Guzman Lugo
<fernando.lugo@ti.com>.

ELF loader was written by Mark Grosen <mgrosen@ti.com>, based on
msm's Peripheral Image Loader (PIL) by Stephen Boyd <sboyd@codeaurora.org>.

Designed with Brian Swetland <swetland@google.com>.

Signed-off-by: Ohad Ben-Cohen <ohad@wizery.com>
Acked-by: Grant Likely <grant.likely@secretlab.ca>
Cc: Brian Swetland <swetland@google.com>
Cc: Arnd Bergmann <arnd@arndb.de>
Cc: Tony Lindgren <tony@atomide.com>
Cc: Russell King <linux@arm.linux.org.uk>
Cc: Rusty Russell <rusty@rustcorp.com.au>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: Greg KH <greg@kroah.com>
Cc: Stephen Boyd <sboyd@codeaurora.org>

1 files changed, 265 insertions, 0 deletions

diff --git a/include/linux/remoteproc.h b/include/linux/remoteproc.h
new file mode 100644
index 000000000000..1edbfde4593c
--- /dev/null
+++ b/include/linux/remoteproc.h
@@ -0,0 +1,265 @@
+/*
+ * Remote Processor Framework
+ *
+ * Copyright(c) 2011 Texas Instruments, Inc.
+ * Copyright(c) 2011 Google, Inc.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ * * Redistributions in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in
+ *   the documentation and/or other materials provided with the
+ *   distribution.
+ * * Neither the name Texas Instruments nor the names of its
+ *   contributors may be used to endorse or promote products derived
+ *   from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#ifndef REMOTEPROC_H
+#define REMOTEPROC_H
+
+#include <linux/types.h>
+#include <linux/kref.h>
+#include <linux/klist.h>
+#include <linux/mutex.h>
+#include <linux/virtio.h>
+#include <linux/completion.h>
+
+/*
+ * The alignment between the consumer and producer parts of the vring.
+ * Note: this is part of the "wire" protocol. If you change this, you need
+ * to update your peers too.
+ */
+#define AMP_VRING_ALIGN (4096)
+
+/**
+ * struct fw_resource - describes an entry from the resource section
+ * @type: resource type
+ * @id: index number of the resource
+ * @da: device address of the resource
+ * @pa: physical address of the resource
+ * @len: size, in bytes, of the resource
+ * @flags: properties of the resource, e.g. iommu protection required
+ * @reserved: must be 0 atm
+ * @name: name of resource
+ *
+ * The remote processor firmware should contain a "resource table":
+ * array of 'struct fw_resource' entries.
+ *
+ * Some resources entries are mere announcements, where the host is informed
+ * of specific remoteproc configuration. Other entries require the host to
+ * do something (e.g. reserve a requested resource) and possibly also reply
+ * by overwriting a member inside 'struct fw_resource' with info about the
+ * allocated resource.
+ *
+ * Different resource entries use different members of this struct,
+ * with different meanings. This is pretty limiting and error-prone,
+ * so the plan is to move to variable-length TLV-based resource entries,
+ * where each resource type will have its own structure.
+ */
+struct fw_resource {
+        u32 type;
+        u32 id;
+        u64 da;
+        u64 pa;
+        u32 len;
+        u32 flags;
+        u8 reserved[16];
+        u8 name[48];
+} __packed;
+
+/**
+ * enum fw_resource_type - types of resource entries
+ *
+ * @RSC_CARVEOUT:   request for allocation of a physically contiguous
+ *                  memory region.
+ * @RSC_DEVMEM:     request to iommu_map a memory-based peripheral.
+ * @RSC_TRACE:      announces the availability of a trace buffer into which
+ *                  the remote processor will be writing logs. In this case,
+ *                  'da' indicates the device address where logs are written to,
+ *                  and 'len' is the size of the trace buffer.
+ * @RSC_VRING:      request for allocation of a virtio vring (address should
+ *                  be indicated in 'da', and 'len' should contain the number
+ *                  of buffers supported by the vring).
+ * @RSC_VIRTIO_DEV: this entry declares about support for a virtio device,
+ *                  and serves as the virtio header. 'da' holds the
+ *                  the virtio device features, 'pa' holds the virtio guest
+ *                  features, 'len' holds the virtio status, and 'flags' holds
+ *                  the virtio id (currently only VIRTIO_ID_RPMSG is supported).
+ *
+ * Most of the resource entries share the basic idea of address/length
+ * negotiation with the host: the firmware usually asks (on behalf of the
+ * remote processor that will soon be booted with it) for memory
+ * of size 'len' bytes, and the host needs to allocate it and provide
+ * the device/physical address (when relevant) in 'da'/'pa' respectively.
+ *
+ * If the firmware is compiled with hard coded device addresses, and
+ * can't handle dynamically allocated 'da' values, then the 'da' field
+ * will contain the expected device addresses (today we actually only support
+ * this scheme, as there aren't yet any use cases for dynamically allocated
+ * device addresses).
+ */
+enum fw_resource_type {
+        RSC_CARVEOUT    = 0,
+        RSC_DEVMEM      = 1,
+        RSC_TRACE       = 2,
+        RSC_VRING       = 3,
+        RSC_VIRTIO_DEV  = 4,
+        RSC_VIRTIO_CFG  = 5,
+};
+
+/**
+ * struct rproc_mem_entry - memory entry descriptor
+ * @va: virtual address
+ * @dma: dma address
+ * @len: length, in bytes
+ * @da: device address
+ * @priv: associated data
+ * @node: list node
+ */
+struct rproc_mem_entry {
+        void *va;
+        dma_addr_t dma;
+        int len;
+        u64 da;
+        void *priv;
+        struct list_head node;
+};
+
+struct rproc;
+
+/**
+ * struct rproc_ops - platform-specific device handlers
+ * @start:      power on the device and boot it
+ * @stop:       power off the device
+ * @kick:       kick a virtqueue (virtqueue id given as a parameter)
+ */
+struct rproc_ops {
+        int (*start)(struct rproc *rproc);
+        int (*stop)(struct rproc *rproc);
+        void (*kick)(struct rproc *rproc, int vqid);
+};
+
+/**
+ * enum rproc_state - remote processor states
+ * @RPROC_OFFLINE:      device is powered off
+ * @RPROC_SUSPENDED:    device is suspended; needs to be woken up to receive
+ *                      a message.
+ * @RPROC_RUNNING:      device is up and running
+ * @RPROC_CRASHED:      device has crashed; need to start recovery
+ * @RPROC_LAST:         just keep this one at the end
+ *
+ * Please note that the values of these states are used as indices
+ * to rproc_state_string, a state-to-name lookup table,
+ * so please keep the two synchronized. @RPROC_LAST is used to check
+ * the validity of an index before the lookup table is accessed, so
+ * please update it as needed too.
+ */
+enum rproc_state {
+        RPROC_OFFLINE   = 0,
+        RPROC_SUSPENDED = 1,
+        RPROC_RUNNING   = 2,
+        RPROC_CRASHED   = 3,
+        RPROC_LAST      = 4,
+};
+
+/**
+ * struct rproc - represents a physical remote processor device
+ * @node: klist node of this rproc object
+ * @domain: iommu domain
+ * @name: human readable name of the rproc
+ * @firmware: name of firmware file to be loaded
+ * @priv: private data which belongs to the platform-specific rproc module
+ * @ops: platform-specific start/stop rproc handlers
+ * @dev: underlying device
+ * @refcount: refcount of users that have a valid pointer to this rproc
+ * @power: refcount of users who need this rproc powered up
+ * @state: state of the device
+ * @lock: lock which protects concurrent manipulations of the rproc
+ * @dbg_dir: debugfs directory of this rproc device
+ * @traces: list of trace buffers
+ * @num_traces: number of trace buffers
+ * @carveouts: list of physically contiguous memory allocations
+ * @mappings: list of iommu mappings we initiated, needed on shutdown
+ * @firmware_loading_complete: marks e/o asynchronous firmware loading
+ * @bootaddr: address of first instruction to boot rproc with (optional)
+ * @rvdev: virtio device (we only support a single rpmsg virtio device for now)
+ */
+struct rproc {
+        struct klist_node node;
+        struct iommu_domain *domain;
+        const char *name;
+        const char *firmware;
+        void *priv;
+        const struct rproc_ops *ops;
+        struct device *dev;
+        struct kref refcount;
+        atomic_t power;
+        unsigned int state;
+        struct mutex lock;
+        struct dentry *dbg_dir;
+        struct list_head traces;
+        int num_traces;
+        struct list_head carveouts;
+        struct list_head mappings;
+        struct completion firmware_loading_complete;
+        u64 bootaddr;
+        struct rproc_vdev *rvdev;
+};
+
+/**
+ * struct rproc_vdev - remoteproc state for a supported virtio device
+ * @rproc: the rproc handle
+ * @vdev: the virio device
+ * @vq: the virtqueues for this vdev
+ * @vring: the vrings for this vdev
+ * @dfeatures: virtio device features
+ * @gfeatures: virtio guest features
+ */
+struct rproc_vdev {
+        struct rproc *rproc;
+        struct virtio_device vdev;
+        struct virtqueue *vq[2];
+        struct rproc_mem_entry vring[2];
+        unsigned long dfeatures;
+        unsigned long gfeatures;
+};
+
+struct rproc *rproc_get_by_name(const char *name);
+void rproc_put(struct rproc *rproc);
+
+struct rproc *rproc_alloc(struct device *dev, const char *name,
+                                const struct rproc_ops *ops,
+                                const char *firmware, int len);
+void rproc_free(struct rproc *rproc);
+int rproc_register(struct rproc *rproc);
+int rproc_unregister(struct rproc *rproc);
+
+int rproc_boot(struct rproc *rproc);
+void rproc_shutdown(struct rproc *rproc);
+
+static inline struct rproc *vdev_to_rproc(struct virtio_device *vdev)
+{
+        struct rproc_vdev *rvdev = container_of(vdev, struct rproc_vdev, vdev);
+
+        return rvdev->rproc;
+}
+
+#endif /* REMOTEPROC_H */