6502/py65
1
0
Fork 0
mirror of https://github.com/mnaberez/py65.git synced 2025-01-16 18:33:00 +00:00
Code Issues Projects Releases Wiki Activity

Added Sphinx-based documentation.

Browse Source
This commit is contained in:
Mike Naberezny 2008-12-01 02:58:39 +00:00
parent 17b33d0105
commit e1aa881e4c
3 changed files with 623 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
docs/Makefile Normal file
View File

@ -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."

187
docs/conf.py Normal file
View File

@ -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

361
docs/index.rst Normal file
View File

@ -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.