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