| RFC-0253: zx_object_get_info ZX_INFO_VMAR_MAPS | |
|---|---|
| Status | Accepted |
| Areas |
|
| Description | This RFC proposes adding a new zx_object_get_info topic, ZX_INFO_VMAR_MAPS. |
| Issues | |
| Gerrit change | |
| Authors | |
| Reviewers | |
| Date submitted (year-month-day) | 2024-07-19 |
| Date reviewed (year-month-day) | 2024-07-17 |
Problem Statement
ZX_INFO_PROCESS_MAPS is inefficient when callers only care about one VMAR.
ZX_INFO_PROCESS_MAPS iterates a process's address space, providing the caller
with zx_info_maps_t structs that describe every address region and mapping
available to the process. If a caller wants only a subset of this information,
e.g. just the contents of one specific VMAR, it must pay the full price anyway.
What's worse is that the caller must then filter the results.
Summary
We propose adding a new object_info topic, ZX_INFO_VMAR_MAPS, that behaves
like ZX_INFO_PROCESS_MAPS, but for VMARs.
Stakeholders
Who has a stake in whether this RFC is accepted? (This section is optional but encouraged.)
Facilitator:
Reviewers: adamperry@ (Starnix), adanis@ (Zircon VM), dworsham@ (Zircon VM), mcgrathr@ (Zircon)
Socialization: The proposal was briefly discussed with adamperry@ and adanis@ prior to drafting this RFC.
Requirements
The purpose of this proposal is to improve Starnix performance by allowing it to query a particular VMAR (the Linux process address space, a.k.a. the restricted region) rather than the entire process's address space.
Efficiency - The new syscall should perform work proportional to the size/complexity of the specified VMAR.
Symmetry and Ergonomics - The new call should produce results that are
structurally similar to those produced by the existing ZX_INFO_PROCESS_MAPS in
order to minimize work on existing callers that wish to use the new call.
Design
We will add a new object_info topic named ZX_INFO_VMAR_MAPS. This new topic
will behave like the existing ZX_INFO_PROCESS_MAPS, but instead of returning
results for the specified process, it will return results for the specified
VMAR.
Like ZX_INFO_PROCESS_MAPS, the result will be a depth-first pre-order
traversal.
The first result record will describe the specified VMAR.
Unlike ZX_INFO_PROCESS_MAPS, the depth fields of the results will be relative
to the specified VMAR rather than the specified process. The depth of the first
result record will be 0.
To illustrate, the updated docs for object_get_info will say something like,
If *topic* is `ZX_INFO_VMAR_MAPS`, *handle* must be of type `ZX_OBJ_TYPE_VMAR`
and have `ZX_RIGHT_INSPECT`.
and
### ZX_INFO_VMAR_MAPS
*handle* type: `VM Address Region`, with `ZX_RIGHT_INSPECT`
*buffer* type: `zx_info_maps_t[n]`
The `zx_info_maps_t` array is a depth-first pre-order walk of the target
VMAR tree. As per the pre-order traversal base addresses will be in ascending
order.
See `ZX_INFO_PROCESS_MAPS` for a description of `zx_info_maps_t`.
The first `zx_info_maps_t` will describe the queried VMAR. The *depth*
field of each entry describes its relationship to the nodes that come
before it. The queried VMAR will have depth 0. All other entries have
depth 1 or greater.
Additional errors:
* `ZX_ERR_ACCESS_DENIED`: If the appropriate rights are missing.
* `ZX_ERR_BAD_STATE`: If the target process containing the VMAR has
terminated, or if the address space containing the VMAR has been
destroyed.
Implementation
The new feature will be implemented with a series of small, backwards compatible
changes that include updates to tests and documentation. Some existing code
will be refactored so that it can be reused for both ZX_INFO_PROCESS_MAPS and
ZX_INFO_VMAR_MAPS.
Performance
No impact to existing code/systems. Once complete, callers that are migrated
from ZX_INFO_PROCESS_MAPS to ZX_INFO_VMAR_MAPS should see a performance
improvement from the reduced work performed by the syscall as well as the
elimination of any post-call filter step.
Ergonomics
For easy of use, the result types and semantics will closely match those of an
existing call, object_get_info with ZX_INFO_PROCESS_MAPS.
Backwards Compatibility
The proposed change is backwards compatible. No existing calls are impacted. The new call will behave similar to an existing call.
Security considerations
Because the returned information is a subset of what's returned by
ZX_INFO_PROCESS_MAPS, and because the new object_get_info call will require
the same handle rights required of the existing ZX_INFO_PROCESS_MAPS call,
there is no change to the security surface area or posture.
Privacy considerations
There are no privacy concerns.
Testing
The core-tests suite will be updated to test the new call.
Documentation
The syscall docs will be updated to describe the new call.
Drawbacks, alternatives, and unknowns
Implementing this proposal requires only a small amount of engineering effort. Future maintenance of the new syscall should be minimal. Further more, the new call does not significantly reduce (kernel implementation) flexibility or (API) freedom.
The primary alternative to implementing a new topic is to continue to use the
less efficient ZX_INFO_PROCESS_MAPS and continue to filter the results.
Depth relative to target vs. address space
Under this proposal the depth field reported for each visited node is relative to the target, the specified VMAR, starting at zero.
An alternative is to report the depth relative to the process's address space. That is, report an absolute depth. Both options meet the requirements and perform similarly against the stated goals.
We selected depth relative to target because it exposes less information to callers and because it allow for more implementation flexibility when it comes to internal lock strategies.
Prior art and references
See also ZX_INFO_PROCESS_MAPS and ZX_INFO_VMAR.