|
| 1 | +//! Memory operations, analyses and transformations. |
| 2 | +// |
| 3 | +// FIXME(eddyb) document at least these aspects: |
| 4 | +// - "memory" = indirect storage of data and/or resources |
| 5 | +// - (untyped) "data" = mix of plain bytes and pointers (as per RalfJ blog post) |
| 6 | +// (does "non-data memory" actually make sense? could be considered typed?) |
| 7 | +// |
| 8 | +// FIXME(eddyb) dig into past notes (e.g. `qptr::legalize`, Rust-GPU release notes, |
| 9 | +// https://github.com/EmbarkStudios/spirt/pull/24, etc.) for useful docs. |
| 10 | +// |
| 11 | +// FIXME(eddyb) consider taking this into a more (R)VSDG "state type" direction. |
| 12 | + |
| 13 | +use crate::{OrdAssertEq, Type}; |
| 14 | +use std::collections::BTreeMap; |
| 15 | +use std::num::NonZeroU32; |
| 16 | +use std::rc::Rc; |
| 17 | + |
| 18 | +// NOTE(eddyb) all the modules are declared here, but they're documented "inside" |
| 19 | +// (i.e. using inner doc comments). |
| 20 | +pub mod analyze; |
| 21 | +// FIXME(eddyb) make this public? |
| 22 | +pub(crate) mod layout; |
| 23 | +pub mod shapes; |
| 24 | + |
| 25 | +pub use layout::LayoutConfig; |
| 26 | + |
| 27 | +/// Memory-specific attributes ([`Attr::Mem`]). |
| 28 | +#[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] |
| 29 | +pub enum MemAttr { |
| 30 | + /// When applied to a `GlobalVar` or `FuncLocalVar`, this tracks all possible |
| 31 | + /// access patterns its memory may be subjected to (see [`MemAccesses`]). |
| 32 | + Accesses(OrdAssertEq<MemAccesses>), |
| 33 | +} |
| 34 | + |
| 35 | +#[derive(Clone, PartialEq, Eq, Hash)] |
| 36 | +pub enum MemAccesses { |
| 37 | + /// Accesses to one or more handles (i.e. optionally indexed by |
| 38 | + /// [`crate::qptr::QPtrOp::HandleArrayIndex`]), which can be: |
| 39 | + /// - `Handle::Opaque(handle_type)`: all accesses involve [`MemOp::Load`] or |
| 40 | + /// [`crate::qptr::QPtrAttr::ToSpvPtrInput`], with the common type `handle_type` |
| 41 | + /// - `Handle::Buffer(data_happ)`: carries with it `data_happ`, |
| 42 | + /// i.e. the access patterns for the memory that is reached through |
| 43 | + /// [`crate::qptr::QPtrOp::BufferData`] |
| 44 | + Handles(shapes::Handle<DataHapp>), |
| 45 | + |
| 46 | + Data(DataHapp), |
| 47 | +} |
| 48 | + |
| 49 | +/// Data HAPP ("Hierarchical Access Pattern Partitioning"): all access patterns |
| 50 | +/// for some memory, structured by disjoint offset ranges ("partitions"). |
| 51 | +/// |
| 52 | +/// This is the core of "type recovery" (inferring typed memory from untyped), |
| 53 | +/// with "struct/"array" equivalents (i.e. as `DataHappKind` variants), but |
| 54 | +/// while it can be mapped to an explicitly laid out data type, it also tracks |
| 55 | +/// distinctions only needed during merging (e.g. [`DataHappKind::StrictlyTyped`]). |
| 56 | +/// |
| 57 | +/// **Note**: the only reason for the recursive/"hierarchical" aspect is that |
| 58 | +/// (array-like) dynamic indexing allows for compact representation of repeated |
| 59 | +/// patterns, which can non-trivially nest for 3+ levels without losing the need |
| 60 | +/// for efficient representation - in fact, one can construct a worst-case like: |
| 61 | +/// ```ignore |
| 62 | +/// [(A, [(B, [(C, [(D, [T; N], X); 2], Y); 2], Z); 2], W); 2] |
| 63 | +/// ``` |
| 64 | +/// (with only `N * 2**4` leaf `T`s because of the 4 `[(_, ..., _); 2]` levels, |
| 65 | +/// and the potential for dozens of such levels while remaining a plausible size) |
| 66 | +// |
| 67 | +// FIXME(eddyb) reconsider the name (acronym was picked to avoid harder decisions). |
| 68 | +#[derive(Clone, PartialEq, Eq, Hash)] |
| 69 | +pub struct DataHapp { |
| 70 | + /// If present, this is a worst-case upper bound on the offsets at which |
| 71 | + /// accesses may be perfomed. |
| 72 | + // |
| 73 | + // FIXME(eddyb) use proper newtypes for byte amounts. |
| 74 | + // |
| 75 | + // FIXME(eddyb) suboptimal naming choice, but other options are too verbose, |
| 76 | + // including maybe using `RangeTo<_>` to explicitly indicate "exclusive". |
| 77 | + // |
| 78 | + // FIXME(eddyb) consider renaming such information to "extent", but that might |
| 79 | + // be ambiguous with an offset range (as opposed to using the maximum of all |
| 80 | + // *possible* `offset_range.end` values to describe a "maximum size"). |
| 81 | + pub max_size: Option<u32>, |
| 82 | + |
| 83 | + pub kind: DataHappKind, |
| 84 | +} |
| 85 | + |
| 86 | +impl DataHapp { |
| 87 | + pub const DEAD: Self = Self { max_size: Some(0), kind: DataHappKind::Dead }; |
| 88 | +} |
| 89 | + |
| 90 | +#[derive(Clone, PartialEq, Eq, Hash)] |
| 91 | +pub enum DataHappKind { |
| 92 | + /// Not actually accessed (only an intermediary state, during access analysis). |
| 93 | + // |
| 94 | + // FIXME(eddyb) use `Option<DataHapp>` instead? or an empty `Disjoint`? |
| 95 | + Dead, |
| 96 | + |
| 97 | + // FIXME(eddyb) replace the two leaves with e.g. `Leaf(Type, LeafAccessKind)`. |
| 98 | + // |
| 99 | + // |
| 100 | + /// Accesses through typed pointers (e.g. via unknown SPIR-V instructions), |
| 101 | + /// requiring a specific choice of pointee type which cannot be modified, |
| 102 | + /// and has to be reused as-is, when lifting to typed memory. |
| 103 | + /// |
| 104 | + /// Other overlapping accesses can be merged into this one as long as they |
| 105 | + /// can be fully expressed using the (transitive) components of this type. |
| 106 | + StrictlyTyped(Type), |
| 107 | + |
| 108 | + /// Direct accesses (e.g. [`MemOp::Load`], [`MemOp::Store`]), which can be |
| 109 | + /// decomposed as necessary (down to individual scalar leaves), to allow |
| 110 | + /// maximal merging opportunities. |
| 111 | + // |
| 112 | + // FIXME(eddyb) track whether accesses are `Load`s and/or `Store`s, to allow |
| 113 | + // inferring `NonWritable`/`NonReadable` annotations, as well. |
| 114 | + Direct(Type), |
| 115 | + |
| 116 | + /// Partitioning into disjoint offset ranges (the map is keyed by the start |
| 117 | + /// of the offset range, while the end is implied by its corresponding value), |
| 118 | + /// requiring a "struct" type, when lifting to typed memory. |
| 119 | + // |
| 120 | + // FIXME(eddyb) make this non-nestable and the fundamental basis of "HAPP". |
| 121 | + Disjoint(Rc<BTreeMap<u32, DataHapp>>), |
| 122 | + |
| 123 | + /// `Disjoint` counterpart for dynamic offsetting, requiring an "array" type, |
| 124 | + /// when lifting to typed memory, with one single element type being repeated |
| 125 | + /// across the entire size, at all offsets that are a multiple of `stride`. |
| 126 | + Repeated { |
| 127 | + // FIXME(eddyb) this feels inefficient. |
| 128 | + element: Rc<DataHapp>, |
| 129 | + stride: NonZeroU32, |
| 130 | + }, |
| 131 | +} |
| 132 | + |
| 133 | +/// Memory-specific operations ([`DataInstKind::Mem`]). |
| 134 | +#[derive(Clone, PartialEq, Eq, Hash)] |
| 135 | +pub enum MemOp { |
| 136 | + // HACK(eddyb) `OpVariable` replacement, which itself should not be kept as |
| 137 | + // a `SpvInst` - once fn-local variables are lowered, this should go there. |
| 138 | + FuncLocalVar(shapes::MemLayout), |
| 139 | + |
| 140 | + /// Read a single value from a pointer (`inputs[0]`). |
| 141 | + // |
| 142 | + // FIXME(eddyb) limit this to data - and scalars, maybe vectors at most. |
| 143 | + Load, |
| 144 | + |
| 145 | + /// Write a single value (`inputs[1]`) to a pointer (`inputs[0]`). |
| 146 | + // |
| 147 | + // FIXME(eddyb) limit this to data - and scalars, maybe vectors at most. |
| 148 | + Store, |
| 149 | + // |
| 150 | + // FIXME(eddyb) implement more ops (e.g. copies, atomics). |
| 151 | +} |
0 commit comments