| RFC-0262: Expand KMEM_STATS ||
|---|---|
| Status | Accepted |
| Areas | - Kernel |
| Description | Expand the fields and descriptions in ZX_INFO_KMEM_STATS and deprecate ZX_INFO_KMEM_STATS_EXTENDED. |
| Issues | - [42147338](https://fxbug.dev/42147338) |
| Gerrit change | - [1108953](https://fuchsia-review.googlesource.com/c/fuchsia/+/1108953) |
| Authors | - [adanis@google.com](https://fuchsia-review.googlesource.com/q/owner:adanis@google.com) |
| Reviewers | - [maniscalco@google.com](https://fuchsia-review.googlesource.com/q/owner:maniscalco@google.com) - [mcgrathr@google.com](https://fuchsia-review.googlesource.com/q/owner:mcgrathr@google.com) |
| Date submitted (year-month-day) | 2024-08-28 |
| Date reviewed (year-month-day) | 2024-10-02 |

[Edit this RFC](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/contribute/governance/rfcs/0262_expand_kmem_stats.md)
[Edit RFC metadata](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/contribute/governance/rfcs/_rfcs.yaml&searchAndJump=-+name:+'RFC-0262')

## Problem Statement

The existing [`ZX_INFO_KMEM_STATS`](https://fuchsia.dev/reference/syscalls/object_get_info.md.txt#zx_info_kmem_stats)
query is missing fields to report newer kernel memory usage types, creating
confusion in how to interpret the existing fields, and the existing fields
themselves have confusing or minimal documentation. This RFC seeks to address
both of these problems.

This RFC does not seek to change the style of reporting that
`ZX_INFO_KMEM_STATS` does or otherwise support additional kinds of memory usage
queries.

## Summary

Expand the structure returned by the `ZX_INFO_KMEM_STATS` to include counting
for pages in states that did not exist when the query was originally written and
include the fields from the [`ZX_INFO_KMEM_STATS_EXTENDED`](https://fuchsia.dev/reference/syscalls/object_get_info.md.txt#zx_info_kmem_stats_extended)
query, deprecating it in the process. Update the documentation for both the new
and existing fields for clarity and correctness.

## Stakeholders

*Facilitator:*

davemoore@google.com

*Reviewers:*

maniscalco@google.com, mcgrathr@google.com

*Consulted:*

plabatut@google.com

*Socialization:*

A CL to implement this RFC was iterated on with the target reviewers.

## Design

Existing kernel struct evolution and versions strategies will be used to provide
a new version of the `ZX_INFO_KMEM_STATS` query and deprecate the
`ZX_INFO_KMEM_STATS_EXTENDED` query. The new version of the `ZX_INFO_KMEM_STATS`
struct will include fields for the missing `vm_page_state`, these these are:
`FREE_LOANED`, `CACHE`, `SLAB` and `ZRAM` states, and all the fields from
`ZX_INFO_KMEM_STATS_EXTENDED`.

Documentation changes are focused on clarifying some of the following items:

- Memory in these states is not in use by the kernel, but is the kernel's interpretation of system memory usage.
- Increased specificity on memory being 'free' as memory can be both unallocated, but only available for certain kinds of allocations.
- How to interpret memory in VMOs that is reported in multiple states and when that reporting overlaps or not.

## Implementation

This will be landed as two CLs:

1. Update the `ZX_INFO_KMEM_STATS` query and all documentation with a new versioned topic number and struct.
2. Deprecate `ZX_INFO_KMEM_STATS_EXTENDED` once users have switched to `ZX_INFO_KMEM_STATS`.

The deprecation will leave the query implemented in the kernel, preserving
binary compatibility.

## Performance

Expanding the fields in `ZX_INFO_KMEM_STATS` will make the query take more time,
especially with adding the `ZX_INFO_KMEM_STATS_EXTENDED` fields, but this cost
should still be negligible relative to existing cost of the syscall. Primary
existing user, memory_monitor, sometimes performs both queries anyway and in
those cases a single syscall will improve performance.

Actual syscall performance cost and potential impact on memory_monitor should
still be validated.

## Backwards Compatibility

The struct evolution strategy preserves binary compatibility for any prebuilt
artifacts, and since fields are only added source compatibility should be
preserved in most cases. It is possible that the existing info struct is being
used in a way that adding fields breaks, in which case the old version of the
struct and query can be used until that usage site can be updated.

## Documentation

Updating the documentation of the `ZX_INFO_KMEM_STATS` query is an explicit goal
of this RFC and such changes will be part of any CLs.

## Drawbacks, alternatives, and unknowns

Instead of deprecating the `ZX_INFO_KMEM_STATS_EXTENDED` query, it could be
maintained and its fields not merged into `ZX_INFO_KMEM_STATS`, preventing any
performance concerns. Although the `ZX_INFO_KMEM_STATS_EXTENDED` query was
intended to be a place for information deemed too expensive for
`ZX_INFO_KMEM_STATS`, this information is, due to kernel evolution, no longer
expensive to gather and has no benefit being separated.
[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/contribute/governance/rfcs/0262_expand_kmem_stats.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/contribute/governance/rfcs/0262_expand_kmem_stats.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/contribute/governance/rfcs/0262_expand_kmem_stats.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/contribute/governance/rfcs/0262_expand_kmem_stats.md "Edit the source code of this page")