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);which expands to a call to codeview_annotation:
codeview_annotation!("Bytes {}, duration {} ms", "some other metadata");and the string arguments plus some metadata 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 fn codeview_annotation(strings: &[&str]);
and is publicly exposed through a macro with the same name.
The &[&str] parameter is required to be a const as it must be available at compile time in order to be lowered to llvm.codeview.annotation. Non-const arguments are rejected with a compiler error.
Supported Platforms
Only LLVM on msvc is supported. It is a no-op on other platforms.
Implementation
Calls to codeview_annotation are lowered to StatementKind::Intrinsic at MIR building time. The string arguments are extracted from THIR and stored in the newly introduced variant NonDivergingIntrinsic::CodeviewAnnotation(Box<[Symbol]>) which is ultimately lowered to llvm.codeview.annotation in the backend.
We have chosen to collect the string arguments at the time of THIR->MIR translation because it is easier to do so. The other option was to do it during codegen but that would have required walking chains of MIR locals backwards which was more complicated.
Future Work
Ideally the features should be based on const generics e.g.:
pub fn codeview_annotation<const STRINGS: &[&str]>();
as that guarantees the compile time availability of the inputs. 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:
You can read more about Major Change Proposals on forge.
Proposal
Add a new compiler intrinsic called
codeview_annotationwhich lowers tollvm.codeview.annotationand allows users to emit arbitraryS_ANNOTATIONrecords 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_annotationis 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:
which expands to a call to
codeview_annotation:and the string arguments plus some metadata 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_countandelapsed_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:
and is publicly exposed through a macro with the same name.
The
&[&str]parameter is required to be aconstas it must be available at compile time in order to be lowered tollvm.codeview.annotation. Non-constarguments are rejected with a compiler error.Supported Platforms
Only LLVM on msvc is supported. It is a no-op on other platforms.
Implementation
Calls to
codeview_annotationare lowered toStatementKind::Intrinsicat MIR building time. The string arguments are extracted from THIR and stored in the newly introduced variantNonDivergingIntrinsic::CodeviewAnnotation(Box<[Symbol]>)which is ultimately lowered tollvm.codeview.annotationin the backend.We have chosen to collect the string arguments at the time of THIR->MIR translation because it is easier to do so. The other option was to do it during codegen but that would have required walking chains of MIR locals backwards which was more complicated.
Future Work
Ideally the features should be based on const generics e.g.:
as that guarantees the compile time availability of the inputs. However, we are blocked on
adt_const_paramsand especiallyunsized_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:
@rustbot secondor kickoff a team FCP with@rfcbot fcp $RESOLUTION.You can read more about Major Change Proposals on forge.