refactoring for more flexibility

Author: benedekkupper

.github/workflows/cmake-multi-platform.yml

@@ -0,0 +1,71 @@
+# This starter workflow is for a CMake project running on multiple platforms. There is a different starter workflow if you just want a single platform.
+# See: https://github.com/actions/starter-workflows/blob/main/ci/cmake-single-platform.yml
+name: CMake on multiple platforms
+
+on:
+  push:
+    branches: [ "main", "develop" ]
+  pull_request:
+    branches: [ "main", "develop" ]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      # Set fail-fast to false to ensure that feedback is delivered for all matrix combinations. Consider changing this to true when your workflow is stable.
+      fail-fast: false
+
+      # Set up a matrix to run the following 3 configurations:
+      # 1. <Windows, Release, latest MSVC compiler toolchain on the default runner image, default generator>
+      # 2. <Linux, Release, latest GCC compiler toolchain on the default runner image, default generator>
+      # 3. <Linux, Release, latest Clang compiler toolchain on the default runner image, default generator>
+      #
+      # To add more build types (Release, Debug, RelWithDebInfo, etc.) customize the build_type list.
+      matrix:
+        os: [ubuntu-latest]
+        build_type: [Release]
+        c_compiler: [gcc, clang, cl]
+        include:
+          - os: ubuntu-latest
+            c_compiler: gcc
+            cpp_compiler: g++
+          - os: ubuntu-latest
+            c_compiler: clang
+            cpp_compiler: clang++
+        exclude:
+          - os: ubuntu-latest
+            c_compiler: cl
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set reusable strings
+      # Turn repeated input strings (such as the build output directory) into step outputs. These step outputs can be used throughout the workflow file.
+      id: strings
+      shell: bash
+      run: |
+        echo "build-output-dir=${{ github.workspace }}/build" >> "$GITHUB_OUTPUT"
+
+    - name: Configure CMake
+      # Configure CMake in a 'build' subdirectory. `CMAKE_BUILD_TYPE` is only required if you are using a single-configuration generator such as make.
+      # See https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html?highlight=cmake_build_type
+      run: >
+        cmake -B ${{ steps.strings.outputs.build-output-dir }}
+        -DCMAKE_CXX_COMPILER=${{ matrix.cpp_compiler }}
+        -DCMAKE_C_COMPILER=${{ matrix.c_compiler }}
+        -DCMAKE_BUILD_TYPE=${{ matrix.build_type }}
+        -S ${{ github.workspace }}
+
+    - name: Build
+      # Build your program with the given configuration. Note that --config is needed because the default Windows generator is a multi-config generator (Visual Studio generator).
+      run: cmake --build ${{ steps.strings.outputs.build-output-dir }} --config ${{ matrix.build_type }}
+
+    - name: Test
+      working-directory: ${{ steps.strings.outputs.build-output-dir }}
+      # Execute tests defined by the CMake configuration. Note that --build-config is needed because the default Windows generator is a multi-config generator (Visual Studio generator).
+      # See https://cmake.org/cmake/help/latest/manual/ctest.1.html for more detail
+      run: ctest --build-config ${{ matrix.build_type }}

.github/workflows/cmake-single-platform.yml

@@ -0,0 +1,55 @@
+name: "CodeQL Advanced"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+    - cron: '25 3 * * 2'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: 'ubuntu-latest'
+    permissions:
+      # required for all workflows
+      security-events: write
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: actions
+          build-mode: none
+        - language: c-cpp
+          build-mode: autobuild
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    # Add any setup steps before running the `github/codeql-action/init` action.
+    # This includes steps like installing compilers or runtimes (`actions/setup-node`
+    # or others). This is typically only required for manual builds.
+    # - name: Setup runtime (example)
+    #   uses: actions/setup-example@v1
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v3
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+
+        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # queries: security-extended,security-and-quality
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3
+      with:
+        category: "/language:${{matrix.language}}"

.github/workflows/codeql.yml

@@ -19,13 +19,21 @@ struct legacy
 
 We can manipulate each field as normal members of `struct legacy`, their values don't cross bit boundaries,
 the signed integers even get sign extended, that's all well.
