christoph/fail
1
Fork 0
Code Releases Activity

debuggers: import openocd-0.7.0

Browse Source 
Initial check-in of openocd-0.7.0 as it can be downloaded from
http://sourceforge.net/projects/openocd/files/openocd/0.7.0/

Any modifications will follow.

Change-Id: I6949beaefd589e046395ea0cb80f4e1ab1654d55
This commit is contained in:
Lars Rademacher
2013-10-21 00:50:02 +02:00
parent 85fffe007e
commit 83d72a091e
1148 changed files with 571445 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

204
debuggers/openocd/doc/INSTALL.txt Normal file
View File

@ -0,0 +1,204 @@
TODO!!! this should be merged into openocd.texi!!!
Prerequisites
=============
When building with support for FTDI FT2232 based devices, you need at least
one of the following libraries:
- libftdi (http://www.intra2net.com/opensource/ftdi/)
- libftd2xx (http://www.ftdichip.com/Drivers/D2XX.htm)
On Windows, you need either Cygwin or MinGW, but compilation for MinGW is also
possible using a Cygwin host.
Basic Installation
==================
OpenOCD is distributed without autotools generated files, i.e. without a
configure script. Run ./bootstrap in the openocd directory to have all
necessary files generated.
You have to explicitly enable desired JTAG interfaces during configure:
./configure --enable-parport --enable-ft2232-libftdi (OR --enable-ft2232-ftd2xx) \
--enable-amtjtagaccel
Under Windows/Cygwin, only the ftd2xx driver is supported for FT2232 based
devices. You have to specify the location of the FTDI driver package with the
--with-ftd2xx=/full/path/name option.
Under Linux you can choose to build the parport driver with support for
/dev/parportN instead of the default access with direct port I/O using
--enable-parport_ppdev. This has the advantage of running OpenOCD without root
privileges at the expense of a slight performance decrease. This is also
available on FreeBSD using PPI, but the naming of the devices is different.
Generic installation instructions
=================================
These are generic installation instructions.
The `configure' shell script attempts to guess correct values for
various system-dependent variables used during compilation. It uses
those values to create a `Makefile' in each directory of the package.
It may also create one or more `.h' files containing system-dependent
definitions. Finally, it creates a shell script `config.status' that
you can run in the future to recreate the current configuration, a file
`config.cache' that saves the results of its tests to speed up
reconfiguring, and a file `config.log' containing compiler output
(useful mainly for debugging `configure').
If you need to do unusual things to compile the package, please try
to figure out how `configure' could check whether to do them, and mail
diffs or instructions to the address given in the `README' so they can
be considered for the next release. If at some point `config.cache'
contains results you don't want to keep, you may remove or edit it.
The file `configure.in' is used to create `configure' by a program
called `autoconf'. You only need `configure.in' if you want to change
it or regenerate `configure' using a newer version of `autoconf'.
The simplest way to compile this package is:
1. `cd' to the directory containing the package's source code and type
`./configure' to configure the package for your system. If you're
using `csh' on an old version of System V, you might need to type
`sh ./configure' instead to prevent `csh' from trying to execute
`configure' itself.
Running `configure' takes a while. While running, it prints some
messages telling which features it is checking for.
2. Type `make' to compile the package.
3. Type `make install' to install the programs and any data files and
documentation.
4. You can remove the program binaries and object files from the
source code directory by typing `make clean'.
Compilers and Options
=====================
Some systems require unusual options for compilation or linking that
the `configure' script does not know about. You can give `configure'
initial values for variables by setting them in the environment. Using
a Bourne-compatible shell, you can do that on the command line like
this:
CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
Or on systems that have the `env' program, you can do it like this:
env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
Compiling For Multiple Architectures
====================================
You can compile the package for more than one kind of computer at the
same time, by placing the object files for each architecture in their
own directory. To do this, you must use a version of `make' that
supports the `VPATH' variable, such as GNU `make'. `cd' to the
directory where you want the object files and executables to go and run
the `configure' script. `configure' automatically checks for the
source code in the directory that `configure' is in and in `..'.
If you have to use a `make' that does not supports the `VPATH'
variable, you have to compile the package for one architecture at a time
in the source code directory. After you have installed the package for
one architecture, use `make distclean' before reconfiguring for another
architecture.
Installation Names
==================
By default, `make install' will install the package's files in
`/usr/local/bin', `/usr/local/man', etc. You can specify an
installation prefix other than `/usr/local' by giving `configure' the
option `--prefix=PATH'.
You can specify separate installation prefixes for
architecture-specific files and architecture-independent files. If you
give `configure' the option `--exec-prefix=PATH', the package will use
PATH as the prefix for installing programs and libraries.
Documentation and other data files will still use the regular prefix.
If the package supports it, you can cause programs to be installed
with an extra prefix or suffix on their names by giving `configure' the
option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.
Optional Features
=================
Some packages pay attention to `--enable-FEATURE' options to
`configure', where FEATURE indicates an optional part of the package.
They may also pay attention to `--with-PACKAGE' options, where PACKAGE
is something like `gnu-as' or `x' (for the X Window System). The
`README' should mention any `--enable-' and `--with-' options that the
package recognizes.
For packages that use the X Window System, `configure' can usually
find the X include and library files automatically, but if it doesn't,
you can use the `configure' options `--x-includes=DIR' and
`--x-libraries=DIR' to specify their locations.
Specifying the System Type
==========================
There may be some features `configure' can not figure out
automatically, but needs to determine by the type of host the package
will run on. Usually `configure' can figure that out, but if it prints
a message saying it can not guess the host type, give it the
`--host=TYPE' option. TYPE can either be a short name for the system
type, such as `sun4', or a canonical name with three fields:
CPU-COMPANY-SYSTEM
See the file `config.sub' for the possible values of each field. If
`config.sub' isn't included in this package, then this package doesn't
need to know the host type.
If you are building compiler tools for cross-compiling, you can also
use the `--target=TYPE' option to select the type of system they will
produce code for and the `--build=TYPE' option to select the type of
system on which you are compiling the package.
Sharing Defaults
================
If you want to set default values for `configure' scripts to share,
you can create a site shell script called `config.site' that gives
default values for variables like `CC', `cache_file', and `prefix'.
`configure' looks for `PREFIX/share/config.site' if it exists, then
`PREFIX/etc/config.site' if it exists. Or, you can set the
`CONFIG_SITE' environment variable to the location of the site script.
A warning: not all `configure' scripts look for a site script.
Operation Controls
==================
`configure' recognizes the following options to control how it
operates.
`--cache-file=FILE'
Use and save the results of the tests in FILE instead of
`./config.cache'. Set FILE to `/dev/null' to disable caching, for
debugging `configure'.
`--help'
Print a summary of the options to `configure', and exit.
`--quiet'
`--silent'
`-q'
Do not print messages saying which checks are being made.
`--srcdir=DIR'
Look for the package's source code in directory DIR. Usually
`configure' can determine that directory automatically.
`--version'
Print the version of Autoconf used to generate the `configure'
script, and exit.
`configure' also accepts some other, not widely useful, options.

20
debuggers/openocd/doc/Makefile.am Normal file
View File

@ -0,0 +1,20 @@
info_TEXINFOS = openocd.texi
openocd_TEXINFOS = fdl.texi
man_MANS = openocd.1
EXTRA_DIST = openocd.1 \
INSTALL.txt
dist-hook:
mkdir $(distdir)/manual
cp -p $(srcdir)/manual/*.txt $(distdir)/manual
for i in $$(cd $(srcdir)/manual/ && ls -d */); do \
mkdir $(distdir)/manual/$$i; \
cp -p $(srcdir)/manual/$$i/* $(distdir)/manual/$$i/; \
done
MAINTAINERCLEANFILES = \
$(srcdir)/Makefile.in \
$(srcdir)/mdate-sh \
$(srcdir)/stamp-vti \
$(srcdir)/version.texi \
$(srcdir)/texinfo.tex

809
debuggers/openocd/doc/Makefile.in Normal file
View File

@ -0,0 +1,809 @@
# Makefile.in generated by automake 1.13.1 from Makefile.am.
# @configure_input@
# Copyright (C) 1994-2012 Free Software Foundation, Inc.
# This Makefile.in is free software; the Free Software Foundation
# gives unlimited permission to copy and/or distribute it,
# with or without modifications, as long as this notice is preserved.
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
# PARTICULAR PURPOSE.
@SET_MAKE@
VPATH = @srcdir@
am__make_dryrun = \
{ \
am__dry=no; \
case $$MAKEFLAGS in \
*\\[\ \ ]*) \
echo 'am--echo: ; @echo "AM" OK' | $(MAKE) -f - 2>/dev/null \
| grep '^AM OK$$' >/dev/null || am__dry=yes;; \
*) \
for am__flg in $$MAKEFLAGS; do \
case $$am__flg in \
*=*|--*) ;; \
*n*) am__dry=yes; break;; \
esac; \
done;; \
esac; \
test $$am__dry = yes; \
}
pkgdatadir = $(datadir)/@PACKAGE@
pkgincludedir = $(includedir)/@PACKAGE@
pkglibdir = $(libdir)/@PACKAGE@
pkglibexecdir = $(libexecdir)/@PACKAGE@
am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
install_sh_DATA = $(install_sh) -c -m 644
install_sh_PROGRAM = $(install_sh) -c
install_sh_SCRIPT = $(install_sh) -c
INSTALL_HEADER = $(INSTALL_DATA)
transform = $(program_transform_name)
NORMAL_INSTALL = :
PRE_INSTALL = :
POST_INSTALL = :
NORMAL_UNINSTALL = :
PRE_UNINSTALL = :
POST_UNINSTALL = :
build_triplet = @build@
host_triplet = @host@
subdir = doc
DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/Makefile.am \
$(openocd_TEXINFOS) mdate-sh $(srcdir)/version.texi \
$(srcdir)/stamp-vti texinfo.tex
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
am__aclocal_m4_deps = $(top_srcdir)/config_subdir.m4 \
$(top_srcdir)/configure.ac
am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
$(ACLOCAL_M4)
mkinstalldirs = $(install_sh) -d
CONFIG_HEADER = $(top_builddir)/config.h
CONFIG_CLEAN_FILES =
CONFIG_CLEAN_VPATH_FILES =
AM_V_P = $(am__v_P_@AM_V@)
am__v_P_ = $(am__v_P_@AM_DEFAULT_V@)
am__v_P_0 = false
am__v_P_1 = :
AM_V_GEN = $(am__v_GEN_@AM_V@)
am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@)
am__v_GEN_0 = @echo " GEN " $@;
am__v_GEN_1 =
AM_V_at = $(am__v_at_@AM_V@)
am__v_at_ = $(am__v_at_@AM_DEFAULT_V@)
am__v_at_0 = @
am__v_at_1 =
SOURCES =
DIST_SOURCES =
AM_V_DVIPS = $(am__v_DVIPS_@AM_V@)
am__v_DVIPS_ = $(am__v_DVIPS_@AM_DEFAULT_V@)
am__v_DVIPS_0 = @echo " DVIPS " $@;
am__v_DVIPS_1 =
AM_V_MAKEINFO = $(am__v_MAKEINFO_@AM_V@)
am__v_MAKEINFO_ = $(am__v_MAKEINFO_@AM_DEFAULT_V@)
am__v_MAKEINFO_0 = @echo " MAKEINFO" $@;
am__v_MAKEINFO_1 =
AM_V_INFOHTML = $(am__v_INFOHTML_@AM_V@)
am__v_INFOHTML_ = $(am__v_INFOHTML_@AM_DEFAULT_V@)
am__v_INFOHTML_0 = @echo " INFOHTML" $@;
am__v_INFOHTML_1 =
AM_V_TEXI2DVI = $(am__v_TEXI2DVI_@AM_V@)
am__v_TEXI2DVI_ = $(am__v_TEXI2DVI_@AM_DEFAULT_V@)
am__v_TEXI2DVI_0 = @echo " TEXI2DVI" $@;
am__v_TEXI2DVI_1 =
AM_V_TEXI2PDF = $(am__v_TEXI2PDF_@AM_V@)
am__v_TEXI2PDF_ = $(am__v_TEXI2PDF_@AM_DEFAULT_V@)
am__v_TEXI2PDF_0 = @echo " TEXI2PDF" $@;
am__v_TEXI2PDF_1 =
AM_V_texinfo = $(am__v_texinfo_@AM_V@)
am__v_texinfo_ = $(am__v_texinfo_@AM_DEFAULT_V@)
am__v_texinfo_0 = -q
am__v_texinfo_1 =
AM_V_texidevnull = $(am__v_texidevnull_@AM_V@)
am__v_texidevnull_ = $(am__v_texidevnull_@AM_DEFAULT_V@)
am__v_texidevnull_0 = > /dev/null
am__v_texidevnull_1 =
INFO_DEPS = $(srcdir)/openocd.info
am__TEXINFO_TEX_DIR = $(srcdir)
DVIS = openocd.dvi
PDFS = openocd.pdf
PSS = openocd.ps
HTMLS = openocd.html
TEXINFOS = openocd.texi
TEXI2DVI = texi2dvi
TEXI2PDF = $(TEXI2DVI) --pdf --batch
MAKEINFOHTML = $(MAKEINFO) --html
AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS)
DVIPS = dvips
am__can_run_installinfo = \
case $$AM_UPDATE_INFO_DIR in \
n|no|NO) false;; \
*) (install-info --version) >/dev/null 2>&1;; \
esac
am__installdirs = "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)"
am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`;
am__vpath_adj = case $$p in \
$(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \
*) f=$$p;; \
esac;
am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`;
am__install_max = 40
am__nobase_strip_setup = \
srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'`
am__nobase_strip = \
for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||"
am__nobase_list = $(am__nobase_strip_setup); \
for p in $$list; do echo "$$p $$p"; done | \
sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \
$(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \
if (++n[$$2] == $(am__install_max)) \
{ print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \
END { for (dir in files) print dir, files[dir] }'
am__base_list = \
sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \
sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g'
am__uninstall_files_from_dir = { \
test -z "$$files" \
|| { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \
|| { echo " ( cd '$$dir' && rm -f" $$files ")"; \
$(am__cd) "$$dir" && rm -f $$files; }; \
}
man1dir = $(mandir)/man1
NROFF = nroff
MANS = $(man_MANS)
am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
ACLOCAL = @ACLOCAL@
AMTAR = @AMTAR@
AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@
AR = @AR@
AUTOCONF = @AUTOCONF@
AUTOHEADER = @AUTOHEADER@
AUTOMAKE = @AUTOMAKE@
AWK = @AWK@
CC = @CC@
CCDEPMODE = @CCDEPMODE@
CC_FOR_BUILD = @CC_FOR_BUILD@
CFLAGS = @CFLAGS@
CFLAGS_FOR_BUILD = @CFLAGS_FOR_BUILD@
CPP = @CPP@
CPPFLAGS = @CPPFLAGS@
CYGPATH_W = @CYGPATH_W@
DEFS = @DEFS@
DEPDIR = @DEPDIR@
DLLTOOL = @DLLTOOL@
DSYMUTIL = @DSYMUTIL@
DUMPBIN = @DUMPBIN@
ECHO_C = @ECHO_C@
ECHO_N = @ECHO_N@
ECHO_T = @ECHO_T@
EGREP = @EGREP@
EXEEXT = @EXEEXT@
EXEEXT_FOR_BUILD = @EXEEXT_FOR_BUILD@
FGREP = @FGREP@
GREP = @GREP@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
INSTALL_SCRIPT = @INSTALL_SCRIPT@
INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
LD = @LD@
LDFLAGS = @LDFLAGS@
LIBOBJS = @LIBOBJS@
LIBS = @LIBS@
LIBTOOL = @LIBTOOL@
LIBTOOL_DEPS = @LIBTOOL_DEPS@
LIPO = @LIPO@
LN_S = @LN_S@
LTLIBOBJS = @LTLIBOBJS@
MAINT = @MAINT@
MAKEINFO = @MAKEINFO@
MANIFEST_TOOL = @MANIFEST_TOOL@
MKDIR_P = @MKDIR_P@
NM = @NM@
NMEDIT = @NMEDIT@
OBJDUMP = @OBJDUMP@
OBJEXT = @OBJEXT@
OTOOL = @OTOOL@
OTOOL64 = @OTOOL64@
PACKAGE = @PACKAGE@
PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
PACKAGE_NAME = @PACKAGE_NAME@
PACKAGE_STRING = @PACKAGE_STRING@
PACKAGE_TARNAME = @PACKAGE_TARNAME@
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
RANLIB = @RANLIB@
SED = @SED@
SET_MAKE = @SET_MAKE@
SHELL = @SHELL@
STRIP = @STRIP@
VERSION = @VERSION@
abs_builddir = @abs_builddir@
abs_srcdir = @abs_srcdir@
abs_top_builddir = @abs_top_builddir@
abs_top_srcdir = @abs_top_srcdir@
ac_ct_AR = @ac_ct_AR@
ac_ct_CC = @ac_ct_CC@
ac_ct_DUMPBIN = @ac_ct_DUMPBIN@
am__include = @am__include@
am__leading_dot = @am__leading_dot@
am__quote = @am__quote@
am__tar = @am__tar@
am__untar = @am__untar@
bindir = @bindir@
build = @build@
build_alias = @build_alias@
build_cpu = @build_cpu@
build_os = @build_os@
build_vendor = @build_vendor@
builddir = @builddir@
datadir = @datadir@
datarootdir = @datarootdir@
docdir = @docdir@
doxygen_as_html = @doxygen_as_html@
doxygen_as_pdf = @doxygen_as_pdf@
dvidir = @dvidir@
exec_prefix = @exec_prefix@
host = @host@
host_alias = @host_alias@
host_cpu = @host_cpu@
host_os = @host_os@
host_vendor = @host_vendor@
htmldir = @htmldir@
includedir = @includedir@
infodir = @infodir@
install_sh = @install_sh@
libdir = @libdir@
libexecdir = @libexecdir@
localedir = @localedir@
localstatedir = @localstatedir@
mandir = @mandir@
mkdir_p = @mkdir_p@
oldincludedir = @oldincludedir@
pdfdir = @pdfdir@
prefix = @prefix@
program_transform_name = @program_transform_name@
psdir = @psdir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
subdirs = @subdirs@
sysconfdir = @sysconfdir@
target_alias = @target_alias@
top_build_prefix = @top_build_prefix@
top_builddir = @top_builddir@
top_srcdir = @top_srcdir@
info_TEXINFOS = openocd.texi
openocd_TEXINFOS = fdl.texi
man_MANS = openocd.1
EXTRA_DIST = openocd.1 \
INSTALL.txt
MAINTAINERCLEANFILES = \
$(srcdir)/Makefile.in \
$(srcdir)/mdate-sh \
$(srcdir)/stamp-vti \
$(srcdir)/version.texi \
$(srcdir)/texinfo.tex
all: all-am
.SUFFIXES:
.SUFFIXES: .dvi .html .info .pdf .ps .texi
$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps)
@for dep in $?; do \
case '$(am__configure_deps)' in \
*$$dep*) \
( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \
&& { if test -f $@; then exit 0; else break; fi; }; \
exit 1;; \
esac; \
done; \
echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/Makefile'; \
$(am__cd) $(top_srcdir) && \
$(AUTOMAKE) --gnu doc/Makefile
.PRECIOUS: Makefile
Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
@case '$?' in \
*config.status*) \
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \
*) \
echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \
cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \
esac;
$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
$(am__aclocal_m4_deps):
mostlyclean-libtool:
-rm -f *.lo
clean-libtool:
-rm -rf .libs _libs
.texi.info:
$(AM_V_MAKEINFO)restore=: && backupdir="$(am__leading_dot)am$$$$" && \
am__cwd=`pwd` && $(am__cd) $(srcdir) && \
rm -rf $$backupdir && mkdir $$backupdir && \
if ($(MAKEINFO) --version) >/dev/null 2>&1; then \
for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \
if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \
done; \
else :; fi && \
cd "$$am__cwd"; \
if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \
-o $@ $<; \
then \
rc=0; \
$(am__cd) $(srcdir); \
else \
rc=$$?; \
$(am__cd) $(srcdir) && \
$$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \
fi; \
rm -rf $$backupdir; exit $$rc
.texi.dvi:
$(AM_V_TEXI2DVI)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \
$(TEXI2DVI) $(AM_V_texinfo) --build-dir=$(@:.dvi=.t2d) -o $@ $(AM_V_texidevnull) \
$<
.texi.pdf:
$(AM_V_TEXI2PDF)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \
$(TEXI2PDF) $(AM_V_texinfo) --build-dir=$(@:.pdf=.t2p) -o $@ $(AM_V_texidevnull) \
$<
.texi.html:
$(AM_V_MAKEINFO)rm -rf $(@:.html=.htp)
$(AM_V_at)if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \
-o $(@:.html=.htp) $<; \
then \
rm -rf $@; \
if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \
mv $(@:.html=) $@; else mv $(@:.html=.htp) $@; fi; \
else \
if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \
rm -rf $(@:.html=); else rm -Rf $(@:.html=.htp) $@; fi; \
exit 1; \
fi
$(srcdir)/openocd.info: openocd.texi $(srcdir)/version.texi $(openocd_TEXINFOS)
openocd.dvi: openocd.texi $(srcdir)/version.texi $(openocd_TEXINFOS)
openocd.pdf: openocd.texi $(srcdir)/version.texi $(openocd_TEXINFOS)
openocd.html: openocd.texi $(srcdir)/version.texi $(openocd_TEXINFOS)
$(srcdir)/version.texi: @MAINTAINER_MODE_TRUE@ $(srcdir)/stamp-vti
$(srcdir)/stamp-vti: openocd.texi $(top_srcdir)/configure
@(dir=.; test -f ./openocd.texi || dir=$(srcdir); \
set `$(SHELL) $(srcdir)/mdate-sh $$dir/openocd.texi`; \
echo "@set UPDATED $$1 $$2 $$3"; \
echo "@set UPDATED-MONTH $$2 $$3"; \
echo "@set EDITION $(VERSION)"; \
echo "@set VERSION $(VERSION)") > vti.tmp
@cmp -s vti.tmp $(srcdir)/version.texi \
|| (echo "Updating $(srcdir)/version.texi"; \
cp vti.tmp $(srcdir)/version.texi)
-@rm -f vti.tmp
@cp $(srcdir)/version.texi $@
mostlyclean-vti:
-rm -f vti.tmp
maintainer-clean-vti:
@MAINTAINER_MODE_TRUE@ -rm -f $(srcdir)/stamp-vti $(srcdir)/version.texi
.dvi.ps:
$(AM_V_DVIPS)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
$(DVIPS) $(AM_V_texinfo) -o $@ $<
uninstall-dvi-am:
@$(NORMAL_UNINSTALL)
@list='$(DVIS)'; test -n "$(dvidir)" || list=; \
for p in $$list; do \
$(am__strip_dir) \
echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \
rm -f "$(DESTDIR)$(dvidir)/$$f"; \
done
uninstall-html-am:
@$(NORMAL_UNINSTALL)
@list='$(HTMLS)'; test -n "$(htmldir)" || list=; \
for p in $$list; do \
$(am__strip_dir) \
echo " rm -rf '$(DESTDIR)$(htmldir)/$$f'"; \
rm -rf "$(DESTDIR)$(htmldir)/$$f"; \
done
uninstall-info-am:
@$(PRE_UNINSTALL)
@if test -d '$(DESTDIR)$(infodir)' && $(am__can_run_installinfo); then \
list='$(INFO_DEPS)'; \
for file in $$list; do \
relfile=`echo "$$file" | sed 's|^.*/||'`; \
echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \
if install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \
then :; else test ! -f "$(DESTDIR)$(infodir)/$$relfile" || exit 1; fi; \
done; \
else :; fi
@$(NORMAL_UNINSTALL)
@list='$(INFO_DEPS)'; \
for file in $$list; do \
relfile=`echo "$$file" | sed 's|^.*/||'`; \
relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \
(if test -d "$(DESTDIR)$(infodir)" && cd "$(DESTDIR)$(infodir)"; then \
echo " cd '$(DESTDIR)$(infodir)' && rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]"; \
rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \
else :; fi); \
done
uninstall-pdf-am:
@$(NORMAL_UNINSTALL)
@list='$(PDFS)'; test -n "$(pdfdir)" || list=; \
for p in $$list; do \
$(am__strip_dir) \
echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \
rm -f "$(DESTDIR)$(pdfdir)/$$f"; \
done
uninstall-ps-am:
@$(NORMAL_UNINSTALL)
@list='$(PSS)'; test -n "$(psdir)" || list=; \
for p in $$list; do \
$(am__strip_dir) \
echo " rm -f '$(DESTDIR)$(psdir)/$$f'"; \
rm -f "$(DESTDIR)$(psdir)/$$f"; \
done
dist-info: $(INFO_DEPS)
@srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \
list='$(INFO_DEPS)'; \
for base in $$list; do \
case $$base in \
$(srcdir)/*) base=`echo "$$base" | sed "s|^$$srcdirstrip/||"`;; \
esac; \
if test -f $$base; then d=.; else d=$(srcdir); fi; \
base_i=`echo "$$base" | sed 's|\.info$$||;s|$$|.i|'`; \
for file in $$d/$$base $$d/$$base-[0-9] $$d/$$base-[0-9][0-9] $$d/$$base_i[0-9] $$d/$$base_i[0-9][0-9]; do \
if test -f $$file; then \
relfile=`expr "$$file" : "$$d/\(.*\)"`; \
test -f "$(distdir)/$$relfile" || \
cp -p $$file "$(distdir)/$$relfile"; \
else :; fi; \
done; \
done
mostlyclean-aminfo:
-rm -rf openocd.t2d openocd.t2p
clean-aminfo:
-test -z "openocd.dvi openocd.pdf openocd.ps openocd.html" \
|| rm -rf openocd.dvi openocd.pdf openocd.ps openocd.html
maintainer-clean-aminfo:
@list='$(INFO_DEPS)'; for i in $$list; do \
i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \
echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \
rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \
done
install-man1: $(man_MANS)
@$(NORMAL_INSTALL)
@list1=''; \
list2='$(man_MANS)'; \
test -n "$(man1dir)" \
&& test -n "`echo $$list1$$list2`" \
|| exit 0; \
echo " $(MKDIR_P) '$(DESTDIR)$(man1dir)'"; \
$(MKDIR_P) "$(DESTDIR)$(man1dir)" || exit 1; \
{ for i in $$list1; do echo "$$i"; done; \
if test -n "$$list2"; then \
for i in $$list2; do echo "$$i"; done \
| sed -n '/\.1[a-z]*$$/p'; \
fi; \
} | while read p; do \
if test -f $$p; then d=; else d="$(srcdir)/"; fi; \
echo "$$d$$p"; echo "$$p"; \
done | \
sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
-e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \
sed 'N;N;s,\n, ,g' | { \
list=; while read file base inst; do \
if test "$$base" = "$$inst"; then list="$$list $$file"; else \
echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \
$(INSTALL_DATA) "$$file" "$(DESTDIR)$(man1dir)/$$inst" || exit $$?; \
fi; \
done; \
for i in $$list; do echo "$$i"; done | $(am__base_list) | \
while read files; do \
test -z "$$files" || { \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man1dir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(man1dir)" || exit $$?; }; \
done; }
uninstall-man1:
@$(NORMAL_UNINSTALL)
@list=''; test -n "$(man1dir)" || exit 0; \
files=`{ for i in $$list; do echo "$$i"; done; \
l2='$(man_MANS)'; for i in $$l2; do echo "$$i"; done | \
sed -n '/\.1[a-z]*$$/p'; \
} | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
-e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \
dir='$(DESTDIR)$(man1dir)'; $(am__uninstall_files_from_dir)
tags TAGS:
ctags CTAGS:
cscope cscopelist:
distdir: $(DISTFILES)
@srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
list='$(DISTFILES)'; \
dist_files=`for file in $$list; do echo $$file; done | \
sed -e "s|^$$srcdirstrip/||;t" \
-e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \
case $$dist_files in \
*/*) $(MKDIR_P) `echo "$$dist_files" | \
sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \
sort -u` ;; \
esac; \
for file in $$dist_files; do \
if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
if test -d $$d/$$file; then \
dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \
if test -d "$(distdir)/$$file"; then \
find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
fi; \
if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \
find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
fi; \
cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \
else \
test -f "$(distdir)/$$file" \
|| cp -p $$d/$$file "$(distdir)/$$file" \
|| exit 1; \
fi; \
done
$(MAKE) $(AM_MAKEFLAGS) \
top_distdir="$(top_distdir)" distdir="$(distdir)" \
dist-info dist-hook
check-am: all-am
check: check-am
all-am: Makefile $(INFO_DEPS) $(MANS)
installdirs:
for dir in "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)"; do \
test -z "$$dir" || $(MKDIR_P) "$$dir"; \
done
install: install-am
install-exec: install-exec-am
install-data: install-data-am
uninstall: uninstall-am
install-am: all-am
@$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
installcheck: installcheck-am
install-strip:
if test -z '$(STRIP)'; then \
$(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
install; \
else \
$(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
"INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \
fi
mostlyclean-generic:
clean-generic:
distclean-generic:
-test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
-test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES)
maintainer-clean-generic:
@echo "This command is intended for maintainers to use"
@echo "it deletes files that may require special tools to rebuild."
-test -z "$(MAINTAINERCLEANFILES)" || rm -f $(MAINTAINERCLEANFILES)
clean: clean-am
clean-am: clean-aminfo clean-generic clean-libtool mostlyclean-am
distclean: distclean-am
-rm -f Makefile
distclean-am: clean-am distclean-generic
dvi: dvi-am
dvi-am: $(DVIS)
html: html-am
html-am: $(HTMLS)
info: info-am
info-am: $(INFO_DEPS)
install-data-am: install-info-am install-man
install-dvi: install-dvi-am
install-dvi-am: $(DVIS)
@$(NORMAL_INSTALL)
@list='$(DVIS)'; test -n "$(dvidir)" || list=; \
if test -n "$$list"; then \
echo " $(MKDIR_P) '$(DESTDIR)$(dvidir)'"; \
$(MKDIR_P) "$(DESTDIR)$(dvidir)" || exit 1; \
fi; \
for p in $$list; do \
if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
echo "$$d$$p"; \
done | $(am__base_list) | \
while read files; do \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(dvidir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(dvidir)" || exit $$?; \
done
install-exec-am:
install-html: install-html-am
install-html-am: $(HTMLS)
@$(NORMAL_INSTALL)
@list='$(HTMLS)'; list2=; test -n "$(htmldir)" || list=; \
if test -n "$$list"; then \
echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)'"; \
$(MKDIR_P) "$(DESTDIR)$(htmldir)" || exit 1; \
fi; \
for p in $$list; do \
if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \
$(am__strip_dir) \
d2=$$d$$p; \
if test -d "$$d2"; then \
echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \
$(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \
echo " $(INSTALL_DATA) '$$d2'/* '$(DESTDIR)$(htmldir)/$$f'"; \
$(INSTALL_DATA) "$$d2"/* "$(DESTDIR)$(htmldir)/$$f" || exit $$?; \
else \
list2="$$list2 $$d2"; \
fi; \
done; \
test -z "$$list2" || { echo "$$list2" | $(am__base_list) | \
while read files; do \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(htmldir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(htmldir)" || exit $$?; \
done; }
install-info: install-info-am
install-info-am: $(INFO_DEPS)
@$(NORMAL_INSTALL)
@srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \
list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \
if test -n "$$list"; then \
echo " $(MKDIR_P) '$(DESTDIR)$(infodir)'"; \
$(MKDIR_P) "$(DESTDIR)$(infodir)" || exit 1; \
fi; \
for file in $$list; do \
case $$file in \
$(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \
esac; \
if test -f $$file; then d=.; else d=$(srcdir); fi; \
file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \
for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \
$$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \
if test -f $$ifile; then \
echo "$$ifile"; \
else : ; fi; \
done; \
done | $(am__base_list) | \
while read files; do \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(infodir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(infodir)" || exit $$?; done
@$(POST_INSTALL)
@if $(am__can_run_installinfo); then \
list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \
for file in $$list; do \
relfile=`echo "$$file" | sed 's|^.*/||'`; \
echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\
install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\
done; \
else : ; fi
install-man: install-man1
install-pdf: install-pdf-am
install-pdf-am: $(PDFS)
@$(NORMAL_INSTALL)
@list='$(PDFS)'; test -n "$(pdfdir)" || list=; \
if test -n "$$list"; then \
echo " $(MKDIR_P) '$(DESTDIR)$(pdfdir)'"; \
$(MKDIR_P) "$(DESTDIR)$(pdfdir)" || exit 1; \
fi; \
for p in $$list; do \
if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
echo "$$d$$p"; \
done | $(am__base_list) | \
while read files; do \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(pdfdir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(pdfdir)" || exit $$?; done
install-ps: install-ps-am
install-ps-am: $(PSS)
@$(NORMAL_INSTALL)
@list='$(PSS)'; test -n "$(psdir)" || list=; \
if test -n "$$list"; then \
echo " $(MKDIR_P) '$(DESTDIR)$(psdir)'"; \
$(MKDIR_P) "$(DESTDIR)$(psdir)" || exit 1; \
fi; \
for p in $$list; do \
if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
echo "$$d$$p"; \
done | $(am__base_list) | \
while read files; do \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(psdir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(psdir)" || exit $$?; done
installcheck-am:
maintainer-clean: maintainer-clean-am
-rm -f Makefile
maintainer-clean-am: distclean-am maintainer-clean-aminfo \
maintainer-clean-generic maintainer-clean-vti
mostlyclean: mostlyclean-am
mostlyclean-am: mostlyclean-aminfo mostlyclean-generic \
mostlyclean-libtool mostlyclean-vti
pdf: pdf-am
pdf-am: $(PDFS)
ps: ps-am
ps-am: $(PSS)
uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \
uninstall-man uninstall-pdf-am uninstall-ps-am
uninstall-man: uninstall-man1
.MAKE: install-am install-strip
.PHONY: all all-am check check-am clean clean-aminfo clean-generic \
clean-libtool cscopelist-am ctags-am dist-hook dist-info \
distclean distclean-generic distclean-libtool distdir dvi \
dvi-am html html-am info info-am install install-am \
install-data install-data-am install-dvi install-dvi-am \
install-exec install-exec-am install-html install-html-am \
install-info install-info-am install-man install-man1 \
install-pdf install-pdf-am install-ps install-ps-am \
install-strip installcheck installcheck-am installdirs \
maintainer-clean maintainer-clean-aminfo \
maintainer-clean-generic maintainer-clean-vti mostlyclean \
mostlyclean-aminfo mostlyclean-generic mostlyclean-libtool \
mostlyclean-vti pdf pdf-am ps ps-am tags-am uninstall \
uninstall-am uninstall-dvi-am uninstall-html-am \
uninstall-info-am uninstall-man uninstall-man1 \
uninstall-pdf-am uninstall-ps-am
dist-hook:
mkdir $(distdir)/manual
cp -p $(srcdir)/manual/*.txt $(distdir)/manual
for i in $$(cd $(srcdir)/manual/ && ls -d */); do \
mkdir $(distdir)/manual/$$i; \
cp -p $(srcdir)/manual/$$i/* $(distdir)/manual/$$i/; \
done
# Tell versions [3.59,3.63) of GNU make to not export all variables.
# Otherwise a system limit (for SysV at least) may be exceeded.
.NOEXPORT:

452
debuggers/openocd/doc/fdl.texi Normal file
View File

@ -0,0 +1,452 @@
@c -*-texinfo-*-
@node License
@appendix The GNU Free Documentation License.
@center Version 1.2, November 2002
@c This file is intended to be included within another document,
@c hence no sectioning command or @node.
@display
Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc.
51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
@end display
@enumerate 0
@item
PREAMBLE
The purpose of this License is to make a manual, textbook, or other
functional and useful document @dfn{free} in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible
for modifications made by others.
This License is a kind of ``copyleft'', which means that derivative
works of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does. But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book. We recommend this License
principally for works whose purpose is instruction or reference.
@item
APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License. Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein. The ``Document'', below,
refers to any such manual or work. Any member of the public is a
licensee, and is addressed as ``you''. You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.
A ``Modified Version'' of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A ``Secondary Section'' is a named appendix or a front-matter section
of the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall
subject (or to related matters) and contains nothing that could fall
directly within that overall subject. (Thus, if the Document is in
part a textbook of mathematics, a Secondary Section may not explain
any mathematics.) The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.
The ``Invariant Sections'' are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License. If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant. The Document may contain zero
Invariant Sections. If the Document does not identify any Invariant
Sections then there are none.
The ``Cover Texts'' are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License. A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.
A ``Transparent'' copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
of text. A copy that is not ``Transparent'' is called ``Opaque''.
Examples of suitable formats for Transparent copies include plain
@sc{ascii} without markup, Texinfo input format, La@TeX{} input
format, @acronym{SGML} or @acronym{XML} using a publicly available
@acronym{DTD}, and standard-conforming simple @acronym{HTML},
PostScript or @acronym{PDF} designed for human modification. Examples
of transparent image formats include @acronym{PNG}, @acronym{XCF} and
@acronym{JPG}. Opaque formats include proprietary formats that can be
read and edited only by proprietary word processors, @acronym{SGML} or
@acronym{XML} for which the @acronym{DTD} and/or processing tools are
not generally available, and the machine-generated @acronym{HTML},
PostScript or @acronym{PDF} produced by some word processors for
output purposes only.
The ``Title Page'' means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page. For works in
formats which do not have any title page as such, ``Title Page'' means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.
A section ``Entitled XYZ'' means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language. (Here XYZ stands for a
specific section name mentioned below, such as ``Acknowledgements'',
``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
of such a section when you modify the Document means that it remains a
section ``Entitled XYZ'' according to this definition.
The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document. These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
no effect on the meaning of this License.
@item
VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License. You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute. However, you may accept
compensation in exchange for copies. If you distribute a large enough
number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and
you may publicly display copies.
@item
COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have
printed covers) of the Document, numbering more than 100, and the
Document's license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify
you as the publisher of these copies. The front cover must present
the full title with all words of the title equally prominent and
visible. You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.
If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a computer-network location from which the general network-using
public has access to download using public-standard network protocols
a complete Transparent copy of the Document, free of added material.
If you use the latter option, you must take reasonably prudent steps,
when you begin distribution of Opaque copies in quantity, to ensure
that this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you distribute an
Opaque copy (directly or through your agents or retailers) of that
edition to the public.
It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.
@item
MODIFICATIONS
You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it. In addition, you must do these things in the Modified Version:
@enumerate A
@item
Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
of the Document). You may use the same title as a previous version
if the original publisher of that version gives permission.
@item
List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has fewer than five),
unless they release you from this requirement.
@item
State on the Title page the name of the publisher of the
Modified Version, as the publisher.
@item
Preserve all the copyright notices of the Document.
@item
Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
@item
Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below.
@item
Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document's license notice.
@item
Include an unaltered copy of this License.
@item
Preserve the section Entitled ``History'', Preserve its Title, and add
to it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If
there is no section Entitled ``History'' in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.
@item
Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on. These may be placed in the ``History'' section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.
@item
For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
the Title of the section, and preserve in the section all the
substance and tone of each of the contributor acknowledgements and/or
dedications given therein.
@item
Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section titles.
@item
Delete any section Entitled ``Endorsements''. Such a section
may not be included in the Modified Version.
@item
Do not retitle any existing section to be Entitled ``Endorsements'' or
to conflict in title with any Invariant Section.
@item
Preserve any Warranty Disclaimers.
@end enumerate
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant. To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.
You may add a section Entitled ``Endorsements'', provided it contains
nothing but endorsements of your Modified Version by various
parties---for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.
You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version. Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.
@item
COMBINING DOCUMENTS
You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled ``History''
in the various original documents, forming one section Entitled
``History''; likewise combine any sections Entitled ``Acknowledgements'',
and any sections Entitled ``Dedications''. You must delete all
sections Entitled ``Endorsements.''
@item
COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.
@item
AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, is called an ``aggregate'' if the copyright
resulting from the compilation is not used to limit the legal rights
of the compilation's users beyond what the individual works permit.
When the Document is included in an aggregate, this License does not
apply to the other works in the aggregate which are not themselves
derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half of
the entire aggregate, the Document's Cover Texts may be placed on
covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole
aggregate.
@item
TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions
of those notices and disclaimers. In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.
If a section in the Document is Entitled ``Acknowledgements'',
``Dedications'', or ``History'', the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual
title.
@item
TERMINATION
You may not copy, modify, sublicense, or distribute the Document except
as expressly provided for under this License. Any other attempt to
copy, modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License. However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such
parties remain in full compliance.
@item
FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
@uref{http://www.gnu.org/copyleft/}.
Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License ``or any later version'' applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation. If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.
@end enumerate
@unnumberedsec ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:
@smallexample
@group
Copyright (C) @var{year} @var{your name}.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
@end group
@end smallexample
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
replace the ``with@dots{}Texts.'' line with this:
@smallexample
@group
with the Invariant Sections being @var{list their titles}, with
the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
being @var{list}.
@end group
@end smallexample
If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.
@c Local Variables:
@c ispell-local-pdict: "ispell-dict"
@c End:

9
debuggers/openocd/doc/manual/app.txt Normal file
View File

@ -0,0 +1,9 @@
/** @page appdocs OpenOCD Application APIs
The top-level APIs in the OpenOCD library allow applications to integrate
all of the low-level functionality using a set of simple function calls.
These function calls do not exist in a re-usable form, but
contributions to create and document them will be welcome.
*/

35
debuggers/openocd/doc/manual/flash.txt Normal file
View File

@ -0,0 +1,35 @@
/** @page flashdocs OpenOCD Flash APIs
OpenOCD provides its Flash APIs for developers to support different
types of flash devices, some of which are built-in to target devices
while others may be connected via standard memory interface (e.g. CFI,
FMI, etc.).
The Flash module provides the following APIs:
- @subpage flashcfi
- @subpage flashnand
- @subpage flashtarget
This section needs to be expanded.
*/
/** @page flashcfi OpenOCD CFI Flash API
This section needs to be expanded to describe OpenOCD's CFI Flash API.
*/
/** @page flashnand OpenOCD NAND Flash API
This section needs to be expanded to describe OpenOCD's NAND Flash API.
*/
/** @page flashtarget OpenOCD Target Flash API
This section needs to be expanded to describe OpenOCD's Target Flash API.
*/

136
debuggers/openocd/doc/manual/helper.txt Normal file
View File

@ -0,0 +1,136 @@
/** @page helperdocs OpenOCD Helper APIs
OpenOCD uses several low-level APIs as the foundation for high-level APIs:
- @subpage helperporting
- @subpage helperjim
- @subpage helpercommand
- @subpage helperlogging
- @subpage helperbuffers
This section needs to be expanded.
*/
/** @page helperporting OpenOCD Types/Portability APIs
This section needs to be expanded to describe OpenOCD's type and
portability API.
*/
/** @page helperjim OpenOCD Jim API
The Jim API provides access to a small-footprint TCL implementation.
Visit http://jim.berlios.de/ for more information on Jim.
This section needs to be expanded to describe OpenOCD's Jim API.
*/
/** @page helpercommand OpenOCD Command API
OpenOCD's command API allows modules to register callbacks that are then
available to the scripting services. It provides the mechanism for
these commands to be dispatched to the modlue using a standard
interfaces. It provides macros for defining functions that use and
extend this interface.
@section helpercmdhandler Command Handlers
Command handlers are functions with a particular signature, which can
be extended by modules for passing additional parameters to helpers or
another layer of handlers.
@subsection helpercmdhandlerdef Defining and Calling Command Handlers
These functions should be defined using the @c COMMAND_HANDLER macro.
These methods must be defined as static, as their principle entry point
should be the run_command dispatch mechanism.
Command helper functions that require access to the full set of
parameters should be defined using the @c COMMAND_HELPER. These must be
declared static by you, as sometimes you might want to share a helper
among several files (e.g. @c s3c24xx_nand.h).
Both types of routines must be called using the @c CALL_COMMAND_HANDLER macro.
Calls using this macro to normal handlers require the name of the command
handler (which can a name or function pointer). Calls to helpers and
derived handlers must pass those extra parameters specified by their
definitions; however, lexical capture is used for the core parameters.
This dirty trick is being used as a stop-gap measure while the API is
migrated to one that passes a pointer to a structure containing the
same ingredients. At that point, this macro will be removed and callers
will be able to use direct invocations.
Thus, the following macros can be used to define and call command
handlers or helpers:
- @c COMMAND_HANDLER - declare or define a command handler.
- @c COMMAND_HELPER - declare or define a derived command handler or helper.
- @c CALL_COMMAND_COMMAND - call a command handler/helper.
@subsection helpercmdhandlermacros Command Handler Macros
In addition, the following macros may be used in the context of
command handlers and helpers:
- @c CMD_CTX - the current @c command_context
- @c CMD_NAME - invoked command name
- @c CMD_ARGC - the number of command arguments
- @c CMD_ARGV - array of command argument strings
@section helpercmdregister Command Registration
In order to use a command handler, it must be registered with the
command subsystem. All commands are registered with command_registration
structures, specifying the name of the command, its handler, its allowed
mode(s) of execution, and strings that provide usage and help text.
A single handler may be registered using multiple names, but any name
may have only one handler associated with it.
The @c register_commands() and @c register_commands() functions provide
registration, while the @c unregister_command() and
@c unregister_all_commands() functions will remove existing commands.
These may be called at any time, allowing the command set to change in
response to system actions.
@subsection helpercmdjim Jim Command Registration
The command_registration structure provides support for registering
native Jim command handlers (@c jim_handler) too. For these handlers,
the module can provide help and usage support; however, this mechanism
allows Jim handlers to be called as sub-commands of other commands.
These commands may be registered with a private data value (@c
jim_handler_data) that will be available when called, as with low-level
Jim command registration.
A command may have a normal @c handler or a @c jim_handler, but not both.
@subsection helpercmdregisterchains Command Chaining
When using register_commands(), the array of commands may reference
other arrays. When the @c chain field is filled in a
command_registration record, the commands on in the chained list will
added in one of two places. If the record defines a new command, then
the chained commands are added under it; otherwise, the commands are
added in the same context as the other commands in the array.
@section helpercmdprimer Command Development Primer
This @ref primercommand provides details about the @c hello module,
showing how the pieces desrcribed on this page fit together.
*/
/** @page helperlogging OpenOCD Logging API
This section needs to be expanded to describe OpenOCD's Logging API.
*/
/** @page helperbuffers OpenOCD Byte Buffer API
This section needs to be expanded to describe OpenOCD's Byte Buffer API.
*/

73
debuggers/openocd/doc/manual/jtag.txt Normal file
View File

@ -0,0 +1,73 @@
/** @page jtagdocs JTAG APIs
For new developers unfamiliar with the technology, @ref primerjtag provides
a brief introduction to the IEEE JTAG interface.
The OpenOCD JTAG library API covers several functional areas. The jtag
@b core communicates through the @b minidriver API with either its full
@a driver implementation (src/jtag/jtag_driver.c) or a @a minidriver .
Internally, the @b command API is used by the JTAG driver for managing
asynchronous transactions.
- @subpage jtagcore
- @b public API routines
- declared in @c src/jtag/jtag.h
- used by other modules
- @subpage jtagtcl
- @b private TCL handling routines
- defined in @c src/jtag/tcl.c
- registers and handles Jim commands that configure and use the JTAG core
- @subpage jtagcmd
- @b private command queue API
- declared in @c src/jtag/commands.h
- provides routines used internally by the full JTAG drivers.
- @subpage jtagiface
- @b private interface driver API
- declared in @c src/jtag/interface.h
- used by the core, minidrivers, and the full interface device drivers.
- allows implementing new interface device drivers.
- includes the Cable/TAP API (commands starting with @c tap_)
- @subpage jtagdriver
- @b private minidriver API
- declared in @c src/jtag/minidriver.h
- used @a only by the core and minidriver implementations:
- @c jtag_driver.c (in-tree OpenOCD drivers)
- @c zy1000/build/include/jtag_minidriver.h (ZY1000 minidriver)
- future implementations (on other embedded hosts)
- interface device drivers do @b not need this API.
*/
/** @page jtagcore JTAG Core API
This section needs to be expanded.
*/
/** @page jtagtcl JTAG TCL API
This section needs to be expanded.
*/
/** @page jtagcmd JTAG Command API
This section needs to be expanded.
*/
/** @page jtagiface JTAG Interface API
This section needs to be expanded.
*/
/** @page jtagdriver JTAG Minidriver API
This section needs to be expanded.
*/

105
debuggers/openocd/doc/manual/main.txt Normal file
View File

@ -0,0 +1,105 @@
/** @mainpage OpenOCD Developer's Guide
Welcome to the OpenOCD Developer's Guide -- the developer's resource for
learning about the internal architecture of the OpenOCD project. @par
In addition, this document contains the tactical and strategic plans
and processes that have been developed by and for the OpenOCD community.
Developers that want to contribute to OpenOCD should read the following
sections before starting work:
- The List of @subpage thelist enumerates opportunities for improving or
extending the OpenOCD platform. If your ideas are on The List, you might
check the mailing list archives to find the status of your feature (or bug).
- The @subpage styleguide provides rules that developers should
follow when writing new code for OpenOCD.
- The @subpage patchguide provides policies that developers should
follow when submitting patches to the project.
- The @subpage bugs page contains the content of the BUGS file, which
provides instructions for submitting bug reports to the maintainers.
- The @subpage releases page describes the project's release process.
@ref primer provide introductory materials for new developers on various
specific topics.
Finally, the @ref oocd pages explain how the code has been organized
into layers of APIs, providing an overview of how they fit together.
These pages attempt to give developers a high-level perspective of the
various code modules provided by OpenOCD.
*/
/** @page primer OpenOCD Technical Primers
This pages lists Technical Primers available for OpenOCD Developers.
They seek to provide information to pull novices up the learning curves
associated with the fundamental technologies used by OpenOCD.
- @subpage primerdocs
- @subpage primerautotools
- @subpage primertcl
- @subpage primerjtag
The above documents should bridge any "ancillary" gaps in contributor
knowledge, without having to learn the complete languages or technology.
They should provide enough information for experienced developers to
learn how to make "correct" changes when creating patches.
Beyond the fundamentals, the following primers provide introductory
tutorials for OpenOCD's sub-systems. These complement the @ref oocd
pages that provide more high-level perspective on related topics.
- @subpage primercommand
In all cases, these Primers should use idiomatic conventions that the
community has agreed are the "right way of doing things". In this
respect, these documents typically assume some familiarity with the
information contained in one or more @ref styleguide, or they will
directly refer to specific style guides as supplemental reading.
Contributions or suggestions for new Technical Primers are welcome.
*/
/** @page oocd OpenOCD Architecture
The OpenOCD library consists of several APIs that build together to
provide the support functionality. The following list shows how these
modules are stacked in the current implementation (from bottom to top):
- @subpage helperdocs
- @ref helperporting
- @ref helperjim
- @ref helpercommand
- @ref helperlogging
- @subpage jtagdocs
- @ref jtagcore
- @ref jtagtcl
- @ref jtagcmd
- @ref jtagiface
- @ref jtagdriver
- @subpage targetdocs
- @ref targetarm
- @ref targetnotarm
- @ref targetmips
- @ref targetregister
- @ref targetimage
- @ref targettrace
- @subpage flashdocs
- @ref flashcfi
- @ref flashnand
- @ref flashtarget
- @subpage serverdocs
- @ref servergdb
- @ref servertelnet
- @ref serverhttp
- @subpage appdocs
Obviously, there are some nuances to the stack that are not shown by
this linear list of layers.
The List of @ref thelist enumerates opportunities for improving or
extending the OpenOCD platform.
*/

167
debuggers/openocd/doc/manual/primer/autotools.txt Normal file
View File

@ -0,0 +1,167 @@
/** @page primerautotools OpenOCD Autotools Primer
This page provides an overview to OpenOCD's use of the GNU autotool suite:
- @ref primerautoconf
- @ref primerautomake
- @ref primerlibtool
Most developers do not need to concern themselves with these tools, as
the @ref primerbootstrap script runs these tools in the required sequence.
@section primerbootstrap Autotools Bootstrap
The @c bootstrap script should be used by developers to run the
autotools in the correct sequence.
When run after a fresh checkout, this script generates the build files
required to compile the project, producing the project configure script.
After running @c configure, the @ref primermaintainermode settings will
handle most situations that require running these tools again. In some
cases, a fresh bootstrap may be still required.
@subsection primerbootstrapcures Problems Solved By Bootstrap
For example, the build system can fail in unexpected ways after running
<code>git pull</code>. Here, the <code>make maintainer-clean</code>
should be used to remove all of the files generated by the @c bootstrap
script and subsequent build processes.
In this particular case, one may also need to remove stray files by hand
after running this command to ensure everything is rebuilt properly.
This step should be necessary only if the @c maintainer-clean was run
@b after altering the build system files with git. If it is run
@b before any updates, the build system should never leave artifacts
in the tree.
Without such precautions, changes can be introduced that leave the tree
timestamps in an inconsistent state, producing strange compile errors
that are resolve after such diligence.
@subsection primermaintainerclean Autotools Cleaning
Normally, all files generated by the bootstrap script, configure
process, and build system should be removed after running <code>make
maintainer-clean</code>. Automatically generated files that remain
after this should be listed in @c MAINTAINERCLEANFILES,
@c DISTCLEANFILES, or @c CLEANFILES, depending on which stage of the
build process they are produced.
@section primerautoconf Autoconf Configuration Script
The @c autoconf program generates the @c configure script from
@c configure.in, using serious Perl voodoo. The resulting script is
included in the project distribution packages and run by users to
configure the build process for their system.
@subsection primermaintainermode Maintainer Mode
After a fresh checkout, @c bootstrap, and a simple @c configure, you may
experience errors when running @c make that some files cannot be found
(e.g. @c version.texi), and a second @c make will "mysteriously" solve
the problems. The isssue is well-known and expected, if unfortunate.
The OpenOCD project requires that all developers building from the
git repository use the @c --enable-maintainer-mode option when
running the @c configure script. This option ensures that certain files
are created during the build process that would normally be packaged in
the distribution tarball. The @c bootstrap script will remind you of
this requirement when it runs.
In addition to solving these problems, this option enables Makefile
rules (provided by automake) that allow the normal @c make process to
rebuild the autotools outputs, included the automake-generated Makefiles
themselves. This avoids the heavy-handed approach of running the
@c bootstrap script after changing one of these files.
@section primerautomake Automake Makefiles
The @c automake program generates @c Makefile.in files (from @c
Makefile.am files). These files are later processed by the configure
script produced by @c autoconf.
@subsection primerautomakenewfiles Creating Makefile.am Files
This section shows how to add a @c Makefile.am in a new directory (or
one that lacks one).
-# The new directory must be listed in the @c SUBDIRS variable in the
parent directory's Makefile.am:
@code
$ echo 'SUBDIRS += directory' >>../Makefile.am
@endcode
-# Create an bare-bones Makefile.am file in directory that needs it:
@code
$ echo "MAINTAINERCLEANFILES = Makefile.in" >Makefile.am
@endcode
-# The @c configure.in script must be updated, so it generates the required
Makefile when the @a configure script is run by the user:
@verbatim
AC_OUTPUT([
...
path/to/new/Makefile
])
@endverbatim
Note: these instructions are @b not meant to be used literally, rather
they are shown for demonstration purposes.
The default MAINTAINERCLEANFILES rule ensures that the
automake-generated @c Makefile.in file will be removed when developers
run <code>make maintainer-clean</code>. Additional rules may be added
after this; however, the project should bootstrap and tear down cleanly
after taking these minimal steps, with the new directory being visited
during the @c make sequence.
@subsection primerautomaketweaks Updating Makefile.am Files
Adding, removing, and renaming files from the project tree usually
requires updating the autotools inputs. This section will help describe
how to do this as questions arise.
@section primerlibtool Libtool and Libraries
The @c libtool program provides the means of generating libraries in a
portable and painless manner (relatively speaking).
This section will contain an answer to "what does libtool give OpenOCD?"
and "what do developers need to consider in new code?"
@section primerautotoolsmation Autotools Automation
This section outlines three ways the autotools provides automation to
assist with testing and distribution:
- @ref primerautocheck -- automatic unit and smoke tests
- @ref primerautodistcheck -- automatic distribution and packaging tests
@subsection primerautocheck make check
The <code>make check</code> command will run the OpenOCD test suite,
once it has been integrated as such. This section will contain
information about how to extend the testing build system components to
implement new checks.
@subsection primerautodistcheck make distcheck
The <code>make distcheck</code> command produces an archive of the
project deliverables (using <code>make dist</code>) and verifies its
integrity for distribution by attemptng to use the package in the same
manner as a user.
These checks includes the following steps:
-# Unpack the project archive into its expected directory.
-# Configure and build the project in a temporary out-of-tree directory.
-# Run <code>make check</code> to ensure the distributed code passes all tests.
-# Run <code>make install</code> into a temporary installation directory.
-# Check that <code>make uninstall</code> removes all files that were installed.
-# Check that <code>make distclean</code> removes all files created
during all other steps (except the first).
If all of these steps complete successfully, the @c make process will
output a friendly message indicating the archive is ready to be
distributed.
*/
/** @file
This file contains the @ref primerautotools page.
*/

138
debuggers/openocd/doc/manual/primer/commands.txt Normal file
View File

@ -0,0 +1,138 @@
/** @page primercommand Command Development Primer
This page provides a primer for writing commands by introducing @c hello
module. The full source code used in this example can be found in
hello.c, and the @ref primercmdcode section shows how to use it.
A summary of this information can be found in @ref helpercommand .
@section primercmdhandler Command Handlers
Defining new commands and their helpers is easy. The following code
defines a simple command handler that delegates its argument parsing:
@code
COMMAND_HANDLER(handle_hello_command)
{
const char *sep, *name;
int retval = CALL_COMMAND_HANDLER(handle_hello_args);
if (ERROR_OK == retval)
command_print(CMD_CTX, "Greetings%s%s!", sep, name);
return retval;
}
@endcode
Here, the @c COMMAND_HANDLER macro establishes the function signature,
see in command.h by the @c __COMMAND_HANDLER macro.
The COMMAND_HELPER macro function allows defining functions with an
extended version of the base signature. These helper functions can be
called (with the appropriate parameters), the @c CALL_COMMAND_HANDLER
macro to pass any e as parameters to the following helper function:
The subsequent blocks of code are a normal C function that can do
anything, so only complex commands deserve should use comamnd helper
functions. In this respect, this example uses one to demonstrate how --
not when -- they should be used.
@code
static COMMAND_HELPER(handle_hello_args, const char **sep, const char **name)
{
if (argc > 1)
{
LOG_ERROR("%s: too many arguments", CMD_NAME);
return ERROR_COMMAND_SYNTAX_ERROR;
}
if (1 == CMD_ARGC)
{
*sep = ", ";
*name = CMD_ARGV[0];
}
else
*sep = *name = "";
return ERROR_OK;
}
@endcode
Of course, you may also call other macros or functions, but that extends
beyond the scope of this tutorial on writing commands.
@section primercmdreg Command Registration
Before this new function can be used, it must be registered somehow.
For a new module, registering should be done in a new function for
the purpose, which must be called from @c openocd.c:
@code
static const struct command_registration hello_command_handlers[] = {
{
.name = "hello",
.mode = COMMAND_ANY,
.handler = handle_hello_command,
.help = "print a warm greeting",
.usage = "[name]",
},
{
.chain = foo_command_handlers,
}
COMMAND_REGISTRATION_DONE
};
int hello_register_commands(struct command_context_s *cmd_ctx)
{
return register_commands(cmd_ctx, NULL, handle_command_handlers);
}
@endcode
Note that the "usage" text should use the same EBNF that's found
in the User's Guide: literals in 'single quotes', sequences of
optional parameters in [square brackets], and alternatives in
(parentheses|with|vertical bars), and so forth. No angle brackets.
That's it! The command should now be registered and available to scripts.
@section primercmdchain Command Chaining
This example also shows how to chain command handler registration, so
your modules can "inherit" commands provided by other (sub)modules.
Here, the hello module includes the foo commands in the same context
that the 'hello' command will be registered.
If the @c chain field had been put in the 'hello' command, then the
@c foo module commands would be registered under it. Indeed, that
technique is used to define the 'foo bar' and 'foo baz' commands,
as well as for the example drivers that use these modules.
The code for the 'foo' command handlers can be found in @c hello.c.
@section primercmdcode Trying These Example Commands
These commands have been inherited by the dummy interface, faux flash,
and testee target drivers. The easiest way to test these is by using the
dummy interface.
Once OpenOCD has been built with this example code, the following command
demonstrates the abilities that the @c hello module provides:
@code
openocd -c 'interface dummy' \
-c 'dummy hello' \
-c 'dummy hello World' \
-c 'dummy hello {John Doe}' \
-c 'dummy hello John Doe' # error: too many arguments
@endcode
If saved in @c hello.cfg, then running <code>openocd -f hello.cfg</code>
should produce the following output before displaying the help text and
exiting:
@code
Greetings!
Greetings, World!
Greetings, John Doe!
Error: hello: too many arguments
Runtime error, file "openocd.cfg", line 14:
hello: too many arguments
dummy hello [<name>]
prints a warm welcome
@endcode
*/

124
debuggers/openocd/doc/manual/primer/docs.txt Normal file
View File

@ -0,0 +1,124 @@
/** @page primerdocs OpenOCD Documentation Primers
This page provides an introduction to OpenOCD's documentation processes.
OpenOCD presently produces several kinds of documentation:
- The User's Guide:
- Focuses on using the OpenOCD software.
- Details the installation, usage, and customization.
- Provides descriptions of public Jim/TCL script commands.
- Written using GNU texinfo.
- Created with 'make pdf' or 'make html'.
- See @subpage primertexinfo and @ref styletexinfo.
- The References: (as proposed)
- Focuses on using specific hardware with OpenOCD.
- Details the supported interfaces, chips, boards, and targets.
- Provides overview, usage, reference, and FAQ for each device.
- Written using LaTeX language with custom macros.
- Created with 'make references'.
- See @subpage primerlatex and @ref stylelatex.
- The Manual:
- Focuses on developing the OpenOCD software.
- Details the architecutre, driver interfaces, and processes.
- Provides "full" coverage of C source code (work-in-progress).
- Written using Doxygen C language conventions (i.e. in comments).
- Created with 'make doxygen'.
- See @subpage primerdoxygen and @ref styledoxygen.
The following sections provide more information for anyone that wants to
contribute new or updated documentation to the OpenOCD project.
*/
/** @page primertexinfo Texinfo Primer
The OpenOCD User's Guide presently exists entirely within the
doc/openocd.texi document. That file contains documentation with
mark-up suitable for being parsed by the GNU Texinfo utilities
(http://www.gnu.org/software/texinfo/).
When you add a new command, driver, or driver option, it needs to be
documented in the User's Guide. Use the existing documentation for
models, but feel free to make better use of Texinfo mechanisms. See
the Texinfo web site for the Texinfo manual and more information.
OpenOCD style guidelines for Texinfo documentation can be found on the
@ref styletexinfo page.
*/
/** @page primerlatex LaTeX Primer
The OpenOCD project provides a number of reference guides using the
LaTeX typesetting language.
- OpenOCD Quick Reference Sheets
- OpenOCD Hardware Reference Guides
These documents have not yet been produced, so this Primer serves as
a placeholder to describe how they are created and can be extended.
The same holds true for the @ref stylelatex page.
*/
/** @page primerdoxygen Doxygen Primer
Doxygen-style comments are used to provide documentation in-line with
the OpenOCD source code. These comments are used to document functions,
variables, structs, enums, fields, and everything else that might need
to be documented for developers. Additional files containing comments
that supplement the code comments in order to provide complete developer
documentation.
Even if you already know Doxygen, please read this Primer to learn
how OpenOCD developers already use Doxygen features in the project tree.
For more information about OpenOCD's required style for using Doxygen,
see the @ref styledoxygen page and look at existing documentation in the
@c doc/manual tree.
@section primerdoxytext Doxygen Input Files
Doxygen has been configured parse all of the C source code files (*.c
and *.h) in @c src/ in order to produce a complete reference of all
OpenOCD project symbols. In addition to the source code files, other
files will also be scanned for comment blocks; some are referenced
explicitly by the @c INPUT variable in the Doxygen configuration file.
By default, the Doxygen configuration enables a "full" set of features,
including generation of dependency graphs (using the GraphViz package).
These features may be disabled by editing the @c Doxyfile.in file at the
top of the project tree; the configuration file includes comments that
provide detailed documentation for each option.
To support out-of-tree building of the documentation, the @c Doxyfile.in
@c INPUT values will have all instances of the string @c "@srcdir@"
replaced with the current value of the make variable
<code>$(srcdir)</code>. The Makefile uses a rule to convert
@c Doxyfile.in into the @c Doxyfile used by <code>make doxygen</code>.
@section primerdoxyoocd OpenOCD Input Files
OpenOCD uses the @c INPUT mechanism to include additional documentation to
provide The Manual for OpenOCD Developers. These extra files contain
high-level information intended to supplement the relatively low-level
documentation that gets extracted from the source code comments.
OpenOCD's Doxygen configuration file will search for all @c .txt files
that can be found under the @c doc/manual directory in the project tree.
New files containing valid Doxygen markup that are placed in or under
that directory will be detected and included in The Manual automatically.
@section primerdoxyman Doxygen Reference Manual
The full documentation for Doxygen can be referenced on-line at the project
home page: http://www.doxygen.org/index.html. In HTML versions of this
document, an image with a link to this site appears in the page footer.
*/
/** @file
This file contains the Doxygen source code for the @ref primerdocs.
The @ref primerdocs page also contains the following sections:
- @ref primertexinfo
- @ref primerlatex
- @ref primerdoxygen
*/

170
debuggers/openocd/doc/manual/primer/jtag.txt Normal file
View File

@ -0,0 +1,170 @@
/** @page primerjtag OpenOCD JTAG Primer
JTAG is unnecessarily confusing, because JTAG is often confused with
boundary scan, which is just one of its possible functions.
JTAG is simply a communication interface designed to allow communication
to functions contained on devices, for the designed purposes of
initialisation, programming, testing, debugging, and anything else you
want to use it for (as a chip designer).
Think of JTAG as I2C for testing. It doesn't define what it can do,
just a logical interface that allows a uniform channel for communication.
See @par
http://en.wikipedia.org/wiki/Joint_Test_Action_Group
and @par
http://www.inaccessnetworks.com/projects/ianjtag/jtag-intro/jtag-state-machine-large.png
The first page (among other things) shows a logical representation
describing how multiple devices are wired up using JTAG. JTAG does not
specify, data rates or interface levels (3.3V/1.8V, etc) each device can
support different data rates/interface logic levels. How to wire them
in a compatible way is an exercise for an engineer.
Basically TMS controls which shift register is placed on the device,
between TDI and TDO. The second diagram shows the state transitions on
TMS which will select different shift registers.
The first thing you need to do is reset the state machine, because when
you connect to a chip you do not know what state the controller is in,you need
to clock TMS as 1, at least 5 times. This will put you into "Test Logic
Reset" State. Knowing this, you can, once reset, then track what each
transition on TMS will do, and hence know what state the JTAG state
machine is in.
There are 2 "types" of shift registers. The Instruction shift register
and the data shift register. The sizes of these are undefined, and can
change from chip to chip. The Instruction register is used to select
which Data register/data register function is used, and the data
register is used to read data from that function or write data to it.
Each of the states control what happens to either the data register or
instruction register.
For example, one of the data registers will be known as "bypass" this is
(usually) a single bit which has no function and is used to bypass the
chip. Assume we have 3 identical chips, wired up like the picture(wikipedia)
and each has a 3 bits instruction register, and there are 2 known
instructions (110 = bypass, 010 = "some other function") if we want to use
"some other function", on the second chip in the line, and not change
the other chips we would do the following transitions.
From Test Logic Reset, TMS goes:
0 1 1 0 0
which puts every chip in the chain into the "Shift IR state"
Then (while holding TMS as 0) TDI goes:
0 1 1 0 1 0 0 1 1
which puts the following values in the instruction shift register for
each chip [110] [010] [110]
The order is reversed, because we shift out the least significant bit
first. Then we transition TMS:
1 1 1 0 0
which puts us in the "Shift DR state".
Now when we clock data onto TDI (again while holding TMS to 0) , the
data shifts through the data registers, and because of the instruction
registers we selected ("some other function" has 8 bits in its data
register), our total data register in the chain looks like this:
0 00000000 0
The first and last bit are in the "bypassed" chips, so values read from
them are irrelevant and data written to them is ignored. But we need to
write bits for those registers, because they are in the chain.
If we wanted to write 0xF5 to the data register we would clock out of
TDI (holding TMS to 0):
0 1 0 1 0 1 1 1 1 0
Again, we are clocking the least-significant bit first. Then we would
clock TMS:
1 1 0
which updates the selected data register with the value 0xF5 and returns
us to run test idle.
If we needed to read the data register before over-writing it with F5,
no sweat, that's already done, because the TDI/TDO are set up as a
circular shift register, so if you write enough bits to fill the shift
register, you will receive the "captured" contents of the data registers
simultaneously on TDO.
That's JTAG in a nutshell. On top of this, you need to get specs for
target chips and work out what the various instruction registers/data
registers do, so you can actually do something useful. That's where it
gets interesting. But in and of itself, JTAG is actually very simple.
@section primerjtag More Reading
A separate primer contains information about @subpage primerjtagbs for
developers that want to extend OpenOCD for such purposes.
*/
/** @page primerjtagbs JTAG Boundary Scan Primer
The following page provides an introduction on JTAG that focuses on its
boundary scan capabilities: @par
http://www.engr.udayton.edu/faculty/jloomis/ece446/notes/jtag/jtag1.html
OpenOCD does not presently have clear means of using JTAG for boundary
scan testing purposes; however, some developers have explored the
possibilities. The page contains information that may be useful to
those wishing to implement boundary scan capabilities in OpenOCD.
@section primerbsdl The BSDL Language
For more information on the Boundary Scan Description Language (BSDL),
the following page provides a good introduction: @par
http://www.radio-electronics.com/info/t_and_m/boundaryscan/bsdl.php
@section primerbsdlvendors Vendor BSDL Files
NXP LPC: @par
http://www.standardics.nxp.com/support/models/lpc2000/
Freescale PowerPC: @par
http://www.freescale.com/webapp/sps/site/overview.jsp?code=DRPPCBSDLFLS
Freescale i.MX1 (too old): @par
http://www.freescale.com/webapp/sps/site/prod_summary.jsp?code=i.MX1&nodeId=0162468rH311432973ZrDR&fpsp=1&tab=Design_Tools_Tab
Renesas R32C/117: @par
http://sg.renesas.com/fmwk.jsp?cnt=r32c116_7_8_root.jsp&fp=/products/mpumcu/m16c_family/r32c100_series/r32c116_7_8_group/
- The device page does not come with BSDL file; you have to register to
download them. @par
http://www.corelis.com/support/BSDL.htm
TI links theirs right off the generic page for each chip;
this may be the case for other vendors as well. For example:
- DaVinci DM355 -- http://www.ti.com/litv/zip/sprm262b
- DaVinci DM6446
- 2.1 silicon -- http://www.ti.com/litv/zip/sprm325a
- older silicon -- http://www.ti.com/litv/zip/sprm203
- OMAP 3530
- CBB package -- http://www.ti.com/litv/zip/sprm315b
- 515 ball s-PGBA, POP, 0.4mm pitch
- CUS package -- http://www.ti.com/litv/zip/sprm314a
- 515 ball s-PGBA, POP, 0.5mm pitch
- CBC package -- http://www.ti.com/litv/zip/sprm346
- 423 ball s-PGBA, 0.65mm pitch
Many other files are available in the "Semiconductor Manufacturer's BSDL
files" section of the following site: @par
http://www.freelabs.com/~whitis/electronics/jtag/
*/
/** @file
This file contains the @ref primerjtag and @ref primerjtagbs page.
*/

440
debuggers/openocd/doc/manual/primer/tcl.txt Normal file
View File

@ -0,0 +1,440 @@
/** @page primertcl OpenOCD TCL Primer
The @subpage scripting page provides additional TCL Primer material.
@verbatim
****************************************
****************************************
This is a short introduction to 'un-scare' you about the language
known as TCL. It is structured as a guided tour through the files
written by me [Duane Ellis] - in early July 2008 for OpenOCD.
Which uses the "JIM" embedded Tcl clone-ish language.
Thing described here are *totally* TCL generic... not Jim specific.
The goal of this document is to encourage you to add your own set of
chips to the TCL package - and most importantly you should know where
you should put them - so they end up in an organized way.
--Duane Ellis.
duane@duaneellis.com
****************************************
****************************************
Adding "chip" support - Duane Ellis July 5 - 2008.
The concept is this:
In your "openocd.cfg" file add something like this:
source [find tcl/chip/VENDOR/FAMILY/NAME.tcl]
For example...
source [find tcl/chip/atmel/at91/at91sam7x256.tcl]
You'll notice that it makes use of:
tcl/cpu/arm/<NAME>.tcl.
Yes, that is where you should put "core" specific things.
Be careful and learn the difference:
THE "CORE" - is not the entire chip!
Definition:
That "file" listed above is called a "CHIP FILE".
It may be standalone, or may need to "source" other "helper" files.
The reference [7/5/2008] is the at91sam7x256.tcl file.
****************************************
****************************************
=== TCL TOUR ===
Open: at91sam7x256.tcl
=== TCL TOUR ===
A walk through --- For those who are new to TCL.
Examine the file: at91sam7x256.tcl
It starts with:
source [find path/filename.tcl]
In TCL - this is very important.
Rule #1 Everything is a string.
Rule #2 If you think other wise See #1.
Reminds you of:
Rule #1: The wife is correct.
Rule #2: If you think otherwise, See #1
Any text contained inside of [square-brackets]
is just like `back-ticks` in BASH.
Hence, the [find FILENAME] executes the command find with a single
parameter the filename.
========================================
Next you see a series of:
set NAME VALUE
It is mostly "obvious" what is going on.
Exception: The arrays.
You would *THINK* Tcl supports arrays.
In fact, multi-dim arrays. That is false.
For the index for"FLASH(0,CHIPSELECT)" is actually the string
"0,CHIPSELECT". This is problematic. In the normal world, you think
of array indexes as integers.
For example these are different:
set foo(0x0c) 123
set foo(12) 444
Why? Because 0x0c {lowercase} is a string.
Don't forget UPPER CASE.
You must be careful - always... always... use simple decimal
numbers. When in doubt use 'expr' the evaluator. These are all the
same.
set x 0x0c
set foo([expr $x]) "twelve"
set x 12
set foo([expr $x]) "twelve"
set x "2 * 6"
set foo([expr $x]) "twelve"
**************************************************
***************************************************
=== TCL TOUR ===
Open the file: "bitsbytes.tcl"
There is some tricky things going on.
===============
First, there is a "for" loop - at level 0
{level 0 means: out side of a proc/function}
This means it is evaluated when the file is parsed.
== SIDEBAR: About The FOR command ==
In TCL, "FOR" is a funny thing, it is not what you think it is.
Syntactically - FOR is a just a command, it is not language
construct like for(;;) in C...
The "for" command takes 4 parameters.
(1) The "initial command" to execute.
(2) the test "expression"
(3) the "next command"
(4) the "body command" of the FOR loop.
Notice I used the words "command" and "expression" above.
The FOR command:
1) executes the "initial command"
2) evaluates the expression if 0 it stops.
3) executes the "body command"
4) executes the "next command"
5) Goto Step 2.
As show, each of these items are in {curly-braces}. This means they
are passed as they are - KEY-POINT: un evaluated to the FOR
command. Think of it like escaping the backticks in Bash so that the
"under-lying" command can evaluate the contents. In this case, the FOR
COMMAND.
== END: SIDEBAR: About The FOR command ==
You'll see two lines:
LINE1:
set vn [format "BIT%d" $x]
Format is like "sprintf". Because of the [brackets], it becomes what
you think. But here's how:
First - the line is parsed - for {braces}. In this case, there are
none. The, the parser looks for [brackets] and finds them. The,
parser then evaluates the contents of the [brackets], and replaces
them. It is alot this bash statement.
EXPORT vn=`date`
LINE 2 & 3
set $vn [expr (1024 * $x)]
global $vn
In line 1, we dynamically created a variable name. Here, we are
assigning it a value. Lastly Line 3 we force the variable to be
global, not "local" the the "for command body"
===============
The PROCS
proc create_mask { MSB LSB } {
... body ....
}
Like "for" - PROC is really just a command that takes 3 parameters.
The (1) NAME of the function, a (2) LIST of parameters, and a (3) BODY
Again, this is at "level 0" so it is a global function. (Yes, TCL
supports local functions, you put them inside of a function}
You'll see in some cases, I nest [brackets] alot and in others I'm
lazy or wanted it to be more clear... it is a matter of choice.
===============
**************************************************
***************************************************
=== TCL TOUR ===
Open the file: "memory.tcl"
===============
Here is where I setup some 'memory definitions' that various targets can use.
For example - there is an "unknown" memory region.
All memory regions must have 2 things:
(1) N_<name>
(2) NAME( array )
And the array must have some specific names:
( <idx>, THING )
Where: THING is one of:
CHIPSELECT
BASE
LEN
HUMAN
TYPE
RWX - the access ability.
WIDTH - the accessible width.
ie: Some regions of memory are not 'word'
accessible.
The function "address_info" - given an address should
tell you about the address.
[as of this writing: 7/5/2008 I have done
only a little bit with this -Duane]
===
MAJOR FUNCTION:
==
proc memread32 { ADDR }
proc memread16 { ADDR }
proc memread8 { ADDR }
All read memory - and return the contents.
[ FIXME: 7/5/2008 - I need to create "memwrite" functions]
**************************************************
***************************************************
=== TCL TOUR ===
Open the file: "mmr_helpers.tcl"
===============
This file is used to display and work with "memory mapped registers"
For example - 'show_mmr32_reg' is given the NAME of the register to
display. The assumption is - the NAME is a global variable holding the
address of that MMR.
The code does some tricks. The [set [set NAME]] is the TCL way
of doing double variable interpolation - like makefiles...
In a makefile or shell script you may have seen this:
FOO_linux = "Penguins rule"
FOO_winXP = "Broken Glass"
FOO_mac = "I like cat names"
# Pick one
BUILD = linux
#BUILD = winXP
#BUILD = mac
FOO = ${FOO_${BUILD}}
The "double [set] square bracket" thing is the TCL way, nothing more.
----
The IF statement - and "CATCH" .
Notice this IF COMMAND - (not statement) is like this:
[7/5/2008 it is this way]
if ![catch { command } msg ] {
...something...
} else {
error [format string...]
}
The "IF" command expects either 2 params, or 4 params.
=== Sidebar: About "commands" ===
Take a look at the internals of "jim.c"
Look for the function: Jim_IfCoreCommand()
And all those other "CoreCommands"
You'll notice - they all have "argc" and "argv"
Yea, the entire thing is done that way.
IF is a command. SO is "FOR" and "WHILE" and "DO" and the
others. That is why I keep using the phase it is a "command"
=== END: Sidebar: About "commands" ===
Parameter 1 to the IF command is expected to be an expression.
As such, I do not need to wrap it in {braces}.
In this case, the "expression" is the result of the "CATCH" command.
CATCH - is an error catcher.
You give CATCH 1 or 2 parameters.
The first 1st parameter is the "code to execute"
The 2nd (optional) is where to put the error message.
CATCH returns 0 on success, 1 for failure.
The "![catch command]" is self explaintory.
The 3rd parameter to IF must be exactly "else" or "elseif" [I lied
above, the IF command can take many parameters they just have to
be joined by exactly the words "else" or "elseif".
The 4th parameter contains:
"error [format STRING....]"
This lets me modify the previous lower level error by tacking more
text onto the end of it. In this case, i want to add the MMR register
name to make my error message look better.
---------
Back to something inside show_mmr32_reg{}.
You'll see something 'set fn show_${NAME}_helper' Here I am
constructing a 'function name' Then - I look it up to see if it
exists. {the function: "proc_exists" does this}
And - if it does - I call the function.
In "C" it is alot like using: 'sprintf()' to construct a function name
string, then using "dlopen()" and "dlsym()" to look it up - and get a
function pointer - and calling the function pointer.
In this case - I execute a dynamic command. You can do some cool
tricks with interpretors.
----------
Function: show_mmr32_bits()
In this case, we use the special TCL command "upvar" which tcl's way
of passing things by reference. In this case, we want to reach up into
the callers lexical scope and find the array named "NAMES"
The rest of the function is pretty straight forward.
First - we figure out the longest name.
Then print 4 rows of 8bits - with names.
**************************************************
***************************************************
=== TCL TOUR ===
Open the file: "chips/atmel/at91/usarts.tcl"
===============
First - about the AT91SAM series - all of the usarts
are basically identical...
Second - there can be many of them.
In this case - I do some more TCL tricks to dynamically
create functions out of thin air.
Some assumptions:
The "CHIP" file has defined some variables in a proper form.
ie: AT91C_BASE_US0 - for usart0,
AT91C_BASE_US1 - for usart1
... And so on ...
Near the end of the file - look for a large "foreach" loop that
looks like this:
foreach WHO { US0 US1 US2 US3 US4 .... } {
}
In this case, I'm trying to figure out what USARTs exist.
Step 1 - is to determine if the NAME has been defined.
ie: Does AT91C_BASE_USx - where X is some number exist?
The "info exists VARNAME" tells you if the variable exists. Then -
inside the IF statement... There is another loop. This loop is the
name of various "sub-registers" within the USART.
Some more trick are played with the [set VAR] backtick evaluation stuff.
And we create two variables
We calculate and create the global variable name for every subregister in the USART.
And - declare that variable as GLOBAL so the world can find it.
Then - we dynamically create a function - based on the register name.
Look carefully at how that is done. You'll notice the FUNCTION BODY is
a string - not something in {braces}. Why? This is because we need TCL
to evaluate the contents of that string "*NOW*" - when $vn exists not
later, when the function "show_FOO" is invoked.
Lastly - we build a "str" of commands - and create a single function -
with the generated list of commands for the entire USART.
With that little bit of code - I now have a bunch of functions like:
show_US0, show_US1, show_US2, .... etc ...
And show_US0_MR, show_US0_IMR ... etc...
And - I have this for every USART... without having to create tons of
boiler plate yucky code.
****************************************
****************************************
END of the Tcl Intro and Walk Through
****************************************
****************************************
FUTURE PLANS
Some "GPIO" functions...
@endverbatim
*/

465
debuggers/openocd/doc/manual/release.txt Normal file
View File

@ -0,0 +1,465 @@
/** @page releases Release Processes
This page provides an introduction to the OpenOCD Release Processes:
- @ref releasewhy - Explain the motivations for producing
releases on a regular basis.
- @ref releasewho - Describes the responsibilities and
authority required to produce official OpenOCD releases.
- @ref releasewhen - Provides guidelines for scheduling
activities for each release cycle.
- @ref releasehow - Outlines all of the steps for the
processes used to produce and release the package source archives.
- @ref releasescriptcmds - Introduces the automated @c release.sh script.
@section releasewhy Why Produce Releases?
The OpenOCD maintainers produce <i>releases</i> periodically for many
reasons. This section provides the key reasons for making releases on a
regular basis and why a set of <i>release processes</i> should be used
to produce them.
At any time, <i>source archives</i> can be produced by running
<code>make dist</code> in the OpenOCD project tree. With the 0.2.0
release, this command will package the tree into several popular archive
formats: <code>openocd-\<version\>.{tar.gz,tar.bz2,zip}</code>. If
produced properly, these files are suitable for release to the public.
When properly versioned and released for users, these archives present
several important advantages compared to using the source repository
(including snapshots downloaded from that repository using gitweb):
-# They allow others to package and distribute the code using
consistent version labels. Users won't normally need to care
whose package they use, just the version of OpenOCD.
-# They contain a working configure script and makefiles, which
were produced as part of creating the archive.
-# Because they have been formally released by the project, users
don't need to try a random work-in-process revision. Releasing
involves spending some time specifically on quality improvments,
including bugfixing source code and documentation.
-# They provide developers with the flexibility needed to address
larger issues, which sometimes involves temporary breakage.
Hopefully, this shows several good reasons to produce regular releases,
but the release processes were developed with some additional design
goals in mind. Specifically, the releases processes should have the
following properties:
-# Produce successive sets of archives cleanly and consistently.
-# Implementable as a script that automates the critical steps.
-# Prevent human operators from producing broken packages, when possible.
-# Allow scheduling and automation of building and publishing milestones.
The current release processes are documented in the following sections.
They attempt to meet these design goals, but improvements may still
need to be made.
@subsection version_labels Version Labels
Users can display the OpenOCD version string in at least two
ways. The command line <code>openocd -v</code> invocation
displays it; as does the Tcl <code>version</code> command.
Labels for released versions look like <em>0.3.0</em>, or
<em>0.3.0-rc1</em> for a preliminary release.
Non-released (developer) versions look like <em>0.3.0-dev</em>,
or <em>0.3.0-rc1-dev</em>.
In all cases, additional tags may be appended to those base
release version labels.
The <code>tools/release/version.sh</code> script is used to
manipulate version IDs found in the source tree.
@subsubsection releaseversions Release Versions and Tags
The OpenOCD version string is composed of three numeric components
separated by two decimal points: @c x.y.z, where @c x is the @a major
version number, @c y is the @a minor number, and @c z is the @a micro.
For any <em>bug-fix</em> release, the micro version number will be non-zero
(<code>z > 0</code>). For a <i>minor release</i>, the micro version
number will be zero (<code>z = 0</code>). For a <i>major releases</i>,
the minor version will @a also be zero (<code>y = 0, z = 0</code>).
After these required numeric components, release version strings
may contain tags such as as <em>-rc1</em> or <em>-rc2</em>.
These 'rc' tags indicate "release candidate" versions of the package.
Like major/minor/micro numbers, these are updated
as part of the release process.
The release process includes version number manipulations to the tree
being released, ensuring that all numbers are incremented (or rolled
over) at the right time and in the proper locations of the repository.
One of those manipulations creates a repository tag matching that
release's version label.
@subsubsection releaseversionsdist Packager Versions
Distributors of patched versions of OpenOCD are encouraged to extend the
version string with a unique version tag when producing external
releases, as this helps to identify your particular distribution series.
Knowing that a release has such patches can be essential to tracking
down and fixing bugs.
Packager version tags should always be suffixes to the version
code from the OpenOCD project, signifying modifications to the
original code base. Each packager release should have a unique
version.
For example, the following command will add a 'foo' tag to the
configure.ac script of a local copy of the source tree, giving
a version label like <em>0.3.0-foo</em>:
@code
tools/release/version.sh tag add foo
@endcode
This command will modify the configure.ac script in your working copy
only. After running the @c bootstrap sequence, the tree can be patched
and used to produce your own derived versions. You might check that
change into a private branch of your git tree, along with the other
patches you are providing.
You can also "bump" those tags (so "foo1" becomes "foo2" etc)
each time a derived package is released, incrementing the tag's
version to facilitate tracking the changes you have distributed.
@code
tools/release/version.sh bump tag foo
@endcode
Of course, any patches in your branches must be provided to
your customers, and be in conformance with the GPL. In most
cases you should also work to merge your improvements to the
mainline tree.
@subsubsection version_tags Development Versions and Tags
Everything except formal releases should have the tag <em>-dev</em>
in their version number. This helps developers identify reports
created from non-release versions, and it can be detected and
manipulated by the release script. Specifically, this tag will be
removed and re-added during the release process; it should never be
manipulated by developers in submitted patches.
Versions built from developer trees may have additional tags.
Trees built from git snapshots have <em>snapshot</em> tags.
When built from a "live" git tree, tags specify
specific git revisions:
0.3.0-rc1-dev-00015-gf37c9b8-dirty
indicates a development tree based on git revison f37c9b8
(a truncated version of a SHA1 hash) with some non-git
patches applied (the <em>dirty</em> tag). This information
can be useful when tracking down bugs.
(Note that at this writing, the tags do not directly
correspond to <code>git describe</code> output. The
hash ID can be used with <code>git show</code>, but
the relevant repository tag isn't <em>0.3.0-rc1-dev</em>;
this might change in the future.)
@section releasewho Release Manager
OpenOCD archive releases will be produced by an individual filling the
role of <i>Release Manager</i>, hereafter abbreviated as <i>RM</i>. This
individual determines the schedule and executes the release processes
for the community.
@subsection releasewhohow RM Authority
Each release requires one individual to fulfill the RM role; however,
graceful transitions of this authority may take place at any time. The
current RM may transfer their authority to another contributor in a post
to the OpenOCD development mailing list. Such delegation of authority
must be approved by the individual that will receive it and the
community of maintainers. Initial arrangements with the new RM should
be made off-list, as not every contributor wants these responsibilities.
@subsection releasewhowhat RM Responsibilities
In addition to the actual process of producing the releases, the RM is
responsible for keeping the community informed of all progress through
the release cycle(s) being managed. The RM is responsible for managing
the changes to the package version, though the release tools should
manage the tasks of adding or removing any required development branch
tags and incrementing the version.
These responsibilities matter most towards the end of the release
cycle, when the RM creates the first RC and all contributors enter
a quality-improvement mode. The RM works with other contributors
to make sure everyone knows what kinds of fixes should merge, the
status of major issues, and the release timetable.
In particular, the RM has the final decision on whether a given
bug should block the release.
@section releasewhen Release Schedule
The OpenOCD release process must be carried out on a periodic basis, so
the project can realize the benefits presented in answer to the question,
@ref releasewhy.
Starting with the 0.2.0 release, the OpenOCD project expects to produce
new releases every few months.
Bug fix releases could be provided more frequently. These release
schedule goals may be adjusted in the future, after the project
maintainers and distributors receive feedback and experience.
More importantly, the statements made in this section do not create an
obligation by any member of the OpenOCD community to produce new
releases on regular schedule, now or in the future.
@subsection releasewhenexample Sample Schedule
The RM must pro-actively communicate with the community from the
beginning of the development cycle through the delivery of the new
release. This section presents guidelines for scheduling key points
where the community must be informed of changing conditions.
If Tn is the time of release n, then the following schedule
might describe some key T0-to-T1 release cycle milestones.
- T0 ... End of T0 release cycle. T1 cycle starts, with merge
window opening. Developers begin to merge queued work.
- <em>... several weeks of merge window ...</em>
- RC1 ... Close mainline to new work. Produce RC1
release, begin testing phase; developers are in "bugfix mode",
all other work is queued; send out planned endgame schedule.
- RC2 ... Produce RC2 and send schedule update to
mailing list, listing priorities for remaining fixes
- <em>... more RC milestones, until ready ...</em>
- T1: End of T1 release cycle. T2 cycle starts, with merge
window opening. Developers begin to merge queued work.
Note that until it happens, any date for T1 is just a goal.
Critical bugs prevent releases from happening. We are just
beginning to use this window-plus-RCs process, so the lengths
of the merge windows versus the RC phase is subject to change.
Most projects have RC phases of a month or more.
Some additional supplemental communication will be desirable. The above
list omits the step-by-step instructions to daily release management.
Individuals performing release management need to have the ability to
interact proactively with the community as a whole, anticipating when
such interaction will be required and giving ample notification.
The next section explains why the OpenOCD project allows significant
flexibility in the part of the development that precedes the release
process.
@subsection releasewhenflex Schedule Flexibility
The Release Manager should attempt to follow the guidelines in this
document, but the process of scheduling each release milestone should be
community driven at the start. Features that don't complete before
the merge window closes can be held (perhaps in some branch) until
the next merge window opens, rather than delaying the release cycle.
The Release
Manager cannot schedule the work that will be done on the project,
when it will be submitted, reviewed, and deemed suitable to be committed.
That is, the RM cannot act as a priest in a cathedral; OpenOCD uses
the bazaar development model. The release schedule must adapt
continuously in response to changes in the rate of work.
Fewer releases may be
required if developers contribute less patches, and more releases may be
desirable if the project continues to grow and experience high rates of
community contribution. During each cycle, the RM should be tracking
the situation and gathering feedback from the community.
@section releasehow Release Process: Step-by-Step
The release process is not final; it may need more iterations
to work out bugs.
While there are release scripts, key steps require community
support; the Release Manager isn't the only participant.
The following steps should be followed to produce each release:
-# Produce final patches using a local clone of mainline. Nobody
except the RM should be committing anything. <em>Everyone with commit
privileges needs to know and agree to this in advance!</em> Even the RM
only commits a handful of updates as part of the release process
itself ... to files which are part of the version identification scheme
or release process; and to create the version tag; and then to open the
merge window for the next release cycle.
-# Finalize @c the NEWS file to describe the changes in the release
- This file is used to automatically post "blurbs" about the project.
- This material should have been produced during the development cycle,
by adding items for each @c NEWS-worthy contribution, when committed
during the merge window. (One part of closing the merge window, by
opening the RC phase of the release, is the commitment to hold all
further such contributions until the next merge window opens.)
- The RM should make sure nothing important was omitted, as part of
the RC1 cycle. From then on, no more updates to NEWS content should
be needed (except to seed the process for the next release, or maybe
if a significant and longstanding bug is fixed late in the RC phase).
-# Bump library version if our API changed (not yet required)
-# Update and commit the final package version in @c configure.ac:
(The <code>tools/release/version.sh</code> script might help ensure
the versions are named properly.):
-# Remove @c -dev tag.
-# Update any @c -rc tag:
- If producing the final release from an -rc series, remove it
- If producing the first RC in a series, add rc1
- If producing the next RC in a series, bump the rc number
-# Commit that version change, with a good descriptive comment.
-# Create a git tag for the final commit, with a tag name matching
the version string in <code>configure.ac</code> (including <em>-rcN</em>
where relevant):
@verbatim
PACKAGE_VERSION="x.y.z"
PACKAGE_TAG="v${PACKAGE_VERSION}"
git tag -m "The openocd-${PACKAGE_VERSION} release." "${PACKAGE_TAG}"
@endverbatim
-# Do not push those changes to mainline yet; only builds using the
source archives you will be creating should ever be labeled as
official releases (with no "-dev" suffix). Since mainline is a
development tree, these will be pushed later, as part of opening
the merge window for the next release cycle (restoring the "-dev"
suffix for that next release.) Those version and tag updates are
the last ones to be included in the release being made.
-# Produce the release files, using the local clone of the source
tree which holds the release's tag and updated version in
@c configure.ac ... this is used only to produce the release, and
all files should already be properly checked out.
-# Run <code>tools/release.sh package</code> to produce the
source archives. This automatically bootstraps and
configures the process.
-# Run <code>tools/release.sh stage</code> to create an @c archives
directory with the release data, including MD5 and SHA1
checksum files.
-# Sanity check at least one of those archives, by extracting and
configuring its contents, using them to build a copy of OpenOCD,
and verifying that the result prints the correct release version
in its startup banner. (For example,
"configure --enable-ft2232_libftdi --enable-parport"
then "make" and run "src/openocd -v" as a sanity check.)
-# Run <code>make docs</code> to create the
documentation which will be published.
-# Upload packages and post announcements of their availability:
-# Release packages into files section of project sites:
- SF.net:
-# Under "Project Admin", use the "File Manager"
-# Create a new folder under "openocd" named "${PACKAGE_VERSION}"
-# Upload the @c NEWS file and mark it as the release notes.
-# Upload the three source archive files, using the Web interface,
into that folder. Verify the upload worked OK by checking the
MD5 and SHA1 checksums computed by SourceForge against the
versions created as part of staging the release.
-# Also upload doc/openocd.pdf (the User's Guide) so the version
matching each release will be easily available.
-# Select each file in the release, and use the property panel
to set its type and select the right release notes.
- .tar.bz2: Linux, Mac
- .tar.gz: BSD, Solaris, Others
- .zip: Windows
- For openocd.pdf just associate it with the right release notes.
-# Create an SF.net project news update.
-# Depending on how paranoid you're feeling today, verify the images by
downloading them from the websites and making sure there are no
differences between the downloaded copies and your originals.
-# Publish User's and Developer's Guides to the project web sites:
-# Use SCP to update the SF.net web site with PDF and HTML for the
User's Guide, and HTML for the developer's guide ... you can
instantiate a shell.sourceforge.net instance and set up symlinks
from your home directory, to simplify this process.
-# Post announcement e-mail to the openocd-development list.
-# optionally:
-# Post an update on the OpenOCD blog.
-# Announce updates on freshmeat.net and other trackers.
-# Submit updates to news feeds (e.g. Digg, Reddit, etc.).
-# Resume normal development on mainline, by opening the merge window for
the next major or minor release cycle. (You might want to do this
before all the release bits are fully published.)
- Update the version label in the @c configure.ac file:
- Restore @c -dev version tag.
- For a new minor release cycle, increment the release's minor number
- For a new major release cycle, increment the release's major number
and zero its minor number
- Archive @c NEWS file as "<code>doc/news/NEWS-${PACKAGE_VERSION}</code>".
- Create a new @c NEWS file for the next release
- Commit those changes.
- Push all the updates to mainline.
- Last updates for the release, including the release tag (you
will need to "git push --tags").
- Updates opening the merge window
- At this point, it's OK for commiters to start pushing changes
which have been held off until the next release. (Any bugfixes to
this release will be against a bug-fix release branch starting from
the commit you tagged as this release, not mainline.)
- Announce to the openocd-development list. Ideally, you will also
be able to say who is managing the next release cycle.
To start a bug-fix release branch:
-# Create a new branch, starting from a major or
minor release tag
-# Restore @c -dev version tag.
-# Bump micro version number in configure.ac
-# Backport bugfix patches from mainline into that branch.
(Always be sure mainline has the fix first, so it's hard
to just lose a bugfix.)
-# Commit and push those patches.
-# When desired, release as above ... except note that the next
release of a bugfix branch is never a new major or minor release
@subsection releasescriptcmds Release Script Commands
The @c release.sh script automates some of the steps involved
in making releases, simplifying the Release Manager's work.
The release script can be used for two tasks:
- Creating releases and starting a new release cycle:
@code
git checkout master
tools/release.sh --type=minor --final --start-rc release
@endcode
- Creating a development branch from a tagged release:
@code
git checkout 'v0.2.0'
tools/release.sh --type=micro branch
@endcode
Both of these variations make automatic commits and tags in your
repository, so you should be sure to run it on a cloned copy before
proceding with a live release.
@subsection releasescriptopts Release Script Options
The @c release.sh script recognizes some command-line options that
affect its behavior:
- The @c --start-rc indicates that the new development release cycle
should start with @c -rc0. Without this, the @c -rc tag will be omitted,
leading to non-monotonic versioning of the in-tree version numbers.
- The @c --final indicates that the release should drop the @c -rc tag,
to going from @c x.y.z-rcN-dev to x.y.z.
@subsection releasescriptenv Release Script Environment
The @c release.sh script recognizes some environment variables which
affect its behavior:
- @c CONFIG_OPTS : Passed as options to the configure script.
- @c MAKE_OPTS : Passed as options to the 'make' processes.
@section releasetutorial Release Tutorials
This section should contain a brief tutorial for using the Release
Script to perform release tasks, but the new script needs to be
used for 0.3.0.
@section releasetodo Release Script Shortcomings
Improved automated packaging and distribution of OpenOCD requires more
patching of the configure script. The final release script should be
able to manage most steps of the processes. The steps requiring user
input could be guided by an "assistant" that walks the Release Manager
through the process from beginning to end, performing basic sanity
checks on their various inputs (e.g. the @c NEWS blurb).
*/
/** @file
This file contains the @ref releases page.
*/

80
debuggers/openocd/doc/manual/scripting.txt Normal file
View File

@ -0,0 +1,80 @@
/** @page scripting Scripting Overview
@section scriptingisnt What scripting will not do
The scripting support is intended for developers of OpenOCD.
It is not the intention that normal OpenOCD users will
use tcl scripting extensively, write lots of clever scripts,
or contribute back to OpenOCD.
Target scripts can contain new procedures that end users may
tinker to their needs without really understanding tcl.
Since end users are not expected to mess with the scripting
language, the choice of language is not terribly important
to those same end users.
Jim Tcl was chosen as it was easy to integrate, works
great in an embedded environment and Øyvind Harboe
had experience with it.
@section scriptinguses Uses of scripting
Default implementation of procedures in tcl/procedures.tcl.
- Polymorphic commands for target scripts.
- there will be added some commands in Tcl that the target
scripts can replace.
- produce \<productionfile\> \<serialnumber\>. Default implementation
is to ignore serial number and write a raw binary file
to beginning of first flash. Target script can dictate
file format and structure of serialnumber. Tcl allows
an argument to consist of e.g. a list so the structure of
the serial number is not limited to a single string.
- reset handling. Precise control of how srst, trst &
tms is handled.
- replace some parts of the current command line handler.
This is only to simplify the implementation of OpenOCD
and will have no externally visible consequences.
Tcl has an advantage in that it's syntax is backwards
compatible with the current OpenOCD syntax.
- external scripting. Low level tcl functions will be defined
that return machine readable output. These low level tcl
functions constitute the tcl api. flash_banks is such
a low level tcl proc. "flash banks" is an example of
a command that has human readable output. The human
readable output is expected to change inbetween versions
of OpenOCD. The output from flash_banks may not be
in the preferred form for the client. The client then
has two choices a) parse the output from flash_banks
or b) write a small piece of tcl to output the
flash_banks output to a more suitable form. The latter may
be simpler.
@section scriptingexternal External scripting
The embedded Jim Tcl interpreter in OpenOCD is very limited
compared to any full scale PC hosted scripting language.
The goal is to keep the internal Jim Tcl interpreter as
small as possible and allow any advanced scripting,
especially scripting that interacts with the host,
run on the host and talk to OpenOCD via the TCP/IP
scripting connection.
Another problem with Jim Tcl is that there is no debugger
for it.
With a bit of trickery it should be possible to run Jim
Tcl scripts under a Tcl interpreter on a PC. The advantage
would be that the Jim Tcl scripts could be debugged using
a standard PC Tcl debugger.
The rough idea is to write an unknown proc that sends
unknown commands to OpenOCD.
Basically a PC version of startup.tcl. Patches most
gratefully accepted! :-)
*/

316
debuggers/openocd/doc/manual/server.txt Normal file
View File

@ -0,0 +1,316 @@
/** @page serverdocs OpenOCD Server APIs
OpenOCD provides support for implementing different types of servers.
Presently, the following servers have APIs that can be used.
- @subpage servergdb
- @subpage servertelnet
- @subpage serverhttp
@section serverdocsoverview Overview
What follows is a development history, and describes some of the intent
of why certain features exist within OpenOCD along with the reasoning
behind them.
This roadmap section was written May 2009 - about 9 to 12 months
after some of this work had started, it attempts to document some of
the reasons why certain features exist within OpenOCD at that time.
@section serverdocsbg Background
In early 2008, Oyvind Harboe and Duane Ellis had talked about how to
create a reasonable GUI for OpenOCD - something that is non-invasive,
simple to use and maintain, and does not tie OpenOCD to many other
packages. It would be wrong to "spider web" requirements into other
external external packages. That makes it difficult for developers to
write new code and creates a support nightmare.
In many ways, people had talked about the need for some type of
high-level interface to OpenOCD, because they only had two choices:
- the ability to script: via an external program the actions of OpenOCD.
- the ablity to write a complex internal commands: native 'commands'
inside of OpenOCD was complicated.
Fundamentally, the basic problem with both of those would be solved
with a script language:
-# <b>Internal</b>: simple, small, and self-contained.
-# <b>Cross Language</b>: script friendly front-end
-# <b>Cross Host</b>: GUI Host interface
-# <b>Cross Debugger</b>: GUI-like interface
What follows hopefully shows how the plans to solve these problems
materialized and help to explain the grand roadmap plan.
@subsection serverdocsjim Why JimTCL? The Internal Script Language
At the time, the existing "command context schema" was proving itself
insufficient. However, the problem was also considered from another
direction: should OpenOCD be first class and the script second class?
Which one rules?
In the end, OpenOCD won, the conclusion was that simpler will be better.
Let the script language be "good enough"; it would not need numerous
features. Imagine debugging an embedded Perl module while debugging
OpenOCD. Yuck. OpenOCD already has a complex enough build system, why
make it worse?
The goal was to add a simple language that would be moderately easy to
work with and be self-contained. JimTCL is a single C and single H
file, allowing OpenOCD to avoid the spider web of dependent packages.
@section serverdocstcl TCL Server Port
The TCL Server port was added in mid-2008. With embedded TCL, we can
write scripts internally to help things, or we can write "C" code that
interfaces well with TCL.
From there, the developers wanted to create an external front-end that
would be @a very usable and that that @a any language could utilize,
allowing simple front-ends to be (a) cross-platform (b) languag
agnostic, and (c) easy to develop and use.
Simple ASCII protocols are easy. For example, HTTP, FTP (control), and
SMTP are all text-based. All of these examples are widely and
well-known, and they do not require high-speed or high-volume. They
also support a high degree of interoperability with multiple systems.
They are not human-centric protocols; more correctly, they are rigid,
terse, simple ASCII protocols that are emensely parsable by a script.
Thus, the TCL server -- a 'machine' type socket interface -- was added
with the hope was it would output simple "name-value" pair type
data. At the time, simple name/value pairs seemed reasonably easier to
do at the time, though Maybe it should output JSON;
See here:
http://www.mail-archive.com/openocd-development%40lists.berlios.de/msg00248.html
The hope was that one could write a script in what ever language you want
and do things with it!
@section serverdocsgui GUI Like Interfaces
A lot has been said about various "widigit-foo-gui-library is so
wonderful". Please refer back to the domino and spider web problem of
dependencies. Sure, you may well know the WhatEver-GUI library, but
most others will not (including the next contributer to OpenOCD).
How do we solve that problem?
For example, Cygwin can be painful, Cygwin GUI packages want X11
to be present, crossing the barrier between MinGW and Cygwin is
painful, let alone getting the GUI front end to work on MacOS, and
Linux, yuck yuck yuck. Painful. very very painful.
What works easier and is less work is what is already present in every
platform? The answer: A web browser. In other words, OpenOCD could
serve out embedded web pages via "localhost" to your browser.
Long before OpenOCD had a TCL command line, Zylin AS built their ZY1000
devince with a built-in HTTP server. Later, they were willing to both
contribute and integrate most of that work into the main tree.
@subsection serverdocsother Other Options Considered
What if a web browser is not acceptable ie: You want to write your own
front gadget in Eclipse, or KDevelop, or PerlTK, Ruby, or what ever
the latest and greatest Script De Jour is.
- Option 1: Can we transport this extra data through the GDB server
protocol? In other words, can we extend the GDB server protocol?
No, Eclipse wants to talk to GDB directly and control the GDB port.
- Option 2: SWIG front end (libopenocd): Would that work?
That's painful - unless you design your api to be very simplistic -
every language has it's own set of wack-ness, parameter marshaling is
painful.
What about "callbacks" and structures, and other mess. Imagine
debugging that system. When JimTCL was introduced Spencer Oliver had
quite a few well-put concerns (Summer 2008) about the idea of "TCL"
taking over OpenOCD. His concern is and was: how do you debug
something written in 2 different languages? A "SWIG" front-end is
unlikely to help that situation.
@subsection serverdoccombined Combined: Socket & WebServer Benifits
Seriously think about this question: What script language (or compiled
language) today cannot talk directly to a socket? Every thing in the
OpenOCD world can work a socket interface. Any host side tool can talk
to Localhost or remote host, however one might want to make it work.
A socket interface is very simple. One could write a Java application
and serve it out via the embedded web server, could it - or something
like it talk to the built in TCL server? Yes, absolutely! We are on to
something here.
@subsection serverdocplatforms Platform Permuntations
Look at some permutations where OpenOCD can run; these "just work" if
the Socket Approach is used.
- Linux/Cygwin/MinGw/MacOSx/FreeBSD development Host Locally
- OpenOCD with some dongle on that host
- Linux/Cygwin/MingW/MacOS/FreeBSD development host
- DONGLE: tcpip based ARM-Linux perhaps at91rm9200 or ep93xx.c, running openocd.
- Windows cygwin/X desktop environment.
- Linux development host (via remote X11)
- Dongle: "eb93xx.c" based linux board
@subsection serverdocfuture Development Scale Out
During 2008, Duane Ellis created some TCL scripts to display peripheral
register contents. For example, look at the sam7 TCL scripts, and the
stm32 TCL scripts. The hope was others would create more.
A good example of this is display/view the peripheral registers on
your embedded target. Lots of commercial embedded debug tools have
this, some can show the TIMER registers, the interrupt controller.
What if the chip companies behind STM32, or PIC32, AT91SAM chips -
wanted to write something that makes working with their chip better,
easier, faster, etc.
@a Question: How can we (the OpenOCD group) make that really fancy
stuff across multiple different host platforms?
Remember: OpenOCD runs on:
-# Linux via USB,
-# ARM Linux - bit-banging GPIO pins
-# MacOSX
-# FreeBSD
-# Cygwin
-# MinGW32
-# Ecos
How can we get that to work?
@subsection serverdocdebug What about Debugger Plugins?
Really GDB is nice, it works, but it is not a good embedded debug tool.
OpenOCD cannot work in a GUI when one cannot get to its command line.
Some GDB front-end developers have pedantic designs that refuse any and
all access to the GDB command line (e.g. http://www.kdbg.org/todo.php).
The TELNET interface to OpenOCD works, but the intent of that interface
is <b>human interaction</b>. It must remain available, developers depend
upon it, sometimes that is the only scheme available.
As a small group of developers, supporting all the platforms and
targets in the debugger will be difficult, as there are enough problem
with the plethora of Adapters, Chips, and different target boards.
Yes, the TCL interface might be suitable, but it has not received much
love or attention. Perhaps it will after you read and understand this.
One reason might be, this adds one more host side requirement to make
use of the feature. In other words, one could write a Python/TK
front-end, but it is only useable if you have Python/TK installed.
Maybe this can be done via Ecllipse, but not all developers use Ecplise.
Many devlopers use Emacs (possibly with GUD mode) or vim and will not
accept such an interface. The next developer reading this might be
using Insight (GDB-TK) - and somebody else - DDD..
There is no common host-side GDB front-end method.
@section serverdocschallenge Front-End Scaling
Maybe we are wrong - ie: OpenOCD + some TK tool
Remember: OpenOCD is often (maybe 99.9%) of the time used with
GDB-REMOTE. There is always some front-end package - be it command-line
GDB under DDD, Eclipse, KDevelop, Emacs, or some other package
(e.g. IAR tools can talk to GDB servers). How can the OpenOCD
developers make that fancy target display GUI visible under 5 to 10
different host-side GDB..
Sure - a <em>man on a mission</em> can make that work. The GUI might be
libopenocd + Perl/TK, or maybe an Eclipse Plug-in.
That is a development support nightmare for reasons described
above. We have enough support problems as it is with targets, adapters,
etc.
@section serverdocshttpbg HTTP Server Background
OpenOCD includes an HTTP server because most development environments
are likely contain a web browser. The web browser can talk to OpenOCD's
HTTP server and provide a high-level interfaces to the program.
Altogether, it provides a universally accessible GUI for OpenOCD.
@section serverdocshtml Simple HTML Pages
There is (or could be) a simple "Jim TCL" function to read a memory
location. If that can be tied into a TCL script that can modify the
HTTP text, then we have a simple script-based web server with a JTAG
engine under the hood.
Imagine a web page - served from a small board with two buttons:
"LED_ON" and "LED_OFF", each click - turns the LED on or OFF, a very
simplistic idea. Little boards with web servers are great examples of
this: Ethernut is a good example and Contiki (not a board, an embedded
OS) is another example.
One could create a simple: <b>Click here to display memory</b> or maybe
<b>click here to display the UART REGISTER BLOCK</b>; click again and see
each register explained in exquisit detail.
For an STM32, one could create a simple HTML page, with simple
substitution text that the simple web server use to substitute the
HTML text JIMTCL_PEEK32( 0x12345678 ) with the value read from
memory. We end up with an HTML page that could list the contents of
every peripheral register on the target platform.
That also is transportable, regardless of the OpenOCD host
platform: Linux/X86, Linux/ARM, FreeBSD, Cygwin, MingW, or MacOSX.
You could even port OpenOCD to an Android system and use it as a
bit-banging JTAG Adapter serving web pages.
@subsection serverdocshtmladv Advanced HTML Pages
Java or JavaScript could be used to talk back to the TCL port. One
could write a Java, AJAX, FLASH, or some other developer friendly
toolbox and get a real cross-platform GUI interface. Sure, the interface
is not native - but it is 100% cross-platform!
OpenOCD current uses simple HTML pages; others might be an Adobe FLASH
expert, or a Java Expert. These possibilities could allow the pages
remain cross-platform but still provide a rich user-interface
experience.
Don't forget it can also be very simple, exactly what one developer
can contribute, a set of very simple web pages.
@subsection serverdocshtmlstatus HTTP/HTML Status
As of May 2009, much of the HTML pages were contributed by Zylin AS,
hence they continue to retain some resemblance to the ZY1000 interface.
Patches would be welcome to move these parts of the system forward.
*/
/** @page servergdb OpenOCD GDB Server API
This section needs to be expanded.
*/
/** @page servertelnet OpenOCD Telnet Server API
This section needs to be expanded.
*/
/** @page serverhttp OpenOCD http Server API
This section needs to be expanded.
*/

403
debuggers/openocd/doc/manual/style.txt Normal file
View File

@ -0,0 +1,403 @@
/** @page styleguide Style Guides
The goals for each of these guides are:
- to produce correct code that appears clean, consistent, and readable,
- to allow developers to create patches that conform to a standard, and
- to eliminate these issues as points of future contention.
Some of these rules may be ignored in the spirit of these stated goals;
however, such exceptions should be fairly rare.
The following style guides describe a formatting, naming, and other
conventions that should be followed when writing or changing the OpenOCD
code:
- @subpage styletcl
- @subpage stylec
- @subpage styleperl
- @subpage styleautotools
In addition, the following style guides provide information for
providing documentation, either as part of the C code or stand-alone.
- @subpage styledoxygen
- @subpage styletexinfo
- @subpage stylelatex
Feedback would be welcome to improve the OpenOCD guidelines.
*/
/** @page styletcl TCL Style Guide
OpenOCD needs to expand its Jim/TCL Style Guide.
Many of the guidelines listed on the @ref stylec page should apply to
OpenOCD's Jim/TCL code as well.
*/
/** @page stylec C Style Guide
This page contains guidelines for writing new C source code for the
OpenOCD project.
@section styleformat Formatting Guide
- remove any trailing white space at the end of lines.
- use TAB characters for indentation; do NOT use spaces.
- displayed TAB width is 4 characters.
- use Unix line endings ('\\n'); do NOT use DOS endings ('\\r\\n')
- limit adjacent empty lines to at most two (2).
- remove any trailing empty lines at the end of source files
- do not "comment out" code from the tree; instead, one should either:
-# remove it entirely (git can retrieve the old version), or
-# use an @c \#if/\#endif block.
Finally, try to avoid lines of code that are longer than than 72-80 columns:
- long lines frequently indicate other style problems:
- insufficient use of static functions, macros, or temporary variables
- poor flow-control structure; "inverted" logical tests
- a few lines may be wider than this limit (typically format strings), but:
- all C compilers will concatenate series of string constants.
- all long string constants should be split across multiple lines.
@section stylenames Naming Rules
- most identifiers must use lower-case letters (and digits) only.
- macros must use upper-case letters (and digits) only.
- OpenOCD identifiers should NEVER use @c MixedCaps.
- @c typedef names must end with the '_t' suffix.
- This should be reserved for types that should be passed by value.
- Do @b not mix the typedef keyword with @c struct.
- use underline characters between consecutive words in identifiers
(e.g. @c more_than_one_word).
@section stylec99 C99 Rules
- inline functions
- @c // comments -- in new code, prefer these for single-line comments
- trailing comma allowed in enum declarations
- designated initializers ( .field = value )
- variables declarations should occur at the point of first use
- new block scopes for selection and iteration statements
- use malloc() to create dynamic arrays. Do @b not use @c alloca
or variable length arrays on the stack. non-MMU hosts(uClinux) and
pthreads require modest and predictable stack usage.
@section styletypes Type Guidelines
- use native types (@c int or @c unsigned) if the type is not important
- if size matters, use the types from \<stdint.h\> or \<inttypes.h\>:
- @c int8_t, @c int16_t, @c int32_t, or @c int64_t: signed types of specified size
- @c uint8_t, @c uint16_t, @c uint32_t, or @c uint64_t: unsigned types of specified size
- do @b NOT redefine @c uN types from "types.h"
@section stylefunc Functions
- static inline functions should be prefered over macros:
@code
/** do NOT define macro-like functions like this... */
#define CUBE(x) ((x) * (x) * (x))
/** instead, define the same expression using a C99 inline function */
static inline int cube(int x) { return x * x * x; }
@endcode
- Functions should be declared static unless required by other modules
- define static functions before first usage to avoid forward declarations.
- Functions should have no space between its name and its parameter list:
@code
int f(int x1, int x2)
{
...
int y = f(x1, x2 - x1);
...
}
@endcode
- Separate assignment and logical test statements. In other words, you
should write statements like the following:
@code
// separate statements should be preferred
result = foo();
if (ERROR_OK != result)
...
@endcode
More directly, do @b not combine these kinds of statements:
@code
// Combined statements should be avoided
if (ERROR_OK != (result = foo()))
return result;
@endcode
*/
/** @page styledoxygen Doxygen Style Guide
The following sections provide guidelines for OpenOCD developers
who wish to write Doxygen comments in the code or this manual.
For an introduction to Doxygen documentation,
see the @ref primerdoxygen.
@section styledoxyblocks Doxygen Block Selection
Several different types of Doxygen comments can be used; often,
one style will be the most appropriate for a specific context.
The following guidelines provide developers with heuristics for
selecting an appropriate form and writing consistent documentation
comments.
-# use @c /// to for one-line documentation of instances.
-# for documentation requiring multiple lines, use a "block" style:
@verbatim
/**
* @brief First sentence is short description. Remaining text becomes
* the full description block, where "empty" lines start new paragraphs.
*
* One can make text appear in @a italics, @b bold, @c monospace, or
* in blocks such as the one in which this example appears in the Style
* Guide. See the Doxygen Manual for the full list of commands.
*
* @param foo For a function, describe the parameters (e.g. @a foo).
* @returns The value(s) returned, or possible error conditions.
*/
@endverbatim
-# The block should start on the line following the opening @c /**.
-# The end of the block, \f$*/\f$, should also be on its own line.
-# Every line in the block should have a @c '*' in-line with its start:
- A leading space is required to align the @c '*' with the @c /** line.
- A single "empty" line should separate the function documentation
from the block of parameter and return value descriptions.
- Except to separate paragraphs of documentation, other extra
"empty" lines should be removed from the block.
-# Only single spaces should be used; do @b not add mid-line indentation.
-# If the total line length will be less than 72-80 columns, then
- The @c /**< form can be used on the same line.
- This style should be used sparingly; the best use is for fields:
@code int field; /**< field description */ @endcode
@section styledoxyall Doxygen Style Guide
The following guidelines apply to all Doxygen comment blocks:
-# Use the @c '\@cmd' form for all doxygen commands (do @b not use @c '\\cmd').
-# Use symbol names such that Doxygen automatically creates links:
-# @c function_name() can be used to reference functions
(e.g. flash_set_dirty()).
-# @c struct_name::member_name should be used to reference structure
fields in the documentation (e.g. @c flash_driver::name).
-# URLS get converted to markup automatically, without any extra effort.
-# new pages can be linked into the heirarchy by using the @c \@subpage
command somewhere the page(s) under which they should be linked:
-# use @c \@ref in other contexts to create links to pages and sections.
-# Use good Doxygen mark-up:
-# '\@a' (italics) should be used to reference parameters (e.g. <i>foo</i>).
-# '\@b' (bold) should be used to emphasizing <b>single</b> words.
-# '\@c' (monospace) should be used with <code>file names</code> and
<code>code symbols</code>, so they appear visually distinct from
surrounding text.
-# To mark-up multiple words, the HTML alternatives must be used.
-# Two spaces should be used when nesting lists; do @b not use '\\t' in lists.
-# Code examples provided in documentation must conform to the Style Guide.
@section styledoxytext Doxygen Text Inputs
In addition to the guidelines in the preceding sections, the following
additional style guidelines should be considered when writing
documentation as part of standalone text files:
-# Text files must contain Doxygen at least one comment block:
-# Documentation should begin in the first column (except for nested lists).
-# Do NOT use the @c '*' convention that must be used in the source code.
-# Each file should contain at least one @c \@page block.
-# Each new page should be listed as a \@subpage in the \@page block
of the page that should serve as its parent.
-# Large pages should be structure in parts using meaningful \@section
and \@subsection commands.
-# Include a @c \@file block at the end of each Doxygen @c .txt file to
document its contents:
- Doxygen creates such pages for files automatically, but no content
will appear on them for those that only contain manual pages.
- The \@file block should provide useful meta-documentation to assist
techincal writers; typically, a list of the pages that it contains.
- For example, the @ref styleguide exists in @c doc/manual/style.txt,
which contains a reference back to itself.
-# The \@file and \@page commands should begin on the same line as
the start of the Doxygen comment:
@verbatim
/** @page pagename Page Title
Documentation for the page.
*/
/** @file
This file contains the @ref pagename page.
*/
@endverbatim
For an example, the Doxygen source for this Style Guide can be found in
@c doc/manual/style.txt, alongside other parts of The Manual.
*/
/** @page styletexinfo Texinfo Style Guide
The User's Guide is there to provide two basic kinds of information. It
is a guide for how and why to use each feature or mechanism of OpenOCD.
It is also the reference manual for all commands and options involved
in using them, including interface, flash, target, and other drivers.
At this time, it is the only user-targetted documentation; everything
else is addressing OpenOCD developers.
There are two key audiences for the User's Guide, both developer based.
The primary audience is developers using OpenOCD as a tool in their
work, or who may be starting to use it that way. A secondary audience
includes developers who are supporting those users by packaging or
customizing it for their hardware, installing it as part of some software
distribution, or by evolving OpenOCD itself. There is some crossover
between those audiences. We encourage contributions from users as the
fundamental way to evolve and improve OpenOCD. In particular, creating
a board or target specific configuration file is something that many
users will end up doing at some point, and we like to see such files
become part of the mainline release.
General documentation rules to remember include:
- Be concise and clear. It's work to remove those extra words and
sentences, but such "noise" doesn't help readers.
- Make it easy to skim and browse. "Tell what you're going to say,
then say it". Help readers decide whether to dig in now, or
leave it for later.
- Make sure the chapters flow well. Presentations should not jump
around, and should move easily from overview down to details.
- Avoid using the passive voice.
- Address the reader to clarify roles ("your config file", "the board you
are debugging", etc.); "the user" (etc) is artificial.
- Use good English grammar and spelling. Remember also that English
will not be the first language for many readers. Avoid complex or
idiomatic usage that could create needless barriers.
- Use examples to highlight fundamental ideas and common idioms.
- Don't overuse list constructs. This is not a slide presentation;
prefer paragraphs.
When presenting features and mechanisms of OpenOCD:
- Explain key concepts before presenting commands using them.
- Tie examples to common developer tasks.
- When giving instructions, you can \@enumerate each step both
to clearly delineate the steps, and to highlight that this is
not explanatory text.
- When you provide "how to use it" advice or tutorials, keep it
in separate sections from the reference material.
- Good indexing is something of a black art. Use \@cindex for important
concepts, but don't overuse it. In particular, rely on the \@deffn
indexing, and use \@cindex primarily with significant blocks of text
such as \@subsection. The \@dfn of a key term may merit indexing.
- Use \@xref (and \@anchor) with care. Hardcopy versions, from the PDF,
must make sense without clickable links (which don't work all that well
with Texinfo in any case). If you find you're using many links,
read that as a symptom that the presentation may be disjointed and
confusing.
- Avoid font tricks like \@b, but use \@option, \@file, \@dfn, \@emph
and related mechanisms where appropriate.
For technical reference material:
- It's OK to start sections with explanations and end them with
detailed lists of the relevant commands.
- Use the \@deffn style declarations to define all commands and drivers.
These will automatically appear in the relevant index, and those
declarations help promote consistent presentation and style.
- It's a "Command" if it can be used interactively.
- Else it's a "Config Command" if it must be used before the
configuration stage completes.
- For a "Driver", list its name.
- Use EBNF style regular expressions to define parameters:
brackets around zero-or-one choices, parentheses around
exactly-one choices.
- Use \@option, \@file, \@var and other mechanisms where appropriate.
- Say what output it displays, and what value it returns to callers.
- Explain clearly what the command does. Sometimes you will find
that it can't be explained clearly. That usually means the command
is poorly designed; replace it with something better, if you can.
- Be complete: document all commands, except as part of a strategy
to phase something in or out.
- Be correct: review the documentation against the code, and
vice versa.
- Alphabetize the \@defn declarations for all commands in each
section.
- Keep the per-command documentation focussed on exactly what that
command does, not motivation, advice, suggestions, or big examples.
When commands deserve such expanded text, it belongs elsewhere.
Solutions might be using a \@section explaining a cluster of related
commands, or acting as a mini-tutorial.
- Details for any given driver should be grouped together.
The User's Guide is the first place most users will start reading,
after they begin using OpenOCD. Make that investment of their time
be as productive as possible. Needing to look at OpenOCD source code,
to figure out how to use it is a bad sign, though it's OK to need to
look at the User's guide to figure out what a config script is doing.
*/
/** @page stylelatex LaTeX Style Guide
This page needs to provide style guidelines for using LaTeX, the
typesetting language used by The References for OpenOCD Hardware.
Likewise, the @ref primerlatex for using this guide needs to be completed.
*/
/** @page styleperl Perl Style Guide
This page provides some style guidelines for using Perl, a scripting
language used by several small tools in the tree:
-# Ensure all Perl scripts use the proper suffix (@c .pl for scripts, and
@c .pm for modules)
-# Pass files as script parameters or piped as input:
- Do NOT code paths to files in the tree, as this breaks out-of-tree builds.
- If you must, then you must also use an automake rule to create the script.
-# use @c '#!/usr/bin/perl' as the first line of Perl scripts.
-# always <code>use strict</code> and <code>use warnings</code>
-# invoke scripts indirectly in Makefiles or other scripts:
@code
perl script.pl
@endcode
Maintainers must also be sure to follow additional guidelines:
-# Ensure that Perl scripts are committed as executables:
Use "<code>chmod +x script.pl</code>"
@a before using "<code>git add script.pl</code>"
*/
/** @page styleautotools Autotools Style Guide
This page contains style guidelines for the OpenOCD autotools scripts.
The following guidelines apply to the @c configure.ac file:
- Better guidelines need to be developed, but until then...
- Use good judgement.
The following guidelines apply to @c Makefile.am files:
-# When assigning variables with long lists of items:
-# Separate the values on each line to make the files "patch friendly":
@code
VAR = \
value1 \
value2 \
...
value9 \
value10
@endcode
*/
/** @file
This file contains the @ref styleguide pages. The @ref styleguide pages
include the following Style Guides for their respective code and
documentation languages:
- @ref styletcl
- @ref stylec
- @ref styledoxygen
- @ref styletexinfo
- @ref stylelatex
- @ref styleperl
- @ref styleautotools
*/

46
debuggers/openocd/doc/manual/target.txt Normal file
View File

@ -0,0 +1,46 @@
/** @page targetdocs OpenOCD Target APIs
OpenOCD provides its Target APIs to allow developers to provide trace and
debugging support for specific device targets. These primarily consist of
ARM cores, but other types have been supported. New targets should be
developed by following or using these APIs.
The Target Support module contains APIs that cover several functional areas:
- @subpage targetarm
- @subpage targetnotarm
- @subpage targetmips
- @subpage targetregister
- @subpage targetimage
- @subpage targettrace
This section needs to be expanded.
*/
/** @page targetarm OpenOCD ARM Targets
This section needs to describe OpenOCD's ARM target support.
*/
/** @page targetregister OpenOCD Target Register API
This section needs to describe OpenOCD's Target Register API, as
provided by 'src/target/register.h'.
*/
/** @page targetimage OpenOCD Target Image API
This section needs to describe OpenOCD's Target Image API, as provided
by 'src/target/image.h'.
*/
/** @page targettrace OpenOCD Target Trace API
This section needs to describe OpenOCD's Target Trace API, as provided
by 'src/target/trace.h'.
*/

536
debuggers/openocd/doc/manual/target/mips.txt Normal file
View File

@ -0,0 +1,536 @@
/** @page targetmips OpenOCD MIPS Targets
@section ejatgmem EJTAG Memory Addresses
An optional uncached and unmapped debug segment dseg (EJTAG area) appears in the address range
0xFFFF FFFF FF20 0000 to 0xFFFF FFFF FF3F FFFF. The dseg segment thereby appears in the kseg part of the
compatibility segment, and access to kseg is possible with the dseg segment.
The dseg segment is subdivided into dmseg (EJTAG memory) segment and the drseg (EJTAG registers) segment. The
dmseg segment is used when the probe services the memory segment. The drseg segment is used when the
memory-mapped debug registers are accessed. Table 5-2 shows the subdivision and attributes for the segments.
dseg is divided in :
- dmseg (0xFFFF FFFF FF20 0000 to 0xFFFF FFFF FF2F FFFF)
- drseg (0xFFFF FFFF FF30 0000 to 0xFFFF FFFF FF3F FFFF)
Because the dseg segment is serviced exclusively by the EJTAG features, there
are no physical address per se. Instead the lower 21 bits of the virtual address select
the appropriate reference in either EJTAG memory or registers. References are not mapped through the
TLB, nor do the accesses appear on the external system memory interface.
Both of this memory segments are Uncached.
On debug exception (break) CPU jumps to the beginning of dmseg. This some kind of memory shared
between CPU and EJTAG dongle.
There CPU stops (correct terminology is : stalls, because it stops it's pipeline), and is waiting for some action of dongle.
If the dongle gives it instruction, CPU executes it, augments it's PC to 0xFFFF FFFF FF20 0001 - but it again points to dmseg area,
so it stops waiting for next instruction.
This will all become clear later, after reading following prerequisite chapters.
@section impflags Important flags
@subsection pnnw PNnW
Indicates read or write of a pending processor access:
- 0 : Read processor access, for a fetch/load access
- 1 : Write processor access, for a store access
This value is defined only when a processor access is pending.
Processor will do the action for us : it can for example read internal state (register values),
and send us back the information via EJTAG memory (dmseg), or it can take some data from dmseg and write it into the registers or RAM.
Every time when it sees address (i.e. when this address is the part of the opcode it is executing, wether it is instruction or data fetch)
that falls into dmseg, processor stalls. That acutally meand that CPU stops it's pipeline and it is waitning for dongle to take some action.
CPU is now either waiting for dongle to take some data from dmseg (if we requested for CPU do give us internal state, for example),
or it will wait for some data from dongle (if it needs following instruction because it did previous, or if the operand address of the currently executed opcode
falls somewhere (anywhere) in dmseg (0xff..ff20000 - 0xff..ff2fffff)).
Bit PNnW describes character of CPU access to EJTAG memory (the memry where dongle puts/takes data) - CPU can either READ for it (PNnW == 0) or
WRITE to it (PNnW == 1).
By reading PNnW bit OpenOCD will know if it has to send (PNnW == 0) or to take (PNnW == 1) data (from dmseg, via dongle).
@subsection pracc PrAcc
Indicates a pending processor access and controls finishing of a pending processor access.
When read:
- 0 : No pending processor access
- 1 : Pending processor access
A write of 0 finishes a processor access if pending;
otherwise operation of the processor is UNDEFINED
if the bit is written to 0 when no processor access is
pending. A write of 1 is ignored.
A successful FASTDATA access will clear this bit.
As noted above, on any access to dmseg, processor will stall. It waits for dongle to do some action - either to take or put some data.
OpenOCD can figure out which action has to be taken by reading PrAcc bit.
Once action from dongle has been done, i.e. after the data is taken/put, OpenOCD can signal to CPU to proceed with executing the instruction.
This can be the next instruction (if previous was finished before pending), or the same instruction - if for example CPU was waiting on dongle
to give it an operand, because it saw in the instruction opcode that operand address is somewhere in dmseg. That prowoked the CPU to stall (it tried operand fetch to dmseg and stopped),
and PNnW bit is 0 (CPU does read from dmseg), and PrAcc is 1 (CPU is pending on dmseg access).
@subsection spracc SPrAcc
Shifting in a zero value requests completion of the Fastdata access.
The PrAcc bit in the EJTAG Control register is overwritten with zero when the access
succeeds. (The access succeeds if PrAcc is one and the operation address is in the legal dmseg segment
Fastdata area.)
When successful, a one is shifted out. Shifting out a zero indicates a Fastdata access failure.
Shifting in a one does not complete the Fastdata access and the PrAcc bit is unchanged. Shifting out a
one indicates that the access would have been successful if allowed to complete and a zero indicates
the access would not have successfully completed.
@section fdreg Fastdata Register (TAP Instruction FASTDATA)
The width of the Fastdata register is 1 bit.
During a Fastdata access, the Fastdata register is written and read, i.e., a bit is
shifted in and a bit is shifted out.
Also during a Fastdata access, the Fastdata register value shifted in specifies whether the Fastdata
access should be completed or not. The value shifted out is a flag that indicates whether the Fastdata access was
successful or not (if completion was requested).
@section ejtagacc EJTAG Access Implementation
OpenOCD reads/writes data to JTAG via mips_m4k_read_memory() and mips_m4k_write_memory() functions defined in src/target/mips_m4k.c.
Internally, these functions call mips32_pracc_read_mem() and mips32_pracc_write_mem() defined in src/target/mips32_pracc.c
Let's take for example function mips32_pracc_read_mem32() which describes CPU reads (fetches) from dmseg (EJTAG memory) :
@code
static const uint32_t code[] = {
/* start: */
MIPS32_MTC0(15,31,0), /* move $15 to COP0 DeSave */
MIPS32_LUI(15,UPPER16(MIPS32_PRACC_STACK)), /* $15 = MIPS32_PRACC_STACK */
MIPS32_ORI(15,15,LOWER16(MIPS32_PRACC_STACK)),
MIPS32_SW(8,0,15), /* sw $8,($15) */
MIPS32_SW(9,0,15), /* sw $9,($15) */
MIPS32_SW(10,0,15), /* sw $10,($15) */
MIPS32_SW(11,0,15), /* sw $11,($15) */
MIPS32_LUI(8,UPPER16(MIPS32_PRACC_PARAM_IN)), /* $8 = MIPS32_PRACC_PARAM_IN */
MIPS32_ORI(8,8,LOWER16(MIPS32_PRACC_PARAM_IN)),
MIPS32_LW(9,0,8), /* $9 = mem[$8]; read addr */
MIPS32_LW(10,4,8), /* $10 = mem[$8 + 4]; read count */
MIPS32_LUI(11,UPPER16(MIPS32_PRACC_PARAM_OUT)), /* $11 = MIPS32_PRACC_PARAM_OUT */
MIPS32_ORI(11,11,LOWER16(MIPS32_PRACC_PARAM_OUT)),
/* loop: */
MIPS32_BEQ(0,10,8), /* beq 0, $10, end */
MIPS32_NOP,
MIPS32_LW(8,0,9), /* lw $8,0($9), Load $8 with the word @mem[$9] */
MIPS32_SW(8,0,11), /* sw $8,0($11) */
MIPS32_ADDI(10,10,NEG16(1)), /* $10-- */
MIPS32_ADDI(9,9,4), /* $1 += 4 */
MIPS32_ADDI(11,11,4), /* $11 += 4 */
MIPS32_B(NEG16(8)), /* b loop */
MIPS32_NOP,
/* end: */
MIPS32_LW(11,0,15), /* lw $11,($15) */
MIPS32_LW(10,0,15), /* lw $10,($15) */
MIPS32_LW(9,0,15), /* lw $9,($15) */
MIPS32_LW(8,0,15), /* lw $8,($15) */
MIPS32_B(NEG16(27)), /* b start */
MIPS32_MFC0(15,31,0), /* move COP0 DeSave to $15 */
};
@endcode
We have to pass this code to CPU via dongle via dmseg.
After debug exception CPU will find itself stalling at the begining of the dmseg. It waits for the first instruction from dongle.
This is MIPS32_MTC0(15,31,0), so CPU saves C0 and continues to addr 0xFF20 0001, which falls also to dmseg, so it stalls.
Dongle proceeds giving to CPU one by one instruction in this manner.
However, things are not so simple. If you take a look at the program, you will see that some instructions take operands. If it has to take
operand from the address in dmseg, CPU will stall witing for the dongle to do the action of passing the operand and signal this by putting PrAcc to 0.
If this operand is somewhere in RAM, CPU will not stall (it stalls only on dmseg), but it will just take it and proceed to nex instruction. But since PC for next instruction
points to dmseg, it will stall, so that dongle can pass next instruction.
Some instuctions are jumps (if these are jumps in dmseg addr, CPU will jump and then stall. If this is jump to some address in RAM, CPU will jump and just proceed -
will not stall on addresses in RAM).
To have information about CPU is currently (does it stalls wanting on operand or it jumped somewhere waiting for next instruction),
OpenOCD has to call TAP ADDRESS instruction, which will ask CPU to give us his address within EJTAG memory :
@code
address = data = 0;
mips_ejtag_set_instr(ejtag_info, EJTAG_INST_ADDRESS);
mips_ejtag_drscan_32(ejtag_info, &address);
@endcode
And then, upon the results, we can conclude where it is in our code so far, so we can give it what it wants next :
@code
if ((address >= MIPS32_PRACC_PARAM_IN)
&& (address <= MIPS32_PRACC_PARAM_IN + ctx->num_iparam * 4))
{
offset = (address - MIPS32_PRACC_PARAM_IN) / 4;
data = ctx->local_iparam[offset];
}
else if ((address >= MIPS32_PRACC_PARAM_OUT)
&& (address <= MIPS32_PRACC_PARAM_OUT + ctx->num_oparam * 4))
{
offset = (address - MIPS32_PRACC_PARAM_OUT) / 4;
data = ctx->local_oparam[offset];
}
else if ((address >= MIPS32_PRACC_TEXT)
&& (address <= MIPS32_PRACC_TEXT + ctx->code_len * 4))
{
offset = (address - MIPS32_PRACC_TEXT) / 4;
data = ctx->code[offset];
}
else if (address == MIPS32_PRACC_STACK)
{
/* save to our debug stack */
data = ctx->stack[--ctx->stack_offset];
}
else
{
/* TODO: send JMP 0xFF200000 instruction.
Hopefully processor jump back to start of debug vector */
data = 0;
LOG_ERROR("Error reading unexpected address 0x%8.8" PRIx32 "", address);
return ERROR_JTAG_DEVICE_ERROR;
}
@endcode
i.e. if CPU is stalling on addresses in dmseg that are reserved for input parameters, we can conclude that it actually tried to take (read)
parametar from there, and saw that address of param falls in dmseg, so it stopped. Obviously, now dongle have to give to it operand.
Similarly, mips32_pracc_exec_write() describes CPU writes into EJTAG memory (dmseg).
Obvioulsy, code is RO, and CPU can change only parameters :
@code
mips_ejtag_set_instr(ctx->ejtag_info, EJTAG_INST_DATA);
mips_ejtag_drscan_32(ctx->ejtag_info, &data);
/* Clear access pending bit */
ejtag_ctrl = ejtag_info->ejtag_ctrl & ~EJTAG_CTRL_PRACC;
mips_ejtag_set_instr(ctx->ejtag_info, EJTAG_INST_CONTROL);
mips_ejtag_drscan_32(ctx->ejtag_info, &ejtag_ctrl);
//jtag_add_clocks(5);
jtag_execute_queue();
if ((address >= MIPS32_PRACC_PARAM_IN)
&& (address <= MIPS32_PRACC_PARAM_IN + ctx->num_iparam * 4))
{
offset = (address - MIPS32_PRACC_PARAM_IN) / 4;
ctx->local_iparam[offset] = data;
}
else if ((address >= MIPS32_PRACC_PARAM_OUT)
&& (address <= MIPS32_PRACC_PARAM_OUT + ctx->num_oparam * 4))
{
offset = (address - MIPS32_PRACC_PARAM_OUT) / 4;
ctx->local_oparam[offset] = data;
}
else if (address == MIPS32_PRACC_STACK)
{
/* save data onto our stack */
ctx->stack[ctx->stack_offset++] = data;
}
else
{
LOG_ERROR("Error writing unexpected address 0x%8.8" PRIx32 "", address);
return ERROR_JTAG_DEVICE_ERROR;
}
@endcode
CPU loops here :
@code
while (1)
{
if ((retval = wait_for_pracc_rw(ejtag_info, &ejtag_ctrl)) != ERROR_OK)
return retval;
address = data = 0;
mips_ejtag_set_instr(ejtag_info, EJTAG_INST_ADDRESS);
mips_ejtag_drscan_32(ejtag_info, &address);
/* Check for read or write */
if (ejtag_ctrl & EJTAG_CTRL_PRNW)
{
if ((retval = mips32_pracc_exec_write(&ctx, address)) != ERROR_OK)
return retval;
}
else
{
/* Check to see if its reading at the debug vector. The first pass through
* the module is always read at the vector, so the first one we allow. When
* the second read from the vector occurs we are done and just exit. */
if ((address == MIPS32_PRACC_TEXT) && (pass++))
{
break;
}
if ((retval = mips32_pracc_exec_read(&ctx, address)) != ERROR_OK)
return retval;
}
if (cycle == 0)
break;
}
@endcode
and using presented R (mips32_pracc_exec_read()) and W (mips32_pracc_exec_write()) functions it reads in the code (RO) and reads and writes operands (RW).
@section fdimpl OpenOCD FASTDATA Implementation
OpenOCD FASTDATA write function, mips32_pracc_fastdata_xfer() is called from bulk_write_memory callback, which writes a count items of 4 bytes
to the memory of a target at the an address given. Because it operates only on whole words, this should be faster than target_write_memory().
In order to implement FASTDATA write, mips32_pracc_fastdata_xfer() uses the following handler :
@code
uint32_t handler_code[] = {
/* caution when editing, table is modified below */
/* r15 points to the start of this code */
MIPS32_SW(8,MIPS32_FASTDATA_HANDLER_SIZE - 4,15),
MIPS32_SW(9,MIPS32_FASTDATA_HANDLER_SIZE - 8,15),
MIPS32_SW(10,MIPS32_FASTDATA_HANDLER_SIZE - 12,15),
MIPS32_SW(11,MIPS32_FASTDATA_HANDLER_SIZE - 16,15),
/* start of fastdata area in t0 */
MIPS32_LUI(8,UPPER16(MIPS32_PRACC_FASTDATA_AREA)),
MIPS32_ORI(8,8,LOWER16(MIPS32_PRACC_FASTDATA_AREA)),
MIPS32_LW(9,0,8), /* start addr in t1 */
MIPS32_LW(10,0,8), /* end addr to t2 */
/* loop: */
/* 8 */ MIPS32_LW(11,0,0), /* lw t3,[t8 | r9] */
/* 9 */ MIPS32_SW(11,0,0), /* sw t3,[r9 | r8] */
MIPS32_BNE(10,9,NEG16(3)), /* bne $t2,t1,loop */
MIPS32_ADDI(9,9,4), /* addi t1,t1,4 */
MIPS32_LW(8,MIPS32_FASTDATA_HANDLER_SIZE - 4,15),
MIPS32_LW(9,MIPS32_FASTDATA_HANDLER_SIZE - 8,15),
MIPS32_LW(10,MIPS32_FASTDATA_HANDLER_SIZE - 12,15),
MIPS32_LW(11,MIPS32_FASTDATA_HANDLER_SIZE - 16,15),
MIPS32_LUI(15,UPPER16(MIPS32_PRACC_TEXT)),
MIPS32_ORI(15,15,LOWER16(MIPS32_PRACC_TEXT)),
MIPS32_JR(15), /* jr start */
MIPS32_MFC0(15,31,0), /* move COP0 DeSave to $15 */
};
@endcode
In the begining and the end of the handler we have fuction prologue (save the regs that will be clobbered) and epilogue (restore regs),
and in the very end, after all the xfer have been done, we do jump to the MIPS32_PRACC_TEXT address, i.e. Debug Exception Vector location.
We will use this fact (that we came back to MIPS32_PRACC_TEXT) to verify later if all the handler is executed (because when in RAM,
processor do not stall - it executes all instructions untill one of them do not demand access to dmseg (if one of it's opernads is there)).
This handler is put into the RAM and executed from there, and not instruction by instruction, like in previous simple write
(mips_m4k_write_memory()) and read (mips_m4k_read_memory()) functions.
N.B. When it is executing this code in RAM, CPU will not stall on instructions, but execute all until it comes to the :
@code
MIPS32_LW(9,0,8) /* start addr in t1 */
@endcode
and there it will stall - because it will see that one of the operands have to be fetched from dmseg (EJTAG memory, in this case FASTDATA memory segment).
This handler is loaded in the RAM, ath the reserved location "work_area". This work_area is configured in OpenOCD configuration script and should be selected
in that way that it is not clobbered (overwritten) by data we want to write-in using FASTDATA.
What is executed instruction by instruction which is passed by dongle (via EJATG memory) is small jump code, which jumps at the handler in RAM.
CPU stalls on dmseg when receiving these jmp_code instructions, but once it jumps in RAM, CPU do not stall anymore and executes bunch of handler instructions.
Untill it comes to the first instruction which has an operand in FASTDATA area. There it stalls and waits on action from probe.
It happens actually when CPU comes to this loop :
@code
MIPS32_LW(9,0,8), /* start addr in t1 */
MIPS32_LW(10,0,8), /* end addr to t2 */
/* loop: */
/* 8 */ MIPS32_LW(11,0,0), /* lw t3,[t8 | r9] */
/* 9 */ MIPS32_SW(11,0,0), /* sw t3,[r9 | r8] */
MIPS32_BNE(10,9,NEG16(3)), /* bne $t2,t1,loop */
@endcode
and then it stalls because operand in r8 points to FASTDATA area.
OpenOCD first verifies that CPU came to this place by :
@code
/* next fetch to dmseg should be in FASTDATA_AREA, check */
address = 0;
mips_ejtag_set_instr(ejtag_info, EJTAG_INST_ADDRESS);
mips_ejtag_drscan_32(ejtag_info, &address);
if (address != MIPS32_PRACC_FASTDATA_AREA)
return ERROR_FAIL;
@endcode
and then passes to CPU start and end address of the loop region for handler in RAM.
In the loop in handler, CPU sees that it has to take and operand from FSTDATA area (to write it to the dst in RAM after), and so it stalls, putting PrAcc to "1".
OpenOCD fills the data via this loop :
@code
for (i = 0; i < count; i++)
{
/* Send the data out using fastdata (clears the access pending bit) */
mips_ejtag_set_instr(ejtag_info, EJTAG_INST_FASTDATA);
if ((retval = mips_ejtag_fastdata_scan(ejtag_info, write_t, buf++)) != ERROR_OK)
return retval;
}
@endcode
Each time when OpenOCD fills data to CPU (via dongle, via dmseg), CPU takes it and proceeds in executing the endler. However, since handler is in a assembly loop,
CPU comes to next instruction which also fetches data from FASTDATA area. So it stalls.
Then OpenOCD fills the data again, from it's (OpenOCD's) loop. And this game continues untill all the data has been filled.
After the last data has beend given to CPU it sees that it reached the end address, so it proceeds with next instruction. However, rhis instruction do not point into dmseg, so
CPU executes bunch of handler instructions (all prologue) and in the end jumps to MIPS32_PRACC_TEXT address.
On it's side, OpenOCD checks in CPU has jumped back to MIPS32_PRACC_TEXT, which is the confirmation that it correclty executed all the rest of the handler in RAM,
and that is not stuck somewhere in the RAM, or stalling on some acces in dmseg - that would be an error :
@code
address = 0;
mips_ejtag_set_instr(ejtag_info, EJTAG_INST_ADDRESS);
mips_ejtag_drscan_32(ejtag_info, &address);
if (address != MIPS32_PRACC_TEXT)
LOG_ERROR("mini program did not return to start");
@endcode
@section fdejtagspec EJTAG spec on FASTDATA access
The width of the Fastdata register is 1 bit. During a Fastdata access, the Fastdata register is written and read, i.e., a bit
is shifted in and a bit is shifted out. During a Fastdata access, the Fastdata register value shifted in specifies whether
the Fastdata access should be completed or not. The value shifted out is a flag that indicates whether the Fastdata
access was successful or not (if completion was requested).
The FASTDATA access is used for efficient block transfers between dmseg (on the probe) and target memory (on the
processor). An "upload" is defined as a sequence of processor loads from target memory and stores to dmseg. A
"download" is a sequence of processor loads from dmseg and stores to target memory. The "Fastdata area" specifies
the legal range of dmseg addresses (0xFF20.0000 - 0xFF20.000F) that can be used for uploads and downloads. The
Data + Fastdata registers (selected with the FASTDATA instruction) allow efficient completion of pending Fastdata
area accesses.
During Fastdata uploads and downloads, the processor will stall on accesses to the Fastdata area. The PrAcc (processor
access pending bit) will be 1 indicating the probe is required to complete the access. Both upload and download
accesses are attempted by shifting in a zero SPrAcc value (to request access completion) and shifting out SPrAcc to
see if the attempt will be successful (i.e., there was an access pending and a legal Fastdata area address was used).
Downloads will also shift in the data to be used to satisfy the load from dmseg’s Fastdata area, while uploads will
shift out the data being stored to dmseg’s Fastdata area.
As noted above, two conditions must be true for the Fastdata access to succeed. These are:
- PrAcc must be 1, i.e., there must be a pending processor access.
- The Fastdata operation must use a valid Fastdata area address in dmseg (0xFF20.0000 to 0xFF20.000F).
Basically, because FASTDATA area in dmseg is 16 bytes, we transfer (0xFF20.0000 - 0xFF20.000F)
FASTDATA scan TAP instruction selects the Data and the Fastdata registers at once.
They come in order :
TDI -> | Data register| -> | Fastdata register | -> TDO
FASTDATA register is 1-bit width register. It takes in SPrAcc bit which should be shifted first,
followed by 32 bit of data.
Scan width of FASTDTA is 33 bits in total : 33 bits are shifted in and 33 bits are shifted out.
First bit that is shifted out is SPrAcc that comes out of Fastdata register and should give us status on FATSDATA write we want to do.
@section fdcheck OpenOCD misses FASTDATA check
Download flow (probe -> target block transfer) :
1) Probe transfer target execution to a loop in target memory doing a fixed number of "loads" to fastdata area of dmseg (and stores to the target download destination.)
2) Probe loops attempting to satisfy the loads "expected" from the target.
On FASTDATA access "successful" move on to next "load".
On FASTDATA access "failure" repeat until "successful" or timeout.
(A "failure" is an attempt to satisfy an access when none are pending.)
Note: A failure may have a recoverable (and even expected) cause like slow target execution of the load loop. Other failures may be due to unexpected more troublesome causes like an exception while in debug mode or a target hang on a bad target memory access.
Shifted out SPrAcc bit inform us that there was CPU access pendingand that it can be complete.
Basically, we should do following procedure :
- Download (dongle -> CPU) :
You shift "download" DATA and FASTDATA[SPrAcc] = 0 (33 bit scan) into the target. If the value of FASTDATA[SPrAcc] shifted out is "1" then an access was pending when you started the scan and it is now complete.
If SPrAcc is 0 then no access was pending to the fastdata area. (Repeat attempt to complete the access you expect for this data word. Timeout if you think the access is "long overdue" as something unexpected has happened.)
- Upload (CPU -> dongle) :
You shift "dummy" DATA and FASTDATA[SPrAcc] = 0 (33 bit scan) into the target. If the value of FASTDATA[SPrAcc] shifted out is "1" then an access was pending when you started the scan and it is now complete. The "upload" is the DATA shifted out of the target.
If SPrAcc is 0 then no access was pending to the fastdata area. (Repeat attempt to complete the access you expect for this data word. Timeout if you think the access is "long overdue" as something unexpected has happened.)
Basically, if checking first (before scan) if CPU is pending on FASTDATA access (PrAcc is "1"), like this
@code
wait(ready);
do_scan();
@endcode
which is inefficient, we should do it like this :
@code
BEGIN :
do_scan();
if (!was_ready)
goto BEGIN;
@endcode
by checking SPrAcc that we shifted out.
If some FASTDATA write fails, OpenOCD will continue with it's loop (on the host side), but CPU will rest pending (on the target side)
waiting for correct FASTDATA write.
Since OpenOCD goes ahead, it will eventually finish it's loop, and proceede to check if CPU took all the data. But since CPU did not took all the data,
it is still turns in handler's loop in RAM, stalling on Fastdata area so this check :
@code
address = 0;
mips_ejtag_set_instr(ejtag_info, EJTAG_INST_ADDRESS);
retval = mips_ejtag_drscan_32(ejtag_info, &address);
if (retval != ERROR_OK)
return retval;
if (address != MIPS32_PRACC_TEXT)
LOG_ERROR("mini program did not return to start");
@endcode
fails, and that gives us enough information of the failure.
In this case, we can lower the JTAG frquency and try again, bacuse most probable reason of this failure is that we tried FASTDATA upload before CPU arrived to rise PrAcc (i.e. before it was pending on access).
However, the reasons for failure might be numerous : reset, exceptions which can occur in debug mode, bus hangs, etc.
If lowering the JTAG freq does not work either, we can fall back to more robust solution with patch posted below.
To summarize, FASTDATA communication goes as following :
-# CPU jumps to Debug Exception Vector Location 0xFF200200 in dmseg and it stalls, pending and waiting for EJTAG to give it first debug instruction and signall it by putting PrAcc to "0"
-# When PrAcc goes to "0" CPU execute one opcode sent by EJTAG via DATA reg. Then it pends on next access, waiting for PrAcc to be put to "0" again
-# Following this game, OpenOCD first loads handler code in RAM, and then sends the jmp_code - instruction by instruction via DATA reg, which redirects CPU to handler previously set up in RAM
-# Once in RAM CPU does not pend on any instruction, but it executes all handler instructions untill first "fetch" to Fastdata area - then it stops and pends.
-# So - when it comes to any instruction (opcode) in this handler in RAM which reads (or writes) to Fastdata area (0xF..F20.0000 to 0xF..F20.000F), CPU stops (i.e. stalls access).
I.e. it stops on this lw opcode and waits to FASTDATA TAP command from the probe.
-# CPU continues only if OpenOCD shifted in SPrAcc "0" (and if the PrAcc was "1"). It shifts-out "1" to tell us that it was OK (processor was stalled, so it can complete the access),
and that it continued execution of the handler in RAM.
-# If PrAcc was not "1" CPU will not continue (go to next instruction), but will shift-out "0" and keep stalling on the same instruction of my handler in RAM.
-# When Fastdata loop is finished, CPU executes all following hadler instructions in RAM (prologue).
-# In the end of my handler in RAM, I jumps back to begining of Debug Exception Vector Location 0xFF200200 in dmseg.
-# When it jumps back to 0xFF200200 in dmseg processor stops and pends, waiting for OpenOCD to send it instruction via DATA reg and signal it by putting PrAcc to "0".
*/

71
debuggers/openocd/doc/manual/target/notarm.txt Normal file
View File

@ -0,0 +1,71 @@
/** @page targetnotarm OpenOCD Non-ARM Targets
This page describes outstanding issues w.r.t. non-ARM targets.
@section targetnotarmflash Flash drivers
The flash drivers contain ARM32 code that is used
to execute code on the target.
This needs to be handled in some CPU independent
manner.
The ocl and ecos flash drivers compile the flash
driver code to run on the target on the developer
machine.
The ocl and ecos flash drivers should be unified
and instructions should be written on how to
compile the target flash drivers. Perhaps
using automake?
eCos has CFI driver that could probably be compiled
for all targets. The trick is to figure out a
way to make the compiled flash drivers work
on all target memory maps + sort out all the
little details
@section targetnotarm32v64 32 vs. 64 bit
Currently OpenOCD only supports 32 bit targets.
Adding 64 bit support would be nice but there
hasn't been any call for it in the openocd development
mailing list
@section targetnotarmsupport Target Support
target.h is relatively CPU agnostic and
the intention is to move in the direction of less
instruction set specific.
Non-CPU targets are also supported, but there isn't
a lot of activity on it in the mailing list currently.
An example is FPGA programming support via JTAG,
but also flash chips can be programmed directly
using JTAG.
@section targetnotarmphy non-JTAG physical layer
JTAG is not the only physical protocol used to talk to
CPUs.
OpenOCD does not today have targets that use non-JTAG.
The actual physical layer is a relatively modest part
of the total OpenOCD system.
@section targetnotarmppc PowerPC
there exists open source implementations of powerpc
target manipulation, but there hasn't been a lot
of activity in the mailing list.
@section targetnotarmmips MIPS
Currently OpenOCD has a MIPS target defined. This is the
first non-ARM example of a CPU target
*/

224
debuggers/openocd/doc/mdate-sh Executable file
View File

@ -0,0 +1,224 @@
#!/bin/sh
# Get modification time of a file or directory and pretty-print it.
scriptversion=2010-08-21.06; # UTC
# Copyright (C) 1995-2013 Free Software Foundation, Inc.
# written by Ulrich Drepper <drepper@gnu.ai.mit.edu>, June 1995
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2, or (at your option)
# any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
# As a special exception to the GNU General Public License, if you
# distribute this file as part of a program that contains a
# configuration script generated by Autoconf, you may include it under
# the same distribution terms that you use for the rest of that program.
# This file is maintained in Automake, please report
# bugs to <bug-automake@gnu.org> or send patches to
# <automake-patches@gnu.org>.
if test -n "${ZSH_VERSION+set}" && (emulate sh) >/dev/null 2>&1; then
emulate sh
NULLCMD=:
# Pre-4.2 versions of Zsh do word splitting on ${1+"$@"}, which
# is contrary to our usage. Disable this feature.
alias -g '${1+"$@"}'='"$@"'
setopt NO_GLOB_SUBST
fi
case $1 in
'')
echo "$0: No file. Try '$0 --help' for more information." 1>&2
exit 1;
;;
-h | --h*)
cat <<\EOF
Usage: mdate-sh [--help] [--version] FILE
Pretty-print the modification day of FILE, in the format:
1 January 1970
Report bugs to <bug-automake@gnu.org>.
EOF
exit $?
;;
-v | --v*)
echo "mdate-sh $scriptversion"
exit $?
;;
esac
error ()
{
echo "$0: $1" >&2
exit 1
}
# Prevent date giving response in another language.
LANG=C
export LANG
LC_ALL=C
export LC_ALL
LC_TIME=C
export LC_TIME
# GNU ls changes its time format in response to the TIME_STYLE
# variable. Since we cannot assume 'unset' works, revert this
# variable to its documented default.
if test "${TIME_STYLE+set}" = set; then
TIME_STYLE=posix-long-iso
export TIME_STYLE
fi
save_arg1=$1
# Find out how to get the extended ls output of a file or directory.
if ls -L /dev/null 1>/dev/null 2>&1; then
ls_command='ls -L -l -d'
else
ls_command='ls -l -d'
fi
# Avoid user/group names that might have spaces, when possible.
if ls -n /dev/null 1>/dev/null 2>&1; then
ls_command="$ls_command -n"
fi
# A 'ls -l' line looks as follows on OS/2.
# drwxrwx--- 0 Aug 11 2001 foo
# This differs from Unix, which adds ownership information.
# drwxrwx--- 2 root root 4096 Aug 11 2001 foo
#
# To find the date, we split the line on spaces and iterate on words
# until we find a month. This cannot work with files whose owner is a
# user named "Jan", or "Feb", etc. However, it's unlikely that '/'
# will be owned by a user whose name is a month. So we first look at
# the extended ls output of the root directory to decide how many
# words should be skipped to get the date.
# On HPUX /bin/sh, "set" interprets "-rw-r--r--" as options, so the "x" below.
set x`$ls_command /`
# Find which argument is the month.
month=
command=
until test $month
do
test $# -gt 0 || error "failed parsing '$ls_command /' output"
shift
# Add another shift to the command.
command="$command shift;"
case $1 in
Jan) month=January; nummonth=1;;
Feb) month=February; nummonth=2;;
Mar) month=March; nummonth=3;;
Apr) month=April; nummonth=4;;
May) month=May; nummonth=5;;
Jun) month=June; nummonth=6;;
Jul) month=July; nummonth=7;;
Aug) month=August; nummonth=8;;
Sep) month=September; nummonth=9;;
Oct) month=October; nummonth=10;;
Nov) month=November; nummonth=11;;
Dec) month=December; nummonth=12;;
esac
done
test -n "$month" || error "failed parsing '$ls_command /' output"
# Get the extended ls output of the file or directory.
set dummy x`eval "$ls_command \"\\\$save_arg1\""`
# Remove all preceding arguments
eval $command
# Because of the dummy argument above, month is in $2.
#
# On a POSIX system, we should have
#
# $# = 5
# $1 = file size
# $2 = month
# $3 = day
# $4 = year or time
# $5 = filename
#
# On Darwin 7.7.0 and 7.6.0, we have
#
# $# = 4
# $1 = day
# $2 = month
# $3 = year or time
# $4 = filename
# Get the month.
case $2 in
Jan) month=January; nummonth=1;;
Feb) month=February; nummonth=2;;
Mar) month=March; nummonth=3;;
Apr) month=April; nummonth=4;;
May) month=May; nummonth=5;;
Jun) month=June; nummonth=6;;
Jul) month=July; nummonth=7;;
Aug) month=August; nummonth=8;;
Sep) month=September; nummonth=9;;
Oct) month=October; nummonth=10;;
Nov) month=November; nummonth=11;;
Dec) month=December; nummonth=12;;
esac
case $3 in
???*) day=$1;;
*) day=$3; shift;;
esac
# Here we have to deal with the problem that the ls output gives either
# the time of day or the year.
case $3 in
*:*) set `date`; eval year=\$$#
case $2 in
Jan) nummonthtod=1;;
Feb) nummonthtod=2;;
Mar) nummonthtod=3;;
Apr) nummonthtod=4;;
May) nummonthtod=5;;
Jun) nummonthtod=6;;
Jul) nummonthtod=7;;
Aug) nummonthtod=8;;
Sep) nummonthtod=9;;
Oct) nummonthtod=10;;
Nov) nummonthtod=11;;
Dec) nummonthtod=12;;
esac
# For the first six month of the year the time notation can also
# be used for files modified in the last year.
if (expr $nummonth \> $nummonthtod) > /dev/null;
then
year=`expr $year - 1`
fi;;
*) year=$3;;
esac
# The result.
echo $day $month $year
# Local Variables:
# mode: shell-script
# sh-indentation: 2
# eval: (add-hook 'write-file-hooks 'time-stamp)
# time-stamp-start: "scriptversion="
# time-stamp-format: "%:y-%02m-%02d.%02H"
# time-stamp-time-zone: "UTC"
# time-stamp-end: "; # UTC"
# End:

