1 /* SPDX-License-Identifier: GPL-2.0-only OR MI 1 /* SPDX-License-Identifier: GPL-2.0-only OR MIT */
2 /* 2 /*
3 * Apple RTKit IPC Library 3 * Apple RTKit IPC Library
4 * Copyright (C) The Asahi Linux Contributors 4 * Copyright (C) The Asahi Linux Contributors
5 * 5 *
6 * Apple's SoCs come with various co-processor 6 * Apple's SoCs come with various co-processors running their RTKit operating
7 * system. This protocol library is used by cl 7 * system. This protocol library is used by client drivers to use the
8 * features provided by them. 8 * features provided by them.
9 */ 9 */
10 #ifndef _LINUX_APPLE_RTKIT_H_ 10 #ifndef _LINUX_APPLE_RTKIT_H_
11 #define _LINUX_APPLE_RTKIT_H_ 11 #define _LINUX_APPLE_RTKIT_H_
12 12
13 #include <linux/device.h> 13 #include <linux/device.h>
14 #include <linux/types.h> 14 #include <linux/types.h>
15 #include <linux/mailbox_client.h> 15 #include <linux/mailbox_client.h>
16 16
17 /* 17 /*
18 * Struct to represent implementation-specific 18 * Struct to represent implementation-specific RTKit operations.
19 * 19 *
20 * @buffer: Shared memory buffer allocated 20 * @buffer: Shared memory buffer allocated inside normal RAM.
21 * @iomem: Shared memory buffer controlled 21 * @iomem: Shared memory buffer controlled by the co-processors.
22 * @size: Size of the shared memory buffe 22 * @size: Size of the shared memory buffer.
23 * @iova: Device VA of shared memory buff 23 * @iova: Device VA of shared memory buffer.
24 * @is_mapped: Shared memory buffer is managed 24 * @is_mapped: Shared memory buffer is managed by the co-processor.
25 * @private: Private data pointer for the pa 25 * @private: Private data pointer for the parent driver.
26 */ 26 */
27 27
28 struct apple_rtkit_shmem { 28 struct apple_rtkit_shmem {
29 void *buffer; 29 void *buffer;
30 void __iomem *iomem; 30 void __iomem *iomem;
31 size_t size; 31 size_t size;
32 dma_addr_t iova; 32 dma_addr_t iova;
33 bool is_mapped; 33 bool is_mapped;
34 void *private; 34 void *private;
35 }; 35 };
36 36
37 /* 37 /*
38 * Struct to represent implementation-specific 38 * Struct to represent implementation-specific RTKit operations.
39 * 39 *
40 * @crashed: Called when the co-processo 40 * @crashed: Called when the co-processor has crashed. Runs in process
41 * context. 41 * context.
42 * @recv_message: Function called when a mess 42 * @recv_message: Function called when a message from RTKit is received
43 * on a non-system endpoint. C 43 * on a non-system endpoint. Called from a worker thread.
44 * @recv_message_early: 44 * @recv_message_early:
45 * Like recv_message, but call 45 * Like recv_message, but called from atomic context. It
46 * should return true if it ha 46 * should return true if it handled the message. If it
47 * returns false, the message 47 * returns false, the message will be passed on to the
48 * worker thread. 48 * worker thread.
49 * @shmem_setup: Setup shared memory buffer. 49 * @shmem_setup: Setup shared memory buffer. If bfr.is_iomem is true the
50 * buffer is managed by the co 50 * buffer is managed by the co-processor and needs to be mapped.
51 * Otherwise the buffer is man 51 * Otherwise the buffer is managed by Linux and needs to be
52 * allocated. If not specified 52 * allocated. If not specified dma_alloc_coherent is used.
53 * Called in process context. 53 * Called in process context.
54 * @shmem_destroy: Undo the shared memory buff 54 * @shmem_destroy: Undo the shared memory buffer setup in shmem_setup. If not
55 * specified dma_free_coherent 55 * specified dma_free_coherent is used. Called in process
56 * context. 56 * context.
57 */ 57 */
58 struct apple_rtkit_ops { 58 struct apple_rtkit_ops {
59 void (*crashed)(void *cookie); 59 void (*crashed)(void *cookie);
60 void (*recv_message)(void *cookie, u8 60 void (*recv_message)(void *cookie, u8 endpoint, u64 message);
61 bool (*recv_message_early)(void *cooki 61 bool (*recv_message_early)(void *cookie, u8 endpoint, u64 message);
62 int (*shmem_setup)(void *cookie, struc 62 int (*shmem_setup)(void *cookie, struct apple_rtkit_shmem *bfr);
63 void (*shmem_destroy)(void *cookie, st 63 void (*shmem_destroy)(void *cookie, struct apple_rtkit_shmem *bfr);
64 }; 64 };
65 65
66 struct apple_rtkit; 66 struct apple_rtkit;
67 67
68 /* 68 /*
69 * Initializes the internal state required to 69 * Initializes the internal state required to handle RTKit. This
70 * should usually be called within _probe. 70 * should usually be called within _probe.
71 * 71 *
72 * @dev: Pointer to the device node th 72 * @dev: Pointer to the device node this coprocessor is associated with
73 * @cookie: opaque cookie passed to all f 73 * @cookie: opaque cookie passed to all functions defined in rtkit_ops
74 * @mbox_name: mailbox name used to communic 74 * @mbox_name: mailbox name used to communicate with the co-processor
75 * @mbox_idx: mailbox index to be used if m 75 * @mbox_idx: mailbox index to be used if mbox_name is NULL
76 * @ops: pointer to rtkit_ops to be us 76 * @ops: pointer to rtkit_ops to be used for this co-processor
77 */ 77 */
78 struct apple_rtkit *devm_apple_rtkit_init(stru 78 struct apple_rtkit *devm_apple_rtkit_init(struct device *dev, void *cookie,
79 cons 79 const char *mbox_name, int mbox_idx,
80 cons 80 const struct apple_rtkit_ops *ops);
81 81
82 /* 82 /*
83 * Non-devm version of devm_apple_rtkit_init. 83 * Non-devm version of devm_apple_rtkit_init. Must be freed with
84 * apple_rtkit_free. 84 * apple_rtkit_free.
85 * 85 *
86 * @dev: Pointer to the device node th 86 * @dev: Pointer to the device node this coprocessor is associated with
87 * @cookie: opaque cookie passed to all f 87 * @cookie: opaque cookie passed to all functions defined in rtkit_ops
88 * @mbox_name: mailbox name used to communic 88 * @mbox_name: mailbox name used to communicate with the co-processor
89 * @mbox_idx: mailbox index to be used if m 89 * @mbox_idx: mailbox index to be used if mbox_name is NULL
90 * @ops: pointer to rtkit_ops to be us 90 * @ops: pointer to rtkit_ops to be used for this co-processor
91 */ 91 */
92 struct apple_rtkit *apple_rtkit_init(struct de 92 struct apple_rtkit *apple_rtkit_init(struct device *dev, void *cookie,
93 cons 93 const char *mbox_name, int mbox_idx,
94 cons 94 const struct apple_rtkit_ops *ops);
95 95
96 /* 96 /*
97 * Free an instance of apple_rtkit. 97 * Free an instance of apple_rtkit.
98 */ 98 */
99 void apple_rtkit_free(struct apple_rtkit *rtk) 99 void apple_rtkit_free(struct apple_rtkit *rtk);
100 100
101 /* 101 /*
102 * Reinitialize internal structures. Must only 102 * Reinitialize internal structures. Must only be called with the co-processor
103 * is held in reset. 103 * is held in reset.
104 */ 104 */
105 int apple_rtkit_reinit(struct apple_rtkit *rtk 105 int apple_rtkit_reinit(struct apple_rtkit *rtk);
106 106
107 /* 107 /*
108 * Handle RTKit's boot process. Should be call 108 * Handle RTKit's boot process. Should be called after the CPU of the
109 * co-processor has been started. 109 * co-processor has been started.
110 */ 110 */
111 int apple_rtkit_boot(struct apple_rtkit *rtk); 111 int apple_rtkit_boot(struct apple_rtkit *rtk);
112 112
113 /* 113 /*
114 * Quiesce the co-processor. 114 * Quiesce the co-processor.
115 */ 115 */
116 int apple_rtkit_quiesce(struct apple_rtkit *rt 116 int apple_rtkit_quiesce(struct apple_rtkit *rtk);
117 117
118 /* 118 /*
119 * Wake the co-processor up from hibernation m 119 * Wake the co-processor up from hibernation mode.
120 */ 120 */
121 int apple_rtkit_wake(struct apple_rtkit *rtk); 121 int apple_rtkit_wake(struct apple_rtkit *rtk);
122 122
123 /* 123 /*
124 * Shutdown the co-processor 124 * Shutdown the co-processor
125 */ 125 */
126 int apple_rtkit_shutdown(struct apple_rtkit *r 126 int apple_rtkit_shutdown(struct apple_rtkit *rtk);
127 127
128 /* 128 /*
129 * Put the co-processor into idle mode 129 * Put the co-processor into idle mode
130 */ 130 */
131 int apple_rtkit_idle(struct apple_rtkit *rtk); 131 int apple_rtkit_idle(struct apple_rtkit *rtk);
132 132
133 /* 133 /*
134 * Checks if RTKit is running and ready to han 134 * Checks if RTKit is running and ready to handle messages.
135 */ 135 */
136 bool apple_rtkit_is_running(struct apple_rtkit 136 bool apple_rtkit_is_running(struct apple_rtkit *rtk);
137 137
138 /* 138 /*
139 * Checks if RTKit has crashed. 139 * Checks if RTKit has crashed.
140 */ 140 */
141 bool apple_rtkit_is_crashed(struct apple_rtkit 141 bool apple_rtkit_is_crashed(struct apple_rtkit *rtk);
142 142
143 /* 143 /*
144 * Starts an endpoint. Must be called after bo 144 * Starts an endpoint. Must be called after boot but before any messages can be
145 * sent or received from that endpoint. 145 * sent or received from that endpoint.
146 */ 146 */
147 int apple_rtkit_start_ep(struct apple_rtkit *r 147 int apple_rtkit_start_ep(struct apple_rtkit *rtk, u8 endpoint);
148 148
149 /* 149 /*
150 * Send a message to the given endpoint. 150 * Send a message to the given endpoint.
151 * 151 *
152 * @rtk: RTKit reference 152 * @rtk: RTKit reference
153 * @ep: target endpoint 153 * @ep: target endpoint
154 * @message: message to be sent 154 * @message: message to be sent
155 * @completeion: will be completed once the 155 * @completeion: will be completed once the message has been submitted
156 * to the hardware FIFO. Can 156 * to the hardware FIFO. Can be NULL.
157 * @atomic: if set to true this functi 157 * @atomic: if set to true this function can be called from atomic
158 * context. 158 * context.
159 */ 159 */
160 int apple_rtkit_send_message(struct apple_rtki 160 int apple_rtkit_send_message(struct apple_rtkit *rtk, u8 ep, u64 message,
161 struct completion 161 struct completion *completion, bool atomic);
162 162
163 /* 163 /*
164 * Process incoming messages in atomic context 164 * Process incoming messages in atomic context.
165 * This only guarantees that messages arrive a 165 * This only guarantees that messages arrive as far as the recv_message_early
166 * callback; drivers expecting to handle incom 166 * callback; drivers expecting to handle incoming messages synchronously
167 * by calling this function must do it that wa 167 * by calling this function must do it that way.
168 * Will return 1 if some data was processed, 0 168 * Will return 1 if some data was processed, 0 if none was, or a
169 * negative error code on failure. 169 * negative error code on failure.
170 * 170 *
171 * @rtk: RTKit reference 171 * @rtk: RTKit reference
172 */ 172 */
173 int apple_rtkit_poll(struct apple_rtkit *rtk); 173 int apple_rtkit_poll(struct apple_rtkit *rtk);
174 174
175 #endif /* _LINUX_APPLE_RTKIT_H_ */ 175 #endif /* _LINUX_APPLE_RTKIT_H_ */
176 176
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.