Yury Plyakhin 4d27530c69 [Offloading] Offload Binary Format V2: Support Multiple Entries (#169425) ...

This PR updates the OffloadBinary format from version 1 to version 2,
enabling support for multiple offloading entries in a single binary.
This allows combining multiple device images into a single binary with
common global metadata while maintaining backwards compatibility with
version 1 binaries.

# Key Changes
## Binary Format Enhancements
  **Version 2 Format Changes:**
  - Changed from single-entry to multi-entry design
  - Updated `Header` structure:
    - Renamed `EntryOffset` → `EntriesOffset` (offset to entries array)
    - Renamed `EntrySize` → `EntriesCount` (number of entries)
- Added `StringEntry::ValueSize` field to support explicit string value
sizes (enables non-null-terminated strings)
- Introduced `OffloadEntryFlags` enum with `OIF_Metadata` flag for
metadata-only entries (entries without binary images)

  **API Changes:**
- `OffloadBinary::create()` now returns
`Expected<SmallVector<std::unique_ptr<OffloadBinary>>>` instead of
single binary
- Added optional `Index` parameter to extract specific entry:
`create(Buffer, std::optional<uint64_t> Index)`
- `OffloadBinary::write()` now accepts `ArrayRef<OffloadingImage>`
instead of single image
  - Added `OffloadBinary::extractHeader()` for header extraction

  **Memory Management:**
- Implemented `SharedMemoryBuffer` class to enable memory sharing across
multiple `OffloadBinary` instances from the same file
- Multiple entries from a single serialized binary share the underlying
buffer

## Testing
  **Unit Tests (`unittests/Object/OffloadingTest.cpp`):**
- `checkMultiEntryBinaryExtraction`: Tests extracting all entries from a
multi-entry binary
- `checkIndexBasedExtraction`: Tests extracting specific entries by
index, including out-of-bounds validation
  - `checkEdgeCases`: Tests edge cases including:
    - Empty string metadata
    - Empty image data
    - Large string values (4KB)

  **Other Tests:**
- Updated `test/ObjectYAML/Offload/multiple_members.yaml` to include
metadata-only entry

---------

Co-authored-by: Joseph Huber <huberjn@outlook.com>

2026-02-05 07:46:57 -08:00

2.4 KiB

Raw Blame History

View Raw