Multiple issues with Saturating Instructions Chapter in all DGUG for Cortex-M

Hi All:

I am currently studying the Saturation functionality on Cortex-M, the hardware I have access to is Cortex-M4F, but I have similar issues with this chapter in all of the Devices Generic User Guides for all the models that have this functionality.

I think there are several issues with the wording and formatting of this "Saturating Instructions" chapter that were making it rough going.

I normally use the recommended form to suggest any suspected errors in the documentation, but in the case of this chapter there were a whole bunch found across each of the five DGUGs I reviewed, and they aren't simple "Said X should read Y instead" comments.

Systemic Upstream Build Pipeline & Template Defect Report

Target Documentation: Cortex-M Developer Guides / Generic User Guides (DGUGs: Cortex-M4, Cortex-M7, Cortex-M33, Cortex-M55, Cortex-M85)

Subject: Master Source-Tree Audit: Macro Leaks, Vocabulary Hallucinations, and Syntax Template Failures in DSP/SIMD Instruction Sections

Executive Summary

An audit of the SIMD and DSP extension instruction chapters across mainline Cortex-M Programmer’s / Developer's Guides reveals multiple systemic, cross-document build-pipeline and authoring defects. These include invalid UAL assembler syntax templates, non-existent architectural terminology, dissociated arithmetic descriptions, math-rendering exponent flattening, and dangling macro-variable leakage.

Because these patterns appear uniformly across multiple product generations (Cortex-M4 through M85), they trace directly back to an upstream DITA/XML source template corruption rather than isolated human typos.

Detailed Errata Categories & Evidence

1. Dangling Syntax Comma Defect ({Rd},)

• Location: Instruction syntax header tables (e.g., UQADD, UQSUB, SIMD variants).
• Defect: The destination register and trailing comma are bracketed incorrectly as {Rd}, rather than {Rd,}.
• Impact: Instructs the user to generate invalid Unified Assembly Language (UAL) syntax with a leading dangling comma (OP , Rn, Rm) if the destination register is omitted, which causes immediate fatal syntax errors in standard assemblers like arm-none-eabi-as.

2. Vocabulary Hallucination: Non-Standard Terminology ("Highword")

• Location: Exchange instruction descriptions (QASX, QSAX, SHASX, SHSAX, and unsigned variants).
• Defect: The non-word "highword" (and phrases like "bottom highword" or "top highword") appears 8+ times per document across mainline DGUGs.
• Impact: Contradicts canonical Arm nomenclature. A 32-bit Arm register is a word, divided strictly into a "top halfword" (bits) and a "bottom halfword" (bits [15:0]). "Bottom highword" is a physical and semantic impossibility. (A grep check of the ARMv7-M Architecture Reference Manual returns 269 references to "halfword/halfwords" and 0 references to "highword").

3. Arithmetic Noun Dissociation and Procedural Scrambling

• Location: Sequential step definitions in SIMD exchange and halving instructions (SHASX, SHSAX).
• Defect: The text exhibits internal logical contradictions between operational steps. For example, a step explicitly executing a subtraction is described as saving the result of an "addition" or a "division", and vice versa.
• Impact: Completely scrambles the functional explanation of cross-lane exchange mathematics, forcing developers to bypass the user guide entirely to guess correct silicon behavior from the ARM ARM.

4. Renderer Exponent Flattening

• Location: Mathematical range boundary descriptions across saturation sections.
• Defect: Superscript XML/HTML tags for mathematical exponents are stripped entirely during PDF rendering, converting formal bounds like  into flat strings like -215.
• Impact: Renders bit-depth saturation boundaries visually nonsensical (e.g., presenting negative two-hundred-and-fifteen as a 16-bit signed integer range limit).

5. Macro Variable Shadowing and Parameter Leakage ("where x equals 16")

• Location: Saturation range appendices.
• Defect: Descriptions conclude with redundant, self-contradictory macro residue, such as:

"... writes a 16-bit signed integer in the range –215 ≤ x ≤ 215 – 1, where x equals 16, to the top halfword..."

• Impact: The template variable name (x) was reused for both the equation range parameter and the bit-depth constant (). When exponents were flattened and math hardcoded, the trailing variable assignment leaked into the final published text verbatim, yielding sentences that nonsensically assert that the result of the instruction is always explicitly the integer 16.

Recommended Remediation

1. Source Template Refactor: Audit the master DITA/XML template used for data-processing instruction headers to correct optionality bracket nesting ({Rd,}).
2. Global Terminology Sweep: Execute a case-insensitive search-and-destroy script for the string "highword" across all technical publication repositories, replacing it with canonical top/bottom halfword terminology.
3. ASL Cross-Verification: Re-generate the step-by-step prose descriptions for exchange and halving instructions (QASX, SHASX, etc.) directly from the formal Architecture Specification Language (ASL) models to eliminate arithmetic noun scrambling and leaked macro variables.