[PATCH v3 6/6] gdb/doc: Document AArch64 FPMR support

[<Ezra.Sitorus@arm.com>]

From: Ezra Sitorus <ezra.sitorus@arm.com>

Add NEWS entry and document new feature in gdb.texinfo.

---
Changes from v1->v3:
* This is new in v3.

Ezra

 gdb/NEWS            | 104 ++++++++++++++++++++++----------------------
 gdb/doc/gdb.texinfo |  71 ++++++++++++++++++++++++++++++
 2 files changed, 124 insertions(+), 51 deletions(-)

diff --git a/gdb/NEWS b/gdb/NEWS
index 01bd1524c7a..75e979b4e9f 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -14,6 +14,8 @@
   this flag is used gdbserver will not escape special shell characters
   within the inferior arguments.
 
+* Support for Floating Point Mode Register (FPMR) in AArch64.
+
 * New targets
 
 GNU/Linux/MicroBlaze (gdbserver) microblazeel-*linux*
@@ -1380,7 +1382,7 @@ AMDGPU amdgcn-*-*
 * New features in the GDB remote stub, GDBserver
 
   ** GDBserver is now supported on LoongArch GNU/Linux.
-  
+
   ** GDBserver is now supported on CSKY GNU/Linux.
 
 * LoongArch floating-point support
@@ -2274,7 +2276,7 @@ pipe -d DELIM COMMAND DELIM SHELL_COMMAND
 
 define-prefix COMMAND
   Define or mark a command as a user-defined prefix command.
-  
+
 with SETTING [VALUE] [-- COMMAND]
 w SETTING [VALUE] [-- COMMAND]
   Temporarily set SETTING, run COMMAND, and restore SETTING.
@@ -3384,7 +3386,7 @@ show disassembler-options
        0x40057b <main(int, char**)+25>:
         callq  0x400536 <Func1(int, char const*)>
 
-* Fortran: Support structures with fields of dynamic types and 
+* Fortran: Support structures with fields of dynamic types and
   arrays of dynamic types.
 
 * The symbol dumping maintenance commands have new syntax.
@@ -3996,7 +3998,7 @@ vforkdone stop reason
   an exec or exit, allowing the vfork parent to resume execution.
 
 fork-events and vfork-events features in qSupported
-  The qSupported packet allows GDB to request support for fork and 
+  The qSupported packet allows GDB to request support for fork and
   vfork events using new 'gdbfeatures' fork-events and vfork-events,
   and the qSupported response can contain the corresponding
   'stubfeatures'.  Set and show commands can be used to display
@@ -4065,7 +4067,7 @@ Itanium running HP-UX         ia64-*-hpux*
   ** You can now add attributes to gdb.Objfile and gdb.Progspace objects.
   ** New function gdb.lookup_objfile.
 
-  New events which are triggered when GDB modifies the state of the 
+  New events which are triggered when GDB modifies the state of the
   inferior.
 
   ** gdb.events.inferior_call_pre: Function call is about to be made.
@@ -4732,7 +4734,7 @@ Tilera TILE-Gx GNU/Linux	tilegx*-*-linux
 
 * New commands (for set/show, see "New options" below)
 
-catch signal 
+catch signal
   Catch signals.  This is similar to "handle", but allows commands and
   conditions to be attached.
 
@@ -4816,14 +4818,14 @@ show debug notification
      "=memory-changed".
   ** The data-disassemble command response will include a "fullname" field
      containing the absolute file name when source has been requested.
-  ** New optional parameter COUNT added to the "-data-write-memory-bytes" 
+  ** New optional parameter COUNT added to the "-data-write-memory-bytes"
      command, to allow pattern filling of memory areas.
   ** New commands "-catch-load"/"-catch-unload" added for intercepting
      library load/unload events.
   ** The response to breakpoint commands and breakpoint async records
      includes an "installed" field containing a boolean state about each
      non-pending tracepoint location is whether installed on target or not.
-  ** Output of the "-trace-status" command includes a "trace-file" field 
+  ** Output of the "-trace-status" command includes a "trace-file" field
      containing the name of the trace file being examined.  This field is
      optional, and only present when examining a trace file.
   ** The "fullname" field is now always present along with the "file" field,
