[Debian-coldfire-commits] r9 - trunk/doc

[Wouter Verhelst]

Author: wouter
Date: 2006-02-17 11:51:06 +0000 (Fri, 17 Feb 2006)
New Revision: 9

Added:
   trunk/doc/Makefile
   trunk/doc/prm.tex
Log:
Some initial documentation, to explain to Joe Random Hacker what we expect.
Needs a lot of work; may eventually be totally useless, as well.


Added: trunk/doc/Makefile
===================================================================
--- trunk/doc/Makefile	2006-02-17 11:50:05 UTC (rev 8)
+++ trunk/doc/Makefile	2006-02-17 11:51:06 UTC (rev 9)
@@ -0,0 +1,84 @@
+TEXFILES=$(wildcard *.tex)
+BASES=$(basename $(TEXFILES))
+DVIFILES=$(addsuffix .dvi, $(BASES))
+PDFFILES=$(addsuffix .pdf, $(BASES))
+PSPDFFILES=$(addsuffix .ps.pdf, $(BASES))
+PDFPSFILES=$(addsuffix .pdf.ps, $(BASES))
+G3FILES=$(addsuffix .g3, $(BASES))
+AUXFILES=$(addsuffix .aux, $(BASES))
+LOGFILES=$(addsuffix .log, $(BASES))
+TOCFILES=$(addsuffix .toc, $(BASES))
+PSFILES=$(addsuffix .ps, $(BASES))
+PRINTS=$(addprefix print-, $(BASES))
+WORKFILES=$(wildcard *~) $(wildcard *.bak)
+RTFFILES=$(addsuffix .rtf, $(BASES))
+HTMLFILES=$(addsuffix .html, $(BASES))
+DJFILES=$(addsuffix .dj, $(BASES))
+PCLFILES=$(addsuffix .pcl, $(BASES))
+IDXFILES=$(addsuffix .idx, $(BASES))
+ILGFILES=$(addsuffix .ilg, $(BASES))
+INDFILES=$(addsuffix .ind, $(BASES))
+SNMFILES=$(addsuffix .snm, $(BASES))
+NAVFILES=$(addsuffix .nav, $(BASES))
+OUTFILES=$(addsuffix .out, $(BASES))
+CRUFTFILES=$(AUXFILES) $(LOGFILES) $(WORKFILES) $(TOCFILES) $(IDXFILES) $(INDFILES) $(ILGFILES) $(OUTFILES) $(SNMFILES) $(NAVFILES)
+OUTPUTFILES=$(PSFILES) $(PDFFILES) $(DVIFILES) $(HTMLFILES) $(RTFFILES) $(DJFILES) $(PCLFILES) $(PSPDFFILES) $(G3FILES) $(PDFPSFILES)
+DVIFLAGS=
+PDFFLAGS=
+PSFLAGS=
+all: alldvis allpdfs allpss
+alldvis: $(DVIFILES)
+allpdfs: $(PDFFILES)
+allpss: $(PSFILES)
+allprints: $(PRINTS)
+allrtfs: $(RTFFILES)
+allpspdfs: $(PSPDFFILES)
+allpdfpss: $(PDFPSFILES)
+allpsspecials: allpspdfs allpdfpss
+alldviview: $(addsuffix .view, $(DVIFILES))
+allpdfview: $(addsuffix .view, $(PDFFILES))
+svnsync:
+	rm -f foo
+	for i in $(CRUFTFILES) $(OUTPUTFILES); do echo $$i >> foo; done
+	svn ps svn:ignore -F foo .
+	rm -f foo
+%.dvi: %.tex
+	latex $< && latex $< 
+	-makeindex $(basename $<).idx
+	latex $(DVIFLAGS) $<
+%.aux: %.tex
+	latex $<
+%.pdf: %.tex
+	pdflatex $< && pdflatex $< 
+	-makeindex $(basename $<).idx
+	pdflatex $(PDFFLAGS) $< 
+%.ps.pdf: %.ps
+	ps2pdf $< $@
+%.pdf.ps: %.pdf
+	pdf2ps $< $@
+%.ps: %.dvi
+	dvi2ps $(PSFLAGS) $< > $@
+%.dj: %.ps
+	gs -sDEVICE=DJ9xx -sOutputFile=$@ -dNOPAUSE -dBATCH $<
+%.pcl: %.ps
+	gs -sDEVICE=ljet3 -sOutputFile=$@ -dNOPAUSE -dBATCH $<
+%.g3: %.ps
+	gs -sDEVICE=dfaxlow -sOutputFile=$@ -dNOPAUSE -dBATCH $<
+%.rtf: %.tex
+	latex2rtf -o $@ $<
+%.print: %.ps
+	lpr $<
+%.dvi.view: %.dvi
+	xdvi $<
+%.pdf.view: %.pdf
+	xpdf $<
+%.ps.view: %.ps
+	gv $<
+%.pdf.beam: %.pdf
+	xpdf -fullscreen $<
+all-%: %.tex %.ps %.pdf %.dj %.rtf %.dvi
+clean: cruftclean
+	rm -f $(OUTPUTFILES)
+cruftclean:
+	rm -f $(CRUFTFILES)
+.PHONY: alldvis allpdfs allpss allprints all clean cruftclean

