staging: nvshm: create new communication channel for RPC
[linux-3.10.git] / drivers / staging / nvshm / nvshm_rpc.h
1 /*
2  * Copyright (C) 2013 NVIDIA Corporation.
3  *
4  * This software is licensed under the terms of the GNU General Public
5  * License version 2, as published by the Free Software Foundation, and
6  * may be copied, distributed, and modified under those terms.
7  *
8  * This program is distributed in the hope that it will be useful,
9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11  * GNU General Public License for more details.
12  *
13  */
14
15 #ifndef __DRIVERS_STAGING_NVSHM_NVSHM_RPC_H
16 #define __DRIVERS_STAGING_NVSHM_NVSHM_RPC_H
17
18 #include <linux/types.h>
19
20 /**
21  * Type for a RPC message (request or response.)
22  *
23  * @param payload Payload to send across
24  * @param length Payload length - DO NOT MODIFY
25  * @param private An internal context - DO NOT MODIFY
26  */
27 struct nvshm_rpc_message {
28         void *payload;
29         /* The fields below are set at allocation time and are private */
30         u32 length;
31         void *private;
32 };
33
34 /**
35  * Set a default dispatcher.
36  *
37  * The default dispatcher is the dispatcher that receives requests from clients
38  * on the remote processor, while responses are sent back the originator's
39  * callback automatically.
40  *
41  * Reminder: the callback (or one of its sub-processes) MUST free the message.
42  *
43  * @param callback Callback to use to receive incoming messages
44  * @param context Context to remind at callback time (may be NULL)
45  */
46 void nvshm_rpc_setdispatcher(
47         void (*callback)(struct nvshm_rpc_message *message, void *context),
48         void *context);
49
50 /**
51  * Allocate a message buffer for request.
52  *
53  * The point here is for the client to fill in this buffer and not make a copy.
54  * NOTE: SENT MESSAGES ARE FREED AUTOMATICALLY.
55  *
56  * Reminder: the callback (or one of its sub-processes) MUST free the message.
57  *
58  * @param size Size of the buffer to allocate
59  * @param callback Callback to use to receive ASYNCHRONOUS responses
60  * @param context A user context to pass to the callback, if relevant
61  * @return a buffer, or NULL on error
62  */
63 struct nvshm_rpc_message *nvshm_rpc_allocrequest(
64         u32 size,
65         void (*callback)(struct nvshm_rpc_message *message, void *context),
66         void *context);
67
68 /**
69  * Allocate a message buffer for response.
70  *
71  * The point here is for the client to fill in this buffer and avoid making a
72  * copy.
73  * NOTE: SENT MESSAGES ARE FREED AUTOMATICALLY.
74  *
75  * @param size Size of the buffer to allocate
76  * @param request Request message as received
77  * @return a buffer, or NULL on error
78  */
79 struct nvshm_rpc_message *nvshm_rpc_allocresponse(
80         u32 size,
81         const struct nvshm_rpc_message *request);
82
83 /**
84  * Free a message buffer.
85  *
86  * Use of this function should never be need if the message is sent, as the
87  * destruction is then automatic.  It is needed to destroy the response to
88  * synchronous calls though, and the message passed to both dispatcher and
89  * message callbacks.
90  *
91  * @param message Message to free
92  */
93 void nvshm_rpc_free(
94         struct nvshm_rpc_message *message);
95
96 /**
97  * Send a request or response message.
98  *
99  * Responses go through the callback (if any)
100  *
101  * @param message Request or response to send, automatically freed once sent
102  * @return 0, or negative on error
103  */
104 int nvshm_rpc_send(
105         struct nvshm_rpc_message *message);
106
107 #endif /* #ifndef __DRIVERS_STAGING_NVSHM_NVSHM_RPC_H */