Queues

Queues are resources, but only the ASQ, ACQ, IOSQ and IOCQ classes are meant to be instantiated by tests. A queue resource residing within tnvme represents the corresponding physical entity residing within dnvme. However, tnvme has complete control over those resources. For SQ’s tnvme controls what, and when commands are placed within it and when its doorbell is rung. For CQ’s, tnvme controls when and if items are reaped from CQ’s, and how many elements to reap per reap request. It is important to understand that dnvme will never do anything to any queue unless specifically told to by tnvme. The interaction between tnvme and dnvme occurs via IOCTL’s, but these details are obscured from a test developer on purpose.

The framework provides queue classes for tests to instantiate and initialize. A test can interact with a queue resource at its leisure. A test simply calls the public methods of the class hierarchy to control those resources. A common scenario might be for a test to request that the gRsrcMngr allocate an object and then typecast the resulting object into the appropriate shared_ptr. A good place to seek for examples is to peruse the source code files within directory tnvme/GrpBasicInit. After a queue object is born it must be initialized for it to be useful. Simply call one of the objects public Init() methods. During initialization is where tnvme notifies dnvme what type of memory is to back this resource.

Backing a queue resource with memory requires a test to call the appropriate public Init() method of that resource. There are currently 2 methods and they allow backing using discontiguous and contiguous memory. Discontiguous memory backing requires tnvme to allocate a MemBuffer resource and specify the alignment requirements in the process. Contiguous memory backing is only possible by authorizing dnvme to allocate it on tnvme’s behalf and mmap that memory back to user space as r/w memory. Thus no matter what type of memory is backing a queue resource, tnvme has the ability to peek into it.

After a queue resource has been initialized it can be used immediately if it is an ASQ or ACQ. Of course the controller must first be enabled. However, if the queue object is an IOQ type, then first an admin command must be sent to the DUT to allow the 2nd half of creation to commence. If the creation command succeeds tnvme may use it to issue commands into it.