OXYGENHUB
# f2f91ceb0e9f oxygen / vendor / crc-fast / .kiro / specs / future-proof-crc-params / tasks.md
6.0 KiB · Markdown · last changed Strata: the cloud stores send through ureq, so every release target links 1 month ago renderedsource blame history raw
1 
# Implementation Plan
2
3 
- [x] 1. Phase 1: Add CrcKeysStorage enum and helper methods
4 
  - Add CrcKeysStorage enum with KeysFold256 and KeysFutureTest variants
5 
  - Implement get_key() and key_count() methods on CrcKeysStorage
6 
  - Add const constructor methods from_keys_fold_256() and from_keys_fold_future_test()
7 
  - Add safe accessor methods to CrcParams that delegate to existing keys field
8 
  - Write comprehensive unit tests for CrcKeysStorage functionality
9 
  - _Requirements: 4.1, 4.2, 4.4, 5.1_
10
11 
- [x] 2. Phase 2: Update architecture code to use safe accessors
12 
  - [x] 2.1 Update SIMD folding code in src/arch/ to use params.get_key()
13 
    - Replace direct keys[index] access with params.get_key(index) in algorithm.rs
14 
    - Update VPCLMULQDQ code to use safe key access methods
15 
    - Update aarch64 and x86 architecture-specific code
16 
    - _Requirements: 3.1, 5.2_
17
18 
  - [x] 2.2 Update CRC32 algorithm code to use safe accessors
19 
    - Modify src/crc32/algorithm.rs to use params.get_key() instead of keys[index]
20 
    - Update fusion code in src/crc32/fusion/ if it accesses keys directly
21 
    - _Requirements: 3.1, 5.2_
22
23 
  - [x] 2.3 Update CRC64 algorithm code to use safe accessors
24 
    - Modify src/crc64/algorithm.rs to use params.get_key() instead of keys[index]
25 
    - Update any other CRC64-specific code that accesses keys directly
26 
    - _Requirements: 3.1, 5.2_
27
28 
  - [x] 2.4 Run performance benchmarks to verify zero overhead
29 
    - Benchmark key access performance before and after changes
30 
    - Verify compiler optimizations eliminate any performance regression
31 
    - Document that performance remains identical to direct array access
32 
    - _Requirements: 2.2, 4.4_
33
34 
- [x] 3. Phase 3: Switch CrcParams to use CrcKeysStorage
35 
  - [x] 3.1 Update CrcParams struct definition
36 
    - Change keys field from [u64; 23] to CrcKeysStorage
37 
    - Update CrcParams accessor methods to delegate to CrcKeysStorage
38 
    - Remove temporary delegation methods added in Phase 1
39 
    - _Requirements: 5.3_
40
41 
  - [x] 3.2 Update all CRC32 const definitions
42 
    - Update src/crc32/consts.rs to use CrcKeysStorage::from_keys_fold_256()
43 
    - Modify all CRC32_* const definitions to use new key storage format
44 
    - Ensure all existing key arrays are properly wrapped
45 
    - _Requirements: 1.2, 2.1_
46
47 
  - [x] 3.3 Update all CRC64 const definitions
48 
    - Update src/crc64/consts.rs to use CrcKeysStorage::from_keys_fold_256()
49 
    - Modify all CRC64_* const definitions to use new key storage format
50 
    - Ensure all existing key arrays are properly wrapped
51 
    - _Requirements: 1.2, 2.1_
52
53 
  - [x] 3.4 Update get-custom-params binary output
54 
    - Modify src/bin/get-custom-params.rs to output CrcKeysStorage format
55 
    - Update output template to use CrcKeysStorage::from_keys_fold_256()
56 
    - Test that generated const definitions compile and work correctly
57 
    - _Requirements: 6.1, 6.2, 6.3_
58
59 
  - [x] 3.5 Update cache system for new CrcParams structure
60 
    - Modify src/cache.rs to work with CrcKeysStorage-based CrcParams
61 
    - Update CrcParams::new() method to use new key storage format
62 
    - Ensure cache functionality remains intact after structural changes
63 
    - _Requirements: 2.3, 5.3_
64
65 
- [x] 4. Create comprehensive test suite for future-proof functionality
66 
  - [x] 4.1 Add unit tests for bounds checking behavior
67 
    - Test that get_key() returns 0 for out-of-bounds indices
68 
    - Test that get_key_checked() returns None for invalid indices
69 
    - Verify key_count() returns correct values for different storage variants
70 
    - _Requirements: 3.2_
71
72 
  - [x] 4.2 Add integration tests for third-party compatibility
73 
    - Create mock third-party const definitions using new format
74 
    - Test that existing key access patterns continue to work
75 
    - Verify backwards compatibility throughout migration phases
76 
    - _Requirements: 1.1, 2.3_
77
78 
  - [x] 4.3 Add performance regression tests
79 
    - Benchmark CRC calculation performance before and after changes
80 
    - Verify that key access performance matches direct array access
81 
    - Test memory usage impact of enum-based storage
82 
    - _Requirements: 2.2, 4.4_
83
84 
  - [x] 4.4 Add future expansion simulation tests
85 
    - Create test CrcParams using KeysFutureTest variant with 25 keys
86 
    - Test that code gracefully handles different key array sizes
87 
    - Verify that expansion to larger key arrays works as designed
88 
    - _Requirements: 1.1, 4.2_
89
90 
- [x] 5. Validate migration and run full test suite
91 
  - Run cargo test to ensure all existing tests pass
92 
  - Run cargo clippy to ensure code quality standards
93 
  - Run cargo fmt to ensure consistent formatting
94 
  - Verify that all CRC calculations produce identical results
95 
  - Test that third-party usage patterns remain functional
96 
  - _Requirements: 5.4_
97
98 
- [x] 6. Implement FFI future-proofing for C/C++ compatibility
99 
  - [x] 6.1 Update CrcFastParams struct to use pointer-based keys
100 
    - Change keys field from [u64; 23] to const uint64_t *keys pointer
101 
    - Add key_count field to track number of available keys
102 
    - Update From<CrcFastParams> and From<CrcParams> conversion implementations
103 
    - _Requirements: 7.2, 8.1_
104
105 
  - [x] 6.2 Implement stable key pointer management
106 
    - Add create_stable_key_pointer() helper function for CrcKeysStorage
107 
    - Ensure key pointers remain valid for the lifetime of CrcFastParams
108 
    - Handle memory management safely between Rust and C boundaries
109 
    - _Requirements: 8.2, 8.3_
110
111 
  - [x] 6.3 Update FFI functions to use new CrcFastParams structure
112 
    - Update existing FFI functions to use new pointer-based CrcFastParams
113 
    - Ensure all FFI functions handle variable key counts correctly
114 
    - Test conversion between CrcKeysStorage variants and C pointer access
115 
    - _Requirements: 7.1, 7.3_
116
117 
  - [x] 6.4 Update C header file and add comprehensive FFI tests
118 
    - Update CrcFastParams struct definition in libcrc_fast.h to use pointer
119 
    - Create FFI tests for direct pointer access with different key counts
120 
    - Test future expansion scenarios with different key counts (23, 25, etc.)
121 
    - Verify memory safety and pointer stability across FFI boundary
122 
    - _Requirements: 7.1, 8.1_