path: root/include/asm-arm/arch-mxc/mxc_ipc.h

/*
 * Copyright 2004-2007 Freescale Semiconductor, Inc. All Rights Reserved.
 */

/*
 * The code contained herein is licensed under the GNU General Public
 * License. You may obtain a copy of the GNU General Public License
 * Version 2 or later at the following locations:
 *
 * http://www.opensource.org/licenses/gpl-license.html
 * http://www.gnu.org/copyleft/gpl.html
 */

/*!
 * @defgroup IPC InterProcessor Communication (IPC)
 */

/*!
 * @file arch-mxc/mxc_ipc.h
 *
 * @brief This file contains the IPC API configuration details and
 * public API declarations.
 *
 * @ingroup IPC
 */
#ifndef __ASM_ARCH_MXC_IPC_H__
#define __ASM_ARCH_MXC_IPC_H__

/*!
 * This enum defines the different status of an IPC link
 */
typedef enum {
	HW_CTRL_IPC_STATUS_OK = 0,
	HW_CTRL_IPC_STATUS_CHANNEL_UNAVAILABLE,
	HW_CTRL_IPC_STATUS_IPC_SUSPENDED,
	HW_CTRL_IPC_STATUS_READ_ON_GOING,
	HW_CTRL_IPC_STATUS_WRITE_ON_GOING,
	HW_CTRL_IPC_STATUS_INIT_ALREADY_CALLED,
	HW_CTRL_IPC_STATUS_ERROR
} HW_CTRL_IPC_STATUS_T;

/*!
 * This typedef defines the ioctls available
 * for kernel modules using IPC.
 */
typedef enum {
	HW_CTRL_IPC_SET_READ_CALLBACK = 0,
	HW_CTRL_IPC_SET_WRITE_CALLBACK,
	HW_CTRL_IPC_SET_NOTIFY_CALLBACK,
	HW_CTRL_IPC_SET_MAX_CTRL_STRUCT_NB
} HW_CTRL_IPC_IOCTL_ACTION_T;

/*!
 * Definition of IPC channel types
 *
 * There are currently three types of channels:
 *
 * - Short Message channels. Used to transfer 32-bits
 *   messages from MCU to DSP and vice versa
 *
 * - Packet Data channels. Useful to transfer data between
 *   the two cores.
 *
 * - Logging channel. This type of channel is read-only from
 *   the MCU. It is used to report log events to the MCU.
 *
 */
typedef enum {
	HW_CTRL_IPC_PACKET_DATA = 0,
	HW_CTRL_IPC_CHANNEL_LOG,
	HW_CTRL_IPC_SHORT_MSG
} HW_CTRL_IPC_CHANNEL_TYPE_T;

/*!
 * This enum defines the write modes IPC can support.
 *
 * - Contigous mode: All data is stored in a contigous
 *   memory zone.
 *
 * - LinkedList mode: Data can be presented in chunks of
 *   non-contiguous memory. Up to 11 chunks can be processed
 *   by this mode.
 *
 *  Note that only Packet Data channels can support LinkedList mode.
 */
typedef enum {
	HW_CTRL_IPC_MODE_CONTIGUOUS = 0,
	HW_CTRL_IPC_MODE_LINKED_LIST
} HW_CTRL_IPC_MODE_T;

typedef struct {
} HW_CTRL_IPC_INIT_T;

typedef struct {
	/*!
	 * the channel from which data was read
	 */
	int channel_nb;
} HW_CTRL_IPC_CHANNEL_T;

/*!
 * A structure of this type is passed as parameter when a read
 * callback is invoked. This normally happens when a read transfer has been
 * completed.
 */
typedef struct {
	/*!
	 * the channel handler from which data was read
	 */
	HW_CTRL_IPC_CHANNEL_T *channel;

	/*!
	 * number of bytes read.
	 */
	int nb_bytes;
} HW_CTRL_IPC_READ_STATUS_T;

/*!
 * A structure of this type is passed as parameter when a write
 * callback is invoked. This normally happens when a write transfer has been
 * completed.
 */
#define HW_CTRL_IPC_WRITE_STATUS_T     HW_CTRL_IPC_READ_STATUS_T

/*!
 * A structure of this type is passed as parameter when a notify
 * callback is invoked. This happens only when a transfer has been
 * abnormally terminated.
 */
