rpmsg: rpc: introduce a new rpmsg_rpc driver
[rpmsg/rpmsg.git] / drivers / rpmsg / rpmsg_rpc_internal.h
1 /* SPDX-License-Identifier: (GPL-2.0 OR BSD-3-Clause) */
2 /*
3  * Remote Processor Procedure Call Driver
4  *
5  * Copyright (C) 2012-2019 Texas Instruments Incorporated - http://www.ti.com/
6  */
8 #ifndef _RPMSG_RPC_INTERNAL_H_
9 #define _RPMSG_RPC_INTERNAL_H_
11 #include <linux/cdev.h>
12 #include <linux/idr.h>
13 #include <linux/wait.h>
14 #include <linux/fs.h>
15 #include <linux/skbuff.h>
17 typedef u32 virt_addr_t;
18 typedef u32 dev_addr_t;
20 /**
21  * struct rppc_device - The per-device (server) data
22  * @cdev: character device
23  * @dev: device
24  * @rpdev: rpmsg channel device associated with the remote server
25  * @instances: list of currently opened/connected instances
26  * @lock: mutex for protection of device variables
27  * @comp: completion signal used for unblocking users during a
28  *        remote processor recovery
29  * @sig_attr: array of device attributes to use with the publishing of
30  *            function information in sysfs for all the functions
31  *            associated with this remote server device.
32  * @signatures: function signatures for the functions published by this
33  *              remote server device
34  * @minor: minor number for the character device
35  * @num_funcs: number of functions published by this remote server device
36  * @cur_func: counter used while querying information for each function
37  *            associated with this remote server device
38  *
39  * A rppc_device indicates the base remote server device that supports the
40  * execution of a bunch of remote functions. Each such remote server device
41  * has an associated character device that is used by the userland apps to
42  * connect to it, and request the execution of any of these remote functions.
43  */
44 struct rppc_device {
45         struct cdev cdev;
46         struct device *dev;
47         struct rpmsg_device *rpdev;
48         struct list_head instances;
49         struct mutex lock; /* device state variables lock */
50         struct completion comp;
51         struct device_attribute *sig_attr;
52         struct rppc_func_signature *signatures;
53         unsigned int minor;
54         u32 num_funcs;
55         u32 cur_func;
56 };
58 /**
59  * struct rppc_instance - The per-instance data structure (per user)
60  * @list: list node
61  * @rppcdev: the rppc device (remote server instance) handle
62  * @queue: queue of buffers waiting to be read by the user
63  * @lock: mutex for protecting instance variables
64  * @readq: wait queue of blocked user threads waiting to read data
65  * @reply_arrived: signal for unblocking the user thread
66  * @ept: rpmsg endpoint associated with the rppc device
67  * @in_transition: flag for storing a pending connection request
68  * @dst: destination end-point of the remote server instance
69  * @state: state of the opened instance, see enum rppc_state
70  * @dma_idr: idr structure storing the imported buffers
71  * @msg_id: last/current active message id tagged on a message sent
72  *          to the remote processor
73  * @fxn_list: list of functions published by the remote server instance
74  *
75  * This structure is created whenever the user opens the driver. The
76  * various elements of the structure are used to store its state and
77  * information about the remote server it is connected to.
78  */
79 struct rppc_instance {
80         struct list_head list;
81         struct rppc_device *rppcdev;
82         struct sk_buff_head queue;
83         struct mutex lock; /* instance state variables lock */
84         wait_queue_head_t readq;
85         struct completion reply_arrived;
86         struct rpmsg_endpoint *ept;
87         int in_transition;
88         u32 dst;
89         int state;
90         struct idr dma_idr;
91         u16 msg_id;
92         struct list_head fxn_list;
93 };
95 /**
96  * struct rppc_function_list - outstanding function descriptor
97  * @list: list node
98  * @function: current remote function descriptor
99  * @msg_id: message id for the function invocation
100  *
101  * This structure is used for storing the information about outstanding
102  * functions that the remote side is executing. This provides the host
103  * side a means to track every outstanding function, and a means to process
104  * the responses received from the remote processor.
105  */
106 struct rppc_function_list {
107         struct list_head list;
108         struct rppc_function *function;
109         u16 msg_id;
110 };
112 /**
113  * struct rppc_dma_buf - a rppc dma_buf descriptor for buffers imported by rppc
114  * @fd: file descriptor of a buffer used to import the dma_buf
115  * @id: idr index value for this descriptor
116  * @buf: imported dma_buf handle for the buffer
117  * @attach: attachment structure returned by exporter upon attaching to
118  *          the buffer by the rppc driver
119  * @sgt: the scatter-gather structure associated with @buf
120  * @pa: the physical address associated with the imported buffer
121  * @autoreg: mode of how the descriptor is created
122  *
123  * This structure is used for storing the information relevant to the imported
124  * buffer. The rpmsg rpc driver acts as a proxy on behalf of the remote core
125  * and attaches itself to the driver while the remote processor/accelerators are
126  * operating on the buffer.
127  */
128 struct rppc_dma_buf {
129         int fd;
130         int id;
131         struct dma_buf *buf;
132         struct dma_buf_attachment *attach;
133         struct sg_table *sgt;
134         phys_addr_t pa;
135         int autoreg;
136 };
138 /**
139  * enum rppc_msg_type - message types exchanged between host and remote server
140  * @RPPC_MSGTYPE_DEVINFO_REQ: request remote server for channel information
141  * @RPPC_MSGTYPE_DEVINFO_RESP: response message from remote server for a
142  *                             request of type RPPC_MSGTYPE_DEVINFO_REQ
143  * @RPPC_MSGTYPE_FUNCTION_QUERY: request remote server for information about a
144  *                               specific function
145  * @RPPC_MSGTYPE_FUNCTION_INFO: response message from remote server for a prior
146  *                              request of type RPPC_MSGTYPE_FUNCTION_QUERY
147  * @RPPC_MSGTYPE_CREATE_REQ: request the remote server manager to create a new
148  *                           remote server instance. No secondary data is
149  *                           needed
150  * @RPPC_MSGTYPE_CREATE_RESP: response message from remote server manager for a
151  *                            request of type RPPC_MSGTYPE_CREATE_REQ. The
152  *                            message contains the new endpoint address in the
153  *                            rppc_instance_handle
154  * @RPPC_MSGTYPE_DELETE_REQ: request the remote server manager to delete a
155  *                           remote server instance
156  * @RPPC_MSGTYPE_DELETE_RESP: response message from remote server manager to a
157  *                            request of type RPPC_MSGTYPE_DELETE_REQ. The
158  *                            message contains the old endpoint address in the
159  *                            rppc_instance_handle
160  * @RPPC_MSGTYPE_FUNCTION_CALL: request remote server to execute a specific
161  *                              function
162  * @RPPC_MSGTYPE_FUNCTION_RET: response message carrying the return status of a
163  *                             specific function execution
164  * @RPPC_MSGTYPE_ERROR: an error response message sent by either the remote
165  *                      server manager or remote server instance while
166  *                      processing any request messages
167  * @RPPC_MSGTYPE_MAX: limit value to define the maximum message type value
168  *
169  * Every message exchanged between the host-side and the remote-side is
170  * identified through a message type defined in this enum. The message type
171  * is specified through the msg_type field of the struct rppc_msg_header,
172  * which is the common header for rppc messages.
173  */
174 enum rppc_msg_type {
175         RPPC_MSGTYPE_DEVINFO_REQ        = 0,
176         RPPC_MSGTYPE_DEVINFO_RESP       = 1,
177         RPPC_MSGTYPE_FUNCTION_QUERY     = 2,
178         RPPC_MSGTYPE_FUNCTION_INFO      = 3,
179         RPPC_MSGTYPE_CREATE_REQ         = 6,
180         RPPC_MSGTYPE_CREATE_RESP        = 8,
181         RPPC_MSGTYPE_DELETE_REQ         = 4,
182         RPPC_MSGTYPE_DELETE_RESP        = 7,
183         RPPC_MSGTYPE_FUNCTION_CALL      = 5,
184         RPPC_MSGTYPE_FUNCTION_RET       = 9,
185         RPPC_MSGTYPE_ERROR = 10,
186         RPPC_MSGTYPE_MAX
187 };
189 /**
190  * enum rppc_infotype - function information query type
191  * @RPPC_INFOTYPE_FUNC_SIGNATURE: function signature
192  * @RPPC_INFOTYPE_NUM_CALLS: the number of times a function has been invoked
193  * @RPPC_INFOTYPE_MAX: limit value to define the maximum info type
194  *
195  * This enum is used for identifying the type of information queried
196  * from the remote processor. Only RPPC_INFOTYPE_FUNC_SIGNATURE is
197  * currently used.
198  */
199 enum rppc_infotype {
200         RPPC_INFOTYPE_FUNC_SIGNATURE = 1,
201         RPPC_INFOTYPE_NUM_CALLS,
202         RPPC_INFOTYPE_MAX
203 };
205 /**
206  * struct rppc_instance_handle - rppc instance information
207  * @endpoint_address: end-point address of the remote server instance
208  * @status: status of the request
209  *
210  * This structure indicates the format of the message payload exchanged
211  * between the host and the remote sides for messages pertaining to
212  * creation and deletion of the remote server instances. This payload
213  * is associated with messages of type RPPC_MSGTYPE_CREATE_RESP and
214  * RPPC_MSGTYPE_DELETE_RESP.
215  */
216 struct rppc_instance_handle {
217         u32 endpoint_address;
218         u32 status;
219 } __packed;
221 /**
222  * struct rppc_param_signature - parameter descriptor
223  * @direction: input or output classifier, see enum rppc_param_direction
224  * @type: parameter data type, see enum rppc_param_type
225  * @count: used to do some basic sanity checking on array bounds
226  */
227 struct rppc_param_signature {
228         u32 direction;
229         u32 type;
230         u32 count;
231 };
233 /**
234  * struct rppc_func_signature - remote function signature descriptor
235  * @name: name of the function
236  * @num_param: number of parameters to the function
237  * @params: parameter descriptors for each of the parameters
238  *
239  * This structure contains the indicates the format of the message payload
240  * exchanged between the host and the remote sides for messages pertaining
241  * to creation and deletion of the remote server instances. This payload
242  * is associated with messages of type RPPC_MSGTYPE_CREATE_RESP and
243  * RPPC_MSGTYPE_FUNCTION_INFO.
244  */
245 struct rppc_func_signature {
246         char name[RPPC_MAX_CHANNEL_NAMELEN];
247         u32 num_param;
248         struct rppc_param_signature params[RPPC_MAX_NUM_PARAMS + 1];
249 };
251 /**
252  * struct rppc_query_function - function info packet structure
253  * @info_type: type of the function information requested, see
254  *             enum rppc_infotype
255  * @fxn_id: function identifier on this specific remote server instance
256  * @num_calls: number of types function is invoked, filled in during a response
257  *             (only valid for rppc_infotype RPPC_INFOTYPE_NUM_CALLS)
258  * @signature: the signature of the function including its return type,
259  *             parameters and their description
260  *             (only valid for rppc_infotype RPPC_INFOTYPE_FUNC_SIGNATURE)
261  *
262  * This structure indicates the format of the message payload exchanged
263  * between the host and the remote sides for messages pertaining to
264  * information about each function supported by the remote server instance.
265  * This payload is associated with messages of type RPPC_MSGTYPE_FUNCTION_QUERY
266  * and RPPC_MSGTYPE_FUNCTION_INFO.
267  */
268 struct rppc_query_function {
269         u32 info_type;
270         u32 fxn_id;
271         union {
272                 u32 num_calls;
273                 struct rppc_func_signature signature;
274         } info;
275 };
277 /**
278  * enum rppc_translate_direction - pointer translation direction
279  * @RPPC_UVA_TO_RPA: user virtual address to remote device address translation
280  * @RPPC_RPA_TO_UVA: remote device address to user virtual address translation
281  *
282  * An enum used for identifying the rppc function message direction, whether
283  * it is going to the remote side, or is a response from the remote side. This
284  * is used in translating the pointers from the host-side to the remote-side
285  * and vice versa depending on the packet direction.
286  */
287 enum rppc_translate_direction {
288         RPPC_UVA_TO_RPA,
289         RPPC_RPA_TO_UVA,
290 };
292 /**
293  * enum rppc_state - rppc instance state
294  * @RPPC_STATE_DISCONNECTED: uninitialized state
295  * @RPPC_STATE_CONNECTED: initialized state
296  * @RPPC_STATE_STALE: invalid or stale state
297  * @RPPC_STATE_MAX: limit value for the different state values
298  *
299  * This enum value is used to define the status values of a
300  * rppc_instance object.
301  */
302 enum rppc_state {
303         RPPC_STATE_DISCONNECTED,
304         RPPC_STATE_CONNECTED,
305         RPPC_STATE_STALE,
306         RPPC_STATE_MAX
307 };
309 /**
310  * struct rppc_device_info - rppc remote server device info
311  * @num_funcs: number of functions supported by a remote server instance
312  *
313  * This structure indicates the format of the message payload responded by
314  * the remote side upon a request for message type RPPC_MSGTYPE_DEVINFO_REQ.
315  * This payload is associated with messages of type RPPC_MSGTYPE_DEVINFO_RESP.
316  */
317 struct rppc_device_info {
318         u32 num_funcs;
319 };
321 /**
322  * struct rppc_error - rppc error information
323  * @endpoint_address: end-point address of the remote server instance
324  * @status: status of the request
325  *
326  * This structure indicates the format of the message payload exchanged
327  * between the host and the remote sides for error messages. This payload
328  * is associated with messages of type RPPC_MSGTYPE_ERROR
329  * XXX: check if this is needed still, not used anywhere at present
330  */
331 struct rppc_error {
332         u32 endpoint_address;
333         u32 status;
334 } __packed;
336 /**
337  * struct rppc_param_data - marshalled parameter data structure
338  * @size: size of the parameter data type
339  * @data: actual parameter data
340  *
341  * Each function parameter is marshalled in this form between the host
342  * and remote sides. The @data field would contain the actual value of
343  * of the parameter if it is a scalar argument type, or the remote-side
344  * device address (virtual address) of the pointer if the argument is
345  * of pointer type.
346  */
347 struct rppc_param_data {
348         size_t size;
349         size_t data;
350 } __packed;
352 /**
353  * struct rppc_msg_header - generic rpmsg rpc message header
354  * @msg_type: message type, see enum rppc_msg_type
355  * @msg_len: length of the message payload in bytes
356  * @msg_data: the actual message payload (depends on message type)
357  *
358  * All RPPC messages will start with this common header (which will begin
359  * right after the standard rpmsg header ends).
360  */
361 struct rppc_msg_header {
362         u32 msg_type;
363         u32 msg_len;
364         u8  msg_data[0];
365 } __packed;
367 #define RPPC_PAYLOAD(ptr, type) \
368                 ((struct type *)&(ptr)[sizeof(struct rppc_msg_header)])
370 /* from rpmsg_rpc.c */
371 dev_addr_t rppc_local_to_remote_da(struct rppc_instance *rpc, phys_addr_t pa);
373 /* from rpmsg_rpc_dmabuf.c */
374 struct rppc_dma_buf *rppc_alloc_dmabuf(struct rppc_instance *rpc,
375                                        int fd, bool autoreg);
376 struct rppc_dma_buf *rppc_find_dmabuf(struct rppc_instance *rpc, int fd);
377 int rppc_free_dmabuf(int id, void *p, void *data);
378 dev_addr_t rppc_buffer_lookup(struct rppc_instance *rpc, virt_addr_t uva,
379                               virt_addr_t buva, int fd);
380 int rppc_xlate_buffers(struct rppc_instance *rpc, struct rppc_function *func,
381                        int direction);
383 /* from rpmsg_rpc_sysfs.c */
384 int rppc_create_sysfs(struct rppc_device *rppcdev);
385 int rppc_remove_sysfs(struct rppc_device *rppcdev);
387 #endif