[byrnedj]

This adds a public dto.h with an explicit submit/poll API, so applications can overlap DSA work with their own CPU work. It unifies the API work from the cachelib-navy and ch-async-ops development branches into one interface, and adds libdto_explicit: the same library without the libc interposers.

Single operations (dto_async_op, caller-allocated, can be polled from any thread):

• Data movement: dto_submit_memcpy, dto_submit_memset, dto_submit_memfill (8-byte pattern).
• CRC32C:
  • dto_submit_crc and dto_submit_memcpy_crc return the raw CRC32C: the SSE4.2 crc32 loop from 0, no final inversion.
  • dto_submit_crc32c and dto_submit_memcpy_crc32c take a seed in the iSCSI presentation: seed 0 gives standard CRC32C, and passing a previous result chains.
  • dto_crc32c_with_seed is a synchronous call that always returns the right value, using the CPU below DTO_CRC_MIN_BYTES.
• Compare: dto_submit_compare, dto_submit_compval (against an 8-byte pattern).
• Translation fetch: dto_submit_transl_fetch (DSA 2.0).
• Completion: dto_async_poll; dto_async_wait, which waits with DTO_WAIT_METHOD and is a no-op for ops that were never submitted; and the accessors (crc_val, crc32c_val, result, bytes_completed, status).

Batches (dto_batch, up to 1024 operations in one DSA batch descriptor; a single operation goes out as a plain descriptor):

• dto_batch_create, then dto_batch_add_{memmove,memfill,dualcast,crc,memcpy_crc,compare,compval}, then dto_batch_submit, then dto_batch_wait / dto_batch_poll, with per-operation status, result, bytes completed and CRC.
• dto_batch_poll redoes on the CPU every operation the device did not finish, results included, so DONE means every result is valid; dto_batch_status still reports what the device did.
• A move the device stopped partway is resumed from where it stopped, in the direction it was copying. With overlapping buffers, the device has already overwritten part of the source.
• dto_submit_batch_copy is kept as a convenience on top of the builder.

Every submit takes flags:

• DTO_SUBMIT_CC steers output toward the CPU cache.

• DTO_SUBMIT_BOF asks the device to block on page faults, and is passed to it as given:

  WQ block-on-fault	DTO_SUBMIT_BOF	Page fault
  enabled	set	the device waits; the op completes
  disabled	set	always DTO_ASYNC_FAILED, status 0x11 (invalid flags)
  either	not set	DTO_ASYNC_FAILED, status 0x03: partial completion (dto_async_bytes_completed)

  dto.h documents how to finish an overlapping move from where the device stopped. Nothing in the library requests block-on-fault on its own (dto_crc32c_with_seed doesn't), so the default calls work on either configuration.

• DTO_ASYNC_FALLBACK means nothing was done, and explicit submits are not gated by DTO_MIN_BYTES.

Migrating from the development branches:

• Cloud Hypervisor (ch-async-ops):
  • Add a trailing flags argument to dto_submit_{crc,compare,compval,transl_fetch} and dto_batch_add_{compare,crc}.
  • cache_control becomes flags; 1 is still DTO_SUBMIT_CC.
  • Pass DTO_SUBMIT_BOF, which used to be implicit. It needs a work queue with block-on-fault, as the branch's accelConfig.sh configures.
  • dto_async_crc_val now returns uint32_t.
  • dto_batch_poll no longer returns FAILED.
  • CRC values are unchanged (raw).
• cachelib-navy:
  • dto_batch_op_new/free becomes dto_batch_create/destroy.
  • dto_submit_batch(members) becomes dto_batch_add_* calls.
  • dto_batch_member_done / dto_batch_crc_val become dto_batch_status / dto_batch_crc.
  • cache_control becomes flags.
  • The aggregator wait method and dto_thread_active (admission control) are left for follow-up PRs, so dto_wait_blocks() returns 0 for now.
  • The older blocking/callback calls (dto_memcpy_async, dto_crc, dto_memset_pages, dto_batch_copy, ...) are not part of this API.

Testing (GNR, Xeon 6787P, one DSA, shared WQ dsa0/wq0.0):

• Functional: the suite now covers every submit and batch operation, the CPU repair of operations that hit unmapped pages (including overlapping moves left half done in both directions), and two threads polling one batch.
  • The tests used to accept FAILED/FALLBACK everywhere, so they could not tell a working device from one rejecting every operation (as the device does with every DTO_SUBMIT_BOF op on a work queue without block-on-fault, which is what those tests passed). With DTO_TEST_EXPECT_DSA=1, offload is now required.
  • A new test_async_bof checks the table above against whichever setting the work queue has.
  • 29/29 pass in strict mode as root on a WQ with block-on-fault and on one without, for both libdto and libdto_explicit, and on the CPU-fallback path.
• Transparent path: ctest -R sanity A/B against perf_baseline: every cell within ±1.1%, no regressions.
• Explicit API (one thread, block-on-fault WQ, median of 3–5 runs; all buffers prefaulted, so no page faults):
  • Throughput with 32 ops in flight matches cachelib-navy and ch-async-ops for every op and size, up to 64 GB/s; for comparison, CPU memcpy reaches 14.8 GB/s and CPU CRC32C 8.5 GB/s.
  • The 64 × 64 KiB batch copy takes 68.7 µs, against 69.1–69.2 µs on the other branches.
  • ch-async-ops's own 4 KiB batch-compare benchmark gives 131 ns/page for batches of 256 or more on both branches, against 320 ns/page for CPU memcmp.
  • Latency with one op in flight is within 2% at 64 KiB and about 3% at 4 KiB (20–30 ns, for example a 4 KiB CRC at 0.92 µs against 0.89). Most of that is upstream's per-submit round-robin WQ choice in get_wq() (an atomic increment), which the development branches replace with a per-thread WQ.
• The development branches on a WQ without block-on-fault (as this repo's accelConfig.sh configures it): every explicit op and batch fails with status 0x11 (invalid flags), because they set block-on-fault on every descriptor. Here it is set only when the caller asks for it.

[jsydir]

It makes sense to add an optional parameter to the dto_submit_* functions to pass in the max number of retries to allow users to selectively override the default value

dto_submit_common is not made externally visible. It should be renamed to async_submit_common (or some other name that does not start with dto_ ) to conform with the naming convention that non-transparent externally visible functions are named dto_*