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