From 910dd664ceb6faef5e9029e9b0848d7ccc63bf4b Mon Sep 17 00:00:00 2001 From: David Brownell Date: Wed, 9 Dec 2009 10:25:08 -0800 Subject: [PATCH] Comment and doxygen fixes Signed-off-by: David Brownell --- 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(-) 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 // almost all drivers will need this file #include /** * 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 -- 2.39.5