mailbox.c

  1// SPDX-License-Identifier: GPL-2.0-only
  2/*
  3 * Mailbox: Common code for Mailbox controllers and users
  4 *
  5 * Copyright (C) 2013-2014 Linaro Ltd.
  6 * Author: Jassi Brar <jassisinghbrar@gmail.com>
  7 */
  8
  9#include <linux/cleanup.h>
 10#include <linux/delay.h>
 11#include <linux/device.h>
 12#include <linux/err.h>
 13#include <linux/mailbox_client.h>
 14#include <linux/mailbox_controller.h>
 15#include <linux/module.h>
 16#include <linux/mutex.h>
 17#include <linux/of.h>
 18#include <linux/property.h>
 19#include <linux/spinlock.h>
 20
 21#include "mailbox.h"
 22
 23static LIST_HEAD(mbox_cons);
 24static DEFINE_MUTEX(con_mutex);
 25
 26static int add_to_rbuf(struct mbox_chan *chan, void *mssg)
 27{
 28	int idx;
 29
 30	guard(spinlock_irqsave)(&chan->lock);
 31
 32	/* See if there is any space left */
 33	if (chan->msg_count == MBOX_TX_QUEUE_LEN)
 34		return -ENOBUFS;
 35
 36	idx = chan->msg_free;
 37	chan->msg_data[idx] = mssg;
 38	chan->msg_count++;
 39
 40	if (idx == MBOX_TX_QUEUE_LEN - 1)
 41		chan->msg_free = 0;
 42	else
 43		chan->msg_free++;
 44
 45	return idx;
 46}
 47
 48static void msg_submit(struct mbox_chan *chan)
 49{
 50	unsigned count, idx;
 51	void *data;
 52	int err = -EBUSY;
 53
 54	scoped_guard(spinlock_irqsave, &chan->lock) {
 55		if (!chan->msg_count || chan->active_req)
 56			break;
 57
 58		count = chan->msg_count;
 59		idx = chan->msg_free;
 60		if (idx >= count)
 61			idx -= count;
 62		else
 63			idx += MBOX_TX_QUEUE_LEN - count;
 64
 65		data = chan->msg_data[idx];
 66
 67		if (chan->cl->tx_prepare)
 68			chan->cl->tx_prepare(chan->cl, data);
 69		/* Try to submit a message to the MBOX controller */
 70		err = chan->mbox->ops->send_data(chan, data);
 71		if (!err) {
 72			chan->active_req = data;
 73			chan->msg_count--;
 74		}
 75	}
 76
 77	if (!err && (chan->txdone_method & TXDONE_BY_POLL)) {
 78		/* kick start the timer immediately to avoid delays */
 79		scoped_guard(spinlock_irqsave, &chan->mbox->poll_hrt_lock)
 80			hrtimer_start(&chan->mbox->poll_hrt, 0, HRTIMER_MODE_REL);
 81	}
 82}
 83
 84static void tx_tick(struct mbox_chan *chan, int r)
 85{
 86	void *mssg;
 87
 88	scoped_guard(spinlock_irqsave, &chan->lock) {
 89		mssg = chan->active_req;
 90		chan->active_req = NULL;
 91	}
 92
 93	/* Submit next message */
 94	msg_submit(chan);
 95
 96	if (!mssg)
 97		return;
 98
 99	/* Notify the client */
100	if (chan->cl->tx_done)
101		chan->cl->tx_done(chan->cl, mssg, r);
102
103	if (r != -ETIME && chan->cl->tx_block)
104		complete(&chan->tx_complete);
105}
106
107static enum hrtimer_restart txdone_hrtimer(struct hrtimer *hrtimer)
108{
109	struct mbox_controller *mbox =
110		container_of(hrtimer, struct mbox_controller, poll_hrt);
111	bool txdone, resched = false;
112	int i;
113
114	for (i = 0; i < mbox->num_chans; i++) {
115		struct mbox_chan *chan = &mbox->chans[i];
116
117		if (chan->active_req && chan->cl) {
118			txdone = chan->mbox->ops->last_tx_done(chan);
119			if (txdone)
120				tx_tick(chan, 0);
121			else
122				resched = true;
123		}
124	}
125
126	if (resched) {
127		scoped_guard(spinlock_irqsave, &mbox->poll_hrt_lock) {
128			if (!hrtimer_is_queued(hrtimer))
129				hrtimer_forward_now(hrtimer, ms_to_ktime(mbox->txpoll_period));
130		}
131
132		return HRTIMER_RESTART;
133	}
134	return HRTIMER_NORESTART;
135}
136
137/**
138 * mbox_chan_received_data - A way for controller driver to push data
139 *				received from remote to the upper layer.
140 * @chan: Pointer to the mailbox channel on which RX happened.
141 * @mssg: Client specific message typecasted as void *
142 *
143 * After startup and before shutdown any data received on the chan
144 * is passed on to the API via atomic mbox_chan_received_data().
145 * The controller should ACK the RX only after this call returns.
146 */
147void mbox_chan_received_data(struct mbox_chan *chan, void *mssg)
148{
149	/* No buffering the received data */
150	if (chan->cl->rx_callback)
151		chan->cl->rx_callback(chan->cl, mssg);
152}
153EXPORT_SYMBOL_GPL(mbox_chan_received_data);
154
155/**
156 * mbox_chan_txdone - A way for controller driver to notify the
157 *			framework that the last TX has completed.
158 * @chan: Pointer to the mailbox chan on which TX happened.
159 * @r: Status of last TX - OK or ERROR
160 *
161 * The controller that has IRQ for TX ACK calls this atomic API
162 * to tick the TX state machine. It works only if txdone_irq
163 * is set by the controller.
164 */
165void mbox_chan_txdone(struct mbox_chan *chan, int r)
166{
167	if (unlikely(!(chan->txdone_method & TXDONE_BY_IRQ))) {
168		dev_err(chan->mbox->dev,
169		       "Controller can't run the TX ticker\n");
170		return;
171	}
172
173	tx_tick(chan, r);
174}
175EXPORT_SYMBOL_GPL(mbox_chan_txdone);
176
177/**
178 * mbox_client_txdone - The way for a client to run the TX state machine.
179 * @chan: Mailbox channel assigned to this client.
180 * @r: Success status of last transmission.
181 *
182 * The client/protocol had received some 'ACK' packet and it notifies
183 * the API that the last packet was sent successfully. This only works
184 * if the controller can't sense TX-Done.
185 */
186void mbox_client_txdone(struct mbox_chan *chan, int r)
187{
188	if (unlikely(!(chan->txdone_method & TXDONE_BY_ACK))) {
189		dev_err(chan->mbox->dev, "Client can't run the TX ticker\n");
190		return;
191	}
192
193	tx_tick(chan, r);
194}
195EXPORT_SYMBOL_GPL(mbox_client_txdone);
196
197/**
198 * mbox_client_peek_data - A way for client driver to pull data
199 *			received from remote by the controller.
200 * @chan: Mailbox channel assigned to this client.
201 *
202 * A poke to controller driver for any received data.
203 * The data is actually passed onto client via the
204 * mbox_chan_received_data()
205 * The call can be made from atomic context, so the controller's
206 * implementation of peek_data() must not sleep.
207 *
208 * Return: True, if controller has, and is going to push after this,
209 *          some data.
210 *         False, if controller doesn't have any data to be read.
211 */
212bool mbox_client_peek_data(struct mbox_chan *chan)
213{
214	if (chan->mbox->ops->peek_data)
215		return chan->mbox->ops->peek_data(chan);
216
217	return false;
218}
219EXPORT_SYMBOL_GPL(mbox_client_peek_data);
220
221/**
222 * mbox_send_message -	For client to submit a message to be
223 *				sent to the remote.
224 * @chan: Mailbox channel assigned to this client.
225 * @mssg: Client specific message typecasted.
226 *
227 * For client to submit data to the controller destined for a remote
228 * processor. If the client had set 'tx_block', the call will return
229 * either when the remote receives the data or when 'tx_tout' millisecs
230 * run out.
231 *  In non-blocking mode, the requests are buffered by the API and a
232 * non-negative token is returned for each queued request. If the request
233 * is not queued, a negative token is returned. Upon failure or successful
234 * TX, the API calls 'tx_done' from atomic context, from which the client
235 * could submit yet another request.
236 * The pointer to message should be preserved until it is sent
237 * over the chan, i.e, tx_done() is made.
238 * This function could be called from atomic context as it simply
239 * queues the data and returns a token against the request.
240 *
241 * Return: Non-negative integer for successful submission (non-blocking mode)
242 *	or transmission over chan (blocking mode).
243 *	Negative value denotes failure.
244 */
245int mbox_send_message(struct mbox_chan *chan, void *mssg)
246{
247	int t;
248
249	if (!chan || !chan->cl)
250		return -EINVAL;
251
252	t = add_to_rbuf(chan, mssg);
253	if (t < 0) {
254		dev_err(chan->mbox->dev, "Try increasing MBOX_TX_QUEUE_LEN\n");
255		return t;
256	}
257
258	msg_submit(chan);
259
260	if (chan->cl->tx_block) {
261		unsigned long wait;
262		int ret;
263
264		if (!chan->cl->tx_tout) /* wait forever */
265			wait = msecs_to_jiffies(3600000);
266		else
267			wait = msecs_to_jiffies(chan->cl->tx_tout);
268
269		ret = wait_for_completion_timeout(&chan->tx_complete, wait);
270		if (ret == 0) {
271			t = -ETIME;
272			tx_tick(chan, t);
273		}
274	}
275
276	return t;
277}
278EXPORT_SYMBOL_GPL(mbox_send_message);
279
280/**
281 * mbox_flush - flush a mailbox channel
282 * @chan: mailbox channel to flush
283 * @timeout: time, in milliseconds, to allow the flush operation to succeed
284 *
285 * Mailbox controllers that need to work in atomic context can implement the
286 * ->flush() callback to busy loop until a transmission has been completed.
287 * The implementation must call mbox_chan_txdone() upon success. Clients can
288 * call the mbox_flush() function at any time after mbox_send_message() to
289 * flush the transmission. After the function returns success, the mailbox
290 * transmission is guaranteed to have completed.
291 *
292 * Returns: 0 on success or a negative error code on failure.
293 */
294int mbox_flush(struct mbox_chan *chan, unsigned long timeout)
295{
296	int ret;
297
298	if (!chan->mbox->ops->flush)
299		return -ENOTSUPP;
300
301	ret = chan->mbox->ops->flush(chan, timeout);
302	if (ret < 0)
303		tx_tick(chan, ret);
304
305	return ret;
306}
307EXPORT_SYMBOL_GPL(mbox_flush);
308
309static int __mbox_bind_client(struct mbox_chan *chan, struct mbox_client *cl)
310{
311	struct device *dev = cl->dev;
312	int ret;
313
314	if (chan->cl || !try_module_get(chan->mbox->dev->driver->owner)) {
315		dev_err(dev, "%s: mailbox not free\n", __func__);
316		return -EBUSY;
317	}
318
319	scoped_guard(spinlock_irqsave, &chan->lock) {
320		chan->msg_free = 0;
321		chan->msg_count = 0;
322		chan->active_req = NULL;
323		chan->cl = cl;
324		init_completion(&chan->tx_complete);
325
326		if (chan->txdone_method	== TXDONE_BY_POLL && cl->knows_txdone)
327			chan->txdone_method = TXDONE_BY_ACK;
328	}
329
330	if (chan->mbox->ops->startup) {
331		ret = chan->mbox->ops->startup(chan);
332
333		if (ret) {
334			dev_err(dev, "Unable to startup the chan (%d)\n", ret);
335			mbox_free_channel(chan);
336			return ret;
337		}
338	}
339
340	return 0;
341}
342
343/**
344 * mbox_bind_client - Request a mailbox channel.
345 * @chan: The mailbox channel to bind the client to.
346 * @cl: Identity of the client requesting the channel.
347 *
348 * The Client specifies its requirements and capabilities while asking for
349 * a mailbox channel. It can't be called from atomic context.
350 * The channel is exclusively allocated and can't be used by another
351 * client before the owner calls mbox_free_channel.
352 * After assignment, any packet received on this channel will be
353 * handed over to the client via the 'rx_callback'.
354 * The framework holds reference to the client, so the mbox_client
355 * structure shouldn't be modified until the mbox_free_channel returns.
356 *
357 * Return: 0 if the channel was assigned to the client successfully.
358 *         <0 for request failure.
359 */
360int mbox_bind_client(struct mbox_chan *chan, struct mbox_client *cl)
361{
362	guard(mutex)(&con_mutex);
363
364	return __mbox_bind_client(chan, cl);
365}
366EXPORT_SYMBOL_GPL(mbox_bind_client);
367
368/**
369 * mbox_request_channel - Request a mailbox channel.
370 * @cl: Identity of the client requesting the channel.
371 * @index: Index of mailbox specifier in 'mboxes' property.
372 *
373 * The Client specifies its requirements and capabilities while asking for
374 * a mailbox channel. It can't be called from atomic context.
375 * The channel is exclusively allocated and can't be used by another
376 * client before the owner calls mbox_free_channel.
377 * After assignment, any packet received on this channel will be
378 * handed over to the client via the 'rx_callback'.
379 * The framework holds reference to the client, so the mbox_client
380 * structure shouldn't be modified until the mbox_free_channel returns.
381 *
382 * Return: Pointer to the channel assigned to the client if successful.
383 *		ERR_PTR for request failure.
384 */
385struct mbox_chan *mbox_request_channel(struct mbox_client *cl, int index)
386{
387	struct fwnode_reference_args fwspec;
388	struct fwnode_handle *fwnode;
389	struct mbox_controller *mbox;
390	struct of_phandle_args spec;
391	struct mbox_chan *chan;
392	struct device *dev;
393	unsigned int i;
394	int ret;
395
396	dev = cl->dev;
397	if (!dev) {
398		pr_debug("No owner device\n");
399		return ERR_PTR(-ENODEV);
400	}
401
402	fwnode = dev_fwnode(dev);
403	if (!fwnode) {
404		dev_dbg(dev, "No owner fwnode\n");
405		return ERR_PTR(-ENODEV);
406	}
407
408	ret = fwnode_property_get_reference_args(fwnode, "mboxes", "#mbox-cells",
409						 0, index, &fwspec);
410	if (ret) {
411		dev_err(dev, "%s: can't parse \"%s\" property\n", __func__, "mboxes");
412		return ERR_PTR(ret);
413	}
414
415	spec.np = to_of_node(fwspec.fwnode);
416	spec.args_count = fwspec.nargs;
417	for (i = 0; i < spec.args_count; i++)
418		spec.args[i] = fwspec.args[i];
419
420	scoped_guard(mutex, &con_mutex) {
421		chan = ERR_PTR(-EPROBE_DEFER);
422		list_for_each_entry(mbox, &mbox_cons, node) {
423			if (device_match_fwnode(mbox->dev, fwspec.fwnode)) {
424				if (mbox->fw_xlate) {
425					chan = mbox->fw_xlate(mbox, &fwspec);
426					if (!IS_ERR(chan))
427						break;
428				} else if (mbox->of_xlate) {
429					chan = mbox->of_xlate(mbox, &spec);
430					if (!IS_ERR(chan))
431						break;
432				}
433			}
434		}
435
436		fwnode_handle_put(fwspec.fwnode);
437
438		if (IS_ERR(chan))
439			return chan;
440
441		ret = __mbox_bind_client(chan, cl);
442		if (ret)
443			chan = ERR_PTR(ret);
444	}
445
446	return chan;
447}
448EXPORT_SYMBOL_GPL(mbox_request_channel);
449
450struct mbox_chan *mbox_request_channel_byname(struct mbox_client *cl,
451					      const char *name)
452{
453	int index = device_property_match_string(cl->dev, "mbox-names", name);
454
455	if (index < 0) {
456		dev_err(cl->dev, "%s() could not locate channel named \"%s\"\n",
457			__func__, name);
458		return ERR_PTR(index);
459	}
460	return mbox_request_channel(cl, index);
461}
462EXPORT_SYMBOL_GPL(mbox_request_channel_byname);
463
464/**
465 * mbox_free_channel - The client relinquishes control of a mailbox
466 *			channel by this call.
467 * @chan: The mailbox channel to be freed.
468 */
469void mbox_free_channel(struct mbox_chan *chan)
470{
471	if (!chan || !chan->cl)
472		return;
473
474	if (chan->mbox->ops->shutdown)
475		chan->mbox->ops->shutdown(chan);
476
477	/* The queued TX requests are simply aborted, no callbacks are made */
478	scoped_guard(spinlock_irqsave, &chan->lock) {
479		chan->cl = NULL;
480		chan->active_req = NULL;
481		if (chan->txdone_method == TXDONE_BY_ACK)
482			chan->txdone_method = TXDONE_BY_POLL;
483	}
484
485	module_put(chan->mbox->dev->driver->owner);
486}
487EXPORT_SYMBOL_GPL(mbox_free_channel);
488
489static struct mbox_chan *fw_mbox_index_xlate(struct mbox_controller *mbox,
490					     const struct fwnode_reference_args *sp)
491{
492	if (sp->nargs < 1 || sp->args[0] >= mbox->num_chans)
493		return ERR_PTR(-EINVAL);
494
495	return &mbox->chans[sp->args[0]];
496}
497
498/**
499 * mbox_controller_register - Register the mailbox controller
500 * @mbox:	Pointer to the mailbox controller.
501 *
502 * The controller driver registers its communication channels
503 */
504int mbox_controller_register(struct mbox_controller *mbox)
505{
506	int i, txdone;
507
508	/* Sanity check */
509	if (!mbox || !mbox->dev || !mbox->ops || !mbox->num_chans)
510		return -EINVAL;
511
512	if (mbox->txdone_irq)
513		txdone = TXDONE_BY_IRQ;
514	else if (mbox->txdone_poll)
515		txdone = TXDONE_BY_POLL;
516	else /* It has to be ACK then */
517		txdone = TXDONE_BY_ACK;
518
519	if (txdone == TXDONE_BY_POLL) {
520
521		if (!mbox->ops->last_tx_done) {
522			dev_err(mbox->dev, "last_tx_done method is absent\n");
523			return -EINVAL;
524		}
525
526		hrtimer_setup(&mbox->poll_hrt, txdone_hrtimer, CLOCK_MONOTONIC, HRTIMER_MODE_REL);
527		spin_lock_init(&mbox->poll_hrt_lock);
528	}
529
530	for (i = 0; i < mbox->num_chans; i++) {
531		struct mbox_chan *chan = &mbox->chans[i];
532
533		chan->cl = NULL;
534		chan->mbox = mbox;
535		chan->txdone_method = txdone;
536		spin_lock_init(&chan->lock);
537	}
538
539	if (!mbox->fw_xlate && !mbox->of_xlate)
540		mbox->fw_xlate = fw_mbox_index_xlate;
541
542	scoped_guard(mutex, &con_mutex)
543		list_add_tail(&mbox->node, &mbox_cons);
544
545	return 0;
546}
547EXPORT_SYMBOL_GPL(mbox_controller_register);
548
549/**
550 * mbox_controller_unregister - Unregister the mailbox controller
551 * @mbox:	Pointer to the mailbox controller.
552 */
553void mbox_controller_unregister(struct mbox_controller *mbox)
554{
555	int i;
556
557	if (!mbox)
558		return;
559
560	scoped_guard(mutex, &con_mutex) {
561		list_del(&mbox->node);
562
563		for (i = 0; i < mbox->num_chans; i++)
564			mbox_free_channel(&mbox->chans[i]);
565
566		if (mbox->txdone_poll)
567			hrtimer_cancel(&mbox->poll_hrt);
568	}
569}
570EXPORT_SYMBOL_GPL(mbox_controller_unregister);
571
572static void __devm_mbox_controller_unregister(struct device *dev, void *res)
573{
574	struct mbox_controller **mbox = res;
575
576	mbox_controller_unregister(*mbox);
577}
578
579/**
580 * devm_mbox_controller_register() - managed mbox_controller_register()
581 * @dev: device owning the mailbox controller being registered
582 * @mbox: mailbox controller being registered
583 *
584 * This function adds a device-managed resource that will make sure that the
585 * mailbox controller, which is registered using mbox_controller_register()
586 * as part of this function, will be unregistered along with the rest of
587 * device-managed resources upon driver probe failure or driver removal.
588 *
589 * Returns 0 on success or a negative error code on failure.
590 */
591int devm_mbox_controller_register(struct device *dev,
592				  struct mbox_controller *mbox)
593{
594	struct mbox_controller **ptr;
595	int err;
596
597	ptr = devres_alloc(__devm_mbox_controller_unregister, sizeof(*ptr),
598			   GFP_KERNEL);
599	if (!ptr)
600		return -ENOMEM;
601
602	err = mbox_controller_register(mbox);
603	if (err < 0) {
604		devres_free(ptr);
605		return err;
606	}
607
608	devres_add(dev, ptr);
609	*ptr = mbox;
610
611	return 0;
612}
613EXPORT_SYMBOL_GPL(devm_mbox_controller_register);