103
debuggers/openocd/doc/openocd.1 Normal file
View File

@ -0,0 +1,103 @@
.TH "OPENOCD" "1" "November 24, 2009"
.SH "NAME"
openocd \- A free and open on\-chip debugging, in\-system programming and
boundary\-scan testing tool for ARM and MIPS systems
.SH "SYNOPSIS"
.B openocd \fR[\fB\-fsdlcphv\fR] [\fB\-\-file\fR <filename>] [\fB\-\-search\fR <dirname>] [\fB\-\-debug\fR <debuglevel>] [\fB\-\-log_output\fR <filename>] [\fB\-\-command\fR <cmd>] [\fB\-\-pipe\fR] [\fB\-\-help\fR] [\fB\-\-version\fR]
.SH "DESCRIPTION"
.B OpenOCD
is an on\-chip debugging, in\-system programming and boundary\-scan
testing tool for various ARM and MIPS systems.
.PP
The debugger uses an IEEE 1149\-1 compliant JTAG TAP bus master to access
on\-chip debug functionality available on ARM based microcontrollers or
system-on-chip solutions. For MIPS systems the EJTAG interface is supported.
.PP
User interaction is realized through a telnet command line interface,
a gdb (the GNU debugger) remote protocol server, and a simplified RPC
connection that can be used to interface with OpenOCD's Jim Tcl engine.
.PP
OpenOCD supports various different types of JTAG interfaces/programmers,
please check the \fIopenocd\fR info page for the complete list.
.SH "OPTIONS"
.TP
.B "\-f, \-\-file <filename>"
This is a shortcut for a \fB\-c "[script \fI<filename>\fB]"\fR
command, using a search path to load the configuration file
.IR <filename> .
In order to specify multiple config files, you can use multiple
.B \-\-file
arguments. If no such \fB\-c\fR
options are included, the first config file
.B openocd.cfg
in the search path will be used.
.TP
.B "\-s, \-\-search <dirname>"
Add
.I <dirname>
to the search path used for config files and scripts.
The search path begins with the current directory,
then includes these additional directories before other
components such as the standard OpenOCD script libraries.
.TP
.B "\-d, \-\-debug <debuglevel>"
Set debug level. Possible values are:
.br
.RB " * " 0 " (errors)"
.br
.RB " * " 1 " (warnings)"
.br
.RB " * " 2 " (informational messages)"
.br
.RB " * " 3 " (debug messages)"
.br
The default level is
.BR 2 .
.TP
.B "\-l, \-\-log_output <filename>"
Redirect log output to the file
.IR <filename> .
Per default the log output is printed on
.BR stderr .
.TP
.B "\-c, \-\-command <cmd>"
Add the command
.I <cmd>
to a list of commands executed on server startup.
Note that you will need to explicitly invoke
.I init
if the command requires access to a target or flash.
.TP
.B "\-p, \-\-pipe"
Use pipes when talking to gdb.
.TP
.B "\-h, \-\-help"
Show a help text and exit.
.TP
.B "\-v, \-\-version"
Show version information and exit.
.SH "BUGS"
Please report any bugs on the mailing list at
.BR openocd\-devel@lists.sourceforge.net .
.SH "LICENCE"
.B OpenOCD
is covered by the GNU General Public License (GPL), version 2 or later.
.SH "SEE ALSO"
.BR jtag (1)
.PP
The full documentation for
.B openocd
is maintained as a Texinfo manual. If the
.BR info
(or
.BR pinfo )
and
.BR openocd
programs are properly installed at your site, the command
.B info openocd
should give you access to the complete manual.
.SH "AUTHORS"
Please see the file AUTHORS.
.PP
This manual page was written by Uwe Hermann <uwe@hermann\-uwe.de>.
It is licensed under the terms of the GNU GPL (version 2 or later).

