Skip to content

Make Low Level Binary File I/O Independent of Host System's Byte Order - #5543

Merged
bska merged 4 commits into
OPM:masterfrom
bska:modernise-low-level-file-io
Nov 18, 2026
Merged

bska merged 4 commits into
OPM:masterfrom
bska:modernise-low-level-file-io

Conversation

@bska

@bska bska commented Nov 5, 2026

Copy link
Copy Markdown
Member

This PR replaces the bottom layer of the binary file I/O stack, represented by the functions flipEndian*(), with a more portable alternative. We leverage C++20's <bit> header, and especially its endian detection support, to determine whether we need to swap byte order at all. We still require that the binary builds and runs on the same host platform, but at least we're now able to portably read and write files that can be correctly interpreted on systems of both byte orders. We don't support mixed byte orders however.

To this end we introduce a new header, ByteOrder.hpp, with utilities for converting numeric values between the host's native byte order and the big-endian byte order used in "unformatted" result files. The utilities are

  • byteswap() – Unconditionally reverse the bytes of a four or eight byte integer or floating-point value.
  • toFileOrder(), fromFileOrder() – Convert between native and big-endian byte order. Identity operations on big-endian hosts.
  • readFileOrder(), writeFileOrder() – Read or write a single value, or a contiguous range of values, in big-endian byte order.

We implement byteswap() in terms of std::bit_cast<>() to a same-sized unsigned integer type, and use std::byteswap() from C++23 if available. Otherwise we fall back to a shift-and-mask implementation which mainstream compilers recognise and translate into a single byte swap instruction. This replaces the need for compiler intrinsics and reinterpret_cast<>()-based byte reversals.

The header also asserts the platform assumptions of the binary file I/O layer, i.e., 8-bit bytes, a purely little or big-endian host, 4-byte 'int', and IEEE 754 floating-point types.

We use these new utilities in EclUtil and other facilities. As part of this, we also fix the handling of LOGI arrays. These were previously read and written without byte order conversion, with the IX convention's 'true' value encoded as the little-endian representation of a big-endian '1' (0x1000000). LOGI elements now pass through the same byte order conversion as INTE elements and the true_value_ix constant is now 1. The on-disk representation is unchanged on little-endian hosts.

The callback of readBinaryArray<>() now receives numeric elements in native byte order. Its only outside user, ESmry, now uses readBinaryInteArray() instead. We reimplement the flipEndian*() functions in terms of byteswap() as unconditional byte swaps, but mark these as "deprecated".


This work is partly inspired by long-standing Issue #3014. That issue alluded to using C++20's endian support and this PR finally makes that step. More immediately though, I wanted to get away from using compiler intrinsics for byte swapping and reduce the number of reinterpret_cast<>() invocations in the code base.

@bska bska added the manual:enhancement This is an enhancement/improvent that needs to be documented in the manual label Nov 5, 2026
@bska

bska commented Nov 5, 2026

Copy link
Copy Markdown
Member Author

jenkins build this please

@bska
bska requested a balanced review from Copilot November 5, 2026 19:16

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.

🟡 Changes recommended

The change still has a moderate active issue in opm/io/eclipse/ByteOrder.hpp where readFileOrder() writes through a FileScalarRange that can be const, casting away const via reinterpret_cast<char*>, so the range constraint should be tightened to prevent unsafe misuse.

1 open issue
What changed in this PR

This PR modernizes the low-level binary ECL I/O byte-order handling by introducing a central ByteOrder.hpp utility layer (based on C++20 <bit> endian detection) and migrating binary reads/writes to use host↔file (big-endian) conversions consistently across the I/O stack.

Changes:

  • Added opm/io/eclipse/ByteOrder.hpp with byteswap(), toFileOrder()/fromFileOrder(), and readFileOrder()/writeFileOrder() utilities plus platform assumption assertions.
  • Updated binary readers/writers (EclUtil, EclOutput, EGrid, ESmry) to use file-order conversion instead of flipEndian*() and fixed LOGI handling to convert like INTE (with true_value_ix now 1).
  • Expanded/strengthened tests to validate exact on-disk byte sequences (“golden bytes”) and round-trips independent of host endianness.
File Description
tests/​test_EclIO.cpp Updated as part of this pull request.
opm/​io/​eclipse/​ESmry.cpp Updated as part of this pull request.
opm/​io/​eclipse/​EGrid.cpp Updated as part of this pull request.
opm/​io/​eclipse/​EclUtil.hpp Updated as part of this pull request.
opm/​io/​eclipse/​EclUtil.cpp Updated as part of this pull request.
opm/​io/​eclipse/​EclOutput.cpp Updated as part of this pull request.
opm/​io/​eclipse/​EclIOdata.hpp Updated as part of this pull request.
opm/​io/​eclipse/​ByteOrder.hpp Updated as part of this pull request.
CMakeLists_files.cmake Updated as part of this pull request.

Review effort: Balanced

Comment thread opm/io/eclipse/ByteOrder.hpp Resolved
@bska
bska force-pushed the modernise-low-level-file-io branch 3 times, most recently from 0e34afb to d10b249 Compare November 9, 2026 15:13
@bska

bska commented Nov 9, 2026

Copy link
Copy Markdown
Member Author

jenkins build this please

@bska
bska force-pushed the modernise-low-level-file-io branch 4 times, most recently from d5157b6 to a744395 Compare November 12, 2026 08:55
@bska
bska requested a lite review from Copilot November 12, 2026 17:52

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.

