Adding ibv_query_rt_values_ex verb

[atilag]

Issue: #91

Added ibv_query_rt_values_ex support

New public API:

• ValuesMask — bitmask enum (using bitmask-enum, same as AccessFlags) with RawClock variant wrapping IBV_VALUES_MASK_RAW_CLOCK
• RtValues — wrapper around ibv_values_ex with:
  • raw_clock() -> std::time::Duration — the device's free-running hardware clock
  • comp_mask() -> ValuesMask — which fields were actually populated by the driver
• QueryRtValuesError / QueryRtValuesErrorKind — error types following the existing pattern, with a NotSupported variant for drivers that return EOPNOTSUPP
• DeviceContext::query_rt_values_ex(mask: ValuesMask) -> Result<RtValues, QueryRtValuesError> — the main method
  Usage:

use sideway::ibverbs::device_context::ValuesMask;

let rt = context.query_rt_values_ex(ValuesMask::RawClock)?;
println!("HW clock: {:?}", rt.raw_clock());

Added a unit test: test_query_rt_values_ex

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the DeviceContext by integrating support for querying real-time values from RDMA devices. This feature allows applications to retrieve precise hardware clock information, which is vital for correlating event timestamps in high-performance scenarios. The changes introduce new data structures, robust error handling, and a dedicated method to access this functionality.

Highlights

• New Public API: ValuesMask: Introduced a ValuesMask bitmask enum, similar to AccessFlags, which includes a RawClock variant to wrap IBV_VALUES_MASK_RAW_CLOCK.
• New Public API: RtValues: Added an RtValues struct that wraps ibv_values_ex, providing raw_clock() to retrieve the device's free-running hardware clock as a std::time::Duration, and comp_mask() to indicate which fields were populated by the driver.
• New Public API: Error Handling: Created QueryRtValuesError and QueryRtValuesErrorKind error types, following existing patterns, with a NotSupported variant for drivers that do not support the operation.
• New Public API: DeviceContext Method: Implemented DeviceContext::query_rt_values_ex(mask: ValuesMask) as the main method to query real-time values from the RDMA device.
• Unit Test: Added a new unit test, test_query_rt_values_ex, to verify the functionality of the new query_rt_values_ex method.

Changelog

• src/ibverbs/device_context.rs
  • Added std::time::Duration and bitmask_enum::bitmask imports.
  • Imported ibv_query_rt_values_ex, ibv_values_ex, and ibv_values_mask from rdma_mummy_sys.
  • Introduced QueryRtValuesError and QueryRtValuesErrorKind for handling errors during real-time value queries, including a NotSupported variant.
  • Defined ValuesMask enum using bitmask_enum to specify which real-time values to query, with RawClock as the initial variant.
  • Created RtValues struct to encapsulate ibv_values_ex and provide methods like raw_clock() and comp_mask().
  • Implemented DeviceContext::query_rt_values_ex to perform the actual query, handling success, EOPNOTSUPP, and other io::Error cases.
  • Added a unit test test_query_rt_values_ex to verify the functionality of query_rt_values_ex, checking for RawClock presence and non-zero clock values, or NotSupported errors.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request adds support for ibv_query_rt_values_ex to query real-time values from an RDMA device, such as the hardware clock. The changes are well-structured, introducing new error types, a bitmask enum for value selection, and a wrapper for the results, along with the primary query method on DeviceContext. The accompanying unit test effectively validates the new functionality. The implementation is robust and aligns with the existing coding patterns. I have one suggestion to enhance consistency with other FFI calls within the file.

[dragonJACson]

Hi @atilag, thanks for your contribution! The PR looks good to me, but I think we need to add wrapper for ibv_query_rt_values_ex in https://github.com/RDMA-Rust/rdma-core-mummy at the same time, after that we would release a new version of rdma-mummy-sys, then use the new rdma-mummy-sys in Cargo.toml, cc @FujiZ

[FujiZ]

Hi @atilag, thanks for your contribution! The PR looks good to me, but I think we need to add wrapper for ibv_query_rt_values_ex in https://github.com/RDMA-Rust/rdma-core-mummy at the same time, after that we would release a new version of rdma-mummy-sys, then use the new rdma-mummy-sys in Cargo.toml, cc @FujiZ

ibv_query_rt_values_ex is a inline function that does not require dlsym trick.

[codecov]

Codecov Report

❌ Patch coverage is 11.90476% with 37 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/ibverbs/device_context.rs	11.90%	37 Missing ⚠️

❌ Your patch check has failed because the patch coverage (11.90%) is below the target coverage (60.00%). You can increase the patch coverage or adjust the target coverage.

❗ There is a different number of reports uploaded between BASE (ce99bd9) and HEAD (f81c051). Click for more details.

HEAD has 3 uploads less than BASE

Flag	BASE (ce99bd9)	HEAD (f81c051)
	4	1

Files with missing lines	Coverage Δ
src/ibverbs/device_context.rs	39.29% <11.90%> (-46.88%)	⬇️

... and 7 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[dragonJACson]

Could you please rebase this onto main, which already includes some CI-related fixes, so we can see whether the CI passes?

Also, could you please follow the Conventional Commits format for the commit message? Thanks!

[atilag]

@dragonJACson Yes, I will rebase and follow the convention.
I decided to move it as a draft, because I found out that timing information is not really a timespec (secs+nano) despite the libibverb data type, but a clock counter/ticks. So I'm changing the interface to better reflect this change.