arch/arm/include/asm/arch-tegra/ivc.h

   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