Added: trunk/doc/prm.tex
===================================================================
--- trunk/doc/prm.tex	2006-02-17 11:50:05 UTC (rev 8)
+++ trunk/doc/prm.tex	2006-02-17 11:51:06 UTC (rev 9)
@@ -0,0 +1,168 @@
+\documentclass{article}
+\usepackage[american]{babel}
+\usepackage[latin1]{inputenc}
+\usepackage{textcomp}
+\usepackage{textcomp}
+\parskip=1ex
+\parindent=0pt
+\usepackage{geometry}
+%\geometry{top=2.5cm,bottom=2.5cm,left=2cm,right=2cm}
+\newcommand{\reg}{\textsuperscript{\textregistered}}
+\newcommand{\tm}{\textsuperscript{TM}}
+\newcommand{\opcode}[1]{\subsubsection*{OPCODE: #1}}
+\begin{document}
+\title{Programmer's Reference Manual addendum for the CF/68 environment}
+\author{Wouter Verhelst}
+\maketitle
+\begin{abstract}
+This document discusses the technical implementation of the CF/68
+environment, pointing out possible pitfalls a programmer could run into
+when trying to write assembly code that will run on all hardware
+supported by the CF/68 environment. It is not, nor does it try to be, a
+complete reference manual; for full information on what every discussed
+opcode does, please see the document ``ColdFire\reg Family Programmer's
+Reference Manual'', which can be downloaded from the Freescale\tm
+website.
+\end{abstract}
+\tableofcontents
+\newpage
+\section{Introduction}
+\subsection{What is CF/68?}
+The CF/68 environment is a special computing platform in that no
+hardware exists which implements its instruction set as it is defined in
+this document, and nothing more. Instead, the environment is defined as
+the common subset of ColdFire and classic 680x0 hardware.
+
+To understand the reasons for this, a bit of computing history is
+necessary.
+
+In the late 1980s and early 1990s, Motorola's 680x0 processor family,
+also known as `m68k', was one of the more popular processor families,
+used not only in the Apple Macintosh, but also in several home computer
+models by Commodore, Atari, and others. However, halfway the 1990s
+Apple, IBM and Motorola cooperated on a new processor design, the
+PowerPC, which was to replace the m68k processor in the computers made
+by Apple. Because Apple was the main user of the m68k processor, and the
+other m68k-using computers had lost a lot of popularity by that time,
+the m68k family was no longer developed at that point.
+
+However, the design was not entirely thrown away. The m68k instruction
+set is a very clean one, and rather easy to learn; as such, it had
+always been popular with embedded developers. For that reason, Motorola
+decided to base two new processor families on the m68k design; one was
+the DragonBall\tm line (which is now defunct); the other was the
+ColdFire line. Now, about a decade later, the ColdFire processors are
+still being produced, in a design that still shares much with the m68k
+processor family.
+
+The ColdFire is not entirely compatible with classic m68k processors.
+While creating the ColdFire line, Motorola threw out a slew of opcodes
+and addressing modes that were not used all that often on classic m68k
+hardware anyway, and generally revisited the instruction set so that the
+ColdFire design is now a RISC design, rather than the classic m68k one
+which is more of a CISC design. Also, as most embedded controllers do
+not need to do many floating point operations, the FPU unit lost some of
+its precision. Additionally, the ColdFire did not have a Memory
+Management Unit; little embedded applications have a need for that
+anyway, so adding it to the design wouldn't be of much use anyway.
+
+Meanwhile, there has been an m68k Linux\reg port since the early days of the
+Linux\reg kernel. Initially, it was started while the hardware was still
+recent; and while its popularity declined when the design was getting
+more and more outdated, a few fanatics remained active. A port of
+Debian, one of the first non-profit GNU/Linux\reg distritbutions, was kept
+alive. There were ports of the NetBSD system to some m68k-based systems.
+Unfortunately, while the ColdFire processors were faster than the
+classic and outdated m68k hardware, they could not be used because of
+the lack of MMU hardware which is an absolute requirement for a
+UNIX-like operating system, such as Debian or NetBSD\footnote{While
+there is, and always has been, a Linux\reg port for ColdFire processors,
+there is a difference between a working Linux kernel and a working Linux
+distribution. It is possible to create a working kernel for embedded
+purposes on hardware without an MMU; but it is impossible to create a
+comfortable port of a Linux distribution like Debian without an MMU.}.
+
+Somewhere during the first few years of the new millennium, Motorola,
+which renamed themselves to Freescale\tm, produced a new ColdFire
+processor class which did incorporate an MMU, thus opening up the
+possibility of porting Debian and NetBSD to this hardware. In an effort
+to not let current m68k users remain in the cold, the Debian people
+decided to modify the port so that the same user-mode binaries would run
+on both m68k and ColdFire hardware; and that is where this effort comes
+from.
+
+The CF/68 environment is what the Debian/m68k developers are creating to
+make such a situation, where the same binaries would run on both classic
+and coldfire hardware, possible. However, due to the ten years of
+difference between the classic m68k processors on the one side, and the
+ColdFire-with-MMU processors on the other side, this compatibility is
+limited to the \emph{user mode} programming model. The differences in
+supervisor mode are too large to make this possible, with no common
+supervisor registers existing, and almost no common instructions.
+
+\subsection{Problems}
+The ColdFire processor, as discussed above, has an instruction set that
+is similar to the m68k one; however, it is sufficiently different to be
+able to call it a different processor altogether. First, the differences
+in the FPU are pretty severe, so that \ldots
+
+\section{Definitions}
+When this manual speaks of \emph{ColdFire}, it means any processor from
+the ColdFire V4e family; specifically, at this point in time, these are
+the 5470, 5471, 5472, 5473, 5474, 5475, 5480, 5481, 5482, 5483, 5484,
+and 5485 processors.
+
+When this manual speaks of \emph{68k}, \emph{m68k}, or \emph{classic
+m68k}, it is talking about any of the classic m68k processors that are
+supported by this platform; specifically, the 68020, 68030, 68040,
+68060, and any of their variants that include an MMU.
+
+When this manual speaks of \emph{portable}, it is talking about code
+that uses only opcodes common to both platforms, and that makes no
+assumptions about the hardware unless this manual says it can safely do
+so.
+
+When this manual speaks of \emph{non-portable}, it is talking about any
+code that is not portable code.
+
+When this manual speaks of \emph{safe} or \emph{defined}, it is talking
+about data or instruction results that can be predicted without
+knowledge of the platform the code is running on.
+
+When this manual speaks of \emph{unsafe}, it means that an instruction
+has different results on m68k hardware and ColdFire hardware, but that,
+provided one does not try to use the results or the data in between, it
+is possible to return to a defined state somehow\footnote{possibly
+within a defined error margin, in the case of FPU differences}.
+
+When this manual speaks of \emph{undefined}, it means that an
+instruction has different results on m68k hardware and ColdFire
+hardware, and that it is \emph{not} possible, using only portable code,
+to revert to a defined state. It \emph{may} be possible to revert to a
+defined state by using conditional branches (where one branch is
+executed on ColdFire, and another branch on 68k), but it is assumed that
+such a branch is not used.
+\section{Differences}
+\subsection{FPU differences}
+The ColdFire FPU comes with 64-bit FPU registers, while the m68k FPU has
+80-bit registers. As a result, the precision of the ColdFire FPU is
+limited to the ``double'' data type, whereas the m68k can handle ``long
+double'' data. Portable code should thus never make any assumptions about the
+length of the FPU registers.
+
+What follows is a list of problematic FPU opcodes with an explanation of how,
+exactly, they are problematic.
+\opcode{FMOVEM}
+The FMOVEM opcode is \emph{unsafe}, when one tries to copy data from FPU
+registers to RAM. The problem is that it copies data from the FPU
+registers without doing any data conversion. The result is that the
+instruction overwrites 10 bytes (80 bits) on m68k, while it overwrites 8
+bytes (64 bits) on ColdFire.
+
+The instruction is \emph{unsafe} (and not \emph{undefined}) because it
+can also be used to copy data from RAM back to the FPU registers in the
+same manner; thus, portable code can use the FMOVEM instruction to store
+the FPU state on the stack during a function call, and to restore it
+when the function call finishes. Any other use of the instruction---any
+use that includes reading the data in between---is \emph{undefined}.
+\end{document}