#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum WordKind {
Qualifier,
Builtin,
VectorType,
}
impl WordKind {
pub fn detail(self) -> &'static str {
match self {
WordKind::Qualifier => "CUDA qualifier",
WordKind::Builtin => "CUDA built-in variable",
WordKind::VectorType => "CUDA vector type",
}
}
}
#[derive(Debug, Clone, Copy)]
pub struct Word {
pub name: &'static str,
pub kind: WordKind,
pub detail: &'static str,
pub hover_key: &'static str,
}
impl Word {
pub fn takes_an_argument_list(&self) -> bool {
matches!(
self.name,
"__launch_bounds__" | "__maxnreg__" | "__align__" | "__cluster_dims__"
)
}
}
pub const QUALIFIERS: &[Word] = &[
Word {
name: "__global__",
kind: WordKind::Qualifier,
detail: "a kernel: called from host code, run on the device",
hover_key: "cuda.__global__",
},
Word {
name: "__device__",
kind: WordKind::Qualifier,
detail: "runs on the device: callable from a kernel or from another device function",
hover_key: "cuda.__device__",
},
Word {
name: "__host__",
kind: WordKind::Qualifier,
detail: "runs on the host: a function compiled for the CPU",
hover_key: "cuda.__host__",
},
Word {
name: "__shared__",
kind: WordKind::Qualifier,
detail: "a block-wide scratch array in shared memory",
hover_key: "cuda.__shared__",
},
Word {
name: "__constant__",
kind: WordKind::Qualifier,
detail: "read-only device memory written by the host",
hover_key: "cuda.__constant__",
},
Word {
name: "__managed__",
kind: WordKind::Qualifier,
detail: "memory accessible from both the host and the device",
hover_key: "cuda.__managed__",
},
Word {
name: "__grid_constant__",
kind: WordKind::Qualifier,
detail: "a kernel parameter read-only on the device, not copied per thread",
hover_key: "cuda.__grid_constant__",
},
Word {
name: "__restrict__",
kind: WordKind::Qualifier,
detail: "no aliasing through this pointer, as `restrict` is to C",
hover_key: "cuda.__restrict__",
},
Word {
name: "__launch_bounds__",
kind: WordKind::Qualifier,
detail: "the largest block, and the smallest block count, a kernel is launched with",
hover_key: "cuda.__launch_bounds__",
},
Word {
name: "__maxnreg__",
kind: WordKind::Qualifier,
detail: "the maximum number of registers a kernel's threads may use",
hover_key: "cuda.__maxnreg__",
},
Word {
name: "__align__",
kind: WordKind::Qualifier,
detail: "the alignment of a declaration, as `alignas` is to C++",
hover_key: "cuda.__align__",
},
Word {
name: "__cluster_dims__",
kind: WordKind::Qualifier,
detail: "the shape of the thread-block cluster this kernel is launched in",
hover_key: "cuda.__cluster_dims__",
},
Word {
name: "__forceinline__",
kind: WordKind::Qualifier,
detail: "always inline this function",
hover_key: "cuda.__forceinline__",
},
Word {
name: "__noinline__",
kind: WordKind::Qualifier,
detail: "never inline this function",
hover_key: "cuda.__noinline__",
},
];
pub const BUILTINS: &[Word] = &[
Word {
name: "threadIdx",
kind: WordKind::Builtin,
detail: "the index of this thread within its block, a `dim3`",
hover_key: "cuda.threadIdx",
},
Word {
name: "blockIdx",
kind: WordKind::Builtin,
detail: "the index of this block within the grid, a `dim3`",
hover_key: "cuda.blockIdx",
},
Word {
name: "blockDim",
kind: WordKind::Builtin,
detail: "the number of threads in this block, a `dim3`",
hover_key: "cuda.blockDim",
},
Word {
name: "gridDim",
kind: WordKind::Builtin,
detail: "the number of blocks in this grid, a `dim3`",
hover_key: "cuda.gridDim",
},
Word {
name: "warpSize",
kind: WordKind::Builtin,
detail: "the number of threads in a warp: 32 on every NVIDIA GPU so far",
hover_key: "cuda.warpSize",
},
];
pub const VECTOR_OTHERS: &[Word] = &[
Word {
name: "dim3",
kind: WordKind::VectorType,
detail: "three unsigned components, `.x .y .z`, used for a grid's and a block's shape",
hover_key: "cuda.dim3",
},
Word {
name: "__half",
kind: WordKind::VectorType,
detail: "a 16-bit floating-point value (`cuda_fp16.h`)",
hover_key: "cuda.__half",
},
Word {
name: "__half2",
kind: WordKind::VectorType,
detail: "two 16-bit floating-point values (`cuda_fp16.h`)",
hover_key: "cuda.__half2",
},
Word {
name: "__nv_bfloat16",
kind: WordKind::VectorType,
detail: "a 16-bit brain float (`cuda_bf16.h`)",
hover_key: "cuda.__nv_bfloat16",
},
];
macro_rules! vector_family {
($base:literal, $key:literal, $element:literal) => {
[
Word {
name: concat!($base, "1"),
kind: WordKind::VectorType,
detail: concat!("1 × ", $element, ", `.x`"),
hover_key: $key,
},
Word {
name: concat!($base, "2"),
kind: WordKind::VectorType,
detail: concat!("2 × ", $element, ", `.x .y`"),
hover_key: $key,
},
Word {
name: concat!($base, "3"),
kind: WordKind::VectorType,
detail: concat!("3 × ", $element, ", `.x .y .z`"),
hover_key: $key,
},
Word {
name: concat!($base, "4"),
kind: WordKind::VectorType,
detail: concat!("4 × ", $element, ", `.x .y .z .w`"),
hover_key: $key,
},
]
};
}
const VECTOR_FAMILIES: &[[Word; 4]] = &[
vector_family!("char", "cuda.vector_char", "a signed 8-bit integer"),
vector_family!("uchar", "cuda.vector_uchar", "an unsigned 8-bit integer"),
vector_family!("short", "cuda.vector_short", "a signed 16-bit integer"),
vector_family!("ushort", "cuda.vector_ushort", "an unsigned 16-bit integer"),
vector_family!("int", "cuda.vector_int", "a signed 32-bit integer"),
vector_family!("uint", "cuda.vector_uint", "an unsigned 32-bit integer"),
vector_family!("long", "cuda.vector_long", "a signed long"),
vector_family!("ulong", "cuda.vector_ulong", "an unsigned long"),
vector_family!(
"longlong",
"cuda.vector_longlong",
"a signed 64-bit integer"
),
vector_family!(
"ulonglong",
"cuda.vector_ulonglong",
"an unsigned 64-bit integer"
),
vector_family!("float", "cuda.vector_float", "a 32-bit float"),
vector_family!("double", "cuda.vector_double", "a 64-bit float"),
];
pub fn words() -> impl Iterator<Item = &'static Word> {
QUALIFIERS
.iter()
.chain(BUILTINS)
.chain(VECTOR_OTHERS)
.chain(VECTOR_FAMILIES.iter().flatten())
}
pub fn word(name: &str) -> Option<Word> {
words().find(|word| word.name == name).copied()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn every_word_is_listed_once_and_says_something() {
let words: Vec<&Word> = words().collect();
let mut names: Vec<&str> = words.iter().map(|word| word.name).collect();
let count = names.len();
names.sort_unstable();
names.dedup();
assert_eq!(names.len(), count, "a spelling is listed twice");
for word in words {
assert!(!word.detail.is_empty(), "{} has no description", word.name);
assert!(
word.hover_key.starts_with("cuda."),
"{} has a key outside the cuda section: {}",
word.name,
word.hover_key
);
}
}
#[test]
fn the_vocabulary_is_the_one_a_cuda_project_writes() {
let words: Vec<&Word> = words().collect();
let of = |kind: WordKind| words.iter().filter(|word| word.kind == kind).count();
assert_eq!(of(WordKind::Qualifier), 14);
assert_eq!(of(WordKind::Builtin), 5);
assert_eq!(of(WordKind::VectorType), 4 + VECTOR_FAMILIES.len() * 4);
assert_eq!(words.len(), 14 + 5 + 4 + 12 * 4);
}
#[test]
fn every_vector_family_has_one_to_four_components() {
for family in VECTOR_FAMILIES {
let base = family[0].name.trim_end_matches('1');
for components in 1..=4 {
let name = format!("{base}{components}");
let found = word(&name);
assert!(found.is_some(), "{name} is missing from the table");
assert_eq!(found.expect("just checked").kind, WordKind::VectorType);
}
assert!(
word(&format!("{base}5")).is_none(),
"{base}5 is not a type a toolkit declares"
);
}
}
#[test]
fn the_lookup_is_exact() {
assert!(word("threadIdx").is_some());
assert!(word("ThreadIdx").is_none());
assert!(word("threadidx").is_none());
assert!(word("").is_none());
assert!(
word("__CUDA_ARCH__").is_none(),
"device-only, deliberately absent"
);
assert!(
word("float").is_none(),
"a C++ keyword is not CUDA's vocabulary"
);
}
#[test]
fn the_parser_reads_every_qualifier_this_table_offers() {
for word in QUALIFIERS {
let source = if word.takes_an_argument_list() {
format!(
"__global__ void __global__x() {{ }}\n{} void f() {{ }}\n",
word.name
)
} else {
format!("{} void f() {{ }}\n", word.name)
};
let tree = cpp_parser::CppParser::parse(
&source,
cpp_parser::ParserConfig::default().with_cuda(true),
);
assert!(
tree.get_errors().is_empty(),
"`{}` is offered but does not parse as a specifier: {:?}\n{source}",
word.name,
tree.get_errors()
);
}
}
}