From c8699076f9d9078f401188e533283dd25de07439 Mon Sep 17 00:00:00 2001 From: bjorn3 Date: Wed, 23 Sep 2020 15:13:49 +0200 Subject: [PATCH] Document almost all modules Fixes #1082 --- src/abi/comments.rs | 3 ++ src/abi/mod.rs | 3 ++ src/abi/pass_mode.rs | 5 ++ src/abi/returning.rs | 8 +++ src/allocator.rs | 11 +--- src/analyze.rs | 2 + src/archive.rs | 2 + src/backend.rs | 2 + src/base.rs | 2 + src/cast.rs | 2 + src/codegen_i128.rs | 2 +- src/common.rs | 2 +- src/constant.rs | 2 + src/debuginfo/emit.rs | 4 ++ src/debuginfo/line_info.rs | 2 + src/debuginfo/mod.rs | 2 + src/debuginfo/unwind.rs | 2 + src/discriminant.rs | 2 + src/driver/aot.rs | 3 ++ src/driver/jit.rs | 3 ++ src/driver/mod.rs | 3 ++ src/inline_asm.rs | 2 + src/intrinsics/cpuid.rs | 4 +- src/intrinsics/llvm.rs | 2 + src/intrinsics/mod.rs | 3 ++ src/intrinsics/simd.rs | 2 + src/metadata.rs | 2 + src/num.rs | 2 + src/optimize/mod.rs | 2 + src/pointer.rs | 4 ++ src/pretty_clif.rs | 108 ++++++++++++++++++------------------- src/toolchain.rs | 2 + src/trap.rs | 2 + src/unsize.rs | 4 ++ src/value_and_place.rs | 2 + src/vtable.rs | 3 ++ 36 files changed, 145 insertions(+), 66 deletions(-) diff --git a/src/abi/comments.rs b/src/abi/comments.rs index 5d1a6c6ade5..f63a4565a72 100644 --- a/src/abi/comments.rs +++ b/src/abi/comments.rs @@ -1,3 +1,6 @@ +//! Annotate the clif ir with comments describing how arguments are passed into the current function +//! and where all locals are stored. + use std::borrow::Cow; use rustc_middle::mir; diff --git a/src/abi/mod.rs b/src/abi/mod.rs index 7065eefe170..f55d94b0a09 100644 --- a/src/abi/mod.rs +++ b/src/abi/mod.rs @@ -1,3 +1,5 @@ +//! Handling of everything related to the calling convention. Also fills `fx.local_map`. + #[cfg(debug_assertions)] mod comments; mod pass_mode; @@ -325,6 +327,7 @@ impl<'tcx, B: Backend + 'static> FunctionCx<'_, 'tcx, B> { } } +/// Make a [`CPlace`] capable of holding value of the specified type. fn make_local_place<'tcx>( fx: &mut FunctionCx<'_, 'tcx, impl Backend>, local: Local, diff --git a/src/abi/pass_mode.rs b/src/abi/pass_mode.rs index 49aaf22058d..6033cd88da9 100644 --- a/src/abi/pass_mode.rs +++ b/src/abi/pass_mode.rs @@ -1,3 +1,5 @@ +//! Argument passing + use crate::prelude::*; pub(super) use EmptySinglePair::*; @@ -118,6 +120,7 @@ pub(super) fn get_pass_mode<'tcx>(tcx: TyCtxt<'tcx>, layout: TyAndLayout<'tcx>) } } +/// Get a set of values to be passed as function arguments. pub(super) fn adjust_arg_for_abi<'tcx>( fx: &mut FunctionCx<'_, 'tcx, impl Backend>, arg: CValue<'tcx>, @@ -136,6 +139,8 @@ pub(super) fn adjust_arg_for_abi<'tcx>( } } +/// Create a [`CValue`] containing the value of a function parameter adding clif function parameters +/// as necessary. pub(super) fn cvalue_for_param<'tcx>( fx: &mut FunctionCx<'_, 'tcx, impl Backend>, start_block: Block, diff --git a/src/abi/returning.rs b/src/abi/returning.rs index f56468d4755..4505caa67dd 100644 --- a/src/abi/returning.rs +++ b/src/abi/returning.rs @@ -1,3 +1,5 @@ +//! Return value handling + use crate::abi::pass_mode::*; use crate::prelude::*; @@ -5,6 +7,7 @@ fn return_layout<'a, 'tcx>(fx: &mut FunctionCx<'a, 'tcx, impl Backend>) -> TyAnd fx.layout_of(fx.monomorphize(&fx.mir.local_decls[RETURN_PLACE].ty)) } +/// Can the given type be returned into an ssa var or does it need to be returned on the stack. pub(crate) fn can_return_to_ssa_var<'tcx>( tcx: TyCtxt<'tcx>, dest_layout: TyAndLayout<'tcx>, @@ -16,6 +19,8 @@ pub(crate) fn can_return_to_ssa_var<'tcx>( } } +/// Return a place where the return value of the current function can be written to. If necessary +/// this adds an extra parameter pointing to where the return value needs to be stored. pub(super) fn codegen_return_param<'tcx>( fx: &mut FunctionCx<'_, 'tcx, impl Backend>, ssa_analyzed: &rustc_index::vec::IndexVec, @@ -59,6 +64,8 @@ pub(super) fn codegen_return_param<'tcx>( ret_place } +/// Invokes the closure with if necessary a value representing the return pointer. When the closure +/// returns the call return value(s) if any are written to the correct place. pub(super) fn codegen_with_call_return_arg<'tcx, B: Backend, T>( fx: &mut FunctionCx<'_, 'tcx, B>, fn_sig: FnSig<'tcx>, @@ -102,6 +109,7 @@ pub(super) fn codegen_with_call_return_arg<'tcx, B: Backend, T>( (call_inst, meta) } +/// Codegen a return instruction with the right return value(s) if any. pub(crate) fn codegen_return(fx: &mut FunctionCx<'_, '_, impl Backend>) { match get_pass_mode(fx.tcx, return_layout(fx)) { PassMode::NoPass | PassMode::ByRef { size: Some(_) } => { diff --git a/src/allocator.rs b/src/allocator.rs index 894e47dd439..95beb93f26f 100644 --- a/src/allocator.rs +++ b/src/allocator.rs @@ -1,12 +1,5 @@ -// Copyright 2017 The Rust Project Developers. See the COPYRIGHT -// file at the top-level directory of this distribution and at -// http://rust-lang.org/COPYRIGHT. -// -// Licensed under the Apache License, Version 2.0 or the MIT license -// , at your -// option. This file may not be copied, modified, or distributed -// except according to those terms. +//! Allocator shim +// Adapted from rustc use crate::prelude::*; diff --git a/src/analyze.rs b/src/analyze.rs index 055b371f43c..06434bdf69c 100644 --- a/src/analyze.rs +++ b/src/analyze.rs @@ -1,3 +1,5 @@ +//! SSA analysis + use crate::prelude::*; use rustc_index::vec::IndexVec; diff --git a/src/archive.rs b/src/archive.rs index 60975c89af6..fe2c2f100ee 100644 --- a/src/archive.rs +++ b/src/archive.rs @@ -1,3 +1,5 @@ +//! Creation of ar archives like for the lib and staticlib crate type + use std::collections::BTreeMap; use std::fs::File; use std::path::{Path, PathBuf}; diff --git a/src/backend.rs b/src/backend.rs index 072fdc1f246..f6c06f7f88e 100644 --- a/src/backend.rs +++ b/src/backend.rs @@ -1,3 +1,5 @@ +//! Abstraction around the object writing crate + use std::convert::{TryFrom, TryInto}; use rustc_data_structures::fx::FxHashMap; diff --git a/src/base.rs b/src/base.rs index b5598cb5f1e..1bacfb3fe74 100644 --- a/src/base.rs +++ b/src/base.rs @@ -1,3 +1,5 @@ +//! Codegen of a single function + use rustc_index::vec::IndexVec; use rustc_middle::ty::adjustment::PointerCast; diff --git a/src/cast.rs b/src/cast.rs index 36e060496b1..edfe6feb6c8 100644 --- a/src/cast.rs +++ b/src/cast.rs @@ -1,3 +1,5 @@ +//! Various number casting functions + use crate::prelude::*; pub(crate) fn clif_intcast( diff --git a/src/codegen_i128.rs b/src/codegen_i128.rs index cbce7d9d128..99bd526ad01 100644 --- a/src/codegen_i128.rs +++ b/src/codegen_i128.rs @@ -1,4 +1,4 @@ -//! Replaces 128-bit operators with lang item calls +//! Replaces 128-bit operators with lang item calls where necessary use crate::prelude::*; diff --git a/src/common.rs b/src/common.rs index 9ac82eaeb3d..d1375c73a4b 100644 --- a/src/common.rs +++ b/src/common.rs @@ -302,7 +302,7 @@ pub(crate) struct FunctionCx<'clif, 'tcx, B: Backend + 'static> { /// When `#[track_caller]` is used, the implicit caller location is stored in this variable. pub(crate) caller_location: Option>, - /// See [crate::optimize::code_layout] for more information. + /// See [`crate::optimize::code_layout`] for more information. pub(crate) cold_blocks: EntitySet, pub(crate) clif_comments: crate::pretty_clif::CommentWriter, diff --git a/src/constant.rs b/src/constant.rs index 458ace9675d..c01256b7f74 100644 --- a/src/constant.rs +++ b/src/constant.rs @@ -1,3 +1,5 @@ +//! Handling of `static`s, `const`s and promoted allocations + use rustc_span::DUMMY_SP; use rustc_data_structures::fx::FxHashSet; diff --git a/src/debuginfo/emit.rs b/src/debuginfo/emit.rs index 22e284b9df4..0a887e8cb59 100644 --- a/src/debuginfo/emit.rs +++ b/src/debuginfo/emit.rs @@ -1,3 +1,5 @@ +//! Write the debuginfo into an object file. + use rustc_data_structures::fx::FxHashMap; use gimli::write::{Address, AttributeValue, EndianVec, Result, Sections, Writer}; @@ -55,6 +57,7 @@ pub(crate) enum DebugRelocName { Symbol(usize), } +/// A [`Writer`] that collects all necessary relocations. #[derive(Clone)] pub(super) struct WriterRelocate { pub(super) relocs: Vec, @@ -69,6 +72,7 @@ impl WriterRelocate { } } + /// Perform the collected relocations to be usable for JIT usage. #[cfg(feature = "jit")] pub(super) fn relocate_for_jit( mut self, diff --git a/src/debuginfo/line_info.rs b/src/debuginfo/line_info.rs index 798064b07a5..4de84855328 100644 --- a/src/debuginfo/line_info.rs +++ b/src/debuginfo/line_info.rs @@ -1,3 +1,5 @@ +//! Line info generation (`.debug_line`) + use std::ffi::OsStr; use std::path::{Component, Path}; diff --git a/src/debuginfo/mod.rs b/src/debuginfo/mod.rs index 8f7d21dfb4f..9cad668e3f6 100644 --- a/src/debuginfo/mod.rs +++ b/src/debuginfo/mod.rs @@ -1,3 +1,5 @@ +//! Handling of everything related to debuginfo. + mod emit; mod line_info; mod unwind; diff --git a/src/debuginfo/unwind.rs b/src/debuginfo/unwind.rs index 39a951e5eca..fa1a9d44117 100644 --- a/src/debuginfo/unwind.rs +++ b/src/debuginfo/unwind.rs @@ -1,3 +1,5 @@ +//! Unwind info generation (`.eh_frame`) + use crate::prelude::*; use cranelift_codegen::isa::{unwind::UnwindInfo, TargetIsa}; diff --git a/src/discriminant.rs b/src/discriminant.rs index 53a6acd7c85..231802dfb85 100644 --- a/src/discriminant.rs +++ b/src/discriminant.rs @@ -1,3 +1,5 @@ +//! Handling of enum discriminants +//! //! Adapted from https://github.com/rust-lang/rust/blob/d760df5aea483aae041c9a241e7acacf48f75035/src/librustc_codegen_ssa/mir/place.rs use rustc_target::abi::{Int, TagEncoding, Variants}; diff --git a/src/driver/aot.rs b/src/driver/aot.rs index 2eecd8c3c0a..2cf136ceb67 100644 --- a/src/driver/aot.rs +++ b/src/driver/aot.rs @@ -1,3 +1,6 @@ +//! The AOT driver uses [`cranelift_object`] to write object files suitable for linking into a +//! standalone executable. + use std::path::PathBuf; use rustc_codegen_ssa::back::linker::LinkerInfo; diff --git a/src/driver/jit.rs b/src/driver/jit.rs index 195cea02cde..edeeb7670e9 100644 --- a/src/driver/jit.rs +++ b/src/driver/jit.rs @@ -1,3 +1,6 @@ +//! The JIT driver uses [`cranelift_simplejit`] to JIT execute programs without writing any object +//! files. + use std::ffi::CString; use std::os::raw::{c_char, c_int}; diff --git a/src/driver/mod.rs b/src/driver/mod.rs index 304add6f604..0224f929ac7 100644 --- a/src/driver/mod.rs +++ b/src/driver/mod.rs @@ -1,3 +1,6 @@ +//! Drivers are responsible for calling [`codegen_mono_items`] and performing any further actions +//! like JIT executing or writing object files. + use std::any::Any; use rustc_middle::middle::cstore::EncodedMetadata; diff --git a/src/inline_asm.rs b/src/inline_asm.rs index 35b17591744..e11ba4a4f63 100644 --- a/src/inline_asm.rs +++ b/src/inline_asm.rs @@ -1,3 +1,5 @@ +//! Codegen of [`asm!`] invocations. + use crate::prelude::*; use std::fmt::Write; diff --git a/src/intrinsics/cpuid.rs b/src/intrinsics/cpuid.rs index 48891ab2545..94c280ee0ba 100644 --- a/src/intrinsics/cpuid.rs +++ b/src/intrinsics/cpuid.rs @@ -1,6 +1,8 @@ +//! Emulation of a subset of the cpuid x86 instruction. + use crate::prelude::*; -/// Emulates a subset of the cpuid call. +/// Emulates a subset of the cpuid x86 instruction. /// /// This emulates an intel cpu with sse and sse2 support, but which doesn't support anything else. pub(crate) fn codegen_cpuid_call<'tcx>( diff --git a/src/intrinsics/llvm.rs b/src/intrinsics/llvm.rs index ab1c888b4c0..cc919f97616 100644 --- a/src/intrinsics/llvm.rs +++ b/src/intrinsics/llvm.rs @@ -1,3 +1,5 @@ +//! Emulate LLVM intrinsics + use crate::intrinsics::*; use crate::prelude::*; diff --git a/src/intrinsics/mod.rs b/src/intrinsics/mod.rs index fd95c25b572..0b7cc7bee90 100644 --- a/src/intrinsics/mod.rs +++ b/src/intrinsics/mod.rs @@ -1,3 +1,6 @@ +//! Codegen of intrinsics. This includes `extern "rust-intrinsic"`, `extern "platform-intrinsic"` +//! and LLVM intrinsics that have symbol names starting with `llvm.`. + mod cpuid; mod llvm; mod simd; diff --git a/src/intrinsics/simd.rs b/src/intrinsics/simd.rs index cb6e1d20983..93724522e76 100644 --- a/src/intrinsics/simd.rs +++ b/src/intrinsics/simd.rs @@ -1,3 +1,5 @@ +//! Codegen `extern "platform-intrinsic"` intrinsics. + use super::*; use crate::prelude::*; diff --git a/src/metadata.rs b/src/metadata.rs index 9fdd3725940..93cff5711d9 100644 --- a/src/metadata.rs +++ b/src/metadata.rs @@ -1,3 +1,5 @@ +//! Reading and writing of the rustc metadata for rlibs and dylibs + use std::convert::TryFrom; use std::fs::File; use std::path::Path; diff --git a/src/num.rs b/src/num.rs index 3c290026776..4e3b79cd2d6 100644 --- a/src/num.rs +++ b/src/num.rs @@ -1,3 +1,5 @@ +//! Various operations on integer and floating-point numbers + use crate::prelude::*; pub(crate) fn bin_op_to_intcc(bin_op: BinOp, signed: bool) -> Option { diff --git a/src/optimize/mod.rs b/src/optimize/mod.rs index ae969279089..3ce7f8cd9a8 100644 --- a/src/optimize/mod.rs +++ b/src/optimize/mod.rs @@ -1,3 +1,5 @@ +//! Various optimizations specific to cg_clif + use crate::prelude::*; mod code_layout; diff --git a/src/pointer.rs b/src/pointer.rs index 5295b296cde..cd3f27c3247 100644 --- a/src/pointer.rs +++ b/src/pointer.rs @@ -1,9 +1,13 @@ +//! Defines [`Pointer`] which is used to improve the quality of the generated clif ir for pointer +//! operations. + use crate::prelude::*; use rustc_target::abi::Align; use cranelift_codegen::ir::immediates::Offset32; +/// A pointer pointing either to a certain address, a certain stack slot or nothing. #[derive(Copy, Clone, Debug)] pub(crate) struct Pointer { base: PointerBase, diff --git a/src/pretty_clif.rs b/src/pretty_clif.rs index 6d8d085529c..5c4d951bc50 100644 --- a/src/pretty_clif.rs +++ b/src/pretty_clif.rs @@ -1,3 +1,57 @@ +//! This module provides the [CommentWriter] which makes it possible +//! to add comments to the written cranelift ir. +//! +//! # Example +//! +//! ```clif +//! test compile +//! target x86_64 +//! +//! function u0:0(i64, i64, i64) system_v { +//! ; symbol _ZN119_$LT$example..IsNotEmpty$u20$as$u20$mini_core..FnOnce$LT$$LP$$RF$$u27$a$u20$$RF$$u27$b$u20$$u5b$u16$u5d$$C$$RP$$GT$$GT$9call_once17he85059d5e6a760a0E +//! ; instance Instance { def: Item(DefId(0/0:29 ~ example[8787]::{{impl}}[0]::call_once[0])), substs: [ReErased, ReErased] } +//! ; sig ([IsNotEmpty, (&&[u16],)]; c_variadic: false)->(u8, u8) +//! +//! ; ssa {_2: NOT_SSA, _4: NOT_SSA, _0: NOT_SSA, _3: (empty), _1: NOT_SSA} +//! ; msg loc.idx param pass mode ssa flags ty +//! ; ret _0 = v0 ByRef NOT_SSA (u8, u8) +//! ; arg _1 = v1 ByRef NOT_SSA IsNotEmpty +//! ; arg _2.0 = v2 ByVal(types::I64) NOT_SSA &&[u16] +//! +//! ss0 = explicit_slot 0 ; _1: IsNotEmpty size=0 align=1,8 +//! ss1 = explicit_slot 8 ; _2: (&&[u16],) size=8 align=8,8 +//! ss2 = explicit_slot 8 ; _4: (&&[u16],) size=8 align=8,8 +//! sig0 = (i64, i64, i64) system_v +//! sig1 = (i64, i64, i64) system_v +//! fn0 = colocated u0:6 sig1 ; Instance { def: Item(DefId(0/0:31 ~ example[8787]::{{impl}}[1]::call_mut[0])), substs: [ReErased, ReErased] } +//! +//! block0(v0: i64, v1: i64, v2: i64): +//! v3 = stack_addr.i64 ss0 +//! v4 = stack_addr.i64 ss1 +//! store v2, v4 +//! v5 = stack_addr.i64 ss2 +//! jump block1 +//! +//! block1: +//! nop +//! ; _3 = &mut _1 +//! ; _4 = _2 +//! v6 = load.i64 v4 +//! store v6, v5 +//! ; +//! ; _0 = const mini_core::FnMut::call_mut(move _3, move _4) +//! v7 = load.i64 v5 +//! call fn0(v0, v3, v7) +//! jump block2 +//! +//! block2: +//! nop +//! ; +//! ; return +//! return +//! } +//! ``` + use std::fmt; use cranelift_codegen::{ @@ -10,60 +64,6 @@ use rustc_session::config::OutputType; use crate::prelude::*; -/// This module provides the [CommentWriter] which makes it possible -/// to add comments to the written cranelift ir. -/// -/// # Example -/// -/// ```clif -/// test compile -/// target x86_64 -/// -/// function u0:0(i64, i64, i64) system_v { -/// ; symbol _ZN119_$LT$example..IsNotEmpty$u20$as$u20$mini_core..FnOnce$LT$$LP$$RF$$u27$a$u20$$RF$$u27$b$u20$$u5b$u16$u5d$$C$$RP$$GT$$GT$9call_once17he85059d5e6a760a0E -/// ; instance Instance { def: Item(DefId(0/0:29 ~ example[8787]::{{impl}}[0]::call_once[0])), substs: [ReErased, ReErased] } -/// ; sig ([IsNotEmpty, (&&[u16],)]; c_variadic: false)->(u8, u8) -/// -/// ; ssa {_2: NOT_SSA, _4: NOT_SSA, _0: NOT_SSA, _3: (empty), _1: NOT_SSA} -/// ; msg loc.idx param pass mode ssa flags ty -/// ; ret _0 = v0 ByRef NOT_SSA (u8, u8) -/// ; arg _1 = v1 ByRef NOT_SSA IsNotEmpty -/// ; arg _2.0 = v2 ByVal(types::I64) NOT_SSA &&[u16] -/// -/// ss0 = explicit_slot 0 ; _1: IsNotEmpty size=0 align=1,8 -/// ss1 = explicit_slot 8 ; _2: (&&[u16],) size=8 align=8,8 -/// ss2 = explicit_slot 8 ; _4: (&&[u16],) size=8 align=8,8 -/// sig0 = (i64, i64, i64) system_v -/// sig1 = (i64, i64, i64) system_v -/// fn0 = colocated u0:6 sig1 ; Instance { def: Item(DefId(0/0:31 ~ example[8787]::{{impl}}[1]::call_mut[0])), substs: [ReErased, ReErased] } -/// -/// block0(v0: i64, v1: i64, v2: i64): -/// v3 = stack_addr.i64 ss0 -/// v4 = stack_addr.i64 ss1 -/// store v2, v4 -/// v5 = stack_addr.i64 ss2 -/// jump block1 -/// -/// block1: -/// nop -/// ; _3 = &mut _1 -/// ; _4 = _2 -/// v6 = load.i64 v4 -/// store v6, v5 -/// ; -/// ; _0 = const mini_core::FnMut::call_mut(move _3, move _4) -/// v7 = load.i64 v5 -/// call fn0(v0, v3, v7) -/// jump block2 -/// -/// block2: -/// nop -/// ; -/// ; return -/// return -/// } -/// ``` - #[derive(Debug)] pub(crate) struct CommentWriter { global_comments: Vec, diff --git a/src/toolchain.rs b/src/toolchain.rs index 121f4477b80..d1329d5de7e 100644 --- a/src/toolchain.rs +++ b/src/toolchain.rs @@ -1,3 +1,5 @@ +//! Locating various executables part of a C toolchain. + use std::path::PathBuf; use rustc_middle::bug; diff --git a/src/trap.rs b/src/trap.rs index e69e63e4d49..7ab3a4a88c2 100644 --- a/src/trap.rs +++ b/src/trap.rs @@ -1,3 +1,5 @@ +//! Helpers used to print a message and abort in case of certain panics and some detected UB. + use crate::prelude::*; fn codegen_print(fx: &mut FunctionCx<'_, '_, impl cranelift_module::Backend>, msg: &str) { diff --git a/src/unsize.rs b/src/unsize.rs index 962fcaf48ef..441d2b5edd8 100644 --- a/src/unsize.rs +++ b/src/unsize.rs @@ -1,3 +1,7 @@ +//! Codegen of the [`PointerCast::Unsize`] operation. +//! +//! [`PointerCast::Unsize`]: `rustc_middle::ty::adjustment::PointerCast::Unsize` + use crate::prelude::*; // Adapted from https://github.com/rust-lang/rust/blob/2a663555ddf36f6b041445894a8c175cd1bc718c/src/librustc_codegen_ssa/base.rs#L159-L307 diff --git a/src/value_and_place.rs b/src/value_and_place.rs index 765c482e83c..5e663425117 100644 --- a/src/value_and_place.rs +++ b/src/value_and_place.rs @@ -1,3 +1,5 @@ +//! Definition of [`CValue`] and [`CPlace`] + use crate::prelude::*; use cranelift_codegen::entity::EntityRef; diff --git a/src/vtable.rs b/src/vtable.rs index c58b39c1c82..d6bb9c912b5 100644 --- a/src/vtable.rs +++ b/src/vtable.rs @@ -1,4 +1,7 @@ +//! Codegen vtables and vtable accesses. +//! //! See librustc_codegen_llvm/meth.rs for reference +// FIXME dedup this logic between miri, cg_llvm and cg_clif use crate::prelude::*;