misc.h 4.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144
  1. /* SPDX-License-Identifier: GPL-2.0+ */
  2. /*
  3. * Copyright (C) 2015 Thomas Chou <thomas@wytron.com.tw>
  4. */
  5. #ifndef _MISC_H_
  6. #define _MISC_H_
  7. /**
  8. * misc_read() - Read the device to buffer, optional.
  9. * @dev: the device
  10. * @offset: offset to read the device
  11. * @buf: pointer to data buffer
  12. * @size: data size in bytes to read the device
  13. *
  14. * Return: number of bytes read if OK (may be 0 if EOF), -ve on error
  15. */
  16. int misc_read(struct udevice *dev, int offset, void *buf, int size);
  17. /**
  18. * misc_write() - Write buffer to the device, optional.
  19. * @dev: the device
  20. * @offset: offset to write the device
  21. * @buf: pointer to data buffer
  22. * @size: data size in bytes to write the device
  23. *
  24. * Return: number of bytes written if OK (may be < @size), -ve on error
  25. */
  26. int misc_write(struct udevice *dev, int offset, void *buf, int size);
  27. /**
  28. * misc_ioctl() - Assert command to the device, optional.
  29. * @dev: the device
  30. * @request: command to be sent to the device
  31. * @buf: pointer to buffer related to the request
  32. *
  33. * Return: 0 if OK, -ve on error
  34. */
  35. int misc_ioctl(struct udevice *dev, unsigned long request, void *buf);
  36. /**
  37. * misc_call() - Send a message to the device and wait for a response.
  38. * @dev: the device.
  39. * @msgid: the message ID/number to send.
  40. * @tx_msg: the request/transmit message payload.
  41. * @tx_size: the size of the buffer pointed at by tx_msg.
  42. * @rx_msg: the buffer to receive the response message payload. May be NULL if
  43. * the caller only cares about the error code.
  44. * @rx_size: the size of the buffer pointed at by rx_msg.
  45. *
  46. * The caller provides the message type/ID and payload to be sent.
  47. * The callee constructs any message header required, transmits it to the
  48. * target, waits for a response, checks any error code in the response,
  49. * strips any message header from the response, and returns the error code
  50. * (or a parsed version of it) and the response message payload.
  51. *
  52. * Return: the response message size if OK, -ve on error
  53. */
  54. int misc_call(struct udevice *dev, int msgid, void *tx_msg, int tx_size,
  55. void *rx_msg, int rx_size);
  56. /**
  57. * misc_set_enabled() - Enable or disable a device.
  58. * @dev: the device to enable or disable.
  59. * @val: the flag that tells the driver to either enable or disable the device.
  60. *
  61. * The semantics of "disable" and "enable" should be understood here as
  62. * activating or deactivating the device's primary function, hence a "disabled"
  63. * device should be dormant, but still answer to commands and queries.
  64. *
  65. * A probed device may start in a disabled or enabled state, depending on the
  66. * driver and hardware.
  67. *
  68. * Return: -ve on error, 0 if the previous state was "disabled", 1 if the
  69. * previous state was "enabled"
  70. */
  71. int misc_set_enabled(struct udevice *dev, bool val);
  72. /*
  73. * struct misc_ops - Driver model Misc operations
  74. *
  75. * The uclass interface is implemented by all miscellaneous devices which
  76. * use driver model.
  77. */
  78. struct misc_ops {
  79. /**
  80. * Read the device to buffer, optional.
  81. * @dev: the device
  82. * @offset: offset to read the device
  83. * @buf: pointer to data buffer
  84. * @size: data size in bytes to read the device
  85. *
  86. * Return: number of bytes read if OK (may be 0 if EOF), -ve on error
  87. */
  88. int (*read)(struct udevice *dev, int offset, void *buf, int size);
  89. /**
  90. * Write buffer to the device, optional.
  91. * @dev: the device
  92. * @offset: offset to write the device
  93. * @buf: pointer to data buffer
  94. * @size: data size in bytes to write the device
  95. *
  96. * Return: number of bytes written if OK (may be < @size), -ve on error
  97. */
  98. int (*write)(struct udevice *dev, int offset, const void *buf,
  99. int size);
  100. /**
  101. * Assert command to the device, optional.
  102. * @dev: the device
  103. * @request: command to be sent to the device
  104. * @buf: pointer to buffer related to the request
  105. *
  106. * Return: 0 if OK, -ve on error
  107. */
  108. int (*ioctl)(struct udevice *dev, unsigned long request, void *buf);
  109. /**
  110. * Send a message to the device and wait for a response.
  111. * @dev: the device
  112. * @msgid: the message ID/number to send
  113. * @tx_msg: the request/transmit message payload
  114. * @tx_size: the size of the buffer pointed at by tx_msg
  115. * @rx_msg: the buffer to receive the response message payload. May be
  116. * NULL if the caller only cares about the error code.
  117. * @rx_size: the size of the buffer pointed at by rx_msg
  118. *
  119. * Return: the response message size if OK, -ve on error
  120. */
  121. int (*call)(struct udevice *dev, int msgid, void *tx_msg, int tx_size,
  122. void *rx_msg, int rx_size);
  123. /**
  124. * Enable or disable a device, optional.
  125. * @dev: the device to enable.
  126. * @val: the flag that tells the driver to either enable or disable the
  127. * device.
  128. *
  129. * Return: -ve on error, 0 if the previous state was "disabled", 1 if
  130. * the previous state was "enabled"
  131. */
  132. int (*set_enabled)(struct udevice *dev, bool val);
  133. };
  134. #endif /* _MISC_H_ */