From 0fae69387993c77db3d99d1566c13995bfd9a125 Mon Sep 17 00:00:00 2001
From: Zijing Zhang <zijing.zhang@proton.me>
Date: Mon, 26 Jan 2026 20:29:54 +0800
Subject: [PATCH 1/2] docs(report): new section Including Scala Source Location

---
 .../Other language features/report.rst        | 22 ++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/source/SpinalHDL/Other language features/report.rst b/source/SpinalHDL/Other language features/report.rst
index ad833f0e72..2e8e648618 100644
--- a/source/SpinalHDL/Other language features/report.rst	
+++ b/source/SpinalHDL/Other language features/report.rst	
@@ -42,6 +42,27 @@ will result in:
 
     $display("NOTE miaou %t", $time);
 
+Including Scala Source Location
+-------------------------------
+
+After 1.13.0, You can optionally include the Scala call-site location (file and line) in the report output, which allows most IDEs to jump to the source when clicking the log line.
+
+There are two ways to enable it:
+
+.. code-block:: scala
+
+    // Per-call
+    report("HELLO", includeSourceLocation = true)
+
+    // Globally (for all `report(...)` calls in this elaboration)
+    SpinalConfig(reportIncludeSourceLocation = true).generateVerilog(new TopLevel)
+
+Example generated output (Verilog):
+
+.. code-block:: verilog
+
+    $display("path/to/MyTopLevel.scala:123: NOTE HELLO");
+
 **Automatic Handling of Scala Primitive Types (SpinalHDL ^1.12.2)**
 
 You can embed Scala primitive types (e.g., `Int`, `Boolean`, `Float`, `BigInt`, `BigDecimal`, `Char`, `Byte`, `Short`, `Long`) within `L""` interpolated strings without explicit `.toString()` calls.
@@ -106,4 +127,3 @@ This will produce a compact, readable output like:
 .. code-block:: text
 
     PacketHeader(packetLength=0x0c, packetType=0x1, payload=DataPayload(value=0x5678, checksum=0x78))
-

From b73c3e057777441f1fb00b447ebf00aa404eb134 Mon Sep 17 00:00:00 2001
From: Zijing Zhang <zijing.zhang@proton.me>
Date: Mon, 26 Jan 2026 20:58:01 +0800
Subject: [PATCH 2/2] docs(report): explain that users can override the report
 format

---
 .../Other language features/report.rst        | 21 ++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/source/SpinalHDL/Other language features/report.rst b/source/SpinalHDL/Other language features/report.rst
index 2e8e648618..bd6507325a 100644
--- a/source/SpinalHDL/Other language features/report.rst	
+++ b/source/SpinalHDL/Other language features/report.rst	
@@ -45,7 +45,7 @@ will result in:
 Including Scala Source Location
 -------------------------------
 
-After 1.13.0, You can optionally include the Scala call-site location (file and line) in the report output, which allows most IDEs to jump to the source when clicking the log line.
+After 1.13.0, you can optionally include the Scala call-site location (file and line) in the report output, which allows most IDEs to jump to the source when clicking the log line.
 
 There are two ways to enable it:
 
@@ -59,6 +59,25 @@ There are two ways to enable it:
 
 Example generated output (Verilog):
 
+.. code-block:: verilog
+
+    $display("NOTE(path/to/MyTopLevel.scala:123) HELLO");
+
+You can customize the location prefix format globally using `SpinalConfig.reportSourceLocationFormat`, with the following placeholders:
+
+- `$SEVERITY` (NOTE/WARNING/ERROR/FAILURE)
+- `$FILE` (Scala file path)
+- `$LINE`
+
+Example (IDE-friendly clickable output):
+
+.. code-block:: scala
+
+    SpinalConfig(
+      reportIncludeSourceLocation = true,
+      reportSourceLocationFormat = "$FILE:$LINE: $SEVERITY "
+    ).generateVerilog(new TopLevel)
+
 .. code-block:: verilog
 
     $display("path/to/MyTopLevel.scala:123: NOTE HELLO");