5.1. OX Command Line (OX v1.4)

OX accepts arguments in the command line. Please run the OX binary in the DFC prompt or make a script to start it automatically after the kernel boots.

You can use the follow command to see all available arguments:

$ ox-ctrl --help

Available commands:
   start        Start controller with standard configuration
   debug        Start controller and print Admin/IO commands
   test         Start controller, run tests and close
   admin        Execute specific tasks within the controller

Start and Debug

Use ‘start’ to run the controller with standard settings:
$ ox-ctrl start

Use ‘debug’ to run the controller in debug mode (verbose):
$ ox-ctrl debug

When an I/O command is posted to the NVMe submission queue by the host, OX will print the information related to the I/O command flow in Figure 5. See a printed I/O debug example below:

[659] IO CMD 0x92, nsid: 1, cid: 0
 Number of sectors: 8
 DMA size: 32768 (data) + 0 (meta) = 32768 bytes
 [ppa(0): ch: 0, lun: 0, blk: 220, pl: 0, pg: 0, sec: 0]
 [ppa(1): ch: 0, lun: 0, blk: 220, pl: 0, pg: 0, sec: 1]
 [ppa(2): ch: 0, lun: 0, blk: 220, pl: 0, pg: 0, sec: 2]
 [ppa(3): ch: 0, lun: 0, blk: 220, pl: 0, pg: 0, sec: 3]
 [ppa(4): ch: 0, lun: 0, blk: 220, pl: 1, pg: 0, sec: 0]
 [ppa(5): ch: 0, lun: 0, blk: 220, pl: 1, pg: 0, sec: 1]
 [ppa(6): ch: 0, lun: 0, blk: 220, pl: 1, pg: 0, sec: 2]
 [ppa(7): ch: 0, lun: 0, blk: 220, pl: 1, pg: 0, sec: 3]
 [prp(0): 0x00000000961a3000
 [prp(1): 0x0000000096234000
 [prp(2): 0x0000000096235000
 [prp(3): 0x000000009ba23000
 [prp(4): 0x0000000096237000
 [prp(5): 0x0000000096238000
 [prp(6): 0x0000000096239000
 [prp(7): 0x000000009623a000
 [meta_prp(0): 0x0000000000000000
 CMD cid: 0, type: 0x1 submitted to FTL.
  Channel: 0, FTL queue 2
 [IO CALLBK. CMD 0x1. mmgr_ch: 0, lun: 0, blk: 220, pl: 0, pg: 0]
 [IO CALLBK. CMD 0x1. mmgr_ch: 0, lun: 0, blk: 220, pl: 1, pg: 0]
 [NVMe cmd 0x92. cid: 0 completed. Status: 0]

Admin

All commands related to configuration and storage administration are implemented under ‘admin’ argument. For now, only ‘erase-blk’ is implemented (LightNVM writes and reads the first page in the namespace, if the block is not erased properly, LightNVM will fail to initialize the device. If it happens, please erase the block 2 in the LUN 0 in channel 0. This process needs to be done only the first time you initialize the device with LightNVM). Use the follow commands to see all admin available arguments:

$ ox-ctrl-test admin --help

Use this command to run specific tasks within the controller.

Examples:
 Show all available Admin tasks:
  ox-ctrl admin -l
 Run a specific admin task:
  ox-ctrl admin -t <task_name>

$ ox-ctrl-test admin -l

Available OX Admin Tasks:
  - 'erase-blk': erase specific blocks.
   eg. ox-ctrl admin -t erase-blk (it will ask the block address)

  - 'erase-lun': erase specific LUNs.
   eg. ox-ctrl admin -t erase-lun (not implemented)

  - 'erase-ch': erase specific channels.
   eg. ox-ctrl admin -t erase-ch (not implemented)

Tests

OX tests are implemented in the ‘ox-ctrl-test’ binary. It will run a sequence of IO commands to test the Media Manager, LightNVM FTL and LightNVM command parser. To test the PCIe interconnect handler and NVMe queue support, please run tests from the host PC. Use the follow command to see all available test arguments:

$ ox-ctrl-test test --help

Examples:

 Show all available set of tests + subtests:
  ox-ctrl test -l

 Run all available tests:
  ox-ctrl test -a

 Run a specific test set:
  ox-ctrl test -s <set_name>

 Run a specific subtest:
  ox-ctrl test -s <set_name> -t <subtest_name>