Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Replace LaTeX {steps} inside XML files. #940

Merged
merged 4 commits into from
Dec 29, 2023
Merged

Replace LaTeX {steps} inside XML files. #940

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ea33a59
Move label before header.
timsifive Dec 29, 2023
83482fb
Render asciidoc inside table cells, for lists.
timsifive Dec 29, 2023
ac0f59b
Replace LaTeX {steps} with ordered list.
timsifive Dec 29, 2023
008f367
Replace {csr-mcontrol}Six with {csr-mcontrol6}
timsifive Dec 29, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions registers.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -917,6 +917,8 @@ def write_adoc( fd, registers ):
if not r.fields and not r.description:
continue

if r.label and r.define:
fd.write("[[%s]]\n" % toAdocIdentifier(registers.prefix, r.label))
if r.short:
# TODO: Check that (((foo))) renders as ((foo)) inside parens
if r.address:
Expand All @@ -930,8 +932,6 @@ def write_adoc( fd, registers ):
else:
fd.write(f"==={sub} ((`{r.name}`))\n")
fd.write("\n")
if r.label and r.define:
fd.write("[[%s]]\n" % toAdocIdentifier(registers.prefix, r.label))
fd.write(remove_indent(r.description))
fd.write("\n")

Expand Down Expand Up @@ -965,9 +965,9 @@ def write_adoc( fd, registers ):
for f in r.fields:
if f.description or f.values:
identifier = toAdocIdentifier(r.short or r.label, f.name)
fd.write(f"|[[{identifier},{identifier}]] `{columns[0][2](f)}`\n")
fd.write(f"|[[{identifier}]] `{columns[0][2](f)}`\n")
for c in columns[1:]:
fd.write("|" + add_continuations(remove_indent( c[2](f) )) + "\n")
fd.write("a|" + remove_indent( c[2](f) ) + "\n")

fd.write("|===\n")
fd.write("\n")
Expand Down
38 changes: 19 additions & 19 deletions xml/abstract_commands.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,24 +1,24 @@
<registers name="Abstract Commands" skip_index="1" skip_access="1"
skip_reset="1" prefix="AC_" depth="2">
<register name="Access Register">
\begin{steps}{This command gives the debugger access to CPU registers
This command gives the debugger access to CPU registers
and allows it to execute the Program Buffer.
It performs the following sequence of operations:}
\item If {accessregister-write} is clear and {accessregister-transfer} is set, then copy data from
It performs the following sequence of operations:

. If {accessregister-write} is clear and {accessregister-transfer} is set, then copy data from
the register specified by {accessregister-regno} into the {\tt arg0} region of
{\tt data}, and perform any side effects that occur when this
register is read from M-mode.
\item If {accessregister-write} is set and {accessregister-transfer} is set, then copy data from the
. If {accessregister-write} is set and {accessregister-transfer} is set, then copy data from the
{\tt arg0} region of {\tt data} into the register specified by
{accessregister-regno}, and perform any side effects that occur when this register
is written from M-mode.
\item If {accessregister-aarpostincrement} and
. If {accessregister-aarpostincrement} and
{accessregister-transfer} are set, increment
{accessregister-regno}. {accessregister-regno} may also be
incremented if {accessregister-aarpostincrement} is set and
{accessregister-transfer} is clear.
\item Execute the Program Buffer, if {accessregister-postexec} is set.
\end{steps}
. Execute the Program Buffer, if {accessregister-postexec} is set.

If any of these operations fail, {abstractcs-cmderr} is set and none of the
remaining steps are executed. An implementation may detect an upcoming
Expand Down Expand Up @@ -154,17 +154,17 @@
</register>

<register name="Quick Access">
\begin{steps}{Perform the following sequence of operations:}
\item If the hart is halted, the command sets {abstractcs-cmderr} to ``halt/resume'' and does not continue.
\item Halt the hart. If the hart halts for some other reason (e.g. breakpoint), the command
Perform the following sequence of operations:

. If the hart is halted, the command sets {abstractcs-cmderr} to ``halt/resume'' and does not continue.
. Halt the hart. If the hart halts for some other reason (e.g. breakpoint), the command
sets {abstractcs-cmderr} to ``halt/resume'' and does not continue.
\item Execute the Program Buffer.
. Execute the Program Buffer.
If an exception occurs, {abstractcs-cmderr} is set to
``exception,'' the Program Buffer execution ends, and the hart is
halted with {dcsr-cause} set to 3.
\item If the Program Buffer executed without an exception, then
. If the Program Buffer executed without an exception, then
resume the hart.
\end{steps}

Implementing this command is optional.

Expand All @@ -177,17 +177,17 @@
</register>

<register name="Access Memory">
\begin{steps}{This command lets the debugger perform memory accesses,
This command lets the debugger perform memory accesses,
with the exact same memory view and permissions as the selected
hart has. This includes access to hart-local memory-mapped
registers, etc. The command performs the following sequence of
operations:}
\item Copy data from the memory location specified in {\tt arg1} into the
operations:

