mirror of https://github.com/mnaberez/py65.git
Added Sphinx-based documentation.
This commit is contained in:
Mike Naberezny
parent
17b33d0105
commit
e1aa881e4c
|
|
@ -0,0 +1,75 @@
|
|||
# Makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line.
|
||||
SPHINXOPTS =
|
||||
SPHINXBUILD = sphinx-build
|
||||
PAPER =
|
||||
|
||||
# Internal variables.
|
||||
PAPEROPT_a4 = -D latex_paper_size=a4
|
||||
PAPEROPT_letter = -D latex_paper_size=letter
|
||||
ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
|
||||
|
||||
.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
|
||||
|
||||
help:
|
||||
@echo "Please use \`make <target>' where <target> is one of"
|
||||
@echo " html to make standalone HTML files"
|
||||
@echo " pickle to make pickle files"
|
||||
@echo " json to make JSON files"
|
||||
@echo " htmlhelp to make HTML files and a HTML help project"
|
||||
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
|
||||
@echo " changes to make an overview over all changed/added/deprecated items"
|
||||
@echo " linkcheck to check all external links for integrity"
|
||||
|
||||
clean:
|
||||
-rm -rf build/*
|
||||
|
||||
html:
|
||||
mkdir -p build/html build/doctrees
|
||||
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
|
||||
@echo
|
||||
@echo "Build finished. The HTML pages are in build/html."
|
||||
|
||||
pickle:
|
||||
mkdir -p build/pickle build/doctrees
|
||||
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
|
||||
@echo
|
||||
@echo "Build finished; now you can process the pickle files."
|
||||
|
||||
web: pickle
|
||||
|
||||
json:
|
||||
mkdir -p build/json build/doctrees
|
||||
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) build/json
|
||||
@echo
|
||||
@echo "Build finished; now you can process the JSON files."
|
||||
|
||||
htmlhelp:
|
||||
mkdir -p build/htmlhelp build/doctrees
|
||||
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
|
||||
@echo
|
||||
@echo "Build finished; now you can run HTML Help Workshop with the" \
|
||||
".hhp project file in build/htmlhelp."
|
||||
|
||||
latex:
|
||||
mkdir -p build/latex build/doctrees
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
|
||||
@echo
|
||||
@echo "Build finished; the LaTeX files are in build/latex."
|
||||
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
|
||||
"run these through (pdf)latex."
|
||||
|
||||
changes:
|
||||
mkdir -p build/changes build/doctrees
|
||||
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
|
||||
@echo
|
||||
@echo "The overview file is in build/changes."
|
||||
|
||||
linkcheck:
|
||||
mkdir -p build/linkcheck build/doctrees
|
||||
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
|
||||
@echo
|
||||
@echo "Link check complete; look for any errors in the above output " \
|
||||
"or in build/linkcheck/output.txt."
|
||||
|
|
@ -0,0 +1,187 @@
|
|||
# -*- coding: utf-8 -*-
|
||||
#
|
||||
# test documentation build configuration file, created by
|
||||
# sphinx-quickstart on Sun Nov 30 14:39:06 2008.
|
||||
#
|
||||
# This file is execfile()d with the current directory set to its containing dir.
|
||||
#
|
||||
# The contents of this file are pickled, so don't put values in the namespace
|
||||
# that aren't pickleable (module imports are okay, they're removed automatically).
|
||||
#
|
||||
# All configuration values have a default; values that are commented out
|
||||
# serve to show the default.
|
||||
|
||||
import sys, os
|
||||
|
||||
# If your extensions are in another directory, add it here. If the directory
|
||||
# is relative to the documentation root, use os.path.abspath to make it
|
||||
# absolute, like shown here.
|
||||
#sys.path.append(os.path.abspath('.'))
|
||||
|
||||
# General configuration
|
||||
# ---------------------
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be extensions
|
||||
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
||||
extensions = ['sphinx.ext.autodoc']
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['.templates']
|
||||
|
||||
# The suffix of source filenames.
|
||||
source_suffix = '.rst'
|
||||
|
||||
# The encoding of source files.
|
||||
#source_encoding = 'utf-8'
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
# General information about the project.
|
||||
project = u'Py65'
|
||||
copyright = u'2008, Mike Naberezny'
|
||||
|
||||
# The version info for the project you're documenting, acts as replacement for
|
||||
# |version| and |release|, also used in various other places throughout the
|
||||
# built documents.
|
||||
#
|
||||
# The short X.Y version.
|
||||
version = '0.3'
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = '0.3'
|
||||
|
||||
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||
# for a list of supported languages.
|
||||
#language = None
|
||||
|
||||
# There are two options for replacing |today|: either, you set today to some
|
||||
# non-false value, then it is used:
|
||||
#today = ''
|
||||
# Else, today_fmt is used as the format for a strftime call.
|
||||
#today_fmt = '%B %d, %Y'
|
||||
|
||||
# List of documents that shouldn't be included in the build.
|
||||
#unused_docs = []
|
||||
|
||||
# List of directories, relative to source directory, that shouldn't be searched
|
||||
# for source files.
|
||||
exclude_trees = []
|
||||
|
||||
# The reST default role (used for this markup: `text`) to use for all documents.
|
||||
#default_role = None
|
||||
|
||||
# If true, '()' will be appended to :func: etc. cross-reference text.
|
||||
#add_function_parentheses = True
|
||||
|
||||
# If true, the current module name will be prepended to all description
|
||||
# unit titles (such as .. function::).
|
||||
#add_module_names = True
|
||||
|
||||
# If true, sectionauthor and moduleauthor directives will be shown in the
|
||||
# output. They are ignored by default.
|
||||
#show_authors = False
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
pygments_style = 'sphinx'
|
||||
|
||||
|
||||
# Options for HTML output
|
||||
# -----------------------
|
||||
|
||||
# The style sheet to use for HTML and HTML Help pages. A file of that name
|
||||
# must exist either in Sphinx' static/ path, or in one of the custom paths
|
||||
# given in html_static_path.
|
||||
html_style = 'default.css'
|
||||
|
||||
# The name for this set of Sphinx documents. If None, it defaults to
|
||||
# "<project> v<release> documentation".
|
||||
#html_title = None
|
||||
|
||||
# A shorter title for the navigation bar. Default is the same as html_title.
|
||||
#html_short_title = None
|
||||
|
||||
# The name of an image file (relative to this directory) to place at the top
|
||||
# of the sidebar.
|
||||
#html_logo = None
|
||||
|
||||
# The name of an image file (within the static path) to use as favicon of the
|
||||
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
|
||||
# pixels large.
|
||||
#html_favicon = None
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ['.static']
|
||||
|
||||
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
|
||||
# using the given strftime format.
|
||||
#html_last_updated_fmt = '%b %d, %Y'
|
||||
|
||||
# If true, SmartyPants will be used to convert quotes and dashes to
|
||||
# typographically correct entities.
|
||||
#html_use_smartypants = True
|
||||
|
||||
# Custom sidebar templates, maps document names to template names.
|
||||
#html_sidebars = {}
|
||||
|
||||
# Additional templates that should be rendered to pages, maps page names to
|
||||
# template names.
|
||||
#html_additional_pages = {}
|
||||
|
||||
# If false, no module index is generated.
|
||||
#html_use_modindex = True
|
||||
|
||||
# If false, no index is generated.
|
||||
#html_use_index = True
|
||||
|
||||
# If true, the index is split into individual pages for each letter.
|
||||
#html_split_index = False
|
||||
|
||||
# If true, the reST sources are included in the HTML build as _sources/<name>.
|
||||
#html_copy_source = True
|
||||
|
||||
# If true, an OpenSearch description file will be output, and all pages will
|
||||
# contain a <link> tag referring to it. The value of this option must be the
|
||||
# base URL from which the finished HTML is served.
|
||||
#html_use_opensearch = ''
|
||||
|
||||
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
|
||||
#html_file_suffix = ''
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = 'testdoc'
|
||||
|
||||
|
||||
# Options for LaTeX output
|
||||
# ------------------------
|
||||
|
||||
# The paper size ('letter' or 'a4').
|
||||
#latex_paper_size = 'letter'
|
||||
|
||||
# The font size ('10pt', '11pt' or '12pt').
|
||||
#latex_font_size = '10pt'
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title, author, document class [howto/manual]).
|
||||
latex_documents = [
|
||||
('index', 'test.tex', ur'test Documentation',
|
||||
ur'foo', 'manual'),
|
||||
]
|
||||
|
||||
# The name of an image file (relative to this directory) to place at the top of
|
||||
# the title page.
|
||||
#latex_logo = None
|
||||
|
||||
# For "manual" documents, if this is true, then toplevel headings are parts,
|
||||
# not chapters.
|
||||
#latex_use_parts = False
|
||||
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
#latex_preamble = ''
|
||||
|
||||
# Documents to append as an appendix to all manuals.
|
||||
#latex_appendices = []
|
||||
|
||||
# If false, no module index is generated.
|
||||
#latex_use_modindex = True
|
||||
|
|
@ -0,0 +1,361 @@
|
|||
***********************************************
|
||||
Py65 - 6502 Microprocessor Simulation in Python
|
||||
***********************************************
|
||||
|
||||
:Author: Mike Naberezny
|
||||
:Version: |version|
|
||||
|
||||
.. topic:: Overview
|
||||
|
||||
Py65 is a simulation of the original NMOS 6502 microprocessor from MOS
|
||||
Technology, written in Python.
|
||||
|
||||
Using the Monitor
|
||||
=================
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
Py65 includes a program called Py65Mon that functions as a machine language
|
||||
monitor. This kind of program is sometimes also called a debugger. Py65Mon
|
||||
provides a command line with many convenient commands for interacting with the
|
||||
simulated 6502-based system.
|
||||
|
||||
The monitor is started using the ``py65mon`` command::
|
||||
|
||||
$ py65mon
|
||||
|
||||
Py65 Monitor
|
||||
|
||||
<6502: A=00, X=00, Y=00, Flags=20, SP=ff, PC=0000>
|
||||
.
|
||||
|
||||
Once the monitor has started, it will display a register dump and the
|
||||
dot prompt. You can then enter commands for the monitor at this prompt.
|
||||
|
||||
Py65Mon uses commands that are very similar to those used by the monitor
|
||||
included with the `VICE emulator <http://viceteam.org>`_ for Commodore
|
||||
computers. You can get a list of available commands with ``help`` or
|
||||
help on a specific command with ``help command``.
|
||||
|
||||
Number Systems
|
||||
--------------
|
||||
|
||||
When working with Py65Mon, you will frequently need to enter numbers, addresses,
|
||||
and ranges of addresses. Almost all Py65 command support entering numbers in
|
||||
binary, decimal, and hexadecimal.
|
||||
|
||||
Numbers can be entered with a prefix to specify the radix, e.g. ``$c000``
|
||||
instructs Py65Mon that the number ``c000`` is hexadecimal. The following
|
||||
prefixes are supported:
|
||||
|
||||
- ``$c000``: The dollar sign indicates hexadecimal.
|
||||
- ``+828``: The plus sign indicates decimal.
|
||||
- ``%0101``: The percent sign indicates binary.
|
||||
|
||||
Numbers can also be entered without a prefix. Most of the time, working in
|
||||
hexadecimal will be the most convenient so this is the default radix. The
|
||||
number ``c000`` will be assumed to be hexadecimal unless the default radix
|
||||
is changed using the ``radix`` command.
|
||||
|
||||
Address Ranges
|
||||
--------------
|
||||
|
||||
Some commands accept a range of memory addresses::
|
||||
|
||||
.disassemble ff80:ff84
|
||||
$ff80 d8 CLD
|
||||
$ff81 a2 ff LDX #$ff
|
||||
$ff83 9a TXS
|
||||
$ff84 a0 1c LDY #$1c
|
||||
|
||||
The syntax for a range is ``start:end``. Each of the two parts may have
|
||||
a prefix to indicate the radix, or no prefix to use the default radix.
|
||||
|
||||
Sometimes it is useful to have the starting and ending address in a range
|
||||
be the same, such as when you want to inspect a single byte of memory. In
|
||||
this case, you can enter ``ff80:ff80`` or simply ``ff80``.
|
||||
|
||||
Assigning Labels
|
||||
----------------
|
||||
|
||||
Large assembly language programs may have hundreds of procedures. It is
|
||||
difficult to remember the memory address of each procedure and the addresses
|
||||
may change if the program is reassembled.
|
||||
|
||||
You can add a label for any memory address using the ``add_label`` command.
|
||||
This label can then be used anywhere the address could be used::
|
||||
|
||||
.add_label ff80 start
|
||||
|
||||
.disassemble start
|
||||
$ff80 d8 CLD
|
||||
|
||||
When using labels, you can also specify an offset (plus or minus)::
|
||||
|
||||
.disassemble start:start+4
|
||||
$ff80 d8 CLD
|
||||
$ff81 a2 ff LDX #$ff
|
||||
$ff83 9a TXS
|
||||
$ff84 a0 1c LDY #$1c
|
||||
|
||||
Offsets are interpreted like any other numbers. In the example above,
|
||||
``start+4`` implies that the offset (``4``) uses the default radix. This
|
||||
could also be written as ``start+$04`` for explicit hexadecimal.
|
||||
|
||||
Command Reference
|
||||
=================
|
||||
|
||||
.. describe:: add_label <address> <label>
|
||||
|
||||
Assign a label to an address::
|
||||
|
||||
.add_label f000 start
|
||||
|
||||
Once defined, the label may be used in place of the address in other
|
||||
commands. If a label already exists at the address, it will be silently
|
||||
overwritten.
|
||||
|
||||
.. describe:: assemble <address> <statement>
|
||||
|
||||
Assemble a statement at the address::
|
||||
|
||||
.assemble c000 lda $a0,x
|
||||
$c000 b5 a0 LDA $a0,X
|
||||
|
||||
The assembler supports all legal NMOS 6502 opcodes and addressing modes. If
|
||||
you have defined labels with ``add_label``, you may use those labels in the
|
||||
address and the operand.
|
||||
|
||||
.. describe:: cd <path>
|
||||
|
||||
Change the current working directory to the path specified::
|
||||
|
||||
.cd /path/to/my/files
|
||||
/path/to/my/files
|
||||
|
||||
After changing the directory, the new working directory will be displayed.
|
||||
The default working directory is the directory from which the monitor was
|
||||
started.
|
||||
|
||||
.. describe:: cycles
|
||||
|
||||
Display the number of cycles that the microprocessor has run
|
||||
since it was last reset::
|
||||
|
||||
.cycles
|
||||
12
|
||||
|
||||
.. describe:: delete_label <label>
|
||||
|
||||
Delete a label that was previously defined with ``add_label``::
|
||||
|
||||
.delete_label foo
|
||||
|
||||
If the label does not exist, the command will fail silently.
|
||||
|
||||
.. describe:: disassemble <address_range>
|
||||
|
||||
Disassembles a range of memory. All legal NMOS 6502 opcodes and addressing
|
||||
modes are supported::
|
||||
|
||||
.disassemble ff80:ff84
|
||||
$ff80 d8 CLD
|
||||
$ff81 a2 ff LDX #$ff
|
||||
$ff83 9a TXS
|
||||
$ff84 a0 1c LDY #$1c
|
||||
|
||||
If labels have been defined, they will be substituted for
|
||||
addresses in the operands.
|
||||
|
||||
.. describe:: fill <address_range> <byte> [<byte> <byte> ...]
|
||||
|
||||
Fill a range of memory using one or more bytes from the list::
|
||||
|
||||
.fill c000:c003 aa bb
|
||||
Wrote +4 bytes from $c000 to $c003
|
||||
|
||||
.mem c000:c003
|
||||
c000: aa bb aa bb
|
||||
|
||||
If the range is larger than the number of bytes in the list, the list
|
||||
will repeat as shown above.
|
||||
|
||||
.. describe:: goto <address>
|
||||
|
||||
Set the program counter to an address and resume execution::
|
||||
|
||||
.goto c000
|
||||
|
||||
.. describe:: help [<command>]
|
||||
|
||||
Display help for all commands or a single command. If no command is
|
||||
given, a list of commands will be displayed::
|
||||
|
||||
.help
|
||||
|
||||
If a command is given, help for that comand is displayed::
|
||||
|
||||
.help disassemble
|
||||
disassemble <address_range>
|
||||
Disassemble instructions in the address range.
|
||||
|
||||
.. describe:: load <filename> <address>
|
||||
|
||||
Load a binary file into memory starting at the address specified::
|
||||
|
||||
.load hello.bin c000
|
||||
Wrote +29 bytes from $c000 to $c01c
|
||||
|
||||
The file will be loaded relative to the current working directory. You
|
||||
may also specify an absolute path. If the filename contains spaces, use
|
||||
quotes around it::
|
||||
|
||||
.load "say hello.bin" c000
|
||||
Wrote +29 bytes from $c000 to $c01c
|
||||
|
||||
.. note::
|
||||
|
||||
Unlike the VICE monitor, Py65Mon's ``load`` command does not expect
|
||||
the first two bytes to be a Commodore-style load address. It will start
|
||||
reading the file at byte 0, not byte 2.
|
||||
|
||||
.. describe:: mem <address_range>
|
||||
|
||||
Display the contents of memory an address range::
|
||||
|
||||
.mem ff80:ffa0
|
||||
ff80: d8 a2 ff 9a a0 1c b9 bb ff 99 04 02 88 d0 f7 b9 d8 ff
|
||||
ff92: f0 06 20 a6 e0 c8 d0 f5 20 a3 e0 90 fb 29 df
|
||||
|
||||
The contents will be wrapped to the terminal width specified by the
|
||||
``width`` command.
|
||||
|
||||
.. describe:: pwd
|
||||
|
||||
Display the current working directory::
|
||||
|
||||
.pwd
|
||||
/home/mnaberez
|
||||
|
||||
.. describe:: quit
|
||||
|
||||
Quit the monitor::
|
||||
|
||||
.quit
|
||||
|
||||
.. describe:: radix [<H|D|O|B>]
|
||||
|
||||
Display or set the default radix that is assumed for numbers that have no prefix.
|
||||
If no argument is given, the default radix is displayed::
|
||||
|
||||
.radix
|
||||
Default radix is Hexadecimal
|
||||
|
||||
If an argument is given, the default radix will be changed::
|
||||
|
||||
.radix d
|
||||
Default radix is Decimal
|
||||
|
||||
The default radix may be changed to Hexadecimal, Decimal, Octal, or Binary.
|
||||
|
||||
.. describe:: registers [<name=value>, <name=value>, ...>]
|
||||
|
||||
Display or change the registers of the microprocessor. If no arguments are
|
||||
given, the registers are displayed::
|
||||
|
||||
.registers
|
||||
|
||||
<6502: A=00, X=00, Y=00, Flags=20, SP=ff, PC=0000>
|
||||
|
||||
Registers can changed giving ``name=value``, separated by commas if
|
||||
multiple registers are to be changed::
|
||||
|
||||
.registers a=02, x=04
|
||||
|
||||
<6502: A=02, X=04, Y=00, Flags=20, SP=ff, PC=0000>
|
||||
|
||||
.. describe:: reset
|
||||
|
||||
Reset the microprocessor to its default state. All memory will
|
||||
also be cleared::
|
||||
|
||||
.reset
|
||||
|
||||
.. describe:: return
|
||||
|
||||
Continue execution and return to the monitor just before the next
|
||||
RTS or RTI is executed::
|
||||
|
||||
.return
|
||||
|
||||
.. describe:: show_labels
|
||||
|
||||
Display labels that have been defined with ``add_label``::
|
||||
|
||||
.show_labels
|
||||
ffd2: charout
|
||||
|
||||
.. describe:: step
|
||||
|
||||
Execute a single instruction at the program counter. After the instruction
|
||||
executes, the next instruction is disassembled and printed::
|
||||
|
||||
<6502: A=00, X=00, Y=00, Flags=34, SP=fc, PC=0000>
|
||||
.registers pc=c000
|
||||
|
||||
<6502: A=00, X=00, Y=00, Flags=34, SP=fc, PC=c000>
|
||||
.step
|
||||
$c002 a9 42 LDA #$42
|
||||
|
||||
<6502: A=00, X=00, Y=00, Flags=34, SP=fc, PC=c000>
|
||||
.
|
||||
|
||||
In the example above, the instruction at ``$C000`` executes and the monitor
|
||||
prompt returns.
|
||||
|
||||
.. note::
|
||||
|
||||
After the instruction executes, the disassembly of the **next** instruction
|
||||
is printed. This allows you to see what will be executed on the next step.
|
||||
|
||||
.. describe:: tilde
|
||||
|
||||
Display a number in the supported number systems::
|
||||
|
||||
.~ c000
|
||||
+49152
|
||||
$c000
|
||||
140000
|
||||
1100000000000000
|
||||
|
||||
The number will be displayed in this order: decimal, hexadecimal, octal,
|
||||
and then binary.
|
||||
|
||||
.. describe:: version
|
||||
|
||||
Display version information::
|
||||
|
||||
.version
|
||||
|
||||
Py65 Monitor
|
||||
|
||||
.. describe:: width [<columns>]
|
||||
|
||||
Display or set the terminal width. The width is used to wrap the output
|
||||
of some commands like ``mem``. With no argument, the current width is
|
||||
displayed::
|
||||
|
||||
.width
|
||||
Terminal width is 78
|
||||
|
||||
If a column count is given, the width will be changed::
|
||||
|
||||
.width 130
|
||||
Terminal width is 130
|
||||
|
||||
The number of columns is always specified as a decimal number.
|
||||
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue