Go to file

bors 6cb1f5972d Auto merge of #69171 - Amanieu:new-asm, r=nagisa,nikomatsakis Implement new asm! syntax from RFC 2850 This PR implements the new `asm!` syntax proposed in https://github.com/rust-lang/rfcs/pull/2850. # Design A large part of this PR revolves around taking an `asm!` macro invocation and plumbing it through all of the compiler layers down to LLVM codegen. Throughout the various stages, an `InlineAsm` generally consists of 3 components: - The template string, which is stored as an array of `InlineAsmTemplatePiece`. Each piece represents either a literal or a placeholder for an operand (just like format strings). ```rust pub enum InlineAsmTemplatePiece { String(String), Placeholder { operand_idx: usize, modifier: Option<char>, span: Span }, } ``` - The list of operands to the `asm!` (`in`, `[late]out`, `in[late]out`, `sym`, `const`). These are represented differently at each stage of lowering, but follow a common pattern: - `in`, `out` and `inout` all have an associated register class (`reg`) or explicit register (`"eax"`). - `inout` has 2 forms: one with a single expression that is both read from and written to, and one with two separate expressions for the input and output parts. - `out` and `inout` have a `late` flag (`lateout` / `inlateout`) to indicate that the register allocator is allowed to reuse an input register for this output. - `out` and the split variant of `inout` allow `_` to be specified for an output, which means that the output is discarded. This is used to allocate scratch registers for assembly code. - `sym` is a bit special since it only accepts a path expression, which must point to a `static` or a `fn`. - The options set at the end of the `asm!` macro. The only one that is particularly of interest to rustc is `NORETURN` which makes `asm!` return `!` instead of `()`. ```rust bitflags::bitflags! { pub struct InlineAsmOptions: u8 { const PURE = 1 << 0; const NOMEM = 1 << 1; const READONLY = 1 << 2; const PRESERVES_FLAGS = 1 << 3; const NORETURN = 1 << 4; const NOSTACK = 1 << 5; } } ``` ## AST `InlineAsm` is represented as an expression in the AST: ```rust pub struct InlineAsm { pub template: Vec<InlineAsmTemplatePiece>, pub operands: Vec<(InlineAsmOperand, Span)>, pub options: InlineAsmOptions, } pub enum InlineAsmRegOrRegClass { Reg(Symbol), RegClass(Symbol), } pub enum InlineAsmOperand { In { reg: InlineAsmRegOrRegClass, expr: P<Expr>, }, Out { reg: InlineAsmRegOrRegClass, late: bool, expr: Option<P<Expr>>, }, InOut { reg: InlineAsmRegOrRegClass, late: bool, expr: P<Expr>, }, SplitInOut { reg: InlineAsmRegOrRegClass, late: bool, in_expr: P<Expr>, out_expr: Option<P<Expr>>, }, Const { expr: P<Expr>, }, Sym { expr: P<Expr>, }, } ``` The `asm!` macro is implemented in librustc_builtin_macros and outputs an `InlineAsm` AST node. The template string is parsed using libfmt_macros, positional and named operands are resolved to explicit operand indicies. Since target information is not available to macro invocations, validation of the registers and register classes is deferred to AST lowering. ## HIR `InlineAsm` is represented as an expression in the HIR: ```rust pub struct InlineAsm<'hir> { pub template: &'hir [InlineAsmTemplatePiece], pub operands: &'hir [InlineAsmOperand<'hir>], pub options: InlineAsmOptions, } pub enum InlineAsmRegOrRegClass { Reg(InlineAsmReg), RegClass(InlineAsmRegClass), } pub enum InlineAsmOperand<'hir> { In { reg: InlineAsmRegOrRegClass, expr: Expr<'hir>, }, Out { reg: InlineAsmRegOrRegClass, late: bool, expr: Option<Expr<'hir>>, }, InOut { reg: InlineAsmRegOrRegClass, late: bool, expr: Expr<'hir>, }, SplitInOut { reg: InlineAsmRegOrRegClass, late: bool, in_expr: Expr<'hir>, out_expr: Option<Expr<'hir>>, }, Const { expr: Expr<'hir>, }, Sym { expr: Expr<'hir>, }, } ``` AST lowering is where `InlineAsmRegOrRegClass` is converted from `Symbol`s to an actual register or register class. If any modifiers are specified for a template string placeholder, these are validated against the set allowed for that operand type. Finally, explicit registers for inputs and outputs are checked for conflicts (same register used for different operands). ## Type checking Each register class has a whitelist of types that it may be used with. After the types of all operands have been determined, the `intrinsicck` pass will check that these types are in the whitelist. It also checks that split `inout` operands have compatible types and that `const` operands are integers or floats. Suggestions are emitted where needed if a template modifier should be used for an operand based on the type that was passed into it. ## HAIR `InlineAsm` is represented as an expression in the HAIR: ```rust crate enum ExprKind<'tcx> { // [..] InlineAsm { template: &'tcx [InlineAsmTemplatePiece], operands: Vec<InlineAsmOperand<'tcx>>, options: InlineAsmOptions, }, } crate enum InlineAsmOperand<'tcx> { In { reg: InlineAsmRegOrRegClass, expr: ExprRef<'tcx>, }, Out { reg: InlineAsmRegOrRegClass, late: bool, expr: Option<ExprRef<'tcx>>, }, InOut { reg: InlineAsmRegOrRegClass, late: bool, expr: ExprRef<'tcx>, }, SplitInOut { reg: InlineAsmRegOrRegClass, late: bool, in_expr: ExprRef<'tcx>, out_expr: Option<ExprRef<'tcx>>, }, Const { expr: ExprRef<'tcx>, }, SymFn { expr: ExprRef<'tcx>, }, SymStatic { expr: ExprRef<'tcx>, }, } ``` The only significant change compared to HIR is that `Sym` has been lowered to either a `SymFn` whose `expr` is a `Literal` ZST of the `fn`, or a `SymStatic` whose `expr` is a `StaticRef`. ## MIR `InlineAsm` is represented as a `Terminator` in the MIR: ```rust pub enum TerminatorKind<'tcx> { // [..] /// Block ends with an inline assembly block. This is a terminator since /// inline assembly is allowed to diverge. InlineAsm { /// The template for the inline assembly, with placeholders. template: &'tcx [InlineAsmTemplatePiece], /// The operands for the inline assembly, as `Operand`s or `Place`s. operands: Vec<InlineAsmOperand<'tcx>>, /// Miscellaneous options for the inline assembly. options: InlineAsmOptions, /// Destination block after the inline assembly returns, unless it is /// diverging (InlineAsmOptions::NORETURN). destination: Option<BasicBlock>, }, } pub enum InlineAsmOperand<'tcx> { In { reg: InlineAsmRegOrRegClass, value: Operand<'tcx>, }, Out { reg: InlineAsmRegOrRegClass, late: bool, place: Option<Place<'tcx>>, }, InOut { reg: InlineAsmRegOrRegClass, late: bool, in_value: Operand<'tcx>, out_place: Option<Place<'tcx>>, }, Const { value: Operand<'tcx>, }, SymFn { value: Box<Constant<'tcx>>, }, SymStatic { value: Box<Constant<'tcx>>, }, } ``` As part of HAIR lowering, `InOut` and `SplitInOut` operands are lowered to a split form with a separate `in_value` and `out_place`. Semantically, the `InlineAsm` terminator is similar to the `Call` terminator except that it has multiple output places where a `Call` only has a single return place output. The constant promotion pass is used to ensure that `const` operands are actually constants (using the same logic as `#[rustc_args_required_const]`). ## Codegen Operands are lowered one more time before being passed to LLVM codegen: ```rust pub enum InlineAsmOperandRef<'tcx, B: BackendTypes + ?Sized> { In { reg: InlineAsmRegOrRegClass, value: OperandRef<'tcx, B::Value>, }, Out { reg: InlineAsmRegOrRegClass, late: bool, place: Option<PlaceRef<'tcx, B::Value>>, }, InOut { reg: InlineAsmRegOrRegClass, late: bool, in_value: OperandRef<'tcx, B::Value>, out_place: Option<PlaceRef<'tcx, B::Value>>, }, Const { string: String, }, SymFn { instance: Instance<'tcx>, }, SymStatic { def_id: DefId, }, } ``` The operands are lowered to LLVM operands and constraint codes as follow: - `out` and the output part of `inout` operands are added first, as required by LLVM. Late output operands have a `=` prefix added to their constraint code, non-late output operands have a `=&` prefix added to their constraint code. - `in` operands are added normally. - `inout` operands are tied to the matching output operand. - `sym` operands are passed as function pointers or pointers, using the `"s"` constraint. - `const` operands are formatted to a string and directly inserted in the template string. The template string is converted to LLVM form: - `$` characters are escaped as `$$`. - `const` operands are converted to strings and inserted directly. - Placeholders are formatted as `${X:M}` where `X` is the operand index and `M` is the modifier character. Modifiers are converted from the Rust form to the LLVM form. The various options are converted to clobber constraints or LLVM attributes, refer to the [RFC](https://github.com/Amanieu/rfcs/blob/inline-asm/text/0000-inline-asm.md#mapping-to-llvm-ir) for more details. Note that LLVM is sometimes rather picky about what types it accepts for certain constraint codes so we sometimes need to insert conversions to/from a supported type. See the target-specific ISelLowering.cpp files in LLVM for details. # Adding support for new architectures Adding inline assembly support to an architecture is mostly a matter of defining the registers and register classes for that architecture. All the definitions for register classes are located in `src/librustc_target/asm/`. Additionally you will need to implement lowering of these register classes to LLVM constraint codes in `src/librustc_codegen_llvm/asm.rs`.		2020-05-19 18:32:40 +00:00
.cargo	Deprecate util/dev in favor of cargo alias	2020-01-30 21:34:31 +01:00
.github	Remove apt-get upgrade again	2020-04-23 21:14:45 +02:00
clippy_dev	clippy_dev: make it fatal when the regex for updating lint count does not match	2020-04-23 16:11:11 +02:00
clippy_dummy	Fix markdown Files	2020-02-12 09:34:25 +01:00
clippy_lints	Handle InlineAsm in clippy	2020-05-18 14:41:33 +01:00
clippy_workspace_tests	a few small cleanups	2019-12-23 05:28:23 +07:00
doc	Run fetch before testing if master contains beta	2020-04-23 23:25:35 +02:00
etc/relicense	Fix markdown Files	2020-02-12 09:34:25 +01:00
mini-macro	Stabilize fn-like proc macros in expression, pattern and statement positions	2020-05-03 19:24:41 +03:00
rustc_tools_util	Update Copyright year	2020-02-20 12:06:45 +01:00
src	Merge commit 'e214ea82ad0a751563acf67e1cd9279cf302db3a' into clippyup	2020-05-17 17:36:26 +02:00
tests	Auto merge of #68717 - petrochenkov:stabexpat, r=varkor	2020-05-19 03:11:32 +00:00
util	Fix nit and cargo.lock	2020-05-07 17:46:31 -04:00
.editorconfig	Prefer 2 spaces as indent size over 4 on yaml	2020-01-10 04:34:56 +09:00
.gitattributes	git attribute macros not allowed in submodules	2020-03-29 06:58:37 -07:00
.gitignore	Small change to comment in .gitignore	2020-02-12 09:34:26 +01:00
.remarkrc	Rename .remarkrc.json -> .remarkrc and fix file	2020-02-12 09:34:25 +01:00
build.rs	clippy: bump rustc_tools util version to 0.2	2019-05-23 17:40:54 +02:00
Cargo.toml	Merge commit '43a1777b89cf6791f9e20878b4e5e3ae907867a5' into clippyup	2020-05-11 20:23:47 +02:00
CHANGELOG.md	Merge commit 'e214ea82ad0a751563acf67e1cd9279cf302db3a' into clippyup	2020-05-17 17:36:26 +02:00
CODE_OF_CONDUCT.md	Fix markdown Files	2020-02-12 09:34:25 +01:00
CONTRIBUTING.md	Rollup merge of #5422 - nickrtorres:contributing-triage, r=flip1995	2020-04-08 15:50:25 +02:00
COPYRIGHT	update license year to 2020	2020-01-15 15:00:54 +08:00
LICENSE-APACHE	Add Copyright claim, where missing	2020-02-20 12:06:44 +01:00
LICENSE-MIT	Add Copyright claim, where missing	2020-02-20 12:06:44 +01:00
README.md	README: fix lit count line	2020-04-23 16:11:18 +02:00
rust-toolchain	Add rust-toolchain file	2018-07-11 08:03:46 +02:00
rustfmt.toml	Revert "Revert global fmt config and use `rustfmt::skip`"	2019-07-23 02:57:49 +08:00
setup-toolchain.sh	Only /usr/bin/env is portable in shebangs.	2020-04-07 19:51:59 +00:00
triagebot.toml	Allow everyone to assign labels with rustbot	2019-09-28 14:14:20 +02:00

