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
180