@@ -4880,8 +4882,8 @@ qXfer:btrace:read
   in <http://sourceware.org/systemtap/>.
 
 * GDB now supports reversible debugging on ARM, it allows you to
-  debug basic ARM and THUMB instructions, and provides 
-  record/replay support.  
+  debug basic ARM and THUMB instructions, and provides
+  record/replay support.
 
 * The option "symbol-reloading" has been deleted as it is no longer used.
 
@@ -5193,7 +5195,7 @@ QProgramSignals:
      replaced it.  Additionally, the default for "print-stack" is
      now "message", which just prints the error message without
      the stack trace.
-   
+
   ** A prompt substitution hook (prompt_hook) is now available to the
      Python API.
 
@@ -5220,7 +5222,7 @@ QProgramSignals:
 
   ** A new class "gdb.FinishBreakpoint" is provided to catch the return
      of a function.  This class is based on the "finish" command
-     available in the CLI. 
+     available in the CLI.
 
   ** Type objects for struct and union types now allow access to
      the fields using standard Python dictionary (mapping) methods.
@@ -5397,7 +5399,7 @@ show trace-stop-notes
 * New remote packets
 
 QTEnable
-  
+
   Dynamically enable a tracepoint in a started trace experiment.
 
 QTDisable
@@ -5484,7 +5486,7 @@ Renesas RL78				rl78-*-elf
 
   ** Breakpoints can now be sub-classed in Python, and in particular
      you may implement a 'stop' function that is executed each time
-     the inferior reaches that breakpoint.   
+     the inferior reaches that breakpoint.
 
   ** New function gdb.lookup_global_symbol looks up a global symbol.
 
@@ -5639,8 +5641,8 @@ Analog Devices, Inc. Blackfin Processor	bfin-*
   arguments even if the namespace has not been imported.
   For example:
     namespace A
