diff options
author | John Levon <john.levon@nutanix.com> | 2021-08-18 10:13:02 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-08-18 10:13:02 +0100 |
commit | 1f563795ec22e758888c73396e0e187d0557a55d (patch) | |
tree | e6c6f4a6d2e10e5063992b783002ebc93d0bead1 | |
parent | 46ed1dbd8e692ee53a544022dd70151f21a4e725 (diff) | |
download | libvfio-user-1f563795ec22e758888c73396e0e187d0557a55d.zip libvfio-user-1f563795ec22e758888c73396e0e187d0557a55d.tar.gz libvfio-user-1f563795ec22e758888c73396e0e187d0557a55d.tar.bz2 |
improve API docs a little bit (#587)
Clarify a couple of minor things in the API documentation and README.
Signed-off-by: John Levon <john.levon@nutanix.com>
Reviewed-by: Swapnil Ingle <swapnil.ingle@nutanix.com>
-rw-r--r-- | README.md | 19 | ||||
-rw-r--r-- | include/libvfio-user.h | 11 |
2 files changed, 20 insertions, 10 deletions
@@ -30,14 +30,17 @@ Applications using libvfio-user provide a description of the device (eg. region IRQ information) and as set of callbacks which are invoked by `libvfio-user` when those regions are accessed. -Currently there is one, single-threaded, application instance per device, -however the application can employ any form of concurrency needed. In the future -we plan to make libvfio-user multi-threaded. - -The library (and the protocol) are actively under development, and should not be -considered a stable API or interface. Work is underway to integrate the protocol -with `qemu` (as a client) and [SPDK](https://spdk.io) (on the server side, -implementing a virtual NVMe controller). +API +=== + +Currently there is one, single-threaded, library context per device, however the +application can employ any form of concurrency needed. In the future we plan to +make libvfio-user multi-thread safe. + +The library (and the protocol) are actively under development, and should not +yet be considered a stable API or interface. + +The API is currently documented via the [libvfio-user header file](./include/libvfio-user.h). Memory Mapping the Device ------------------------- diff --git a/include/libvfio-user.h b/include/libvfio-user.h index 5e379df..148d76e 100644 --- a/include/libvfio-user.h +++ b/include/libvfio-user.h @@ -33,6 +33,10 @@ /* * Defines the libvfio-user server-side API. The protocol definitions can be * found in vfio-user.h. + * + * This is not currently a stable API or ABI, and may change at any time. + * Library calls are not guaranteed thread-safe: multi-threaded consumers need + * to protect calls with their own exclusion methods. */ #ifndef LIB_VFIO_USER_H @@ -130,8 +134,11 @@ int vfu_attach_ctx(vfu_ctx_t *vfu_ctx); /** - * Return a file descriptor suitable for waiting on via epoll() or similar. This - * should not be cached, as it may change after a successful vfu_attach_ctx(). + * Return a file descriptor suitable for waiting on via epoll() or similar. The + * file descriptor may change after a successful vfu_attach_ctx(), or on + * receiving ENOTCONN error message from vfu_run_ctx(); in those cases, + * vfu_get_poll_fd() should be called again to get the current correct file + * descriptor. */ int vfu_get_poll_fd(vfu_ctx_t *vfu_ctx); |