I thought that I had done this
authorAlain D D Williams <addw@phcomp.co.uk>
Thu, 20 Aug 2020 19:13:19 +0000 (20:13 +0100)
committerAlain D D Williams <addw@phcomp.co.uk>
Thu, 20 Aug 2020 19:13:19 +0000 (20:13 +0100)
powerpc-add/build/Makefile
powerpc-add/src/glossary.tex [new file with mode: 0644]
powerpc-add/src/intro.tex
powerpc-add/src/isamux.tex
powerpc-add/src/power-spec.tex
powerpc-add/src/preamble.tex [new file with mode: 0644]
powerpc-add/src/printglossaries.tex [new file with mode: 0644]

index 2354fb3..593d22d 100644 (file)
@@ -65,14 +65,16 @@ open: $(pdfs)
        open $(pdfs)
 
 $(pdfs_with_bib): %.pdf: $(srcdir)/%.tex $(srcs) $(figs) $(bibs)
-       cd $(outdir); $(PDFLATEX) $*
-       cd $(outdir); $(BIBTEX) $*
-       cd $(outdir); $(PDFLATEX) $*
-       cd $(outdir); $(PDFLATEX) $*
+       cd $(outdir); $(PDFLATEX) $* || true
+       cd $(outdir); $(BIBTEX) $* || true
+       cd $(outdir); $(PDFLATEX) $* || true
+       cd $(outdir); makeglossaries $* || true
+       cd $(outdir); $(PDFLATEX) $* || true
 
 $(pdfs_without_bib): %.pdf: $(srcdir)/%.tex $(srcs) $(figs)
-       cd $(outdir); $(PDFLATEX) $*
-       cd $(outdir); $(PDFLATEX) $*
+       cd $(outdir); $(PDFLATEX) $* || true
+       cd $(outdir); makeglossaries $* || true
+       cd $(outdir); $(PDFLATEX) $* || true
 
 junk += *.aux *.log *.bbl *.blg *.toc *.out
 
