Document RFC 2867: instruction_set attribute

src/attributes.md

@@ -246,6 +246,7 @@ The following is an index of all built-in attributes.
   - [`no_builtins`] — Disables use of certain built-in functions.
   - [`target_feature`] — Configure platform-specific code generation.
   - [`track_caller`] - Pass the parent call location to `std::panic::Location::caller()`.
+  - [`instruction_set`] - Specify the instruction set used to generate a functions code
 - Documentation
   - `doc` — Specifies documentation. See [The Rustdoc Book] for more
     information. [Doc comments] are transformed into `doc` attributes.
@@ -296,6 +297,7 @@ The following is an index of all built-in attributes.
 [`global_allocator`]: runtime.md#the-global_allocator-attribute
 [`ignore`]: attributes/testing.md#the-ignore-attribute
 [`inline`]: attributes/codegen.md#the-inline-attribute
+[`instruction_set`]: attributes/codegen.md#the-instruction_set-attribute
 [`link_name`]: items/external-blocks.md#the-link_name-attribute
 [`link_section`]: abi.md#the-link_section-attribute
 [`link`]: items/external-blocks.md#the-link-attribute

src/attributes/codegen.md

@@ -352,3 +352,26 @@ trait object whose methods are attributed.
 [`core::intrinsics::caller_location`]: ../../core/intrinsics/fn.caller_location.html
 [`core::panic::Location::caller`]: ../../core/panic/struct.Location.html#method.caller
 [`Location`]: ../../core/panic/struct.Location.html
+
+## The `instruction_set` attribute
+
+The *`instruction_set` attribute* may be applied to a function to enable code generation for a specific
+instruction set supported by the target architecture. It uses the [_MetaListPath_] syntax and a path
+comprised of the architecture and instruction set to specify how to generate the code for
+architectures where a single program may utilize multiple instruction sets.
+
+The following values are available on targets for the `ARMv4` and `ARMv5te` architectures:
+
+* `arm::a32` - Uses ARM code.
+* `arm::t32` - Uses Thumb code.
+
+<!-- ignore: arm-only -->
+```rust,ignore
+#[instruction_set(arm::a32)]
+fn foo_arm_code() {}
+
+#[instruction_set(arm::t32)]
+fn bar_thumb_code() {}
+```
+
+[_MetaListPath_]: ../attributes.md#meta-item-attribute-syntax