github ↗
docs menu

Module Rig_mlx5_abi.Completion

A completion is what the NIC writes once a work entry completes or fails.

The completion ring holds m entries of Completion.size bytes, m a power of two. Its consumer count c is how many completions the process read. The next is at byte 64 * (c mod m), and the NIC wrote it once Completion.owned says so.

#val size : int

size is 64, the bytes of a completion.

#type error =
  1. #| Local_length
    (*

    A local length is wrong.

    *)
  2. #| Local_qp_operation
    (*

    The entry is malformed for its queue pair.

    *)
  3. #| Local_protection
    (*

    Local memory is outside its region or its keys.

    *)
  4. #| Flushed
    (*

    The queue pair failed before the entry ran.

    *)
  5. #| Bad_response
    (*

    The peer sent an unexpected response.

    *)
  6. #| Local_access
    (*

    The peer's request violated local access rights.

    *)
  7. #| Remote_invalid_request
    (*

    The peer refused the request as malformed for its queue pair.

    *)
  8. #| Remote_access
    (*

    The peer refused the request's memory or key.

    *)
  9. #| Remote_operation
    (*

    The peer could not complete the request.

    *)
  10. #| Retry_exceeded
    (*

    The peer acknowledged nothing within the queue pair's retries.

    *)
  11. #| Remote_aborted
    (*

    The peer aborted the operation.

    *)
  12. #| Other_error of int
    (*

    Another syndrome, by its number.

    *)

The type for the reasons an entry failed.

#type status =
  1. #| Done
    (*

    An entry of the send ring completed.

    *)
  2. #| Received of int
    (*

    A receive took a message of that many bytes, which have landed in its memory.

    *)
  3. #| Failed of {
    1. #ring : ring;
    2. #error : error;
    3. #vendor : int;
    }
    (*

    An entry of ring failed, and vendor is the NIC's own syndrome.

    *)
  4. #| Unexpected of int
    (*

    The completion is of a kind that the entries here never make, such as a receive's of a message with immediate data, by its opcode.

    *)

The type for the outcomes of entries.

#type t = {
  1. #qp : int;
    (*

    The number of the entry's queue pair.

    *)
  2. #index : int;
    (*

    The low 16 bits of the entry's number, for an entry of the send ring.

    *)
  3. #status : status;
}

The type for completions. The receives of a queue pair complete in the order they were posted.

#val owned : buffer -> int -> count:int -> entries:int -> bool

owned b at ~count ~entries is true iff the completion at byte at of b is the one the NIC wrote for consumer count count of a ring of entries entries: its opcode is valid and its owner bit is bit log2 entries of count. A process must read the completion only after owned returns true, with loads ordered after the one that read the owner bit.

Raises Invalid_argument if the bytes are not in b, count is negative or entries is not a power of two.

#val read : buffer -> int -> t

read b at is the completion at byte at of b.

Raises Invalid_argument if the bytes are not in b.

#val invalidate : buffer -> int -> unit

invalidate b at marks the completion at byte at of b as one the NIC has not written, so that owned is false for it at every count until the NIC writes it. A new ring's completions are all marked so.

Raises Invalid_argument if the bytes are not in b.

#val message : t -> string

message c describes c for a person, such as "queue pair 0x1c3, entry 7: retry counter exceeded (vendor syndrome 0x81)".