More guide improvements.

- Use full names for `rustc_codegen_*` crates rather than shortened
  `cg_*` forms.
- Streamline `rustc_codegen_ssa` description.
- Minor grammer, punctuation, capitalization fixes.
- Fix formatting of some lists.

Author: nnethercote

guide/src/faq.md

@@ -153,7 +153,7 @@ things to gain in terms of safety using Rust.
 The reasoning for this is the same reasoning as to why you would use CUDA over opengl/vulkan compute shaders:
 - CUDA usually outperforms shaders if kernels are written well and launch configurations are optimal.
 - CUDA has many useful features such as shared memory, unified memory, graphs, fine grained thread control, streams, the PTX ISA, etc.
-- rust-gpu does not perform many optimizations, and with cg_ssa's less than ideal codegen, the optimizations by llvm and libnvvm are needed.
+- rust-gpu does not perform many optimizations, and with rustc_codegen_ssa's less than ideal codegen, the optimizations by llvm and libnvvm are needed.
 - SPIRV is arguably still not suitable for serious GPU kernel codegen, it is underspecced, complex, and does not mention many things which are needed.
 While libnvvm (which uses a well documented subset of LLVM IR) and the PTX ISA are very thoroughly documented/specified.
 - rust-gpu is primarily focused on graphical shaders, compute shaders are secondary, which the rust ecosystem needs, but it also 

guide/src/nvvm/backends.md

@@ -15,13 +15,13 @@ Nowadays, Rustc is almost fully decoupled from LLVM and it is instead generic ov
 Rustc instead uses a system of codegen backends that implement traits and then get loaded as dynamically linked libraries.
 This allows rust to compile to virtually anything with a surprisingly small amount of work. At the time of writing, there are
 five publicly known codegens that exist:
-- rustc_codegen_clif, cranelift
+- rustc_codegen_cranelift
 - rustc_codegen_llvm
 - rustc_codegen_gcc
 - rustc_codegen_spirv
 - rustc_codegen_nvvm, obviously the best codegen ;)
 
-`rustc_codegen_clif` targets the cranelift backend, which is a codegen backend written in rust that is faster than LLVM but does not have many optimizations
+`rustc_codegen_cranelift` targets the cranelift backend, which is a codegen backend written in rust that is faster than LLVM but does not have many optimizations
 compared to LLVM. `rustc_codegen_llvm` is obvious, it is the backend almost everybody uses which targets LLVM. `rustc_codegen_gcc` targets GCC (GNU Compiler Collection)
 which is able to target more exotic targets than LLVM, especially for embedded. `rustc_codegen_spirv` targets the SPIR-V (Standard Portable Intermediate Representation 5)
 format, which is a format mostly used for compiling shader languages such as GLSL or WGSL to a standard representation that Vulkan/OpenGL can use, the reasons
