summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDavid Brownell <dbrownell@users.sourceforge.net>2009-12-09 10:25:08 -0800
committerDavid Brownell <dbrownell@users.sourceforge.net>2009-12-09 10:25:52 -0800
commit910dd664ceb6faef5e9029e9b0848d7ccc63bf4b (patch)
treee94c456002048802ac86043a7ecaaf8ffb682697
parent26d7ed08f9ff220be583179fdea76466739cf32d (diff)
downloadopenocd_libswd-910dd664ceb6faef5e9029e9b0848d7ccc63bf4b.tar.gz
openocd_libswd-910dd664ceb6faef5e9029e9b0848d7ccc63bf4b.tar.bz2
openocd_libswd-910dd664ceb6faef5e9029e9b0848d7ccc63bf4b.tar.xz
openocd_libswd-910dd664ceb6faef5e9029e9b0848d7ccc63bf4b.zip
Comment and doxygen fixes
Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>
-rw-r--r--src/flash/nand/driver.h2
-rw-r--r--src/flash/nor/imp.h4
-rw-r--r--src/jtag/jtag.h31
-rw-r--r--src/target/arm_opcodes.h15
-rw-r--r--src/target/embeddedice.c3
5 files changed, 25 insertions, 30 deletions
diff --git a/src/flash/nand/driver.h b/src/flash/nand/driver.h
index 545a731b..fe73e906 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 4c849fef..34ccbe4e 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 fece6521..fa2fcdca 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 b3b51433..58498ac2 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 eb04bd12..a705d7dd 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