Merge branch 'riscv:main' into issue985

LICENSE

@@ -1,3 +1,10 @@
+All files in this repo may be used under the CC-BY-4.0 license, included below.
+Some files may also be used under a different license. Where that is the case,
+they contain a comment near the top of the file specifying the other license.
+Use under any other license is prohibited.
+
+CC-BY-4.0 license:
+
 Attribution 4.0 International
 
 =======================================================================

build/Makefile

@@ -69,15 +69,10 @@ build-registers:	$(REGISTERS_ADOC)
 %.adoc:	../xml/%.xml $(REGISTERS_PY)
 	../registers.py --adoc $@ --adoc-definitions $(patsubst %.adoc,%-def.adoc,$@) $<
 
-debug_defines: debug_defines.h debug_defines.c $(patsubst %,../xml/%,$(REGISTERS_ADOC:.adoc=.xml)) ../registers.py
-	../registers.py $@ --cgetters $(filter %.xml, $^)
-
-debug_defines.%:
-	echo "/*" > $@
-	echo " * This file is auto-generated by running 'make debug_defines' in" >> $@
-	echo " * https://github.com/riscv/riscv-debug-spec/ (`git describe --always --dirty --exclude '*'`)" >> $@
-	echo " */" >> $@
-	echo >> $@
+debug_defines: $(patsubst %,../xml/%,$(REGISTERS_ADOC:.adoc=.xml)) ../registers.py
+	../registers.py $@ --cgetters $(filter %.xml, $^) \
+		--create "This file was auto-generated by running 'make debug_defines' in \
+https://github.com/riscv/riscv-debug-spec/ (`git describe --always --dirty --exclude '*'`)"
 
 %.scala: ../xml/%.xml ../registers.py
 	../registers.py --chisel $(basename $@).scala $< > /dev/null

debug_module.adoc

@@ -146,7 +146,7 @@ simultaneously. The state of the hart array mask register is not
 affected by setting or clearing {dmcontrol-hasel}.
 
 Execution of Abstract Commands ignores this mechanism and only applies
-to the hart selected by {dmstatus-hartsello}.
+to the hart selected by {hartsel}.
 
 === Hart DM States
 
@@ -365,7 +365,7 @@ of {dm-data0}) or hart (e.g. contents of a register modified by a Program Buffe
 
 Before starting an abstract command, a debugger must ensure that {dmcontrol-haltreq}, {dmcontrol-resumereq}, and {dmcontrol-ackhavereset} are all 0.
 
-While an abstract command is executing ({abstractcs-busy} in {dm-abstractcs} is high), a debugger must not change `hartset`, and must not write 1 to {dmcontrol-haltreq}, {dmcontrol-resumereq}, {dmcontrol-ackhavereset}, {dmcontrol-setresethaltreq}, or {dmcontrol-clrresethaltreq}.
+While an abstract command is executing ({abstractcs-busy} in {dm-abstractcs} is high), a debugger must not change {hartsel}, and must not write 1 to {dmcontrol-haltreq}, {dmcontrol-resumereq}, {dmcontrol-ackhavereset}, {dmcontrol-setresethaltreq}, or {dmcontrol-clrresethaltreq}.
 
 If an abstract command does not complete in the expected time and
 appears to be hung, the debugger can try to reset the hart (using {dmcontrol-hartreset} or {dmcontrol-ndmreset}).

introduction.adoc

@@ -40,7 +40,8 @@ functionality.
 
 *DTM*:: Debug Transport Module (see <<dtm>>).
 
-*DXLEN*:: Debug XLEN, which is the widest XLEN a hart supports, ignoring the current value of in .
+*DXLEN*:: Debug XLEN, which is the widest XLEN a hart supports, ignoring the
+current value of `mxl` in `misa`.
 
 *essential feature*:: An essential feature must be present in order for debug to work correctly.
 

registers.py

@@ -15,7 +15,7 @@
 
 class Registers( object ):
     def __init__( self, name, label, prefix, description, skip_index,
-            skip_access, skip_reset, depth ):
+            skip_access, skip_reset, depth, licenses ):
         self.name = name
         self.label = label
         self.prefix = prefix or ""