diff --git a/powerpc-add/src/glossary.tex b/powerpc-add/src/glossary.tex
new file mode 100644 (file)
index 0000000..5aed0b3
--- /dev/null
@@ -0,0 +1,277 @@
+% Glossary
+
+% In the main documentation text I have not tagged every use of the glossary
+% entries below, I have tagged the first in a chapter, or first use for some
+% number of paragraphs.
+
+% Put the definition of terms of the glossary terms in here
+% Try to keep in alphabetic order - for easier editing, they will
+% be generated (in the PDF) in alphabetic order regardless of the order below
+
+% To use one do something like: \gls{PowerPC}
+% Note that the entries are case sensitive.
+
+% Having an entry below will not make it appear in the glossary,
+% it will only appear if it is used, eg: \gls{PowerPC}
+
+% How to use:
+% GlsName      The text that should be used in the document, eg: \gls{GlsName}
+% GlsText      The text that will be shown in the document in place of \gls{GlsName}
+%              GlsName and GlsText can be different but you will probably want
+%              to make them the same.
+% \newglossaryentry{GlsName}
+% {
+%   name=GlsText,
+%   description={
+%     See: \href{}{}
+%     }
+% }
+
+% See:
+% https://en.wikibooks.org/wiki/LaTeX/Glossary
+% http://tug.ctan.org/macros/latex/contrib/glossaries/glossariesbegin.pdf
+
+% An empty entry to use as a template:
+% \newglossaryentry{}
+% {
+%   name=,
+%   description={
+%     See: \href{}{}
+%     }
+% }
+
+% BUG: the glossary entries have a '.' after them that I am not expecting.
+
+% BEWARE: the documentation may need to be built more than once for all of the
+% entries below to appear. This seems to be if an entry is only mentioned in another
+% glossary entry.
+
+\newglossaryentry{Binutils}
+{
+  name=Binutils,
+  description={
+    GNU Binary Utilities is part of the toolchain used for creating and managing
+    binary objects (compiled code).
+    Used with \gls{gcc}.
+    See: \href{https://www.gnu.org/software/binutils/}{GNU web site}
+    }
+}
+
+\newglossaryentry{CPU}
+{
+  name=CPU,
+  description={
+    Central Processing Unit.
+    The brain of a conventional computer that executes general purpose programs.
+    Contrast with \gls{GPU} and \gls{VPU}.
+%    See: \href{}{}
+    }
+}
+
+\newglossaryentry{CSR}
+{
+  name=CSR,
+  description={
+     Control and Status Register.
+     A special register that records CPU status and processing options.
+     One important option to this project is that the special instructions
+     that we have created will be recognised.
+%    See: \href{}{}
+    }
+}
+
+\newglossaryentry{FPGA}
+{
+  name=FPGA,
+  description={
+    Field-programmable gate array.
+    An integrated circuit where the circuitry can be reconfigured.
+    See: \href{https://en.wikipedia.org/wiki/Field-programmable_gate_array}{Wikipedia}
+    }
+}
+
+\newglossaryentry{gcc}
+{
+  name=gcc,
+  description={
+    \gls{GNU} Compiler Collection.
+    A popular open source compiler for C (\& related), Fortran, Ada \& Go and able to generate
+    object code for many \gls{ISA}s including \gls{PowerPC}.
+    See: \href{https://en.wikipedia.org/wiki/GNU_Compiler_Collection}{Wikipedia}
+    }
+}
+
+
+\newglossaryentry{GNU}
+{
+  name=GNU,
+  description={
+    The GNU project is a large collection of free software.
+    It provides many of the core programs that are used by many \gls{Linux} distributions.
+    See: \href{https://www.gnu.org/}{GNU website}
+    }
+}
+
+\newglossaryentry{GPU}
+{
+  name=GPU,
+  description={
+    Graphics processing unit.
+    Special purpose processor optimised for graphics and image generation,
+    often able to run in parallel -- the same instructions on
+    different data at the same time.
+    Contrast with \gls{CPU} and \gls{VPU}.
+    See: \href{https://en.wikipedia.org/wiki/Graphics_processing_unit}{Wikipedia}
+    }
+}
+
+\newglossaryentry{IEEE754}
+{
+  name=IEEE754,
+  description={
+    A popular standard way of representing and manipulating floating point numbers.
+    Initiated by the  Institute of Electrical and Electronics Engineers in 1985.
+    Different precisions from 16 to 256 bits are described.
+    See: \href{https://en.wikipedia.org/wiki/IEEE_754}{Wikipedia}
+    }
+}
+
+\newglossaryentry{ISA}
+{
+  name=ISA,
+  description={
+    Instruction Set Architecture.
+    An abstract model of a computer a definition that includes: registers, memory access,
+    input/output, data types, CPU instruction set.
+    Everything that is needed to be able to create programs to run on the machine.
+    See: \href{https://en.wikipedia.org/wiki/Instruction_set_architecture}{Wikipedia}
+    }
+}
+
+\newglossaryentry{JIT}
+{
+  name=JIT,
+  description={
+    Just In Time compilation.
+    Translate when the program runs, only when needed.
+    See: \href{https://en.wikipedia.org/wiki/Just-in-time_compilation}{Wikipedia}
+    }
+}
+
+\newglossaryentry{Linux}
+{
+  name=Linux,
+  description={
+    A free kernel on which free operating systems and specialised environments are built.
+    Linux is found all the way for small, embedded systems, to desktops, to servers
+    and the world's biggest super computers.
+    It runs on many \gls{ISA}s and supports a huge variety of peripheral devices.
+    Linux was inspired by Unix and is upwards compatible with POSIX.
+    See: \href{https://www.linuxfoundation.org/}{Linux Foundation}
+    }
+}
+
+
+\newglossaryentry{LLVM}
+{
+  name=LLVM,
+  description={
+    A compiler and related toolchain.
+    An open source and able to compileAda, C, C++, D, Delphi, Fortran, Haskell, Julia, Objective-C, Rust, and Swift
+    able to generate object code for many \gls{ISA}s including \gls{PowerPC}.
+    See: \href{https://en.wikipedia.org/wiki/LLVM}{Wikipedia}
+    }
+}
+
+
+\newglossaryentry{PowerPC}
+{
+  name=PowerPC,
+  description={
+    A \gls{RISC} \gls{ISA} created in 1991 by Apple, IBM and Motorola.
+    The name is a backronym: Performance Optimization With Enhanced RISC
+    Performance Computing, sometimes abbreviated as PPC or called POWER).
+    See: \href{https://en.wikipedia.org/wiki/PowerPC}{Wikipedia}
+  }
+}
+
+\newglossaryentry{RISC}
+{
+  name=RISC,
+  description={
+    Reduced Instruction Set Computer.
+    A computer design philosophy that features simple but fast instructions,
+    often with many registers.
+    See: \href{https://en.wikipedia.org/wiki/Reduced_instruction_set_computer}{Wikipedia}
+    }
+}
+
+\newglossaryentry{RISCV}
+{
+  name=RISC-V,
+  description={
+    An open sourced \gls{RISC} \gls{ISA} started in 2010 at the University of California, Berkeley.
+    See: \href{https://en.wikipedia.org/wiki/RISC-V}{Wikipedia}
+    }
+}
+
+\newglossaryentry{SoC}
+{
+  name=SoC,
+  description={
+    System on a Chip.
+    An integrated circuit that has (almost all) the components needed to
+    make a fully running system.
+    See: \href{https://en.wikipedia.org/wiki/System_on_a_chip}{Wikipedia}
+    }
+}
+
+\newglossaryentry{SPARC}
+{
+  name=SPARC,
+  description={
+    A \gls{RISC} \gls{ISA} created by Sun Microsystems.
+    See: \href{https://en.wikipedia.org/wiki/SPARC}{Wikipedia}
+    }
+}
+
+\newglossaryentry{SupervisorMode}
+{
+  name=Supervisor Mode,
+  description={
+    A privileged CPU state where the program can execute instructions or otherwise
+    do things that a non-privileged program would not be allowed to do.
+%    See: \href{}{}
+    }
+}
+
+\newglossaryentry{VPU}
+{
+  name=VPU,
+  description={
+    Video Processing Unit and Visual Processing Unit and Vector Processing Unit
+    Contrast with \gls{CPU} and \gls{GPU}.
+%    See: \href{}{}
+    }
+}
+
+\newglossaryentry{Z80}
+{
+  name=Zilog Z80,
+  description={
+    An 8 bit processor produced by the Zilog Inc in 1986.
+    It is compatible with the Intel 8080 processor.
+    See: \href{https://en.wikipedia.org/wiki/Z80}{Wikiedia}
+    }
+}
+
+% Other entries to consider:
+% emulator
+% namespace
+% MSB
+% PCR
+% ISANS
+% SIE
+% MISA
+% WARL
+% WLRL
index 2f98bcf..d1710a6 100644 (file)
@@ -24,7 +24,7 @@ us.
 \itemsep 1pt
 
 \item
-    We propose the standardisation of the way that the PowerPC Instruction Set
+    We propose the standardisation of the way that the \gls{PowerPC} Instruction Set
     Architecture (PPC ISA) is extended, enabling many different flavours within a
     well supported family to co-exist, long-term, without conflict, right across
     the board.
@@ -51,12 +51,11 @@ us.
 
 \end{itemize}
 
-
 \subsection{One CPU multiple ISAs}
 
 This is a quick overview of the way that we would like to add changes that we
 are proposing to the PowerPC instruction set (ISA). It is based on a Open
-Standardisation of the way that existing "mode switches", already found in the
+Standardisation of the way that existing \textbf{mode switches}, already found in the
 POWER instruction set, are added:
 
 \begin{itemize}
@@ -65,25 +64,25 @@ POWER instruction set, are added:
 
 \item
 
-    FPSCR's "NI" bit, setting non-IEEE754 FP mode
+    FPSCR's \textbf{NI} bit, setting non-\gls{IEEE754} FP mode
 
 \item
 
-    MSR's "LE" bit (and associated HILE bit), setting little-endian mode
+    MSR's \textbf{LE} bit (and associated HILE bit), setting little-endian mode
 
 \item
 
-    MSR's "SF" bit, setting either 32-bit or 64-bit mode
+    MSR's \textbf{SF} bit, setting either 32-bit or 64-bit mode
 
 \item
 
-    PCR's "compatibility" bits 60-62, V2.05 V2.06 V2.07 mode
+    PCR's \textbf{compatibility} bits 60-62, V2.05 V2.06 V2.07 mode
 
 \end{itemize}
 
-[It is well-noted that unless each "mode switch" bit is set, any alternative
+[It is well-noted that unless each \textbf{mode switch} bit is set, any alternative
 (additional) instructions (and functionality) are completely inaccessible, and
-will result in "illegal instruction" traps being thrown. This is recognised as
+will result in \textbf{illegal instruction} traps being thrown. This is recognised as
 being critically important.]
 
 These bits effectively create multiple, incompatible run-time switchable ISAs
@@ -95,14 +94,14 @@ the entire behaviour and characteristics of subsequent instructions.
 
 With these (and other) long-established precedents already in POWER, there is
 therefore essentially conceptually nothing new about what we propose: we simply
-seek that the process by which such "switching" is added is formalised and
+seek that the process by which such \textbf{switching} is added is formalised and
 standardised, such that we (and others, including IBM itself) have a clear,
 well-defined standards-non-disruptive, atomic and non-intrusive path to extend
 the POWER ISA for use in markets that it presently cannot enter.
 
-We advocate that some of "mode-setting" (escape-sequencing) bits be binary
-encoded, some unary encoded, and that some space marked for "offical" use, some
-"experimental", some "custom" and some "reserved". The available space in a
+We advocate that some of \textbf{mode-setting} (escape-sequencing) bits be binary
+encoded, some unary encoded, and that some space marked for \textbf{offical} use, some
+\textbf{experimental}, some \textbf{custom} and some \textbf{reserved}. The available space in a
 suitably-chosen SPR to be formalised, and recommend the OpenPOWER Foundation be
 given the IANA-like role in atomically allocating mode bits.
 
@@ -115,9 +114,9 @@ allocating the same mode bit(s) to two (or more) designers, or not making
 illegal exceptions mandatory: binary interoperability becomes unachievable and
 the result is irrevocable damage to POWER's reputation.)
 
-We also advocate to consider reserving some bits as a "countdown" where the new
+We also advocate to consider reserving some bits as a \textbf{countdown} where the new
 mode will be enabled only for a certain number of instructions. This avoids an
-explicit need to "flip back", reducing binary code size. Note that it is not a
+explicit need to \textbf{flip back}, reducing binary code size. Note that it is not a
 good idea to let the counter cross a branch or other change in PC (and to throw
 illegal instruction trap if attempted). However traps and exceptions themselves
 will need to save (and restore) the countdown, just as the rest of the PCR and
@@ -125,9 +124,9 @@ other modeswitching bits need to be saved.
 
 Instructions that we need to add, which are a normal part of GPUs, include
 ATAN2, LOG, NORMALISE, YUV2RGB, Khronos Compliance FP mode (different from both
-IEEE754 and "NI" mode), and many more. Many of these may turn out to be useful
+IEEE754 and \textbf{NI} mode), and many more. Many of these may turn out to be useful
 in a wider context: they however need to be fully isolated behind
-"mode-setting" before being in any way considered for Standards-track formal
+\textbf{mode-setting} before being in any way considered for Standards-track formal
 adoption.
 
 Some mode-setting instructions are privileged, i.e can only be set by the
@@ -138,22 +137,22 @@ inner loops).
 
 \subsection{About Libre-SOC Commercial Project}
 
-The Libre-SOC Commercial Product is a hybrid GPU-GPU-VPU intended for
+The Libre-SOC Commercial Product is a hybrid \gls{CPU}-\gls{GPU}-\gls{VPU} intended for
 mass-volume production. There is no separate GPU, because the CPU is the GPU.
 There is no separate VPU, because the CPU is the GPU. There is not even a
 separate pipeline: the CPU pipelines are the GPU and VPU pipelines.
 
 Closest equivalents include the ARC core (which has VPU extensions and 3D
 extensions in the form of Broadcom's VideoCore IV) and the ICubeCorp IC3128.
-Both are considered "hybrid" CPU-GPU-VPU processors.
+Both are considered \textbf{hybrid} CPU-GPU-VPU processors.
 
-"Normal" Commercial GPUs are entirely separate processors. The development cost
+\textbf{Normal} Commercial GPUs are entirely separate processors. The development cost
 and complexity purely in terms of Software Drivers alone is immense. We reject
 that approach (and as a small team we do not have the resources anyway).
 
 With the project being Libre - not proprietary and secretive and never to be
-published, ever - it is no good having the extensions as "custom" because
-"custom" is specifically for the cases where the augmented toolchain is never,
+published, ever - it is no good having the extensions as \textbf{custom} because
+\textbf{custom} is specifically for the cases where the augmented toolchain is never,
 under any circumstances, published and made public by the proprietary company
 (and would never be accepted upstream anyway). For business commercial reasons,
 Libre-SOC is the total opposite of this proprietary, secretive approach.
@@ -167,7 +166,7 @@ Therefore, to meet our business objectives:
 \item
 
     As shown from Nyuzi and Larrabee, although ideally suited to high
-    performance compute tasks, a "traditional" general-purpose full
+    performance compute tasks, a \textbf{traditional} general-purpose full
     IEEE754-compliant Vector ISA (such as that in POWER9) is not an adequate
     basis for a commercially competitive GPU. Nyuzi's conclusion is that using
     such general-purpose Vector ISAs results in reaching only 25% performance
@@ -176,13 +175,13 @@ Therefore, to meet our business objectives:
 
 \item
 
-    We are not going the "traditional" (separate custom GPU) route because it
+    We are not going the \textbf{traditional} (separate custom GPU) route because it
     is not practical for a new team to design hardware and spend 8+ man-years
     on massively complex inter-processor driver development as well
 
 \item
 
-    We cannot meet our objectives with a "custom extension" because the
+    We cannot meet our objectives with a \textbf{custom extension} because the
     financial burden on our team to maintain a total hard fork of not just
     toolchains, but also entire GNU/Linux Distros, is highly undesirable, and
     completely impractical (we know for certain that Redhat would strongly
@@ -192,9 +191,9 @@ Therefore, to meet our business objectives:
 
     We could invent our own custom GPU instruction set (or use and extend an
     existing one, to save a man-decade on toolchain development) however even
-    to switch over to that "Dual ISA" GPU instruction set in the next clock
+    to switch over to that \textbf{Dual ISA} GPU instruction set in the next clock
     cycle still requires a PCR modeswitch bit in order to avoid needing a full
-    Inter-Processor Bus Architecture like on "traditional" GPUs.
+    Inter-Processor Bus Architecture like on \textbf{traditional} GPUs.
 
 \item
 
@@ -203,7 +202,7 @@ Therefore, to meet our business objectives:
 
 \item
 
-    We cannot "go ahead anyway" because to do so would be highly irresponsible
+    We cannot \textbf{go ahead anyway} because to do so would be highly irresponsible
     and cause massive disruption to the POWER community.
 
 \end{itemize}
index 670ac87..79da4ea 100644 (file)
@@ -5,7 +5,7 @@
 \paragraph{}
 
 A fixed number of additional (hidden) bits, conceptually a \textbf{namespace},
-set by way of a CSR or other out-of-band mechanism,
+set by way of a \gls{CSR} or other out-of-band mechanism,
 that go directly and non-optionally
 into the instruction decode phase, extending (in each implementation) the
 opcode length to 16+N, 32+N, 48+N, where N is a hard fixed quantity on
@@ -33,8 +33,8 @@ instruction?)
 \paragraph{}
 
 An example of a pre-existing \textbf{namespace} switch that has been in
-prevalent use for several decades (SPARC and other architectures):
-dynamic runtime selectability of littel-endian / big-endian \textbf{meaning}
+prevalent use for several decades (\gls{SPARC} and other architectures):
+dynamic runtime selectability of little-endian / big-endian \textbf{meaning}
 of instructions by way of a \textbf{mode switch} instruction (of some kind).
 
 \paragraph{}
@@ -48,14 +48,15 @@ and generalises that concept.
 
 \paragraph{}
 
-Note that this is a hypothetical format, yet TBD, where particular attention
-needs to be paid to the fact that there is an \textbf{immediate} version of CSRRW
-(with 5 bits of immediate) that could save a lot of space in binaries.
+Note that this is a hypothetical format, yet to be decided, where particular
+attention needs to be paid to the fact that there is an \textbf{immediate}
+version of CSRRW (with 5 bits of immediate) that could save a lot of space in
+binaries.
 
 \begin{verbatim}
    3                   2                   1
 |1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0|
-|------------------------------ |-------|---------------------|-|
+|-------------------------------|-------|---------------------|-|
 |1 custom custom   custom   custom   custom     | foreignarch |1|
 |0 reserved reserved reserved reserved reserved | foreignarch |1|
 |custom         | reserved    |           official|B| rvcpage |0|
@@ -237,7 +238,7 @@ This to occur immediately and atomically at the point at which the change in ISA
 \paragraph{}
 
 The most obvious application of this is for Foreign Archs, which may have their
-own completely separate PC. Thus, foreign assembly code and RISCV assembly code
+own completely separate PC. Thus, foreign assembly code and \gls{RISCV} assembly code
 need not be mixed in the same binary.
 
 \paragraph{}
@@ -254,7 +255,7 @@ state!) which is quite severely burdensome and getting exceptionally complex.
 
 \paragraph{}
 
-Switching CSR, PC (and potentially SP) and other state on a NS change in the
+Switching \gls{CSR}, PC (and potentially SP) and other state on a NS change in the
 RISCV unary NS therefore needs to be done wisely and responsibly, i.e.
 minimised!
 
@@ -288,7 +289,7 @@ This is identical to how xepc is handled.
 
 \paragraph{}
 
-Note 1: in the case of Supervisor Mode (context switches in particular),
+Note 1: in the case of \gls{SupervisorMode} (context switches in particular),
 saving and changing of LAST-ISANS (to and from the stack) must be done
 atomically and under the protection of the SIE bit.  Failure to do so
 could result in corruption of LAST-ISANS when multiple traps occur in
@@ -341,7 +342,7 @@ is the \textbf{solution}.
 
 The correct thing to do is, again, just like with foreign archs, to
 treat RVCs as a \textbf{binary} namespace selector. Bits 1 thru 3 would give
-8 possible completely new alternative meanings, just like how the Z80
+8 possible completely new alternative meanings, just like how the \gls{Z80}
 and the 286 and 386 used to do bank switching.
 
 \paragraph{}
@@ -441,12 +442,12 @@ Those that are compatible with the new standard.
 \paragraph{}
 
 \textbf{These two communities would be mutually exclusively incompatible}. If
-a second emergency occurs, RISCV becomes even less tenable.
+a second emergency occurs, \gls{RISCV} becomes even less tenable.
 
 \paragraph{}
 
 Hardware that wished to be \textbf{compatible} with either flavour would require
-JIT or offline static binary recompilation. No vendor would willingly
+\gls{JIT} or offline static binary recompilation. No vendor would willingly
 accept this as a condition of the standards divergence in the first place,
 locking up decision making to the detriment of RISCV as a whole.
 
@@ -473,7 +474,7 @@ It's complicated in other words!
 Short answer: it doesn't help resolve conflicts, and costs hardware and
 redesigns to do so.  Softcores in cost-sensitive embedded applications may
 even not actually be able to fit the required 48 bit instruction decode engine
-into a (small, ICE40) FPGA.  48-bit instruction decoding is much more complex
+into a (small, ICE40) \gls{FPGA}.  48-bit instruction decoding is much more complex
 than straight 32-bit decoding, requiring a queue.
 
 \paragraph{}
@@ -501,7 +502,7 @@ worldwide context that the UNIX Platform, in particular, has to face
 \paragraph{}
 
 First: lack of coordination, in the proliferation of arbitrary solutions,
-has to primarily be borne by gcc, binutils, LLVM and other compilers.
+has to primarily be borne by \gls{gcc}, \gls{Binutils}, \gls{LLVM} and other compilers.
 
 \paragraph{}
 
@@ -515,7 +516,7 @@ benefit compiler writers), the CSR register space is quickly exhausted.
 Thirdly: JIT Emulation of such an unregulated space becomes just as
 much hell as it is for compiler writers. In addition, if two vendors
 use conflicting CSR addresses, the only sane way to tell the emulator
-what to do is to give the emulator a runtime commandline argument.
+what to do is to give the emulator a runtime command line argument.
 
 \paragraph{}
 
@@ -788,7 +789,7 @@ no way interacts or interferes with this proposal.
 Answer: don't know (yet).  Quoted from Rogier:
 
 \begin{quote}
-"A SOC may have several devices that one may want to directly control
+"A \gls{SoC} may have several devices that one may want to directly control
 with custom instructions. If independent vendors use the same opcodes you
 either have to change the encodings for every different chip (not very
 nice for software) or you can give the device an ID which is defined in
@@ -797,10 +798,10 @@ some device tree or something like that and use that."
 
 \paragraph{}
 
-dynamic detection wasn't originally planned: static
+Dynamic detection wasn't originally planned: static
 compilation was envisaged to solve the need, with a table of
 mvendorid-marchid-isamux/isans being maintained inside gcc / binutils /
-llvm (or separate library?) that, like the linux kernel ARCH table,
+llvm (or separate library?) that, like the Linux kernel ARCH table,
 requires a world-wide atomic \textbf{git commit} to add globally-unique
 registered entries that map functionality to actual namespaces.
 
index 44377e6..9476f36 100644 (file)
 
 \input{preamble}
 
-\newcommand{\specrev}{\mbox{20200813-{\em draft}}}
-\newcommand{\specmonthyear}{\mbox{August 2020}}
-
-\usepackage[english]{babel}
-\usepackage{datetime}
-\longdate      % makes \today generate like: Wednesday 18th August, 2020
-
 \begin{document}
 
 \title{\vspace{-0.7in}\Large {\bf Additions to The PowerPC Instruction Set Manual} \\
@@ -41,7 +34,7 @@ Luke Kenneth Casson Leighton, Jacob R Lifshay, Alain D D Williams
 This document is released under a Creative Commons Attribution 4.0
 International License.
 
-Please cite as: ``The PowerPC Instruction Set Additions, Document Version \specrev'', Editors
+Please cite as: ``The PowerPC Instruction Set Additions, Document Version \specrev'', Editor
 Alain Williams, Libre-SOC, \specmonthyear.
 
 
@@ -61,6 +54,7 @@ Alain Williams, Libre-SOC, \specmonthyear.
 
 \input{intro}
 \input{isamux}
+
 % \input{rv32}
 % \input{zifencei}
 % \input{rv32e}
@@ -95,4 +89,6 @@ Alain Williams, Libre-SOC, \specmonthyear.
 \bibliographystyle{plain}
 \bibliography{power-spec}
 
+\input{printglossaries}
+
 \end{document}
diff --git a/powerpc-add/src/preamble.tex b/powerpc-add/src/preamble.tex
new file mode 100644 (file)
index 0000000..d96b80d
--- /dev/null
@@ -0,0 +1,163 @@
+% Package includes
+
+\usepackage{graphicx}
+\usepackage{geometry}
+\usepackage{array}
+\usepackage{colortbl}
+\usepackage[svgnames]{xcolor}
+
+\usepackage[colorlinks,citecolor=Navy,linkcolor=Navy]{hyperref}
+\usepackage{placeins}
+\usepackage{longtable}
+\usepackage{multirow}
+\usepackage{float}
+\usepackage{listings}
+\usepackage{comment}
+\usepackage{enumitem}
+\usepackage{verbatimbox}
+\usepackage{amsmath}
+
+\usepackage[olditem,oldenum]{paralist}
+
+\usepackage[english]{babel}
+\usepackage{datetime}
+\longdate      % makes \today generate like: Wednesday 18th August, 2020
+
+% **** Change the 2 lines below to specify a new version/release, also the date:
+\newcommand{\specrev}{\mbox{20200813-{\em draft}}}
+\newcommand{\specmonthyear}{\mbox{August 2020}}
+
+
+% Glossary entries. We want them in the index (toc)
+\usepackage[toc]{glossaries}
+\makeglossaries
+% They have to be defined before used, so bring in here:
+\input{glossary}
+
+% Setup margins
+
+\setlength{\topmargin}{-0.5in}
+\setlength{\textheight}{9in}
+\setlength{\oddsidemargin}{0in}
+\setlength{\evensidemargin}{0in}
+\setlength{\textwidth}{6.5in}
+
+% Useful macros
+
+\newcommand{\note}[1]{{\bf [ NOTE: #1 ]}}
+\newcommand{\fixme}[1]{{\bf [ FIXME: #1 ]}}
+\newcommand{\todo}[1]{\marginpar{\footnotesize #1}}
+
+\newcommand{\wunits}[2]{\mbox{#1\,#2}}
+\newcommand{\um}{\mbox{$\mu$m}}
+\newcommand{\xum}[1]{\wunits{#1}{\um}}
+\newcommand{\by}[2]{\mbox{#1$\times$#2}}
+\newcommand{\byby}[3]{\mbox{#1$\times$#2$\times$#3}}
+
+\newlength\savedwidth
+\newcommand\whline[1]{%
+  \noalign{%
+    \global\savedwidth\arrayrulewidth\global\arrayrulewidth 1.5pt%
+  }%
+  \cline{#1}%
+  \noalign{\vskip\arrayrulewidth}%
+  \noalign{\global\arrayrulewidth\savedwidth}%
+}
+
+% Custom list environments
+
+\newlist{tightlist}{itemize}{1}
+\setlist[tightlist]{label=\textbullet,nosep}
+
+\newenvironment{titledtightlist}[1]
+{\noindent
+ ~~\textbf{#1}
+ \begin{tightlist}}
+{\end{tightlist}}
+
+\newenvironment{commentary}
+{      \vspace{-1.5mm}
+       \list{}{
+               \topsep         0mm
+               \partopsep      0mm
+               \listparindent  1.5em
+               \itemindent     \listparindent
+               \rightmargin    \leftmargin
+               \parsep         0mm
+       }
+       \item
+       \small\em
+       \noindent\nopagebreak\rule{\linewidth}{1pt}\par
+       \noindent\ignorespaces
+}
+{\endlist}
+
+%\newenvironment{discussion}
+%{     \vspace{-1.5mm}
+%      \list{}{
+%              \topsep         0mm
+%              \partopsep      0mm
+%              \listparindent  1.5em
+%              \itemindent     \listparindent
+%              \rightmargin    \leftmargin
+%              \parsep         0mm
+%      }
+%      \item
+%      \small\em
+%      \noindent\nopagebreak\rule{\linewidth}{1pt}\par
+%      \noindent\textbf{Discussion:}
+%}
+%{\endlist}
+
+% Other commands and parameters
+
+\pagestyle{myheadings}
+\setlength{\parindent}{0in}
+\setlength{\parskip}{10pt}
+\sloppy
+\raggedbottom
+\clubpenalty=10000
+\widowpenalty=10000
+
+% Commands for register format figures.
+
+% New column types to use in tabular environment for instruction formats.
+% Allocate 0.18in per bit.
+\newcolumntype{I}{>{\centering\arraybackslash}p{0.18in}}
+% Two-bit centered column.
+\newcolumntype{W}{>{\centering\arraybackslash}p{0.36in}}
+% Three-bit centered column.
+\newcolumntype{F}{>{\centering\arraybackslash}p{0.54in}}
+% Four-bit centered column.
+\newcolumntype{Y}{>{\centering\arraybackslash}p{0.72in}}
+% Five-bit centered column.
+\newcolumntype{R}{>{\centering\arraybackslash}p{0.9in}}
+% Six-bit centered column.
+\newcolumntype{S}{>{\centering\arraybackslash}p{1.08in}}
+% Seven-bit centered column.
+\newcolumntype{O}{>{\centering\arraybackslash}p{1.26in}}
+% Eight-bit centered column.
+\newcolumntype{E}{>{\centering\arraybackslash}p{1.44in}}
+% Ten-bit centered column.
+\newcolumntype{T}{>{\centering\arraybackslash}p{1.8in}}
+% Twelve-bit centered column.
+\newcolumntype{M}{>{\centering\arraybackslash}p{2.2in}}
+% Sixteen-bit centered column.
+\newcolumntype{K}{>{\centering\arraybackslash}p{2.88in}}
+% Twenty-bit centered column.
+\newcolumntype{U}{>{\centering\arraybackslash}p{3.6in}}
+% Twenty-bit centered column.
+\newcolumntype{L}{>{\centering\arraybackslash}p{3.6in}}
+% Twenty-five-bit centered column.
+\newcolumntype{J}{>{\centering\arraybackslash}p{4.5in}}
+
+\newcommand{\instbit}[1]{\mbox{\scriptsize #1}}
+\newcommand{\instbitrange}[2]{~\instbit{#1} \hfill \instbit{#2}~}
+\newcommand{\reglabel}[1]{\hfill {\tt #1}\hfill\ }
+
+\newcommand{\wiri}{\textbf{WIRI}}
+\newcommand{\wpri}{\textbf{WPRI}}
+\newcommand{\wlrl}{\textbf{WLRL}}
+\newcommand{\warl}{\textbf{WARL}}
+
+\newcommand{\unspecified}{\textsc{unspecified}}
diff --git a/powerpc-add/src/printglossaries.tex b/powerpc-add/src/printglossaries.tex
new file mode 100644 (file)
index 0000000..1a11255
--- /dev/null
@@ -0,0 +1,7 @@
+% Generate/print the glossary text
+% A separate file so that the acknowledgement can be given.
+
+\printglossaries
+
+Acknowledgement and thanks for some of the glossary text having been
+taken from: Wikipedia, and other places.