soc/apple/rtkit.h

0001 /* SPDX-License-Identifier: GPL-2.0-only OR MIT */
0002 /*
0003  * Apple RTKit IPC Library
0004  * Copyright (C) The Asahi Linux Contributors
0005  *
0006  * Apple's SoCs come with various co-processors running their RTKit operating
0007  * system. This protocol library is used by client drivers to use the
0008  * features provided by them.
0009  */
0010 #ifndef _LINUX_APPLE_RTKIT_H_
0011 #define _LINUX_APPLE_RTKIT_H_
0012
0013 #include <linux/device.h>
0014 #include <linux/types.h>
0015 #include <linux/mailbox_client.h>
0016
0017 /*
0018  * Struct to represent implementation-specific RTKit operations.
0019  *
0020  * @buffer:    Shared memory buffer allocated inside normal RAM.
0021  * @iomem:     Shared memory buffer controlled by the co-processors.
0022  * @size:      Size of the shared memory buffer.
0023  * @iova:      Device VA of shared memory buffer.
0024  * @is_mapped: Shared memory buffer is managed by the co-processor.
0025  */
0026
0027 struct apple_rtkit_shmem {
0028     void *buffer;
0029     void __iomem *iomem;
0030     size_t size;
0031     dma_addr_t iova;
0032     bool is_mapped;
0033 };
0034
0035 /*
0036  * Struct to represent implementation-specific RTKit operations.
0037  *
0038  * @crashed:       Called when the co-processor has crashed. Runs in process
0039  *                 context.
0040  * @recv_message:  Function called when a message from RTKit is received
0041  *                 on a non-system endpoint. Called from a worker thread.
0042  * @recv_message_early:
0043  *                 Like recv_message, but called from atomic context. It
0044  *                 should return true if it handled the message. If it
0045  *                 returns false, the message will be passed on to the
0046  *                 worker thread.
0047  * @shmem_setup:   Setup shared memory buffer. If bfr.is_iomem is true the
0048  *                 buffer is managed by the co-processor and needs to be mapped.
0049  *                 Otherwise the buffer is managed by Linux and needs to be
0050  *                 allocated. If not specified dma_alloc_coherent is used.
0051  *                 Called in process context.
0052  * @shmem_destroy: Undo the shared memory buffer setup in shmem_setup. If not
0053  *                 specified dma_free_coherent is used. Called in process
0054  *                 context.
0055  */
0056 struct apple_rtkit_ops {
0057     void (*crashed)(void *cookie);
0058     void (*recv_message)(void *cookie, u8 endpoint, u64 message);
0059     bool (*recv_message_early)(void *cookie, u8 endpoint, u64 message);
0060     int (*shmem_setup)(void *cookie, struct apple_rtkit_shmem *bfr);
0061     void (*shmem_destroy)(void *cookie, struct apple_rtkit_shmem *bfr);
0062 };
0063
0064 struct apple_rtkit;
0065
0066 /*
0067  * Initializes the internal state required to handle RTKit. This
0068  * should usually be called within _probe.
0069  *
0070  * @dev:         Pointer to the device node this coprocessor is assocated with
0071  * @cookie:      opaque cookie passed to all functions defined in rtkit_ops
0072  * @mbox_name:   mailbox name used to communicate with the co-processor
0073  * @mbox_idx:    mailbox index to be used if mbox_name is NULL
0074  * @ops:         pointer to rtkit_ops to be used for this co-processor
0075  */
0076 struct apple_rtkit *devm_apple_rtkit_init(struct device *dev, void *cookie,
0077                       const char *mbox_name, int mbox_idx,
0078                       const struct apple_rtkit_ops *ops);
0079
0080 /*
0081  * Reinitialize internal structures. Must only be called with the co-processor
0082  * is held in reset.
0083  */
0084 int apple_rtkit_reinit(struct apple_rtkit *rtk);
0085
0086 /*
0087  * Handle RTKit's boot process. Should be called after the CPU of the
0088  * co-processor has been started.
0089  */
0090 int apple_rtkit_boot(struct apple_rtkit *rtk);
0091
0092 /*
0093  * Quiesce the co-processor.
0094  */
0095 int apple_rtkit_quiesce(struct apple_rtkit *rtk);
0096
0097 /*
0098  * Wake the co-processor up from hibernation mode.
0099  */
0100 int apple_rtkit_wake(struct apple_rtkit *rtk);
0101
0102 /*
0103  * Shutdown the co-processor
0104  */
0105 int apple_rtkit_shutdown(struct apple_rtkit *rtk);
0106
0107 /*
0108  * Checks if RTKit is running and ready to handle messages.
0109  */
0110 bool apple_rtkit_is_running(struct apple_rtkit *rtk);
0111
0112 /*
0113  * Checks if RTKit has crashed.
0114  */
0115 bool apple_rtkit_is_crashed(struct apple_rtkit *rtk);
0116
0117 /*
0118  * Starts an endpoint. Must be called after boot but before any messages can be
0119  * sent or received from that endpoint.
0120  */
0121 int apple_rtkit_start_ep(struct apple_rtkit *rtk, u8 endpoint);
0122
0123 /*
0124  * Send a message to the given endpoint.
0125  *
0126  * @rtk:            RTKit reference
0127  * @ep:             target endpoint
0128  * @message:        message to be sent
0129  * @completeion:    will be completed once the message has been submitted
0130  *                  to the hardware FIFO. Can be NULL.
0131  * @atomic:         if set to true this function can be called from atomic
0132  *                  context.
0133  */
0134 int apple_rtkit_send_message(struct apple_rtkit *rtk, u8 ep, u64 message,
0135                  struct completion *completion, bool atomic);
0136
0137 /*
0138  * Send a message to the given endpoint and wait until it has been submitted
0139  * to the hardware FIFO.
0140  * Will return zero on success and a negative error code on failure
0141  * (e.g. -ETIME when the message couldn't be written within the given
0142  * timeout)
0143  *
0144  * @rtk:            RTKit reference
0145  * @ep:             target endpoint
0146  * @message:        message to be sent
0147  * @timeout:        timeout in milliseconds to allow the message transmission
0148  *                  to be completed
0149  * @atomic:         if set to true this function can be called from atomic
0150  *                  context.
0151  */
0152 int apple_rtkit_send_message_wait(struct apple_rtkit *rtk, u8 ep, u64 message,
0153                   unsigned long timeout, bool atomic);
0154
0155 #endif /* _LINUX_APPLE_RTKIT_H_ */