************************************************************
************************************************************
*
*  Command Line Utility Readme.
*
*  This document makes references to products developed by
*  Intel. There are some restrictions on how these products
*  may be used, and what information may be disclosed to
*  others. Please read the Disclaimer section at the bottom
*  of this document, and contact your Intel field
*  representative if you would like more information.
*
************************************************************
************************************************************

************************************************************
*  
*  Intel is making no claims of usability, efficacy or 
*  warranty. The INTEL SOFTWARE LICENSE AGREEMENT contained
*  herein completely defines the license and use of this
*  software.
*
************************************************************

************************************************************
*  CONTENTS OF THIS DOCUMENT
************************************************************

This document contains the following sections:

1.  OVERVIEW
2.  SYSTEM REQUIREMENTS
3.  ENTERING THE COMMAND LINE UTILITY USER INTERFACE
4.  COMMAND LINE UTILITY USAGE
5.  COMMAND LINE RETURN CODES
6.  USAGE SCENARIOS EXAMPLES


************************************************************
* 1.  OVERVIEW
************************************************************

Intel(R) Rapid Storage Technology (Intel(R) RST) CLI "Pro" is 
a command line utility used to perform basic operations
on Intel(R) Optane(TM) memory-enabled systems.

Intel(R) RST CLI "Pro" supports the following functionality :
  - Enabling and disabling Intel(R) Optane(TM) memory acceleration
  - Viewing properties of disks and the Intel(R) Optane(TM) memory volume
  - Resetting Intel(R) Optane(TM) volume metadata

************************************************************
* 2.  SYSTEM REQUIREMENTS
************************************************************

Refer to Intel(R) Rapid Storage Technology product system
requirements.

**IMPORTANT NOTES**
The rstclipro binaries should be unzipped to a secured folder
to prevent unauthorized users from making unintended changes to
the system's Optane(TM) volume.


************************************************************
* 3.  ENTERING THE COMMAND LINE UTILITY USER INTERFACE
************************************************************

Use the following steps to enter command line utility:
1.  Boot the system to Windows. 
2.  Open command prompt as administrator.
3.  Run rstclipro.exe with appropriate command line parameters.


************************************************************
* 4.  COMMAND LINE UTILITY USAGE
************************************************************

   Information Options:
   ------------------------
   | Flag | Name          |
   ------------------------
   | -I   | --information |
   ------------------------

   Information Usage:
   Displays disk, volume, array, and controller information.
    --information

   Information Examples:
    --information
    --information --help
    -I


   Manage Options:
   --------------------------------
   | Flag | Name                  |
   --------------------------------
   | -Z   | --delete-all-metadata |
   | -M   | --manage              |
   --------------------------------

   Manage Usage:
   Manages arrays, volumes and disks present in the storage system.
    --manage --delete-all-metadata

   Manage Examples:
    --manage --delete-all-metadata
    -M -Z


   OptaneMemory Options:
   ---------------------------
   | Flag | Name             |
   ---------------------------
   |      | --OptaneMemory   |
   |      | --disable        |
   |      | --drive-to-accel |
   |      | --enable         |
   |      | --progress       |
   |      | --info           |
   |      | --fast-drive     |
   ---------------------------

   OptaneMemory Usage:
   Manage Optane Memory configuration.
    --OptaneMemory --enable [--fast-drive <driveId> --drive-to-accel <driveId>]
    --OptaneMemory --disable
    --OptaneMemory --progress
    --OptaneMemory --info

   OptaneMemory Examples:
    --OptaneMemory --enable
    --OptaneMemory --enable --fast-drive 0-3-0-0 --drive-to-accel 0-5-0-0
    --OptaneMemory --disable
    --OptaneMemory --help
    --OptaneMemory --info


   Version Options:
   --------------------
   | Flag | Name      |
   --------------------
   | -V   | --version |
   --------------------

   Version Usage:
   Displays version information.
    --version

   Version Examples:
    --version


