Document __PASS__

Document __PASS__, but discourage users from using it.

Signed-off-by: H. Peter Anvin <hpa@zytor.com>

2 files changed, 16 insertions, 0 deletions

diff --git a/doc/changes.src b/doc/changes.src
index 4ce80d1f..3cd0b221 100644
--- a/doc/changes.src
+++ b/doc/changes.src
@@ -35,6 +35,9 @@ since 2007.
 \b New \c{%unmacro} directive to undeclare a multi-line macro.
   See \k{unmacro}.
 
+\b Builtin macro \c{__PASS__} which expands to the current assembly pass.
+  See \k{pass_macro}.
+
 \b \c{__utf16__} and \c{__utf32__} operators to generate UTF-16 and UTF-32
   strings.  See \k{unicode}.
 
diff --git a/doc/nasmdoc.src b/doc/nasmdoc.src
index a27a7837..81062daf 100644
--- a/doc/nasmdoc.src
+++ b/doc/nasmdoc.src
@@ -3670,6 +3670,19 @@ For example, if the \c{altreg} package is included (see
 \k{pkg_altreg}), then the macro \c{__USE_ALTREG__} is defined.
 
 
+\S{pass_macro} \i\c{__PASS__}: Assembly Pass
+
+The macro \c{__PASS__} is defined to be \c{1} on preparatory passes,
+and \c{2} on the final pass.  In preprocess-only mode, it is set to
+\c{2} (there being only the final pass); when running only to generate
+dependencies (due to the \c{-M} or \c{-MG} option, see \k{opt-M}) it
+is set to \c{0}.
+
+\e{Avoid using this macro if at all possible.  It is tremendously easy
+to generate very strange errors by misusing it, and the semantics may
+change in future versions of NASM.}
+
+
 \S{struc} \i\c{STRUC} and \i\c{ENDSTRUC}: \i{Declaring Structure} Data Types
 
 The core of NASM contains no intrinsic means of defining data