class GetVmoInfo

Given a handle to a sysmem-provided VMO, this returns additional info

about the corresponding sysmem logical buffer.

Most callers will duplicate a VMO handle first and send the duplicate to

this call.

If the client has created a child VMO of a sysmem-provided VMO, that

child VMO isn't considered a "sysmem VMO" for purposes of this call.

+ request `vmo` A handle to a sysmem-provided VMO (or see errors).

+ request `need_weak` Iff set to true, the response will have weak_vmo

set to a weak VMO for the buffer, regardless of whether `vmo` in the

request was weak or strong.

- response `buffer_collection_id` The buffer collection ID, which is

unique per logical buffer collection per boot.

- response `buffer_index` The buffer index of the buffer within the

buffer collection. This is the same as the index of the buffer within

[`fuchsia.sysmem2/BufferCollectionInfo.buffers`]. The `buffer_index`

is the same for all sysmem-delivered VMOs corresponding to the same

logical buffer, even if the VMO koids differ. The `buffer_index` is

only unique across buffers of a buffer collection. For a given buffer,

the combination of `buffer_collection_id` and `buffer_index` is unique

per boot.

- response `close_weak_asap` Iff `vmo` is a handle to a weak sysmem VMO

OR need_weak is set to true, the `close_weak_asap` field will be set

in the response. This handle will signal `ZX_EVENTPAIR_PEER_CLOSED`

when all weak VMO handles to the buffer should be closed as soon as

possible. This is signalled shortly after all strong sysmem VMOs to

the buffer are closed (including any held indirectly via strong

`BufferCollectionToken` or strong `BufferCollection`). Failure to

close all weak sysmem VMO handles to the buffer quickly upon

`ZX_EVENTPAIR_PEER_CLOSED` is considered a VMO leak caused by the

client still holding a weak sysmem VMO handle and results in loud

complaints to the log by sysmem (after a delay). The buffers of a

collection can be freed independently of each other. The

`ZX_EVENTPAIR_PEER_CLOSED` may already be signalled before the

response arrives at the client. A client that isn't prepared to

directly handle weak sysmem VMOs and waiting on close_weak_asap, on

seeing this field set in response to a request that had need_weak

un-set, typically should ignore the fact that the vmo handle was a

weak vmo handle; typically another participant that's also a client of

this participant via some other protocol has taken responsibility for

ensuring that this participant will close all handles to the buffer,

typically by shutting down this participant's context holding a vmo

handle in some other way. That said, it is not harmful for both

participants to directly handle close_weak_asap, even if one

participant can take responsibility for handling close_weak_asap. See

also `[fuchsia.sysmem2/Node.SetWeakOk]` for_child_nodes_also.

- response `weak_vmo` This field is set in the response iff the request

had `need_weak` set to true. When set, this is a weak VMO handle to

the same buffer as `vmo` in the request, but may not have the same

koid as `vmo` had (this applies regardless of whether `vmo` was strong

or weak).

* error `[fuchsia.sysmem2/Error.NOT_FOUND]` - the vmo isn't a sysmem

VMO. Both strong and weak sysmem VMOs can be passed to this call, and

the VMO handle passed in to this call itself keeps the VMO's info

alive for purposes of responding to this call. Because of this,

ZX_ERR_NOT_FOUND errors are unambiguous (even if there are no other

handles to the VMO when calling; even if other handles are closed

before the GetVmoInfo response arrives at the client).

* error `[fuchsia.sysmem2/Error.UNSPECIFIED]` The request failed for an

unspecified reason. See the log for more info.

* error `[fuchsia.sysmem2/Error.PROTOCOL_DEVIATION]` The vmo field

wasn't set, or there was some other problem with the request field(s).

See the log.