OPTIONS:

   --disable
     Separate Optane Memory into Optane drive and capacity drive.

   --drive-to-accel <<host>-<bus>-<target>-<lun>>
     Specifies a drive if accelerating a pass-through drive.

   --enable
     Create Optane Memory

   --fast-drive <<host>-<bus>-<target>-<lun>>
     Specifies fast drive that will be used as cache/accelerator. If another 
     fast is being used as cache, then that volume needs to be deleted to use 
     a new fast drive.

   -h,  --help
     Displays help documentation for command line utility modes, options, 
     usage, examples, and return codes. When used with a mode switch (create, 
     information, mange, modify, or accelerate), instructions for that mode 
     display. For example, --create --help displays Create option help.

   -I,  --information
     Displays disk, volume, array, and controller information.

   --info
     Lists information about Optane Memory settings.

   -M,  --manage
     Manages arrays, volumes and disks present in the storage system.

   --OptaneMemory
     Manage Optane Memory configuration.

   --progress
     Displays the progress of file cache migration.

   -V,  --version
     Displays version information.

   -Z,  --delete-all-metadata
     Deletes the metadata from all disks on the system.

************************************************************
* 5.  COMMAND LINE RETURN CODES
************************************************************


   0,  Success 
    Request completed successfully. 

   1,  Request Failed 
    Request is formatted correctly but failed to execute. 

   2,  Invalid Request
    Unrecognized command, request was formatted incorrectly. 

   3,  Invalid Device
    Request not formatted correctly, device passed in does not exist. 

   4,  Request Unsupported
    Request is not supported with the current configuration. 

   5,  Device State Invalid
    Request is not supported with the current device state.
 
************************************************************
* 6.  USAGE SCENARIOS EXAMPLES
************************************************************
The following are examples of how to use RSTCLI Pro tool to manage
Intel(R) Optane(TM) Memory volume in a system.

************************************************************
* 6.1  Usage Scenario #1
************************************************************
Description:
    The end user wants to enable Intel(R) Optane(TM) Memory volume in a Windows 10 OS system

Prerequisite:
    - Intel(R) Optane(TM) Memory M10 installed in supported M.2 NVME slot.
    - BIOS Settings:
        - SATA Mode is set to "RAID / Intel RST Premium".
        - Intel(R) Optane(TM) Memory M10 M.2 NVME slot is set to "RST Controlled".
        - (Optional) If the OS is installed on Intel(R) SSD 660p that is attached to an NVME M.2 slot,
            Then the NVME M.2 slot should also be set to "RST Controlled" if this option is availble.
    - Windows 10 x64 OS RS5 or later installed on SATA SSD/HDD drive or Intel(R) SSD 660p NVME drive.
    - Intel(R) RST driver version 17.7.x or later installed.

Procedure:
    1.    Launch CMD windows as Administrator.
    2.    Change the working directory to the directory where RSTCLI Pro executable (RstCliPro.exe) is or 
        make sure the path to the RSTCLIPro executable is added in system path.
    3.    (Optional) Check for the version of the Intel(R) RST driver currently installed.
        Command:
            RstCliPro.exe --version
        Example Output:
            Intel(R) RSTCLI
            Middleware Version: 17.7.0.1000
            Controller Intel(R) Chipset SATA/PCIe RST Premium Controller \\Scsi0 Driver Version: 17.7.0.1000
            Controller Intel(R) Chipset SATA/PCIe RST Premium Controller \\Scsi0 OROM Version: 15.7.0.3054
        Note:
            - Intel(R) RST driver and middleware version must match.
            - Intel(R) RST driver must be 17.7.0.1000 or later for the RSTCLI Pro to work.
            
    3.    Find the ID for the SATA SSD/HDD drive where the OS installed and the ID of the Intel(R) Optane(TM) Memory M10.
        Command: 
            RstCliPro.exe -I
        Below is the example output of the above command:
            ID:                              0-0-0-0
            Type:                            Disk
            Disk Type:                       SATA Disk
            Disk Link Speed:                 6 Gb/s
            State:                           Normal
            ...
            System Disk:                     True
            ...
            Usage:                           Pass through
            ...
        
            ID:                              0-3-0-0
            Type:                            Disk
            Disk Type:                       PCIE SSD
            Port Interface:                  NVMe
            Bus Width:                       X2
            Bus Speed:                       GEN3
            Host Memory Buffer supported:    No
            State:                           Normal
            ...
            System Disk:                     False
            ...
            Usage:                           Pass through
            ...
            Model:                           INTEL SSDPEK1W120GA
        
        Note:
            - The example output shows only some relavant information. Omitted information is replaced with (...)
            - Intel(R) Optane(TM) Memory M10 is referred to as "fast drive"
            - SATA SSD/HDD or Intel(R) SSD 660p NVME is referred to as "slow drive"     
            
    4.    (Optional) Delete any Intel RST metadata on fast drive and slow drive to ensure that enabling process 
        starts from a fresh point.
        Command:
            RstCliPro.exe --manage --delete-all-metadata
                or
            RstCliPro.exe -M -Z

    5.    Enable Optane Volume with the ID information found in previous command.
        Command:
            RstCliPro.exe --OptaneMemory --enable --fast-drive 0-3-0-0 --drive-to-accel 0-0-0-0
        Note:         
            - The command will take some time to complete. It should block the process until enabling process is completed.
            - If the Optane Volume is already enabled, the operation will return a non Zero code.
            
    6.    (Optional) Check for return code. Refer to section above for Return Code information
    7.    Reboot/Restart (not shutdown) the system to complete the enabling process

