Proposal

Add a new compiler intrinsic called codeview_annotation which lowers to llvm.codeview.annotation and allows users to emit arbitrary S_ANNOTATION records into PDB files on Windows.

Relevant PR rust-lang/rust#160285

Motivation

In Microsoft we are working on supporting Windows driver development in Rust. codeview_annotation is needed to implement a feature called WPP tracing which requires strings from trace statements to be written to the PDB at compile time.

Basically the user writes a trace statement like this in the driver:

trace!("Bytes {}, duration {} ms", byte_count, elapsed_ms);

and it expands to a call to codeview_annotation with the format string "Bytes {}, duration {} ms" plus some other metadata such as the types of byte_count and elapsed_ms and all the strings get written to the PDB.

Later at runtime trace viewing tools extract those strings from the PDB, combine them with the stream of variables (e.g. byte_count and elapsed_ms) coming out of the running driver and produce a human readable log.

This keeps tracing efficient by avoiding costly I/O of strings at runtime and also helps with not leaking implementation details of drivers.

The intrinsic could also be useful in general for other use cases where you need to embed some user-specific information in the PDB.

API

The intrinsic is declared as:

pub trait CodeViewAnnotationArgs {
    const ARGS: &[&str];  // <-- Strings you want to emit in the PDB go here
}

pub fn codeview_annotation<T: CodeViewAnnotationArgs>();

wherein the CodeViewAnnotationArgs trait is used to ensure that the args are compile-time constants not run-time values.

The intrinsic is exposed publicly through a std lib function as shown below:

pub fn codeview_annotation<T: CodeViewAnnotationArgs>() {
    intrinsics::codeview_annotation::<T>(); // invokes the intrinsic
}

Usage

To call the intrinsic users will:

• Declare a type (say Args) and implement CodeViewAnnotationArgs on it. The type can be generic or non-generic.
• Set CodeViewAnnotationArgs::ARGS to the desired string arguments, which can be string literals, constants or associated consts.
• Invoke codeview_annotation function with the type e.g.: codeview_annotation::<Args>()

Here are some example invocations:

Literals and Consts

const WORLD: &str = "world";

struct Args;

impl CodeViewAnnotationArgs for Args {
    const ARGS: &[&str] = &["hello", WORLD];
}

codeview_annotation::<Args>();

Associated Consts

trait GetName {
    const NAME: &str;
}

struct Field;

impl GetName for Field {
    const NAME: &str = "Foo";
}

struct Args;

impl CodeViewAnnotationArgs for Args {
    const ARGS: &[&str] = &["metadata", Field::NAME];
}

codeview_annotation::<Args>();

Associated Consts on Generic Types

This example shows how the user can start with some variables in their code (a and b), infer their types and then emit strings associated with their types as annotations.

// A trait that lets you associate a
// string `NAME` with any type
trait GetName {
    const NAME: &str;
}

// The struct `Args`, its impl of `CodeViewAnnotationArgs`
// and the `emit_annotation` wrapper function work together to
// invoke `codeview_annotation` with the `NAME` associated
// with the types of args `_a` and `_b`
struct Args<A, B>(PhantomData<(A, B)>);
impl<A: GetName, B: GetName> CodeViewAnnotationArgs for Args<A, B> {
    const ARGS: &[&str] = &["metadata", A::NAME, B::NAME];
}
fn emit_annotation<A: GetName, B: GetName>(_a: &A, b: &B) {
    codeview_annotation::<Args<A, B>>();
}

// This is how `codeview_annotation` is eventually invoked
// given some variables `a` and `b`
emit_annotation(&a, &b);

Supported Platforms

The intrinsic will be lowered only if:

• The backend is LLVM because llvm.codeview.annotation is available only on that backend
• The target uses PDB for debug info i.e. TargetOptions::uses_pdb_debuginfo() is true

In all other conditions it will be ignored and will be a no-op.

Future Work

It would have been preferable if this feature was implemented using const generics e.g.:

pub fn codeview_annotation<const ARGS: &[&str]>();

as it would not require the extra trait. However, we are blocked on adt_const_params and especially unsized_const_params. Whenever these features get stabilized we can update the implementation to make use of them.

Mentors or Reviewers

Process

The main points of the Major Change Process are as follows:

• File an issue describing the proposal.
• A compiler team member who is knowledgeable in the area can second by writing @rustbot second or kickoff a team FCP with @rfcbot fcp $RESOLUTION.
  • Refer to Proposals, Approvals and Stabilization docs for when a second is sufficient, or when a full team FCP is required.
• Once an MCP is seconded, the Final Comment Period begins.
  • Final Comment Period lasts for 10 days after all outstanding concerns are solved.
  • Outstanding concerns will block the Final Comment Period from finishing. Once all concerns are resolved, the 10 day countdown is restarted.
  • If no concerns are raised after 10 days since the resolution of the last outstanding concern, the MCP is considered approved.

You can read more about Major Change Proposals on forge.