-      { 
-        class B { }; 
+      {
+        class B { };
         void foo (B) { }
       }
     ...
@@ -6040,7 +6042,7 @@ source
 * New commands (for set/show, see "New options" below)
 
 record save [<FILENAME>]
-  Save a file (in core file format) containing the process record 
+  Save a file (in core file format) containing the process record
   execution log for replay debugging at a later time.
 
 record restore <FILENAME>
@@ -6312,7 +6314,7 @@ qXfer:siginfo:write
 
 * GDB now supports multiple function calling conventions according to the
 DWARF-2 DW_AT_calling_convention function attribute.
-  
+
 * The SH target utilizes the aforementioned change to distinguish between gcc
 and Renesas calling convention.  It also adds the new CLI commands
 `set/show sh calling-convention'.
@@ -6568,7 +6570,7 @@ show multiple-symbols
   The value of this variable can be changed to adjust the debugger behavior
   when an expression or a breakpoint location contains an ambiguous symbol
   name (an overloaded function name, for instance).
-  
+
 set breakpoint always-inserted
 show breakpoint always-inserted
   Keep breakpoints always inserted in the target, as opposed to inserting
@@ -6811,7 +6813,7 @@ vRun
 
 *** Changes in GDB 6.7
 
-* Resolved 101 resource leaks, null pointer dereferences, etc. in gdb, 
+* Resolved 101 resource leaks, null pointer dereferences, etc. in gdb,
 bfd, libiberty and opcodes, as revealed by static analysis donated by
 Coverity, Inc. (http://scan.coverity.com).
 
@@ -6823,7 +6825,7 @@ symbol definition in the current shared library if it was built using the
 recognize the -tui command-line option and print a message that the TUI
 is not supported.
 
-* The GDB remote stub, gdbserver, now has lower overhead for high 
+* The GDB remote stub, gdbserver, now has lower overhead for high
 frequency signals (e.g. SIGALRM) via the QPassSignals packet.
 
 * GDB for MIPS targets now autodetects whether a remote target provides
@@ -6861,7 +6863,7 @@ has been rewritten to use the standard GDB remote protocol.
 layout.  It also supports a TextSeg= and DataSeg= response when only
 segment base addresses (rather than offsets) are available.
 
-* The /i format now outputs any trailing branch delay slot instructions 
+* The /i format now outputs any trailing branch delay slot instructions
 immediately following the last instruction within the count specified.
 
 * The GDB remote protocol "T" stop reply packet now supports a
@@ -7008,7 +7010,7 @@ target ocd
 
 DWARF 1 support
 
-	A debug information format.  The predecessor to DWARF 2 and 
+	A debug information format.  The predecessor to DWARF 2 and
 	DWARF 3, which are still supported.
 
 Support for the HP aCC compiler on HP-UX/PA-RISC
@@ -7127,7 +7129,7 @@ The following commands are presently only implemented for native GNU/Linux:
 
 checkpoint			Save a snapshot of the program state.
 
-restart	<n>			Return the program state to a 
+restart	<n>			Return the program state to a
 				previously saved state.
 
 info checkpoints		List currently saved checkpoints.
@@ -7272,8 +7274,8 @@ continued, we're looking forward to our first translation.
 
 * Ada
 
-Initial support for debugging programs compiled with the GNAT 
-implementation of the Ada programming language has been integrated 
+Initial support for debugging programs compiled with the GNAT
+implementation of the Ada programming language has been integrated
 into GDB.  In this release, support is limited to expression evaluation.
 
 * New native configurations
@@ -7740,7 +7742,7 @@ Fujitsu SPARClite 			sparclite-fujitsu-none  or  sparclite
 
 * REMOVED configurations and files
 
-V850EA ISA				
+V850EA ISA
 Motorola Delta 88000 running Sys V		m88k-motorola-sysv  or  delta88
 IBM AIX PS/2					i[3456]86-*-aix
 i386 running Mach 3.0				i[3456]86-*-mach3*
@@ -7775,7 +7777,7 @@ shared libs like mad''.
 
 * ``gdbserver'' now supports multi-threaded applications on some targets
 
-Support for debugging multi-threaded applications which use  
+Support for debugging multi-threaded applications which use
 the GNU/Linux LinuxThreads package has been added for
 arm*-*-linux*-gnu*, i[3456]86-*-linux*-gnu*, mips*-*-linux*-gnu*,
 powerpc*-*-linux*-gnu*, and sh*-*-linux*-gnu*.
@@ -7890,11 +7892,11 @@ gdb/439: gdb/291: On some ELF object files, gdb was reporting:
 dwarf2read.c:1072: gdb-internal-error: sect_index_text not initialize
 Fix, by Fred Fish, imported from mainline.
 
-Dwarf2 .debug_frame & .eh_frame handler improved in many ways. 
+Dwarf2 .debug_frame & .eh_frame handler improved in many ways.
 Surprisingly enough, it works now.
 By Michal Ludvig, imported from mainline.
 
-i386 hardware watchpoint support: 
+i386 hardware watchpoint support:
 avoid misses on second run for some targets.
 By Pierre Muller, imported from mainline.
 
@@ -7918,18 +7920,18 @@ hosts.  Argument is core file name (defaults to core.<pid>).
 
 * New command line option
 
-GDB now accepts --pid or -p followed by a process id.  
+GDB now accepts --pid or -p followed by a process id.
 
 * Change in command line behavior -- corefiles vs. process ids.
 
-There is a subtle behavior in the way in which GDB handles 
+There is a subtle behavior in the way in which GDB handles
 command line arguments.  The first non-flag argument is always
 a program to debug, but the second non-flag argument may either
 be a corefile or a process id.  Previously, GDB would attempt to
 open the second argument as a corefile, and if that failed, would
 issue a superfluous error message and then attempt to attach it as
-a process.  Now, if the second argument begins with a non-digit, 
-it will be treated as a corefile.  If it begins with a digit, 
+a process.  Now, if the second argument begins with a non-digit,
+it will be treated as a corefile.  If it begins with a digit,
 GDB will attempt to attach it as a process, and if no such process
 is found, will then attempt to open it as a corefile.
 
@@ -7989,7 +7991,7 @@ for the inferior from gdb's command line.
 
 There is a new `operate-and-get-next' function bound to `C-o'.
 
-*** Changes in GDB 5.1.1 
+*** Changes in GDB 5.1.1
 
 Fix compile problem on DJGPP.
 
@@ -8021,7 +8023,7 @@ UltraSparc running GNU/Linux			sparc64-*-linux*
 
 * OBSOLETE configurations and files
 
-x86 FreeBSD before 2.2				i[3456]86*-freebsd{1,2.[01]}*, 
+x86 FreeBSD before 2.2				i[3456]86*-freebsd{1,2.[01]}*,
 Harris/CXUX m88k				m88*-harris-cxux*
 Most ns32k hosts and targets			ns32k-*-mach3* ns32k-umax-*
 						ns32k-utek-sysv* ns32k-utek-*
@@ -8902,7 +8904,7 @@ There is a new hardware breakpoint for the watch command for sparclite
 targets.  See gdb/sparclite/hw_breakpoint.note.
 
 Hardware watchpoints are also now supported under GNU/Linux.
- 
+
 * Annotations
 
 Annotations have been added.  These are for use with graphical interfaces,
@@ -8983,7 +8985,7 @@ for details).
 
 * Improvements in C++ mangling/demangling.
 
