*** empty log message ***
[binutils-gdb.git] / gdb / remote-mips.c
index b763175bbb6789b2d40b62e8d0eb056a7be6e239..ec2e5eb38b17c29e6093c1a40f18335ca1db93ef 100644 (file)
@@ -451,6 +451,9 @@ static int monitor_warnings;
    inferior_ptid.  */
 static ptid_t remote_mips_ptid;
 
+/* Close any ports which might be open.  Reset certain globals indicating
+   the state of those ports.  */
+
 static void
 close_ports (void)
 {
@@ -470,7 +473,7 @@ close_ports (void)
    all hell to break loose--the rest of GDB will tend to get left in an
    inconsistent state.  */
 
-static NORETURN void
+static void ATTRIBUTE_NORETURN
 mips_error (char *string,...)
 {
   va_list args;
@@ -645,7 +648,7 @@ mips_readchar (int timeout)
   static int state = 0;
   int mips_monitor_prompt_len = strlen (mips_monitor_prompt);
 
-  {
+  { /* FIXME this whole block is dead code! */
     int i;
 
     i = timeout;
@@ -1290,18 +1293,25 @@ mips_request (int cmd,
   return rresponse;
 }
 
+/* Cleanup associated with mips_initialize().  */
+
 static void
 mips_initialize_cleanups (void *arg)
 {
   mips_initializing = 0;
 }
 
+/* Cleanup associated with mips_exit_debug().  */
+
 static void
 mips_exit_cleanups (void *arg)
 {
   mips_exiting = 0;
 }
 
+/* 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 prompt)
 }
 
 /* Enter remote (dbx) debug mode: */
+
 static void
 mips_enter_debug (void)
 {
@@ -1337,12 +1348,14 @@ mips_enter_debug (void)
 
   {
     char buff[DATA_MAXLEN + 1];
+
     if (mips_receive_packet (buff, 1, 3) < 0)
       mips_error ("Failed to initialize (didn't receive packet).");
   }
 }
 
 /* Exit remote (dbx) debug mode, returning to the monitor prompt: */
+
 static int
 mips_exit_debug (void)
 {
@@ -1505,6 +1518,7 @@ mips_initialize (void)
 }
 
 /* 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 +1643,8 @@ device is attached to the target board (e.g., /dev/ttya).\n"
   xfree (serial_port_name);
 }
 
+/* Open a connection to an IDT board.  */
+
 static void
 mips_open (char *name, int from_tty)
 {
@@ -1652,12 +1668,16 @@ mips_open (char *name, int from_tty)
   common_open (&mips_ops, name, from_tty, MON_IDT, monitor_prompt);
 }
 
+/* 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> ");
 }
 
+/* Open a connection to a DDB board.  */
+
 static void
 ddb_open (char *name, int from_tty)
 {
@@ -1672,6 +1692,8 @@ rockhopper_open (char *name, int from_tty)
   common_open (&rockhopper_ops, name, from_tty, MON_ROCKHOPPER, "NEC01>");
 }
 
+/* Open a connection to an LSI board.  */
+
 static void
 lsi_open (char *name, int from_tty)
 {
@@ -1735,6 +1757,7 @@ mips_resume (struct target_ops *ops,
 
 /* 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)
 {
@@ -1992,6 +2015,7 @@ mips_fetch_registers (struct target_ops *ops,
       /* If PMON doesn't support this register, don't waste serial
          bandwidth trying to read it.  */
       int pmon_reg = mips_map_regno (gdbarch, regno);
+
       if (regno != 0 && pmon_reg == 0)
        val = 0;
       else
@@ -2160,6 +2184,7 @@ mips_xfer_memory (CORE_ADDR memaddr, gdb_byte *myaddr, int len, int write,
       for (i = 0; i < count; i++, addr += 4)
        {
          int word;
+
          word = extract_unsigned_integer (&buffer[i * 4], 4, byte_order);
          status = mips_store_word (addr, word, NULL);
          /* Report each kilobyte (we download 32-bit words at a time) */
@@ -2324,6 +2349,8 @@ mips_insert_breakpoint (struct gdbarch *gdbarch,
     return memory_insert_breakpoint (gdbarch, bp_tgt);
 }
 
+/* Remove a breakpoint.  */
+
 static int
 mips_remove_breakpoint (struct gdbarch *gdbarch,
                        struct bp_target_info *bp_tgt)
@@ -2374,7 +2401,8 @@ calculate_mask (CORE_ADDR addr, int len)
    watchpoint. */
 
 int
-mips_insert_watchpoint (CORE_ADDR addr, int len, int type)
+mips_insert_watchpoint (CORE_ADDR addr, int len, int type,
+                       struct expression *cond)
 {
   if (mips_set_breakpoint (addr, len, type))
     return -1;
@@ -2382,8 +2410,11 @@ mips_insert_watchpoint (CORE_ADDR addr, int len, int type)
   return 0;
 }
 
+/* Remove a watchpoint.  */
+
 int
-mips_remove_watchpoint (CORE_ADDR addr, int len, int type)
+mips_remove_watchpoint (CORE_ADDR addr, int len, int type,
+                       struct expression *cond)
 {
   if (mips_clear_breakpoint (addr, len, type))
     return -1;
@@ -2391,6 +2422,9 @@ mips_remove_watchpoint (CORE_ADDR addr, int len, int type)
   return 0;
 }
 
+/* Test to see if a watchpoint has been hit.  Return 1 if so; return 0,
+   if not.  */
+
 int
 mips_stopped_by_watchpoint (void)
 {
@@ -2438,6 +2472,7 @@ mips_check_lsi_error (CORE_ADDR addr, int rerrflg)
       if (monitor_warnings)
        {
          int found = 0;
+
          for (err = lsi_warning_table; err->code != 0; err++)
            {
              if ((err->code & rerrflg) == err->code)
@@ -2628,6 +2663,7 @@ mips_common_breakpoint: Bad response from remote board: %s",
       if (set)                 /* set a breakpoint */
        {
          char *flags;
+
          switch (type)
            {
            case BREAK_WRITE:   /* write */
@@ -2685,6 +2721,11 @@ mips_common_breakpoint (%s):  Got error: 0x%x\n",
   return 0;
 }
 \f
+/* 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 received
+   from the board.  */
+
 static void
 send_srec (char *srec, int len, CORE_ADDR addr)
 {
@@ -2905,6 +2946,7 @@ static char encoding[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz01
    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 +2991,7 @@ pmon_makeb64 (unsigned long v, char *p, int n, int *chksum)
 
 /* 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 +3004,20 @@ pmon_zeroset (int recsize, char **buff, int *amount, unsigned int *chksum)
   return (recsize + count + 2);
 }
 
+/* Add the checksum specified by *VALUE to end of the record under
+   construction.  *BUF specifies the location at which to begin
+   writing characters comprising the checksum information.  RECSIZE
+   specifies the size of the record constructed thus far.  (A trailing
+   NUL character may be present in the buffer holding the record, but
+   the record size does not include this character.)
+
+   Return the total size of the record after adding the checksum escape,
+   the checksum itself, and the trailing newline.
+   
+   The checksum specified by *VALUE is zeroed out prior to returning. 
+   Additionally, *BUF is updated to refer to the location just beyond
+   the record elements added by this call.  */
+
 static int
 pmon_checkset (int recsize, char **buff, int *value)
 {
@@ -2991,6 +3048,32 @@ pmon_checkset (int recsize, char **buff, int *value)
 /* NOTE: This constant depends on the monitor being used. This value
    is for PMON 5.x on the Cogent Vr4300 board. */
 
+/* Create a FastLoad format record.
+
+   *OUTBUF is the buffer into which a FastLoad formatted record 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.  No attempt is made to NUL-
+   terminate this portion of the record written to the buffer.
+   
+   INBUF contains the binary input data from which the FastLoad
+   formatted record will be built.  *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, in bytes, of the
+   input data.
+
+   *RECSIZE will be written with the size of the record written to the
+   output buffer prior to returning.  This size does not include a
+   NUL-termination byte as none is written to the output buffer.
+
+   *CSUM is the output buffer checksum.  It is updated as data is
+   written to the output buffer.
+   
+   *ZEROFILL is the current number of 3-byte zero sequences 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,
@@ -3019,6 +3102,7 @@ pmon_make_fastrec (char **outbuf, unsigned char *inbuf, int *inptr,
       else
        {
          unsigned int value = ((inbuf[*inptr + 0] << 16) | (inbuf[*inptr + 1] << 8) | inbuf[*inptr + 2]);
+
          /* Simple check for zero data. TODO: A better check would be
             to check the last, and then the middle byte for being zero
             (if the first byte is not). We could then check for
@@ -3048,6 +3132,10 @@ pmon_make_fastrec (char **outbuf, unsigned char *inbuf, int *inptr,
   return;
 }
 
+/* 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 +3178,12 @@ pmon_start_download (void)
     }
 }
 
+/* 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, remove the temporary file, if
+   appropriate, and return 0.  Otherwise, return 1 to indicate
+   success.  */
+
 static int
 mips_expect_download (char *string)
 {
@@ -3104,26 +3198,48 @@ mips_expect_download (char *string)
     return 1;
 }
 
+/* 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)
 {
   char hexnumber[9];           /* includes '\0' space */
+
   mips_expect_timeout (entry_address, tftp_in_use ? 15 : remote_timeout);
   sprintf (hexnumber, "%x", final);
   mips_expect (hexnumber);
   mips_expect ("\r\n");
 }
 
+/* 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)
 {
   char hexnumber[9];           /* includes '\0' space */
+
   mips_expect ("\r\ntotal = 0x");
   sprintf (hexnumber, "%x", bintotal);
   mips_expect (hexnumber);
   return mips_expect_download (" bytes\r\n");
 }
 
+/* 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.)  */
+   
 static void
 pmon_end_download (int final, int bintotal)
 {
@@ -3190,6 +3306,10 @@ pmon_end_download (int final, int bintotal)
     remove (tftp_localname);   /* Remove temporary file */
 }
 
+/* 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 +3319,9 @@ pmon_download (char *buffer, int length)
     serial_write (udp_in_use ? udp_desc : mips_desc, buffer, length);
 }
 
+/* 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 +3553,10 @@ pmon_command (char *args, int from_tty)
 \f
 extern initialize_file_ftype _initialize_remote_mips; /* -Wmissing-prototypes */
 
+/* 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)
 {