Clearly specify the instruction_set effects

src/attributes/codegen.md

@@ -355,15 +355,16 @@ trait object whose methods are attributed.
 
 ## 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 *`instruction_set` [attribute]* may be applied to a function to control which instruction set the function will be generated for.
+This allows mixing more than one instruction set in a single program on CPU architectures that support it.
+It uses the [_MetaListPath_] syntax, and a path comprised of the architecture family name and instruction set name.
 
-The following values are available on targets for the `ARMv4` and `ARMv5te` architectures:
+[_MetaListPath_]: ../attributes.md#meta-item-attribute-syntax
+
+For the `ARMv4T` and `ARMv5te` architectures, the following are supported:
 
-* `arm::a32` - Uses ARM code.
-* `arm::t32` - Uses Thumb code.
+* `arm::a32` - Generate the function as A32 "ARM" code.
+* `arm::t32` - Generate the function as T32 "Thumb" code.
 
 <!-- ignore: arm-only -->
 ```rust,ignore
@@ -374,4 +375,9 @@ fn foo_arm_code() {}
 fn bar_thumb_code() {}
 ```
 
-[_MetaListPath_]: ../attributes.md#meta-item-attribute-syntax
+If your function has neither the `instruction_set` attribute nor inline assembly, then the code you write within that function should not presume any particular instruction set.
+This ends up creating a limitation to how often code is inlined:
+
+* If a function has an `instruction_set` attribute it won't inline into a function of another instruction set.
+* If a function does not have an `instruction_set` attribute but *does* contain inline assembly, then the inline assembly is assumed to require the default instruction set of the build target, and so inlining between different instruction sets won't happen.
+* Otherwise, inlining happens normally.