Add spectral_norm example from packed_simd

Includes some remarks in intrinsics.rs,
generated while auditing the interface for remaining UB.

and other quirks like panicking
and the equivalence to zipping and mapping binary ops

Co-authored-by: Caleb Zulawski <caleb.zulawski@gmail.com>

Remove overflow panic from divrem and add basic docs to Simd<T, N>

This finishes normalizing Simd<T, N> to being approximately equivalent to Simd<Wrapping<T>, N> for all implemented operations I can think of. It also documents this fact, allowing this to close rust-lang/portable-simd#56.

* Explain unsafe contracts of core::simd

This permeates the module with remarks on safety for pub methods,
layout of the Simd type, correct use of intrinsics, et cetera.
This is mostly to help others curious about how core::simd works,
including other Rust contributors, `unsafe` library authors,
and eventually ourselves.

Previously `level` was named `opt` and `option_name` was named `val`,
then extra names of `payload` or `slot` were used for the option value.
This change aligns the wrapper parameters with their names in POSIX.
Winsock uses similar but more abbreviated names: `level`, `optname`,
`optval`, `optlen`.

POSIX allows `getsockopt` to set `*option_len` to a smaller value if
necessary. Windows will set `*option_len` to 1 for boolean options even
when the caller passes a `BOOL` (`int`) with `*option_len` as 4.

This issue was found by the Wine project and mitigated there [1].

Windows' documented interface for `setsockopt` expects a `BOOL` (a
`typedef` for `int`) for `TCP_NODELAY` [2]. Windows is forgiving and
will accept any positive length and interpret the first byte of
`*option_value` as the value, so this bug does not affect Windows
itself, but does affect systems implementing Windows' interface more
strictly, such as Wine. Wine was previously passing this through to the
host's `setsockopt`, where, e.g., Linux requires that `option_len` be
correct for the chosen option, and `TCP_NODELAY` expects an `int`.

[1]: https://source.winehq.org/git/wine.git/commit/d6ea38f32dfd3edbe107a255c37e9f7f3da06ae7
[2]: https://docs.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-setsockopt

Another approach that fixes rust-lang/portable-simd#223, as an alternative to rust-lang/portable-simd#238.

This adds the `ToBitMask` trait, which is implemented on a vector for each bitmask type it supports.  This includes all unsigned integers with enough bits to contain it.  The byte array variant has been separated out for now into rust-lang/portable-simd#246 and still requires `generic_const_exprs`, but the integer variants no longer require it and can make it to nightly.

This expands the existing `#[must_use]` check in `unused_attributes`
to lint against pretty much everything `#[must_use]` doesn't support.
Fixes rust-lang#93906.

…provements, r=estebank

Generalize "remove `&`"  and "add `*`" suggestions to more than one deref

Suggest removing more than one `&` and `&mut`, along with suggesting adding more than one `*` (or a combination of the two).

r? `@estebank`
(since you're experienced with these types of suggestions, feel free to reassign)

…elid

Rustdoc ty consistency fixes

Changes to make rustdoc cleaning of ty more consistent with hir, and hopefully use it in more places.

r? `@camelid`

…xprs, r=cjgillot

Lint against more useless `#[must_use]` attributes

This expands the existing `#[must_use]` check in `unused_attributes` to lint against pretty much everything `#[must_use]` doesn't support.
Fixes rust-lang#93906.

…=dtolnay

use BOOL for TCP_NODELAY setsockopt value on Windows

This issue was found by the Wine project and mitigated there [^1].

Windows' setsockopt expects a BOOL (a typedef for int) for TCP_NODELAY
[^2]. Windows itself is forgiving and will accept any positive optlen and
interpret the first byte of *optval as the value, so this bug does not
affect Windows itself, but does affect systems implementing Windows'
interface more strictly, such as Wine. Wine was previously passing this
through to the host's setsockopt, where, e.g., Linux requires that
optlen be correct for the chosen option, and TCP_NODELAY expects an int.

[^1]: https://source.winehq.org/git/wine.git/commit/d6ea38f32dfd3edbe107a255c37e9f7f3da06ae7
[^2]: https://docs.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-setsockopt

Add Atomic*::from_mut_slice

Tracking issue rust-lang#76314 for `from_mut` has a question about the possibility of `from_mut_slice`, and I found a real case for it. A user in the forum had a parallelism problem that could be solved by open-indexing updates to a vector of atomics, but they didn't want to affect the other code using that vector. Using `from_mut_slice`, they could borrow that data as atomics just long enough for their parallel loop.

ref: https://users.rust-lang.org/t/sharing-vector-with-rayon-par-iter-correctly/72022

…ebank

5 - Make more use of `let_chains`

Continuation of rust-lang#94376.

cc rust-lang#53667

…r=workingjubilee

Sync portable-simd for bitmasks &c.

In the ideal case, where everything works easily and nothing has to be rearranged, it is as simple as:
- `git subtree pull -P library/portable-simd https://github.com/rust-lang/portable-simd - ${branch}`
- write the commit message
- `python x.py test --stage 1` to make sure it runs
- `git push` to your PR-to-rustc branch

If anything borks up this flow, you can fix it with sufficient git wizardry but you are usually better off going back to the source, fixing it, and starting over, before you open the PR.

r? `@calebzulawski`