From: Sandra Loosemore <sloosemore@baylibre.com>
Date: Fri, 5 Dec 2025 17:07:21 +0000 (+0000)
Subject: doc, h8300: Clean up H8/300 option and attribute documentation [PR122243]
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6562d3364706eb907b8abafd48163db312bd07d8;p=thirdparty%2Fgcc.git

doc, h8300: Clean up H8/300 option and attribute documentation [PR122243]

Comparing the documentation in invoke.texi with hs8300.opt, I spotted
a few options in the latter that were missing documentation, and added
it.

I wanted to add a link to the "monitor" attribute
referenced in the existing docs for this option, but found that was
also missing, along with docs for the "OS_Task" attribute; so I fixed
those problems while I was at it.

gcc/ChangeLog
	PR other/122243
	* config/h8300/h8300.opt (mexr, mno-exr): Add FIXME re ambiguity
	for -mno-exr semantics.
	* doc/extend.texi (H8/300 Function Attributes): Document
	monitor and OS_Task attributes.
	* doc/invoke.texi (Option Summary) <H8/300 Options}: Add -msx,
	-ms2600, -mquickcall, -mslowbyte.  Combine -mexr and -mno-exr.
	(H8/300 Options): Likewise.  Add @opindex entries for options
	that have negative forms.
---

diff --git a/gcc/config/h8300/h8300.opt b/gcc/config/h8300/h8300.opt
index 65300755051..1f45cb6e5d8 100644
--- a/gcc/config/h8300/h8300.opt
+++ b/gcc/config/h8300/h8300.opt
@@ -61,6 +61,8 @@ malign-300
 Target RejectNegative Mask(ALIGN_300)
 Use H8/300 alignment rules.
 
+; FIXME: -mexr and -mno-exr should be merged or both marked RejectNegative.
+; As things stand now, -mno-exr is ambiguous.
 mexr
 Target Mask(EXR)
 Push extended registers on stack in monitor functions.
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 0536ca7ae93..22e6dd8f5a8 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -4824,6 +4824,18 @@ interrupt handler when this attribute is present.
 Use this attribute on the H8/300, H8/300H, and H8S to indicate that
 all registers except the stack pointer should be saved in the prologue
 regardless of whether they are used or not.
+
+@cindex @code{monitor} function attribute, H8/300
+@item monitor
+Use this attribute to indicate a monitor function.  It tells GCC
+to generate entry and exit sequences that disable interrupts during
+execution of the function.
+
+@cindex @code{OS_Task} function attribute, H8/300
+@item OS_Task
+Use this attribute to disable the normal register and stack save and
+restore sequences on function entry and exit.  The function epilogue
+generated by GCC includes only a return instruction.
 @end table
 
 @node IA-64 Function Attributes
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index b276db1673b..5e3015040c6 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -1108,7 +1108,8 @@ Objective-C and Objective-C++ Dialects}.
 -tno-android-cc  -tno-android-ld}
 
 @emph{H8/300 Options} (@ref{H8/300 Options})
-@gccoptlist{-mrelax  -mh  -ms  -mn  -mexr  -mno-exr  -mint32  -malign-300}
+@gccoptlist{-mrelax  -mh  -ms  -mn  -msx  -ms2600
+-mquickcall  -mslowbyte  -mexr  -mint32  -malign-300}
 
 @emph{HPPA Options} (@ref{HPPA Options})
 @gccoptlist{-march=@var{architecture-type}
@@ -28009,34 +28010,47 @@ linker option @option{-relax}.  @xref{H8/300,, @code{ld} and the H8/300,
 ld, Using ld}, for a fuller description.
 
 @opindex mh
+@opindex mno-h
 @item -mh
 Generate code for the H8/300H@.
 
 @opindex ms
+@opindex mno-s
 @item -ms
 Generate code for the H8S@.
 
 @opindex mn
+@opindex mno-n
 @item -mn
 Generate code for the H8S and H8/300H in the normal mode.  This switch
-must be used either with @option{-mh} or @option{-ms}.
+must be used with either @option{-mh} or @option{-ms}.
+
+@opindex msx
+@opindex mno-sx
+@item -msx
+Generate H8SX code.
 
 @opindex ms2600
+@opindex mno-s2600
 @item -ms2600
 Generate code for the H8S/2600.  This switch must be used with @option{-ms}.
 
-@opindex mexr
-@item -mexr
-Extended registers are stored on stack before execution of function
-with monitor attribute. Default option is @option{-mexr}.
-This option is valid only for H8S targets.
+@opindex mquickcall
+@opindex mno-quickcall
+@item -mquickcall
+Use registers for argument passing.
+
+@opindex mslowbyte
+@item -mslowbyte
+Consider access to byte-sized memory slow.
 
-@opindex mno-exr
 @opindex mexr
-@item -mno-exr
-Extended registers are not stored on stack before execution of function
-with monitor attribute. Default option is @option{-mno-exr}.
-This option is valid only for H8S targets.
+@opindex mno-exr
+@item -mexr
+@itemx -mno-exr
+Store extended registers on the stack before execution of functions
+with the @code{monitor} attribute (@pxref{H8/300 Function Attributes}).
+The default is @option{-mexr}.  This option is valid only for H8S targets.
 
 @opindex mint32
 @item -mint32