. Copy data from the memory location specified in {\tt arg1} into the
{\tt arg0} portion of {\tt data}, if {accessregister-write} is clear.
\item Copy data from the {\tt arg0} portion of {\tt data} into the
. Copy data from the {\tt arg0} portion of {\tt data} into the
memory location specified in {\tt arg1}, if {accessregister-write} is set.
\item If {accessmemory-aampostincrement} is set, increment {\tt arg1}.
\end{steps}
. If {accessmemory-aampostincrement} is set, increment {\tt arg1}.

If any of these operations fail, {abstractcs-cmderr} is set and none of the
remaining steps are executed. An access may only fail if the hart,
Expand Down
12 changes: 6 additions & 6 deletions xml/core_registers.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,13 @@
fields and {dcsr-nmip}, the other fields of {csr-dcsr} are only
writable by the external debugger.

\begin{steps}{Table~\ref{tab:dcsrcausepriority} shows the priorities of
Table~\ref{tab:dcsrcausepriority} shows the priorities of
reasons for entering Debug Mode. Implementations should implement
priorities as shown in the table. For compatibility with old versions of this spec, resethaltreq and haltreq are
allowed to be at different positions than shown as long as:}
\item resethaltreq is higher priority than haltreq
\item the relative order of the other four causes is maintained
\end{steps}
allowed to be at different positions than shown as long as:

. resethaltreq is higher priority than haltreq
. the relative order of the other four causes is maintained

\begin{table}[H]
\centering
Expand Down Expand Up @@ -282,7 +282,7 @@
trigger module &amp; The address of the next instruction to be
executed at the time that debug mode was entered. If the trigger is
{csr-mcontrol} and {mcontrol-timing} is 0 or if the trigger is
{csr-mcontrol}Six and {mcontrol6-hit1} is 0, this
{csr-mcontrol6} and {mcontrol6-hit1} is 0, this
corresponds to the address of the instruction which caused the trigger
to fire. \\
\hline
Expand Down
46 changes: 23 additions & 23 deletions xml/dm_registers.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -981,14 +981,14 @@
When the system bus manager is busy, writes to this register will set
{sbcs-sbbusyerror} and don't do anything else.

\begin{steps}{If {sbcs-sberror} is 0, {sbcs-sbbusyerror} is 0, and {sbcs-sbreadonaddr}
is set then writes to this register start the following:}
\item Set {sbcs-sbbusy}.
\item Perform a bus read from the new value of {\tt sbaddress}.
\item If the read succeeded and {sbcs-sbautoincrement} is set, increment
If {sbcs-sberror} is 0, {sbcs-sbbusyerror} is 0, and {sbcs-sbreadonaddr}
is set then writes to this register start the following:

. Set {sbcs-sbbusy}.
. Perform a bus read from the new value of {\tt sbaddress}.
. If the read succeeded and {sbcs-sbautoincrement} is set, increment
{\tt sbaddress}.
\item Clear {sbcs-sbbusy}.
\end{steps}
. Clear {sbcs-sbbusy}.

<field name="address" bits="31:0" access="R/W" reset="0">
Accesses bits 31:0 of the physical address in {\tt sbaddress}.
Expand Down Expand Up @@ -1044,25 +1044,25 @@
If the bus manager is busy then accesses set {sbcs-sbbusyerror}, and don't do
anything else.

\begin{steps}{Writes to this register start the following:}
\item Set {sbcs-sbbusy}.
\item Perform a bus write of the new value of {\tt sbdata} to {\tt sbaddress}.
\item If the write succeeded and {sbcs-sbautoincrement} is set,
Writes to this register start the following:

. Set {sbcs-sbbusy}.
. Perform a bus write of the new value of {\tt sbdata} to {\tt sbaddress}.
. If the write succeeded and {sbcs-sbautoincrement} is set,
increment {\tt sbaddress}.
\item Clear {sbcs-sbbusy}.
\end{steps}

\begin{steps}{Reads from this register start the following:}
\item ``Return'' the data.
\item Set {sbcs-sbbusy}.
\item \begin{steps}{If {sbcs-sbreadondata} is set:}
\item Perform a system bus read from the address contained in
. Clear {sbcs-sbbusy}.

Reads from this register start the following:

. ``Return'' the data.
. Set {sbcs-sbbusy}.
. If {sbcs-sbreadondata} is set:
// TODO: This doesn't work right, but it does work in asiidoclive
.. Perform a system bus read from the address contained in
{\tt sbaddress}, placing the result in {\tt sbdata}.
\item If {sbcs-sbautoincrement} is set and the read was
.. If {sbcs-sbautoincrement} is set and the read was
successful, increment {\tt sbaddress}.
\end{steps}
\item Clear {sbcs-sbbusy}.
\end{steps}
. Clear {sbcs-sbbusy}.

Only {dm-sbdata0} has this behavior. The other {\tt sbdata} registers
have no side effects. On systems that have buses wider than 32 bits, a
Expand Down
51 changes: 24 additions & 27 deletions xml/hwbp_registers.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@

