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

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