Document almost all modules

Fixes #1082
This commit is contained in:
bjorn3 2020-09-23 15:13:49 +02:00
parent 934d56a646
commit c8699076f9
36 changed files with 145 additions and 66 deletions

View File

@ -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;

View File

@ -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,

View File

@ -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,

View File

@ -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<Local, crate::analyze::SsaKind>,
@ -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(_) } => {

View File

@ -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 <LICENSE-APACHE or
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, 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::*;

View File

@ -1,3 +1,5 @@
//! SSA analysis
use crate::prelude::*;
use rustc_index::vec::IndexVec;

View File

@ -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};

View File

@ -1,3 +1,5 @@
//! Abstraction around the object writing crate
use std::convert::{TryFrom, TryInto};
use rustc_data_structures::fx::FxHashMap;

View File

@ -1,3 +1,5 @@
//! Codegen of a single function
use rustc_index::vec::IndexVec;
use rustc_middle::ty::adjustment::PointerCast;

View File

@ -1,3 +1,5 @@
//! Various number casting functions
use crate::prelude::*;
pub(crate) fn clif_intcast(

View File

@ -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::*;

View File

@ -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<CValue<'tcx>>,
/// See [crate::optimize::code_layout] for more information.
/// See [`crate::optimize::code_layout`] for more information.
pub(crate) cold_blocks: EntitySet<Block>,
pub(crate) clif_comments: crate::pretty_clif::CommentWriter,

View File

@ -1,3 +1,5 @@
//! Handling of `static`s, `const`s and promoted allocations
use rustc_span::DUMMY_SP;
use rustc_data_structures::fx::FxHashSet;

View File

@ -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<DebugReloc>,
@ -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,

View File

@ -1,3 +1,5 @@
//! Line info generation (`.debug_line`)
use std::ffi::OsStr;
use std::path::{Component, Path};

View File

@ -1,3 +1,5 @@
//! Handling of everything related to debuginfo.
mod emit;
mod line_info;
mod unwind;

View File

@ -1,3 +1,5 @@
//! Unwind info generation (`.eh_frame`)
use crate::prelude::*;
use cranelift_codegen::isa::{unwind::UnwindInfo, TargetIsa};

View File

@ -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};

View File

@ -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;

View File

@ -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};

View File

@ -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;

View File

@ -1,3 +1,5 @@
//! Codegen of [`asm!`] invocations.
use crate::prelude::*;
use std::fmt::Write;

View File

@ -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>(

View File

@ -1,3 +1,5 @@
//! Emulate LLVM intrinsics
use crate::intrinsics::*;
use crate::prelude::*;

View File

@ -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;

View File

@ -1,3 +1,5 @@
//! Codegen `extern "platform-intrinsic"` intrinsics.
use super::*;
use crate::prelude::*;

View File

@ -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;

View File

@ -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<IntCC> {

View File

@ -1,3 +1,5 @@
//! Various optimizations specific to cg_clif
use crate::prelude::*;
mod code_layout;

View File

@ -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,

View File

@ -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<String>,

View File

@ -1,3 +1,5 @@
//! Locating various executables part of a C toolchain.
use std::path::PathBuf;
use rustc_middle::bug;

View File

@ -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) {

View File

@ -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

View File

@ -1,3 +1,5 @@
//! Definition of [`CValue`] and [`CPlace`]
use crate::prelude::*;
use cranelift_codegen::entity::EntityRef;

View File

@ -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::*;