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

docs/next/_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/next/_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/next/_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
 =========================
 

docs/next/_sources/getting_started/toolchain.rst.txt

@@ -863,7 +863,9 @@ Windows (2022)
 --------------
 
 
-From an elevated command-prompt, then invoke the batch-script::
+Install the required toolchain and libraries, with sufficient system privileges
+(e.g. as eleveted command prompt), by executing the commands below. You can
+run this on administrator command prompt of the **xNVMe** by invoking::
 
   call xnvme\toolbox\pkgs\windows-2022.bat
 
@@ -874,9 +876,9 @@ Or, run the commands contained within the script manually:
 
 
 
-Then go ahead and configure, build and install using ``meson``:
+Then go ahead and configure, build and install using helper batch script ``build.bat``:
 
-.. literalinclude:: ../../toolbox/pkgs/default-build.sh
+.. literalinclude:: build_windows.rst
    :language: bash
    :lines: 2-
 
@@ -896,20 +898,22 @@ Windows (2019)
 --------------
 
 
-From an elevated command-prompt, then invoke the batch-script::
+Install the required toolchain and libraries, with sufficient system privileges
+(e.g. as eleveted privileges command prompt), by executing the commands below. You can
+run this on administrator command prompt of the **xNVMe** by invoking::
 
-  call xnvme\toolbox\pkgs\windows-2019.bat
+  call xnvme\toolbox\pkgs\windows-2022.bat
 
 Or, run the commands contained within the script manually:
 
-.. literalinclude:: ../../toolbox/pkgs/windows-2019.bat
+.. literalinclude:: ../../toolbox/pkgs/windows-2022.bat
    :language: batch
 
 
 
-Then go ahead and configure, build and install using ``meson``:
+Then go ahead and configure, build and install using helper batch script ``build.bat``:
 
-.. literalinclude:: ../../toolbox/pkgs/default-build.sh
+.. literalinclude:: build_windows.rst
    :language: bash
    :lines: 2-
 

docs/next/_sources/tools/xnvme/enum/index.rst.txt

@@ -0,0 +1,10 @@
+enum: enumerate devices
+=======================
+
+Enumerate devices, that is, controllers and namespaces available to the system:
+
+.. literalinclude:: xnvme_enum_usage.cmd
+   :language: bash
+
+.. literalinclude:: xnvme_enum_usage.out
+   :language: bash

docs/next/_sources/tools/xnvme/feature-get/index.rst.txt

@@ -0,0 +1,10 @@
+feature-get: Device feature
+===========================
+
+Execute a Get Features Command:
+
+.. literalinclude:: xnvme_feature_get_usage.cmd
+   :language: bash
+
+.. literalinclude:: xnvme_feature_get_usage.out
+   :language: bash

docs/next/_sources/tools/xnvme/feature-set/index.rst.txt

@@ -0,0 +1,10 @@
+feature-set: Device feature
+===========================
+
+Execute a Set-Features Command:
+
+.. literalinclude:: xnvme_feature_set_usage.cmd
+   :language: bash
+
+.. literalinclude:: xnvme_feature_set_usage.out
+   :language: bash

docs/next/_sources/tools/xnvme/format/index.rst.txt

@@ -0,0 +1,8 @@
+format: Format a NVM namespace
+==============================
+
+.. literalinclude:: xnvme_format_usage.cmd
+   :language: bash
+
+.. literalinclude:: xnvme_format_usage.out
+   :language: bash

docs/next/_sources/tools/xnvme/idfy-ctrlr/index.rst.txt

@@ -0,0 +1,10 @@
+idfy-ctrlr: Controller Identification
+=====================================
+
+Controller identification:
+
+.. literalinclude:: xnvme_idfy_ctrlr_usage.cmd
+   :language: bash
+
+.. literalinclude:: xnvme_idfy_ctrlr_usage.out
+   :language: bash

docs/next/_sources/tools/xnvme/idfy-ns/index.rst.txt

@@ -0,0 +1,11 @@
+idfy-ns: Namespace Identification
+=================================
+
+Namespace identification:
+
+.. literalinclude:: xnvme_idfy_ns_usage.cmd
+   :language: bash
+
+.. literalinclude:: xnvme_idfy_ns_usage.out
+   :language: bash
+

docs/next/_sources/tools/xnvme/idfy/index.rst.txt

@@ -0,0 +1,10 @@
+idfy: User-defined Identification
+=================================
+
+User-defined identification:
+
+.. literalinclude:: xnvme_idfy_usage.cmd
+   :language: bash
+
+.. literalinclude:: xnvme_idfy_usage.out
+   :language: bash

docs/next/_sources/tools/xnvme/index.rst.txt

@@ -6,101 +6,22 @@ xnvme
 .. literalinclude:: xnvme_usage.out
    :language: bash
 
-Enumerate devices
-=================
-
-Enumerate devices, that is, controllers and namespaces available to the system:
-
-.. literalinclude:: xnvme_enum_usage.cmd
-   :language: bash
-
-.. literalinclude:: xnvme_enum_usage.out
-   :language: bash
-
-Device Information
-==================
-
-Device information:
-
-.. literalinclude:: xnvme_info_usage.cmd
-   :language: bash
-
-.. literalinclude:: xnvme_info_usage.out
-   :language: bash
-
-Controller Identification
-=========================
-
-Controller identification:
-
-.. literalinclude:: xnvme_idfy_ctrlr_usage.cmd
-   :language: bash
-
-.. literalinclude:: xnvme_idfy_ctrlr_usage.out
-   :language: bash
-
-Namespace Identification
-========================
-
-Namespace identification:
-
-.. literalinclude:: xnvme_idfy_ns_usage.cmd
-   :language: bash
-
-.. literalinclude:: xnvme_idfy_ns_usage.out
-   :language: bash
-
-User-defined Identification
-===========================
-
-User-defined identification:
-
-.. literalinclude:: xnvme_idfy_usage.cmd
-   :language: bash
-
-.. literalinclude:: xnvme_idfy_usage.out
-   :language: bash
-
-logs: Error-Information
-=======================
-
-Retrieving the error-information log:
-
-.. literalinclude:: xnvme_log_erri_usage.cmd
-   :language: bash
-
-.. literalinclude:: xnvme_log_erri_usage.out
-   :language: bash
-
-logs: Health-Information
-========================
-
-Retrieving the S.M.A.R.T. / health information log:
-
-.. literalinclude:: xnvme_log_health_usage.cmd
-   :language: bash
-
-.. literalinclude:: xnvme_log_health_usage.out
-   :language: bash
-
-logs: User-Defined Log
-======================
-
-Retrieve a log as defined by you:
-
-.. literalinclude:: xnvme_log_usage.cmd
-   :language: bash
-
-.. literalinclude:: xnvme_log_usage.out
-   :language: bash
-
-Library Information
-===================
-
-Retrieve information about the library which ``xnvme`` is linked with:
-
-.. literalinclude:: xnvme_library_info.cmd
-   :language: bash
-
-.. literalinclude:: xnvme_library_info.out
-   :language: bash
+Subcommands
+===========
+
+.. toctree::
+
+   enum/index
+   feature-get/index
+   feature-set/index
+   format/index
+   idfy-ctrlr/index
+   idfy-ns/index
+   idfy/index
+   info/index
+   log-erri/index
+   log-health/index
+   log/index
+   padc/index
+   pioc/index
+   sanitize/index