openocd: fix doxygen parameters of functions

Add to doxygen comment the missing parameters.
Remove from doxygen comment any non-existing parameter.
Fix the parameter names in doxygen comment to match the one in the
function prototype.
Where the parameter name in the doxygen description seems better
than the one in the code, change the code.
Escape the character '<' to prevent doxygen to interpret it as an
xml tag.

Change-Id: I22da723339ac7d7a7a64ac4c1cc4336e2416c2cc
Signed-off-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-on: http://openocd.zylin.com/6002
Tested-by: jenkins
This commit is contained in:
Antonio Borneo 2021-01-02 20:35:09 +01:00
parent 4cf5ab614b
commit 7e64e5a895
18 changed files with 75 additions and 62 deletions

View File

@ -105,7 +105,7 @@ static int at91sam9_init(struct nand_device *nand)
/**
* Enable NAND device attached to a controller.
*
* @param info NAND controller information for controlling NAND device.
* @param nand NAND controller information for controlling NAND device.
* @return Success or failure of the enabling.
*/
static int at91sam9_enable(struct nand_device *nand)
@ -119,7 +119,7 @@ static int at91sam9_enable(struct nand_device *nand)
/**
* Disable NAND device attached to a controller.
*
* @param info NAND controller information for controlling NAND device.
* @param nand NAND controller information for controlling NAND device.
* @return Success or failure of the disabling.
*/
static int at91sam9_disable(struct nand_device *nand)

View File