@@ -24,6 +24,7 @@ def __init__( self, name, label, prefix, description, skip_index,
         self.skip_access = skip_access
         self.skip_reset = skip_reset
         self.depth = depth
+        self.licenses = licenses
         self.registers = []
 
     def add_register( self, register ):
@@ -307,7 +308,13 @@ def parse_bits( field ):
     else:
         assert False, text
 
+def parse_spdx( path ):
+    with open( path ) as f:
+        data = f.read(4096)
+        return set(re.findall(r"SPDX-License-Identifier:\s*(.+?)\s*(?:-->.*)?$", data, re.MULTILINE))
+
 def parse_xml( path ):
+    licenses = parse_spdx(path)
     e = xml.etree.ElementTree.parse( path ).getroot()
     if e.text:
         description = e.text.strip()
@@ -318,7 +325,8 @@ def parse_xml( path ):
             int( e.get( 'skip_index', 0 ) ),
             int( e.get( 'skip_access', 0 ) ),
             int( e.get( 'skip_reset', 0 ) ),
-            int( e.get( 'depth', 1 )))
+            int( e.get( 'depth', 1 )),
+            licenses)
     for r in e.findall( 'register' ):
         name = r.get( 'name' )
         short = r.get( 'short' )
@@ -480,6 +488,10 @@ def c_max(args):
         return c_max(args)
     raise Exception("Unsupported sympy object %r of type %r" % (expression, type(expression)))
 
+def write_c_licenses( fd, licenses ):
+    for license in licenses:
+        fd.write(f"/* SPDX-License-Identifier: {license} */\n")
+
 def write_cheader( fd, registers ):
     definitions = []
     for r in registers.registers:
@@ -1017,7 +1029,7 @@ def write_adoc( fd, registers ):
         fd.write("\n")
 
 def write_adoc_index( fd, registers ):