<value v="6" name="mcontrol6">
The trigger is an address/data match trigger. The remaining bits
in this register act as described in {csr-mcontrol}Six. This is similar
in this register act as described in {csr-mcontrol6}. This is similar
to a type 2 trigger, but provides additional functionality and
should be used instead of type 2 in newer implementations.
</value>
Expand Down Expand Up @@ -171,14 +171,12 @@
Supports triggers as described in this spec at commit 5a5c078,
made on February 2, 2023.

\begin{steps}{In these older versions:}
\item {csr-mcontrol}Six has a timing bit identical to
{mcontrol-timing}
\item {mcontrol6-hit0} behaves just as {mcontrol-hit}.
\item {mcontrol6-hit1} is read-only 0.
\item Encodings for {mcontrol6-size} for access sizes larger
than 64 bits are different.
\end{steps}
In these older versions:

. {csr-mcontrol6} has a timing bit identical to {mcontrol-timing}
. {mcontrol6-hit0} behaves just as {mcontrol-hit}.
. {mcontrol6-hit1} is read-only 0.
. Encodings for {mcontrol6-size} for access sizes larger than 64 bits are different.
</value>
<value v="1" name="1">
Supports triggers as described in the ratified version 1.0 of
Expand Down Expand Up @@ -308,9 +306,9 @@

\begin{commentary}
This trigger type only supports a subset of features of the newer
{csr-mcontrol}Six. It is expected that new implementations will not
{csr-mcontrol6}. It is expected that new implementations will not
support this trigger type and that new debuggers will not use it if
{csr-mcontrol}Six is available.
{csr-mcontrol6} is available.
\end{commentary}

Address and data trigger implementation are heavily dependent on how
Expand Down Expand Up @@ -688,15 +686,15 @@
virtual address is the address which caused any of the chained
triggers to fire.

\begin{steps}{In implementations that support {mcontrol6-match} mode 1 (NAPOT), not all
In implementations that support {mcontrol6-match} mode 1 (NAPOT), not all
NAPOT ranges may be supported. All NAPOT ranges between stem:[2^1] and stem:[2^{maskmax6}]
are supported where stem:[{maskmax6} \geq 1]. The value of maskmax6 can be determined
by the debugger via the following sequence:}
\item Set {mcontrol6-match}=1.
\item Read {mcontrol6-match}. If it is not 1 then NAPOT matching is not supported.
\item Write all ones to {csr-tdata2}.
\item Read {csr-tdata2}. The value of maskmax6 is the index of the most significant 0 bit plus 1.
\end{steps}
by the debugger via the following sequence:

. Set {mcontrol6-match}=1.
. Read {mcontrol6-match}. If it is not 1 then NAPOT matching is not supported.
. Write all ones to {csr-tdata2}.
. Read {csr-tdata2}. The value of maskmax6 is the index of the most significant 0 bit plus 1.

If {csr-textra32} or {csr-textra64} are implemented for this
trigger, it only matches when the conditions set there are satisfied.
Expand Down Expand Up @@ -891,16 +889,16 @@
different type. It is undefined when exactly such a chain fires.

Because {mcontrol6-chain} affects the next trigger, hardware must zero it in
writes to {csr-mcontrol}Six that set {tdata1-dmode} to 0 if the next trigger has
writes to {csr-mcontrol6} that set {tdata1-dmode} to 0 if the next trigger has
{tdata1-dmode} of 1.
In addition hardware should ignore writes to {csr-mcontrol}Six that set
In addition hardware should ignore writes to {csr-mcontrol6} that set
{tdata1-dmode} to 1 if the previous trigger has both {tdata1-dmode} of 0 and
{mcontrol6-chain} of 1. Debuggers must avoid the latter case by checking
{mcontrol6-chain} on the previous trigger if they're writing {csr-mcontrol}Six.
{mcontrol6-chain} on the previous trigger if they're writing {csr-mcontrol6}.

Implementations that wish to limit the maximum length of a trigger
chain (eg. to meet timing requirements) may do so by zeroing
{mcontrol6-chain} in writes to {csr-mcontrol}Six that would make the chain too long.
{mcontrol6-chain} in writes to {csr-mcontrol6} that would make the chain too long.
</field>
<field name="match" bits="10:7" access="WARL" reset="0">
<value v="0" name="equal">
Expand Down Expand Up @@ -1011,14 +1009,13 @@

This register is accessible as {csr-tdata1} when {tdata1-type} is 3.

\begin{steps}{This trigger matches when:}
\item
An instruction retires after having been fetched in a privilege
This trigger matches when:

. An instruction retires after having been fetched in a privilege
mode where the trigger is enabled.
This explicitly includes {\em x}\/RET instructions.
\item A trap is taken from a privilege mode where the trigger is enabled.
. A trap is taken from a privilege mode where the trigger is enabled.
This explicitly includes traps taken due to interrupts.
\end{steps}

If more than one of the above events occur during a single instruction
execution, the trigger still only matches once for that instruction.
Expand Down