You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2016/06/17 23:39:29 UTC
[44/63] [abbrv] [partial] incubator-mynewt-site git commit: remove
untarred files for openocd
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/69f466b5/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/primer/autotools.txt
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/primer/autotools.txt b/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/primer/autotools.txt
deleted file mode 100755
index 9d9aada..0000000
--- a/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/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.
-
- */
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/69f466b5/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/primer/commands.txt
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/primer/commands.txt b/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/primer/commands.txt
deleted file mode 100755
index 5f89d50..0000000
--- a/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/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
-
- */
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/69f466b5/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/primer/docs.txt
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/primer/docs.txt b/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/primer/docs.txt
deleted file mode 100755
index 504da79..0000000
--- a/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/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
-
- */
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/69f466b5/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/primer/jtag.txt
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/primer/jtag.txt b/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/primer/jtag.txt
deleted file mode 100755
index 41eef72..0000000
--- a/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/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.
- */
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/69f466b5/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/primer/tcl.txt
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/primer/tcl.txt b/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/primer/tcl.txt
deleted file mode 100755
index 9be4a05..0000000
--- a/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/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
-
- */
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/69f466b5/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/release.txt
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/release.txt b/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/release.txt
deleted file mode 100755
index d144756..0000000
--- a/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/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.
- */
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/69f466b5/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/scripting.txt
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/scripting.txt b/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/scripting.txt
deleted file mode 100755
index 783541c..0000000
--- a/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/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! :-)
-
- */
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/69f466b5/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/server.txt
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/server.txt b/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/doc/manual/server.txt
deleted file mode 100755
index 3c2fbd0..0000000
--- a/docs/os/tutorials/downloads/openocd-code-89bf96ffe6ac66c80407af8383b9d5adc0dc35f4/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.
-
- */