@@ -32,16 +32,12 @@ What NVVM IR/libnvvm are has been covered in the [CUDA section](../../cuda/pipel
 
 # rustc_codegen_ssa
 
-Despite its name, `rustc_codegen_ssa` does not actually codegen to anything, it is however the central crate behind every single codegen.
-The SSA codegen does most of the hard work in codegen, which is actually codegenning MIR and taking care of managing codegen altogether.
+`rustc_codegen_ssa` is the central crate behind every single codegen and does much of the hard work.
+It abstracts away the MIR lowering logic so that custom codegens only have to implement some
+traits and the SSA codegen does everything else. For example:
+- A trait for getting a type like an integer type.
+- A trait for optimizing a module.
+- A trait for linking everything.
+- A trait for declaring a function.
 
-The SSA codegen abstracts away the MIR lowering logic so that custom codegens do not have to implement the time consuming logic of lowering MIR,
-they can just implement a bunch of traits and the SSA codegen does everything else.
-
-The SSA codegen is literally just a bunch of traits, for example:
-- A trait for getting a type like an integer type
-- A trait for optimizing a module
-- A trait for linking everything
-- A trait for declaring a function
-...etc
-You will find an SSA codegen trait in almost every single file.
+And so on. You will find an SSA codegen trait in almost every file.

guide/src/nvvm/debugging.md

@@ -34,7 +34,7 @@ which i will add to the project soon.
 
 Miscompilations are rare but annoying. They usually result in one of two things happening:
 - CUDA rejecting the PTX as a whole (throwing an InvalidPtx error). This is rare but the most common cause is declaring invalid
-extern functions (just grep for `extern` in the ptx file and check if its odd functions that arent cuda syscalls like vprintf, malloc, free, etc).
+extern functions (just grep for `extern` in the ptx file and check if it's odd functions that aren't cuda syscalls like vprintf, malloc, free, etc).
 - The PTX containing invalid behavior. This is very specific and rare but if you find this, the best way to debug it is:
   - Try to get a minimal working example so we don't have to search through megabytes of llvm ir/ptx.
   - Use `RUSTFLAGS="--emit=llvm-ir"` and find `crate_name.ll` in `target/nvptx64-nvidia-cuda/<debug/release>/deps/` and attach it in any bug report.

guide/src/nvvm/nvvm.md

@@ -42,15 +42,18 @@ dive into each trait.
 
 But first, let's talk about the end of the codegen, it is pretty simple, we do a couple of things:
 *after codegen is done and LLVM has been run to optimize each module*
-- 1: We gather every llvm bitcode module we created.
-- 2: We create a new libnvvm program.
-- 3: We add every bitcode module to the libnvvm program.
-- 4: We try to find libdevice and add it to the program (see [nvidia docs](https://docs.nvidia.com/cuda/libdevice-users-guide/introduction.html#what-is-libdevice) on what libdevice is).
-- 5: We run the verifier on the nvvm program just to check that we did not create any invalid nvvm ir.
-- 6: We run the compiler which gives us a final PTX string, hooray!
-- 7: Finally, the PTX goes through a small stage where its parsed and function DCE is run to eliminate
-     Most of the bloat in the file, traditionally this is done by the linker but theres no linker to be found for miles here.
-- 8: We write this ptx file to wherever rustc tells us to write the final file.
+1. We gather every LLVM bitcode module we created.
+2. We create a new libnvvm program.
+3. We add every bitcode module to the libnvvm program.
+4. We try to find libdevice and add it to the program (see [nvidia
+   docs](https://docs.nvidia.com/cuda/libdevice-users-guide/introduction.html#what-is-libdevice) on
+   what libdevice is).
+5. We run the verifier on the nvvm program just to check that we did not create any invalid NVVM IR.
+6. We run the compiler which gives us a final PTX string, hooray!
+7. Finally, the PTX goes through a small stage where its parsed and function DCE is run to
+   eliminate most of the bloat in the file. Traditionally this is done by the linker but there's no
+   linker to be found for miles here.
+8. We write this PTX file to wherever rustc tells us to write the final file.
 
 We will cover the libnvvm steps in more detail later on.
 
@@ -71,12 +74,12 @@ rlibs are mysterious files, their origins are mysterious and their contents are
 but rlibs often confuse people (including me at first). Rlibs are rustc's way of encoding basically everything it needs to know 
 about a crate into a file. Rlibs usually contain the following:
 - Object files for each CGU.
-- LLVM Bitcode.
-- a Symbol table.
-- metadata:
-  - rustc version (because things can go kaboom if version mismatches, ABIs are fun amirite)
+- LLVM bitcode.
+- A symbol table.
+- Metadata:
+  - The rustc version (because things can go kaboom if version mismatches, ABIs are fun amirite)
   - A crate hash
-  - a crate id
-  - info about the source files
-  - the exported API, things like macros, traits, etc.
+  - A crate id
+  - Info about the source files
+  - The exported API, things like macros, traits, etc.
   - MIR, for things such as generic functions and `#[inline]`d functions (please don't put `#[inline]` on everything, rustc will cry)

guide/src/nvvm/types.md

@@ -4,7 +4,7 @@ Types! who doesn't love types, especially those that cause libnvvm to randomly s
 Anyways, types are an integral part of the codegen and everything revolves around them and you will see them everywhere.
 
 `rustc_codegen_ssa` does not actually tell you what your type representation should be, it allows you to decide. For
-example, `rust-gpu` represents it as a `SpirvType` enum, while both `cg_llvm` and our codegen represent it as 
+example, `rust-gpu` represents it as a `SpirvType` enum, while both `rustc_codegen_llvm` and our codegen represent it as 
 opaque llvm types:
 
 ```rs
@@ -13,7 +13,7 @@ type Type = &'ll llvm::Type;
 
 `llvm::Type` is an opaque type that comes from llvm-c. `'ll` is one of the main lifetimes you will see
 throughout the whole codegen, it is used for anything that lasts as long as the current usage of llvm. 
-LLVM gives you back pointers when you ask for a type or value, some time ago `cg_llvm` fully switched to using
+LLVM gives you back pointers when you ask for a type or value, some time ago rustc_codegen_llvm fully switched to using
 references over pointers, and we follow in their footsteps. 
 
 One important fact about types is that they are opaque, you cannot take a type and ask "is this X struct?",