RFC-0273: Handle specific information calls

RFC-0273: Handle specific information calls
StatusAccepted
Areas
  • Zircon
Description

Provide replacements for handle topics in object_get_info call.

Gerrit change
Authors
Reviewers
Date submitted (year-month-day)2025-05-19
Date reviewed (year-month-day)2025-07-08

Problem Statement

Provide a mechanism for querying information about a handle that is clearly separate from informational queries about the object referred to by a handle.

Summary

Introduce a pair of call to support the ZX_INFO_HANDLE_VALID and ZX_INFO_HANDLE_BASIC topics of object_get_info.

Stakeholders

Zircon Kernel team.

Facilitator:

cpu@google.com

Reviewers:

  • abarth@google.com
  • maniscalco@google.com
  • mcgrathr@google.com

Consulted:

Zircon Kernel team.

Socialization:

Discussed in the Zircon internal chat room.

Requirements

A significant amount of existing code calls object_get_info with the ZX_INFO_HANDLE_BASIC topic to query the KOID for diagnostic purposes. We need to support this code with care.

Design

Introduce a pair of new handle_ centric calls replacing use of the handle topics in object_get_info. These calls have the same behavior as the object_get_info queries they replace with a modernized API design.

Handle validity testing

handle_check_valid accepts a single zx_handle_t parameter and returns ZX_OK if the handle is valid and an error otherwise. This is the replacement for calling object_get_info with a topic of ZX_INFO_HANDLE_VALID. The exact error conditions and codes will be decided during API review with the following goals: - Generate unique errors for statically invalid bit patterns such as ZX_HANDLE_INVALID and having one of the two least significant bits cleared. - Avoid use of ZX_ERR_BAD_HANDLE to reserve this code for situations that would trigger the bad handle policy.

Handle basic info

handle_get_basic_info populates a zx_handle_basic_info_t structure with information about a handle. This is the replacement for calling object_get_info with a topic of ZX_INFO_HANDLE_BASIC.

object_get_info

This proposal does not include modifying the existing object_get_info call. It will continue to support the handle-specific topics. We may want to encourage new code to use the handle-specific entry point for edification.

Implementation

These calls can be implemented initially as vdsocalls using the existing object_get_info system call.

Performance

This adds one more entry point to the vDSO that requires relocation on program load. This is expected to be negligible.

Ergonomics

This provides additional clarity on the separation of the "handle" and "object" concepts in the Zircon API.

Backwards Compatibility

This API will be added following the procedures defined in RFC-0239. The existing functionality of object_get_info will not be changed at this time. In the future, we may deprecate and eventually remove support for the handle specific topics from object_get_info once sufficient time has passed to update all callers and libraries using this functionality to these new calls.

Future work

Once all existing code has been updated to use the new calls for the handle-related topics we could update object_get_info to return an error for these topics.

Security considerations

No security considerations are anticipated.

Privacy considerations

No security considerations are anticipated.

Testing

The Zircon core tests will be expanded to cover these new entry points as they cover object_get_info today.

Documentation

New system call documentation will be added for the new entry points and the "Zircon handles" document will be updated to cite these entry points.

Drawbacks, alternatives, and unknowns

An alternative is to do nothing and continue to use the object entry point to query handle information.

Prior art and references

The rest of the syscall API distinguishes between operations on handles and objects in the name. For example, handle_close and handle_duplicate operate on handles and object_get_property and object_signal operate on objects.