include/linux/remoteproc.h - kernel/msm - Gitiles

 /*
  * 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 */
	/*
	* 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 */