OXYGENHUB
# c6e69e4b8d8f oxygen / vendor / crc-fast / .kiro / specs / checksum-benchmark-option / requirements.md
3.3 KiB · Markdown · last changed Strata: the cloud stores send through ureq, so every release target links 1 month ago renderedsource blame history raw

Requirements Document

Introduction

This feature adds a simple benchmark option to the existing bin/checksum.rs tool via a command-line flag. The benchmark will allow users to test performance across different platforms using a single binary, reporting throughput in GiB/s and the acceleration target used. This enables cross-platform performance comparison without requiring a full development environment checkout.

Glossary

  • Checksum_Tool: The existing bin/checksum.rs binary application
  • Benchmark_Mode: A new operational mode that measures and reports performance metrics
  • Acceleration_Target: The hardware-specific optimization path returned by get_calculator_target()
  • Throughput_Metric: Performance measurement expressed in GiB/s (gibibytes per second)
  • Test_Data: Randomly generated byte array used for benchmark measurements
  • Black_Box: Rust's std::hint::black_box() function that prevents compiler optimizations during benchmarking

Requirements

Requirement 1

User Story: As a developer, I want to run performance benchmarks from the checksum tool, so that I can compare CRC performance across different hardware platforms without setting up a full development environment.

Acceptance Criteria

  1. WHEN the user provides a -b flag, THE Checksum_Tool SHALL enter Benchmark_Mode
  2. WHILE in Benchmark_Mode, THE Checksum_Tool SHALL generate Test_Data of the specified size once and reuse it for all iterations
  3. THE Checksum_Tool SHALL report Throughput_Metric in GiB/s format
  4. THE Checksum_Tool SHALL display the Acceleration_Target used for the benchmark
  5. THE Checksum_Tool SHALL use Black_Box to prevent compiler optimizations during measurement

Requirement 2

User Story: As a developer, I want to specify benchmark parameters, so that I can control the test conditions for consistent cross-platform comparisons.

Acceptance Criteria

  1. WHEN the user provides -a parameter with -b flag, THE Checksum_Tool SHALL use the specified CRC algorithm for benchmarking
  2. WHEN the user provides --size parameter, THE Checksum_Tool SHALL generate Test_Data of the specified byte size
  3. WHEN the user provides --duration parameter, THE Checksum_Tool SHALL run the benchmark for the specified number of seconds
  4. WHERE no benchmark parameters are provided, THE Checksum_Tool SHALL use default values of 1 MiB for size and 10 seconds for duration
  5. THE Checksum_Tool SHALL validate all benchmark parameter values before starting the benchmark

Requirement 3

User Story: As a developer, I want the benchmark to support both file/string input and generated data, so that I can benchmark with specific data or use random data for consistent testing.

Acceptance Criteria

  1. WHEN the user provides -b with -f or -s flags, THE Checksum_Tool SHALL use the file or string content as Test_Data for benchmarking
  2. WHEN the user provides -b with --size parameter but no -f or -s flags, THE Checksum_Tool SHALL generate random Test_Data of the specified size
  3. IF the user provides -b without any data source or size specification, THEN THE Checksum_Tool SHALL generate random Test_Data using the default size
  4. THE Checksum_Tool SHALL display appropriate usage information when benchmark parameters are invalid
  5. THE Checksum_Tool SHALL maintain backward compatibility with existing checksum functionality