[openocd-svn] Main OpenOCD repository branch, master, updated. v0.3.0-912-g910dd66

[David B. <dbr...@us...>]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "Main OpenOCD repository".

The branch, master has been updated
       via  910dd664ceb6faef5e9029e9b0848d7ccc63bf4b (commit)
      from  26d7ed08f9ff220be583179fdea76466739cf32d (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 910dd664ceb6faef5e9029e9b0848d7ccc63bf4b
Author: David Brownell <dbr...@us...>
Date:   Wed Dec 9 10:25:08 2009 -0800

    Comment and doxygen fixes
    
    Signed-off-by: David Brownell <dbr...@us...>

diff --git a/src/flash/nand/driver.h b/src/flash/nand/driver.h
index 545a731..fe73e90 100644
--- a/src/flash/nand/driver.h
+++ b/src/flash/nand/driver.h
@@ -86,7 +86,7 @@ struct nand_flash_controller
 
 /**
  * Find a NAND flash controller by name.
- * @param The name of the NAND controller to find.
+ * @param name Identifies the NAND controller to find.
  * @returns The nand_flash_controller named @c name, or NULL if not found.
  */
 struct nand_flash_controller *nand_driver_find_by_name(const char *name);
diff --git a/src/flash/nor/imp.h b/src/flash/nor/imp.h
index 4c849fe..34ccbe4 100644
--- a/src/flash/nor/imp.h
+++ b/src/flash/nor/imp.h
@@ -22,14 +22,12 @@
 // this is an internal header
 #include "core.h"
 #include "driver.h"
-// common flash internals
-#include <flash/common.h>
 // almost all drivers will need this file
 #include <target/target.h>
 
 /**
  * Adds a new NOR bank to the global list of banks.
- * @params bank The bank that should be added.
+ * @param bank The bank that should be added.
  */
 void flash_bank_add(struct flash_bank *bank);
 
diff --git a/src/jtag/jtag.h b/src/jtag/jtag.h
index fece652..fa2fcdc 100644
--- a/src/jtag/jtag.h
+++ b/src/jtag/jtag.h
@@ -417,24 +417,9 @@ typedef void (*jtag_callback1_t)(jtag_callback_data_t data0);
 void jtag_add_callback(jtag_callback1_t, jtag_callback_data_t data0);
 
 
-
-/**
- * Defines the interface of the JTAG callback mechanism.
- *
- * @param in the pointer to the data clocked in
- * @param data1 An integer big enough to use as an @c int or a pointer.
- * @param data2 An integer big enough to use as an @c int or a pointer.
- * @param data3 An integer big enough to use as an @c int or a pointer.
- * @returns an error code
- */
-typedef int (*jtag_callback_t)(jtag_callback_data_t data0,
-				jtag_callback_data_t data1,
-				jtag_callback_data_t data2,
-				jtag_callback_data_t data3);
-
-
 /**
- * This callback can be executed immediately the queue has been flushed.
+ * Defines the interface of the JTAG callback mechanism.  Such
+ * callbacks can be executed once the queue has been flushed.
  *
  * The JTAG queue can be executed synchronously or asynchronously.
  * Typically for USB, the queue is executed asynchronously.  For
@@ -448,19 +433,21 @@ typedef int (*jtag_callback_t)(jtag_callback_data_t data0,
  *
  * If the execution of the queue fails before the callbacks, then --
  * depending on driver implementation -- the callbacks may or may not be
- * invoked.  @todo Can we make this behavior consistent?
+ * invoked.
  *
- * The strange name is due to C's lack of overloading using function
- * arguments.
+ * @todo Make that behavior consistent.
  *
- * @param f The callback function to add.
  * @param data0 Typically used to point to the data to operate on.
  * Frequently this will be the data clocked in during a shift operation.
  * @param data1 An integer big enough to use as an @c int or a pointer.
  * @param data2 An integer big enough to use as an @c int or a pointer.
  * @param data3 An integer big enough to use as an @c int or a pointer.
- *
+ * @returns an error code
  */
+typedef int (*jtag_callback_t)(jtag_callback_data_t data0,
+				jtag_callback_data_t data1,
+				jtag_callback_data_t data2,
+				jtag_callback_data_t data3);
 
 /**
  * Run a TAP_RESET reset where the end state is TAP_RESET,
diff --git a/src/target/arm_opcodes.h b/src/target/arm_opcodes.h
index b3b5143..58498ac 100644
--- a/src/target/arm_opcodes.h
+++ b/src/target/arm_opcodes.h
@@ -26,6 +26,11 @@
 #ifndef __ARM_OPCODES_H
 #define __ARM_OPCODES_H
 
+/**
+ * @file
+ * Macros used to generate various ARM or Thumb opcodes.
+ */
+
 /* ARM mode instructions */
 
 /* Store multiple increment after
@@ -145,9 +150,13 @@
 
 /* Thumb mode instructions
  *
- * FIXME there must be some reason all these opcodes are 32-bits
- * not 16-bits ... this should get either an explanatory comment,
- * or be changed not to duplicate the opcode.
+ * NOTE: these 16-bit opcodes fill both halves of a word with the same
+ * value.  The reason for this is that when we need to execute Thumb
+ * opcodes on ARM7/ARM9 cores (to switch to ARM state on debug entry),
+ * we must shift 32 bits to the bus using scan chain 1 ... if we write
+ * both halves, we don't need to track which half matters.  On ARMv6 and
+ * ARMv7 we don't execute Thumb instructions in debug mode; the ITR
+ * register does not accept Thumb (or Thumb2) opcodes.
  */
 
 /* Store register (Thumb mode)
diff --git a/src/target/embeddedice.c b/src/target/embeddedice.c
index eb04bd1..a705d7d 100644
--- a/src/target/embeddedice.c
+++ b/src/target/embeddedice.c
@@ -35,7 +35,8 @@
  *
  * This provides lowlevel glue to the EmbeddedICE (or EmbeddedICE-RT)
  * module found on scan chain 2 in ARM7, ARM9, and some other families
- * of ARM cores.
+ * of ARM cores.  The module is called "EmbeddedICE-RT" if it has
+ * monitor mode support.
  *
  * EmbeddedICE provides basic watchpoint/breakpoint hardware and a Debug
  * Communications Channel (DCC) used to read or write 32-bit words to

-----------------------------------------------------------------------

Summary of changes:
 src/flash/nand/driver.h  |    2 +-
 src/flash/nor/imp.h      |    4 +---
 src/jtag/jtag.h          |   31 +++++++++----------------------
 src/target/arm_opcodes.h |   15 ++++++++++++---
 src/target/embeddedice.c |    3 ++-
 5 files changed, 25 insertions(+), 30 deletions(-)


hooks/post-receive
-- 
Main OpenOCD repository