315869390f12a28ac8c69c6994b8ae0f1cbe46a9
1 /*
2 * Remote remote_proc Framework
3 *
4 * Copyright(c) 2011 Texas Instruments, Inc.
5 * Copyright(c) 2011 Google, Inc.
6 * All rights reserved.
7 *
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
10 * are met:
11 *
12 * * Redistributions of source code must retain the above copyright
13 * notice, this list of conditions and the following disclaimer.
14 * * Redistributions in binary form must reproduce the above copyright
15 * notice, this list of conditions and the following disclaimer in
16 * the documentation and/or other materials provided with the
17 * distribution.
18 * * Neither the name Texas Instruments nor the names of its
19 * contributors may be used to endorse or promote products derived
20 * from this software without specific prior written permission.
21 *
22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
23 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
24 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
25 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
26 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
27 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
28 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
29 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
30 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
31 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
32 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33 */
35 #ifndef REMOTEPROC_H
36 #define REMOTEPROC_H
38 #include "openamp/rpmsg.h"
39 #include "openamp/firmware.h"
40 /**
41 * struct resource_table - firmware resource table header
42 * @ver: version number
43 * @num: number of resource entries
44 * @reserved: reserved (must be zero)
45 * @offset: array of offsets pointing at the various resource entries
46 *
47 * A resource table is essentially a list of system resources required
48 * by the remote remote_proc. It may also include configuration entries.
49 * If needed, the remote remote_proc firmware should contain this table
50 * as a dedicated ".resource_table" ELF section.
51 *
52 * Some resources entries are mere announcements, where the host is informed
53 * of specific remoteproc configuration. Other entries require the host to
54 * do something (e.g. allocate a system resource). Sometimes a negotiation
55 * is expected, where the firmware requests a resource, and once allocated,
56 * the host should provide back its details (e.g. address of an allocated
57 * memory region).
58 *
59 * The header of the resource table, as expressed by this structure,
60 * contains a version number (should we need to change this format in the
61 * future), the number of available resource entries, and their offsets
62 * in the table.
63 *
64 * Immediately following this header are the resource entries themselves,
65 * each of which begins with a resource entry header (as described below).
66 */
67 OPENAMP_PACKED_BEGIN
68 struct resource_table {
69 uint32_t ver;
70 uint32_t num;
71 uint32_t reserved[2];
72 uint32_t offset[0];
73 } OPENAMP_PACKED_END;
75 /**
76 * struct fw_rsc_hdr - firmware resource entry header
77 * @type: resource type
78 * @data: resource data
79 *
80 * Every resource entry begins with a 'struct fw_rsc_hdr' header providing
81 * its @type. The content of the entry itself will immediately follow
82 * this header, and it should be parsed according to the resource type.
83 */
84 OPENAMP_PACKED_BEGIN
85 struct fw_rsc_hdr {
86 uint32_t type;
87 uint8_t data[0];
88 } OPENAMP_PACKED_END;
90 /**
91 * enum fw_resource_type - types of resource entries
92 *
93 * @RSC_CARVEOUT: request for allocation of a physically contiguous
94 * memory region.
95 * @RSC_DEVMEM: request to iommu_map a memory-based peripheral.
96 * @RSC_TRACE: announces the availability of a trace buffer into which
97 * the remote remote_proc will be writing logs.
98 * @RSC_VDEV: declare support for a virtio device, and serve as its
99 * virtio header.
100 * @RSC_LAST: just keep this one at the end
101 *
102 * For more details regarding a specific resource type, please see its
103 * dedicated structure below.
104 *
105 * Please note that these values are used as indices to the rproc_handle_rsc
106 * lookup table, so please keep them sane. Moreover, @RSC_LAST is used to
107 * check the validity of an index before the lookup table is accessed, so
108 * please update it as needed.
109 */
110 enum fw_resource_type {
111 RSC_CARVEOUT = 0,
112 RSC_DEVMEM = 1,
113 RSC_TRACE = 2,
114 RSC_VDEV = 3,
115 RSC_LAST = 4,
116 };
118 #define FW_RSC_ADDR_ANY (0xFFFFFFFFFFFFFFFF)
120 /**
121 * struct fw_rsc_carveout - physically contiguous memory request
122 * @da: device address
123 * @pa: physical address
124 * @len: length (in bytes)
125 * @flags: iommu protection flags
126 * @reserved: reserved (must be zero)
127 * @name: human-readable name of the requested memory region
128 *
129 * This resource entry requests the host to allocate a physically contiguous
130 * memory region.
131 *
132 * These request entries should precede other firmware resource entries,
133 * as other entries might request placing other data objects inside
134 * these memory regions (e.g. data/code segments, trace resource entries, ...).
135 *
136 * Allocating memory this way helps utilizing the reserved physical memory
137 * (e.g. CMA) more efficiently, and also minimizes the number of TLB entries
138 * needed to map it (in case @rproc is using an IOMMU). Reducing the TLB
139 * pressure is important; it may have a substantial impact on performance.
140 *
141 * If the firmware is compiled with static addresses, then @da should specify
142 * the expected device address of this memory region. If @da is set to
143 * FW_RSC_ADDR_ANY, then the host will dynamically allocate it, and then
144 * overwrite @da with the dynamically allocated address.
145 *
146 * We will always use @da to negotiate the device addresses, even if it
147 * isn't using an iommu. In that case, though, it will obviously contain
148 * physical addresses.
149 *
150 * Some remote remote_procs needs to know the allocated physical address
151 * even if they do use an iommu. This is needed, e.g., if they control
152 * hardware accelerators which access the physical memory directly (this
153 * is the case with OMAP4 for instance). In that case, the host will
154 * overwrite @pa with the dynamically allocated physical address.
155 * Generally we don't want to expose physical addresses if we don't have to
156 * (remote remote_procs are generally _not_ trusted), so we might want to
157 * change this to happen _only_ when explicitly required by the hardware.
158 *
159 * @flags is used to provide IOMMU protection flags, and @name should
160 * (optionally) contain a human readable name of this carveout region
161 * (mainly for debugging purposes).
162 */
163 OPENAMP_PACKED_BEGIN
164 struct fw_rsc_carveout {
165 uint32_t type;
166 uint32_t da;
167 uint32_t pa;
168 uint32_t len;
169 uint32_t flags;
170 uint32_t reserved;
171 uint8_t name[32];
172 } OPENAMP_PACKED_END;
174 /**
175 * struct fw_rsc_devmem - iommu mapping request
176 * @da: device address
177 * @pa: physical address
178 * @len: length (in bytes)
179 * @flags: iommu protection flags
180 * @reserved: reserved (must be zero)
181 * @name: human-readable name of the requested region to be mapped
182 *
183 * This resource entry requests the host to iommu map a physically contiguous
184 * memory region. This is needed in case the remote remote_proc requires
185 * access to certain memory-based peripherals; _never_ use it to access
186 * regular memory.
187 *
188 * This is obviously only needed if the remote remote_proc is accessing memory
189 * via an iommu.
190 *
191 * @da should specify the required device address, @pa should specify
192 * the physical address we want to map, @len should specify the size of
193 * the mapping and @flags is the IOMMU protection flags. As always, @name may
194 * (optionally) contain a human readable name of this mapping (mainly for
195 * debugging purposes).
196 *
197 * Note: at this point we just "trust" those devmem entries to contain valid
198 * physical addresses, but this isn't safe and will be changed: eventually we
199 * want remoteproc implementations to provide us ranges of physical addresses
200 * the firmware is allowed to request, and not allow firmwares to request
201 * access to physical addresses that are outside those ranges.
202 */
203 OPENAMP_PACKED_BEGIN
204 struct fw_rsc_devmem {
205 uint32_t type;
206 uint32_t da;
207 uint32_t pa;
208 uint32_t len;
209 uint32_t flags;
210 uint32_t reserved;
211 uint8_t name[32];
212 } OPENAMP_PACKED_END;
214 /**
215 * struct fw_rsc_trace - trace buffer declaration
216 * @da: device address
217 * @len: length (in bytes)
218 * @reserved: reserved (must be zero)
219 * @name: human-readable name of the trace buffer
220 *
221 * This resource entry provides the host information about a trace buffer
222 * into which the remote remote_proc will write log messages.
223 *
224 * @da specifies the device address of the buffer, @len specifies
225 * its size, and @name may contain a human readable name of the trace buffer.
226 *
227 * After booting the remote remote_proc, the trace buffers are exposed to the
228 * user via debugfs entries (called trace0, trace1, etc..).
229 */
230 OPENAMP_PACKED_BEGIN
231 struct fw_rsc_trace {
232 uint32_t type;
233 uint32_t da;
234 uint32_t len;
235 uint32_t reserved;
236 uint8_t name[32];
237 } OPENAMP_PACKED_END;
239 /**
240 * struct fw_rsc_vdev_vring - vring descriptor entry
241 * @da: device address
242 * @align: the alignment between the consumer and producer parts of the vring
243 * @num: num of buffers supported by this vring (must be power of two)
244 * @notifyid is a unique rproc-wide notify index for this vring. This notify
245 * index is used when kicking a remote remote_proc, to let it know that this
246 * vring is triggered.
247 * @reserved: reserved (must be zero)
248 *
249 * This descriptor is not a resource entry by itself; it is part of the
250 * vdev resource type (see below).
251 *
252 * Note that @da should either contain the device address where
253 * the remote remote_proc is expecting the vring, or indicate that
254 * dynamically allocation of the vring's device address is supported.
255 */
256 OPENAMP_PACKED_BEGIN
257 struct fw_rsc_vdev_vring {
258 uint32_t da;
259 uint32_t align;
260 uint32_t num;
261 uint32_t notifyid;
262 uint32_t reserved;
263 } OPENAMP_PACKED_END;
265 /**
266 * struct fw_rsc_vdev - virtio device header
267 * @id: virtio device id (as in virtio_ids.h)
268 * @notifyid is a unique rproc-wide notify index for this vdev. This notify
269 * index is used when kicking a remote remote_proc, to let it know that the
270 * status/features of this vdev have changes.
271 * @dfeatures specifies the virtio device features supported by the firmware
272 * @gfeatures is a place holder used by the host to write back the
273 * negotiated features that are supported by both sides.
274 * @config_len is the size of the virtio config space of this vdev. The config
275 * space lies in the resource table immediate after this vdev header.
276 * @status is a place holder where the host will indicate its virtio progress.
277 * @num_of_vrings indicates how many vrings are described in this vdev header
278 * @reserved: reserved (must be zero)
279 * @vring is an array of @num_of_vrings entries of 'struct fw_rsc_vdev_vring'.
280 *
281 * This resource is a virtio device header: it provides information about
282 * the vdev, and is then used by the host and its peer remote remote_procs
283 * to negotiate and share certain virtio properties.
284 *
285 * By providing this resource entry, the firmware essentially asks remoteproc
286 * to statically allocate a vdev upon registration of the rproc (dynamic vdev
287 * allocation is not yet supported).
288 *
289 * Note: unlike virtualization systems, the term 'host' here means
290 * the Linux side which is running remoteproc to control the remote
291 * remote_procs. We use the name 'gfeatures' to comply with virtio's terms,
292 * though there isn't really any virtualized guest OS here: it's the host
293 * which is responsible for negotiating the final features.
294 * Yeah, it's a bit confusing.
295 *
296 * Note: immediately following this structure is the virtio config space for
297 * this vdev (which is specific to the vdev; for more info, read the virtio
298 * spec). the size of the config space is specified by @config_len.
299 */
300 OPENAMP_PACKED_BEGIN
301 struct fw_rsc_vdev {
302 uint32_t type;
303 uint32_t id;
304 uint32_t notifyid;
305 uint32_t dfeatures;
306 uint32_t gfeatures;
307 uint32_t config_len;
308 uint8_t status;
309 uint8_t num_of_vrings;
310 uint8_t reserved[2];
311 struct fw_rsc_vdev_vring vring[0];
312 } OPENAMP_PACKED_END;
314 /**
315 * struct remote_proc
316 *
317 * This structure is maintained by the remoteproc to represent the remote
318 * processor instance. This structure acts as a prime parameter to use
319 * the remoteproc APIs.
320 *
321 * @proc : hardware interface layer processor control
322 * @rdev : remote device , used by RPMSG "messaging" framework.
323 * @loader : pointer remoteproc loader
324 * @channel_created : create channel callback
325 * @channel_destroyed : delete channel callback
326 * @default_cb : default callback for channel
327 * @role : remote proc role , RPROC_MASTER/RPROC_REMOTE
328 *
329 */
330 struct remote_proc {
331 struct hil_proc *proc;
332 struct remote_device *rdev;
333 struct remoteproc_loader *loader;
334 rpmsg_chnl_cb_t channel_created;
335 rpmsg_chnl_cb_t channel_destroyed;
336 rpmsg_rx_cb_t default_cb;
337 int role;
338 };
340 /**
341 * struct resc_table_info
342 *
343 * This structure is maintained by the remoteproc to allow applications
344 * to pass resource table info during remote initialization.
345 *
346 * @rsc_tab : pointer to resource table control block
347 * @size : size of resource table.
348 *
349 */
350 struct rsc_table_info {
351 struct resource_table *rsc_tab;
352 int size;
353 };
355 /* Definitions for device types , null pointer, etc.*/
356 #define RPROC_SUCCESS 0
357 #define RPROC_NULL (void *)0
358 #define RPROC_TRUE 1
359 #define RPROC_FALSE 0
360 #define RPROC_MASTER 1
361 #define RPROC_REMOTE 0
362 /* Number of msecs to wait for remote context to come up */
363 #define RPROC_BOOT_DELAY 500
365 /* Remoteproc error codes */
366 #define RPROC_ERR_BASE -4000
367 #define RPROC_ERR_CPU_ID (RPROC_ERR_BASE -1)
368 #define RPROC_ERR_NO_RSC_TABLE (RPROC_ERR_BASE -2)
369 #define RPROC_ERR_NO_MEM (RPROC_ERR_BASE -3)
370 #define RPROC_ERR_RSC_TAB_TRUNC (RPROC_ERR_BASE -4)
371 #define RPROC_ERR_RSC_TAB_VER (RPROC_ERR_BASE -5)
372 #define RPROC_ERR_RSC_TAB_RSVD (RPROC_ERR_BASE -6)
373 #define RPROC_ERR_RSC_TAB_VDEV_NRINGS (RPROC_ERR_BASE -7)
374 #define RPROC_ERR_RSC_TAB_NP (RPROC_ERR_BASE -8)
375 #define RPROC_ERR_RSC_TAB_NS (RPROC_ERR_BASE -9)
376 #define RPROC_ERR_INVLD_FW (RPROC_ERR_BASE -10)
377 #define RPROC_ERR_LOADER (RPROC_ERR_BASE -11)
378 #define RPROC_ERR_PARAM (RPROC_ERR_BASE -12)
379 #define RPROC_ERR_PTR (void*)0xDEADBEAF
381 /**
382 * remoteproc_resource_init
383 *
384 * Initializes resources for remoteproc remote configuration.Only
385 * remoteproc remote applications are allowed to call this function.
386 *
387 * @param rsc_info - pointer to resource table info control
388 * block
389 * @param pdata - platform data for remote processor
390 * @param channel_created - callback function for channel creation
391 * @param channel_destroyed - callback function for channel deletion
392 * @param default_cb - default callback for channel I/O
393 * @param rproc_handle - pointer to new remoteproc instance
394 * @param init_env - 1 to initialize environment, 0 not to
395 * @param rpmsg_role - 1 for rpmsg master, or 0 for rpmsg slave
396 *
397 * @param returns - status of execution
398 *
399 */
400 int remoteproc_resource_init(struct rsc_table_info *rsc_info,
401 void *pdata,
402 rpmsg_chnl_cb_t channel_created,
403 rpmsg_chnl_cb_t channel_destroyed,
404 rpmsg_rx_cb_t default_cb,
405 struct remote_proc **rproc_handle,
406 int rpmsg_role);
408 /**
409 * remoteproc_resource_deinit
410 *
411 * Uninitializes resources for remoteproc remote configuration.
412 *
413 * @param rproc - pointer to remoteproc instance
414 *
415 * @param returns - status of execution
416 *
417 */
419 int remoteproc_resource_deinit(struct remote_proc *rproc);
421 /**
422 * remoteproc_init
423 *
424 * Initializes resources for remoteproc master configuration. Only
425 * remoteproc master applications are allowed to call this function.
426 *
427 * @param fw_name - name of firmware
428 * @param pdata - platform data for remote processor
429 * @param channel_created - callback function for channel creation
430 * @param channel_destroyed - callback function for channel deletion
431 * @param default_cb - default callback for channel I/O
432 * @param rproc_handle - pointer to new remoteproc instance
433 *
434 * @param returns - status of function execution
435 *
436 */
437 int remoteproc_init(char *fw_name, void *pdata,
438 rpmsg_chnl_cb_t channel_created,
439 rpmsg_chnl_cb_t channel_destroyed,
440 rpmsg_rx_cb_t default_cb,
441 struct remote_proc **rproc_handle);
443 /**
444 * remoteproc_deinit
445 *
446 * Uninitializes resources for remoteproc "master" configuration.
447 *
448 * @param rproc - pointer to remoteproc instance
449 *
450 * @param returns - status of function execution
451 *
452 */
453 int remoteproc_deinit(struct remote_proc *rproc);
455 /**
456 * remoteproc_boot
457 *
458 * This function loads the image on the remote processor and starts
459 * its execution from image load address.
460 *
461 * @param rproc - pointer to remoteproc instance to boot
462 *
463 * @param returns - status of function execution
464 */
465 int remoteproc_boot(struct remote_proc *rproc);
467 /**
468 * remoteproc_shutdown
469 *
470 * This function shutdowns the remote execution context.
471 *
472 * @param rproc - pointer to remoteproc instance to shutdown
473 *
474 * @param returns - status of function execution
475 */
476 int remoteproc_shutdown(struct remote_proc *rproc);
478 #endif /* REMOTEPROC_H_ */