@ -1709,6 +1709,9 @@ static int FLASHD_EraseEntireBank(struct sam4_bank_private *pPrivate)
/**
* Erases the entire flash.
* @param pPrivate - the info about the bank.
* @param firstPage
* @param numPages
* @param status
*/
static int FLASHD_ErasePages(struct sam4_bank_private *pPrivate,
int firstPage,

View File

@ -276,7 +276,8 @@ struct flash_bank *get_flash_bank_by_num_noprobe(unsigned int num);
* @param target The target, presumed to contain one or more banks.
* @param addr An address that is within the range of the bank.
* @param check return ERROR_OK and result_bank NULL if the bank does not exist
* @returns The struct flash_bank located at @a addr, or NULL.
* @param result_bank The struct flash_bank located at @a addr, or NULL.
* @returns ERROR_OK on success, or an error indicating the problem.
*/
int get_flash_bank_by_addr(struct target *target, target_addr_t addr, bool check,
struct flash_bank **result_bank);

View File

@ -453,8 +453,8 @@ static int lpc2900_write_index_page(struct flash_bank *bank,
/**
* Calculate FPTR.TR register value for desired program/erase time.
*
* @param clock System clock in Hz
* @param time Program/erase time in µs
* @param clock_var System clock in Hz
* @param time_var Program/erase time in µs
*/
static uint32_t lpc2900_calc_tr(uint32_t clock_var, uint32_t time_var)
{

View File

@ -873,7 +873,6 @@ exit:
/** ***********************************************************************************************
* @brief Performs Mass Erase operation
* @param bank flash bank index to erase
* @return ERROR_OK in case of success, ERROR_XXX code otherwise
*************************************************************************************************/
COMMAND_HANDLER(psoc6_handle_mass_erase_command)

View File

@ -48,6 +48,7 @@ uint8_t delay_tms;
* Maximum achievable TCK frequency is 182 kHz for ULINK clocked at 24 MHz.
*
* @param out_offset offset in OUT2BUF where payload data starts
* @param in_offset
*/
void jtag_scan_in(uint8_t out_offset, uint8_t in_offset)
{
@ -125,6 +126,7 @@ void jtag_scan_in(uint8_t out_offset, uint8_t in_offset)
* Maximum achievable TCK frequency is 113 kHz for ULINK clocked at 24 MHz.
*
* @param out_offset offset in OUT2BUF where payload data starts
* @param in_offset
*/
void jtag_slow_scan_in(uint8_t out_offset, uint8_t in_offset)
{
@ -373,6 +375,7 @@ void jtag_slow_scan_out(uint8_t out_offset)
* Maximum achievable TCK frequency is 100 kHz for ULINK clocked at 24 MHz.
*
* @param out_offset offset in OUT2BUF where payload data starts
* @param in_offset
*/
void jtag_scan_io(uint8_t out_offset, uint8_t in_offset)
{
@ -465,6 +468,7 @@ void jtag_scan_io(uint8_t out_offset, uint8_t in_offset)
* Maximum achievable TCK frequency is 78 kHz for ULINK clocked at 24 MHz.
*
* @param out_offset offset in OUT2BUF where payload data starts
* @param in_offset
*/
void jtag_slow_scan_io(uint8_t out_offset, uint8_t in_offset)
{

View File

@ -1062,7 +1062,6 @@ static void ftdi_swd_swdio_en(bool enable)
/**
* Flush the MPSSE queue and process the SWD transaction queue
* @param dap
* @return
*/
static int ftdi_swd_run_queue(void)

View File

@ -227,8 +227,8 @@ static int jtag_vpi_reset(int trst, int srst)
* @param nb_bits number of TMS bits (between 1 and 8)
*
* Write a series of TMS transitions, where each transition consists in :
* - writing out TCK=0, TMS=<new_state>, TDI=<???>
* - writing out TCK=1, TMS=<new_state>, TDI=<???> which triggers the transition
* - writing out TCK=0, TMS=\<new_state>, TDI=\<???>
* - writing out TCK=1, TMS=\<new_state>, TDI=\<???> which triggers the transition
* The function ensures that at the end of the sequence, the clock (TCK) is put
* low.
*/
@ -253,8 +253,8 @@ static int jtag_vpi_tms_seq(const uint8_t *bits, int nb_bits)
* @param cmd path transition
*
* Write a series of TMS transitions, where each transition consists in :
* - writing out TCK=0, TMS=<new_state>, TDI=<???>
* - writing out TCK=1, TMS=<new_state>, TDI=<???> which triggers the transition
* - writing out TCK=0, TMS=\<new_state>, TDI=\<???>
* - writing out TCK=1, TMS=\<new_state>, TDI=\<???> which triggers the transition
* The function ensures that at the end of the sequence, the clock (TCK) is put
* low.
*/
@ -344,6 +344,7 @@ static int jtag_vpi_queue_tdi_xfer(uint8_t *bits, int nb_bits, int tap_shift)
* jtag_vpi_queue_tdi - short description
* @param bits bits to be queued on TDI (or NULL if 0 are to be queued)
* @param nb_bits number of bits
* @param tap_shift
*/
static int jtag_vpi_queue_tdi(uint8_t *bits, int nb_bits, int tap_shift)
{

View File

@ -696,6 +696,7 @@ static int ulink_append_queue(struct ulink *device, struct ulink_cmd *ulink_cmd)
* Sends all queued OpenULINK commands to the ULINK for execution.
*
* @param device pointer to struct ulink identifying ULINK driver instance.
* @param timeout
* @return on success: ERROR_OK
* @return on failure: ERROR_FAIL
*/
@ -1682,6 +1683,7 @@ static int ulink_queue_runtest(struct ulink *device, struct jtag_command *cmd)
/**
* Execute a JTAG_RESET command
*
* @param device
* @param cmd pointer to the command that shall be executed.
* @return on success: ERROR_OK
* @return on failure: ERROR_FAIL

View File

@ -364,8 +364,8 @@ static void ublast_idle_clock(void)
* @param type scan type (ie. does a readback of TDO is required)
*
* Output a TDI bit and assert clock to push it into the JTAG device :
* - writing out TCK=0, TMS=<old_state>=0, TDI=<tdi>
* - writing out TCK=1, TMS=<new_state>, TDI=<tdi> which triggers the JTAG
* - writing out TCK=0, TMS=\<old_state>=0, TDI=\<tdi>
* - writing out TCK=1, TMS=\<new_state>, TDI=\<tdi> which triggers the JTAG
* device acquiring the data.
*
* If a TDO is to be read back, the required read is requested (bitbang mode),
@ -448,8 +448,8 @@ static void ublast_queue_bytes(uint8_t *bytes, int nb_bytes)
* @param skip number of TMS bits to skip at the beginning of the series
*
* Write a series of TMS transitions, where each transition consists in :
* - writing out TCK=0, TMS=<new_state>, TDI=<???>
* - writing out TCK=1, TMS=<new_state>, TDI=<???> which triggers the transition
* - writing out TCK=0, TMS=\<new_state>, TDI=\<???>
* - writing out TCK=1, TMS=\<new_state>, TDI=\<???> which triggers the transition
* The function ensures that at the end of the sequence, the clock (TCK) is put
* low.
*/
@ -478,8 +478,8 @@ static void ublast_tms(struct tms_command *cmd)
* @param cmd path transition
*
* Write a series of TMS transitions, where each transition consists in :
* - writing out TCK=0, TMS=<new_state>, TDI=<???>
* - writing out TCK=1, TMS=<new_state>, TDI=<???> which triggers the transition
* - writing out TCK=0, TMS=\<new_state>, TDI=\<???>
* - writing out TCK=1, TMS=\<new_state>, TDI=\<???> which triggers the transition
* The function ensures that at the end of the sequence, the clock (TCK) is put
* low.
*/
@ -525,7 +525,7 @@ static void ublast_state_move(tap_state_t state, int skip)
/**
* ublast_read_byteshifted_tdos - read TDO of byteshift writes
* @param buf the buffer to store the bits
* @param nb_bits the number of bits
* @param nb_bytes the number of bytes
*
* Reads back from USB Blaster TDO bits, triggered by a 'byteshift write', ie. eight
* bits per received byte from USB interface, and store them in buffer.

View File

@ -237,7 +237,7 @@ const struct rtt_control *rtt_get_control(void);
* Read channel information.
*
* @param[in] channel_index Channel index.
* @param[in] channel_type Channel type.
* @param[in] type Channel type.
* @param[out] info Channel information.
*
* @returns ERROR_OK on success, an error code on failure.

View File

@ -924,6 +924,7 @@ exit:
* Finds an actionpoint that triggered last actionpoint event, as specified by
* DEBUG.ASR.
*
* @param target
* @param actionpoint Pointer to be set to last active actionpoint. Pointer
* will be set to NULL if DEBUG.AH is 0.
*/

View File

@ -237,7 +237,7 @@ static void arc_jtag_enque_register_rw(struct arc_jtag *jtag_info, uint32_t *add
* @param type Type of registers to write: core or aux.
* @param addr Array of registers numbers.
* @param count Amount of registers in arrays.
* @param values Array of register values.
* @param buffer Array of register values.
*/
static int arc_jtag_write_registers(struct arc_jtag *jtag_info, uint32_t type,
uint32_t *addr, uint32_t count, const uint32_t *buffer)
@ -272,7 +272,7 @@ static int arc_jtag_write_registers(struct arc_jtag *jtag_info, uint32_t type,
* @param type Type of registers to read: core or aux.
* @param addr Array of registers numbers.
* @param count Amount of registers in arrays.
* @param values Array of register values.
* @param buffer Array of register values.
*/
static int arc_jtag_read_registers(struct arc_jtag *jtag_info, uint32_t type,
uint32_t *addr, uint32_t count, uint32_t *buffer)
@ -337,7 +337,7 @@ int arc_jtag_write_core_reg_one(struct arc_jtag *jtag_info, uint32_t addr,
* @param jtag_info
* @param addr Array of registers numbers.
* @param count Amount of registers in arrays.
* @param values Array of register values.
* @param buffer Array of register values.
*/
int arc_jtag_write_core_reg(struct arc_jtag *jtag_info, uint32_t *addr,
uint32_t count, const uint32_t *buffer)
@ -361,7 +361,7 @@ int arc_jtag_read_core_reg_one(struct arc_jtag *jtag_info, uint32_t addr,
* @param jtag_info
* @param addr Array of core register numbers.
* @param count Amount of registers in arrays.
* @param values Array of register values.
* @param buffer Array of register values.
*/
int arc_jtag_read_core_reg(struct arc_jtag *jtag_info, uint32_t *addr,
uint32_t count, uint32_t *buffer)
@ -385,7 +385,7 @@ int arc_jtag_write_aux_reg_one(struct arc_jtag *jtag_info, uint32_t addr,
* @param jtag_info
* @param addr Array of registers numbers.
* @param count Amount of registers in arrays.
* @param values Array of register values.
* @param buffer Array of register values.
*/
int arc_jtag_write_aux_reg(struct arc_jtag *jtag_info, uint32_t *addr,
uint32_t count, const uint32_t *buffer)
@ -409,7 +409,7 @@ int arc_jtag_read_aux_reg_one(struct arc_jtag *jtag_info, uint32_t addr,
* @param jtag_info
* @param addr Array of AUX register numbers.
* @param count Amount of registers in arrays.
* @param values Array of register values.
* @param buffer Array of register values.
*/
int arc_jtag_read_aux_reg(struct arc_jtag *jtag_info, uint32_t *addr,
uint32_t count, uint32_t *buffer)

View File

@ -450,7 +450,7 @@ static int mem_ap_write(struct adiv5_ap *ap, const uint8_t *buffer, uint32_t siz
* @param buffer The data buffer to receive the data. No particular alignment is assumed.
* @param size Which access size to use, in bytes. 1, 2 or 4.
* @param count The number of reads to do (in size units, not bytes).
* @param address Address to be read; it must be readable by the currently selected MEM-AP.
* @param adr Address to be read; it must be readable by the currently selected MEM-AP.
* @param addrinc Whether the target address should be increased after each read or not. This
* should normally be true, except when reading from e.g. a FIFO.
* @return ERROR_OK on success, otherwise an error code.

View File

@ -1410,27 +1410,21 @@ static int dsp5680xx_write_32(struct target *t, uint32_t a, uint32_t c,
* P: (program) memory or X: (dat) memory.
*
* @param target
* @param address
* @param a address
* @param size Bytes (1), Half words (2), Words (4).
* @param count In bytes.
* @param buffer
* @param b buffer
*
* @return
*/
static int dsp5680xx_write(struct target *t, target_addr_t a, uint32_t s, uint32_t c,
static int dsp5680xx_write(struct target *target, target_addr_t a, uint32_t size, uint32_t count,
const uint8_t *b)
{
/* TODO Cannot write 32bit to odd address, will write 0x12345678 as 0x5678 0x0012 */
struct target *target = t;
uint32_t address = a;
uint32_t count = c;
uint8_t const *buffer = b;
uint32_t size = s;
check_halt_and_debug(target);
int retval = 0;
@ -1479,12 +1473,12 @@ static int dsp5680xx_write_buffer(struct target *t, target_addr_t a, uint32_t si
*
* @return
*/
static int dsp5680xx_read_buffer(struct target *t, target_addr_t a, uint32_t size,
uint8_t *buf)
static int dsp5680xx_read_buffer(struct target *target, target_addr_t address, uint32_t size,
uint8_t *buffer)
{
check_halt_and_debug(t);
check_halt_and_debug(target);
/* The "/2" solves the byte/word addressing issue.*/
return dsp5680xx_read(t, a, 2, size / 2, buf);
return dsp5680xx_read(target, address, 2, size / 2, buffer);
}
/**
@ -1499,19 +1493,19 @@ static int dsp5680xx_read_buffer(struct target *t, target_addr_t a, uint32_t siz
*
* @return
*/
static int dsp5680xx_checksum_memory(struct target *t, target_addr_t a, uint32_t s,
static int dsp5680xx_checksum_memory(struct target *target, target_addr_t address, uint32_t size,
uint32_t *checksum)
{
return ERROR_FAIL;
}
/**
* Calculates a signature over @a word_count words in the data from @a buff16.
* Calculates a signature over @a word_count words in the data from @a buff8.
* The algorithm used is the same the FM uses, so the @a return may be used to compare
* with the one generated by the FM module, and check if flashing was successful.
* This algorithm is based on the perl script available from the Freescale website at FAQ 25630.
*
* @param buff16
* @param buff8
* @param word_count
*
* @return
@ -1609,7 +1603,7 @@ int dsp5680xx_f_protect_check(struct target *target, uint16_t *protected)
* Some commands use the parameters @a address and @a data, others ignore them.
*
* @param target
* @param command Command to execute.
* @param c Command to execute.
* @param address Command parameter.
* @param data Command parameter.
* @param hfm_ustat FM status register.
@ -1617,21 +1611,10 @@ int dsp5680xx_f_protect_check(struct target *target, uint16_t *protected)
*
* @return
*/
static int dsp5680xx_f_ex(struct target *t, uint16_t c, uint32_t a, uint32_t d,
uint16_t *h, int p)
static int dsp5680xx_f_ex(struct target *target, uint16_t c, uint32_t address, uint32_t data,
uint16_t *hfm_ustat, int pmem)
{
struct target *target = t;
uint32_t command = c;
uint32_t address = a;
uint32_t data = d;
uint16_t *hfm_ustat = h;
int pmem = p;
int retval;
retval = core_load_TX_RX_high_addr_to_r0(target);
@ -1799,13 +1782,9 @@ static int set_fm_ck_div(struct target *target)
*
* @return
*/
static int dsp5680xx_f_signature(struct target *t, uint32_t a, uint32_t words,
static int dsp5680xx_f_signature(struct target *target, uint32_t address, uint32_t words,
uint16_t *signature)
{
struct target *target = t;
uint32_t address = a;
int retval;
uint16_t hfm_ustat;

View File

@ -547,13 +547,15 @@ static dmi_status_t dmi_scan(struct target *target, uint32_t *address_in,
}
/**
* @param target
* @param data_in The data we received from the target.
* @param dmi_op The operation to perform (read/write/nop).
* @param dmi_busy_encountered
* If non-NULL, will be updated to reflect whether DMI busy was
* encountered while executing this operation or not.
* @param dmi_op The operation to perform (read/write/nop).
* @param address The address argument to that operation.
* @param data_out The data to send to the target.
* @param timeout_sec
* @param exec When true, this scan will execute something, so extra RTI
* cycles may be added.
* @param ensure_success

View File

@ -89,6 +89,8 @@ extern int gdb_actual_connections;
* Initialize common semihosting support.
*
* @param target Pointer to the target to initialize.
* @param setup
* @param post_result
* @return An error status if there is a problem during initialization.
*/
int semihosting_common_init(struct target *target, void *setup,

View File

@ -803,6 +803,13 @@ static int target_soft_reset_halt(struct target *target)
* algorithm.
*
* @param target used to run the algorithm
* @param num_mem_params
* @param mem_params
* @param num_reg_params
* @param reg_param
* @param entry_point
* @param exit_point
* @param timeout_ms
* @param arch_info target-specific description of the algorithm.
*/
int target_run_algorithm(struct target *target,
@ -838,6 +845,12 @@ done:
* Executes a target-specific native code algorithm and leaves it running.
*
* @param target used to run the algorithm
* @param num_mem_params
* @param mem_params
* @param num_reg_params
* @param reg_params
* @param entry_point
* @param exit_point
* @param arch_info target-specific description of the algorithm.
*/
int target_start_algorithm(struct target *target,
@ -876,6 +889,12 @@ done:
* Waits for an algorithm started with target_start_algorithm() to complete.
*
* @param target used to run the algorithm
* @param num_mem_params
* @param mem_params
* @param num_reg_params
* @param reg_params
* @param exit_point
* @param timeout_ms
* @param arch_info target-specific description of the algorithm.
*/
int target_wait_algorithm(struct target *target,
@ -947,6 +966,7 @@ done:
* @param entry_point address on the target to execute to start the algorithm
* @param exit_point address at which to set a breakpoint to catch the
* end of the algorithm; can be 0 if target triggers a breakpoint itself
* @param arch_info
*/
int target_run_flash_async_algorithm(struct target *target,