xrp_api.h 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605
  1. /*
  2. * Copyright (c) 2016 - 2017 Cadence Design Systems Inc.
  3. *
  4. * Permission is hereby granted, free of charge, to any person obtaining
  5. * a copy of this software and associated documentation files (the
  6. * "Software"), to deal in the Software without restriction, including
  7. * without limitation the rights to use, copy, modify, merge, publish,
  8. * distribute, sublicense, and/or sell copies of the Software, and to
  9. * permit persons to whom the Software is furnished to do so, subject to
  10. * the following conditions:
  11. *
  12. * The above copyright notice and this permission notice shall be included
  13. * in all copies or substantial portions of the Software.
  14. *
  15. * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  16. * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  17. * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  18. * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  19. * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  20. * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  21. * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  22. */
  23. /*!
  24. * \file xrp_api.h
  25. * \brief This section defines XRP API.
  26. *
  27. * General API properties:
  28. * - All status pointers can be NULL.
  29. * - Reference counting is not meant to work across host/DSP boundary, i.e.
  30. * DSP may not retain the host buffer.
  31. * - A buffer allocated for one device can be passed as command parameter to
  32. * a different device; implementation should do reasonable thing, e.g. use
  33. * the original data if possible or transparently migrate it to suitable
  34. * memory.
  35. * - A group of API calls may be host side only, DSP side only, or usable on
  36. * both sides. When it's usable on both sides there may be additional
  37. * restrictions on the DSP side.
  38. */
  39. #ifndef _XRP_API_H
  40. #define _XRP_API_H
  41. #include <stddef.h>
  42. #ifdef __cplusplus
  43. extern "C" {
  44. #endif
  45. /*
  46. * User API.
  47. */
  48. struct xrp_device;
  49. struct xrp_queue;
  50. struct xrp_buffer;
  51. struct xrp_buffer_group;
  52. struct xrp_event;
  53. /*!
  54. * Status codes of XRP calls.
  55. */
  56. enum xrp_status {
  57. /*! Call completed successfully. */
  58. XRP_STATUS_SUCCESS,
  59. /*! Call failed. */
  60. XRP_STATUS_FAILURE,
  61. /*! Call has not completed. */
  62. XRP_STATUS_PENDING,
  63. };
  64. enum xrp_access_flags {
  65. XRP_READ = 0x1,
  66. XRP_WRITE = 0x2,
  67. XRP_READ_WRITE = 0x3,
  68. };
  69. /*!
  70. * Types of information that may be queried for a buffer object.
  71. */
  72. enum xrp_buffer_info {
  73. /*! Size of the buffer. */
  74. XRP_BUFFER_SIZE_SIZE_T,
  75. /*! Host pointer of the buffer. */
  76. XRP_BUFFER_HOST_POINTER_PTR,
  77. };
  78. /*!
  79. * Types of information that may be queried for a buffer group object.
  80. */
  81. enum xrp_buffer_group_info {
  82. /*! Access flags associated with a buffer. Requires buffer index. */
  83. XRP_BUFFER_GROUP_BUFFER_FLAGS_ENUM,
  84. /*! Number of buffers in the buffer group. Buffer index is ignored. */
  85. XRP_BUFFER_GROUP_SIZE_SIZE_T,
  86. };
  87. #define XRP_NAMESPACE_ID_SIZE 16
  88. /*!
  89. * \defgroup device_api Device API
  90. * These calls are available on the host side and on the DSP side with the
  91. * following restriction:
  92. * - only device 0 may be opened.
  93. * @{
  94. */
  95. /*!
  96. * Open device by index.
  97. * A device is reference counted and is opened with reference count of 1.
  98. * Devices are numbered sequentially starting at 0, they can be probed with
  99. * simple loop.
  100. * \param idx: device index to open
  101. * \param[out] status: operation status
  102. * \return pointer to the opened device or NULL in case of error
  103. */
  104. struct xrp_device *xrp_open_device(int idx, enum xrp_status *status);
  105. /*!
  106. * Increment device reference count.
  107. */
  108. void xrp_retain_device(struct xrp_device *device);
  109. /*!
  110. * Decrement device reference count (and free associated resources once the
  111. * counter gets down to zero).
  112. */
  113. void xrp_release_device(struct xrp_device *device);
  114. /*!
  115. * @}
  116. */
  117. /*!
  118. * \defgroup buffer_api Buffer API
  119. * These calls are available on the host side and on the DSP side with the
  120. * following restriction:
  121. * - buffers may not be created on the DSP side.
  122. * @{
  123. */
  124. /*!
  125. * Create memory buffer and allocate device-specific storage (host_ptr == NULL)
  126. * or use host buffer (host_ptr != NULL, treated as virtual address in the
  127. * current process).
  128. * A buffer is reference counted and is created with reference count of 1.
  129. * \param[out] status: operation status
  130. */
  131. struct xrp_buffer *xrp_create_buffer(struct xrp_device *device,
  132. size_t size, void *host_ptr,
  133. enum xrp_status *status);
  134. /*!
  135. * Increment buffer reference count.
  136. */
  137. void xrp_retain_buffer(struct xrp_buffer *buffer);
  138. /*!
  139. * Decrement buffer reference count (and free the storage if it was allocated
  140. * once the counter gets down to zero).
  141. */
  142. void xrp_release_buffer(struct xrp_buffer *buffer);
  143. /*!
  144. * Map subbuffer of the buffer. Buffer may be mapped multiple times.
  145. *
  146. * \param map_flags: access to the mapping requested by the mapper. Access
  147. * to buffers on DSP side is subject to restrictions set by the host side.
  148. * \param[out] status: operation status
  149. */
  150. void *xrp_map_buffer(struct xrp_buffer *buffer, size_t offset, size_t size,
  151. enum xrp_access_flags map_flags, enum xrp_status *status);
  152. /*!
  153. * Unmap previously mapped buffer.
  154. * \param[out] status: operation status
  155. */
  156. void xrp_unmap_buffer(struct xrp_buffer *buffer, void *p,
  157. enum xrp_status *status);
  158. /*!
  159. * Get information about the buffer object.
  160. *
  161. * \param info: information type to retrieve.
  162. * \param[out] out: pointer to return information to.
  163. * \param out_sz: size of out buffer.
  164. * \param[out] status: operation status
  165. */
  166. void xrp_buffer_get_info(struct xrp_buffer *buffer, enum xrp_buffer_info info,
  167. void *out, size_t out_sz, enum xrp_status *status);
  168. /*!
  169. * @}
  170. */
  171. /*!
  172. * \defgroup buffer_group_api Buffer Group API
  173. * These calls are available on the host side and on the DSP side with the
  174. * following restrictions:
  175. * - buffer groups may not be created on the DSP side;
  176. * - existing buffer groups may not be modified on the DSP side.
  177. * @{
  178. */
  179. /*!
  180. * Create a group of shared buffers. Group is reference counted and is
  181. * created with reference count of 1.
  182. * \param[out] status: operation status
  183. */
  184. struct xrp_buffer_group *xrp_create_buffer_group(enum xrp_status *status);
  185. /*!
  186. * Increment buffer group reference count.
  187. */
  188. void xrp_retain_buffer_group(struct xrp_buffer_group *group);
  189. /*!
  190. * Decrement group reference count (and free it once the counter gets down
  191. * to zero).
  192. */
  193. void xrp_release_buffer_group(struct xrp_buffer_group *group);
  194. /*!
  195. * Add buffer to the group and get its index.
  196. * This adds a reference to the buffer.
  197. *
  198. * \param access_flags: granted access. User of the buffer on the DSP side
  199. * will be able to map it only for this type of access.
  200. * \param[out] status: operation status
  201. */
  202. size_t xrp_add_buffer_to_group(struct xrp_buffer_group *group,
  203. struct xrp_buffer *buffer,
  204. enum xrp_access_flags access_flags,
  205. enum xrp_status *status);
  206. /*!
  207. * Put new buffer to the existing index in the group.
  208. * When operation succeeds it releases the buffer previously contained at
  209. * that index and adds a reference to the new buffer.
  210. *
  211. * \param access_flags: granted access. User of the buffer on the DSP side
  212. * will be able to map it only for this type of access.
  213. * \param[out] status: operation status
  214. */
  215. void xrp_set_buffer_in_group(struct xrp_buffer_group *group,
  216. size_t index,
  217. struct xrp_buffer *buffer,
  218. enum xrp_access_flags access_flags,
  219. enum xrp_status *status);
  220. /*!
  221. * Get buffer from the group by its index.
  222. * Buffer must be freed with release_buffer.
  223. * \param[out] status: operation status
  224. */
  225. struct xrp_buffer *xrp_get_buffer_from_group(struct xrp_buffer_group *group,
  226. size_t idx,
  227. enum xrp_status *status);
  228. /*!
  229. * Get information about the buffer group object.
  230. *
  231. * \param info: information type to retrieve.
  232. * \param idx: buffer index (if applicable).
  233. * \param[out] out: pointer to return information to.
  234. * \param out_sz: size of out buffer.
  235. * \param[out] status: operation status
  236. */
  237. void xrp_buffer_group_get_info(struct xrp_buffer_group *group,
  238. enum xrp_buffer_group_info info, size_t idx,
  239. void *out, size_t out_sz,
  240. enum xrp_status *status);
  241. /*!
  242. * @}
  243. */
  244. /*!
  245. * \defgroup queue_api Queue API
  246. * These calls are available only on the host side.
  247. * @{
  248. */
  249. /*!
  250. * Create queue to the default namespace of the device.
  251. * Queue is an ordered device communication channel. Queue is reference
  252. * counted and is created with reference count of 1.
  253. * \param[out] status: operation status
  254. */
  255. struct xrp_queue *xrp_create_queue(struct xrp_device *device,
  256. enum xrp_status *status);
  257. /*!
  258. * Create queue to the specified namespace of the device.
  259. * Queue is an ordered device communication channel. Queue is reference
  260. * counted and is created with reference count of 1.
  261. * \param[out] status: operation status
  262. */
  263. struct xrp_queue *xrp_create_ns_queue(struct xrp_device *device,
  264. const void *nsid,
  265. enum xrp_status *status);
  266. /*!
  267. * Create queue to the specified namespace of the device with specific
  268. * priority.
  269. * Queue is an ordered device communication channel. Queue is reference
  270. * counted and is created with reference count of 1.
  271. * \param[out] status: operation status
  272. */
  273. struct xrp_queue *xrp_create_nsp_queue(struct xrp_device *device,
  274. const void *nsid,
  275. int priority,
  276. enum xrp_status *status);
  277. /*!
  278. * Increment queue reference count.
  279. */
  280. void xrp_retain_queue(struct xrp_queue *queue);
  281. /*!
  282. * Decrement queue reference count (and free it once the counter gets down
  283. * to zero).
  284. */
  285. void xrp_release_queue(struct xrp_queue *queue);
  286. /*!
  287. * @}
  288. */
  289. /*!
  290. * \defgroup event_api Event API
  291. * These calls are available only on the host side.
  292. * @{
  293. */
  294. /*!
  295. * Increment event reference count.
  296. */
  297. void xrp_retain_event(struct xrp_event *event);
  298. /*!
  299. * Decrement event reference count (and free it once the counter gets down
  300. * to zero).
  301. */
  302. void xrp_release_event(struct xrp_event *event);
  303. /*!
  304. * Get status of the event/associated command.
  305. * The function may be called at any time, it sets *status to
  306. * XRP_STATUS_PENDING if the command has not been executed yet, or to the
  307. * command execution status. See status description of xrp_run_command_sync()
  308. * for the description of command execution status.
  309. * \param[out] status: operation status
  310. */
  311. void xrp_event_status(struct xrp_event *event, enum xrp_status *status);
  312. /*!
  313. * @}
  314. */
  315. /*!
  316. * \defgroup communication_api Communication API
  317. * These calls are available only on the host side.
  318. * @{
  319. */
  320. /*
  321. * Even more internal API related to command passing between cores.
  322. * These are tightly coupled to the host-DSP communication model and
  323. * are likely to be changed/enhanced as the model evolves.
  324. */
  325. /*!
  326. * Synchronously send command from host to DSP.
  327. *
  328. * When this is invoked on the host it synchronously runs a command on DSP,
  329. * passing a group of shared buffers and two additional (small) buffers
  330. * with opaque command description (in_data) and results (out_data).
  331. *
  332. * in_data is used at the function call and is not referenced afterwards.
  333. * out_data is updated with the value returned by DSP before the function
  334. * returns.
  335. *
  336. * Optimal processing is guaranteed for in_data and out_data buffers not
  337. * exceeding 16 bytes in size. Larger buffers may require additional data
  338. * copying depending on the implementation.
  339. *
  340. * status is the result of command execution. Command execution is
  341. * successful if the command was delivered to the DSP and the response was
  342. * delivered back. Otherwise the command execution has failed. IOW execution
  343. * success means that the out_data contains command-specific response received
  344. * from the DSP, execution failure means that out_data does not contain useful
  345. * information.
  346. *
  347. * \param[out] status: operation status
  348. */
  349. void xrp_run_command_sync(struct xrp_queue *queue,
  350. const void *in_data, size_t in_data_size,
  351. void *out_data, size_t out_data_size,
  352. struct xrp_buffer_group *buffer_group,
  353. enum xrp_status *status);
  354. /*!
  355. * Asynchronously send command from host to DSP.
  356. *
  357. * When this is invoked on the host it queues a command to DSP,
  358. * passing a group of shared buffers and two additional (small) buffers
  359. * with opaque command description (in_data) and results (out_data).
  360. *
  361. * in_data is used at the function call and is not referenced afterwards.
  362. * out_data must stay valid after this function call until command completion,
  363. * at which point it is updated with the value returned by DSP.
  364. *
  365. * Optimal processing is guaranteed for in_data and out_data buffers not
  366. * exceeding 16 bytes in size. Larger buffers may require additional data
  367. * copying depending on the implementation.
  368. *
  369. * If event is non-NULL then a pointer to an event corresponding to the
  370. * queued command is returned. This event can be waited for with xrp_wait,
  371. * it is signaled when the command execution is complete.
  372. * The returned event object is reference counted and is created with
  373. * reference count of 1.
  374. *
  375. * status is the result of command enqueuing. Command enqueuing is
  376. * successful if the command was enqueued on the host side and an associated
  377. * event has been returned (if requested). Otherwise the command enqueuing has
  378. * failed. IOW enqueuing success means that if event is non-NULL then *event
  379. * contains valid event, enqueuing failure means that *event does not contain
  380. * useful information.
  381. *
  382. * \param[out] status: operation status
  383. */
  384. void xrp_enqueue_command(struct xrp_queue *queue,
  385. const void *in_data, size_t in_data_size,
  386. void *out_data, size_t out_data_size,
  387. struct xrp_buffer_group *buffer_group,
  388. struct xrp_event **event,
  389. enum xrp_status *status);
  390. /*!
  391. * Wait for the event.
  392. * Waiting for already signaled event completes immediately.
  393. * Successful completion of this function does not alter the event state,
  394. * i.e. the event remains signaled.
  395. * status is the result of waiting, not the result of the command execution.
  396. * Use xrp_event_status() to get the command execution status.
  397. * \param[out] status: operation status
  398. */
  399. void xrp_wait(struct xrp_event *event, enum xrp_status *status);
  400. /*!
  401. * Wait for any event in the group.
  402. * Waiting for a group with already signaled event completes immediately.
  403. * Successful completion of this function does not alter the event state,
  404. * i.e. signaled events remain signaled.
  405. * status is the result of waiting, not the result of the command execution.
  406. * Use xrp_event_status() with individual events to get the corresponding
  407. * command execution status.
  408. *
  409. * \param[in] event: an array of pointers to events to wait for
  410. * \param[i] n_events: number of events in the events array
  411. * \param[out] status: operation status
  412. * \return index of a completed event in the event array
  413. */
  414. size_t xrp_wait_any(struct xrp_event **event, size_t n_events,
  415. enum xrp_status *status);
  416. /*!
  417. * @}
  418. */
  419. /*!
  420. * \defgroup dsp_specific_api DSP-specific Interface (Library-Style)
  421. * These calls are available only on the DSP side.
  422. * @{
  423. */
  424. /*!
  425. * Check if there's a command from the host in the hardware queue.
  426. * Returns XRP_STATUS_PENDING if the queue is empty or XRP_STATUS_SUCCESS
  427. * if there is a command ready for processing.
  428. *
  429. * The check is quick and may be issued in any context.
  430. */
  431. enum xrp_status xrp_device_poll(struct xrp_device *device);
  432. /*!
  433. * Check if there's a command from the host in the hardware queue and invoke
  434. * command handler if there's one.
  435. * Returns XRP_STATUS_PENDING if the queue is empty, or the status returned by
  436. * the command handler.
  437. */
  438. enum xrp_status xrp_device_dispatch(struct xrp_device *device);
  439. /*!
  440. * Function type for command handler.
  441. *
  442. * This callback is called on the DSP side to process queued command.
  443. * in_data, out_data and buffer_group correspond to the same parameters of the
  444. * host side API calls.
  445. *
  446. * On return from this function buffer group and individual buffer reference
  447. * counters shall be restored to their entry values. out_data buffer shall be
  448. * updated with command return value.
  449. * Neither in_data nor out_data may be referenced after this function returns.
  450. *
  451. * Return value shall describe whether xrp_command_handler itself was
  452. * successful or not, not the command it was requested to run.
  453. * I.e. if the command was not recognized or its handler could not be called
  454. * due to insufficient memory, that's XRP_STATUS_FAILURE returned in status.
  455. * The host will also receive XRP_STATUS_FAILURE as a completion status.
  456. * If the command was run that's XRP_STATUS_SUCCESS regardless of the
  457. * command-specific status, which should be returned in out_data.
  458. *
  459. * \param handler_context: context that was passed to the
  460. * xrp_device_register_namespace
  461. */
  462. typedef enum xrp_status
  463. (xrp_command_handler)(void *handler_context,
  464. const void *in_data, size_t in_data_size,
  465. void *out_data, size_t out_data_size,
  466. struct xrp_buffer_group *buffer_group);
  467. /*!
  468. * Register namespace handler.
  469. *
  470. * There may be only one handler for a namespace, second attempt to register
  471. * a handler for the same namespace will fail.
  472. *
  473. * \param device: device for which namespace handler is registered
  474. * \param nsid: namespace identifier, XRP_NAMESPACE_ID_SIZE bytes long
  475. * \param handler: pointer to the handler function
  476. * \param handler_context: first argument that will be passed to the handler
  477. * function
  478. * \param[out] status: operation status
  479. */
  480. void xrp_device_register_namespace(struct xrp_device *device,
  481. const void *nsid,
  482. xrp_command_handler *handler,
  483. void *handler_context,
  484. enum xrp_status *status);
  485. /*!
  486. * Unregister namespace handler.
  487. *
  488. * Only registered namespace handler may be unregistered.
  489. *
  490. * \param device: device for which namespace handler is registered
  491. * \param nsid: namespace identifier, XRP_NAMESPACE_ID_SIZE bytes long
  492. * \param[out] status: operation status
  493. */
  494. void xrp_device_unregister_namespace(struct xrp_device *device,
  495. const void *nsid,
  496. enum xrp_status *status);
  497. /*!
  498. * Enable or disable shared memory cache management.
  499. * Note that this call does not change memory caching attributes, it only
  500. * enables flushing and invalidating used regions of shared memory in the
  501. * XRP code.
  502. *
  503. * \param device: device for which shared memory cache management state is
  504. * changed
  505. * \param enable: whether cache management shall be enabled (non-zero) or
  506. * disabled (0)
  507. */
  508. void xrp_device_enable_cache(struct xrp_device *device, int enable);
  509. /*!
  510. * @}
  511. */
  512. /*!
  513. * Helper function that terminates fast simulation.
  514. */
  515. void xrp_exit(void);
  516. /*!
  517. * Check if there's a handshake command from the host in the hardware queue and invoke
  518. * command handler if there's one.
  519. * Returns XRP_STATUS_PENDING if the queue is empty, or the status XRP_STATUS_FAILURE if command is not expected
  520. */
  521. enum xrp_status xrp_device_sync(struct xrp_device *device);
  522. enum xrp_status xrp_device_command_dispatch(struct xrp_device *device);
  523. enum xrp_status xrp_get_report_buffer(struct xrp_device *device,void** buffer,void*buffer_size);
  524. enum xrp_status xrp_send_report(struct xrp_device *device,uint32_t id);
  525. enum xrp_status xrp_get_report_status(struct xrp_device *device);
  526. int xrp_get_irq();
  527. void xrp_interrupt_on();
  528. void xrp_interrupt_off();
  529. void xrp_user_initialize(enum xrp_status *status);
  530. enum xrp_status xrp_device_init_done(struct xrp_device *device);
  531. #ifdef __cplusplus
  532. }
  533. #endif
  534. #endif