Add %note directive to add a note in the list file

This differs from a plain old comment in the following ways:

1. It is optionally macro-expanded;
2. It has a dash prefix;
3. It can be used inside .nolist macros.

Suggested-by: <[email protected]>
Resolves: https://bugzilla.nasm.us/show_bug.cgi?id=3392915
Signed-off-by: H. Peter Anvin <[email protected]>

Author: H. Peter Anvin

asm/error.c

@@ -1,6 +1,6 @@
 /* ----------------------------------------------------------------------- *
  *
- *   Copyright 1996-2019 The NASM Authors - All Rights Reserved
+ *   Copyright 1996-2024 The NASM Authors - All Rights Reserved
  *   See the file AUTHORS included with the NASM distribution for
  *   the specific copyright holders.
  *
@@ -70,6 +70,7 @@ _type nasm_ ## _name (const char *fmt, ...)				\
 }
 
 nasm_err_helpers(void,       listmsg,  ERR_LISTMSG)
+nasm_err_helpers(void,       note,     ERR_NOTE)
 nasm_err_helpers(void,       debug,    ERR_DEBUG)
 nasm_err_helpers(void,       info,     ERR_INFO)
 nasm_err_helpers(void,       nonfatal, ERR_NONFATAL)

asm/listing.c

@@ -71,6 +71,20 @@ static int listlevel, listlevel_e;
 
 static FILE *listfp;
 
+static inline char err_fill_char(errflags severity)
+{
+    severity &= ERR_MASK;
+
+    if (severity < ERR_NOTE)
+        return ' ';
+    else if (severity < ERR_WARNING)
+        return '-';
+    else if (severity < ERR_CRITICAL)
+        return '*';
+    else
+        return 'X';
+}
+
 static void list_emit(void)
 {
     int i;
@@ -100,12 +114,11 @@ static void list_emit(void)
     }
 
     if (list_errors) {
-        static const char fillchars[] = " --***XX";
-        char fillchar;
-
         strlist_for_each(e, list_errors) {
+            char fillchar;
+
             fprintf(listfp, "%6"PRId32"          ", listlineno);
-            fillchar = fillchars[e->pvt.u & ERR_MASK];
+            fillchar = err_fill_char(e->pvt.u);
             for (i = 0; i < LIST_HEXBIT; i++)
                 putc(fillchar, listfp);
 

asm/nasm.c

@@ -1852,11 +1852,11 @@ static bool skip_this_pass(errflags severity)
         return false;
 
     /*
-     * ERR_LISTMSG messages are always skipped; the list file
-     * receives them anyway as this function is not consulted
-     * for sending to the list file.
+     * ERR_LISTMSG and ERR_NOTE messages are always skipped; the list
+     * file receives them anyway as this function is not consulted for
+     * sending to the list file.
      */
-    if (type == ERR_LISTMSG)
+    if (type <= ERR_NOTE)
         return true;
 
     /*
@@ -1920,10 +1920,31 @@ static errflags true_error_type(errflags severity)
 /*
  * The various error type prefixes
  */
-static const char * const error_pfx_table[ERR_MASK+1] = {
-    ";;; ", "debug: ", "info: ", "warning: ",
-        "error: ", "fatal: ", "critical: ", "panic: "
-};
+static inline const char *error_pfx(errflags severity)
+{
+    switch (severity & ERR_MASK) {
+    case ERR_LISTMSG:
+        return ";;; ";
+    case ERR_NOTE:
+        return "note: ";
+    case ERR_DEBUG:
+        return "debug: ";
+    case ERR_INFO:
+        return "info: ";
+    case ERR_WARNING:
+        return "warning: ";
+    case ERR_NONFATAL:
+        return "error: ";
+    case ERR_FATAL:
+        return "fatal: ";
+    case ERR_CRITICAL:
+        return "critical: ";
+    case ERR_PANIC:
+        return "panic: ";
+    default:
+        return "internal error: ";
+    }
+}
 static const char no_file_name[] = "nasm"; /* What to print if no file name */
 
 /*
@@ -1996,7 +2017,7 @@ fatal_func nasm_verror_critical(errflags severity, const char *fmt, va_list args
     if (!where.filename)
         where.filename = no_file_name;
 
-    fputs(error_pfx_table[severity], error_file);
+    fputs(error_pfx(severity), error_file);
     fputs(where.filename, error_file);
     if (where.lineno) {
         fprintf(error_file, "%s%"PRId32"%s",
@@ -2138,7 +2159,7 @@ static void nasm_issue_error(struct nasm_errtext *et)
     if (severity & ERR_NO_SEVERITY)
         pfx = "";
     else
-        pfx = error_pfx_table[true_type];
+        pfx = error_pfx(true_type);
 
     *warnsuf = 0;
     if ((severity & (ERR_MASK|ERR_HERE|ERR_PP_LISTMACRO)) == ERR_WARNING) {

asm/pptok.dat

@@ -1,6 +1,6 @@
 ## --------------------------------------------------------------------------
-##   
-##   Copyright 1996-2019 The NASM Authors - All Rights Reserved
+##
+##   Copyright 1996-2024 The NASM Authors - All Rights Reserved
 ##   See the file AUTHORS included with the NASM distribution for
 ##   the specific copyright holders.
 ##
@@ -14,7 +14,7 @@
 ##     copyright notice, this list of conditions and the following
 ##     disclaimer in the documentation and/or other materials provided
 ##     with the distribution.
-##     
+##
 ##     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
 ##     CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
 ##     INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
@@ -91,6 +91,7 @@
 %line
 %local
 %null
+%note
 %pop
 %pragma
 %push

asm/preproc.c

@@ -1,6 +1,6 @@
 /* ----------------------------------------------------------------------- *
  *
- *   Copyright 1996-2023 The NASM Authors - All Rights Reserved
+ *   Copyright 1996-2024 The NASM Authors - All Rights Reserved
  *   See the file AUTHORS included with the NASM distribution for
  *   the specific copyright holders.
  *
@@ -4437,6 +4437,9 @@ static int do_directive(Token *tline, Token **output)
          */
         severity = ERR_WARNING|WARN_USER|ERR_PASS2;
         goto issue_error;
