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  */
   7
   8 #ifndef _RPMSG_RPC_INTERNAL_H_
   9 #define _RPMSG_RPC_INTERNAL_H_
  10
  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>
  16
  17 typedef u32 virt_addr_t;
  18 typedef u32 dev_addr_t;
  19
  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 };
  57
  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 };
  94
  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 };
 111
 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 };
 137
 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 };
 188
 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 };
 204
 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;
 220
 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 };
 232
 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 };
 250
 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 };
 276
 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 };
 291
 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 };
 308
 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 };
 320
 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;
 335
 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;
 351
 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;
 366
 367 #define RPPC_PAYLOAD(ptr, type) \
 368                 ((struct type *)&(ptr)[sizeof(struct rppc_msg_header)])
 369
 370 /* from rpmsg_rpc.c */
 371 dev_addr_t rppc_local_to_remote_da(struct rppc_instance *rpc, phys_addr_t pa);
 372
 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);
 382
 383 /* from rpmsg_rpc_sysfs.c */
 384 int rppc_create_sysfs(struct rppc_device *rppcdev);
 385 int rppc_remove_sysfs(struct rppc_device *rppcdev);
 386
 387 #endif