-    fd.write(remove_indent(registers.description))
+    fd.write(remove_indent(registers.description) + "\n")
 
     columns = [
         ("Address", "1"),
@@ -1066,14 +1078,26 @@ def main():
     parser.add_argument( '--chisel',
             help='Write Scala Classes to the named file.' )
     parser.add_argument( '--cgetters', dest='xml_paths', nargs='+')
+    parser.add_argument( '--create',
+            help='Line included in the output described how the file was created.' )
     parsed = parser.parse_args()
 
     if (parsed.xml_paths):
-        fd_h = open( parsed.path + ".h", "a" )
+        registers_list = [parse_xml( xml_path ) for xml_path in parsed.xml_paths]
+        license_lists = [registers.licenses for registers in registers_list]
+        # Assert every license list is the same
+        assert all(license_lists[0] == license_list for license_list in license_lists), \
+                "All XML files must have the same SPDX-License-Identifier"
+        fd_h = open( parsed.path + ".h", "w" )
+        write_c_licenses( fd_h, license_lists[0] )
+        if (parsed.create):
+            fd_h.write(f"/* {parsed.create} */\n\n")
         fd_h.write("#ifndef DEBUG_DEFINES_H\n#define DEBUG_DEFINES_H\n")
-        fd_c = open( parsed.path + ".c", "a" )
+        fd_c = open( parsed.path + ".c", "w" )
+        write_c_licenses( fd_c, license_lists[0] )
+        if (parsed.create):
+            fd_c.write(f"/* {parsed.create} */\n\n")
         fd_c.write(f'#include "{parsed.path}.h"\n#include <stddef.h>\n#include <assert.h>\n')
-        registers_list = [parse_xml( xml_path ) for xml_path in parsed.xml_paths]
         for registers in registers_list:
             write_cheader( fd_h, registers )
         print_cgetters(registers_list, fd_h, fd_c)
@@ -1084,7 +1108,9 @@ def main():
     if parsed.definitions:
         write_definitions( open( parsed.definitions, "w" ), registers )
     if parsed.cheader:
-        write_cheader( open( parsed.cheader, "w" ), registers )
+        with open( parsed.cheader, "w" ) as fd:
+            write_c_licenses( fd, registers.licenses )
+            write_cheader( fd, registers )
     if parsed.chisel:
         write_chisel( open( parsed.chisel, "w" ), registers )
     if not registers.skip_index and not parsed.adoc:

xml/abstract_commands.xml

@@ -1,3 +1,13 @@
+<!-- SPDX-License-Identifier: BSD-2-Clause OR CC-BY-4.0 -->
+
+<!--
+This file is dual-licensed. You may choose to use this file under the terms of
+either of the above licenses.
+
+Note: This dual licensing does not apply to other files that may be part of the
+same project unless stated otherwise.
+-->
+
 <registers name="Abstract Commands" skip_index="1" skip_access="1"
         skip_reset="1" prefix="AC_" depth="2">
     <register name="Access Register">

xml/core_registers.xml

@@ -1,3 +1,13 @@
+<!-- SPDX-License-Identifier: BSD-2-Clause OR CC-BY-4.0 -->
+
+<!--
+This file is dual-licensed. You may choose to use this file under the terms of
+either of the above licenses.
+
+Note: This dual licensing does not apply to other files that may be part of the
+same project unless stated otherwise.
+-->
+
 <registers name="Core Debug Registers" prefix="CSR_">
     These registers are only accessible from Debug Mode.
 

xml/dm_registers.xml

@@ -1,3 +1,13 @@
+<!-- SPDX-License-Identifier: BSD-2-Clause OR CC-BY-4.0 -->
+
+<!--
+This file is dual-licensed. You may choose to use this file under the terms of
+either of the above licenses.
+
+Note: This dual licensing does not apply to other files that may be part of the
+same project unless stated otherwise.
+-->
+
 <registers name="Debug Module Debug Bus Registers" prefix="DM_">
 
     <!-- =============== halt/reset/select hart  =============== -->

xml/hwbp_registers.xml

@@ -1,3 +1,13 @@
+<!-- SPDX-License-Identifier: BSD-2-Clause OR CC-BY-4.0 -->
+
+<!--
+This file is dual-licensed. You may choose to use this file under the terms of
+either of the above licenses.
+
+Note: This dual licensing does not apply to other files that may be part of the
+same project unless stated otherwise.
+-->
+
 <registers name="Trigger Module Registers" prefix="CSR_" label="trigger">
     The Trigger Module registers, except {csr-mscontext}, {csr-scontext}, and {csr-hcontext}, are only accessible in machine
     and Debug Mode to prevent untrusted user code from causing entry into Debug
@@ -719,7 +729,7 @@
 
         [NOTE]
         ====
-        {mcontrol6-uncertain} and {mcontrol6-uncertain}en exist to
+        {mcontrol6-uncertain} and {mcontrol6-uncertainen} exist to
         accommodate systems where not every memory access is fully observed by
         the Trigger Module. Possible examples include data values in far AMOs,
         and the address/data/size of accesses by instructions that perform

xml/jtag_registers.xml

@@ -1,3 +1,13 @@
+<!-- SPDX-License-Identifier: BSD-2-Clause OR CC-BY-4.0 -->
+
+<!--
+This file is dual-licensed. You may choose to use this file under the terms of
+either of the above licenses.
+
+Note: This dual licensing does not apply to other files that may be part of the
+same project unless stated otherwise.
+-->
+
 <registers name="JTAG DTM TAP Registers" label="table:jtag_registers" prefix="DTM_">
     <!-- JTAG standard registers, everything starting with 0 -->
     <register name="BYPASS" address="0x00" sdesc="JTAG recommends this encoding"/>

xml/sample_registers.xml

@@ -1,3 +1,13 @@
+<!-- SPDX-License-Identifier: BSD-2-Clause OR CC-BY-4.0 -->
+
+<!--
+This file is dual-licensed. You may choose to use this file under the terms of
+either of the above licenses.
+
+Note: This dual licensing does not apply to other files that may be part of the
+same project unless stated otherwise.
+-->
+
 <registers name="Sample Registers" skip_index="1" depth="2">
     Description of what this register is about.
     <register name="Long Name" short="shortname" address="0x123">
@@ -7,4 +17,3 @@
         </field>
     </register>
 </registers>
-

xml/sw_registers.xml

@@ -1,3 +1,13 @@
+<!-- SPDX-License-Identifier: BSD-2-Clause OR CC-BY-4.0 -->
+
+<!--
+This file is dual-licensed. You may choose to use this file under the terms of
+either of the above licenses.
+
+Note: This dual licensing does not apply to other files that may be part of the
+same project unless stated otherwise.
+-->
+
 <registers name="Virtual Core Debug Registers" prefix="VIRT_">
     A virtual register is one that doesn't exist directly in the hardware, but
     that the debugger exposes as if it does. Debug software should implement