typedef struct {
	/*!
	 * the channel handler from which data was read
	 */
	HW_CTRL_IPC_CHANNEL_T *channel;

	/*!
	 * status code
	 */
	HW_CTRL_IPC_STATUS_T status;
} HW_CTRL_IPC_NOTIFY_STATUS_T;

/*
 * This struct defines parameters needed to
 * execute a write using the linked list mode
 */
typedef struct HW_CTRL_IPC_LINKED_LIST_T {
	/*!
	 * pointer to data to be transfered
	 */
	unsigned char *data_ptr;

	/*!
	 * Lenght of data
	 */
	unsigned int length;

	/*!
	 * Pointer to the next chunk of memory containing data
	 * to be transferred
	 */
	struct HW_CTRL_IPC_LINKED_LIST_T *next;
} HW_CTRL_IPC_LINKED_LIST_T;

/*
 * This struct defines parameters needed to
 * execute a write using the normal mode
 */
typedef struct {
	/*!
	 * pointer to data to be transfered
	 */
	unsigned char *data_ptr;

	/*!
	 * Lenght of data
	 */
	unsigned int length;
} HW_CTRL_IPC_CONTIGUOUS_T;

/*
 * This structure is used by the write_ex function
 * which is in charge of execute the LinkedList mode
 * transfer.
 */
typedef struct {
	/*!
	 * Type of transfer to execute
	 */
	HW_CTRL_IPC_MODE_T ipc_memory_read_mode;

	/*!
	 * Pointer to a buffer holding all data to
	 * transfer orpointer to a buffer holding
	 * first chunk of data to transfer
	 */
	union {
		HW_CTRL_IPC_CONTIGUOUS_T *cont_ptr;
		HW_CTRL_IPC_LINKED_LIST_T *list_ptr;
	} read;
} HW_CTRL_IPC_WRITE_PARAMS_T;

/*
 * Structure used to pass configuration parameters needed
 * to open an IPC channel.
 */
typedef struct {
	/*!
	 * type of IPC channel to open
	 */
	HW_CTRL_IPC_CHANNEL_TYPE_T type;

	/*!
	 * index defining the physical channel
	 * that will be used for this IPC channel
	 */
	int index;

	/*!
	 * read callback provided by the user, called when a read
	 * transfer has been finished
	 */
	void (*read_callback) (HW_CTRL_IPC_READ_STATUS_T * status);

	/*!
	 * write callback provided by the user, called when a write
	 * transfer has been finished
	 */
	void (*write_callback) (HW_CTRL_IPC_WRITE_STATUS_T * status);

	/*!
	 * notify callback provided by the user, called when an error
	 * occurs during a transfer.
	 */
	void (*notify_callback) (HW_CTRL_IPC_NOTIFY_STATUS_T * status);
} HW_CTRL_IPC_OPEN_T;

/*!@param *data_control_struct_ipcv2
 *   Data Node Descriptor (Buffer Descriptor):
 *------------------------------------------------------------------------------
 *| 31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16	15	 …	  0|
 *------------------------------------------------------------------------------
 *| L	E	D	R	R	R	R	R	|<---- Reserved          ---->  |<- Length-> |
 *------------------------------------------------------------------------------
 *| <---------------------------- Data Ptr ----------------------------------->|
 *------------------------------------------------------------------------------
 *
 * L bit (LAST): If set, means that this buffer of data is the last buffer of the frame
 * E bit (END): If set, we reached the end of the buffers passed to the function
 * D bit (DONE): Only valid on the read callback. When set, means that the buffer has been
 * filled by the SDMA.
 * Length: Length of data pointed by this node in bytes
 * Data Ptr: Pointer to the data pointed to by this node.
 */
typedef struct ipc_dataNodeDescriptor {
	unsigned short length;
	unsigned short comand;
	void *data_ptr;
} HW_CTRL_IPC_DATA_NODE_DESCRIPTOR_T;

/*!
 * Opens an IPC link. This functions can be called directly by kernel
 * modules. POSIX implementation of the IPC Driver also calls it.
 *
 * @param config	Pointer to a struct containing configuration para
 * 			meters for the channel to open (type of channel,
 *			callbacks, etc)
 *
 * @return		returns a virtual channel handler on success, a NULL pointer otherwise.
 */
HW_CTRL_IPC_CHANNEL_T *hw_ctrl_ipc_open(const HW_CTRL_IPC_OPEN_T * config);

