-
Notifications
You must be signed in to change notification settings - Fork 10
/
chapter-introduction.tex
186 lines (112 loc) · 16 KB
/
chapter-introduction.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
\chapter{Introduction}
% ████████████████████████████████████████████████████████████████████████████████████
% █░░░░░░░░░░█░░░░░░██████████░░░░░░█░░░░░░░░░░░░░░█░░░░░░░░░░░░░░░░███░░░░░░░░░░░░░░█
% █░░▄▀▄▀▄▀░░█░░▄▀░░░░░░░░░░██░░▄▀░░█░░▄▀▄▀▄▀▄▀▄▀░░█░░▄▀▄▀▄▀▄▀▄▀▄▀░░███░░▄▀▄▀▄▀▄▀▄▀░░█
% █░░░░▄▀░░░░█░░▄▀▄▀▄▀▄▀▄▀░░██░░▄▀░░█░░░░░░▄▀░░░░░░█░░▄▀░░░░░░░░▄▀░░███░░▄▀░░░░░░▄▀░░█
% ███░░▄▀░░███░░▄▀░░░░░░▄▀░░██░░▄▀░░█████░░▄▀░░█████░░▄▀░░████░░▄▀░░███░░▄▀░░██░░▄▀░░█
% ███░░▄▀░░███░░▄▀░░██░░▄▀░░██░░▄▀░░█████░░▄▀░░█████░░▄▀░░░░░░░░▄▀░░███░░▄▀░░██░░▄▀░░█
% ███░░▄▀░░███░░▄▀░░██░░▄▀░░██░░▄▀░░█████░░▄▀░░█████░░▄▀▄▀▄▀▄▀▄▀▄▀░░███░░▄▀░░██░░▄▀░░█
% ███░░▄▀░░███░░▄▀░░██░░▄▀░░██░░▄▀░░█████░░▄▀░░█████░░▄▀░░░░░░▄▀░░░░███░░▄▀░░██░░▄▀░░█
% ███░░▄▀░░███░░▄▀░░██░░▄▀░░░░░░▄▀░░█████░░▄▀░░█████░░▄▀░░██░░▄▀░░█████░░▄▀░░██░░▄▀░░█
% █░░░░▄▀░░░░█░░▄▀░░██░░▄▀▄▀▄▀▄▀▄▀░░█████░░▄▀░░█████░░▄▀░░██░░▄▀░░░░░░█░░▄▀░░░░░░▄▀░░█
% █░░▄▀▄▀▄▀░░█░░▄▀░░██░░░░░░░░░░▄▀░░█████░░▄▀░░█████░░▄▀░░██░░▄▀▄▀▄▀░░█░░▄▀▄▀▄▀▄▀▄▀░░█
% █░░░░░░░░░░█░░░░░░██████████░░░░░░█████░░░░░░█████░░░░░░██░░░░░░░░░░█░░░░░░░░░░░░░░█
% ████████████████████████████████████████████████████████████████████████████████████
\ChapterTOC[] % don't apply default style for introduction (we want to keep using the simple style without headers)
\section{Where to get this document}
\BookTitle ~is available as coil bound printed book on
\url{https://bit.ly/zx-next-assembly-dev-guide}
You can also download it as PDF document from GitHub where you can also find its source \LaTeX ~form so you can edit it to your preference
\url{https://github.com/tomaz/zx-next-dev-guide}
\section{Companion Source Code}
GitHub repository also includes companion source code. Sample projects were created in a cross-platform environment on Windows so instructions on the following page are written with these in mind. All programs mentioned are available on Linux and macOS; you should be able to run everything on those platforms too, but likely with some deviations. Regardless, these are merely suggestions, you should be able to use your preferred editor or tools.
\pagebreak % we want list of all tools and software to be on the same page
\begin{description}[style=unboxed,leftmargin=0cm]
\item[Visual Studio Code (\url{https://code.visualstudio.com/})]\hfill
My code editor of choice! I use it with the following plugins:
\begin{description}[topsep=1pt,labelindent=2em,leftmargin=2em]
\item[DeZog plugin (\url{https://github.com/maziac/DeZog})]\hfill
Essential plugin; features list is too large to even attempt to enumerate here but essentially turns VS Code into a fully-fledged debugging environment.
\item[Z80 Macro-Assembler (\url{https://github.com/mborik/z80-macroasm-vscode})]\hfill
Another must-have plugin for the Z80 assembly developer; syntax highlighting, code formatting and code completion, renaming etc.
\item[Z80 Instruction Set (\url{https://github.com/maziac/z80-instruction-set})]\hfill
Adds mouse hover action above any Z80N instruction for quick info.
\item[Z80 Assembly meter (\url{https://github.com/theNestruo/z80-asm-meter-vscode})]\hfill
Shows the sum of clock cycles and machine code bytes for all instructions in the current selection.
\end{description}
\item[sjasmplus 1.18.2 (\url{https://github.com/z00m128/sjasmplus})]\hfill
Source code includes sjasmplus specific directives for creating {\tt nex} files at the top and bottom of {\tt main.asm} files; if you use a different compiler, you may need to tweak or comment them out.
VS Code projects are set up to expect binaries in a specific folder. You will need to download and copy so that {\tt sjasmplus.exe} is located in {\tt Tools/sjasmplus}.
\item[CSpect 2.13.0 (\url{http://cspect.org})]\hfill
Similar to sjasmplus, CSpect binaries are expected in a specific folder. To install, download and copy so that {\tt CSpect.exe} is located in {\tt Tools/CSpect} folder.
\item[CSpect Next Image (\url{http://www.zxspectrumnext.online/\#sd})]\hfill
You will also need to download the ZX Spectrum Next image file and copy it to the folder where {\tt CSpect.exe} is located. I use a 2GB image, hence VS Code project file is configured for that. If you use a different image, make sure to update {\tt .vscode/tasks.json} file.
\item[DeZog CSpect plugin (\url{https://github.com/maziac/DeZogPlugin})]\hfill
DeZog requires this plugin to be installed to work with CSpect. To install, download and copy to the same folder where {\tt CSpect.exe} is located. Make sure the plugin version matches the DeZog version!
\end{description}
{
\footnotesize
\begin{description}[topsep=1pt,itemsep=1pt,labelindent=0pt,leftmargin=0pt]
\item[Note:] you need to have CSpect launched before you can run the samples. I created couple tasks\footnotemark~for it: open VS Code command palette ({\tt Ctrl+Shift+P} shortcut on my installation) and select \textit{Tasks: Run Task} option, then select \textit{Launch CSpect} from list. This is only needed once. Afterwards, use \textit{Run \textgreater ~Start Debugging} from the main menu to compile and launch the program.
\item[Note:] default DeZog port of 11000 doesn't work on my computer, so I changed it to 13000. This needs to be managed in 2 places: {\tt .vscode/launch.json} and on the plugin side. Companion code repository already includes the setup needed, including {\tt DeZogPlugin.dll.config} file, so it should work out of the box.
\item[Note:] sample projects are ready for ZEsarUX as well, select the option from debugging panel in VS Code.
\end{description}
}
\footnotetext{
Workspace tasks seem to not be supported in some later VS Code versions. If this is the case for you, copy them to user tasks (shared between projects): open {\tt .vscode/tasks.json} file from any of the sample projects, scroll down a little and copy {\tt Launch CSpect} and {\tt Launch ZEsarUX} tasks to user tasks. You can do this all from within VS Code. To open the user tasks file, open the command palette and start typing {\tt open user tasks}, then select the option from the drop-down menu.
}
\pagebreak % we want next section to be on its own page, fully visible when listing physical book
\section{Background, Contact \& Feedback}
My first computer was ZX Spectrum 48K. Initially, it was only used to play games, but my creative mind soon set me on the path of building simple games of my own in BASIC. While too young to master assembler at that point, the idea stayed with me. ZX Spectrum Next revived my wish to learn Z80 and return to writing games for the platform.
My original intent was to have coil bound list of all ZX Next instructions so I can quickly compare. However, after finding Z80 Undocumented online, it felt like a perfect starting point. And with additional information included, it also encouraged me to extend the mere instructions list with the Next specific chapters. In a way, this book represents my notes as I was learning those topics. That being said, I did my best to present information as a reference to keep the book relevant.
During the process, I wanted to tweak or unify the look of various elements. For example instruction tables. Original \LaTeX ~code required applying changes to each and every instance. As \LaTeX ~is all but a programming language, I extracted individual elements into reusable commands which allowed me to tweak appearance in a single place and apply it to the whole document. I also converted almost all drawings from {\tt picture} to {\tt tikz} as it's far more adaptable. With this, I almost completely restructured the original \LaTeX ~code. While this took a lot of time and effort, it allowed me to quickly iterate later on. I really love this aspect of \LaTeX!
English is not my native tongue. And our mind is not the best tool to correct our own work either. Since I can't afford a professional proofreader, mistakes are a matter of fact I'm afraid. If you spot something or want to contribute, feel free to open an issue on GitHub. Pull requests are also welcome! If you want to contribute, but are unsure of what, check the accompanying readme file on GitHub for ideas. If you want to discuss in advance, or for anything else, you can find me on email \email{tkragelj}{gmail}{com} or Twitter {\tt @tomsbarks}.
That being said, I hope you'll enjoy reading this document as much as I did writing it!
Sincerely, \AuthorName
\pagebreak
\section{Z80 Undocumented}
As the saying ``standing on the shoulders of giants'' goes, this book is also based on pre-existing work from Jan and Sean. While my work is ZX Spectrum Next developer-oriented, their original project was more focused on hardware perspective, for Z80 emulator developers.
If interested, you can find it at \url{http://www.myquest.nl/z80undocumented/}.
\begin{description}[style=unboxed,leftmargin=0cm]
\item[Jan]\hfill
\url{http://www.myquest.nl/z80undocumented/}\\
Email \email{jw}{dds}{nl}\\
Twitter \twitter{janwilmans}
Interested in emulation for a long time, but a few years after Sean started writing this document, I have also started writing my own MSX emulator in 2003 and I've used this document quite a lot. Now (2005) the Z80 emulation is nearing perfection, I decided to add what extra I have learned and comments various people have sent to Sean, to this document.
I have restyled the document (although very little) to fit my personal needs and I have checked a lot of things that were already in here.
\item[Sean]\hfill
\url{http://www.msxnet.org/}
Ever since I first started working on an MSX emulator, I've been very interested in getting the emulation absolutely correct - including the undocumented features. Not just to make sure that all games work, but also to make sure that if a program crashes, it crashes exactly the same way if running on an emulator as on the real thing. Only then is perfection achieved.
I set about collecting information. I found pieces of information on the Internet, but not everything there is to know. So I tried to fill in the gaps, the results of which I put on my website. Various people have helped since then; this is the result of all those efforts and to my knowledge, this document is the most complete.
\end{description}
\pagebreak
\section{ChangeLog}
\begin{description}
% when adding versions:
% 1. replace `\LatestRevisionName` with value from macro definition in `defines.tex`
% 2. update `\LatestRevisionName` with new value in `defines.tex`
% 3. create new entry here using now updated values (copy item definition from previous version)
\item[\LatestRevisionName]
Corrections, updates and improvements. Main focus on making instruction up close chapter more useful. Each instruction now includes description of effects on flags and where makes sense, includes additional description or code examples.
\item[\RevisionTwoName]
Corrections and updates based on community comments - with special thanks to Peter Ped Helcmanovsky and Alvin Albrecht. Restructured and updated many ZX Next chapters: added sample code to ports, completely restructured memory map and paging, added new palette chapter including 9-bit palette handling, updated ULA with shadow screen info and added Next extended keyboard, DMA, Copper and Hardware IM2 sections. Other than some cosmetic changes: redesigned title, copyright pages etc. Also, many behind the scenes improvements like splitting previous huge single \LaTeX~ file into multiple per-chapter/section. This is not only more manageable but can also compile much faster.
\item[\RevisionOneName]
Added ZX Spectrum Next information and instructions and restructured text for better maintainability and readability.
\item[18 September 2005]
Corrected a textual typo in the R register and memory refresh section, thanks to David Aubespin. Corrected the contradiction in the {\tt DAA} section saying the \FlagNF{} flag was both affected and unchanged :) thanks to Dan Meir. Added an error in official documentation about the way Interrupt Mode 2 works, thanks to Aaldert Dekker.
\item[15 June 2005]
Corrected improper notation of {\tt JP x,nn} mnemonics in opcode list, thanks to Laurens Holst. Corrected a mistake in the {\tt INI}, {\tt INIR}, {\tt IND}, {\tt INDR} section and documented a mistake in official Z80 documentation concerning Interrupt Mode 2, thanks to Boris Donko. Thanks to Aaldert Dekker for his ideas, for verifying many assumptions and for writing instruction exercisers for various instruction groups.
\item[18 May 2005]
Added an alphabetical list of instructions for easy reference and corrected an error in the 16-bit arithmetic section, {\tt SBC HL,nn} sets the NF flag just like other subtraction instructions, thanks to Fredrik Olssen for pointing that out.
\item[4 April 2005]
I (Jan \email{jw}{dds}{nl}) will be maintaining this document from this version on. I restyled the document to fix the page numbering issues, corrected an error in the I/O Block Instructions section, added graphics for the {\tt RLD} and {\tt RRD} instructions and corrected the spelling in several places.
\item[20 November 2003]
Again, thanks to Ramsoft, added PV flag to {\tt OUTI}, {\tt INI} and friends. Minor fix to {\tt DAA} tables, other minor fixes.
\item[13 November 2003]
Thanks to Ramsoft, add the correct tables for the {\tt DAA} instruction (section \XRef{z80_undocumented_instruction_daa}). Minor corrections \& typos, thanks to Jim Battle, David Sutherland and most of all Fred Limouzin.
\item[September 2001]
Previous documents I had written were in plain text and Microsoft Word, which I now find very embarrassing, so I decided to combine them all and use {\LaTeX}. Apart from a full re-write, the only changed information is ``Power on defaults'' (section \XRef{z80_power_on_defaults}) and the algorithm for the CF and HF flags for {\tt OTIR} and friends (section \XRef{z80_undocumented_instructions_io_block}).
\end{description}
\pagebreak
\IntentionallyEmpty
\pagebreak