🟡 Changes recommended

Moderate-severity active issues remain around binary I/O correctness—specifically potential partial-read garbage values and non–fixed-width integer sizing (e.g., LOGI using unsigned int) that can break the on-disk format or desynchronize streams on some platforms—so the change needs fixes before approval.

4 open issues
1 resolved since last review

Review effort: Lite

Comment thread opm/io/eclipse/ByteOrder.hpp Resolved
Comment thread opm/io/eclipse/EclIOdata.hpp Resolved
Comment thread opm/io/eclipse/EclOutput.cpp Resolved
Comment thread opm/io/eclipse/EclUtil.cpp Resolved
@bska
bska force-pushed the modernise-low-level-file-io branch 5 times, most recently from 65a3524 to c7ffd26 Compare November 16, 2026 15:17
@bska

bska commented Nov 16, 2026

Copy link
Copy Markdown
Member Author

jenkins build this please

@bska
bska force-pushed the modernise-low-level-file-io branch from c7ffd26 to 295185d Compare November 17, 2026 10:57
bska and others added 4 commits November 17, 2026 13:21
This commit introduces a new header, ByteOrder.hpp, with utilities for
converting numeric values between the host's native byte order and
the big-endian byte order used in "unformatted" result files.  The
utilities are

  * byteswap() -- Unconditionally reverse the bytes of a four or eight
    byte integer or floating-point value.
  * toFileOrder(), fromFileOrder() -- Convert between native and
    big-endian byte order.  Identity operations on big-endian hosts.
  * readFileOrder(), writeFileOrder() -- Read or write a single value,
    or a contiguous range of values, in big-endian byte order.

We implement byteswap() in terms of std::bit_cast<>() to a same-sized
unsigned integer type, and use std::byteswap() from C++23 if
available.  Otherwise we fall back to a shift-and-mask implementation
which mainstream compilers recognise and translate into a single byte
swap instruction.  This replaces the need for compiler intrinsics and
reinterpret_cast<>()-based byte reversals.

The header also asserts the platform assumptions of the binary file
I/O layer, i.e., 8-bit bytes, a purely little or big-endian host,
4-byte 'int', and IEEE 754 floating-point types.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit switches the low-level binary file I/O in EclUtil,
EclOutput, EGrid, and ESmry over to using the byte order utilities
from ByteOrder.hpp instead of the unconditional flipEndian*()
functions.  In turn, this removes the compiler specific byte swapping
intrinsics and makes the binary file I/O layer correct on big-endian
hosts.

As part of this, we also fix the handling of LOGI arrays.  These were
previously read and written without byte order conversion, with the
IX convention's 'true' value encoded as the little-endian
representation of a big-endian '1' (0x1000000).  LOGI elements now
pass through the same byte order conversion as INTE elements and the
'true_value_ix' constant is now 1.  The on-disk representation is
unchanged on little-endian hosts.

The callback of readBinaryArray<>() now receives numeric elements in
native byte order.  Its only outside user, ESmry, now uses
readBinaryInteArray() instead.

Keep the flipEndian*() functions for now, but mark them as deprecated.
They are implemented in terms of byteswap() and remain unconditional
byte swaps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit adds unit tests for the byte order utilities and for the
on-disk representation of binary INTE, REAL, DOUB, and LOGI arrays.
The latter compare the output of EclOutput against hand-written,
big-endian byte sequences--including LOGI arrays using the IX
convention--and read the same byte sequences back through EclFile.

These tests are independent of the host's byte order and are intended
to catch byte order errors if we ever run on big-endian hosts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The FileScalarRange concept admits immutable ranges such as
std::span<const T> and 'const std::vector<T>&'.  That is appropriate
for writeFileOrder(), which only reads the in-memory values, but not
for readFileOrder() which stores the values loaded from the file into
the range.  Passing an immutable range to readFileOrder() would fail
to compile, but with a diagnostic from inside the function body.

This commit introduces a new concept, FileOutputScalarRange, which
additionally requires that the range be an output range for its own
value type, and uses that to constrain readFileOrder().  Misuse is
now reported as an unsatisfied constraint at the call site.

Add compile-time tests of which range types readFileOrder() and
writeFileOrder() accept.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@bska
bska force-pushed the modernise-low-level-file-io branch from 295185d to e494a23 Compare November 17, 2026 12:54
@bska

bska commented Nov 17, 2026

Copy link
Copy Markdown
Member Author

jenkins build this please

@bska

bska commented Nov 17, 2026

Copy link
Copy Markdown
Member Author

I've tested this as much as I'm able to so I am, with much trepidation, marking it "ready for review".

@bska
bska marked this pull request as ready for review November 17, 2026 14:48

@akva2 akva2 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. Killing all those nasty reinterpret_casts makes for a good work day.

@bska

bska commented Nov 18, 2026

Copy link
Copy Markdown
Member Author

Killing all those nasty reinterpret_casts makes for a good work day.

It was indeed very satisfying.

As the PR's approved and the build check is green, I'll merge this into the master branch now.

@bska
bska merged commit 240967d into OPM:master Nov 18, 2026
2 checks passed
@bska
bska deleted the modernise-low-level-file-io branch November 18, 2026 08:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

manual:enhancement This is an enhancement/improvent that needs to be documented in the manual

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants