habmm.h 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381
  1. /* SPDX-License-Identifier: GPL-2.0-only */
  2. /*
  3. * Copyright (c) 2016-2020, The Linux Foundation. All rights reserved.
  4. * Copyright (c) 2022-2024 Qualcomm Innovation Center, Inc. All rights reserved.
  5. */
  6. #ifndef HABMM_H
  7. #define HABMM_H
  8. #include "linux/habmmid.h"
  9. #define HAB_API_VER_DEF(_MAJOR_, _MINOR_) \
  10. ((_MAJOR_&0xFF)<<16 | (_MINOR_&0xFFF))
  11. #define HAB_API_VER HAB_API_VER_DEF(1, 0)
  12. #include <linux/types.h>
  13. /* habmm_socket_open
  14. *
  15. * Description:
  16. *
  17. * Establish a communication channel between Virtual Machines. Blocks
  18. * until the connection is established between sender and receiver.
  19. * Client can call this APImultiple times with the same name to connect
  20. * to the same communication channel, the function returns a different context
  21. * for every open for proper resource allocation and client identification.
  22. *
  23. * Params:
  24. * out handle - An opaque handle associated with a successful virtual channel
  25. * creation in MM_ID - multimedia ID used to allocate the physical channels to
  26. * service all the virtual channels created through this open
  27. * in timeout - timeout value specified by the client to avoid forever block
  28. * in flags - future extension
  29. *
  30. * Return:
  31. * status (success/failure/timeout)
  32. *
  33. */
  34. /* single FE-BE connection multi-to-multi point to point matching (default) */
  35. #define HABMM_SOCKET_OPEN_FLAGS_SINGLE_BE_SINGLE_FE 0x00000000
  36. /* one BE for one domU */
  37. #define HABMM_SOCKET_OPEN_FLAGS_SINGLE_BE_SINGLE_DOMU 0x00000001
  38. /* one BE for all the domUs */
  39. #define HABMM_SOCKET_OPEN_FLAGS_SINGLE_BE_MULTI_DOMUS 0x00000002
  40. /* This option is only available for HAB clients in kernel space, and it will
  41. * be HAB clients responsibility in kernel space to avoid calling any unexpected
  42. * uninterruptible habmm_socket_open() since it is not killable.
  43. */
  44. #define HABMM_SOCKET_OPEN_FLAGS_UNINTERRUPTIBLE 0x00000004
  45. int32_t habmm_socket_open(int32_t *handle, uint32_t mm_ip_id,
  46. uint32_t timeout, uint32_t flags);
  47. /* habmm_socket_close
  48. *
  49. * Description:
  50. *
  51. * Tear down the virtual channel that was established through habmm_socket_open
  52. * and release all resources associated with it.
  53. *
  54. * Params:
  55. *
  56. * in handle - handle to the virtual channel created by habmm_socket_open
  57. *
  58. * Return:
  59. * status - (success/failure)
  60. *
  61. *
  62. */
  63. int32_t habmm_socket_close(int32_t handle);
  64. /* habmm_socket_send
  65. *
  66. * Description:
  67. *
  68. * Send data over the virtual channel
  69. *
  70. * Params:
  71. *
  72. * in handle - handle created by habmm_socket_open
  73. * in src_buff - data to be send across the virtual channel
  74. * inout size_bytes - size of the data to be send. Either the whole packet is
  75. * sent or not
  76. * in flags - future extension
  77. *
  78. * Return:
  79. * status (success/fail/disconnected)
  80. *
  81. */
  82. /* Non-blocking mode: function will return immediately with HAB_AGAIN
  83. * if the send operation cannot be completed without blocking.
  84. */
  85. #define HABMM_SOCKET_SEND_FLAGS_NON_BLOCKING 0x00000001
  86. /* Collect cross-VM stats: client provides stat-buffer large enough to allow 2
  87. * sets of a 2-uint64_t pair to collect seconds and nano-seconds at the
  88. * beginning of the stat-buffer. Stats are collected when the stat-buffer leaves
  89. * VM1, then enters VM2
  90. */
  91. #define HABMM_SOCKET_SEND_FLAGS_XING_VM_STAT 0x00000002
  92. /* start to measure cross-vm schedule latency: VM1 send msg with this flag
  93. * to VM2 to kick off the measurement. In the hab driver level, the VM1 hab
  94. * driver shall record the time of schedule out with mpm_timer, and buffer
  95. * it for later usage. The VM2 hab driver shall record the time of schedule
  96. * in with mpm_timer and pass it to "habtest" application.
  97. */
  98. #define HABMM_SOCKET_XVM_SCHE_TEST 0x00000004
  99. /* VM2 responds this message to VM1 for HABMM_SOCKET_XVM_SCHE_TEST.
  100. * In the hab driver level, the VM2 hab driver shall record the time of schedule
  101. * out with mpm_timer, and buffer it for later usage; the VM1 hab driver
  102. * shall record the time of schedule in with mpm_timer and pass it to "habtest"
  103. * application.
  104. */
  105. #define HABMM_SOCKET_XVM_SCHE_TEST_ACK 0x00000008
  106. /* VM1 sends this message to VM2 asking for collect all the mpm_timer values
  107. * to calculate the latency of schduling between VM1 and VM2. In the hab driver
  108. * level, the VM1 hab driver shall save the previous restored schduling out
  109. * time to the message buffer
  110. */
  111. #define HABMM_SOCKET_XVM_SCHE_RESULT_REQ 0x00000010
  112. /* VM2 responds this message to VM2 for HABMM_SOCKET_XVM_SCHE_RESULT_REQ.
  113. * In the habtest application level, VM2 shall save the previous restored
  114. * scheduling in time into message buffer, in the hab driver level, VM2
  115. * shall save the previous restored scheduling out time to the message
  116. * buffer.
  117. */
  118. #define HABMM_SOCKET_XVM_SCHE_RESULT_RSP 0x00000020
  119. struct habmm_xing_vm_stat {
  120. uint64_t tx_sec;
  121. uint64_t tx_usec;
  122. uint64_t rx_sec;
  123. uint64_t rx_usec;
  124. };
  125. int32_t habmm_socket_send(int32_t handle, void *src_buff, uint32_t size_bytes,
  126. uint32_t flags);
  127. /* habmm_socket_recv
  128. *
  129. * Description:
  130. *
  131. * Receive data over the virtual channel created by habmm_socket_open.
  132. * Blocking until actual data is received or timeout value expires
  133. *
  134. * Params:
  135. *
  136. * in handle - communication channel created by habmm_socket_open
  137. * inout dst_buff - buffer pointer to store received data
  138. * inout size_bytes - size of the dst_buff. returned value shows the actual
  139. * bytes received.
  140. * in timeout - timeout value specified by the client to avoid forever blocking,
  141. * The unit of measurement is ms.
  142. * 0 is immediately timeout; -1 is forever blocking.
  143. * in flags - details as below.
  144. *
  145. *
  146. * Return:
  147. * status (success/failure/timeout/disconnected)
  148. *
  149. */
  150. /* Non-blocking mode: function will return immediately if there is no data
  151. * available.
  152. */
  153. #define HABMM_SOCKET_RECV_FLAGS_NON_BLOCKING 0x00000001
  154. /* In the blocking mode, this flag is used to indicate it is an
  155. * uninterruptbile blocking call.
  156. */
  157. #define HABMM_SOCKET_RECV_FLAGS_UNINTERRUPTIBLE 0x00000002
  158. /* Enable timeout function, This flag is used to indicate that the timeout
  159. * function takes effect. Note that the timeout parameter is meaningful only if
  160. * this flag is added, otherwise the timeout parameter is ignored.
  161. * In addition, when the HABMM_SOCKET_RECV_FLAGS_NON_BLOCKING flag is set,
  162. * the current flag is ignored.
  163. */
  164. #define HABMM_SOCKET_RECV_FLAGS_TIMEOUT 0x00000004
  165. int32_t habmm_socket_recv(int32_t handle, void *dst_buff, uint32_t *size_bytes,
  166. uint32_t timeout, uint32_t flags);
  167. /* habmm_socket_sendto
  168. *
  169. * Description:
  170. *
  171. * This is for backend only. Send data over the virtual channel to remote
  172. * frontend virtual channel for multi-FEs-to-single-BE model when
  173. * the BE virtual channel is created using
  174. * HABMM_SOCKET_OPEN_FLAGS_SINGLE_BE_SINGLE_DOMU or
  175. * HABMM_SOCKET_OPEN_FLAGS_SINGLE_BE_MULTI_DOMUS
  176. *
  177. * Params:
  178. *
  179. * in handle - handle created by habmm_socket_open
  180. * in src_buff - data to be send across the virtual channel
  181. * inout size_bytes - size of the data to be send. The packet is fully sent on
  182. * success,or not sent at all upon any failure
  183. * in remote_handle - the destination of this send using remote FE's virtual
  184. * channel handle
  185. * in flags - future extension
  186. *
  187. * Return:
  188. * status (success/fail/disconnected)
  189. */
  190. int32_t habmm_socket_sendto(int32_t handle, void *src_buff, uint32_t size_bytes,
  191. int32_t remote_handle, uint32_t flags);
  192. /* habmm_socket_recvfrom
  193. *
  194. * Description:
  195. *
  196. * Receive data over the virtual channel created by habmm_socket_open.
  197. * Returned is the remote FE's virtual channel handle to be used for sendto.
  198. * Blocking until actual data is received or timeout value expires. This is for
  199. * BE running in multi-FEs-to-single-BE model when the BE virtual channel is
  200. * created using HABMM_SOCKET_OPEN_FLAGS_SINGLE_BE_SINGLE_DOMU or
  201. * HABMM_SOCKET_OPEN_FLAGS_SINGLE_BE_MULTI_DOMUS.
  202. *
  203. * Params:
  204. *
  205. * in handle - communication channel created by habmm_socket_open
  206. * inout dst_buff - buffer pointer to store received data
  207. * inout size_bytes - size of the dst_buff. returned value shows the actual
  208. * bytes received.
  209. * in timeout - timeout value specified by the client to avoid forever block
  210. * in remote_handle - the FE who sent this message through the
  211. * connected virtual channel to BE.
  212. * in flags - future extension
  213. *
  214. * Return:
  215. * status (success/failure/timeout/disconnected)
  216. *
  217. */
  218. int32_t habmm_socket_recvfrom(int32_t handle, void *dst_buff,
  219. uint32_t *size_bytes, uint32_t timeout,
  220. int32_t *remote_handle, uint32_t flags);
  221. /* exporting memory type DMA : This is platform dependent for user mode. If it
  222. * does exist, HAB needs to use DMA method to retrieve the memory for exporting.
  223. * If it does not exist, this flag is ignored.
  224. */
  225. #define HABMM_EXP_MEM_TYPE_DMA 0x00000001
  226. /*
  227. * this flag is used for export from dma_buf fd or import to dma_buf fd
  228. */
  229. #define HABMM_EXPIMP_FLAGS_FD 0x00010000
  230. #define HABMM_EXPIMP_FLAGS_DMABUF 0x00020000
  231. #define HAB_MAX_EXPORT_SIZE 0x8000000
  232. /*
  233. * Description:
  234. *
  235. * Prepare the sharing of the buffer on the exporter side. The returned
  236. * reference ID needs to be sent to importer separately.
  237. * During sending the HAB will attach the actual exporting buffer information.
  238. * The exporting is per process space.
  239. *
  240. * Params:
  241. *
  242. * in handle - communication channel created by habmm_socket_open
  243. * in buff_to_share - buffer to be exported
  244. * in size_bytes - size of the exporting buffer in bytes
  245. * out export_id - to be returned by this call upon success
  246. * in flags - future extension
  247. *
  248. * Return:
  249. * status (success/failure)
  250. *
  251. */
  252. int32_t habmm_export(int32_t handle, void *buff_to_share, uint32_t size_bytes,
  253. uint32_t *export_id, uint32_t flags);
  254. /*
  255. * Description:
  256. *
  257. * Free any allocated resource associated with this export IDin on local side.
  258. * Params:
  259. *
  260. * in handle - communication channel created by habmm_socket_open
  261. * in export_id - all resource allocated with export_id are to be freed
  262. * in flags - future extension
  263. *
  264. * Return:
  265. * status (success/failure)
  266. *
  267. */
  268. int32_t habmm_unexport(int32_t handle, uint32_t export_id, uint32_t flags);
  269. /*
  270. * Description:
  271. *
  272. * Import the exporter's shared reference ID.
  273. * The importing is per process space.
  274. *
  275. * Params:
  276. *
  277. * in handle - communication channel created by habmm_socket_open
  278. * out buff_shared - buffer to be imported. returned upon success
  279. * in size_bytes - size of the imported buffer in bytes. It should match the
  280. * original exported buffer size
  281. * in export_id - received when exporter sent its exporting ID through
  282. * habmm_socket_send() previously
  283. * in flags - future extension
  284. *
  285. * Return:
  286. * status (success/failure)
  287. *
  288. */
  289. /* Non-blocking mode: function will return immediately if there is no data
  290. * available. Supported only for kernel clients.
  291. */
  292. #define HABMM_IMPORT_FLAGS_CACHED 0x00000001
  293. int32_t habmm_import(int32_t handle, void **buff_shared, uint32_t size_bytes,
  294. uint32_t export_id, uint32_t flags);
  295. /*
  296. * Description:
  297. *
  298. * Release any resource associated with the export ID on the importer side.
  299. *
  300. * Params:
  301. *
  302. * in handle - communication channel created by habmm_socket_open
  303. * in export_id - received when exporter sent its exporting ID through
  304. * habmm_socket_send() previously
  305. * in buff_shared - received from habmm_import() together with export_id
  306. * in flags - future extension
  307. *
  308. * Return:
  309. * status (success/failure)
  310. *
  311. */
  312. int32_t habmm_unimport(int32_t handle, uint32_t export_id, void *buff_shared,
  313. uint32_t flags);
  314. /*
  315. * Description:
  316. *
  317. * Query various information of the opened hab socket.
  318. *
  319. * Params:
  320. *
  321. * in handle - communication channel created by habmm_socket_open
  322. * in habmm_socket_info - retrieve socket information regarding local and remote
  323. * VMs
  324. * in flags - future extension
  325. *
  326. * Return:
  327. * status (success/failure)
  328. *
  329. */
  330. #define VMNAME_SIZE 12
  331. struct hab_socket_info {
  332. int32_t vmid_remote; /* habmm's vmid */
  333. int32_t vmid_local;
  334. /* name from hypervisor framework if available */
  335. char vmname_remote[VMNAME_SIZE];
  336. char vmname_local[VMNAME_SIZE];
  337. };
  338. int32_t habmm_socket_query(int32_t handle, struct hab_socket_info *info,
  339. uint32_t flags);
  340. #endif /* HABMM_H */