/*!
 * Close an IPC link. This functions can be called directly by kernel
 * modules. POSIX implementation of the IPC Driver also calls it.
 *
 * @param channel	handler to the virtual channel to close.
 *
 * @return		returns HW_CTRL_IPC_STATUS_OK on success, an error code
 *			otherwise.
 */
HW_CTRL_IPC_STATUS_T hw_ctrl_ipc_close(HW_CTRL_IPC_CHANNEL_T * channel);

/*!
 * Reads data from an IPC link. This functions can be called directly by kernel
 * modules. POSIX implementation of the IPC Driver also calls it.
 *
 * @param channel	virtual channel handler where read has been requested.
 * @param buf		buffer to store data read from the channel.
 * @param buffer_size	size of the buffer
 *
 * @return		returns HW_CTRL_IPC_STATUS_OK on success, an error code
 *			otherwise.
 */
HW_CTRL_IPC_STATUS_T hw_ctrl_ipc_read(HW_CTRL_IPC_CHANNEL_T * channel,
				      unsigned char *buf,
				      unsigned short buffer_size);

/*!
 * Writes data to an IPC link. This functions can be called directly by kernel
 * modules. POSIX implementation of the IPC Driver also calls it.
 *
 * @param channel	virtual handler to the channel where read has been requested.
 * @param buf		buffer containing data t be written on the channel.
 * @param buffer_size	size of the buffer
 *
 * @return		returns HW_CTRL_IPC_STATUS_OK on success, an error code
 *			otherwise.
 */
HW_CTRL_IPC_STATUS_T hw_ctrl_ipc_write(HW_CTRL_IPC_CHANNEL_T * channel,
				       unsigned char *buf,
				       unsigned short nb_bytes);

/*!
 * Writes data to an IPC link. This function can be called directly by kernel
 * modules. It accepts a linked list or contiguous data.
 *
 * @param channel       handler to the virtual channel where read has
 *                      been requested.
 * @param mem_ptr       of type HW_CTRL_IPC_WRITE_PARAMS_T.
 *
 * @return              returns HW_CTRL_IPC_STATUS_OK on success, an error code
 *                      otherwise.
 */
HW_CTRL_IPC_STATUS_T hw_ctrl_ipc_write_ex(HW_CTRL_IPC_CHANNEL_T * channel,
					  HW_CTRL_IPC_WRITE_PARAMS_T * mem_ptr);

/*!
 * Used to set various channel parameters
 *
 * @param channel handler to the virtual channel where read has
 *                been requested.
 * @param action  IPC driver control action to perform.
 * @param param   parameters required to complete the requested action
 */
HW_CTRL_IPC_STATUS_T hw_ctrl_ipc_ioctl(HW_CTRL_IPC_CHANNEL_T * channel,
				       HW_CTRL_IPC_IOCTL_ACTION_T action,
				       void *param);

/*!
 * This function is a variant on the write() function, and is used to send a
 * group of frames made of various pieces each to the IPC driver.
 * It is mandatory to allow high throughput on IPC while minimizing the time
 * spent in the drivers / interrupts.
 *
 * @param channel       handler to the virtual channel where read has
 *                      been requested.
 * @param ctrl_ptr      Pointer on the control structure.
 *
 * @return              returns HW_CTRL_IPC_STATUS_OK on success, an error code
 *                      otherwise.
 */
HW_CTRL_IPC_STATUS_T hw_ctrl_ipc_write_ex2(HW_CTRL_IPC_CHANNEL_T * channel,
					   HW_CTRL_IPC_DATA_NODE_DESCRIPTOR_T *
					   ctrl_ptr);

/*!
 * This function is used to give a set of buffers to the IPC and enable data
 * transfers.
 *
 * @param channel       handler to the virtual channel where read has
 *                      been requested.
 * @param ctrl_ptr      Pointer on the control structure.
 *
 * @return              returns HW_CTRL_IPC_STATUS_OK on success, an error code
 *                      otherwise.
 */
HW_CTRL_IPC_STATUS_T hw_ctrl_ipc_read_ex2(HW_CTRL_IPC_CHANNEL_T * channel,
					  HW_CTRL_IPC_DATA_NODE_DESCRIPTOR_T *
					  ctrl_ptr);
#endif				//MXC_IPC_H