Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1/* SPDX-License-Identifier: GPL-2.0-only */
2
3#ifndef __MAILBOX_CONTROLLER_H
4#define __MAILBOX_CONTROLLER_H
5
6#include <linux/bits.h>
7#include <linux/completion.h>
8#include <linux/device.h>
9#include <linux/hrtimer.h>
10#include <linux/of.h>
11#include <linux/types.h>
12
13struct mbox_chan;
14
15/* Sentinel value distinguishing "no active request" from "NULL message data" */
16#define MBOX_NO_MSG ((void *)-1)
17
18#define MBOX_TXDONE_BY_IRQ BIT(0) /* controller has remote RTR irq */
19#define MBOX_TXDONE_BY_POLL BIT(1) /* controller can read status of last TX */
20#define MBOX_TXDONE_BY_ACK BIT(2) /* S/W ACK received by Client ticks the TX */
21
22/**
23 * struct mbox_chan_ops - methods to control mailbox channels
24 * @send_data: The API asks the MBOX controller driver, in atomic
25 * context try to transmit a message on the bus. Returns 0 if
26 * data is accepted for transmission, -EBUSY while rejecting
27 * if the remote hasn't yet read the last data sent. Actual
28 * transmission of data is reported by the controller via
29 * mbox_chan_txdone (if it has some TX ACK irq). It must not
30 * sleep.
31 * @flush: Called when a client requests transmissions to be blocking but
32 * the context doesn't allow sleeping. Typically the controller
33 * will implement a busy loop waiting for the data to flush out.
34 * @startup: Called when a client requests the chan. The controller
35 * could ask clients for additional parameters of communication
36 * to be provided via client's chan_data. This call may
37 * block. After this call the Controller must forward any
38 * data received on the chan by calling mbox_chan_received_data.
39 * The controller may do stuff that need to sleep.
40 * @shutdown: Called when a client relinquishes control of a chan.
41 * This call may block too. The controller must not forward
42 * any received data anymore.
43 * The controller may do stuff that need to sleep.
44 * @last_tx_done: If the controller sets 'txdone_poll', the API calls
45 * this to poll status of last TX. The controller must
46 * give priority to IRQ method over polling and never
47 * set both txdone_poll and txdone_irq. Only in polling
48 * mode 'send_data' is expected to return -EBUSY.
49 * The controller may do stuff that need to sleep/block.
50 * Used only if txdone_poll:=true && txdone_irq:=false
51 * @peek_data: Atomic check for any received data. Return true if controller
52 * has some data to push to the client. False otherwise.
53 */
54struct mbox_chan_ops {
55 int (*send_data)(struct mbox_chan *chan, void *data);
56 int (*flush)(struct mbox_chan *chan, unsigned long timeout);
57 int (*startup)(struct mbox_chan *chan);
58 void (*shutdown)(struct mbox_chan *chan);
59 bool (*last_tx_done)(struct mbox_chan *chan);
60 bool (*peek_data)(struct mbox_chan *chan);
61};
62
63/**
64 * struct mbox_controller - Controller of a class of communication channels
65 * @dev: Device backing this controller. Required.
66 * @ops: Operators that work on each communication chan. Required.
67 * @chans: Array of channels. Required.
68 * @num_chans: Number of channels in the 'chans' array. Required.
69 * @txdone_irq: Indicates if the controller can report to API when
70 * the last transmitted data was read by the remote.
71 * Eg, if it has some TX ACK irq.
72 * @txdone_poll: If the controller can read but not report the TX
73 * done. Ex, some register shows the TX status but
74 * no interrupt rises. Ignored if 'txdone_irq' is set.
75 * @txpoll_period: If 'txdone_poll' is in effect, the API polls for
76 * last TX's status after these many millisecs
77 * @fw_xlate: Controller driver specific mapping of channel via fwnode
78 * @of_xlate: Controller driver specific mapping of channel via DT
79 * @poll_hrt: API private. hrtimer used to poll for TXDONE on all
80 * channels.
81 * @poll_hrt_lock: API private. Lock protecting access to poll_hrt.
82 * @node: API private. To hook into list of controllers.
83 */
84struct mbox_controller {
85 struct device *dev;
86 const struct mbox_chan_ops *ops;
87 struct mbox_chan *chans;
88 int num_chans;
89 bool txdone_irq;
90 bool txdone_poll;
91 unsigned txpoll_period;
92 struct mbox_chan *(*fw_xlate)(struct mbox_controller *mbox,
93 const struct fwnode_reference_args *sp);
94 struct mbox_chan *(*of_xlate)(struct mbox_controller *mbox,
95 const struct of_phandle_args *sp);
96 /* Internal to API */
97 struct hrtimer poll_hrt;
98 spinlock_t poll_hrt_lock;
99 struct list_head node;
100};
101
102/*
103 * The length of circular buffer for queuing messages from a client.
104 * 'msg_count' tracks the number of buffered messages while 'msg_free'
105 * is the index where the next message would be buffered.
106 * We shouldn't need it too big because every transfer is interrupt
107 * triggered and if we have lots of data to transfer, the interrupt
108 * latencies are going to be the bottleneck, not the buffer length.
109 * Besides, mbox_send_message could be called from atomic context and
110 * the client could also queue another message from the notifier 'tx_done'
111 * of the last transfer done.
112 * REVISIT: If too many platforms see the "Try increasing MBOX_TX_QUEUE_LEN"
113 * print, it needs to be taken from config option or somesuch.
114 */
115#define MBOX_TX_QUEUE_LEN 20
116
117/**
118 * struct mbox_chan - s/w representation of a communication chan
119 * @mbox: Pointer to the parent/provider of this channel
120 * @txdone_method: Way to detect TXDone chosen by the API
121 * @cl: Pointer to the current owner of this channel
122 * @tx_complete: Transmission completion
123 * @active_req: Currently active request hook
124 * @msg_count: No. of mssg currently queued
125 * @msg_free: Index of next available mssg slot
126 * @msg_data: Hook for data packet
127 * @lock: Serialise access to the channel
128 * @con_priv: Hook for controller driver to attach private data
129 */
130struct mbox_chan {
131 struct mbox_controller *mbox;
132 unsigned txdone_method;
133 struct mbox_client *cl;
134 struct completion tx_complete;
135 void *active_req;
136 unsigned msg_count, msg_free;
137 void *msg_data[MBOX_TX_QUEUE_LEN];
138 spinlock_t lock; /* Serialise access to the channel */
139 void *con_priv;
140};
141
142int mbox_controller_register(struct mbox_controller *mbox); /* can sleep */
143void mbox_controller_unregister(struct mbox_controller *mbox); /* can sleep */
144void mbox_chan_received_data(struct mbox_chan *chan, void *data); /* atomic */
145void mbox_chan_txdone(struct mbox_chan *chan, int r); /* atomic */
146
147int devm_mbox_controller_register(struct device *dev,
148 struct mbox_controller *mbox);
149#endif /* __MAILBOX_CONTROLLER_H */