************************************************************
* 6.2  Usage Scenario #2
************************************************************
Description:
    The end user wants to enable Intel(R) Optane(TM) Memory volume on a system and deploy a pre-configured (IT configured) Windows 10 OS image 
    to the system's Intel Optane Memory Volume in Windows Preinstallation Environment (WinPE).
    
Prerequisite:
    - Intel(R) Optane(TM) Memory M10 installed in supported M.2 NVME slot.
    - SATA SSD/HDD connected to SATA Port or Intel(R) SSD 660p that is attached to an NVME M.2 slot.
    - BIOS Settings:
        - SATA Mode is set to "RAID / Intel RST Premium".
        - Intel(R) Optane(TM) Memory M10 M.2 NVME slot is set to "RST Controlled".
        - (Optional) If the OS is installed to Intel(R) SSD 660p that is attached to an NVME M.2 slot,
            Then the NVME M.2 slot should also be set to "RST Controlled" if this option is availble.
    - IMPORTANT information regarding installation media:
        - WinPE USB drive that has Intel(R) RST driver version 17.7.x or later injected into "boot.wim" file.
        Refer https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/winpe-mount-and-customize
        for help on how to add Intel(R) RST driver to WinPE.
        - Intel RSTCLI Pro executable is placed on the same customized WinPE USB drive.
    - Deployed Windows OS Image must already has Intel(R) RST driver version 17.7.x or later integrated into it. 

Procedure:
    1.    Boot the system into the customized (with injected Intel RST driver) WinPE.
    2.    Use "diskpart" to create the required Windows OS partition on the SATA SSD/HDD or Intel(R) SSD 660p where the Windows OS image will be deployed.
    3.    Deploy the Windows OS Image that already has Intel(R) RST driver version 17.7.x or later integrated into it; onto the SATA SSD/HDD or Intel(R) SSD 660p.
    4.    Change the working directory to the drive and directory where RSTCLI Pro executable (RstCliPro.exe) is.
    5.    Find the ID for the SATA SSD/HDD or Intel(R) SSD 660p and the ID of the Intel(R) Optane(TM) Memory M10.
        Command: 
            RstCliPro.exe -I
        Below is the example output of the above command:
            ID:                              0-0-0-0
            Type:                            Disk
            Disk Type:                       SATA Disk
            Disk Link Speed:                 6 Gb/s
            State:                           Normal
            ...
            System Disk:                     True
            ...
            Usage:                           Pass through
            ...
            
            ID:                              0-3-0-0
            Type:                            Disk
            Disk Type:                       PCIE SSD
            Port Interface:                  NVMe
            Bus Width:                       X2
            Bus Speed:                       GEN3
            Host Memory Buffer supported:    No
            State:                           Normal
            ...
            System Disk:                     False
            ...
            Usage:                           Pass through
            ...
            Model:                           INTEL SSDPEK1W120GA
        
        Note:
            - The example output shows only some relavant information. Omitted information is replaced with (...)
            - Intel(R) Optane(TM) Memory M10 is referred to as "fast drive"
            - SATA SSD/HDD or Intel(R) SSD 660p NVME is referred to as "slow drive"     
            
    6.    Enable Optane Volume with the ID information found in previous command.
        Command:
            RstCliPro.exe --OptaneMemory --enable --fast-drive 0-3-0-0 --drive-to-accel 0-0-0-0
        Note:         
            - The command will take some time to complete. It should block the process until enabling process is completed.
            
    7.    (Optional) Check for return code. Refer to section above for Return Code information
    8.    Reboot/Restart (not shutdown) the system to complete the process.

