Skip to content

Commit

Permalink
Auto-deployed update of 'docs/' for 'refs/heads/next'
Browse files Browse the repository at this point in the history
  • Loading branch information
ghs-safl committed Aug 8, 2023
1 parent d0ea7bc commit 545d7d7
Show file tree
Hide file tree
Showing 76 changed files with 3,644 additions and 701 deletions.
Binary file modified docs/next/.doctrees/backends/xnvme_be_windows.doctree
Binary file not shown.
Binary file modified docs/next/.doctrees/capis/xnvme_kvs.doctree
Binary file not shown.
Binary file modified docs/next/.doctrees/capis/xnvme_mem.doctree
Binary file not shown.
Binary file modified docs/next/.doctrees/capis/xnvme_spec.doctree
Binary file not shown.
Binary file modified docs/next/.doctrees/contributing/contributing-conventions.doctree
Binary file not shown.
Binary file modified docs/next/.doctrees/environment.pickle
Binary file not shown.
Binary file modified docs/next/.doctrees/getting_started/build_windows.doctree
Binary file not shown.
Binary file modified docs/next/.doctrees/getting_started/index.doctree
Binary file not shown.
Binary file modified docs/next/.doctrees/getting_started/toolchain.doctree
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file modified docs/next/.doctrees/tools/xnvme/index.doctree
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file added docs/next/.doctrees/tools/xnvme/log/index.doctree
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file modified docs/next/.doctrees/tutorial/devs/index.doctree
Binary file not shown.
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
13 changes: 11 additions & 2 deletions docs/next/_sources/getting_started/build_windows.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
118 changes: 118 additions & 0 deletions docs/next/_sources/getting_started/index.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
=========================

Expand Down
20 changes: 12 additions & 8 deletions docs/next/_sources/getting_started/toolchain.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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-

Expand All @@ -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-

Expand Down
10 changes: 10 additions & 0 deletions docs/next/_sources/tools/xnvme/enum/index.rst.txt
Original file line number Diff line number Diff line change
@@ -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
10 changes: 10 additions & 0 deletions docs/next/_sources/tools/xnvme/feature-get/index.rst.txt
Original file line number Diff line number Diff line change
@@ -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
10 changes: 10 additions & 0 deletions docs/next/_sources/tools/xnvme/feature-set/index.rst.txt
Original file line number Diff line number Diff line change
@@ -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
8 changes: 8 additions & 0 deletions docs/next/_sources/tools/xnvme/format/index.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
format: Format a NVM namespace
==============================

.. literalinclude:: xnvme_format_usage.cmd
:language: bash

.. literalinclude:: xnvme_format_usage.out
:language: bash
10 changes: 10 additions & 0 deletions docs/next/_sources/tools/xnvme/idfy-ctrlr/index.rst.txt
Original file line number Diff line number Diff line change
@@ -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
11 changes: 11 additions & 0 deletions docs/next/_sources/tools/xnvme/idfy-ns/index.rst.txt
Original file line number Diff line number Diff line change
@@ -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

10 changes: 10 additions & 0 deletions docs/next/_sources/tools/xnvme/idfy/index.rst.txt
Original file line number Diff line number Diff line change
@@ -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
117 changes: 19 additions & 98 deletions docs/next/_sources/tools/xnvme/index.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading

0 comments on commit 545d7d7

Please sign in to comment.