+    case PP_NOTE:
+        severity = ERR_NOTE;
+        goto issue_error;
 
 issue_error:
     {

doc/preproc.src

@@ -2251,7 +2251,8 @@ the construction of an appropriately sized ENTER instruction
 as shown in the example.
 
 
-\H{pperror} Reporting \i{User-Defined Errors}: \i\c{%error}, \i\c{%warning}, \i\c{%fatal}
+\H{pperror} Reporting \i{User-generated Diagnostics}: \i\c{%error},
+\i\c{%warning}, \i\c{%fatal}, \i\c{%note}
 
 The preprocessor directive \c{%error} will cause NASM to report an
 error if it occurs in assembled code. So if other users are going to
@@ -2282,6 +2283,9 @@ Similarly, \c{%warning} issues a warning, but allows assembly to continue:
 \c     %define F1
 \c %endif
 
+User-defined error messages can be suppressed with the \c{-w-user}
+option, and promoted to errors with \c{-w+error=user}.
+
 \c{%error} and \c{%warning} are issued only on the final assembly
 pass.  This makes them safe to use in conjunction with tests that
 depend on symbol values.
@@ -2291,10 +2295,13 @@ is useful when there is no point in continuing the assembly further,
 and doing so is likely just going to cause a spew of confusing error
 messages.
 
-It is optional for the message string after \c{%error}, \c{%warning}
-or \c{%fatal} to be quoted.  If it is \e{not}, then single-line macros
-are expanded in it, which can be used to display more information to
-the user.  For example:
+\c{%note} adds an output line to the list file; it does not output
+anything on the console or error file.
+
+It is optional for the message string after \c{%error}, \c{%warning},
+\c{%fatal}, or \c{%note} to be quoted.  If it is \e{not}, then
+single-line macros are expanded in it, which can be used to display
+more information to the user.  For example:
 
 \c %if foo > 64
 \c     %assign foo_over foo-64
@@ -2459,7 +2466,3 @@ compatibility aliases)
 
 In NASM 2.14 and earlier, only the single syntax \c{%clear} was
 supported, which is equivalent to \c{%clear global all}.
-
-
-
-

include/error.h

@@ -1,6 +1,6 @@
 /* ----------------------------------------------------------------------- *
  *
- *   Copyright 1996-2023 The NASM Authors - All Rights Reserved
+ *   Copyright 1996-2024 The NASM Authors - All Rights Reserved
  *   See the file AUTHORS included with the NASM distribution for
  *   the specific copyright holders.
  *
@@ -79,20 +79,21 @@ fatal_func vprintf_func(2) nasm_verror_critical(errflags severity, const char *f
  * These are the error severity codes which get passed as the first
  * argument to an efunc.
  */
-#define ERR_LISTMSG		0x00000000      /* for the listing file only */
-#define ERR_DEBUG		0x00000001	/* debugging message */
-#define ERR_INFO		0x00000002	/* information for the list file */
-#define ERR_WARNING		0x00000003	/* warn only: no further action */
-#define ERR_NONFATAL		0x00000004	/* terminate assembly after phase */
-#define ERR_FATAL		0x00000005	/* instantly fatal: exit with error */
-#define ERR_CRITICAL		0x00000006      /* fatal, but minimize code before exit */
-#define ERR_PANIC		0x00000007	/* internal error: panic instantly
+#define ERR_LISTMSG		0x00000000      /* for the listing file only (no prefix) */
+#define ERR_NOTE		0x00000001      /* for the listing file only (with prefix) */
+#define ERR_DEBUG		0x00000002	/* debugging message */
+#define ERR_INFO		0x00000003	/* information for the list file */
+#define ERR_WARNING		0x00000004	/* warn only: no further action */
+#define ERR_NONFATAL		0x00000008	/* terminate assembly after phase */
+#define ERR_FATAL		0x00000009	/* instantly fatal: exit with error */
+#define ERR_CRITICAL		0x0000000e      /* fatal, but minimize code before exit */
+#define ERR_PANIC		0x0000000f	/* internal error: panic instantly
 						 * and dump core for reference */
-#define ERR_MASK		0x00000007	/* mask off the above codes */
-#define ERR_UNDEAD		0x00000008      /* skip if we already have errors */
-#define ERR_NOFILE		0x00000010	/* don't give source file name/line */
-#define ERR_HERE		0x00000020      /* point to a specific source location */
-#define ERR_USAGE		0x00000040	/* print a usage message */
+#define ERR_MASK		0x0000000f	/* mask off the above codes */
+#define ERR_UNDEAD		0x00000010      /* skip if we already have errors */
+#define ERR_NOFILE		0x00000020	/* don't give source file name/line */
+#define ERR_HERE		0x00000040      /* point to a specific source location */
+#define ERR_USAGE		0x00000080	/* print a usage message */
 #define ERR_PASS2		0x00000100	/* ignore unless on pass_final */
 
 #define ERR_NO_SEVERITY		0x00000200	/* suppress printing severity */

nasmlib/errfile.c

@@ -1,4 +1,3 @@
 #include "compiler.h"
 
 FILE *error_file;
-