109
debuggers/openocd/doc/openocd.info Normal file
View File

@ -0,0 +1,109 @@
This is openocd.info, produced by makeinfo version 5.1 from
openocd.texi.
This User's Guide documents release 0.7.0, dated 4 May 2013, of the Open
On-Chip Debugger (OpenOCD).
* Copyright (C) 2008 The OpenOCD Project
* Copyright (C) 2007-2008 Spencer Oliver <spen@spen-soft.co.uk>
* Copyright (C) 2008-2010 Oyvind Harboe <oyvind.harboe@zylin.com>
* Copyright (C) 2008 Duane Ellis <openocd@duaneellis.com>
* Copyright (C) 2009-2010 David Brownell
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.2 or any later version published by the Free Software
Foundation; with no Invariant Sections, with no Front-Cover Texts,
and with no Back-Cover Texts. A copy of the license is included in
the section entitled "GNU Free Documentation License".
INFO-DIR-SECTION Development
START-INFO-DIR-ENTRY
* OpenOCD: (openocd). OpenOCD User's Guide
END-INFO-DIR-ENTRY

Indirect:
openocd.info-1: 990
openocd.info-2: 301821

Tag Table:
(Indirect)
Node: Top990
Node: About3496
Node: Developers7842
Node: Debug Adapter Hardware10510
Node: About Jim-Tcl21044
Node: Running23186
Node: OpenOCD Project Setup28081
Ref: OpenOCD Project Setup-Footnote-147973
Ref: OpenOCD Project Setup-Footnote-248313
Ref: OpenOCD Project Setup-Footnote-348581
Node: Config File Guidelines48909
Ref: theinitboardprocedure72069
Ref: definecputargetsworkinginsmp78860
Ref: theinittargetsprocedure83294
Ref: translatingconfigurationfiles86553
Ref: Config File Guidelines-Footnote-187780
Node: Daemon Configuration87855
Ref: configurationstage88177
Ref: enteringtherunstage89029
Ref: tcpipports91478
Ref: gdbconfiguration93724
Ref: gdbbreakpointoverride94039
Ref: gdbflashprogram94414
Ref: eventpolling95289
Node: Debug Adapter Configuration97725
Ref: jtagspeed125585
Node: Reset Configuration128543
Ref: srstandtrstissues131471
Node: TAP Declaration143516
Ref: enablinganddisablingtaps155076
Ref: autoprobing157723
Ref: TAP Declaration-Footnote-1160414
Node: CPU Configuration160614
Ref: targettypes164761
Ref: targetconfiguration166765
Ref: targetcurstate175679
Ref: targetevents176920
Node: Flash Commands181766
Ref: norconfiguration183298
Ref: flashprogrammingcommands185957
Ref: flashprotect191530
Ref: program191888
Ref: flashdriverlist192139
Ref: at91sam3196024
Ref: Flash Commands-Footnote-1221282
Ref: Flash Commands-Footnote-2221448
Node: Flash Programming221613
Node: NAND Flash Commands223061
Ref: nandconfiguration226029
Ref: nanddriverlist236404
Node: PLD/FPGA Commands241099
Node: General Commands243162
Ref: debuglevel245109
Ref: targetstatehandling246035
Ref: resetcommand249687
Ref: memoryaccess251957
Ref: imageaccess253584
Node: Architecture and Core Commands257966
Ref: armhardwaretracing258436
Ref: traceportdrivers266354
Ref: arm9vectorcatch274250
Ref: xscalevectorcatch282653
Ref: softwaredebugmessagesandtracing288914
Node: JTAG Commands292381
Node: Boundary Scan Commands301821
Node: TFTP304271
Node: GDB and OpenOCD305145
Ref: programmingusinggdb310040
Ref: usingopenocdsmpwithgdb311483
Node: Tcl Scripting API312914
Node: FAQ315554
Ref: faqrtck315664
Ref: faqtaporder328202
Node: Tcl Crash Course329965
Node: License341963
Node: OpenOCD Concept Index364373
Node: Command and Driver Index382304

End Tag Table

6641
debuggers/openocd/doc/openocd.info-1 Normal file
View File

File diff suppressed because it is too large Load Diff

2250
debuggers/openocd/doc/openocd.info-2 Normal file
View File

File diff suppressed because it is too large Load Diff

8825
debuggers/openocd/doc/openocd.texi Normal file
View File

File diff suppressed because it is too large Load Diff

4
debuggers/openocd/doc/stamp-vti Normal file
View File

@ -0,0 +1,4 @@
@set UPDATED 4 May 2013
@set UPDATED-MONTH May 2013
@set EDITION 0.7.0
@set VERSION 0.7.0

10074
debuggers/openocd/doc/texinfo.tex Normal file
View File

File diff suppressed because it is too large Load Diff

4
debuggers/openocd/doc/version.texi Normal file
View File

@ -0,0 +1,4 @@
@set UPDATED 4 May 2013
@set UPDATED-MONTH May 2013
@set EDITION 0.7.0
@set VERSION 0.7.0