Home | History | Annotate | Download | only in arch-tegra 
      1 /* SPDX-License-Identifier: GPL-2.0 */
      2 /*
      3  * Copyright (c) 2016, NVIDIA CORPORATION.
      4  */
      5 
      6 #ifndef _ASM_ARCH_TEGRA_IVC_H
      7 #define _ASM_ARCH_TEGRA_IVC_H
      8 
      9 #include <common.h>
     10 
     11 /*
     12  * Tegra IVC is a communication protocol that transfers fixed-size frames
     13  * bi-directionally and in-order between the local CPU and some remote entity.
     14  * Communication is via a statically sized and allocated buffer in shared
     15  * memory and a notification mechanism.
     16  *
     17  * This API handles all aspects of the shared memory buffer's metadata, and
     18  * leaves all aspects of the frame content to the calling code; frames
     19  * typically contain some higher-level protocol. The notification mechanism is
     20  * also handled externally to this API, since it can vary from instance to
     21  * instance.
     22  *
     23  * The client model is to first find some free (for TX) or filled (for RX)
     24  * frame, process that frame's memory buffer (fill or read it), and then
     25  * inform the protocol that the frame has been filled/read, i.e. advance the
     26  * write/read pointer. If the channel is full, there may be no available frames
     27  * to fill/read. In this case, client code may either poll for an available
     28  * frame, or wait for the remote entity to send a notification to the local
     29  * CPU.
     30  */
     31 
     32 /**
     33  * struct tegra_ivc - In-memory shared memory layout.
     34  *
     35  * This is described in detail in ivc.c.
     36  */
     37 struct tegra_ivc_channel_header;
     38 
     39 /**
     40  * struct tegra_ivc - Software state of an IVC channel.
     41  *
     42  * This state is internal to the IVC code and should not be accessed directly
     43  * by clients. It is public solely so clients can allocate storage for the
     44  * structure.
     45  */
     46 struct tegra_ivc {
     47 	/**
     48 	 * rx_channel - Pointer to the shared memory region used to receive
     49 	 * messages from the remote entity.
     50 	 */
     51 	struct tegra_ivc_channel_header *rx_channel;
     52 	/**
     53 	 * tx_channel - Pointer to the shared memory region used to send
     54 	 * messages to the remote entity.
     55 	 */
     56 	struct tegra_ivc_channel_header *tx_channel;
     57 	/**
     58 	 * r_pos - The position in list of frames in rx_channel that we are
     59 	 * reading from.
     60 	 */
     61 	uint32_t r_pos;
     62 	/**
     63 	 * w_pos - The position in list of frames in tx_channel that we are
     64 	 * writing to.
     65 	 */
     66 	uint32_t w_pos;
     67 	/**
     68 	 * nframes - The number of frames allocated (in each direction) in
     69 	 * shared memory.
     70 	 */
     71 	uint32_t nframes;
     72 	/**
     73 	 * frame_size - The size of each frame in shared memory.
     74 	 */
     75 	uint32_t frame_size;
     76 	/**
     77 	 * notify - Function to call to notify the remote processor of a
     78 	 * change in channel state.
     79 	 */
     80 	void (*notify)(struct tegra_ivc *);
     81 };
     82 
     83 /**
     84  * tegra_ivc_read_get_next_frame - Locate the next frame to receive.
     85  *
     86  * Locate the next frame to be received/processed, return the address of the
     87  * frame, and do not remove it from the queue. Repeated calls to this function
     88  * will return the same address until tegra_ivc_read_advance() is called.
     89  *
     90  * @ivc		The IVC channel.
     91  * @frame	Pointer to be filled with the address of the frame to receive.
     92  *
     93  * @return 0 if a frame is available, else a negative error code.
     94  */
     95 int tegra_ivc_read_get_next_frame(struct tegra_ivc *ivc, void **frame);
     96 
     97 /**
     98  * tegra_ivc_read_advance - Advance the read queue.
     99  *
    100  * Inform the protocol and remote entity that the frame returned by
    101  * tegra_ivc_read_get_next_frame() has been processed. The remote end may then
    102  * re-use it to transmit further data. Subsequent to this function returning,
    103  * tegra_ivc_read_get_next_frame() will return a different frame.
    104  *
    105  * @ivc		The IVC channel.
    106  *
    107  * @return 0 if OK, else a negative error code.
    108  */
    109 int tegra_ivc_read_advance(struct tegra_ivc *ivc);
    110 
    111 /**
    112  * tegra_ivc_write_get_next_frame - Locate the next frame to fill for transmit.
    113  *
    114  * Locate the next frame to be filled for transmit, return the address of the
    115  * frame, and do not add it to the queue. Repeated calls to this function
    116  * will return the same address until tegra_ivc_read_advance() is called.
    117  *
    118  * @ivc		The IVC channel.
    119  * @frame	Pointer to be filled with the address of the frame to fill.
    120  *
    121  * @return 0 if a frame is available, else a negative error code.
    122  */
    123 int tegra_ivc_write_get_next_frame(struct tegra_ivc *ivc, void **frame);
    124 
    125 /**
    126  * tegra_ivc_write_advance - Advance the write queue.
    127  *
    128  * Inform the protocol and remote entity that the frame returned by
    129  * tegra_ivc_write_get_next_frame() has been filled and should be transmitted.
    130  * The remote end may then read data from it. Subsequent to this function
    131  * returning, tegra_ivc_write_get_next_frame() will return a different frame.
    132  *
    133  * @ivc		The IVC channel.
    134  *
    135  * @return 0 if OK, else a negative error code.
    136  */
    137 int tegra_ivc_write_advance(struct tegra_ivc *ivc);
    138 
    139 /**
    140  * tegra_ivc_channel_notified - handle internal messages
    141  *
    142  * This function must be called following every notification.
    143  *
    144  * @ivc		The IVC channel.
    145  *
    146  * @return 0 if the channel is ready for communication, or -EAGAIN if a
    147  * channel reset is in progress.
    148  */
    149 int tegra_ivc_channel_notified(struct tegra_ivc *ivc);
    150 
    151 /**
    152  * tegra_ivc_channel_reset - initiates a reset of the shared memory state
    153  *
    154  * This function must be called after a channel is initialized but before it
    155  * is used for communication. The channel will be ready for use when a
    156  * subsequent call to notify the remote of the channel reset indicates the
    157  * reset operation is complete.
    158  *
    159  * @ivc		The IVC channel.
    160  */
    161 void tegra_ivc_channel_reset(struct tegra_ivc *ivc);
    162 
    163 /**
    164  * tegra_ivc_init - Initialize a channel's software state.
    165  *
    166  * @ivc		The IVC channel.
    167  * @rx_base	Address of the the RX shared memory buffer.
    168  * @tx_base	Address of the the TX shared memory buffer.
    169  * @nframes	Number of frames in each shared memory buffer.
    170  * @frame_size	Size of each frame.
    171  *
    172  * @return 0 if OK, else a negative error code.
    173  */
    174 int tegra_ivc_init(struct tegra_ivc *ivc, ulong rx_base, ulong tx_base,
    175 		   uint32_t nframes, uint32_t frame_size,
    176 		   void (*notify)(struct tegra_ivc *));
    177 
    178 #endif
    179