diff options
Diffstat (limited to 'doc/manual')
| -rw-r--r-- | doc/manual/app.txt | 9 | ||||
| -rw-r--r-- | doc/manual/flash.txt | 35 | ||||
| -rw-r--r-- | doc/manual/helper.txt | 136 | ||||
| -rw-r--r-- | doc/manual/images/jtag-state-machine-large.png | bin | 11416 -> 0 bytes | |||
| -rw-r--r-- | doc/manual/jtag.txt | 73 | ||||
| -rw-r--r-- | doc/manual/jtag/drivers/remote_bitbang.txt | 53 | ||||
| -rw-r--r-- | doc/manual/main.txt | 105 | ||||
| -rw-r--r-- | doc/manual/primer/autotools.txt | 147 | ||||
| -rw-r--r-- | doc/manual/primer/commands.txt | 138 | ||||
| -rw-r--r-- | doc/manual/primer/docs.txt | 124 | ||||
| -rw-r--r-- | doc/manual/primer/jtag.txt | 169 | ||||
| -rw-r--r-- | doc/manual/primer/tcl.txt | 440 | ||||
| -rw-r--r-- | doc/manual/release.txt | 465 | ||||
| -rw-r--r-- | doc/manual/scripting.txt | 80 | ||||
| -rw-r--r-- | doc/manual/server.txt | 316 | ||||
| -rw-r--r-- | doc/manual/style.txt | 422 | ||||
| -rw-r--r-- | doc/manual/target.txt | 46 | ||||
| -rw-r--r-- | doc/manual/target/mips.txt | 536 | ||||
| -rw-r--r-- | doc/manual/target/notarm.txt | 71 |
19 files changed, 0 insertions, 3365 deletions
diff --git a/doc/manual/app.txt b/doc/manual/app.txt deleted file mode 100644 index 989e6e6..0000000 --- a/doc/manual/app.txt +++ /dev/null @@ -1,9 +0,0 @@ -/** @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. - - */ diff --git a/doc/manual/flash.txt b/doc/manual/flash.txt deleted file mode 100644 index a9f6c2a..0000000 --- a/doc/manual/flash.txt +++ /dev/null @@ -1,35 +0,0 @@ -/** @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. - -*/ diff --git a/doc/manual/helper.txt b/doc/manual/helper.txt deleted file mode 100644 index 1b01b2e..0000000 --- a/doc/manual/helper.txt +++ /dev/null @@ -1,136 +0,0 @@ -/** @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.tcl.tk/ 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 module using a standard -interface. 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 principal 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 be 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_HANDLER - 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 described 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. - - */ diff --git a/doc/manual/images/jtag-state-machine-large.png b/doc/manual/images/jtag-state-machine-large.png Binary files differdeleted file mode 100644 index c91fcf4..0000000 --- a/doc/manual/images/jtag-state-machine-large.png +++ /dev/null diff --git a/doc/manual/jtag.txt b/doc/manual/jtag.txt deleted file mode 100644 index 8f0804c..0000000 --- a/doc/manual/jtag.txt +++ /dev/null @@ -1,73 +0,0 @@ -/** @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. - - */ diff --git a/doc/manual/jtag/drivers/remote_bitbang.txt b/doc/manual/jtag/drivers/remote_bitbang.txt deleted file mode 100644 index 5a80047..0000000 --- a/doc/manual/jtag/drivers/remote_bitbang.txt +++ /dev/null @@ -1,53 +0,0 @@ -/** @remote_bitbangpage OpenOCD Developer's Guide - -The remote_bitbang JTAG driver is used to drive JTAG from a remote process. The -remote_bitbang driver communicates via TCP or UNIX sockets with some remote -process using an ASCII encoding of the bitbang interface. The remote process -presumably then drives the JTAG however it pleases. The remote process should -act as a server, listening for connections from the openocd remote_bitbang -driver. - -The remote bitbang driver is useful for debugging software running on -processors which are being simulated. - -The bitbang interface consists of the following functions. - -blink on - Blink a light somewhere. The argument on is either 1 or 0. - -read - Sample the value of tdo. - -write tck tms tdi - Set the value of tck, tms, and tdi. - -reset trst srst - Set the value of trst, srst. - -An additional function, quit, is added to the remote_bitbang interface to -indicate there will be no more requests and the connection with the remote -driver should be closed. - -These five functions are encoded in ascii by assigning a single character to -each possible request. The assignments are: - - B - Blink on - b - Blink off - R - Read request - Q - Quit request - 0 - Write 0 0 0 - 1 - Write 0 0 1 - 2 - Write 0 1 0 - 3 - Write 0 1 1 - 4 - Write 1 0 0 - 5 - Write 1 0 1 - 6 - Write 1 1 0 - 7 - Write 1 1 1 - r - Reset 0 0 - s - Reset 0 1 - t - Reset 1 0 - u - Reset 1 1 - -The read response is encoded in ascii as either digit 0 or 1. - - */ diff --git a/doc/manual/main.txt b/doc/manual/main.txt deleted file mode 100644 index c14096b..0000000 --- a/doc/manual/main.txt +++ /dev/null @@ -1,105 +0,0 @@ -/** @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. - - */ diff --git a/doc/manual/primer/autotools.txt b/doc/manual/primer/autotools.txt deleted file mode 100644 index 9d9aada..0000000 --- a/doc/manual/primer/autotools.txt +++ /dev/null @@ -1,147 +0,0 @@ -/** @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. - -@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. - - */ diff --git a/doc/manual/primer/commands.txt b/doc/manual/primer/commands.txt deleted file mode 100644 index 5f89d50..0000000 --- a/doc/manual/primer/commands.txt +++ /dev/null @@ -1,138 +0,0 @@ -/** @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 - - */ diff --git a/doc/manual/primer/docs.txt b/doc/manual/primer/docs.txt deleted file mode 100644 index 504da79..0000000 --- a/doc/manual/primer/docs.txt +++ /dev/null @@ -1,124 +0,0 @@ -/** @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 - - */ diff --git a/doc/manual/primer/jtag.txt b/doc/manual/primer/jtag.txt deleted file mode 100644 index 41eef72..0000000 --- a/doc/manual/primer/jtag.txt +++ /dev/null @@ -1,169 +0,0 @@ -/** @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 - -@image html 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. - */ diff --git a/doc/manual/primer/tcl.txt b/doc/manual/primer/tcl.txt deleted file mode 100644 index 9be4a05..0000000 --- a/doc/manual/primer/tcl.txt +++ /dev/null @@ -1,440 +0,0 @@ -/** @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 - - */ diff --git a/doc/manual/release.txt b/doc/manual/release.txt deleted file mode 100644 index d144756..0000000 --- a/doc/manual/release.txt +++ /dev/null @@ -1,465 +0,0 @@ -/** @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. - */ diff --git a/doc/manual/scripting.txt b/doc/manual/scripting.txt deleted file mode 100644 index 783541c..0000000 --- a/doc/manual/scripting.txt +++ /dev/null @@ -1,80 +0,0 @@ -/** @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! :-) - - */ diff --git a/doc/manual/server.txt b/doc/manual/server.txt deleted file mode 100644 index 3c2fbd0..0000000 --- a/doc/manual/server.txt +++ /dev/null @@ -1,316 +0,0 @@ -/** @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. - - */ diff --git a/doc/manual/style.txt b/doc/manual/style.txt deleted file mode 100644 index 2ff2a29..0000000 --- a/doc/manual/style.txt +++ /dev/null @@ -1,422 +0,0 @@ -/** @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 style_include_guards Include Guards - -Every header file should have a unique include guard to prevent multiple -inclusion. -To guarantee uniqueness, an include guard should be based on the filename and -the full path in the project source tree. - -For the header file src/helper/jim-nvp.h, the include guard would look like -this: - -@code -#ifndef OPENOCD_HELPER_JIM_NVP_H -#define OPENOCD_HELPER_JIM_NVP_H - -/* Your code here. */ - -#endif /* OPENOCD_HELPER_JIM_NVP_H */ -@endcode - -@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 - - */ diff --git a/doc/manual/target.txt b/doc/manual/target.txt deleted file mode 100644 index 7e9767f..0000000 --- a/doc/manual/target.txt +++ /dev/null @@ -1,46 +0,0 @@ -/** @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'. - - */ diff --git a/doc/manual/target/mips.txt b/doc/manual/target/mips.txt deleted file mode 100644 index 32c40b9..0000000 --- a/doc/manual/target/mips.txt +++ /dev/null @@ -1,536 +0,0 @@ -/** @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". - -*/ diff --git a/doc/manual/target/notarm.txt b/doc/manual/target/notarm.txt deleted file mode 100644 index 5d5be78..0000000 --- a/doc/manual/target/notarm.txt +++ /dev/null @@ -1,71 +0,0 @@ -/** @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 - - */ |
