rpmsg: rpc: introduce a new rpmsg_rpc driver
[rpmsg/rpmsg.git] / include / uapi / linux / rpmsg_rpc.h
1 /* SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) 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 _UAPI_LINUX_RPMSG_RPC_H_
9 #define _UAPI_LINUX_RPMSG_RPC_H_
11 #include <linux/ioctl.h>
13 /**
14  * struct rppc_buf_fds - rppc buffer registration/deregistration
15  * @num: number of file descriptors
16  * @fds: pointer to the array holding the file descriptors
17  */
18 struct rppc_buf_fds {
19         uint32_t num;
20         int32_t *fds;
21 };
23 /*
24  * ioctl definitions
25  */
26 #define RPPC_IOC_MAGIC          'r'
27 #define RPPC_IOC_CREATE         _IOW(RPPC_IOC_MAGIC, 1, char *)
28 #define RPPC_IOC_BUFREGISTER    _IOW(RPPC_IOC_MAGIC, 2, struct rppc_buf_fds)
29 #define RPPC_IOC_BUFUNREGISTER  _IOW(RPPC_IOC_MAGIC, 3, struct rppc_buf_fds)
30 #define RPPC_IOC_MAXNR          (4)
32 #define RPPC_MAX_PARAMETERS     (10)
33 #define RPPC_MAX_TRANSLATIONS   (1024)
34 #define RPPC_MAX_INST_NAMELEN   (48)
36 /**
37  * enum rppc_param_type - RPC function parameter type
38  * @RPPC_PARAM_TYPE_UNKNOWN: unrecognized parameter
39  * @RPPC_PARAM_TYPE_ATOMIC: an atomic data type, 1 byte to architecture limit
40  *                          sized bytes
41  * @RPPC_PARAM_TYPE_PTR: a pointer to shared memory. The fd field in the
42  *                       structures rppc_param and rppc_param_translation must
43  *                       contain the file descriptor of the associated dma_buf
44  * @RPPC_PARAM_TYPE_STRUCT: (unsupported) a structure type. Will be architecture
45  *                          width aligned in memory
46  *
47  * These enum values are used to identify the parameter type for every
48  * parameter argument of the remote function.
49  */
50 enum rppc_param_type {
51         RPPC_PARAM_TYPE_UNKNOWN = 0,
52         RPPC_PARAM_TYPE_ATOMIC,
53         RPPC_PARAM_TYPE_PTR,
54         RPPC_PARAM_TYPE_STRUCT,
55 };
57 /**
58  * struct rppc_param_translation - pointer translation helper structure
59  * @index: index of the parameter where the translation needs to be done in.
60  *         used for computing the primary offset and mapping into kernel
61  *         the page from the buffer referred to in the corresponding parameter
62  * @offset: offset from the primary base pointer to the pointer to translate.
63  *          This is the secondary offset, and used either for mentioning the
64  *          offset from an structure array element base, or within a single
65  *          structure which itself is at an offset in an allocated buffer
66  * @base: the base user virtual address of the pointer to translate (used to
67  *        calculate translated pointer offset)
68  * @fd: dma_buf file descriptor of the allocated buffer pointer within which
69  *      the translated pointer is present
70  */
71 struct rppc_param_translation {
72         uint32_t index;
73         ptrdiff_t offset;
74         size_t base;
75         int32_t fd;
76 };
78 /**
79  * struct rppc_param - descriptor structure for each parameter
80  * @type: type of the parameter, as dictated by enum rppc_param_type
81  * @size: size of the data (for atomic types) or size of the containing
82  *        structure in which translations are performed
83  * @data: either the parameter value itself (for atomic type) or
84  *        the actual user space pointer address to the data (for pointer type)
85  * @base: the base user space pointer address of the original allocated buffer,
86  *        providing a reference if data has the pointer that is at an offset
87  *        from the original pointer
88  * @fd: file descriptor of the exported allocation (will be used to
89  *      import the associated dma_buf within the driver).
90  */
91 struct rppc_param {
92         uint32_t type;
93         size_t size;
94         size_t data;
95         size_t base;
96         int32_t fd;
97 };
99 /**
100  * struct rppc_function - descriptor structure for the remote function
101  * @fxn_id: index of the function to invoke on the opened rppc device
102  * @num_params: number of parameters filled in the params field
103  * @params: array of parameter descriptor structures
104  * @num_translations: number of in-place translations to be performed within
105  *                    the arguments.
106  * @translations: an open array of the translation descriptor structures, whose
107  *                length is given in @num_translations. Used for translating
108  *                the pointers within the function data.
109  *
110  * This is the primary descriptor structure passed down from the userspace,
111  * describing the function, its parameter arguments and the needed translations.
112  */
113 struct rppc_function {
114         uint32_t fxn_id;
115         uint32_t num_params;
116         struct rppc_param params[RPPC_MAX_PARAMETERS];
117         uint32_t num_translations;
118         struct rppc_param_translation translations[0];
119 };
121 /**
122  * struct rppc_function_return - function return status descriptor structure
123  * @fxn_id: index of the function invoked on the opened rppc device
124  * @status: return value of the executed function
125  */
126 struct rppc_function_return {
127         uint32_t fxn_id;
128         uint32_t status;
129 };
131 /**
132  * struct rppc_create_instance - rppc channel connector helper
133  * @name: Name of the rppc server device to establish a connection with
134  */
135 struct rppc_create_instance {
136         char name[RPPC_MAX_INST_NAMELEN];
137 };
139 /*
140  * helper macros for manipulating the function index in the marshalled packet
141  */
142 #define RPPC_DESC_EXEC_SYNC     (0x0100)
143 #define RPPC_DESC_TYPE_MASK     (0x0F00)
145 /*
146  * helper macros for manipulating the function index in the marshalled packet.
147  * The remote functions are offset by one relative to the client
148  * XXX: Remove the relative offset
149  */
150 #define RPPC_SET_FXN_IDX(idx)   (((idx) + 1) | 0x80000000)
151 #define RPPC_FXN_MASK(idx)      (((idx) - 1) & 0x7FFFFFFF)
153 /**
154  * struct rppc_packet - the actual marshalled packet
155  * @desc: type of function execution, currently only synchronous function
156  *        invocations are supported
157  * @msg_id: an incremental message index identifier
158  * @flags: a combination of job id and pool id of the worker threads
159  *         of the server
160  * @fxn_id: id of the function to execute
161  * @result: result of the remotely executed function
162  * @data_size: size of the payload packet
163  * @data: variable payload, containing the marshalled function data.
164  *
165  * This is actually a condensed structure of the Remote Command Messaging
166  * (RCM) structure. The initial fields of the structure are used by the
167  * remote-side server to schedule the execution of the function. The actual
168  * variable payload data starts from the .data field. This marshalled packet
169  * is the payload for a rpmsg message.
170  *
171  * XXX: remove or mask unneeded fields, some fields can be stripped down
172  */
173 struct rppc_packet {
174         uint16_t desc;
175         uint16_t msg_id;
176         uint32_t flags;
177         uint32_t fxn_id;
178         int32_t  result;
179         uint32_t data_size;
180         uint8_t  data[0];
181 } __packed;
183 #endif /* _UAPI_LINUX_RPMSG_RPC_H_ */