mailbox.h 6.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147
  1. /* SPDX-License-Identifier: GPL-2.0 */
  2. /*
  3. * Copyright (c) 2016, NVIDIA CORPORATION.
  4. */
  5. #ifndef _MAILBOX_H
  6. #define _MAILBOX_H
  7. /**
  8. * A mailbox is a hardware mechanism for transferring small fixed-size messages
  9. * and/or notifications between the CPU on which U-Boot runs and some other
  10. * device such as an auxiliary CPU running firmware or a hardware module.
  11. *
  12. * Data transfer is optional; a mailbox may consist solely of a notification
  13. * mechanism. When data transfer is implemented, it is via HW registers or
  14. * FIFOs, rather than via RAM-based buffers. The mailbox API generally
  15. * implements any communication protocol enforced solely by hardware, and
  16. * leaves any higher-level protocols to other layers.
  17. *
  18. * A mailbox channel is a bi-directional mechanism that can send a message or
  19. * notification to a single specific remote entity, and receive messages or
  20. * notifications from that entity. The size, content, and format of such
  21. * messages is defined by the mailbox implementation, or the remote entity with
  22. * which it communicates; there is no general standard at this API level.
  23. *
  24. * A driver that implements UCLASS_MAILBOX is a mailbox provider. A provider
  25. * will often implement multiple separate mailbox channels, since the hardware
  26. * it manages often has this capability. mailbox-uclass.h describes the
  27. * interface which mailbox providers must implement.
  28. *
  29. * Mailbox consumers/clients generate and send, or receive and process,
  30. * messages. This header file describes the API used by clients.
  31. */
  32. struct udevice;
  33. /**
  34. * struct mbox_chan - A handle to a single mailbox channel.
  35. *
  36. * Clients provide storage for channels. The content of the channel structure
  37. * is managed solely by the mailbox API and mailbox drivers. A mailbox channel
  38. * is initialized by "get"ing the mailbox. The channel struct is passed to all
  39. * other mailbox APIs to identify which mailbox to operate upon.
  40. *
  41. * @dev: The device which implements the mailbox.
  42. * @id: The mailbox channel ID within the provider.
  43. * @con_priv: Hook for controller driver to attach private data
  44. *
  45. * Currently, the mailbox API assumes that a single integer ID is enough to
  46. * identify and configure any mailbox channel for any mailbox provider. If this
  47. * assumption becomes invalid in the future, the struct could be expanded to
  48. * either (a) add more fields to allow mailbox providers to store additional
  49. * information, or (b) replace the id field with an opaque pointer, which the
  50. * provider would dynamically allocated during its .of_xlate op, and process
  51. * during is .request op. This may require the addition of an extra op to clean
  52. * up the allocation.
  53. */
  54. struct mbox_chan {
  55. struct udevice *dev;
  56. /* Written by of_xlate.*/
  57. unsigned long id;
  58. void *con_priv;
  59. };
  60. /**
  61. * mbox_get_by_index - Get/request a mailbox by integer index
  62. *
  63. * This looks up and requests a mailbox channel. The index is relative to the
  64. * client device; each device is assumed to have n mailbox channels associated
  65. * with it somehow, and this function finds and requests one of them. The
  66. * mapping of client device channel indices to provider channels may be via
  67. * device-tree properties, board-provided mapping tables, or some other
  68. * mechanism.
  69. *
  70. * @dev: The client device.
  71. * @index: The index of the mailbox channel to request, within the
  72. * client's list of channels.
  73. * @chan A pointer to a channel object to initialize.
  74. * @return 0 if OK, or a negative error code.
  75. */
  76. int mbox_get_by_index(struct udevice *dev, int index, struct mbox_chan *chan);
  77. /**
  78. * mbox_get_by_name - Get/request a mailbox by name
  79. *
  80. * This looks up and requests a mailbox channel. The name is relative to the
  81. * client device; each device is assumed to have n mailbox channels associated
  82. * with it somehow, and this function finds and requests one of them. The
  83. * mapping of client device channel names to provider channels may be via
  84. * device-tree properties, board-provided mapping tables, or some other
  85. * mechanism.
  86. *
  87. * @dev: The client device.
  88. * @name: The name of the mailbox channel to request, within the client's
  89. * list of channels.
  90. * @chan A pointer to a channel object to initialize.
  91. * @return 0 if OK, or a negative error code.
  92. */
  93. int mbox_get_by_name(struct udevice *dev, const char *name,
  94. struct mbox_chan *chan);
  95. /**
  96. * mbox_free - Free a previously requested mailbox channel.
  97. *
  98. * @chan: A channel object that was previously successfully requested by
  99. * calling mbox_get_by_*().
  100. * @return 0 if OK, or a negative error code.
  101. */
  102. int mbox_free(struct mbox_chan *chan);
  103. /**
  104. * mbox_send - Send a message over a mailbox channel
  105. *
  106. * This function will send a message to the remote entity. It may return before
  107. * the remote entity has received and/or processed the message.
  108. *
  109. * @chan: A channel object that was previously successfully requested by
  110. * calling mbox_get_by_*().
  111. * @data: A pointer to the message to transfer. The format and size of
  112. * the memory region pointed at by @data is determined by the
  113. * mailbox provider. Providers that solely transfer notifications
  114. * will ignore this parameter.
  115. * @return 0 if OK, or a negative error code.
  116. */
  117. int mbox_send(struct mbox_chan *chan, const void *data);
  118. /**
  119. * mbox_recv - Receive any available message from a mailbox channel
  120. *
  121. * This function will wait (up to the specified @timeout_us) for a message to
  122. * be sent by the remote entity, and write the content of any such message
  123. * into a caller-provided buffer.
  124. *
  125. * @chan: A channel object that was previously successfully requested by
  126. * calling mbox_get_by_*().
  127. * @data: A pointer to the buffer to receive the message. The format and
  128. * size of the memory region pointed at by @data is determined by
  129. * the mailbox provider. Providers that solely transfer
  130. * notifications will ignore this parameter.
  131. * @timeout_us: The maximum time to wait for a message to be available, in
  132. * micro-seconds. A value of 0 does not wait at all.
  133. * @return 0 if OK, -ENODATA if no message was available, or a negative error
  134. * code.
  135. */
  136. int mbox_recv(struct mbox_chan *chan, void *data, ulong timeout_us);
  137. #endif