-However, the `legacy` type itself cannot be assigned to any other type.
+There are a number of drawbacks to using standard bitfields, such as:
+1. Lack of standardization (and thus portability),
+a C++ compiler implementation can freely decide how these bits are stored in memory
+(see also [bitfield traits](./bitfilled/bitfield_traits.hpp) for an overview).
+2. Lack of flexibility,
+e.g. they may only have integral or enum type,
+they cannot be passed by reference,
+nor can they be organized into arrays, etc.
+
 This is a problem in many use cases involving bit-fields. So let's solve that:
 
 ```cpp
-struct nextgen : public bitfilled::host<std::uint8_t>
+struct nextgen : bitfilled::host_integer<std::uint8_t>
 {
-    using superclass::operator=;
+    BF_COPY_SUPERCLASS(nextgen)
     BF_BITS(bool, 0) boolean;
     BF_BITS(std::endian, 1, 2) enumerated;
     BF_BITS(std::int32_t, 3, 7) integer;
@@ -34,7 +42,7 @@ struct nextgen : public bitfilled::host<std::uint8_t>
 
 Our `nextgen` type's bit-fields work with the exact same syntax as their `legacy` counterparts.
 The difference here is that a `nextgen` object can be converted to and from any `uint8_t` type,
-no more sketchy casting necessary to get the underlying integer type.
+no more explicit casting necessary to get the underlying integer type.
 One thing to note is that the nextgen fields have absolute bit offsets, as opposed to the legacy
 fields (which in turn only have a bit size specifier).
 This characteristic of the behavior also means that nextgen's bit-fields can be made to overlap one another.
@@ -44,21 +52,25 @@ This characteristic of the behavior also means that nextgen's bit-fields can be
 The bitfilled logic consists of two building blocks, that work in tandem to provide the desired functionality:
 1. The bitfilled member variables hold the bit-field's **properties** (`props`): the position of the bits and the access rights,
 and also - indirectly - the memory location of the bits (more on that later).
-2. The encapsulating object type provides the **operators** (`ops`), which are used by the bitfilled members
+2. The encapsulating object type defines the **operators** (`ops`), which are used by the bitfilled members
 to perform the memory access and bit operations needed to read or modify the bit-field.
 
 The term "property" is used to refer to the bitfilled members due to them functioning as [properties][property wiki]
 as known in other programming languages (C# and Python to name a few):
  - they don't increase the size of the encapsulating type [(achieved with `[[no_unique_address]]`)](https://en.cppreference.com/w/cpp/language/attributes/no_unique_address)
  - their value is derived from the encapsulating type's state
 
+Note that `[[no_unique_address]]` isn't effective when two bitfields with the same type parameters are defined,
+(i.e. same value type, access, operations, bit position) as the C++ core rule of unique identity would be violated
+(this applies even if the two bitfield types are distinct, but inherit the same base class).
+
 The key point to understand, and the reason for the design requiring the *operators* in the tandem, is this:
 By dereferencing their address, the bitfilled members provide access to memory that is not theirs,
 but rather whichever member is preceeding them in the encapsulating type layout.
 Therefore the encapsulating type must have a preceeding member variable for bit-field use,
 and the bitfilled members must be made aware of this member variable's type - this is what the operators are achieving.
 Mismatches between the storage member variable and the operators type is impossible to catch at compile time,
-therefore it is recommended to use predefined helper base classes such as `bitfilled::host` and `bitfilled::mmr`,
+therefore it is recommended to use predefined helper base classes such as `bitfilled::host_integer` and `bitfilled::mmreg`,
 instead of defining the storage member variable and the operators independently.
 
 ## Memory mapped registers

README.md

@@ -3,6 +3,8 @@ target_sources(${PROJECT_NAME}
         ${CMAKE_CURRENT_SOURCE_DIR}/bitfilled.hpp
         ${CMAKE_CURRENT_SOURCE_DIR}/bitfield_traits.hpp
         ${CMAKE_CURRENT_SOURCE_DIR}/${PROJECT_NAME}/access.hpp
+        ${CMAKE_CURRENT_SOURCE_DIR}/${PROJECT_NAME}/base_ops.hpp
+        ${CMAKE_CURRENT_SOURCE_DIR}/${PROJECT_NAME}/bitband_ops.hpp
         ${CMAKE_CURRENT_SOURCE_DIR}/${PROJECT_NAME}/bits.hpp
         ${CMAKE_CURRENT_SOURCE_DIR}/${PROJECT_NAME}/integer.hpp
         ${CMAKE_CURRENT_SOURCE_DIR}/${PROJECT_NAME}/macros.hpp

bitfilled/CMakeLists.txt

@@ -49,6 +49,7 @@ constexpr inline bool has_padding_field = []() constexpr
 }();
 
 // bit-field endianness is either little (least significant bit field first), or big
+#if defined(__GNUC__) && (__GNUC__ >= 11)
 constexpr inline std::endian endianness = []() constexpr
 {
     constexpr struct s
@@ -60,6 +61,18 @@ constexpr inline std::endian endianness = []() constexpr
     static_assert(x);
     return x == 1 ? std::endian::little : std::endian::big;
 }();
+#else
+inline std::endian endianness = []()
+{
+    struct s
+    {
+        char a : 1 = 1;
+        char b : 7 = 0;
+    } val;
+    static const auto x = std::bit_cast<std::array<char, bitfilled::aligned_size<s>>>(val).front();
+    return x == 1 ? std::endian::little : std::endian::big;
+}();
+#endif
 
 // an implementation either wraps overflows, or clamps them
 constexpr inline bool overflow_wraps = []() constexpr

bitfilled/bitfield_traits.hpp

@@ -1,4 +1,4 @@
+#include "bitfilled/bitband_ops.hpp"
 #include "bitfilled/bits.hpp"
-#include "bitfilled/bitband.hpp"
 #include "bitfilled/macros.hpp"
 #include "bitfilled/mmreg.hpp"