about summary refs log tree commit diff
path: root/src/doc
AgeCommit message (Collapse)AuthorLines
2021-10-22Describe how to trigger perf runs (#1237)Rémy Rakic-1/+4
2021-10-19Make printed message match the code commentChris Palmer-1/+1
I think this code is getting L0, not L1 cache size, if I'm reading the Intel manual right. (I might not be.) Either way, the code comment and the printed message should match, whichever way is right. :)
2021-10-19Fix minor typosChris Palmer-2/+2
2021-10-19Small scrape-example fixesWill Crichton-1/+1
2021-10-18Remove docs on Assemble step (#1233)Joshua Nelson-19/+4
2021-10-14Revert "Stabilize `arbitrary_enum_discriminant`"Mark Rousskov-0/+37
This reverts commit 7a62f29f3171767090949778ce0f161e930706b9.
2021-10-13Unlinkify email address to satisfy linkcheckerJosh Triplett-1/+1
The linkchecker doesn't seem happy with links to email addresses.
2021-10-13Documentation fixes.Mike Leany-2/+3
Fix broken link to target documentation. Also fix formatting of developer list.
2021-10-13x86_64-unknown-none: Add target documentationJosh Triplett-1/+77
In particular, document the default properties and assumptions of code built for the target. (Work on this target sponsored by Profian.)
2021-10-13Rename x86_64-unknown-none-elf to x86_64-unknown-noneJosh Triplett-1/+1
Most Rust freestanding/bare-metal targets use just `-unknown-none` here, including aarch64-unknown-none, mipsel-unknown-none, and the BPF targets. The *only* target using `-unknown-none-elf` is RISC-V. The underlying toolchain doesn't care; LLVM accepts both `x86_64-unknown-none` and `x86_64-unknown-none-elf`. In addition, there's a long history of embedded x86 targets with varying definitions for the `elf` suffix; on some of those embedded targets, `elf` implied the inclusion of a C library based on newlib or similar. Using `x86_64-unknown-none` avoids any potential ambiguity there. (Work on this target sponsored by Profian.)
2021-10-13Add `x86_64-unknown-none-elf` to `platform-support.md`.Mike Leany-0/+1
2021-10-11Update booksEric Huss-0/+0
2021-10-12Update some docs from 2021-10 date triage (#1230)Yusuke Abe-2/+2
2021-10-11Add -Z no-unique-section-names to reduce ELF header bloat.Javier Blazquez-0/+9
This change adds a new compiler flag that can help reduce the size of ELF binaries that contain many functions. By default, when enabling function sections (which is the default for most targets), the LLVM backend will generate different section names for each function. For example, a function "func" would generate a section called ".text.func". Normally this is fine because the linker will merge all those sections into a single one in the binary. However, starting with LLVM 12 (llvm/llvm-project@ee5d1a0), the backend will also generate unique section names for exception handling, resulting in thousands of ".gcc_except_table.*" sections ending up in the final binary because some linkers don't currently merge or strip these EH sections. This can bloat the ELF headers and string table significantly in binaries that contain many functions. The new option is analogous to Clang's -fno-unique-section-names, and instructs LLVM to generate the same ".text" and ".gcc_except_table" section for each function, resulting in smaller object files and potentially a smaller final binary.
2021-10-10Rollup merge of #89713 - nbdd0121:doc2, r=AmanieuMatthias Krüger-1/+1
Fix ABNF of inline asm options This is the case since #73227. r? `@camelid`
2021-10-10Recommend `rustfmt --edition=2021`Noah Lev-2/+2
2021-10-10Auto merge of #88952 - skrap:add-armv7-uclibc, r=nagisabors-0/+67
Add new tier-3 target: armv7-unknown-linux-uclibceabihf This change adds a new tier-3 target: armv7-unknown-linux-uclibceabihf This target is primarily used in embedded linux devices where system resources are slim and glibc is deemed too heavyweight. Cross compilation C toolchains are available [here](https://toolchains.bootlin.com/) or via [buildroot](https://buildroot.org). The change is based largely on a previous PR #79380 with a few minor modifications. The author of that PR was unable to push the PR forward, and graciously allowed me to take it over. Per the [target tier 3 policy](https://github.com/rust-lang/rfcs/blob/master/text/2803-target-tier-policy.md), I volunteer to be the "target maintainer". This is my first PR to Rust itself, so I apologize if I've missed things!
2021-10-09Fix ABNF of inline asm optionsGary Guo-1/+1
2021-10-08Fix asm docs typoasquared31415-2/+2
2021-10-08Update sanitizer documentationTomasz Miąsko-15/+57
2021-10-08Mention needs-sanitizer-hwaddress directiveTomasz Miąsko-3/+4
2021-10-08Address review commentsOli Scherer-10/+20
2021-10-08Document tracing awesomenessOli Scherer-11/+72
2021-10-08Move log/tracing instructions to its own fileOli Scherer-136/+137
2021-10-07Rollup merge of #89082 - smoelius:master, r=kennytmJubilee-1/+35
Implement #85440 (Random test ordering) This PR adds `--shuffle` and `--shuffle-seed` options to `libtest`. The options are similar to the [`-shuffle` option](https://github.com/golang/go/blob/c894b442d1e5e150ad33fa3ce13dbfab1c037b3a/src/testing/testing.go#L1482-L1499) that was recently added to Go. Here are the relevant parts of the help message: ``` --shuffle Run tests in random order --shuffle-seed SEED Run tests in random order; seed the random number generator with SEED ... By default, the tests are run in alphabetical order. Use --shuffle or set RUST_TEST_SHUFFLE to run the tests in random order. Pass the generated "shuffle seed" to --shuffle-seed (or set RUST_TEST_SHUFFLE_SEED) to run the tests in the same order again. Note that --shuffle and --shuffle-seed do not affect whether the tests are run in parallel. ``` Is an RFC needed for this?
2021-10-07Rollup merge of #87918 - mikebenfield:pr-afdo, r=nikicJubilee-0/+45
Enable AutoFDO. This largely involves implementing the options debug-info-for-profiling and profile-sample-use and forwarding them on to LLVM. AutoFDO can be used on x86-64 Linux like this: rustc -O -Clink-arg='Wl,--no-rosegment' -Cdebug-info-for-profiling main.rs -o main perf record -b ./main create_llvm_prof --binary=main --out=code.prof rustc -O -Cprofile-sample-use=code.prof main.rs -o main2 Now `main2` will have feedback directed optimization applied to it. The create_llvm_prof tool can be obtained from this github repository: https://github.com/google/autofdo The option -Clink-arg='Wl,--no-rosegment' is necessary to avoid lld putting an extra RO segment before the executable code, which would make the binary silently incompatible with create_llvm_prof.
2021-10-07Update src/closure.mdEric Holk-1/+1
Co-authored-by: Joshua Nelson <github@jyn.dev>
2021-10-07Fix accidental HTML tagEric Holk-1/+1
The markdown parser was interpreting the `<something>` in `adjust_upvar_borrow_kind_for_<something>` as an HTML tag that was hidden in the rendered text. This minor edit fixes that.
2021-10-06Update to latest rustc and rustdoc stylesWill Crichton-0/+14
2021-10-06Enable AutoFDO.Michael Benfield-0/+45
This largely involves implementing the options debug-info-for-profiling and profile-sample-use and forwarding them on to LLVM. AutoFDO can be used on x86-64 Linux like this: rustc -O -Cdebug-info-for-profiling main.rs -o main perf record -b ./main create_llvm_prof --binary=main --out=code.prof rustc -O -Cprofile-sample-use=code.prof main.rs -o main2 Now `main2` will have feedback directed optimization applied to it. The create_llvm_prof tool can be obtained from this github repository: https://github.com/google/autofdo Fixes #64892.
2021-10-06Rollup merge of #89324 - yoshuawuyts:hardware-parallelism, r=m-ou-seManish Goregaokar-2/+2
Rename `std::thread::available_conccurrency` to `std::thread::available_parallelism` _Tracking issue: https://github.com/rust-lang/rust/issues/74479_ This PR renames `std::thread::available_conccurrency` to `std::thread::available_parallelism`. ## Rationale The API was initially named `std::thread::hardware_concurrency`, mirroring the [C++ API of the same name](https://en.cppreference.com/w/cpp/thread/thread/hardware_concurrency). We eventually decided to omit any reference to the word "hardware" after [this comment](https://github.com/rust-lang/rust/pull/74480#issuecomment-662045841). And so we ended up with `available_concurrency` instead. --- For a talk I was preparing this week I was reading through ["Understanding and expressing scalable concurrency" (A. Turon, 2013)](http://aturon.github.io/academic/turon-thesis.pdf), and the following passage stood out to me (emphasis mine): > __Concurrency is a system-structuring mechanism.__ An interactive system that deals with disparate asynchronous events is naturally structured by division into concurrent threads with disparate responsibilities. Doing so creates a better fit between problem and solution, and can also decrease the average latency of the system by preventing long-running computations from obstructing quicker ones. > __Parallelism is a resource.__ A given machine provides a certain capacity for parallelism, i.e., a bound on the number of computations it can perform simultaneously. The goal is to maximize throughput by intelligently using this resource. For interactive systems, parallelism can decrease latency as well. _Chapter 2.1: Concurrency is not Parallelism. Page 30._ --- _"Concurrency is a system-structuring mechanism. Parallelism is a resource."_ — It feels like this accurately captures the way we should be thinking about these APIs. What this API returns is not "the amount of concurrency available to the program" which is a property of the program, and thus even with just a single thread is effectively unbounded. But instead it returns "the amount of _parallelism_ available to the program", which is a resource hard-constrained by the machine's capacity (and can be further restricted by e.g. operating systems). That's why I'd like to propose we rename this API from `available_concurrency` to `available_parallelism`. This still meets the criteria we previously established of not attempting to define what exactly we mean by "hardware", "threads", and other such words. Instead we only talk about "concurrency" as an abstract resource available to our program. r? `@joshtriplett`
2021-10-06add platform support details file for armv7-unknown-linux-uclibcJonah Petri-0/+66
2021-10-06Add new target armv7-unknown-linux-uclibceabihfYannick Koehler-0/+1
Co-authored-by: Jonah Petri <jonah@petri.us>
2021-10-06Update links to `rustc_mir` in Two Phase Borrows (#1226)Janggun Lee-3/+3
https://github.com/rust-lang/rust/pull/80522 split the `rustc_mir` crates into 5 crates, effectively invalidating all the direct links to `rustc_mir` in the docs. I found this while looking at the Two Phase Borrows doc, which is why I am giving out this PR to fix this.
2021-10-05Add tracking issueSamuel E. Moelius III-2/+4
2021-10-05Update some docs from 2021-10 date triage (#1224)Noah Lev-15/+11
2021-10-04Add documentationSamuel E. Moelius III-1/+33
2021-10-02Fix typos in rustdoc/lintsTobias Nießen-3/+3
Refs: https://github.com/rust-lang/rust/pull/85223
2021-10-01Rollup merge of #88847 - oliverbr:master, r=steveklabnikManish Goregaokar-2/+2
platform-support.md: correct ARMv7+MUSL platform triple notes This PR fixes two minor inconsistencies in the platform support list. - use "with MUSL" suffix for "armv7-unknown-linux-musleabi" - add "hardfloat" suffix for "armv7-unknown-linux-musleabihf" r? `@steveklabnik`
2021-10-01Rollup merge of #85223 - simbleau:master, r=steveklabnikManish Goregaokar-0/+6
rustdoc: Clarified the attribute which prompts the warning The example call was lacking clarification of the `#![warn(rustdoc::invalid_codeblock_attributes)]` attribute which generates the specified warning.
2021-10-01Rollup merge of #88820 - hlopko:add_pie_relocation_model, r=petrochenkovManish Goregaokar-0/+4
Add `pie` as another `relocation-model` value MCP: https://github.com/rust-lang/compiler-team/issues/461
2021-10-01Add `pie` as another `relocation-model` valueMarcel Hlopko-0/+4
2021-09-29Update booksEric Huss-0/+0
2021-09-28Rename `std::thread::available_onccurrency` to ↵Yoshua Wuyts-2/+2
`std::thread::available_parallelism`
2021-09-28Add SOLID targetsTomoaki Kawada-0/+69
SOLID[1] is an embedded development platform provided by Kyoto Microcomputer Co., Ltd. This commit introduces a basic Tier 3 support for SOLID. # New Targets The following targets are added: - `aarch64-kmc-solid_asp3` - `armv7a-kmc-solid_asp3-eabi` - `armv7a-kmc-solid_asp3-eabihf` SOLID's target software system can be divided into two parts: an RTOS kernel, which is responsible for threading and synchronization, and Core Services, which provides filesystems, networking, and other things. The RTOS kernel is a μITRON4.0[2][3]-derived kernel based on the open-source TOPPERS RTOS kernels[4]. For uniprocessor systems (more precisely, systems where only one processor core is allocated for SOLID), this will be the TOPPERS/ASP3 kernel. As μITRON is traditionally only specified at the source-code level, the ABI is unique to each implementation, which is why `asp3` is included in the target names. More targets could be added later, as we support other base kernels (there are at least three at the point of writing) and are interested in supporting other processor architectures in the future. # C Compiler Although SOLID provides its own supported C/C++ build toolchain, GNU Arm Embedded Toolchain seems to work for the purpose of building Rust. # Unresolved Questions A μITRON4 kernel can support `Thread::unpark` natively, but it's not used by this commit's implementation because the underlying kernel feature is also used to implement `Condvar`, and it's unclear whether `std` should guarantee that parking tokens are not clobbered by other synchronization primitives. # Unsupported or Unimplemented Features Most features are implemented. The following features are not implemented due to the lack of native support: - `fs::File::{file_attr, truncate, duplicate, set_permissions}` - `fs::{symlink, link, canonicalize}` - Process creation - Command-line arguments Backtrace generation is not really a good fit for embedded targets, so it's intentionally left unimplemented. Unwinding is functional, however. ## Dynamic Linking Dynamic linking is not supported. The target platform supports dynamic linking, but enabling this in Rust causes several problems. - The linker invocation used to build the shared object of `std` is too long for the platform-provided linker to handle. - A linker script with specific requirements is required for the compiled shared object to be actually loadable. As such, we decided to disable dynamic linking for now. Regardless, the users can try to create shared objects by manually invoking the linker. ## Executable Building an executable is not supported as the notion of "executable files" isn't well-defined for these targets. [1] https://solid.kmckk.com/SOLID/ [2] http://ertl.jp/ITRON/SPEC/mitron4-e.html [3] https://en.wikipedia.org/wiki/ITRON_project [4] https://toppers.jp/
2021-09-24Fix a typo on closure.md (#1218)Dave Farnham-1/+1
2021-09-23Auto merge of #87064 - Aaron1011:new-closure-track-caller, r=estebankbors-0/+12
Support `#[track_caller]` on closures and generators ## Lang team summary This PR adds support for placing the `#[track_caller]` attribute on closure and generator expressions. This attribute's addition behaves identically (from a users perspective) to the attribute being placed on the method in impl Fn/FnOnce/FnMut for ... generated by compiler. The attribute is currently "double" feature gated -- both `stmt_expr_attributes` (preexisting) and `closure_track_caller` (newly added) must be enabled in order to place these attributes on closures. As the Fn* traits lack a `#[track_caller]` attribute in their definition, caller information does not propagate when invoking closures through dyn Fn*. There is no limitation that this PR adds in supporting this; it can be added in the future. # Implementation details This is implemented in the same way as for functions - an extra location argument is appended to the end of the ABI. For closures, this argument is *not* part of the 'tupled' argument storing the parameters - the final closure argument for `#[track_caller]` closures is no longer a tuple. For direct (monomorphized) calls, the necessary support was already implemented - we just needeed to adjust some assertions around checking the ABI and argument count to take closures into account. For calls through a trait object, more work was needed. When creating a `ReifyShim`, we need to create a shim for the trait method (e.g. `FnOnce::call_mut`) - unlike normal functions, closures are never invoked directly, and always go through a trait method. Additional handling was needed for `InstanceDef::ClosureOnceShim`. In order to pass location information throgh a direct (monomorphized) call to `FnOnce::call_once` on an `FnMut` closure, we need to make `ClosureOnceShim` aware of `#[tracked_caller]`. A new field `track_caller` is added to `ClosureOnceShim` - this is used by `InstanceDef::requires_caller` location, allowing codegen to pass through the extra location argument. Since `ClosureOnceShim.track_caller` is only used by codegen, we end up generating two identical MIR shims - one for `track_caller == true`, and one for `track_caller == false`. However, these two shims are used by the entire crate (i.e. it's two shims total, not two shims per unique closure), so this shouldn't a big deal.
2021-09-22Support `#[track_caller]` on closures and generatorsAaron Hill-0/+12
This PR allows applying a `#[track_caller]` attribute to a closure/generator expression. The attribute as interpreted as applying to the compiler-generated implementation of the corresponding trait method (`FnOnce::call_once`, `FnMut::call_mut`, `Fn::call`, or `Generator::resume`). This feature does not have its own feature gate - however, it requires `#![feature(stmt_expr_attributes)]` in order to actually apply an attribute to a closure or generator. This is implemented in the same way as for functions - an extra location argument is appended to the end of the ABI. For closures, this argument is *not* part of the 'tupled' argument storing the parameters - the final closure argument for `#[track_caller]` closures is no longer a tuple. For direct (monomorphized) calls, the necessary support was already implemented - we just needeed to adjust some assertions around checking the ABI and argument count to take closures into account. For calls through a trait object, more work was needed. When creating a `ReifyShim`, we need to create a shim for the trait method (e.g. `FnOnce::call_mut`) - unlike normal functions, closures are never invoked directly, and always go through a trait method. Additional handling was needed for `InstanceDef::ClosureOnceShim`. In order to pass location information throgh a direct (monomorphized) call to `FnOnce::call_once` on an `FnMut` closure, we need to make `ClosureOnceShim` aware of `#[tracked_caller]`. A new field `track_caller` is added to `ClosureOnceShim` - this is used by `InstanceDef::requires_caller` location, allowing codegen to pass through the extra location argument. Since `ClosureOnceShim.track_caller` is only used by codegen, we end up generating two identical MIR shims - one for `track_caller == true`, and one for `track_caller == false`. However, these two shims are used by the entire crate (i.e. it's two shims total, not two shims per unique closure), so this shouldn't a big deal.
2021-09-21Fix inconsistent heading level in the rustdoc bookNoah Lev-1/+1
2021-09-21Document `--show-type-layout` in the rustdoc bookNoah Lev-0/+16