types.cxxm

Go to the documentation of this file.

/// SPDX-License-Identifier: Apache-2.0
/// @file zxfoundation/dgp/isolation.zcomponent/types.cxxm
/// @brief Hardware-first DGP isolation policy and lifecycle types.
 
export module zxfoundation.dgp.isolation.types;
import zxfoundation.base.types;
import zxfoundation.base.typestate;
import arch.s390x.mmu.types;
 
export {
 
namespace zxfoundation::dgp::isolation {
 
    /// @brief Storage key value requesting automatic allocation by DGP policy.
    inline constexpr u8 STORAGE_KEY_AUTO = 0xFFU;
 
    /// @brief Number of architected storage-key access-control values.
    inline constexpr u8 STORAGE_KEY_COUNT = 16U;
 
    /// @brief First user-domain storage key retained for non-nucleus domains.
    inline constexpr u8 STORAGE_KEY_USER_BASE = 8U;
 
    /// @brief Last user-domain storage key retained for non-nucleus domains.
    inline constexpr u8 STORAGE_KEY_USER_MAX = 15U;
 
    /// @brief Hardware isolation facilities required by a DGP policy.
    enum class isolation_feature : u64 {
        none             = 0ULL,
        dat_asce         = 1ULL << 0,
        storage_key      = 1ULL << 1,
        program_call     = 1ULL << 2,
        access_register  = 1ULL << 3,
        edat_large_page  = 1ULL << 4,
        numa_policy      = 1ULL << 5,
        transactional_vm = 1ULL << 6,
        smp_invalidation = 1ULL << 7,
    };
 
    /// @brief Revocation phase for a storage key held by a DGP domain.
    enum class skey_revocation_state : u8 {
        none = 0,
        active = 1,
        draining = 2,
        reusable = 3,
    };
 
    /// @brief Authority bits interpreted by the DGP policy plane.
    enum class isolation_rights : u32 {
        none      = 0U,
        enter     = 1U << 0,   ///< Cross-domain gate entry.
        map       = 1U << 1,   ///< Map physical memory into own address space.
        share     = 1U << 2,   ///< Share memory across domain boundaries.
        signal    = 1U << 3,   ///< Send/receive cross-domain signals.
        io        = 1U << 4,   ///< Bind and operate I/O devices.
        lifecycle = 1U << 5,   ///< Create/destroy sub-domains, gates, portals.
        delegate  = 1U << 6,   ///< Delegate capabilities to other domains.
        quota     = 1U << 7,   ///< Allocate physical pages, DMA pools, I/O slots.
        debug     = 1U << 8,   ///< Inspect other domains' state (query, info).
        sched     = 1U << 9,   ///< Create strands, set scheduling parameters.
        console   = 1U << 10,  ///< Write to system console.
        service   = 1U << 11,  ///< Register/lookup/unregister named services.
        all       = 0x0000'FFFFU,  ///< All rights (nucleus only).
    };
 
    /// @brief Combine two feature masks.
    /// @param[in] lhs Left-hand feature mask.
    /// @param[in] rhs Right-hand feature mask.
    /// @return Combined feature mask.
    [[nodiscard]] constexpr auto operator|(
        isolation_feature lhs,
        isolation_feature rhs
    ) noexcept -> isolation_feature {
        return static_cast<isolation_feature>(
            static_cast<u64>(lhs) | static_cast<u64>(rhs));
    }
 
    /// @brief Intersect two feature masks.
    /// @param[in] lhs Left-hand feature mask.
    /// @param[in] rhs Right-hand feature mask.
    /// @return Common feature mask.
    [[nodiscard]] constexpr auto operator&(
        isolation_feature lhs,
        isolation_feature rhs
    ) noexcept -> isolation_feature {
        return static_cast<isolation_feature>(
            static_cast<u64>(lhs) & static_cast<u64>(rhs));
    }
 
    /// @brief Combine two right masks.
    /// @param[in] lhs Left-hand right mask.
    /// @param[in] rhs Right-hand right mask.
    /// @return Combined right mask.
    [[nodiscard]] constexpr auto operator|(
        dgp::isolation::isolation_rights lhs,
        dgp::isolation::isolation_rights rhs
    ) noexcept -> dgp::isolation::isolation_rights {
        return static_cast<dgp::isolation::isolation_rights>(
            static_cast<u32>(lhs) | static_cast<u32>(rhs));
    }
 
    /// @brief Intersect two right masks.
    /// @param[in] lhs Left-hand right mask.
    /// @param[in] rhs Right-hand right mask.
    /// @return Common right mask.
    [[nodiscard]] constexpr auto operator&(
        dgp::isolation::isolation_rights lhs,
        dgp::isolation::isolation_rights rhs
    ) noexcept -> dgp::isolation::isolation_rights {
        return static_cast<dgp::isolation::isolation_rights>(
            static_cast<u32>(lhs) & static_cast<u32>(rhs));
    }
 
    /// @brief Test that all requested features are present.
    /// @param[in] available Available feature mask.
    /// @param[in] requested Required feature mask.
    /// @return true when every requested feature is present.
    [[nodiscard]] constexpr auto has_all_features(
        isolation_feature available,
        isolation_feature requested
    ) noexcept -> bool {
        return (static_cast<u64>(available & requested) == static_cast<u64>(requested));
    }
 
    /// @brief Test that all requested rights are present.
    /// @param[in] available Available right mask.
    /// @param[in] requested Required right mask.
    /// @return true when every requested right is present.
    [[nodiscard]] constexpr auto has_all_rights(
        dgp::isolation::isolation_rights available,
        dgp::isolation::isolation_rights requested
    ) noexcept -> bool {
        return (static_cast<u32>(available & requested) == static_cast<u32>(requested));
    }
 
    /// @brief Domain policy supplied to the DGP isolation core.
    struct isolation_policy {
        isolation_feature required_features{isolation_feature::none};
        dgp::isolation::isolation_rights default_rights{dgp::isolation::isolation_rights::none};
        u8 storage_key{STORAGE_KEY_AUTO};
        u8 numa_node{0};
        bool allow_portals{false};
        bool allow_user_execute{false};
        bool bootstrap_admin{false};
    };
 
    /// @brief Hardware-backed state recorded for one DGP isolation domain.
    struct isolation_domain_state {
        u32 domain_id{0};
        arch::s390x::mmu::typed_asce<arch::s390x::mmu::dat_level::region_1> asce{};
        u64 root_phys{0};
        u8 storage_key{0};
        u8 numa_node{0};
        u16 revocation_epoch{0};
        u32 storage_key_generation{0};
        skey_revocation_state storage_key_state{skey_revocation_state::none};
        dgp::isolation::isolation_rights granted_rights{dgp::isolation::isolation_rights::none};
    };
 
    static_assert(sizeof(isolation_feature) == sizeof(u64), "DGP feature mask must remain 64-bit");
    static_assert(sizeof(dgp::isolation::isolation_rights) == sizeof(u32), "DGP rights mask must remain 32-bit");
    static_assert(sizeof(zxfoundation::base::lifecycle_state) == sizeof(u8), "DGP lifecycle state must remain byte-sized");
    static_assert(sizeof(skey_revocation_state) == sizeof(u8), "DGP storage-key revocation state must remain byte-sized");
    static_assert(static_cast<u8>(zxfoundation::base::lifecycle_state::embryo) == 0U, "Embryo must be the zero state");
    static_assert(static_cast<u8>(skey_revocation_state::none) == 0U, "Storage-key revocation none state must be zero");
    static_assert(static_cast<u32>(dgp::isolation::isolation_rights::all) == 0x0000'FFFFU, "all rights must be the low 16 bits");
    static_assert(STORAGE_KEY_USER_MAX < STORAGE_KEY_COUNT, "User storage-key range exceeds architected key count");
 
} // namespace zxfoundation::dgp
 
} // end export