include/linux/remoteproc.h

/*
 * 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).
 * @RSC_LAST:       just keep this one at the end
 *
 * 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).
 *
 * Please note that these values are used as indices to the rproc_handle_rsc
 * lookup table, so please keep them sane. Moreover, @RSC_LAST is used to
 * check the validity of an index before the lookup table is accessed, so
 * please update it as needed.
 */
enum fw_resource_type {
	RSC_CARVEOUT	= 0,
	RSC_DEVMEM	= 1,
	RSC_TRACE	= 2,
	RSC_VRING	= 3,
	RSC_VIRTIO_DEV	= 4,
	RSC_LAST	= 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 */