Auto-deployed update of 'docs/' for 'refs/heads/main'

docs/main/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: ee12bd602f239ef4622a4d83d7340888
+config: 816478dc43b72e366c21064ee198395e
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/main/_sources/contributing/contributing-conventions.rst.txt

@@ -74,7 +74,7 @@ C: API
 
   - The source-code for the command-line tools serve as examples of utilizing
     the C API in general and the tools are used during testing
-  - The command-line utilities must use the ``libxnvmec.h`` as this provides a
+  - The command-line utilities must use the ``libxnvme_cli.h`` as this provides a
     common command-line interface, the common-cli is nice as for usability,
     such that all cli-tools use the same arguments, it is also essential for
     instrumentation of not just the logic of the tool but also the library

docs/main/_sources/getting_started/build_windows.rst.txt

@@ -3,5 +3,14 @@
   # build: auto-configure xNVMe, build third-party libraries, and xNVMe itself
   build.bat
 
-  # In case you want to enable debugging then use the following instead
-  # build.bat debug
+  # config: only configure xNVMe
+  build.bat config
+
+  # config: debug only configure xNVMe
+  build.bat config-debug
+
+  # install xNVMe
+  build.bat install
+
+  # uninstall xNVMe
+  # build.bat uninstall

docs/main/_sources/getting_started/index.rst.txt

@@ -372,6 +372,124 @@ filepaths::
 
 .. _sec-building-example:
 
+Windows Kernel
+--------------
+
+Windows 10 or later version is currently preferred as it has all the features
+which **xNVMe** utilizes. This section also gives you a brief overview of the
+different I/O paths and APIs which the **xNVMe** API unifies access to.
+
+NVMe Driver and IOCTLs
+~~~~~~~~~~~~~~~~~~~~~~
+
+The default for **xNVMe** is to communicate with devices via the operating
+system NVMe driver IOCTLs, specifically on Windows the following are used:
+
+* ``IOCTL_STORAGE_QUERY_PROPERTY``
+* ``IOCTL_STORAGE_SET_PROPERTY``
+* ``IOCTL_STORAGE_REINITIALIZE_MEDIA``
+* ``IOCTL_SCSI_PASS_THROUGH_DIRECT``
+
+You can check that this interface is behaving as expected by running:
+
+.. literalinclude:: xnvme_win_info_default.cmd
+   :language: bash
+
+Which should yield output equivalent to:
+
+.. literalinclude:: xnvme_win_info_default.out
+   :language: bash
+   :lines: 1-12
+
+This tells you that **xNVMe** can communicate with the given device identifier
+and it informs you that it utilizes **nvme_ioctl** for synchronous command
+execution and it uses **iocp** for asynchronous command execution. This method
+can be used for raw devices via **\\.\PhysicalDrive<disk number>** device path.
+
+NVMe Driver and Regular File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**xNVMe** can communicate with File System mounted devices via the operating
+system generic APIs like **ReadFile** and **WriteFile** operations. This method
+can be used to do operation on Regular Files.
+
+You can check that this interface is behaving as expected by running:
+
+.. literalinclude:: xnvme_win_info_fs.cmd
+   :language: bash
+
+Which should yield output equivalent to:
+
+.. literalinclude:: xnvme_win_info_fs.out
+   :language: bash
+   :lines: 1-12
+
+This tells you that **xNVMe** can communicate with the given regular file
+and it informs you that it utilizes **nvme_ioctl** for synchronous command
+execution and it uses **iocp** for asynchronous command execution. This method
+can be used for file operations via **<driver name>:\<file name>** path.
+
+Async I/O via ``iocp``
+~~~~~~~~~~~~~~~~~~~~~~
+
+When AIO is available then the NVMe NVM Commands for **read** and **write** are
+sent over the Windows IOCP interface. Doing so improves command-throughput at
+higher queue-depths when compared to sending the command via the NVMe driver
+ioctl().
+
+One can explicitly tell **xNVMe** to utilize ``iocp`` for async I/O by
+encoding it in the device identifier, like so:
+
+.. literalinclude:: xnvme_win_io_async_read_iocp.cmd
+   :language: bash
+
+Yielding the output:
+
+.. literalinclude:: xnvme_win_io_async_read_iocp.out
+   :language: bash
+
+
+Async I/O via ``iocp_th``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Similar to ``iocp`` interface, only difference is separate poller is used to
+fetch the completed IOs.
+
+One can explicitly tell **xNVMe** to utilize ``iocp_th`` for async I/O by
+encoding it in the device identifier, like so:
+
+.. literalinclude:: xnvme_win_io_async_read_iocp_th.cmd
+   :language: bash
+
+Yielding the output:
+
+.. literalinclude:: xnvme_win_io_async_read_iocp_th.out
+   :language: bash
+
+Async I/O via ``io_ring``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**xNVMe** utilizes the Windows **io_ring** interface, its support for
+feature-probing the **io_ring** interface and the **io_ring** opcodes:
+
+When available, then **xNVMe** can send the **io_ring** specific request using
+**IORING_HANDLE_REF** and **IORING_BUFFER_REF** structure for **read** via the
+Windows **io_ring** interface. Doing so improves command-throughput at all
+io-depths when compared to sending the command via NVMe Driver IOCTLs.
+
+One can explicitly tell **xNVMe** to utilize ``io_ring`` for async I/O by
+encoding it in the device identifier, like so:
+
+.. literalinclude:: xnvme_win_io_async_read_io_ring.cmd
+   :language: bash
+
+Yielding the output:
+
+.. literalinclude:: xnvme_win_io_async_read_io_ring.out
+   :language: bash
+   :lines: 1-12
+
+
 Building an xNVMe Program
 =========================