README.md

Clippy

A collection of lints to catch common mistakes and improve your Rust code.

There are over 350 lints included in this crate!

We have a bunch of lint categories to allow you to choose how much Clippy is supposed to ~~annoy~~ help you:

clippy::all (everything that is on by default: all the categories below except for nursery, pedantic, and cargo)
clippy::correctness (code that is just outright wrong or very very useless, causes hard errors by default)
clippy::style (code that should be written in a more idiomatic way)
clippy::complexity (code that does something simple but in a complex way)
clippy::perf (code that can be written in a faster way)
clippy::pedantic (lints which are rather strict, off by default)
clippy::nursery (new lints that aren't quite ready yet, off by default)
clippy::cargo (checks against the cargo manifest, off by default)

More to come, please file an issue if you have ideas!

Only the following of those categories are enabled by default:

clippy::style
clippy::correctness
clippy::complexity
clippy::perf

Other categories need to be enabled in order for their lints to be executed.

The lint list also contains "restriction lints", which are for things which are usually not considered "bad", but may be useful to turn on in specific cases. These should be used very selectively, if at all.

Table of contents:

Usage instructions
Configuration
Contributing
License

Usage

Since this is a tool for helping the developer of a library or application write better code, it is recommended not to include Clippy as a hard dependency. Options include using it as an optional dependency, as a cargo subcommand, or as an included feature during build. These options are detailed below.

As a cargo subcommand (`cargo clippy`)

One way to use Clippy is by installing Clippy through rustup as a cargo subcommand.

Step 1: Install rustup

You can install rustup on supported platforms. This will help us install Clippy and its dependencies.

If you already have rustup installed, update to ensure you have the latest rustup and compiler:

rustup update

Step 2: Install Clippy

Once you have rustup and the latest stable release (at least Rust 1.29) installed, run the following command:

rustup component add clippy

If it says that it can't find the clippy component, please run rustup self update.

Step 3: Run Clippy

Now you can run Clippy by invoking the following command:

cargo clippy

Automatically applying Clippy suggestions

Clippy can automatically apply some lint suggestions. Note that this is still experimental and only supported on the nightly channel:

cargo clippy --fix -Z unstable-options

Running Clippy from the command line without installing it

To have cargo compile your crate with Clippy without Clippy installation in your code, you can use:

cargo run --bin cargo-clippy --manifest-path=path_to_clippys_Cargo.toml

Note: Be sure that Clippy was compiled with the same version of rustc that cargo invokes here!

Travis CI

You can add Clippy to Travis CI in the same way you use it locally:

language: rust
rust:
  - stable
  - beta
before_script:
  - rustup component add clippy
script:
  - cargo clippy
  # if you want the build job to fail when encountering warnings, use
  - cargo clippy -- -D warnings
  # in order to also check tests and non-default crate features, use
  - cargo clippy --all-targets --all-features -- -D warnings
  - cargo test
  # etc.

If you are on nightly, It might happen that Clippy is not available for a certain nightly release. In this case you can try to conditionally install Clippy from the Git repo.

language: rust
rust:
  - nightly
before_script:
   - rustup component add clippy --toolchain=nightly || cargo install --git https://github.com/rust-lang/rust-clippy/ --force clippy
   # etc.

Note that adding -D warnings will cause your build to fail if any warnings are found in your code. That includes warnings found by rustc (e.g. dead_code, etc.). If you want to avoid this and only cause an error for Clippy warnings, use #![deny(clippy::all)] in your code or -D clippy::all on the command line. (You can swap clippy::all with the specific lint category you are targeting.)

Configuration

Some lints can be configured in a TOML file named clippy.toml or .clippy.toml. It contains a basic variable = value mapping eg.

blacklisted-names = ["toto", "tata", "titi"]
cognitive-complexity-threshold = 30

See the list of lints for more information about which lints can be configured and the meaning of the variables.

To deactivate the “for further information visit lint-link” message you can define the CLIPPY_DISABLE_DOCS_LINKS environment variable.

Allowing/denying lints

You can add options to your code to allow/warn/deny Clippy lints:

the whole set of Warn lints using the clippy lint group (#![deny(clippy::all)])
all lints using both the clippy and clippy::pedantic lint groups (#![deny(clippy::all)], #![deny(clippy::pedantic)]). Note that clippy::pedantic contains some very aggressive lints prone to false positives.
only some lints (#![deny(clippy::single_match, clippy::box_vec)], etc.)
allow/warn/deny can be limited to a single function or module using #[allow(...)], etc.

Note: deny produces errors instead of warnings.

If you do not want to include your lint levels in your code, you can globally enable/disable lints by passing extra flags to Clippy during the run: cargo clippy -- -A clippy::lint_name will run Clippy with lint_name disabled and cargo clippy -- -W clippy::lint_name will run it with that enabled. This also works with lint groups. For example you can run Clippy with warnings for all lints enabled: cargo clippy -- -W clippy::pedantic If you care only about a single lint, you can allow all others and then explicitly reenable the lint(s) you are interested in: cargo clippy -- -Aclippy::all -Wclippy::useless_format -Wclippy::...

Contributing

If you want to contribute to Clippy, you can find more information in CONTRIBUTING.md.

License

Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option. Files in the project may not be copied, modified, or distributed except according to those terms.