-This release has much better g++ debugging, specifically in name 
+This release has much better g++ debugging, specifically in name
 mangling/demangling, virtual function calls, print virtual table,
 call methods, ...etc.
 
@@ -9045,7 +9047,7 @@ Z8000 simulator		  		z8k-zilog-none 	  or z8ksim
 IDT MIPS board over serial line		mips-idt-ecoff
 
 Cross-debugging to GO32 targets is supported.  It requires a custom
-version of the i386-stub.c module which is integrated with the 
+version of the i386-stub.c module which is integrated with the
 GO32 memory extender.
 
  * New remote protocols
@@ -9666,7 +9668,7 @@ encapulation, but the details have not been worked out yet.
  *  Improved configuration
 
 Only one copy of `configure' exists now, and it is not self-modifying.
-Porting BFD is simpler.  
+Porting BFD is simpler.
 
  *  Stepping improved
 
@@ -9768,7 +9770,7 @@ stub on the target system.
 
 New CPUs supported include the AMD 29000 and Intel 960.
 
-GDB now reads object files and symbol tables via a ``binary file'' 
+GDB now reads object files and symbol tables via a ``binary file''
 library, which allows a single copy of GDB to debug programs of multiple
 object file types such as a.out and coff.
 
@@ -9794,27 +9796,27 @@ confirm on/off:  Enables warning questions for operations that are
 		 hard to recover from, e.g. rerunning the program while
 		 it is already running.  Default is ON.
 
-editing on/off:  Enables EMACS style command line editing 
-                 of input.  Previous lines can be recalled with 
+editing on/off:  Enables EMACS style command line editing
+                 of input.  Previous lines can be recalled with
 		 control-P, the current line can be edited with control-B,
 		 you can search for commands with control-R, etc.
 		 Default is ON.
 
-history filename NAME:  NAME is where the gdb command history 
+history filename NAME:  NAME is where the gdb command history
 			will be stored.  The default is .gdb_history,
 			or the value of the environment variable
 			GDBHISTFILE.
 
-history size N:  The size, in commands, of the command history.  The 
+history size N:  The size, in commands, of the command history.  The
 		 default is 256, or the value of the environment variable
 		 HISTSIZE.
 
 history save on/off: If this value is set to ON, the history file will
-		      be saved after exiting gdb.  If set to OFF, the 
+		      be saved after exiting gdb.  If set to OFF, the
 		      file will not be saved.  The default is OFF.
 
-history expansion on/off: If this value is set to ON, then csh-like 
-			  history expansion will be performed  on 
+history expansion on/off: If this value is set to ON, then csh-like
+			  history expansion will be performed  on
 			  command line input.  The default is OFF.
 
 radix N:  Sets the default radix for input and output.  It can be set
@@ -9839,7 +9841,7 @@ print address on/off:  Print memory addresses in various command displays,
 		      more ``symbolic'' if you turn this off; it looks more
 		      ``machine level'' with it on.  Default is ON.
 
-print array on/off:  Prettyprint arrays.  New convenient format!  Default 
+print array on/off:  Prettyprint arrays.  New convenient format!  Default
                     is OFF.
 
 print demangle on/off:   Print C++ symbols in "source" form if on,
@@ -9870,7 +9872,7 @@ from dynamically linked programs), gdb reads the symbols from each
 shared library when you type the ``sharedlibrary'' command.
 It can be abbreviated ``share''.
 
-sharedlibrary REGEXP:  Load shared object library symbols for files 
+sharedlibrary REGEXP:  Load shared object library symbols for files
                        matching a unix regular expression.  No argument
 		       indicates to load symbols for all shared libraries.
 
@@ -9938,7 +9940,7 @@ find your source file in the current directory, type "dir .".
 For normal use, type ``./configure host''.  See README or gdb.texinfo
 for more details.
 
-GDB now handles cross debugging.  If you are remotely debugging between 
+GDB now handles cross debugging.  If you are remotely debugging between
 two different machines, type ``./configure host -target=targ''.
 Host is the machine where GDB will run; targ is the machine
 where the program that you are debugging will run.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 676143be416..0ec1b92d7c3 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -27080,6 +27080,26 @@ Program received signal SIGSEGV, Segmentation fault
 Guarded Control Stack error.
 @end smallexample
 
+@subsubsection AArch64 Floating Point Mode Register
+@cindex Floating Point Mode Register, AArch64
+@cindex FPMR, AArch64
+
+When @value{GDBN} is debugging the AArch64 architecture and the Floating Point
+Mode Register (FPMR) is available, then @value{GDBN} will make the @code{fpmr}
+available. This register determines the behaviour of FP8 instructions.
+
+To aid debugging, @value{GDBN} interprets the mode or value of each field in
+@code{fpmr}.
+
+@smallexample
+p $fpmr
+$1 = [ F8S1=E5M2 F8S2=E5M2 F8D=E5M2 OSM=Inf OSC=Inf/NaN LSCALE=0 NSCALE=0 LSCALE2=0 ]
+@end smallexample
+
+For more information about FPMR, please refer to the official
+@uref{https://developer.arm.com/documentation/ddi0601/latest,ignored,
+architecture registers documentation}.
+
 @node x86
 @subsection x86
 
@@ -49770,6 +49790,57 @@ documentation} in the Linux kernel.
 Extra registers are allowed in these features, but they will not affect
 @value{GDBN}.
 
+@subsubsection AArch64 FPMR feature
+
+The @samp{org.gnu.gdb.aarch64.fpmr} optional feature was introduced so
+@value{GDBN} could detect support for the Floating Point Mode Register
+extension.  If present, this feature must have the following register:
+
+@itemize @minus
+@item
+@samp{fpmr}, the tag control register.  It is represented as if it were a 64-bit
+register with a custom flags type.
+@end itemize
+
+The custom flags type allows @value{GDBN} to print a human-friendly
+representation of the contents of @code{fpmr} should contain:
+
+@itemize @minus
+
+@item
+@code{F8S1}, which is either @code{E5M2} or @code{E4M3}
+
+@item
+@code{F8S2}, which is either @code{E5M2} or @code{E4M3}
+
+@item
+@code{F8D}, which is either @code{E5M2} or @code{E4M3}
+
+@item
+@code{OSM}, which is either @code{Inf} or @code{MaxNormal}
+
+@item
+@code{OSC}, which is either @code{Inf/NaN} or @code{MaxNormal}
+
+@item
+@code{LSCALE}, which is a 7-bit unsigned value
+
+@item
+@code{NSCALE}, which is actually an 8-bit signed value but represented as an
+8-bit unsigned value
+
+@item
+@code{LSCALE2}, which is a 6-bit unsigned value
+
+@end itemize
+
+Extra registers are allowed in this feature, but they will not affect
+@value{GDBN}.
+
+For more information about FPMR, please refer to the official
+@uref{https://developer.arm.com/documentation/ddi0601/latest,ignored,
+architecture registers documentation}.
+
 @node Alpha Features
 @subsection Alpha Features
 @cindex target descriptions, Alpha Features
-- 
2.45.2