New user self-registration is disabled due to spam. Please email eigen-core-team @ lists.tuxfamily.org if you need an account.
Before reporting a bug, please make sure that your Eigen version is up-to-date!
Bug 1349 - Some compiler options, macros, version upgrades can break binary compatibility. Documentation should warn about this.
Summary: Some compiler options, macros, version upgrades can break binary compatibilit...
Status: NEW
Alias: None
Product: Eigen
Classification: Unclassified
Component: Core - vectorization (show other bugs)
Version: 3.3 (current stable)
Hardware: All All
: Normal Documentation
Assignee: Nobody
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2016-11-23 16:10 UTC by Zsbán Ambrus
Modified: 2016-11-23 16:10 UTC (History)
4 users (show)



Attachments

Description Zsbán Ambrus 2016-11-23 16:10:10 UTC
The ABI of Eigen can differ depending on the version of Eigen, certain compiler options and certain Eigen-specific macros the user is allowed to define.  The documentation warns about some of these in "http://eigen.tuxfamily.org/dox/TopicPreprocessorDirectives.html", but not all.  The documentation should be improved to make it more clear what exactly changes the ABI and what doesn't.

One particularly important aspect is alignment.  On x86_64 (and x86_32 too), Eigen sometimes decides that some data has to be aligned to 32 bytes, when it was previously aligned to only 16 bytes.  Alignment to 32 is active if you use Eigen version 3.3 or later (not the 3.2 branch) and tell the compiler to compile with AVX instructions.  This can change both the representation (size) of fixed size matrix types, but can also change what allocating functions are used for dynamic matrix types.  This means that if you compile a library that references Eigen types in its interface, then change compiler options to use AVX or upgrade to Eigen 3.3, then compile the rest of your program that way without recompiling the library, you could get mysterious silent memory corruptions in the worst case.  The case of enabling AVX instructions is particularly problematic, because people often use a higher instruction set for their programs than what the precompiled libraries installed on their system use.  (Relevant gcc options include -march=*, -mavx, -mavx2)  Enabling AVX2 instruction sets might also affect alignment, I don't know if it does.

Certain Eigen-specific macros the user can define also affect the ABI: these include EIGEN_DONT_ALIGN, EIGEN_DONT_ALIGN_STATICALLY, EIGEN_MALLOC_ALREADY_ALIGNED, EIGEN_MAX_STATIC_ALIGN_BYTES, EIGEN_MAX_ALIGN_BYTES, EIGEN_DEFAULT_DENSE_INDEX_TYPE, EIGEN_DEFAULT_TO_ROW_MAJOR.

The documentation should warn about surprising ABI break situations, especially ones that could cause silent memory corruption or other misbehaviour (as opposed to merely crashes or link errors).  It should try to make it clear, as much as possible, which compiler options, version differences and macros can affect binary compatibility.  (For the compiler options, it's enough to mention those options that do not normally change binary compatibility of typical libraries.)  Yes, this is difficult.

Note You need to log in before you can comment on or make changes to this bug.