From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 28661 invoked by alias); 8 Mar 2010 22:18:34 -0000 Received: (qmail 28651 invoked by uid 22791); 8 Mar 2010 22:18:32 -0000 X-SWARE-Spam-Status: No, hits=-8.4 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_HI,SPF_HELO_PASS X-Spam-Check-By: sourceware.org Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Mon, 08 Mar 2010 22:18:26 +0000 Received: from int-mx01.intmail.prod.int.phx2.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by mx1.redhat.com (8.13.8/8.13.8) with ESMTP id o28MIOHF029875 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Mon, 8 Mar 2010 17:18:24 -0500 Received: from localhost.localdomain (ovpn01.gateway.prod.ext.phx2.redhat.com [10.5.9.1]) by int-mx01.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id o28MINoI029602 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES128-SHA bits=128 verify=NO) for ; Mon, 8 Mar 2010 17:18:24 -0500 Date: Mon, 08 Mar 2010 22:18:00 -0000 From: Kevin Buettner To: gdb-patches@sourceware.org Subject: [RFC] remote-mips.c: Make sure that each function has an introductory comment Message-ID: <20100308151822.2adfab51@redhat.com> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2010-03/txt/msg00342.txt.bz2 After Joel noticed that a couple of functions in one of my recent patch submissions for remote-mips.c were missing comments, I noticed that there were more than a few functions in remote-mips.c that are missing introductory comments. Many of the new comments in the patch below describe "obvious" functions, but some of them weren't so obvious. Since there were a few non-obvious ones, I decided to ask for comments prior to committing. So... Comments? Kevin * remote-mips.c (close_ports, mips_initialize_cleanups) (mips_exit_cleanups, mips_send_command, mips_open, pmon_open) (ddb_open, lsi_open, mips_remove_breakpoint, mips_remove_watchpoint) (mips_stopped_by_watchpoint, send_srec, pmon_checkset) (pmon_make_fastrec, pmon_check_ack, mips_expect_download) (pmon_check_entry_address, pmon_check_total, pmon_end_download) (pmon_download, pmon_load_fast, _initialize_remote_mips): Add comments describing each of these functions. (mips_enter_debug, mips_exit_debug, common_open) (mips_signal_from_protocol, pmon_makeb64, pmon_zeroset): Add blank line after the comment describing the function. Index: remote-mips.c =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D RCS file: /cvs/src/src/gdb/remote-mips.c,v retrieving revision 1.111 diff -u -p -r1.111 remote-mips.c --- remote-mips.c 8 Mar 2010 19:06:34 -0000 1.111 +++ remote-mips.c 8 Mar 2010 21:55:00 -0000 @@ -451,6 +451,9 @@ static int monitor_warnings; inferior_ptid. */ static ptid_t remote_mips_ptid; =20 +/* Close any ports which might be open. Reset certain globals indicating + the state of those ports. */ + static void close_ports (void) { @@ -1290,18 +1293,25 @@ mips_request (int cmd, return rresponse; } =20 +/* Cleanup associated with mips_initialize(). */ + static void mips_initialize_cleanups (void *arg) { mips_initializing =3D 0; } =20 +/* Cleanup associated with mips_exit_debug(). */ + static void mips_exit_cleanups (void *arg) { mips_exiting =3D 0; } =20 +/* Send a command and wait for that command to be echoed back. Wait, + too, for the following prompt. */ + static void mips_send_command (const char *cmd, int prompt) { @@ -1313,6 +1323,7 @@ mips_send_command (const char *cmd, int=20 } =20 /* Enter remote (dbx) debug mode: */ + static void mips_enter_debug (void) { @@ -1343,6 +1354,7 @@ mips_enter_debug (void) } =20 /* Exit remote (dbx) debug mode, returning to the monitor prompt: */ + static int mips_exit_debug (void) { @@ -1505,6 +1517,7 @@ mips_initialize (void) } =20 /* Open a connection to the remote board. */ + static void common_open (struct target_ops *ops, char *name, int from_tty, enum mips_monitor_type new_monitor, @@ -1629,6 +1642,8 @@ device is attached to the target board ( xfree (serial_port_name); } =20 +/* Open a connection to an IDT board. */ + static void mips_open (char *name, int from_tty) { @@ -1652,12 +1667,16 @@ mips_open (char *name, int from_tty) common_open (&mips_ops, name, from_tty, MON_IDT, monitor_prompt); } =20 +/* Open a connection to a PMON board. */ + static void pmon_open (char *name, int from_tty) { common_open (&pmon_ops, name, from_tty, MON_PMON, "PMON> "); } =20 +/* Open a connection to a DDB board. */ + static void ddb_open (char *name, int from_tty) { @@ -1672,6 +1691,8 @@ rockhopper_open (char *name, int from_tt common_open (&rockhopper_ops, name, from_tty, MON_ROCKHOPPER, "NEC01>"); } =20 +/* Open a connection to an LSI board. */ + static void lsi_open (char *name, int from_tty) { @@ -1735,6 +1756,7 @@ mips_resume (struct target_ops *ops, =20 /* Return the signal corresponding to SIG, where SIG is the number which the MIPS protocol uses for the signal. */ + static enum target_signal mips_signal_from_protocol (int sig) { @@ -2324,6 +2346,8 @@ mips_insert_breakpoint (struct gdbarch * return memory_insert_breakpoint (gdbarch, bp_tgt); } =20 +/* Remove a breakpoint. */ + static int mips_remove_breakpoint (struct gdbarch *gdbarch, struct bp_target_info *bp_tgt) @@ -2382,6 +2406,8 @@ mips_insert_watchpoint (CORE_ADDR addr,=20 return 0; } =20 +/* Remove a watchpoint. */ + int mips_remove_watchpoint (CORE_ADDR addr, int len, int type) { @@ -2391,6 +2417,9 @@ mips_remove_watchpoint (CORE_ADDR addr,=20 return 0; } =20 +/* Test to see if a watchpoint has been hit. Return 1 if so; return 0, + if not. */ + int mips_stopped_by_watchpoint (void) { @@ -2685,6 +2714,11 @@ mips_common_breakpoint (%s): Got error: return 0; } =0C +/* Send one S record as specified by SREC of length LEN, starting + at ADDR. Note, however, that ADDR is not used except to provide + a useful message to the user in the event that a NACK is recieved + from the board. */ + static void send_srec (char *srec, int len, CORE_ADDR addr) { @@ -2905,6 +2939,7 @@ static char encoding[] =3D "ABCDEFGHIJKLMN at a time (range 0..63). Keep a checksum if required (passed pointer non-NULL). The function returns the number of encoded characters written into the buffer. */ + static int pmon_makeb64 (unsigned long v, char *p, int n, int *chksum) { @@ -2949,6 +2984,7 @@ pmon_makeb64 (unsigned long v, char *p,=20 =20 /* Shorthand function (that could be in-lined) to output the zero-fill escape sequence into the data stream. */ + static int pmon_zeroset (int recsize, char **buff, int *amount, unsigned int *chksum) { @@ -2961,6 +2997,13 @@ pmon_zeroset (int recsize, char **buff,=20 return (recsize + count + 2); } =20 +/* Add the checksum specified by *VALUE to the buffer, the last location + of which, so far, is specified by *BUF. At the time of this call, + the current size of the buffer is RECSIZE. Return the total size + of the buffer after adding the checksum escape, the checksum itself, + and the trailing newline. As a side effect, the running checksum + specified by *VALUE will be zeroed out prior to returning. */ + static int pmon_checkset (int recsize, char **buff, int *value) { @@ -2991,6 +3034,27 @@ pmon_checkset (int recsize, char **buff, /* NOTE: This constant depends on the monitor being used. This value is for PMON 5.x on the Cogent Vr4300 board. */ =20 +/* Create a FastLoad format record. + + *OUTBUF is the buffer into which the FastLoad formatted data is + written. On return the pointer position represented by *OUTBUF + is updated to point at the end of the data, i.e. the next position + in the buffer that may be written. +=20=20=20 + INBUF is the input data and *INPTR is an index into this buffer. + *INPTR is updated as the input is consumed. Thus, on return, + the caller has access to the position of the next input byte + yet to be processed. INAMOUNT is the size of INBUF. + + *RECSIZE will be written with the total size of the output buffer + prior to returning. + + *CSUM is the output buffer checksum. It is updated as data is + written to the output buffer. +=20=20=20 + *ZEROFILL is the current number of 12-bit zeros that have been + encountered. It is both an input and an output to this function. */ + static void pmon_make_fastrec (char **outbuf, unsigned char *inbuf, int *inptr, int inamount, int *recsize, unsigned int *csum, @@ -3048,6 +3112,10 @@ pmon_make_fastrec (char **outbuf, unsign return; } =20 +/* Attempt to read an ACK. If an ACK is not read in a timely manner, + output the message specified by MESG. Return -1 for failure, 0 + for success. */ + static int pmon_check_ack (char *mesg) { @@ -3090,6 +3158,11 @@ pmon_start_download (void) } } =20 +/* Look for the string specified by STRING sent from the target board + during a download operation. If the string in question is not seen, + output an error message, clean up, and return 0. Otherwise, return + 1 to indicate success. */ + static int mips_expect_download (char *string) { @@ -3104,6 +3177,15 @@ mips_expect_download (char *string) return 1; } =20 +/* Look for messages from the target board associated with the entry + address. + + NOTE: This function doesn't indicate success or failure, so we + have no way to determine whether or not the output from the board + was correctly seen. However, given that other items are checked + after this, it seems unlikely that those checks will pass if this + check doesn't first (silently) pass. */ + static void pmon_check_entry_address (char *entry_address, int final) { @@ -3114,6 +3196,10 @@ pmon_check_entry_address (char *entry_ad mips_expect ("\r\n"); } =20 +/* Look for messages from the target board showing the total number of + bytes downloaded to the board. Output 1 for success if the tail + end of the message was read correctly, 0 otherwise. */ + static int pmon_check_total (int bintotal) { @@ -3124,6 +3210,13 @@ pmon_check_total (int bintotal) return mips_expect_download (" bytes\r\n"); } =20 +/* Look for the termination messages associated with the end of + a download to the board. + + Also, when `tftp_in_use' is set, issue the load command to the + board causing the file to be transferred. (This is done prior + to looking for the above mentioned termination messages.) */ +=20=20=20 static void pmon_end_download (int final, int bintotal) { @@ -3190,6 +3283,10 @@ pmon_end_download (int final, int bintot remove (tftp_localname); /* Remove temporary file */ } =20 +/* Write the buffer specified by BUFFER of length LENGTH to either + the board or the temporary file that'll eventually be transferred + to the board. */ + static void pmon_download (char *buffer, int length) { @@ -3199,6 +3296,9 @@ pmon_download (char *buffer, int length) serial_write (udp_in_use ? udp_desc : mips_desc, buffer, length); } =20 +/* Open object or executable file, FILE, and send it to the board + using the FastLoad format. */ + static void pmon_load_fast (char *file) { @@ -3430,6 +3530,10 @@ pmon_command (char *args, int from_tty) =0C extern initialize_file_ftype _initialize_remote_mips; /* -Wmissing-prototy= pes */ =20 +/* Initialize mips_ops, lsi_ops, ddb_ops, pmon_ops, and rockhopper_ops. + Create target specific commands and perform other initializations + specific to this file. */ + void _initialize_remote_mips (void) {