usb_blaster: maintainer-clean Makefile.in
[openocd.git] / TODO
diff --git a/TODO b/TODO
index e8f90d9..8aac157 100644 (file)
--- a/TODO
+++ b/TODO
@@ -1,15 +1,10 @@
-/** @page thelist Pending and Open Tasks
+// This file is part of the Doxygen Developer Manual
+/** @page tasks Pending and Open Tasks
 
 This page lists pending and open tasks being considered or worked upon
 by the OpenOCD community.
 
-
-Items with a current patch available should include a link to its
-posting on the openocd-developer mailing list archives.
-
-Some items may be in progress, usually indicated by the individual whose
-initials in parentheses following it.  A key for decoding these initials
-appears after The List.
+@section thelist The List
 
 Most items are open for the taking, but please post to the mailing list
 before spending much time working on anything lists here.  The community
@@ -17,129 +12,369 @@ may have evolved an idea since it was added here.
 
 Feel free to send patches to add or clarify items on this list, too.
 
-@verbatim
-================================================================== 
-                             The List
-------------------------------------------------------------------
-@endverbatim
-
-- JTAG/TAP changes:
-  - update all drivers to use tap_get_tms_path_len API.
-  - use tap_set_state everywhere to allow logging TAP state transitions
-  - rename other tap_states to use standard JTAG names (suggested by ML)
-  - add TAP_UNKNOWN to augment TAP_INVALID? (suggested by ML/DH)
-  
-- JTAG Interfaces:
-  - autodetect devices present on the scan chain
-    - implement 'discover_taps' command
-  - FT2232 driver: (DH)
-    - integrate FTD2XX High-Speed Device support
-      - PATCH: https://lists.berlios.de/pipermail/openocd-development/2009-April/005479.html
-    - massive set of changes (DH):
-      - fixes non-recoverability of cable connect/reconnect
-      - https://lists.berlios.de/pipermail/openocd-development/2009-May/006011.html
-    - further cleanup (DH):
-      - PATCH: https://lists.berlios.de/pipermail/openocd-development/2009-May/006112.html
-    - fix outstanding bugs
-  - J-Link driver: (ZW)
-    - fix outstanding bugs
-    - test with known targets (i.e. working with other interfaces)
-    - test compatibility between v6.0 (yellow) and older units (e.g. v5.2)
-  - TCP driver:
-    - add TCP/IP client and server for remote JTAG interface control
-  - Do others need some help?  Probably....
-
-- Other Interfaces
-  - SVF/XSVF:
-    - pending tasks??
-  - SPI/UART emulation:
-    - (ab)use bit-banging JTAG interfaces to emulate SPI/UART
-    - allow SPI to program flash, MCUs, etc.
-  - SWD
-
-- Target Support:
-  - general layer cleanup:
-    - https://lists.berlios.de/pipermail/openocd-development/2009-May/006590.html
-  - ARM11 improvements (MB?)
-    - fix single stepping  (reported by ØH)
-    - implement missing functionality (grep FNC_INFO_NOTIMPLEMENTED ...)
-  - Cortex A8 support (ML)
-    - add target implementation (ML)
-    - what else remains to be done?
-  - MC1322x support (JW/DE?)
-    - integrate and test support from JW (and DE?)
-    - get working with a known good interface (i.e. not today's jlink)
-  - AT91SAM92xx:
-    - improvements for unknown-board-atmel-at91sam9260.cfg (RD)
-  - STR9x: (ZW)
-    - improvements to str912.cfg to be more general purpose
-  - AVR: (SQ)
-    - independently verify implementation
-    - incrementally improve working prototype in trunk. (SQ)
-    - work out how to debug this target
-    - AVR debugging protocol.
-  - FPGA:
-    - improve things (??)
-  - Coldfire (suggested by NC)
-    - can we draw from the BDM project?  @par
-      http://bdm.sourceforge.net/
-
-  - other targets?  (suggestions always welcome)
-
-- CFI:
-  - finish implementing bus width/chip width handling (suggested by NC)
-  - factor vendor-specific code into separate source files
+@section thelisttcl TCL
+
+This section provides possible things to improve with OpenOCD's TCL support.
+
+- Fix problem with incorrect line numbers reported for a syntax
+  error in a reset init event.
+
+- organize the TCL configurations:
+  - provide more directory structure for boards/targets?
+  - factor configurations into layers (encapsulation and re-use)
+
+- Fix handling of variables between multiple command line "-c" and "-f"
+  parameters.  Currently variables assigned through one such parameter
+  command/script are unset before the next one is invoked.
+
+- Isolate all TCL command support:
+  - Pure C CLI implementations using --disable-builtin-tcl.
+    - Allow developers to build new dongles using OpenOCD's JTAG core.
+    - At first, provide only low-level JTAG support; target layer and
+      above rely heavily on scripting event mechanisms.
+  - Allow full TCL support? add --with-tcl=/path/to/installed/tcl
+  - Move TCL support out of foo.[ch] and into foo_tcl.[ch] (other ideas?)
+    - See src/jtag/core.c and src/jtag/tcl.c for an example.
+    - allow some of these TCL command modules to be dynamically loadable?
+
+@section thelistjtag JTAG
+
+This section list issues that need to be resolved in the JTAG layer.
+
+@subsection thelistjtagcore JTAG Core
+
+The following tasks have been suggested for cleaning up the JTAG layer:
+
+- use tap_set_state everywhere to allow logging TAP state transitions
+- Encapsulate cmd_queue_cur_state and related variable handling.
+- add slick 32 bit versions of jtag_add_xxx_scan() that avoids
+buf_set_u32() calls and other evidence of poor impedance match between
+API and calling code. New API should cut down # of lines in calling
+code by 100's and make things clearer. Also potentially be supported
+directly in minidriver API for better embedded host performance.
+
+The following tasks have been suggested for adding new core JTAG support:
+
+- Improve autodetection of TAPs by supporting tcl escape procedures that
+  can configure discovered TAPs based on IDCODE value ... they could:
+    - Remove guessing for irlen
+    - Allow non-default irmask/ircapture values
+- SPI/UART emulation:
+  - (ab)use bit-banging JTAG interfaces to emulate SPI/UART
+  - allow SPI to program flash, MCUs, etc.
+
+@subsection thelistjtaginterfaces JTAG Interfaces
+
+There are some known bugs to fix in JTAG adapter drivers:
+
+- For JTAG_STATEMOVE to TAP_RESET, all drivers must ignore the current
+  recorded state.  The tap_get_state() call won't necessarily return
+  the correct value, especially at server startup.  Fix is easy:  in
+  that case, always issue five clocks with TMS high.
+  - amt_jtagaccel.c
+  - arm-jtag-ew.c
+  - bitbang.c
+  - bitq.c
+  - gw16012.c
+  - jlink.c
+  - usbprog.c
+  - vsllink.c
+  - rlink/rlink.c
+- bug: USBprog is broken with new tms sequence; it needs 7-clock cycles.
+  Fix promised from  Peter Denison openwrt at marshadder.org
+  Workaround: use "tms_sequence long" @par
+  https://lists.berlios.de/pipermail/openocd-development/2009-July/009426.html
+
+The following tasks have been suggested for improving OpenOCD's JTAG
+interface support:
+
+- rework USB communication to be more robust.  Two possible options are:
+  -# use libusb-1.0.1 with libusb-compat-0.1.1 (non-blocking I/O wrapper)
+  -# rewrite implementation to use non-blocking I/O
+- J-Link driver:
+  - fix to work with long scan chains, such as R.Doss's svf test.
+- FT2232 (libftdi):
+  - make performance comparable to alternatives (on Win32, D2XX is faster)
+  - make usability comparable to alternatives
+- Autodetect USB based adapters; this should be easy on Linux.  If there's
+  more than one, list the options; otherwise, just select that one.
+
+The following tasks have been suggested for adding new JTAG interfaces:
+
+- TCP driver: allow client/server for remote JTAG interface control.
+This requires a client and a server. The server is built into the
+normal OpenOCD and takes commands from the client and executes
+them on the interface returning the result of TCP/IP. The client
+is an OpenOCD which is built with a TCP/IP minidriver. The use
+of a minidriver is required to capture all the jtag_add_xxx()
+fn's at a high enough level and repackage these cmd's as
+TCP/IP packets handled by the server.
+
+@section thelistswd Serial Wire Debug
+
+- implement Serial Wire Debug interface
+
+@section thelistbs Boundary Scan Support
+
+- add STAPL support?
+- add BSDL support?
+
+A few possible options for the above:
+  -# Fake a TCL equivalent?
+  -# Integrate an existing library?
+  -# Write a new C implementation a la Jim?
+
+Once the above are completed:
+- add support for programming flash using boundary scan techniques
+- add integration with a modified gerber view program:
+  - provide means to view the PCB and select pins and traces
+  - allow use-cases such as the following:
+    - @b Stimulus
+      -# Double-click on a pin (or trace) with the mouse.
+    - @b Effects
+      -# The trace starts blinking, and
+      -# OpenOCD toggles the pin(s) 0/1.
+
+@section thelisttargets Target Support
+
+- Many common ARM cores could be autodetected using IDCODE
+- general layer cleanup: @par
+  https://lists.berlios.de/pipermail/openocd-development/2009-May/006590.html
+- regression: "reset halt" between 729(works) and 788(fails): @par
+https://lists.berlios.de/pipermail/openocd-development/2009-July/009206.html
+- registers
+  - add flush-value operation, call them all on resume/reset
+- mcr/mrc target->type support
+  - missing from ARM920t, ARM966e, XScale.
+  It's possible that the current syntax is unable to support read-modify-write
+  operations(see arm966e).
+  - mcr/mrc - retire cp15 commands when there the mrc/mrc commands have been
+  tested from: arm926ejs, arm720t, cortex_a8
+- ARM7/9:
+  - clean up "arm9tdmi vector_catch". Available for some arm7 cores? @par
+https://lists.berlios.de/pipermail/openocd-development/2009-October/011488.html
+https://lists.berlios.de/pipermail/openocd-development/2009-October/011506.html
+  - add reset option to allow programming embedded ice while srst is asserted.
+  Some CPUs will gate the JTAG clock when srst is asserted and in this case,
+  it is necessary to program embedded ice and then assert srst afterwards.
+- ARM926EJS:
+  - reset run/halt/step is not robust; needs testing to map out problems.
+- ARM11 improvements (MB?)
+  - add support for asserting srst to reset the core.
+  - Single stepping works, but should automatically
+  use hardware stepping if available.
+  - mdb can return garbage data if read byte operation fails for
+  a memory region(16 & 32 byte access modes may be supported). Is this
+  a bug in the .MX31 PDK init script? Try on i.MX31 PDK:
+  mdw 0xb80005f0 0x8, mdh 0xb80005f0 0x10, mdb 0xb80005f0 0x20. mdb returns
+  garabage.
+  - implement missing functionality (grep FNC_INFO_NOTIMPLEMENTED ...)
+- Thumb2 single stepping: ARM1156T2 needs simulator support
+- Cortex A8 support (ML)
+  - add target implementation (ML)
+- Cortex M3 support
+  - when stepping, only write dirtied registers (be faster)
+  - when connecting to halted core, fetch registers (startup is quirky)
+- Generic ARM run_algorithm() interface
+  - tagged struct wrapping ARM instructions and metadata
+  - not revision-specific (current: ARMv4+ARMv5 -or- ARMv6 -or- ARMv7)
+  - usable with at least arm_nandwrite() and generic CFI drivers
+- ETM
+  - don't show FIFOFULL registers if they're not supported
+  - use comparators to get more breakpoints and watchpoints
+  - add "etm drivers" command
+  - trace driver init() via examine() paths only, not setup()/reset
+- MC1322x support (JW/DE?)
+  - integrate and test support from JW (and DE?)
+  - get working with a known good interface (i.e. not today's jlink)
+- AT91SAM92xx:
+  - improvements for unknown-board-atmel-at91sam9260.cfg (RD)
+- STR9x: (ZW)
+  - improvements to str912.cfg to be more general purpose
+- AVR: (SQ)
+  - independently verify implementation
+  - incrementally improve working prototype in trunk. (SQ)
+  - work out how to debug this target
+  - AVR debugging protocol.
+- FPGA:
+  - Altera Nios Soft-CPU support
+- Coldfire (suggested by NC)
+  - can we draw from the BDM project?  @par
+    http://bdm.sourceforge.net/
+
+    or the OSBDM package @par
+    http://forums.freescale.com/freescale/board/message?board.id=OSBDM08&thread.id=422
+
+@section thelistsvf SVF/XSVF
+
+- develop SVF unit tests
+- develop XSVF unit tests
+
+@section thelistflash Flash Support
+
+- finish documentation for the following flash drivers:
+  - avr
+  - pic32mx
+  - ocl
+  - str9xpec
+
+- Don't expect writing all-ones to be a safe way to write without
+  changing bit values.  Minimally it loses on flash modules with
+  internal ECC, where it may change the ECC.
+  - NOR flash_write_unlock() does that between sectors
+  - there may be other cases too
+
+- Make sure all commands accept either a bank name or a bank number,
+  and be sure both identifiers show up in "flash banks" and "nand list".
+  Right now the user-friendly names are pretty much hidden...
+
+@subsection thelistflashcfi CFI
+
+- finish implementing bus width/chip width handling (suggested by NC)
+- factor vendor-specific code into separate source files
   - add new callback interface for vendor-specific code
-  - investigate/implement "thin wrapper" to use eCos CFI drivers (ØH)
-
-- TCL
-  - mem2array bugs:
-    - Report: https://lists.berlios.de/pipermail/openocd-development/2009-May/006459.html
-  - Isolate all TCL command support: 
-    - Allow pure C CLI implementations using --disable-builtin-tcl
-    - Allow full TCL support? add --with-tcl=/path/to/installed/tcl
-    - Move TCL support in foo.* to foo_tcl.* (other ideas?)
-
-- Debugger Support
-  - Keil AGDI interface to OpenOCD (submitted by Dario Vecchio)
-
-- Architectural Upgrades
-  - Allow N:M:P mapping of servers, targets, and interfaces
-  - loadable module support for interface/target/flash drivers
-  - libopenocd support: @par
-      https://lists.berlios.de/pipermail/openocd-development/2009-May/006405.html
-
-- Test Suite:
-  - implement server unit tests
-  - implement JTAG core unit tests
-  - implement JTAG interface unit tests
-  - implement flash unit tests
-  - implement target unit tests
-
-- Test Feedback Tools: @par
-      https://lists.berlios.de/pipermail/openocd-development/2009-May/006358.html
-
-  - extend target test script to produce helpful pass/fail output
-  - provide results submission script
-
-
-- Generic Hardware Tester:
-  - implement VHDL to use for FPGA-based JTAG TAP testing device
-  - develop test suite that utilizes this testing device
-
-- Build Systems (Autotools, CMake, etc.)
-  - investigate fixes to permit the use of -Wshadow
-  - change bootstrap to call 'configure --enable-maintainer-mode <opts>'?
-
-- Miscellaneous:
-  - make JTAG and USB debug output a run-time configuration option
-  - review and clean up interface/target/flash APIs 
-  - factor code to eliminate duplicated functionality
-  - overhaul use of types to improve 32/64-bit portability
-
-- Berlios Admin:
-  - use patch tracker? @par
-    https://developer.berlios.de/patch/?group_id=4148
-  - use bug tracking?  we need something!
+- investigate/implement "thin wrapper" to use eCos CFI drivers (ØH)
+
+@section thelistdebug Debugger Support
+
+- add support for masks in watchpoints? @par
+  https://lists.berlios.de/pipermail/openocd-development/2009-October/011507.html
+- breakpoints can get lost in some circumstances: @par
+  https://lists.berlios.de/pipermail/openocd-development/2009-June/008853.html
+- add support for masks in watchpoints. The trick is that GDB does not
+  support a breakpoint mask in the remote protocol. One way to work around
+  this is to add a separate command "watchpoint_mask add/rem <addr> <mask>", that
+  is run to register a list of masks that the gdb_server knows to use with
+  a particular watchpoint address.
+- integrate Keil AGDI interface to OpenOCD? (submitted by Dario Vecchio)
+
+@section thelisttesting Testing Suite
+
+This section includes several related groups of ideas:
+- @ref thelistunittests
+- @ref thelistsmoketests
+- @ref thelisttestreports
+- @ref thelisttestgenerichw
+
+@subsection thelistunittests Unit Tests
+
+- add testing skeleton to provide frameworks for adding tests
+- implement server unit tests
+- implement JTAG core unit tests
+- implement JTAG interface unit tests
+- implement flash unit tests
+- implement target unit tests
+
+@subsection thelistsmoketests Smoke Test Tools
+
+-# extend 'make check' with a smoketest app
+  - checks for OOCD_TEST_CONFIG, etc. in environment (or config file)
+  - if properly set, runs the smoke test with specified parameters
+    - openocd -f ${OOCD_TEST_CONFIG}
+    - implies a modular test suite (see below)
+  - should be able to run some minimal tests with dummy interface:
+    - compare results of baseline sanity checks with expected results
+
+-# builds a more complete test suite:
+  - existing testing/examples/ look like a great start
+  - all targets should be tested fully and for all capabilities
+    - we do NOT want a "lowest common denominator" test suite
+    - ... but can we start with one to get going?
+  - probably requires one test configuration file per board/target
+    - modularization can occur here, just like with targets/boards/chips
+    - coverage can increase over time, building up bundles of tests
+
+-# add new 'smoketest' Makefile target:
+  - calls 'make check' (and the smoketest app)
+  - gather inputs and output into a report file
+
+@subsection thelisttestreports Test Feedback Tools
+
+These ideas were first introduced here: @par
+  https://lists.berlios.de/pipermail/openocd-development/2009-May/006358.html
+
+- provide report submission scripts for e-mail and web forms
+- add new Makefile targets to post the report:
+  - 'checkreportsend' -- send to list via e-mail (via sendmail)
+  - 'checkreportpost' -- send web form (via curl or other script)
+
+@subsection thelisttestgenerichw Generic Hardware Tester
+
+- implement VHDL to use for FPGA-based JTAG TAP testing device
+- develop test suite that utilizes this testing device
+
+@section thelistautotools Autotools Build System
+
+- make entire configure process require less user consideration:
+  - automatically detect the features that are available, unless
+    options were specifically provided to configure
+  - provide a report of the drivers that will be build at the end of
+    running configure, so the users can verify which drivers will be
+    built during 'make' (and their options) .
+- eliminate sources of confusion in @c bootstrap script:
+  -# Make @c bootstrap call 'configure --enable-maintainer-mode \<opts\>'?
+  -# Add @c buildstrap script to assist with bootstrap and configure steps.
+- automatically build tool-chains required for cross-compiling
+  - produce mingw32, arm-elf, others using in-tree scripts
+  - build all required target code from sources
+- make JTAG and USB debug output a run-time configuration option
+
+@section thelistarchitecture Architectural Tasks
+
+The following architectural tasks need to be accomplished and should be
+fairly easy to complete:
+
+
+- use dynamic allocations for working memory. Scan & fix code
+for excessive stack allocations. take linux/scripts/checkstack.pl and
+see what the worst offenders are. Dynamic stack allocations are found
+at the bottom of the list below.  Example, on amd64:
+
+ $ objdump -d | checkstack.pl | head -10
+ 0x004311e3 image_open [openocd]:                      13464
+ 0x00431301 image_open [openocd]:                      13464
+ 0x004237a4 target_array2mem [openocd]:                        4376
+ 0x0042382b target_array2mem [openocd]:                        4376
+ 0x00423e74 target_mem2array [openocd]:                        4360
+ 0x00423ef9 target_mem2array [openocd]:                        4360
+ 0x00404aed handle_svf_command [openocd]:              2248
+ 0x00404b7e handle_svf_command [openocd]:              2248
+ 0x00413581 handle_flash_fill_command [openocd]:               2200
+ 0x004135fa handle_flash_fill_command [openocd]:               2200
+- clean-up code to match style guides
+- factor code to eliminate duplicated functionality
+- rewrite code that uses casts to access 16-bit and larger types
+  from unaligned memory addresses
+- libopenocd support: @par
+    https://lists.berlios.de/pipermail/openocd-development/2009-May/006405.html
+- review and clean up interface/target/flash APIs
+
+The following strategic tasks will require ambition, knowledge, and time
+to complete:
+
+- overhaul use of types to improve 32/64-bit portability
+  - types for both host and target word sizes?
+  - can we use GDB's CORE_TYPE support?
+- Allow N:M:P mapping of servers, targets, and interfaces
+- loadable module support for interface/target/flash drivers and commands
+  - support both static and dynamic modules.
+  - should probably use libltdl for dynamic library handing.
+
+@section thelistadmin Documentation Tasks
+
+- Develop milestone and release guidelines, processes, and scripts.
+- Develop "style" guidelines (and scripts) for maintainers:
+  - reviewing patches
+  - committing to git
+- Review Users' Guide for documentation errors or omissions
+  - "capture" and "ocd_find" commands
+  - "ocd_" prefix on various stuff
+- Update Developer's Manual (doxygen output)
+  - Add documentation describing the architecture of each module
+  - Provide more Technical Primers to bootstrap contributor knowledge
 
 */
+/** @file
+This file contains the @ref thelist page.
+*/
+