diff --git a/LICENSE b/LICENSE index 06c608dc..336a5941 100644 --- a/LICENSE +++ b/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 ======================================================================= diff --git a/build/Makefile b/build/Makefile index 2147a56f..65a24024 100644 --- a/build/Makefile +++ b/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 diff --git a/debug_module.adoc b/debug_module.adoc index eaf876ce..a0a957ab 100644 --- a/debug_module.adoc +++ b/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}). diff --git a/introduction.adoc b/introduction.adoc index ecad6d6a..96d9d63c 100644 --- a/introduction.adoc +++ b/introduction.adoc @@ -40,7 +40,8 @@ functionality. *DTM*:: Debug Transport Module (see <>). -*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. diff --git a/registers.py b/registers.py index 0b41219a..51641b48 100755 --- a/registers.py +++ b/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 \n#include \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: diff --git a/xml/abstract_commands.xml b/xml/abstract_commands.xml index 154e7891..0bb55ddf 100644 --- a/xml/abstract_commands.xml +++ b/xml/abstract_commands.xml @@ -1,3 +1,13 @@ + + + + diff --git a/xml/core_registers.xml b/xml/core_registers.xml index 3ae5daa3..023520ea 100755 --- a/xml/core_registers.xml +++ b/xml/core_registers.xml @@ -1,3 +1,13 @@ + + + + These registers are only accessible from Debug Mode. diff --git a/xml/dm_registers.xml b/xml/dm_registers.xml index bbc46f84..426d1592 100755 --- a/xml/dm_registers.xml +++ b/xml/dm_registers.xml @@ -1,3 +1,13 @@ + + + + diff --git a/xml/hwbp_registers.xml b/xml/hwbp_registers.xml index 4dc4d056..b87a4d7b 100755 --- a/xml/hwbp_registers.xml +++ b/xml/hwbp_registers.xml @@ -1,3 +1,13 @@ + + + + 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 diff --git a/xml/jtag_registers.xml b/xml/jtag_registers.xml index dfda46d0..54e7fdaf 100755 --- a/xml/jtag_registers.xml +++ b/xml/jtag_registers.xml @@ -1,3 +1,13 @@ + + + + diff --git a/xml/sample_registers.xml b/xml/sample_registers.xml index abd3c2f0..d709cde6 100755 --- a/xml/sample_registers.xml +++ b/xml/sample_registers.xml @@ -1,3 +1,13 @@ + + + + Description of what this register is about. @@ -7,4 +17,3 @@ - diff --git a/xml/sw_registers.xml b/xml/sw_registers.xml index d98b6d05..b7dfc8bd 100644 --- a/xml/sw_registers.xml +++ b/xml/sw_registers.xml @@ -1,3 +1,13 @@ + + + + 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