************************************************************
* 6.3  Usage Scenario #3
************************************************************
Description:
    The end user wants to upgrade SATA SSD/HDD or Intel(R) SSD 660p NVME that is a part of an Intel Optane Memory volume 
    on the current system to a higher capacity one.

Prerequisite:
    - Assume that the system has already met all the HW and BIOS requirements for Intel(R) Optane(TM) Memory volume to be enabled in the first place.
    - Windows 10 x64 OS RS5 or later installed on SATA SSD/HDD drive or Intel(R) SSD 660p NVME drive.
    - Intel(R) RST driver version 17.7.x or later installed.
    
Procedure:
    1.    Back up all the data.
    2.    Disable Intel(R) Optane(TM) Memory volume.
        Command:
            RstCliPro.exe --OptaneMemory --disable
        Note:
            - The command will take some time to complete. It should block the process until enabling process is completed.
    3.    Reboot/Restart (not shutdown) the system to complete disabling process.
    4.    Use cloning software to clone the image on the SATA SSD/HDD or Intel(R) SSD 660p NVME drive to a bigger drive.
        Please note that for NVME SSD, only Intel(R) SSD 660p NVME is supported.
    5.    Start the system with the new drive.
    6.    Follow the steps in section 6.1 to enable Intel(R) Optane(TM) Memory volume again.
    
************************************************************
* 6.4  Usage Scenario #4
************************************************************
Description:
    The end user wants to enable Intel® Optane™ Memory volume on a system, equipped with Intel® Optane™ Memory H10 with Solid State Drive,
    and deploy a pre-configured (IT configured) Windows 10 OS image to the system's Intel Optane Memory Volume in Windows Preinstallation Environment (WinPE).
    
Prerequisite:
    - Intel® Optane™ Memory H10 installed in supported M.2 NVME slot.
    - BIOS Settings:
        - SATA Mode is set to "RAID / Intel RST Premium".
        - Intel® Optane™ Memory H10's M.2 NVME slot is set to "Not RST Controlled".
    - IMPORTANT information regarding installation media:
        - WinPE USB drive that has Intel® RST driver version 17.7.x or later injected into "boot.wim" file.
        Refer https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/winpe-mount-and-customize
        for help on how to add Intel® RST driver to WinPE.
        - Intel RSTCLI Pro executable is placed on the same customized WinPE USB drive.
    - Deployed Windows OS Image must already has Intel® RST driver version 17.7.x or later integrated into it. 

