struct OperationTraits

Usage notes:

nand::Operation is a c++ wrapper around the nand_operation_t object. It provides

capabilities to interact with a nand_op buffer which is used to traverse the

nand stack. On deletion, it will automatically free itself.

nand::BorrowedOperation provides an unowned variant of nand::Operation. It adds

functionality to store and call a complete callback which isn't present in

nand::Operation. In addition, it will call the completion on destruction if it

wasn't already triggered.

nand::OperationPool provides pooling functionality for nand::Operation reuse.

nand::OperationQueue provides a queue interface for tracking nand::Operation and

nand::BorrowedOperation objects.

Available methods for both Operation and BorrowedOperation include:

nand_operation_t* operation(); // accessor for inner type.

// Takes ownership of inner type. Should only be used when transferring

// ownership to another driver.

nand_operation_t* take();

Available to Operation and BorrowedOperation if they templatize of Storage:

Storage* private_storage(); // accessor for private storage.

Available to Operation:

void Release(); // Frees the inner type.

Available to BorrowedOperation:

void Complete(zx_status_t); // Completes the operation.

////////////////////////////////////////////////////////////////////////////

Example: Basic allocation with a pool:

nand::OperationPool

<

> pool;

const size_t op_size = nand::Operation

<

>::OperationSize(parent_op_size);

for (int i = 0; i

<

kNumRequest; i++) {

std::optional

<nand

::Operation> request;

request = nand::Operation::Alloc(op_size, parent_op_size);

if (!request) return ZX_ERR_NO_MEMORY;

pool.add(*std::move(request));

}

////////////////////////////////////////////////////////////////////////////

Example: Enqueue incoming operation into a nand::OperationQueue:

class Driver {

public:

<

...>

private:

nand::BorrowedOperationQueue

<

> operations_;

const size_t parent_op_size_;

};

void Driver::NandQueue(nand_operation_t* op, nand_queue_callback completion_cb, void* cookie) {

operations_.push(nand::BorrowedOperation

<

>(op, cb, parent_req_size_));

}

////////////////////////////////////////////////////////////////////////////

Example: Using private context only visible to your driver:

struct PrivateStorage {

bool valid;

size_t count_metric;

}

using NandOperation = nand::BorrowedOperation

<PrivateStorage

>;

void Driver::NandQueue(nand_operation_t* op, nand_queue_callback completion_cb, void* cookie) {

NandOperation nand_op(op, cb, parent_req_size_));

ZX_DEBUG_ASSERT(nand_op.operation()->command == NAND_ERASE);

nand_op.private_storage()->valid = true;

nand_op.private_storage()->count_metric += 1;

<

...>

}