ZXFoundation™ 26h2
Loading...
Searching...
No Matches
types.cxxm
Go to the documentation of this file.
1/// SPDX-License-Identifier: Apache-2.0
2/// @file zxfoundation/dgp/cap.zcomponent/types.cxxm
3/// @brief Capability system type definitions — opaque resource tokens for
4/// the DGP kernel's capability-based authorization model.
5
6export module zxfoundation.dgp.cap.types;
7import zxfoundation.base.types;
8
9export {
10
11namespace zxfoundation::dgp::cap {
12
13 /// @brief Discriminator for the kind of resource a capability token refers to.
14 enum class cap_type : u16 {
15 none = 0, ///< Invalid / null capability.
16 domain = 1, ///< Reference to a domain.
17 gate = 2, ///< Reference to a gate.
18 portal = 3, ///< Reference to a portal.
19 io_device = 5, ///< Reference to an I/O device binding.
20 memory = 6, ///< Reference to a memory grant authority.
21 service = 7, ///< Reference to a service registry entry.
22 admin = 8, ///< Administrative authority (domain mgmt, etc.).
23 memory_extent = 9, ///< Exact physical range authorized for mapping.
24 };
25
26 /// @brief Return a human-readable label for a capability type.
27 [[nodiscard]] constexpr auto cap_type_name(cap_type t) noexcept -> const char* {
28 switch (t) {
29 case cap_type::none: return "none";
30 case cap_type::domain: return "domain";
31 case cap_type::gate: return "gate";
32 case cap_type::portal: return "portal";
33 case cap_type::io_device: return "io_device";
34 case cap_type::memory: return "memory";
35 case cap_type::service: return "service";
36 case cap_type::admin: return "admin";
37 case cap_type::memory_extent: return "memory_extent";
38 default: return "unknown";
39 }
40 }
41
42 /// @brief Standard access rights usable with any capability type.
43 enum class cap_rights : u16 {
44 none = 0,
45 read = 1U << 0, ///< Read / view the resource.
46 write = 1U << 1, ///< Write / modify the resource.
47 exec = 1U << 2, ///< Execute / invoke the resource.
48 destroy = 1U << 3, ///< Destroy the resource.
49 delegate = 1U << 4, ///< Delegate this capability to another domain.
50 admin = 1U << 5, ///< Administrative operations (domain create/destroy).
51 map = 1U << 6, ///< Map physical memory into address space.
52 all = 0xFFFFU, ///< All rights.
53 };
54
55 [[nodiscard]] constexpr auto operator|(cap_rights a, cap_rights b) noexcept -> cap_rights {
56 return static_cast<cap_rights>(static_cast<u16>(a) | static_cast<u16>(b));
57 }
58
59 [[nodiscard]] constexpr auto operator&(cap_rights a, cap_rights b) noexcept -> cap_rights {
60 return static_cast<cap_rights>(static_cast<u16>(a) & static_cast<u16>(b));
61 }
62
63 [[nodiscard]] constexpr auto operator~(cap_rights r) noexcept -> cap_rights {
64 return static_cast<cap_rights>(~static_cast<u16>(r));
65 }
66
67 /// @brief Opaque 64-bit capability token.
68 /// @note Tokens are value types (copyable, movable).
69 struct cap_token {
70 u64 raw{0}; ///< Raw 64-bit encoding.
71
72 constexpr cap_token() noexcept = default;
73 constexpr explicit cap_token(u64 v) noexcept : raw(v) {}
74
75 /// @brief Construct a token from its components.
76 /// @param[in] type Resource type discriminator.
77 /// @param[in] obj_id Nucleus capability-slot index.
78 /// @param[in] gen Object generation counter.
79 /// @param[in] rights Delegated rights mask.
80 static constexpr auto make(
81 cap_type type,
82 u16 obj_id,
83 u16 gen,
84 cap_rights rights
85 ) noexcept -> cap_token {
86 return cap_token(
87 (static_cast<u64>(rights) << 48) |
88 (static_cast<u64>(gen) << 32) |
89 (static_cast<u64>(obj_id) << 16) |
90 static_cast<u64>(type)
91 );
92 }
93
94 /// @brief Extract the type field.
95 [[nodiscard]] constexpr auto type() const noexcept -> cap_type {
96 return static_cast<cap_type>(raw & 0xFFFFU);
97 }
98
99 /// @brief Extract the object ID field.
100 [[nodiscard]] constexpr auto object_id() const noexcept -> u16 {
101 return static_cast<u16>((raw >> 16) & 0xFFFFU);
102 }
103
104 /// @brief Extract the generation field.
105 [[nodiscard]] constexpr auto generation() const noexcept -> u16 {
106 return static_cast<u16>((raw >> 32) & 0xFFFFU);
107 }
108
109 /// @brief Extract the rights mask.
110 [[nodiscard]] constexpr auto rights() const noexcept -> cap_rights {
111 return static_cast<cap_rights>((raw >> 48) & 0xFFFFU);
112 }
113
114 /// @brief Check whether a specific right is present.
115 [[nodiscard]] constexpr auto has_right(cap_rights r) const noexcept -> bool {
116 return (static_cast<u16>(rights()) & static_cast<u16>(r)) != 0;
117 }
118
119 /// @brief Derive a new token with a subset of the rights.
120 /// @param[in] subset Rights to retain in the derived token.
121 [[nodiscard]] constexpr auto derive(cap_rights subset) const noexcept -> cap_token {
122 return make(type(), object_id(), generation(),
123 rights() & subset);
124 }
125
126 /// @brief Check whether the token is valid (non-null).
127 [[nodiscard]] constexpr explicit operator bool() const noexcept {
128 return raw != 0 && type() != cap_type::none;
129 }
130
131 /// @brief Compare two tokens for equality.
132 [[nodiscard]] constexpr auto operator==(cap_token o) const noexcept -> bool {
133 return raw == o.raw;
134 }
135
136 [[nodiscard]] constexpr auto operator!=(cap_token o) const noexcept -> bool {
137 return raw != o.raw;
138 }
139 };
140
141 /// @brief Null / invalid capability token sentinel.
142 inline constexpr cap_token CAP_TOKEN_NULL{};
143
144 /// @brief Sentinel value indicating an error from capability operations.
145 inline constexpr u64 CAP_ERROR_SENTINEL = ~0ULL;
146
147} // namespace zxfoundation::dgp::cap
148
149} // end export