Procedure:
    1.    Boot the system into the customized (with injected Intel RST driver) WinPE.
    2.    Use "diskpart" to create the required Windows OS partition on the Intel® Optane™ Memory H10's QLC NAND device where the Windows OS image will be deployed.
            Below example is diskpart output of a 256GB/1TB Intel® Optane™ Memory H10 device. The OS is installed on Disk 1.
      =====
            Microsoft DiskPart version 10.0.17763.1

            Copyright (C) Microsoft Corporation.
            On computer: MININT-F9FTMHO

              Disk ###  Status         Size     Free     Dyn  Gpt
              --------  -------------  -------  -------  ---  ---
              Disk 0    Online           27 GB    27 GB         
              Disk 1    Online          953 GB   715 GB        *
              Disk 2    Online           14 GB      0 B        *
      =====
    3.    Deploy the Windows OS Image that already has Intel® RST driver version 17.7.x or later integrated into it; onto the .
    4.    Change the working directory to the drive and directory where RSTCLI Pro executable (RstCliPro.exe) is.
    5.    Find the ID for the SATA SSD/HDD or Intel® SSD 660p and the ID of the Intel® Optane™ Memory M10.
        Command: 
            RstCliPro.exe -I
        Below is the example output of the above command:
            ID:                              0-13-0-0
            Type:                            Disk
            Disk Type:                       PCIE SSD
            Port Interface:                  NVMe
            Bus Width:                       X2
            Bus Speed:                       GEN3
            ...
            State:                           Normal
            Size:                            27 GB
            Space available for new volumes: 27 GB
            ...
            Model:                           INTEL HBRPEKNX0203AO                    

            ID:                              0-14-0-0
            Type:                            Disk
            Disk Type:                       PCIE SSD
            Port Interface:                  NVMe
            Bus Width:                       X2
            Bus Speed:                       GEN3
            ...
            State:                           Normal
            Size:                            954 GB
            Space available for new volumes: 954 GB
            ...
            Usage:                           Pass through
            Model:                           INTEL HBRPEKNX0203A                     
        
        Note:
            - The example output shows only some relavant information. Omitted information is replaced with (...)
            - Intel® Optane™ Memory H10's Optane device is referred to as "fast drive"
            - Intel® Optane™ Memory H10's QLC NAND device is referred to as "slow drive"
            
    6.    Enable Optane Volume with the ID information found in previous command.
        Command:
            RstCliPro.exe --OptaneMemory --enable --fast-drive 0-13-0-0 --drive-to-accel 0-14-0-0
        Note:         
            - The command will take some time to complete. It should block the process until enabling process is completed.
            
    7.    (Optional) Check for return code. Refer to section above for Return Code information
    8.    Reboot/Restart (not shutdown) the system to complete the process.


************************************************************
* Boost Software License - Version 1.0 - August 17th, 2003
************************************************************

Permission is hereby granted, free of charge, to any person or organization
obtaining a copy of the software and accompanying documentation covered by
this license (the "Software") to use, reproduce, display, distribute,
execute, and transmit the Software, and to prepare derivative works of the
Software, and to permit third-parties to whom the Software is furnished to
do so, all subject to the following:

The copyright notices in the Software and this entire statement, including
the above license grant, this restriction and the following disclaimer,
must be included in all copies of the Software, in whole or in part, and
all derivative works of the Software, unless such copies or derivative
works are solely in the form of machine-executable object code generated by
a source language processor.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.


************************************************************
* DISCLAIMER
************************************************************

INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL PRODUCTS.
NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY
INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS
PROVIDED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, INTEL
ASSUMES NO LIABILITY WHATSOEVER AND INTEL DISCLAIMS ANY EXPRESS OR IMPLIED
WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY
OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE,
MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER
INTELLECTUAL PROPERTY RIGHT.

UNLESS OTHERWISE AGREED IN WRITING BY INTEL, THE INTEL PRODUCTS ARE NOT 
DESIGNED NOR INTENDED FOR ANY APPLICATION IN WHICH THE FAILURE OF THE INTEL
PRODUCT COULD CREATE A SITUATION WHERE PERSONAL INJURY OR DEATH MAY OCCUR.

Intel may make changes to specifications and product descriptions at any
time, without notice. Designers must not rely on the absence or 
characteristics of any features or instructions marked "reserved" or "undefined". 
Intel reserves these for future definition and shall have no
responsibility whatsoever for conflicts or incompatibilities arising from 
future changes to them. The information here is subject to change without 
notice. Do not finalize a design with this information.

The products described in this document may contain design defects or
errors known as errata which may cause the product to deviate from 
published specifications. Current characterized errata are available on 
request.

Contact your local Intel sales office or your distributor to obtain the 
latest specifications and before placing your product order.

Copies of documents which have an order number and are referenced in this
document, or other Intel literature, may be obtained by calling 
1-800-548-4725, or go to: http://www.intel.com/#/en_us_01

Intel(R) is a trademark of Intel Corporation in the U.S. and other 
countries.

* Other names and brands may be claimed as the property of others
        
Copyright (C), Intel Corporation. All rights reserved.
************************************************************
* INTEL SOFTWARE LICENSE AGREEMENT
************************************************************
