1 /* SPDX-License-Identifier: GPL-2.0 */
3 * Copyright (c) 2016, NVIDIA CORPORATION.
6 #ifndef _ASM_ARCH_TEGRA_IVC_H
7 #define _ASM_ARCH_TEGRA_IVC_H
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.
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
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
33 * struct tegra_ivc - In-memory shared memory layout.
35 * This is described in detail in ivc.c.
37 struct tegra_ivc_channel_header;
40 * struct tegra_ivc - Software state of an IVC channel.
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
48 * rx_channel - Pointer to the shared memory region used to receive
49 * messages from the remote entity.
51 struct tegra_ivc_channel_header *rx_channel;
53 * tx_channel - Pointer to the shared memory region used to send
54 * messages to the remote entity.
56 struct tegra_ivc_channel_header *tx_channel;
58 * r_pos - The position in list of frames in rx_channel that we are
63 * w_pos - The position in list of frames in tx_channel that we are
68 * nframes - The number of frames allocated (in each direction) in
73 * frame_size - The size of each frame in shared memory.
77 * notify - Function to call to notify the remote processor of a
78 * change in channel state.
80 void (*notify)(struct tegra_ivc *);
84 * tegra_ivc_read_get_next_frame - Locate the next frame to receive.
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.
90 * @ivc The IVC channel.
91 * @frame Pointer to be filled with the address of the frame to receive.
93 * @return 0 if a frame is available, else a negative error code.
95 int tegra_ivc_read_get_next_frame(struct tegra_ivc *ivc, void **frame);
98 * tegra_ivc_read_advance - Advance the read queue.
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.
105 * @ivc The IVC channel.
107 * @return 0 if OK, else a negative error code.
109 int tegra_ivc_read_advance(struct tegra_ivc *ivc);
112 * tegra_ivc_write_get_next_frame - Locate the next frame to fill for transmit.
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.
118 * @ivc The IVC channel.
119 * @frame Pointer to be filled with the address of the frame to fill.
121 * @return 0 if a frame is available, else a negative error code.
123 int tegra_ivc_write_get_next_frame(struct tegra_ivc *ivc, void **frame);
126 * tegra_ivc_write_advance - Advance the write queue.
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.
133 * @ivc The IVC channel.
135 * @return 0 if OK, else a negative error code.
137 int tegra_ivc_write_advance(struct tegra_ivc *ivc);
140 * tegra_ivc_channel_notified - handle internal messages
142 * This function must be called following every notification.
144 * @ivc The IVC channel.
146 * @return 0 if the channel is ready for communication, or -EAGAIN if a
147 * channel reset is in progress.
149 int tegra_ivc_channel_notified(struct tegra_ivc *ivc);
152 * tegra_ivc_channel_reset - initiates a reset of the shared memory state
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.
159 * @ivc The IVC channel.
161 void tegra_ivc_channel_reset(struct tegra_ivc *ivc);
164 * tegra_ivc_init - Initialize a channel's software state.
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.
172 * @return 0 if OK, else a negative error code.
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 *));