TEXT   104

gdb.txt

Guest on 4th September 2021 03:15:11 PM

  1. Embecosm logo    Services - tools - models - for embedded software development
  2. Embecosm divider strip
  3. Howto: GDB Remote Serial Protocol
  4. Writing a RSP Server
  5.  
  6. Jeremy Bennett
  7. Embecosm
  8.  
  9. Application Note 4. Issue 2
  10. November
  11.  
  12. Copyright © Embecosm Limited
  13. Creative Commons License    The document entitled " Howto: GDB Remote Serial Protocol " by Jeremy Bennett of Embecosm is licensed under a Creative Commons Attribution 2.0 UK: England & Wales License. See the Legal Notice for details.
  14. Table of Contents
  15.  
  16. 1. Introduction
  17. 1.1. Rationale
  18. 1.2. Target Audience
  19. 1.3. Further Sources of Information
  20. 1.3.1. Written Documentation
  21. 1.3.2. Other Information Channels
  22. 1.4. About Embecosm
  23. 2. Overview of the Remote Serial Protocol
  24. 2.1. Client-Server Relationship
  25. 2.2. Session Layer: The Serial Connection
  26. 2.3. Presentation Layer: Packet Transfer
  27. 2.3.1. Packet Acknowledgment
  28. 2.3.2. Interrupt
  29. 2.4. Application Layer: Remote Serial Protocol
  30. 2.5. Putting it All Together to Build a Server
  31. 2.5.1. Using gdbserver
  32. 2.5.2. Implementing Server Code on the Target
  33. 2.5.3. Implementing Server Code for Simulators
  34. 2.5.4. Implementing a Custom Server for JTAG
  35. 3. Mapping GDB Commands to RSP
  36. 3.1. Remote Debugging in GDB
  37. 3.1.1. Standard Remote Debugging
  38. 3.1.2. Extended Remote Debugging
  39. 3.1.3. Asynchronous Remote Debugging
  40. 3.2. GDB Standard Remote Command Dialogs
  41. 3.2.1. The target remote Command
  42. 3.2.2. The load Command
  43. 3.2.3. Examining Registers
  44. 3.2.4. Examining Memory
  45. 3.2.5. The stepi Command
  46. 3.2.6. The step Command
  47. 3.2.7. The cont Command
  48. 3.2.8. The break Command
  49. 3.2.9. The watch Command
  50. 3.2.10. The detach and disconnect Commands
  51. 3.3. GDB Extended Remote Command Dialogs
  52. 3.3.1. The target extended-remote Command
  53. 3.4. GDB Asynchronous Remote Command Dialogs
  54. 4. RSP Server Implementation Example
  55. 4.1. The OpenRISC 1000 Architectural Simulator, Or1ksim
  56. 4.1.1. The OpenRISC 1000 Architecture
  57. 4.1.2. The OpenRISC 1000 Debug Unit
  58. 4.1.3. The OpenRISC 1000 JTAG Interface
  59. 4.1.4. Application Binary Interface (ABI)
  60. 4.1.5. Or1ksim: the OpenRISC 1000 Architectural Simulator
  61. 4.2. OpenRISC 1000 GDB Architectural Specification
  62. 4.3. Overview of the RSP Server Implementation
  63. 4.3.1. External Code Interface
  64. 4.3.2. Global Data Structures
  65. 4.3.3. Top Level Behavior
  66. 4.4. The Serial Connection
  67. 4.4.1. Establishing the Server Listener Socket
  68. 4.4.2. Establishing the Client Connection
  69. 4.4.3. Communicating with the Client
  70. 4.5. The Packet Interface
  71. 4.5.1. Packet Representation
  72. 4.5.2. Getting Packets
  73. 4.5.3. Sending Packets
  74. 4.6. Convenience Functions
  75. 4.6.1. Convenience String Packet Output
  76. 4.6.2. Conversion Between Binary and Hexadecimal Characters
  77. 4.6.3. Conversion Between Binary and Hexadecimal Character Registers
  78. 4.6.4. Data "Unescaping"
  79. 4.6.5. Setting the Program Counter
  80. 4.7. High Level Protocol Implementation
  81. 4.7.1. Deprecated Packets
  82. 4.7.2. Unsupported Packets
  83. 4.7.3. Simple Packets
  84. 4.7.4. Reporting the Last Exception
  85. 4.7.5. Continuing
  86. 4.7.6. Reading and Writing All Registers
  87. 4.7.7. Reading and Writing Memory
  88. 4.7.8. Reading and Writing Individual Registers
  89. 4.7.9. Query Packets
  90. 4.7.10. Set Packets
  91. 4.7.11. Restart the Target
  92. 4.7.12. Stepping
  93. 4.7.13. v Packets
  94. 4.7.14. Binary Data Transfer
  95. 4.7.15. Matchpoint Handling
  96. 5. Summary
  97. Glossary
  98. References
  99. Index
  100. Chapter 1.  Introduction
  101. This document complements the existing documentation for GDB ([3], [4]). It is intended to help software engineers implementing a server for the GDB Remote Serial Protocol (RSP) for the first time.
  102.  
  103. This application note is based on the author's experience to date. It will be updated in future issues. Suggestions for improvements are always welcome.
  104.  
  105. 1.1.  Rationale
  106. The GDB User Guide [3] documents the Remote Serial Protocol (RSP) for communicating with remote targets. The target must act as a server for the RSP, and the source distribution includes stub implementations for architectures such as the Motorola 680xx and Sun SPARC. The User Guide offers advice on how these stubs can be modified and integrated for new targets.
  107.  
  108. However the examples have not been changed for several years, and the advice on using the stubs is now out of date. The documentation also lacks any explanation of the dynamics of the protocol—the sequence of commands/responses used to effect the various GDB commands.
  109.  
  110. This document aims to fill that gap, by explaining how the RSP works today and how it can be used to write a server for a target to be debugged with GDB.
  111.  
  112. Throughout, examples are provided from the author's experience implementing a RSP server for the OpenRISC 1000 architecture. This document captures the learning experience, with the intention of helping others.
  113.  
  114. 1.2.  Target Audience
  115. If you are about to start a port of GDB to a new architecture, this document is for you. If at the end of your endeavors you are better informed, please help by adding to this document.
  116.  
  117. If you have already been through the porting process, please help others by adding to this document.
  118.  
  119. 1.3.  Further Sources of Information
  120. 1.3.1.  Written Documentation
  121. The main user guide for GDB [3] explains how remote debugging works and provides the reference for the various RSP packets.
  122.  
  123. The main GDB code base is generally well commented, particularly in the headers for the major interfaces. Inevitably this must be the definitive place to find out exactly how a particular function behaves. In particular the source code for the RSP client side in gdb/remote.c provides the definitive guide on the expected dynamics of the protocol.
  124.  
  125. The files making up the RSP server for the OpenRISC 1000 are comprehensively commented, and can be processed with Doxygen [5]. Each function's behavior, its parameters and any return value is described.
  126.  
  127. This application note complements the Embecosm Application Note 3, "HOWTO: Porting the GNU Debugger" [2]. Details of the OpenRISC 1000 can be found in its Architecture Manual [6]. The OpenRISC 1000 architectural simulator and tool chain is documented in Embecosm Application Note 2 [1].
  128.  
  129. 1.3.2.  Other Information Channels
  130. The main GDB website is at sourceware.org/gdb/. It is supplemented by the less formal GDB Wiki at sourceware.org/gdb/wiki/.
  131.  
  132. The GDB developer community communicate through the GDB mailing lists and using IRC chat. These are always good places to find solutions to problems.
  133.  
  134. IRC is channel #gdb on irc.freenode.net.
  135.  
  136. The main mailing list for discussion is gdb@sourceware.org, although for detailed insight, take a look at the patches mailing list, gdb-patches@sourceware.org. See the main GDB website for details of subscribing to these mailing lists.
  137.  
  138. 1.4.  About Embecosm
  139. Embecosm is a consultancy specializing in open source tools, models and training for the embedded software community. All Embecosm products are freely available under open source licenses.
  140.  
  141. Embecosm offers a range of commercial services.
  142.  
  143. Customization of open source tools and software, including porting to new architectures.
  144.  
  145. Support, tutorials and training for open source tools and software.
  146.  
  147. Custom software development for the embedded market, including bespoke software models of hardware.
  148.  
  149. Independent evaluation of software tools.
  150.  
  151. For further information, visit the Embecosm website at www.embecosm.com.
  152.  
  153. Chapter 2.  Overview of the Remote Serial Protocol
  154. The GDB Remote Serial Protocol (RSP) provides a high level protocol allowing GDB to connect to any target remotely. If a target's architecture is defined in GDB and the target implements the server side of the RSP protocol, then the debugger will be able to connect remotely to that target.
  155.  
  156. The protocol supports a wide range of connection types: direct serial devices, UDP/IP, TCP/IP and POSIX pipes. Historically RSP has only required 7-bit clean connections. However more recent commands added to the protocol assume an 8-bit clean connection. It is also worth noting, that although UDP/IP is supported, lost packets with unreliable transport methods such as this may lead to GDB reporting errors.
  157.  
  158. RSP is most commonly of value in embedded environments, where it is not possible to run GDB natively on the target.
  159.  
  160. The protocol is layered, approximately following the OSI model as shown in Figure 2.1.
  161.  
  162. OSI Layers in the Remote Serial Protocol
  163. Figure 2.1.  OSI Layers in the Remote Serial Protocol
  164.  
  165.  
  166. 2.1.  Client-Server Relationship
  167. The GDB program acts as the RSP client with the target acting as the RSP server. The client issues packets which are requests for information or action. Depending on the nature of the client packet, the server may respond with a packet of its own.
  168.  
  169. This is the only circumstance under which the server sends a packet: in reply to a packet from the client requiring a response.
  170.  
  171. 2.2.  Session Layer: The Serial Connection
  172. The serial connection is established in response to a target remote or target extended-remote command from the GDB client. The way the server handles this depends on the nature of the serial connection:
  173.  
  174. Connection via a serial device. The target should be listening for connections on the device. This may either be via routine polling or via an event driven interface. Once the connection is established, packets are read from and written to the device.
  175.  
  176. Connection via TCP/IP or UDP/IP. The target should be listening on a socket connected to the specified port. This may either be via routine polling or via an event driven interface. Accepting a new connection (the POSIX accept () function) will yield a file descriptor, which can be used for reading and writing packets.
  177.  
  178. Connection via a pipe. The target will be created, with standard input and output as the file descriptors for packet reading and writing.
  179.  
  180. In each case there is no specific requirement that the target be either running or stopped. GDB will establish via RSP commands the state of the target once the connection is established.
  181.  
  182. GDB is almost entirely non-preemptive, which is reflected in the sequence of packet exchanges of RSP. The exception is when GDB wishes to interrupt an executing program (typically via ctrl-C). A single byte, 0x03, is sent (no packet structure). If the target is prepared to handle such interrupts it should recognize such bytes. Unless the target is routinely polling for input (which may be the case for simulators), a prompt response typically will require an event driven reader for the connection.
  183.  
  184. 2.3.  Presentation Layer: Packet Transfer
  185. The basic format of a RSP packet is shown in Figure 2.2.
  186.  
  187. RSP Packet Format
  188. Figure 2.2.  RSP Packet Format
  189.  
  190.  
  191. For almost all packets, binary data is represented as two hexadecimal digits per byte of data. The checksum is the unsigned sum of all the characters in the packet data modulo 256. It is represented as a pair of hexadecimal digits.
  192.  
  193. Where the characters '#' or '$' appear in the packet data, they must be escaped. The escape character is ASCII 0x7d ('}'), and is followed by the original character XORed with 0x20. The character '}' itself must also be escaped.
  194.  
  195. The small number of packets which transmit data as raw binary (thus requiring an 8-bit clean connection) must also escape the characters '#', '$' and '}' if they occur in the binary data.
  196.  
  197. Reply packets sent by the server may use run-length encoding. The format is to follow the character being repeated by '*' and then the character whose ASCII code is 28 greater than the total repeat, so long as it remains a printable ASCII character (i.e. not greater than 126). Thus the string "XXXXX" would be represented as "X*!" ('!' is ASCII 33).
  198.  
  199. This feature is suitable for run-lengths of 4, 5 and 8-97. Run lengths of 6 and 7 cannot be used, since the repeat characters would be '#' and '$' and interfere with the recognition of the packet itself before decoding. For these cases, a run length of 5 is used, followed by 1 or 2 instances of the repeated character as required. '*' and '}' cause no problem, since they are part of decoding, and their use in a run-length would be recognized as such.
  200.  
  201. [Note]  Note
  202. There is no requirement for a server to use run length encoding.
  203.  
  204. 2.3.1.  Packet Acknowledgment
  205. Each packet should be acknowledged with a single character. '+' to indicate satisfactory receipt, with valid checksum or '-' to indicate failure and request retransmission.
  206.  
  207. Retransmission should be requested until a satisfactory packet is received.
  208.  
  209. 2.3.2.  Interrupt
  210. The GDB client may wish to interrupt the server (e.g. when the user has pressed ctrl-C). This is indicated by transmitting the character 0x03 between packets.
  211.  
  212. If the server wishes to handle such interrupts, it should recognize such characters and process as appropriate. However not all servers are capable of handling such requests. The server is free to ignore such out-of-band characters.
  213.  
  214. 2.4.  Application Layer: Remote Serial Protocol
  215. RSP commands from the client to the server are textual strings, optionally followed by arguments. Each command is sent in its own packet. The packets fall into four groups:
  216.  
  217. Packets requiring no acknowledgment. These commands are: f, i, I, k, R, t and vFlashDone.
  218.  
  219. Packets requiring a simple acknowledgment packet. The acknowledgment is either OK, Enn (where nn is an error number) or for some commands an empty packet (meaning "unsupported"). These commands are: !, A, D, G, H, M, P, Qxxxx, T, vFlashErase, vFlashWrite, X, z and Z.
  220.  
  221. Packets that return result data or an error code.. These commands are: ?, c, C, g, m, p, qxxxx, s, S and most vxxxx.
  222.  
  223. Deprecated packets which should no longer be used. These commands are b, B, d and r.
  224.  
  225. This application note does not document all these commands, except where clarification is needed, since thy are all documented in Appendix D of the main GDB user guide ([3]).
  226.  
  227. [Tip]   Tip
  228. Many commands come in pairs: for example g and G. In general the lower case is used for the command to read or delete data, or the command in its simpler form. The upper case is used to write or install data, or for a more complex form of the command.
  229.  
  230. The RSP was developed over several years, and represents an evolved standard, but one which had to keep backward compatibility. As a consequence the detailed syntax can be inconsistent. For example most commands are separated from their arguments by ':', but some use ',' for this purpose.
  231.  
  232. 2.5.  Putting it All Together to Build a Server
  233. There are three approaches to adding a RSP server to a target.
  234.  
  235. Run the gdbserver program on the target. A variant of this uses a custom server program to drive a physical interface to real hardware. This is most commonly seen with programs, running on the host, which drive a JTAG link connected via a parallel port or USB.
  236.  
  237. Implement code on the target to establish a connection, recognize the packets and implement the behavior.
  238.  
  239. For simulators, add code to the simulator to establish a connection, recognize the packets and implement the behavior in the simulator.
  240.  
  241. When remote debugging, GDB assumes that the target server will terminate the connection if the target program exits. However there is a variant, invoked by target extended-remote, which makes the server persistent, allowing the user to restart a program, or run an alternative program. This is discussed in more detail later (see Section 3.1.2).
  242.  
  243. In general GDB assumes that when it connects to a target via RSP, that target will be stopped. However there are new features in GDB allowing it to work asynchronously while some or all threads in the target continue executing. This is discussed in more detail later (see Section 3.1.3).
  244.  
  245. 2.5.1.  Using gdbserver
  246. The gdbserver command is well documented in the GDB User Guide [3]. This approach is suitable for powerful targets, where it is easy to invoke a program from the command line.
  247.  
  248. Generally this approach is not suitable for embedded systems.
  249.  
  250. 2.5.2.  Implementing Server Code on the Target
  251. This is the usual approach for embedded systems, and is the strategy encapsulated in the server stubs supplied with the GDB source code.
  252.  
  253. There are two key components of the code:
  254.  
  255. Code to establish the serial connection with the client GDB session.
  256.  
  257. Code for the target's interrupt handlers, so all exceptions are routed through the RSP server.
  258.  
  259. In the stub code, the user must implement the serial connection by supplying functions getDebugChar () and putDebugChar (). The user must supply the function exceptionHandler () to set up exception handling.
  260.  
  261. The serial connection is usually established on the first call to getDebugChar (). This is standard POSIX code to access either the serial device, or to listen for a TCP/IP or UDP/IP connection. The target may choose to block here, if it does not wish to run without control from a GDB client.
  262.  
  263. If the serial connection chooses not to block on getDebugChar () then the exception handler should be prepared for this response, allowing the exception to be processed as normal.
  264.  
  265. [Note]  Note
  266. The stub RSP server code supplied with the GDB source distribution assumes getDebugChar () blocks until the connection is established.
  267.  
  268. In general the server interacts with the client only when it has received control due to a target exception.
  269.  
  270. At start up, the first time this occurs, the target will be waiting for the GDB client to send a packet to which it can respond. These dialogs will continue until the client GDB session wishes to continue or step the target (c, C, i, I, s or S packet).
  271.  
  272. Thereafter control is received only when another exception has occurred, following a continue or step. In this case, the first action of the target RSP server should be to send the reply packet back to the client GDB session.
  273.  
  274. [Caution]   Caution
  275. The key limitation in the stub RSP server code supplied with the GDB source distribution is that it only deals with the second case. In other words, it always sends a reply packet to the client, even on first execution.
  276.  
  277. This causes two problems. First, the putDebugChar () is called before getDebugChar (), so it must be able to establish the connection.
  278.  
  279. Secondly, the initial reply is sent without a request packet from the client GDB session. As a result this reply will typically be queued and appear as the reply to the first request packet from GDB. The client interface is quite robust and usually quietly rejects unexpected packets, but there is potential for client requests and server responses to get out of step. It certainly does not represent good program design.
  280.  
  281. The final issue that server code needs to address is the issue of BREAK signaling from the client. This is a raw 0x03 byte sent from the client between packets. Typically this is in response to a ctrl-C from the client GDB session.
  282.  
  283. If the target server wishes to handle such signaling, it must provide an event driven getDebugChar (), triggered when data is received, which can act on such BREAK signals.
  284.  
  285. 2.5.3.  Implementing Server Code for Simulators
  286. Simulators are commonly integrated separately into GDB, and accessed using the target sim command.
  287.  
  288. However it can also be useful to connect to them by using the RSP. This allows the GDB experience to be identical whether simulator or real silicon is used.
  289.  
  290. The general approach is the same as that for implementing code on a target (see Section 2.5.2). However the code forms part of the simulator, not the target. The RSP handler will be attached to the simulators handling of events, rather than the events themselves.
  291.  
  292. In general the simulator will use the same form of connection as when debugging real silicon. Where the RSP server for real silicon is implemented on the target, or gdbserver is used, connection via a serial device, TCP/IP or UDP/IP is appropriate. Where the RSP interface for real silicon is via a pipe to a program driving JTAG a pipe interface should be used to launch the simulator.
  293.  
  294. The example used in Chapter 4 is based on a simulator for the OpenRISC 1000.
  295.  
  296. 2.5.4.  Implementing a Custom Server for JTAG
  297. Many embedded systems will offer JTAG ports for debugging. Most commonly these are connected to a host workstation running GDB via the parallel port or USB.
  298.  
  299. In the past users would implement a custom target interface in GDB to drive the JTAG interface directly. However with RSP it makes more sense to write a RSP server program, which runs standalone on the host. This program maps RSP commands and responses to the underlying JTAG interface.
  300.  
  301. Logically this is rather like a custom gdbserver, although it runs on the host rather than the target. The implementation techniques are similar to those required for interfacing to a simulator.
  302.  
  303. This is one situation, where using the pipe interface is sensible. The pipe interface is used to launch the program which will talk to the JTAG interface. If this approach is used, then debugging via a simulator should also use a pipe interface to launch the simulator, thus allowing the debugging experience to be the same whether real silicon or a simulator is used.
  304.  
  305. Chapter 3.  Mapping GDB Commands to RSP
  306. 3.1.  Remote Debugging in GDB
  307. GDB provides two flavors of remote debugging via the RSP
  308.  
  309. target remote. This is the GDB command documented in the GDB User Guide ([3]).
  310.  
  311. target extended-remote. The RSP server is made persistent. When the target exits, the server does not close the connection. The user is able to restart the target program, or load and run an alternative program.
  312.  
  313. 3.1.1.  Standard Remote Debugging
  314. A RSP server supporting standard remote debugging (i.e. using the GDB target remote command) should implement at least the following RSP packets:
  315.  
  316. ?. Report why the target halted.
  317.  
  318. c, C, s and S. Continue or step the target (possibly with a particular signal). A minimal implementation may not support stepping or continuing with a signal.
  319.  
  320. D. Detach from the client.
  321.  
  322. g and G. Read or write general registers.
  323.  
  324. qC and H. Report the current thread or set the thread for subsequent operations. The significance of this will depend on whether the target supports threads.
  325.  
  326. k. Kill the target. The semantics of this are not clearly defined. Most targets should probably ignore it.
  327.  
  328. m and M. Read or write main memory.
  329.  
  330. p and P. Read or write a specific register.
  331.  
  332. qOffsets. Report the offsets to use when relocating downloaded code.
  333.  
  334. qSupported. Report the features supported by the RSP server. As a minimum, just the packet size can be reported.
  335.  
  336. qSymbol:: (i.e. the qSymbol packet with no arguments). Request any symbol table data. A minimal implementation should request no data.
  337.  
  338. vCont?. Report what vCont actions are supported. A minimal implementation should return an empty packet to indicate no actions are supported.
  339.  
  340. X. Load binary data.
  341.  
  342. z and Z. Clear or set breakpoints or watchpoints.
  343.  
  344. 3.1.2.  Extended Remote Debugging
  345. A RSP server supporting standard remote debugging (i.e. using the GDB target remote command) should implement at least the following RSP packets in addition to those required for standard remote debugging:
  346.  
  347. !. Advise the target that extended remote debugging is being used.
  348.  
  349. R. Restart the program being run.
  350.  
  351. vAttach. Attach to a new process with a specified process ID. This packet need not be implemented if the target has no concept of a process ID, but should return an error code.
  352.  
  353. vRun. Specify a new program and arguments to run. A minimal implementation may restrict this to the case where only the current program may be run again.
  354.  
  355. 3.1.3.  Asynchronous Remote Debugging
  356. The most recent versions of GDB have started to introduce the concept of asynchronous debugging. This is primarily for use with targets capable of "non-stop" execution. Such targets are able to stop the execution of a single thread in a multithreaded environment, allowing it to be debugged while others continue to execute.
  357.  
  358. This still represents technology under development. In GDB 6.8, the commands target async and target extended-async were provided to specify remote debugging of a non-stop target in asynchronous fashion.
  359.  
  360. The mechanism will change in the future, with GDB flags set to specify asynchronous interpretation of commands, which are otherwise unchanged. Readers particularly interested in this area should look at the current development version of GDB and the discussions in the various GDB newsgroups.
  361.  
  362. Asynchronous debugging requires that the target support packets specifying execution of particular threads. The most significant of these are:
  363.  
  364. H. To specify which thread a subsequent command should apply to.
  365.  
  366. q (various packets). The query packets related to threads, qC, qfThreadInfo, qsThreadInfo, qGetTLSAddr and qThreadExtraInfo will need to be implemented.
  367.  
  368. T. To report if a particular thread is alive.
  369.  
  370. vCont. To specify step or continue actions specific to one or more threads.
  371.  
  372. In addition, non-stop targets should also support the T response to continue or step commands, so that status of individual threads can be reported.
  373.  
  374. 3.2.  GDB Standard Remote Command Dialogs
  375. The following sections show diagrammatically how various GDB commands map onto RSP packet exchanges. These implement the desired behavior with standard remote debugging (i.e when connecting with target remote).
  376.  
  377. 3.2.1.  The target remote Command
  378. The RSP packet exchanges to implement the GDB target remote command are shown as a sequence diagram in Figure 3.1.
  379.  
  380. RSP packet exchanges for the GDB target remote command
  381. Figure 3.1.  RSP packet exchanges for the GDB target remote command
  382.  
  383.  
  384. This is the initial dialog once the connection has been established. The first thing the client needs to know is what this RSP server supports. The only feature that matters is to report the packet size that is supported. The largest packet that will be needed is to hold a command with the hexadecimal values of all the general registers (for the G packets). In this example, there are a total of 35 32-bit registers, each requiring 8 hex characters + 1 character for the 'G', a total of 281 (hexadecimal 0x119) characters.
  385.  
  386. The client then asks why the target halted. For a standard remote connection (rather than extended remote connection), the target must be running, even if it has halted for a signal. So the client will verify that the reply is not W (exited) or X (terminated with signal). In this case the target reports it has stopped due to a TRAP exception.
  387.  
  388. The next packet is an instruction from the client that any future step or continue commands should apply to all threads. This is followed by a request (qC) for information on the thread currently running. In this example the target is "bare metal", so there is no concept of threads. An empty response is interpreted as "use the existing value", which suits in this case—since it is never set explicitly, it will be the NULL thread ID, which is appropriate.
  389.  
  390. The next packet (qOffsets) requests any offsets for loading binary data. At the minimum this must return offsets for the text, data and BSS sections of an executable—in this example all zero.
  391.  
  392. [Note]  Note
  393. The BSS component must be specified, contrary to the advice in the GDB User Guide.
  394.  
  395. The client then fetches the value of all the registers, so it can populate its register cache. It first specifies that operations such as these apply to all threads (Hg-1 packet), then requests the value of all registers (g packet).
  396.  
  397. Finally the client offers to supply any symbolic data required by the server. In this example, no data is needed, so a reply of "OK" is sent.
  398.  
  399. Through this exchange, the GDB client shows the following output:
  400.  
  401. (gdb) target remote :51000
  402. Remote debugging using :51000
  403. 0x00000100 in _start ()
  404. (gdb)
  405.    
  406. 3.2.2.  The load Command
  407. The RSP packet exchanges to implement the GDB load command are shown as a sequence diagram in Figure 3.2. In this example a program with a text section of 4752 (0x1290) bytes at address 0x0 and data section of 15 (0xe) bytes at address 0x1290 is loaded.
  408.  
  409. RSP packet exchanges for the GDB load command
  410. Figure 3.2.  RSP packet exchanges for the GDB load command
  411.  
  412.  
  413. The first packet is a binary write of zero bytes (X0,0:). A reply of "OK" indicates the target supports binary writing, an empty reply indicates that binary write is not supported, in which case the data will be loaded using M packets.
  414.  
  415. [Note]  Note
  416. This initial dialog is 7-bit clean, even though it uses the X packet. It can therefore safely be used with connections that are not 8-bit clean.
  417.  
  418. [Caution]   Caution
  419. The use of a null reply to indicate that X packet transfers are not supported is not documented in the GDB User Guide.
  420.  
  421. Having established in this case that binary transfers are permitted, each section of the loaded binary is transmitted in blocks of up to 256 binary data bytes.
  422.  
  423. Had binary transfers not been permitted, the sections would have been transferred using M packets, using pairs of hexadecimal digits for each byte.
  424.  
  425. Finally the client sets the value of the program counter to the entry point of the code using a P packet. In this example the program counter is general register 33 and the entry point is address 0x100.
  426.  
  427. Through this exchange, the GDB client shows the following output:
  428.  
  429. (gdb) load hello
  430. Loading section .text, size 0x1290 lma 0x0
  431. Loading section .rodata, size 0xe lma 0x1290
  432. Start address 0x100, load size 4766
  433. Transfer rate: 5 KB/sec, 238 bytes/write.
  434. (gdb)
  435.    
  436. 3.2.3.  Examining Registers
  437. Examining registers in GDB causes no RSP packets to be exchanged. This is because the GDB client always obtains values for all the registers whenever it halts and caches that data. So for example in the following command sequence, there is no RSP traffic.
  438.  
  439. (gdb) print $pc
  440. $1 = (void (*)()) 0x1264 <main+16>
  441. (gdb)
  442.    
  443. 3.2.4.  Examining Memory
  444. All GDB commands which involve examining memory are mapped by the client to a series of m packets. Unlike registers, memory values are not cached by the client, so repeated examination of a memory location will lead to multiple m packets for the same location.
  445.  
  446. The packet exchanges to implement the GDB disassemble command for a simple function are shown as a sequence diagram in Figure 3.3. In this example the simputc () function is disassembled.
  447.  
  448. RSP packet exchanges for the GDB disassemble command
  449. Figure 3.3.  RSP packet exchanges for the GDB disassemble command
  450.  
  451.  
  452. The disassemble command in the GDB client generates a series of RSP m packets, to obtain the instructions required one at a time.
  453.  
  454. Through this exchange, the GDB client shows the following output:
  455.  
  456. (gdb) disas simputc
  457. Dump of assembler code for function simputc:
  458. 0x00001020 <simputc+0>: l.addi   r1,r1,-8
  459. 0x00001024 <simputc+4>: l.sw     0(r1),r2
  460. 0x00001028 <simputc+8>: l.addi   r2,r1,8
  461. 0x0000102c <simputc+12>:        l.sw     -4(r2),r3
  462. 0x00001030 <simputc+16>:        l.nop    4
  463. 0x00001034 <simputc+20>:        l.lwz    r2,0(r1)
  464. 0x00001038 <simputc+24>:        l.jr     r9
  465. 0x0000103c <simputc+28>:        l.addi   r1,r1,8
  466. End of assembler dump.
  467. (gdb)
  468.    
  469. 3.2.5.  The stepi Command
  470. The RSP offers two mechanisms for stepping and continuing programs. The original mechanism has the thread concerned specified with a Hc packet, and then the thread stepped or continued with a s, S, c or C packet.
  471.  
  472. The newer mechanism uses the vCont: packet to specify the command and the thread ID in a single packet. The availability of the vCont: packet is established using the vCont? packet.
  473.  
  474. The simplest GDB execution command is the stepi command to step the target a single machine instruction. The RSP packet exchanges to implement the GDB stepi command are shown as a sequence diagram in Figure 3.4. In this example the instruction at address 0x100 is executed.
  475.  
  476. RSP packet exchanges for the GDB stepi command
  477. Figure 3.4.  RSP packet exchanges for the GDB stepi command
  478.  
  479.  
  480. The first exchange is related to the definition of the architecture used in this example. Before stepping any instruction, GDB needs to know if there is any special behavior due to this instruction occupying a delay slot. This is achieved by calling the gdbarch_single_step_through_delay () function. In this example, that function reads the instruction at the previous program counter (in this case address 0x0) to see if it was an instruction with a delay slot. This is achieved by using the m packet to obtain the 4 bytes of instruction at that address.
  481.  
  482. The next packet, vCont? from the client seeks to establish if the server supports the vCont packet. A null response indicates that it is not.
  483.  
  484. [Note]  Note
  485. The vCont? packet is used only once, and the result cached by the GDB client. Subsequent step or continue commands will not result in this packet being reissued.
  486.  
  487. The client then establishes the thread to be used for the step with the Hc0 packet. The value 0 indicates that any thread may be used by the server.
  488.  
  489. [Note]  Note
  490. Note the difference to the earlier use of the Hc packet (see Section 3.2.1), where a value of -1 was used to mean all threads.
  491.  
  492. [Note]  Note
  493. The GDB client remembers the thread currently in use. It does not issue further Hc packets unless the thread has to change.
  494.  
  495. The actual step is invoked by the s packet. This does not return a result to the GDB client until it has completed. The reply indicates that the server stopped for signal 5 (TRAP exception).
  496.  
  497. [Caution]   Caution
  498. In the RSP, the s packet indicates stepping of a single machine instruction, not a high level statement. In this way it maps to GDB's stepi command, not its step command (which confusingly can be abbreviated to just s).
  499.  
  500. The last two exchanges are a g and m packet. These allow GDB to reload its register cache and note the instruction just executed.
  501.  
  502. Through this exchange, the GDB client shows the following output:
  503.  
  504. (gdb) stepi
  505. 0x00000104 in _start ()
  506. (gdb)
  507.    
  508. 3.2.6.  The step Command
  509. The GDB step command to step the target a single high level instruction is similar to the stepi instruction, and works by using multiple s packets. However additional packet exchanges are also required to provide information to be displayed about the high level data structures, such as the stack.
  510.  
  511. The RSP packet exchanges to implement the GDB step command are shown as a sequence diagram in Figure 3.5. In this example the first instruction of a C main () function is executed.
  512.  
  513. RSP packet exchanges for the GDB step command
  514. Figure 3.5.  RSP packet exchanges for the GDB step command
  515.  
  516.  
  517. The exchanges start similarly to the stepi, although, since this is not the first step, there are no vCont? or Hc packets.
  518.  
  519. The high level language step is mapped by the client GDB session into a series of s packets, after each of which the register cache is refreshed by a g packet.
  520.  
  521. After the step, are a series of reads of data words, using m packets. The first group are from the code. This is the first execution in a new function, and the frame analysis functions of the GDB client are analyzing the function prologue, to establish the location of key values (stack pointer, frame pointer, return address).
  522.  
  523. The second group access the stack frame to obtain information required by GDB. In this example the return address from the current stack frame.
  524.  
  525. Through this exchange, the GDB client shows the following output:
  526.  
  527. (gdb) step
  528. main () at hello.c:41
  529. 41        simputs( "Hello World!\n" );
  530. (gdb)
  531.    
  532. 3.2.7.  The cont Command
  533. The packet exchange for the GDB continue is very similar to that for the step (see Section 3.2.6). The difference is that in the absence of a breakpoint, the target program may complete execution. A simple implementation need not trap the exit—GDB will handle the loss of connection quite cleanly.
  534.  
  535. The RSP packet exchanges to implement the GDB continue command are shown as a sequence diagram in Figure 3.6. In this example the target executes to completion and exits, without returning a reply packet to the GDB client.
  536.  
  537. RSP packet exchanges for the GDB continue command
  538. Figure 3.6.  RSP packet exchanges for the GDB continue command
  539.  
  540.  
  541. The packet exchange is initially the same as that for a GDB step or stepi command (see Figure 3.4).
  542.  
  543. In this example the gdbarch_single_step_through_delay () function finds that the previously executed instruction is a jump instruction (m packet). Since the target may be in a delay slot, it executes a single step (s packet) to step past that slot, followed by notification of the TRAP exception (S05 packet) and register cache reload (g packet).
  544.  
  545. The next call to gdbarch_single_step_through_delay () determines that the previous instruction did not have a delay slot (m packet), so the c packet can be used to resume execution of the target.
  546.  
  547. Since the target exits, there is no reply to the GDB client. However it correctly interprets the loss of connection to the server as target execution. Through this exchange, the GDB client shows the following output:
  548.  
  549. (gdb) continue
  550. Continuing.
  551. Remote connection closed
  552. (gdb)
  553.    
  554. 3.2.8.  The break Command
  555. The GDB command to set breakpoints, break does not immediately cause a RSP interaction. GDB only actually sets breakpoints immediately before execution (for example by a continue or step command) and immediately clears them when a breakpoint is hit. This minimizes the risk of a program being left with breakpoints inserted, for example when a serial link fails.
  556.  
  557. The RSP packet exchanges to implement the GDB break command and a subsequent continue are shown as a sequence diagram in Figure 3.7. In this example a breakpoint is set at the start of the function simputs ().
  558.  
  559. RSP packet exchanges for the GDB break and continue commands
  560. Figure 3.7.  RSP packet exchanges for the GDB break and continue commands
  561.  
  562.  
  563. The command sequence is very similar to that of the plain continue command (see Section 3.2.7). With two key differences.
  564.  
  565. First, immediately before the c packet, the breakpoint is set with a Z0 packet. Secondly, as soon as the register cache has been refreshed (g packet) when control returns, the program counter is stepped back to re-execute the instruction at the location of the TRAP with a P packet and the breakpoint is cleared with a z0 packet. In this case only a single breakpoint (at location 0x1150, the start of function simputs ()) is set. If there were multiple breakpoints, they would all be set immediately before the c packet and cleared immediately after the g packet.
  566.  
  567. In this example, the client ensures that the program counter is set to point to the TRAP instruction just executed, not the instruction following.
  568.  
  569. An alternative to adjusting the program counter in the target is to use the GDB architecture value decr_pc_after_break () value to specify that the program counter should be wound back. In this case an additional P packet would be used to reset the program counter register. Whichever approach is used, it means that when execution resumes, the instruction which was replaced by a trap instruction will be executed first.
  570.  
  571. [Note]  Note
  572. Perhaps rather surprisingly, it is the responsibility of the target RSP server, not the GDB client to keep track of the substituted instructions.
  573.  
  574. Through this exchange, the GDB client shows the following output:
  575.  
  576. (gdb) break simputs
  577. Breakpoint 1 at 0x1150: file utils.c, line 90.
  578. (gdb) c
  579. Continuing.
  580.  
  581. Breakpoint 1, simputs (str=0x1290 "Hello World!\n") at utils.c:90
  582. 90        for( i = 0; str[i] != '\0' ; i++ ) {
  583. (gdb)
  584.    
  585. The example here showed the use of a memory breakpoint (also known as a software breakpoint). GDB also supports use of hardware watchpoints explicitly through the hbreak command. These behave analogously to memory breakpoints in RSP, but using z1 and Z1 packets.
  586.  
  587. If a RSP server implementation does not support hardware breakpoints it should return an empty packet to any request for insertion or deletion.
  588.  
  589. 3.2.9.  The watch Command
  590. If hardware watchpoints are supported (the default assumption in GDB), then the setting and clearing of watchpoints is very similar to breakpoints, but using z2 and Z2 packets (for write watchpoints), z3 and Z3 packets (for read watchpoints) and z4 and Z4 packets (for access watchpoints)
  591.  
  592. GDB also supports software write watchpoints. These are implemented by single stepping the target, and examining the watched value after each step. This is painfully slow when GDB is running native. Under RSP, where each step involves an number of packet exchanges, the performance drops ever further. Software watchpointing should be restricted to the shortest section of code possible.
  593.  
  594. 3.2.10.  The detach and disconnect Commands
  595. The rules for detach mandate that it breaks the connection with the target, and allows the target to resume execution. By contrast, the disconnect command simply breaks the connection. A reconnection (using the target remote command) should be able to resume debugging at the point where the previous connection was broken.
  596.  
  597. The disconnect command just closes the serial connection. It is up to the target server to notice the connection has broken, and to try to re-establish a connection.
  598.  
  599. The detach command requires a RSP exchange with the target for a clean shutdown. The RSP packet exchanges to implement the command are shown as a sequence diagram in Figure 3.8.
  600.  
  601. RSP packet exchanges for the GDB detach command
  602. Figure 3.8.  RSP packet exchanges for the GDB detach command
  603.  
  604.  
  605. The exchange is a simple D packet to which the target responds with an OK packet, before closing the connection.
  606.  
  607. Through this exchange, the GDB client shows the following output:
  608.  
  609. (gdb) detach
  610. Ending remote debugging.
  611. (gdb)
  612.    
  613. The disconnect command has no dialog of itself. The GDB client shows the following output in a typical session. However there are no additional packet exchanges due to the disconnect.
  614.  
  615. (gdb) target remote :51000
  616. Remote debugging using :51000
  617. 0x00000100 in _start ()
  618. (gdb) load hello
  619. Loading section .text, size 0x1290 lma 0x0
  620. Loading section .rodata, size 0xe lma 0x1290
  621. Start address 0x100, load size 4766
  622. Transfer rate: 5 KB/sec, 238 bytes/write.
  623. (gdb) break main
  624. Breakpoint 1 at 0x1264: file hello.c, line 41.
  625. (gdb) c
  626. Continuing.
  627.  
  628. Breakpoint 1, main () at hello.c:41
  629. 41        simputs( "Hello World!\n" );
  630. (gdb) disconnect
  631. Ending remote debugging.
  632. (gdb) target remote :51000
  633. Remote debugging using :51000
  634. main () at hello.c:41
  635. 41        simputs( "Hello World!\n" );
  636. (gdb) c
  637. Continuing.
  638. Remote connection closed
  639. (gdb)
  640.    
  641. Unlike with the detach command, when debugging is reconnected through target remote, the target is still at the point where execution terminated previously.
  642.  
  643. 3.3.  GDB Extended Remote Command Dialogs
  644. The following sections show diagrammatically how various GDB commands map onto RSP packet exchanges to implement the desired behavior with extended remote debugging (i.e when connecting with target extended-remote).
  645.  
  646. 3.3.1.  The target extended-remote Command
  647. The RSP packet exchanges to implement the GDB target extended-remote command are shown as a sequence diagram in Figure 3.9.
  648.  
  649. RSP packet exchanges for the GDB target remote command
  650. Figure 3.9.  RSP packet exchanges for the GDB target remote command
  651.  
  652.  
  653. The dialog is almost identical to that for standard remote debugging (see Section 3.2.1). The difference is the penultimate ! packet, notifying the target that this is an extended remote connection.
  654.  
  655. Through this exchange, the GDB client shows the following output:
  656.  
  657. (gdb) target extended-remote :51000
  658. Remote debugging using :51000
  659. 0x00000100 in _start ()
  660. (gdb)
  661.    
  662. 3.4.  GDB Asynchronous Remote Command Dialogs
  663. The dialogs for asynchronous debugging in general parallel their synchronous equivalents. The only differences are in those commands which can specify a particular thread to execute or stop.
  664.  
  665. Chapter 4.  RSP Server Implementation Example
  666. The examples used are based on the RSP server implementation for the OpenRISC 1000 architectural simulator, Or1ksim.
  667.  
  668. The target is "bare metal". There is no operating system infrastructure necessarily present. In this context, commands relating to threads or the file system are of no meaning and not implemented.
  669.  
  670. 4.1.  The OpenRISC 1000 Architectural Simulator, Or1ksim
  671. 4.1.1.  The OpenRISC 1000 Architecture
  672. The OpenRISC 1000 architecture defines a family of free, open source RISC processor cores. It is a 32 or 64-bit load and store RISC architecture designed with emphasis on performance, simplicity, low power requirements, scalability and versatility.
  673.  
  674. The OpenRISC 1000 is fully documented in its Architecture Manual [6].
  675.  
  676. From a debugging perspective, there are three data areas that are manipulated by the instruction set.
  677.  
  678. Main memory. A uniform address space with 32 or 64-bit addressing. Provision for separate or unified instruction and data and instruction caches. Provision for separate or unified, 1 or 2-level data and instruction MMUs.
  679.  
  680. General Purpose Registers (GPRs). Up to 32 registers, 32 or 64-bit in length.
  681.  
  682. Special Purpose Registers (SPRs). Up to 32 groups each with up to 2048 registers, up to 32 or 64-bit in length. These registers provide all the administrative functionality of the processor: program counter, processor status, saved exception registers, debug interface, MMU and cache interfaces, etc.
  683.  
  684. The Special Purpose Registers (SPRs) represent a challenge for GDB, since they represent neither addressable memory, nor have the characteristics of a register set (generally modest in number).
  685.  
  686. A number of SPRs are of particular significance to the GDB implementation.
  687.  
  688. Configuration registers. The Unit Present register (SPR 1, UPR), CPU Configuration register (SPR 2, CPUCFGR) and Debug Configuration register (SPR 7, DCFGR) identify the features available in the particular OpenRISC 1000 implementation. This includes the instruction set in use, number of general purpose registers and configuration of the hardware debug interface.
  689.  
  690. Program counters. The Previous Program Counter (SPR 0x12, PPC) is the address of the instruction just executed. The Next Program Counter (SPR 0x10, NPC) is the address of the next instruction to be executed. The NPC is the value reported by GDBs $pc variable.
  691.  
  692. Supervision Register. The supervision register (SPR 0x11, SR) represents the current status of the processor. It is the value reported by GDBs status register variable, $ps.
  693.  
  694. 4.1.2.  The OpenRISC 1000 Debug Unit
  695. Of particular importance are the SPRs in group 6 controlling the debug unit (if present). The debug unit can trigger a trap exception in response to any one of up to 10 watchpoints. Watchpoints are logical expressions built by combining matchpoints, which are simple point tests of particular behavior (has a specified address been accessed for example).
  696.  
  697. Debug Value and Control registers. There are up to 8 pairs of Debug Value (SPR 0x3000–0x3007, DVR0 through DVR7) and Debug Control (SPR 0x3008–0x300f, DCR0 through DCR7) registers. Each pair is associated with one hardware matchpoint. The Debug Value register in each pair gives a value to compare against. The Debug Control register indicates whether the matchpoint is enabled, the type of value to compare against (instruction fetch address, data load and/or store address data load and/or store value) and the comparison to make (equal, not equal, less than, less than or equal, greater than, greater than or equal), both signed and unsigned. If the matchpoint is enabled and the test met, the corresponding matchpoint is triggered.
  698.  
  699. Debug Watchpoint counters. There are two 16-bit Debug Watchpoint Counter registers (SPR 0x3012–0x3013, DWCR0 and DWCR1), associated with two further matchpoints. The upper 16 bits are a value to match, the lower 16 bits a counter. The counter is incremented when specified matchpoints are triggered (see Debug Mode register 1). When the count reaches the match value, the corresponding matchpoint is triggered.
  700.  
  701. [Caution]   Caution
  702. There is potential ambiguity in that counters are incremented in response to matchpoints and also generate their own matchpoints. It is not good practice to set a counter to increment on its own matchpoint!
  703.  
  704. Debug Mode registers. There are two Debug Mode registers to control the behavior of the the debug unit (SPR 0x3010–0x3011, DMR1 and DMR2). DMR1 provides a pair of bits for each of the 10 matchpoints (8 associated with DVR/DCR pairs, 2 associated with counters). These specify whether the watchpoint is triggered by the associated matchpoint, by the matchpoint AND-ed with the previous watchpoint or by the matchpoint OR-ed with the previous watchpoint. By building chains of watchpoints, complex logical tests of hardware behavior can be built up.
  705.  
  706. Two further bits in DMR1 enable single step behavior (a trap exception occurs on completion of each instruction) and branch step behavior (a trap exception occurs on completion of each branch instruction).
  707.  
  708. DMR2 contains an enable bit for each counter, 10 bits indicating which watchpoints are assigned to which counter and 10 bits indicating which watchpoints generate a trap exception. It also contains 10 bits of output, indicating which watchpoints have generated a trap exception.
  709.  
  710. Debug Stop and Reason registers. In normal operation, all OpenRISC 1000 exceptions are handled through the exception vectors at locations 0x100 through 0xf00. The Debug Stop register (SPR 0x3014, DSR) is used to assign particular exceptions instead to the JTAG interface. These exceptions stall the processor, allowing the machine state to be analyzed through the JTAG interface. Typically a debugger will enable this for trap exceptions used for breakpointing.
  711.  
  712. Where an exception has been diverted to the development interface, the Debug Reason register (SPR 0x3021, DRR) indicates which exception caused the diversion. Note that although single stepping and branch stepping cause a trap, if they are assigned to the JTAG interface, they do not set the TE bit in the DRR. This allows an external debugger to distinguish between breakpoint traps and single/branch step traps.
  713.  
  714. 4.1.3.  The OpenRISC 1000 JTAG Interface
  715. In a physical OpenRISC 1000 chip, debugging would be via the JTAG interface. However since the examples used here are based on the architectural simulator, the JTAG interface is not described further here.
  716.  
  717. 4.1.4.  Application Binary Interface (ABI)
  718. The ABI for the OpenRISC 1000 is described in Chapter 16 of the Architecture Manual [6]. However the actual GCC compiler implementation differs very slightly from the documented ABI. Since precise understanding of the ABI is critical to GDB, those differences are documented here.
  719.  
  720. Register Usage: R12 is used as another callee-saved register. It is never used to return the upper 32 bits of a 64-bit result on a 32-bit architecture. All values greater than 32-bits are returned by a pointer.
  721.  
  722. Although the specification requires stack frames to be double word aligned, the current GCC compiler implements single word alignment.
  723.  
  724. Integral values more than 32 bits (64 bits on 64-bit architectures), structures and unions are returned as pointers to the location of the result. That location is provided by the calling function, which passes it as a first argument in GPR 3. In other words, where a function returns a result of this type, the first true argument to the function will appear in R4 (or R5/R6 if it is a 64-bit argument on a 32-bit architecture).
  725.  
  726. 4.1.5.  Or1ksim: the OpenRISC 1000 Architectural Simulator
  727. Or1ksim is an instruction set simulator (ISS) for the OpenRISC 1000 architecture. At present only the 32-bit architecture is modeled. In addition to modeling the core processor, Or1ksim can model a number of peripherals, to provide the functionality of a complete System-on-Chip (SoC).
  728.  
  729. Or1ksim implements the RSP server side. It is the implementation of this RSP server which forms the example for this application note.
  730.  
  731. 4.2.  OpenRISC 1000 GDB Architectural Specification
  732. The GDB architectural specification (gdbarch) for OpenRISC 1000 is fully documented in Embecosm Application Note 3 ([2]). This section notes some important features, which will be of relevance to the RSP server implementation.
  733.  
  734. All data sizes are specified to match the ABI for the OpenRISC 1000
  735.  
  736. All memory breakpoints are implemented at the program counter using the l.trap 1 opcode, which like all OpenRISC 1000 instructions is 4 bytes long.
  737.  
  738. This means that after a trap due to a breakpoint, the program counter must be stepped back, to allow re-execution on resumption of the instruction that was replaced by l.trap
  739.  
  740. A total of 35 registers are defined to GDB: The 32 general purpose registers, the previous program counter, the next program counter (colloquially known as the program counter) and the supervision register. There are no pseudo-registers.
  741.  
  742. 4.3.  Overview of the RSP Server Implementation
  743. All the code for the OpenRISC 1000 RSP server interface can be found in debug/rsp-server.c. The interface is specified in the header file, debug/rsp-server.h.
  744.  
  745. The code is commented for post-processing with doxygen ([5]).
  746.  
  747. 4.3.1.  External Code Interface
  748. The external interface to the RSP server code is through three void functions.
  749.  
  750. rsp_init (). Called at start up to initialize the RSP server. It initializes global data structures (discussed in Section 4.3.2) and then sets up a TCP/IP listener on the configured RSP port.
  751.  
  752. handle_rsp (). Called repeatedly when the processor is stalled to read packets from any GDB client and process them.
  753.  
  754. rsp_exception (). Called from the simulator to record any exceptions that occur, for subsequent use by handle_rsp (). It takes a single argument, the OpenRISC 1000 exception handler entry address, which is mapped by the RSP server to the equivalent GDB target signal.
  755.  
  756. 4.3.2. Global Data Structures
  757. The RSP server has one data structure, rsp, shared amongst its implementing functions (and is thus declared static in rsp-server.c).
  758.  
  759. static struct
  760. {
  761.   int                client_waiting;
  762.   int                proto_num;
  763.   int                server_fd;
  764.   int                client_fd;
  765.   int                sigval;
  766.   unsigned long int  start_addr;
  767.   struct mp_entry   *mp_hash[MP_HASH_SIZE];
  768. } rsp;
  769.    
  770. The fields are:
  771.  
  772. client_waiting. A flag to indicate if the target has previously been set running (by a GDB continue or step) instruction, in which case the client will be waiting for a response indicating when and why the server has stopped.
  773.  
  774. proto_num. The number of the communication protocol used (in this case TCP/IP).
  775.  
  776. server_fd. File handle of the server connection to the RSP port, listening for connections. Set to -1 if it is not open.
  777.  
  778. client_fd. File handle of the current client connection to the RSP port, on which all packet transfers take place. Set to -1 if it is not open.
  779.  
  780. sigval. The last exception raised by the target as a GDB target signal number. Set by the simulator calling rsp_exception ().
  781.  
  782. start_addr. The start address of the last run. Needed to support the restart function of extended remote debugging.
  783.  
  784. mp_hash. Pointer to the hash table of matchpoints set (see Section 4.3.2.1).
  785.  
  786. The RSP server also draws on several Or1ksim data structures. Most notably config for configuration data and cpu_state for all the CPU state data.
  787.  
  788. 4.3.2.1.  The Matchpoint Hash Table
  789. The matchpoint hash table is implemented as an open hash table, where the hash table entry is calculated as the address of the matchpoint modulo the size of the hash table (MP_HASH_SIZE) and the key is formed from the address and the matchpoint type. Matchpoint types are defined for memory and hardware breakpoints and hardware write, read and access watchpoints:
  790.  
  791. enum mp_type {
  792.   BP_MEMORY   = 0,
  793.   BP_HARDWARE = 1,
  794.   WP_WRITE    = 2,
  795.   WP_READ     = 3,
  796.   WP_ACCESS   = 4
  797. };
  798.          
  799. Each entry in the table holds the instruction at the location of the matchpoint, which in the case of memory breakpoints will have been replaced by l.trap
  800.  
  801. struct mp_entry
  802. {
  803.   enum mp_type       type;
  804.   unsigned long int  addr;
  805.   unsigned long int  instr;
  806.   struct mp_entry   *next;
  807. };
  808.      
  809. Linking through the next field allows multiple entries with the same hash value to be stored.
  810.  
  811. Interface to the hash table is through four functions:
  812.  
  813. mp_hash_init (). void function which sets all the hash table slots to NULL
  814.  
  815. mp_hash_add (). void function which adds an entry to the hash table (if it is not already there). It takes three arguments, the matchpoint type and address and the instruction stored at that address. Repeated adding of the same entry has no effect, which provides convenient behavior for debugging over noisy connections where packets may be duplicated.
  816.  
  817. mp_hash_lookup (). Function to look up a key in the hash table. It takes a matchpoint type and address and returns a pointer to the entry (as a pointer to struct mp_entry) or NULL if the key is not found.
  818.  
  819. mp_hash_delete (). Function with the same behavior as mp_hash_lookup (), but also deletes the entry from the hash table if it is found there. If the entry is not found, it silently does nothing (and returns NULL).
  820.  
  821. [Note]  Note
  822. This function returns a pointer to the struct—mp_entry deleted from the hash table if the key is found. To avoid memory leaks it is important that the caller delete this structure (using free ()) when the data has been extracted.
  823.  
  824. 4.3.3.  Top Level Behavior
  825. The RSP server initialization, rsp_init () is called from the main simulator initialization, sim_init () in toplevel-support.c.
  826.  
  827. The main simulation initialization is also modified to start the processor stalled on a TRAP exception if RSP debugging is enabled. This ensures that the handler will be called initially.
  828.  
  829. The main loop of Or1ksim, called after initialization, is in the function exec_main () in cpu/or32/execute.c.
  830.  
  831. If RSP debugging is enabled in the Or1ksim configuration, the code to interact with the RSP client (handle_rsp ()) is called at the start of each iteration, but only if the processor is stalled. The handler is called repeatedly until an interaction with the client unstalls the processor (i.e. a step or continue function.
  832.  
  833. void
  834. exec_main ()
  835. {
  836.   long long time_start;
  837.  
  838.   while (1)
  839.     {
  840.       time_start = runtime.sim.cycles;
  841.       if (config.debug.enabled)
  842.         {
  843.           while (runtime.cpu.stalled)
  844.             {
  845.               if (config.debug.rsp_enabled)
  846.                 {
  847.                   handle_rsp ();
  848.                 }
  849.  
  850.               ...
  851.        
  852. Since interaction with the client can only occur when the processor is stalled, BREAK signals (i.e. ctrl-C) cannot be intercepted.
  853.  
  854. It would be possible to poll the connection on every instruction iteration, but the performance overhead on the simulator would be unacceptable.
  855.  
  856. An implementation to pick up BREAK signals should use event driven I/O - i.e. with a signal handler for SIGIO. An alternative is to poll the interface less frequently when the CPU is not stalled. Since Or1ksim executes at several MIPS, polling every 100,000 cycles would mean a response to ctrl-C of less than 100ms, while adding no significant overhead.
  857.  
  858. 4.3.3.1.  Exception handling
  859. The RSP interface will only pick up those exceptions which cause the processor to stall. These are the exceptions routed to the debug interface, rather than through their exception vectors, and are specified in the Debug Stop Register (set during initialization). In the present implementation, only TRAP exceptions are picked up this way, allowing the debugger to process memory based breakpoints. However an alternative implementation could allow the debugger to see all exceptions.
  860.  
  861. Exceptions will be processed at the start of each iteration by handle_rsp (). However the handler needs to know which signal caused the exception. This is achieved by modifying the main debug unit exception handling function (debug_ignore_exception () in debug/debug-unit.c) to call rsp_exception () if RSP is enabled for any exception handled by the debug unit. This function stores the exception (translated to a GDB target signal) in rsp.sigval.
  862.  
  863. int
  864. debug_ignore_exception (unsigned long  except)
  865. {
  866.   int           result = 0;
  867.   unsigned long dsr    = cpu_state.sprs[SPR_DSR];
  868.  
  869.   switch (except)
  870.     {
  871.     case EXCEPT_RESET:    result = (dsr & SPR_DSR_RSTE);  break;
  872.     case EXCEPT_BUSERR:   result = (dsr & SPR_DSR_BUSEE); break;
  873.  
  874.   ...
  875.  
  876.   cpu_state.sprs[SPR_DRR] |= result;
  877.   set_stall_state (result != 0);
  878.  
  879.   if (config.debug.rsp_enabled && (0 != result))
  880.     {
  881.       rsp_exception (except);
  882.     }
  883.  
  884.   return  (result != 0);
  885.  
  886. }       /* debug_ignore_exception () */
  887.      
  888. For almost all exceptions, this approach is suitable. However TRAP exceptions due to single stepping are taken at the end of each instruction execution and do not use the standard exception handling mechanism.
  889.  
  890. The exec_main () function already includes code to handle this towards the end of the main loop. This is extended with a call to rsp_exception () if RSP debugging is enabled.
  891.  
  892.       if (config.debug.enabled)
  893.         {
  894.           if (cpu_state.sprs[SPR_DMR1] & SPR_DMR1_ST)
  895.             {
  896.               set_stall_state (1);
  897.  
  898.               if (config.debug.rsp_enabled)
  899.                 {
  900.                   rsp_exception (EXCEPT_TRAP);
  901.                 }
  902.             }
  903.         }
  904.      
  905. 4.4.  The Serial Connection
  906. 4.4.1.  Establishing the Server Listener Socket
  907. A TCP/IP socket to listen on the RSP port is created in rsp_init (), and its file descriptor stored in rsp.server_fd. As a variant, if the port is configured to be 0, the socket uses the port specified for the or1ksim-rsp service.
  908.  
  909. The setup uses standard POSIX calls to establish the socket and associate it with a TCP/IP port. The interface is set to be non-blocking and marked as a passive port (using a call to listen ()), with at most one outstanding client request. There is no meaning to the server handling more than one client GDB connection.
  910.  
  911. The main RSP handler function handle_rsp () checks that the server port is still open. This may be closed if there is a serious error. In the present implementation, handle_rsp () gives up at this point, but a richer implementation could try reopening a new server port.
  912.  
  913. 4.4.2.  Establishing the Client Connection
  914. If a client connection is yet to be established, then handle_rsp () blocks until a connection request is made. A valid request is handled by rsp_server_request (), which opens a connection to the client, saving the file descriptor in rsp.client_fd.
  915.  
  916. This connection is also non-blocking. Nagel's algorithm is also disabled, since all packet bytes should be sent immediately, rather than being queued to build larger blocks.
  917.  
  918. 4.4.3.  Communicating with the Client
  919. Having established a client connection if necessary, handle_rsp () blocks until packet data is available. It then calls rsp_client_request () to read the packet, provide the required behavior and generate any reply packets.
  920.  
  921. 4.5.  The Packet Interface
  922. 4.5.1.  Packet Representation
  923. Although packets are character based, they cannot simply be represented as strings, since binary packets may contain the end of string character (zero). Packets are therefore represented as a simple struct, rsp_buf:
  924.  
  925. struct rsp_buf
  926. {
  927.   char  data[GDB_BUF_MAX];
  928.   int   len;
  929. };
  930.    
  931. For convenience, all packets have a zero added at location data[len], allowing the data field of non-binary packets to be printed as a simple string for debugging purposes.
  932.  
  933. 4.5.2.  Getting Packets
  934. The packet reading function is get_packet (). It looks for a well formed packet, beginning with '$', with '#' at the end of data and a valid 2 byte checksum (see Figure 2.2 in Section 2.3 for packet representation details).
  935.  
  936. If a valid packet is found, '+' is returned using put_rsp_char () (see Section 4.5.3.1) and the packet is returned as a pointer to a struct rsp_buf. Otherwise '-' is returned and the loop repeated to get a new packet (presumably retransmitted by the client).
  937.  
  938. The buffer is statically allocated within get_packet (). This is acceptable, since two received packets cannot be in use simultaneously.
  939.  
  940. In general errors are silently ignored (the connection could be poor quality). However bad checksums are noted in a warning message. In the event of end of file being encountered, get_packet () returns immediately with NULL as result.
  941.  
  942. 4.5.2.1.  Character Input
  943. The individual characters are read using get_rsp_char (). The result is returned as an int, allowing -1 to be used to indicate end of file, or other error. In the event of end of file, or error, the client connection is closed and rsp.client_fd set to -1.
  944.  
  945. 4.5.3.  Sending Packets
  946. The packet writing function is put_packet (). It takes as argument a struct rsp_buf and creates a well formed packet, beginning with '$', with '#' at the end of data and a valid 2 byte checksum (see Figure 2.2 in Section 2.3 for packet representation details).
  947.  
  948. The acknowledgment character is read using get_rsp_char () (see Section 4.5.2.1). If successful ('+'), the function returns. Otherwise the packet is repeatedly resent until ('+') is received as a response.
  949.  
  950. Errors on writing are silently ignored. If the read of the acknowledgment returns -1 (indicating failure of the connection or end-of-file), put_packet () returns immediately.
  951.  
  952. 4.5.3.1.  Character Output
  953. The individual characters are written by put_packet () using put_rsp_char (). In the event of an error other than a retry request or interrupt a warning is printed and the connection closed.
  954.  
  955. 4.6.  Convenience Functions
  956. A number of convenience functions are provided for RSP protocol behavior that is repeatedly required.
  957.  
  958. 4.6.1.  Convenience String Packet Output
  959. Many response packets take the form of a fixed string. As a convenience put_str_packet () is provided. This takes a constant string argument, from which a struct rsp_buf is constructed. This is then sent using put_packet ().
  960.  
  961. 4.6.2.  Conversion Between Binary and Hexadecimal Characters
  962. The function hex () takes an ASCII character which is a valid hexadecimal digit (upper or lower case) and returns its value (0-15 decimal). Any invalid digit returns -1.
  963.  
  964. The static array hexchars[] declared at the top level in rsp-server.c provides a mapping from a hexadecimal digit value (in the range 0-15 decimal) to its ASCII character representation.
  965.  
  966. 4.6.3.  Conversion Between Binary and Hexadecimal Character Registers
  967. For several packets, register values must be represented as strings of characters in target endian order. For convenience, the functions reg2hex () and hex2reg () are provided. Each takes a pointer to a buffer for the characters. For reg2hex () a value to be converted is passed. For hex2reg () the value represented is returned as a result.
  968.  
  969. 4.6.4.  Data "Unescaping"
  970. The function rsp_unescape () takes a pointer to a data buffer and a length and "unescapes" the buffer in place. The length is the size of the data after all escape characters have been removed.
  971.  
  972. 4.6.5.  Setting the Program Counter
  973. The program counter (i.e. the address of the next instruction to be executed) is held in Special Purpose Register 16 (next program counter). Within Or1ksim this is cached in cpu_state.pc.
  974.  
  975. When changing the next program counter in Or1ksim it is necessary to change associated data which controls the delay slot pipeline. If there is a delayed transfer, the flag cpu_state.delay_insn is set. The address of the next instruction to be executed (which is affected by the delay slot) is held in the global variable, pc_next.
  976.  
  977. The utility function set_npc () takes an address as argument. If that address is different to the current value of NPC, then the NPC (in cpu_state.pc) is updated to the new address, the delay slot pipeline is cleared (cpu_state.delay_insn is set to zero) and the following instruction (pcnext) is set to cpu_state.pc+4.
  978.  
  979. 4.7.  High Level Protocol Implementation
  980. The high level protocol is driven from the function rsp_client_request (), which is called from handle_rsp () once a client connection is established.
  981.  
  982. This function calls get_packet () to get the next packet from the client, and then switches on the first character of the packet data to determine the action to be taken.
  983.  
  984. The following sections discuss the implementation details of the various packet types that must be supported.
  985.  
  986. 4.7.1.  Deprecated Packets
  987. Packets requesting functionality that is now deprecated are ignored (possibly with an error response if that is expected) and a warning message printed. The packets affected are: b (set baud rate), B (set a breakpoint), d (disable debug) and r (reset the system).
  988.  
  989. In each case the warning message indicates the recommended way to achieve the desired functionality.
  990.  
  991. 4.7.2.  Unsupported Packets
  992. The development of an interface such as RSP can be incremental, where functionality is added in stages. A number of packets are not supported. In a few cases this is because the functionality is meaningless for the current target, but in the majority of cases, the functionality can be supported as the server is developed further in the future.
  993.  
  994. The unsupported packets are:
  995.  
  996. A. Specifying the arguments for a program is hard on "bare metal". It requires determining whether the code has yet entered its main () function and if not patching in pointers to the new arguments.
  997.  
  998. C and S. Continuing or stepping with a signal is currently not supported. Implementing this would require insertion of an exception, which is not difficult, so this will be an enhancement for the near future.
  999.  
  1000. F. File I/O is not meaningful with a bare metal target, where a file-system may not be present.
  1001.  
  1002. i and I. The target is an architectural simulator, executing one instruction at a time. So cycle accurate stepping is not available.
  1003.  
  1004. t. The meaning (or use) of the search command is not clear, so this packet is not currently implemented.
  1005.  
  1006. 4.7.3.  Simple Packets
  1007. Some packets are very simple to handle, either requiring no response, or a simple fixed text response.
  1008.  
  1009. !. A simple reply of "OK" indicates the target will support extended remote debugging.
  1010.  
  1011. D. The detach is acknowledged with a reply packet of "OK" before the client connection is closed and rsp.client_fd set to -1. The semantics of detach require the target to resume execution, so the processor is unstalled using set_stall_state (0).
  1012.  
  1013. H. This sets the thread number of subsequent operations. Since thread numbers are of no relevance to this target, a response of "OK" is always acceptable.
  1014.  
  1015. k. The kill request is used in extended mode before a restart or request to run a new program (vRun packet). Since the CPU is already stalled, it seems to have no additional semantic meaning. Since it requires no reply it can be silently ignored.
  1016.  
  1017. T. Since this is a bare level target, there is no concept of separate threads. The one thread is always active, so a reply of "OK" is always acceptable.
  1018.  
  1019. 4.7.4.  Reporting the Last Exception
  1020. The response to the ? packet is provided by rsp_report_exception (). This is always a S packet. The signal value (as a GDB target signal) is held in rsp.sigval, and is presented as two hexadecimal digits.
  1021.  
  1022. 4.7.5.  Continuing
  1023. The c packet is processed by rsp_continue (). Any address from which to continue is broken out from the packet using sscanf (). If no address is given, execution continues from the current program counter (in cpu_state.pc).
  1024.  
  1025. The continue functionality is provided by the function rsp_continue_generic () which takes an address and an Or1ksim exception as arguments, allowing it to be shared with the processing of the C packet (continue with signal) in the future. For the c packet, EXCEPT_NONE is used.
  1026.  
  1027. rsp_continue_generic () at present ignores its exception argument (the C packet is not supported). It sets the program counter to the address supplied using set_npc () (see Section 4.6.5).
  1028.  
  1029. The control registers of the debug unit must then be set appropriately. The Debug Reason Register and watchpoint generation flags in Debug Mode Register 2 are cleared. The Debug Stop Register is set to trigger on TRAP exceptions (so memory breakpoints are picked up), and the single step flag is cleared in Debug Mode Register 1.
  1030.  
  1031.   cpu_state.sprs[SPR_DRR]   = 0;
  1032.   cpu_state.sprs[SPR_DMR2] &= ~SPR_DMR2_WGB;
  1033.   cpu_state.sprs[SPR_DMR1] &= ~SPR_DMR1_ST;
  1034.   cpu_state.sprs[SPR_DSR]  |= SPR_DSR_TE;
  1035.    
  1036. The processor is then unstalled (set_stall_state (0)) and the client waiting flag (rsp.client_waiting) set. This latter means that when handle_rsp () is next entered, it will know that a reply is outstanding, and return the appropriate stop packet required when the processor stalls after a continue or step command.
  1037.  
  1038. 4.7.6.  Reading and Writing All Registers
  1039. The g and G packets respectively read and write all registers, and are handled by the functions rsp_read_all_regs () and rsp_write_all_regs ().
  1040.  
  1041. 4.7.6.1.  Reading All Registers
  1042. The register data is provided in a reply packet as a stream of hexadecimal digits for each register in GDB register order. For the OpenRISC 1000 this is the 32 GPRs followed by the Previous Program Counter, Next Program Counter and Supervision Register SPRs. Each register is presented in target endian order, using the convenience function reg2hex ().
  1043.  
  1044. 4.7.6.2.  Writing All Registers
  1045. The register data follows the G as a stream of hexadecimal digits for each register in GDB register order. For the OpenRISC 1000 this is the 32 GPRs followed by the Previous Program Counter, Next Program Counter and Supervision Register SPRs. Each register is supplied in target endian order and decoded using the utility function hex2reg ().
  1046.  
  1047. The corresponding values are set in the Or1ksim data structures. For the GPRs this is in the cpu_state.regs array. For the Previous Program Counter and Supervision Register it is the relevant entry in the cpu_state.sprs array. The Next Program Counter is set using the set_npc () convenience function (see Section 4.6.5), which ensures associated variables, controlling the delay pipeline are also updated appropriately.
  1048.  
  1049. 4.7.7.  Reading and Writing Memory
  1050. The m and M packets respectively read and write blocks of memory, with the data represented as hexadecimal characters. The processing is provided by rsp_read_mem () and rsp_write_mem ().
  1051.  
  1052. 4.7.7.1.  Reading Memory
  1053. The syntax of the packet is m,addr,len:. sscanf () is used to break out the address and length fields (both in hex).
  1054.  
  1055. The reply packet is a stream of bytes, starting from the lowest address, each represented as a pair of hex characters. Each byte is read from memory using the simulator function eval_direct8 (), having first verified the memory area is valid using verify_memoryarea ().
  1056.  
  1057. The packet is only sent if all bytes are read satisfactorily. Otherwise an error packet, "E01" is sent. The actual error number does not matter—it is not used by the client.
  1058.  
  1059. [Caution]   Caution
  1060. The use of eval_direct8 () is not correct, since it ignores any caching or memory management. As a result the current implementation is only correct for configurations with no MMU or cache.
  1061.  
  1062. 4.7.7.2.  Writing Memory
  1063. The syntax of the packet is m,addr,len: followed by the data to be written as a stream of bytes, starting from the lowest address, each represented as a pair of hex characters. sscanf () is used to break out the address and length fields (both in hex).
  1064.  
  1065. Each byte is written to memory using set_program8 () (which ignores any read only constraints on the modeled memory), having first verified that the memory address is valid using verify_memoryarea ().
  1066.  
  1067. If all bytes are written successfully, a reply packet "OK" is sent. Otherwise an error reply, "E01" is sent. The actual error number does not matter—it is not used by the client.
  1068.  
  1069. [Caution]   Caution
  1070. The use of set_program8 () is not correct, since it ignores any caching or memory management. As a result the current implementation is only correct for configurations with no MMU or cache.
  1071.  
  1072. 4.7.8.  Reading and Writing Individual Registers
  1073. The p and P packets are implemented respectively by rsp_read_reg () and rsp_write_reg ().
  1074.  
  1075. These functions are very similar in implementation to rsp_read_all_regs () and rsp_write_all_regs () (see Section 4.7.6).
  1076.  
  1077. The two differences are that the packet data must be parsed to identify the register affected, and (clearly) only one register is read or written.
  1078.  
  1079. 4.7.9.  Query Packets
  1080. Query packets all start with q. The functionality is all provided in the function rsp_query ().
  1081.  
  1082. 4.7.9.1.  Deprecated Query Packets
  1083. The qL and qP packets to obtain information about threads are now obsolete, and are ignored with a warning. An empty reply (meaning not supported) is sent to each.
  1084.  
  1085. These packets have been replaced by qC, qfThreadInfo, qsThreadInfo, qThreadExtraInfo and qGetTLSAddr packets (see Section 4.7.9.3).
  1086.  
  1087. 4.7.9.2.  Unsupported Query Packets
  1088. A number of query packets are not needed in an initial implementation, or make no sense for a "bare metal" target.
  1089.  
  1090. qCRC. This can be implemented later by writing the code to compute a CRC for a memory area. A warning is printed and an error packet ("E01") returned.
  1091.  
  1092. qGetTLSAddr. This is a highly operating system dependent function to return the location of thread local storage. It has no meaning in a simple "bare metal" target. An empty reply is used to indicate that the feature is not supported.
  1093.  
  1094. qRcmd. This packet is used to run a remote command. Although this does not have a direct meaning, it is a useful way of passing arbitrary requests to the target. In the current implementation two commands readspr and writespr are provided to read and write values from and to Special Purpose Registers (needed for the GDB info spr and spr commands). These commands cannot be implemented using the main packets, since SPRs do not appear in either the memory map or the register file.
  1095.  
  1096. A side effect of this mechanism is that the remote commands are directly visible to the user through the GDB monitor command. Thus there are two ways to view a SPR. The "official" way:
  1097.  
  1098. (gdb) info spr npc
  1099. SYS.NPC = SPR0_16 = 256 (0x100)
  1100. (gdb)
  1101.          
  1102. And the unofficial way:
  1103.  
  1104. (gdb) monitor readspr 10
  1105.      100(gdb)
  1106.          
  1107. For this reason, defining and using a new qXfer packet type (see below) might be preferred as a way of accessing custom information such as SPR values.
  1108.  
  1109. qXfer:. This packet is used to transfer "special" data to and from the target. A number of variants are already defined, to access particular features, some specific to certain targets and operating systems.
  1110.  
  1111. This is the alternative way to provide SPR access, by providing a new variant qXfer specific to the OpenRISC 1000. However any new qXfer does demand integration within GDB.
  1112.  
  1113. qXfer functionality must be specifically enabled using the qSupported packet (see Section 4.7.9.5). For the present this is not provided.
  1114.  
  1115. 4.7.9.3.  Queries About Threads
  1116. Although threads are not meaningful on the "bare metal" target, sensible replies can be given to most of the thread related queries by using -1 to mean "all threads".
  1117.  
  1118. qC. An empty reply is used, which is interpreted as "use the previously selected thread". Since no thread is ever explicitly selected by the target, this will allow the client GDB session to use its default NULL thread, which is what is wanted.
  1119.  
  1120. qfThreadInfo and qsThreadInfo. These packets are used to report the currently active threads. qfThreadInfo is used to report the first set of information and qsThreadInfo for all subsequent information, until a reply packet of "l" indicates the last packet.
  1121.  
  1122. In this implementation, a reply packet of "m-1" (all packets are active is used for qfThreadInfo and a reply packet of "l" is used for qsThreadInfo to indicate there is no more information.
  1123.  
  1124. qThreadExtraInfo. This should return a printed string, encoded as ASCII characters as hexadecimal digits with attributes of the thread specified as argument.
  1125.  
  1126. The argument is always ignored (this target only has one thread), and the reply "Runnable" is sent back
  1127.  
  1128. 4.7.9.4.  Query About Executable Relocation
  1129. The qOffsets packet requests a reply string of the format "Text=xx;Data=yy;Bss=zz" to identify the offsets used in relocating the sections of code to be downloaded.
  1130.  
  1131. No relocation is used in this target, so the fixed string "Text=0;Data=0;Bss=0" is sent as a reply.
  1132.  
  1133. [Caution]   Caution
  1134. The GDB User Guide ([3]) suggests the final ";Bss=zz" is optional. This is not the case. It must be specified.
  1135.  
  1136. 4.7.9.5.  Query About Supported Functionality
  1137. The qSupported packet asks the client for information about features for which support is optional. By default, none are supported. The features are maximum packet size and support for the various qXfer packets and the QPassSignals packet.
  1138.  
  1139. Of these only the packet size is of relevance to this target, so a reply of "PacketSize=xx", where "xx" is the maximum packet size (GDB_BUF_MAX) is sent.
  1140.  
  1141. 4.7.9.6.  Query About Symbol Table Data
  1142. A qSymbol:: packet (i.e. a qSymbol packet with no data) is used as an offer from the client to provide symbol table information. The server may respond with packets of the form qSymbol:name to request information about the symbol name.
  1143.  
  1144. A reply of "OK" is used to indicate that no further symbol table information is required. For the current implementation, no information is required, so "OK" is always sent as the response.
  1145.  
  1146. 4.7.10.  Set Packets
  1147. Set packets all start with Q. The functionality is all provided in rsp_set ().
  1148.  
  1149. The QPassSignals packet is used to pass signals to the target process. This is not supported, and not reported as supported in a qSupported packet (see Section 4.7.9.5), so should never be received.
  1150.  
  1151. If a QPassSignals packet is received, an empty response is used to indicate no support.
  1152.  
  1153. 4.7.10.1.  Tracepoint Packets
  1154. All the remaining set packets (QTDP, QFrame, QTStart, QTStop, QTinit and QTro) are concerned with tracepoints. Tracepoints are not currently supported with the Or1ksim target, so an empty reply packet is sent to indicate this.
  1155.  
  1156. 4.7.11.  Restart the Target
  1157. The functionality for the R packet is provided in rsp_restart (). The start address of the current target is held in rsp.start_addr. The program counter is set to this address using set_npc () (see Section 4.6.5).
  1158.  
  1159. The processor is not unstalled, since there would be no way to regain control if this happened. It is up to the GDB client to restart execution (with continue or step if that is what is desired).
  1160.  
  1161. This packet should only be used in extended remote debugging.
  1162.  
  1163. 4.7.12.  Stepping
  1164. The step packet (s) requests a single machine instruction step. Its implementation is almost identical to that of the continue (c) packet, but using the functions rsp_step () and rsp_step_generic ().
  1165.  
  1166. The sole difference is that the generic function sets, rather than clears the single stepping flag in Debug Mode Register 1. This ensures a TRAP exception is raised after the next instruction completes execution.
  1167.  
  1168.   cpu_state.sprs[SPR_DRR]   = 0;
  1169.   cpu_state.sprs[SPR_DMR2] &= ~SPR_DMR2_WGB;
  1170.   cpu_state.sprs[SPR_DMR1] |= SPR_DMR1_ST;
  1171.   cpu_state.sprs[SPR_DSR]  |= SPR_DSR_TE;
  1172.    
  1173. 4.7.13.  v Packets
  1174. The v packets provide additional flexibility in controlling execution on the target. Much of this is related to non-stop targets with multithreading support and to flash memory control and need not be supported in a simple implementation.
  1175.  
  1176. All the v packet functionality is provided in the function rsp_vpkt ().
  1177.  
  1178. 4.7.13.1.  Extended Debugging Support
  1179. The vAttach and vRun packets are only required for extended remote debugging.
  1180.  
  1181. vRun is used to specify a new program to be run, or if no program is specified that the existing target program be run again. In the current implementation, only this latter option is supported. Any program specified is ignored with a warning. The semantics of the vRun command are that the target is left in the stopped state, and the stopped condition reported back to the client.
  1182.  
  1183. The vRun packet may also specify arguments to pass to the program to be run. In the current implementation those arguments are ignored with a warning.
  1184.  
  1185. This behavior is identical to that of the R (restart) packet (see Section 4.7.11) with the addition of a reply packet. The implementation uses exactly this functionality, with a reply packet reporting a TRAP exception.
  1186.  
  1187.       rsp_restart ();
  1188.       put_str_packet ("S05");
  1189.      
  1190. The vAttach packet allows a client to attach to a new process. In this target, there is only one process, so the process argument is ignored and no action taken. However a stop response is required, so a reply packet indicating a TRAP exception is sent (put_str_packet ("S05").
  1191.  
  1192. 4.7.13.2.  Non-stop Support
  1193. The vCont packet provides a more fine grained control over individual threads than the c or s packets.
  1194.  
  1195. Support for vCont packets is established with a vCont? packet which should always be supported. In the current implementation, vCont is not supported, so an empty response is provided to any vCont? packet.
  1196.  
  1197. 4.7.13.3.  File Handling
  1198. The vFile packet allows a file operation to be implemented on a target platform. In the absence of any file system with the "bare metal" target, this packet is not supported. An empty response is sent and a warning printed.
  1199.  
  1200. 4.7.13.4.  Flash Memory
  1201. The vFlashErase, vFlashWrite and vFlashDone packets provide support for targets with flash memory systems.
  1202.  
  1203. At present these are not supported on the target and an error reply ("E01") is returned. However Or1ksim can model flash memory, and these packets could be supported in the future.
  1204.  
  1205. 4.7.14.  Binary Data Transfer
  1206. The X provides for data to be written to the target in binary format. This is the mechanism of choice for program loading (the GDB load command). GDB will first probe the target with an empty X packet (which is 7-bit clean). If an "OK" response is received, subsequent transfers will use the X packet. Otherwise M packets will be used. Thus even 7-bit clean implementations should still support replying to an empty X packet.
  1207.  
  1208. The example implementation is found in rsp_write_mem_bin (). Even though the data is binary, it must still be escaped so that '#', '$' and '}' characters are not mistaken for new packets or escaped characters.
  1209.  
  1210. Each byte is read, and if escaped, restored to its original value. The data is written using set_program8 (), having first verified the memory location with verify_memoryarea ().
  1211.  
  1212. If all bytes are successfully written, a reply packet of "OK" is sent. Otherwise and error packet ("E01") is sent. The error number does not matter—it is ignored by the target.
  1213.  
  1214. [Caution]   Caution
  1215. The use of set_program8 () is not correct, since it ignores any caching or memory management. As a result the current implementation is only correct for configurations with no instruction MMU or instruction cache.
  1216.  
  1217. 4.7.15.  Matchpoint Handling
  1218. Matchpoint is the general term used for breakpoints (both memory and hardware) and watchpoints (write, read and access). Matchpoints are removed with zcommand> packets and set with Z packets. The functionality is provided respectively in resp_remove_matchpoint () and resp_insert_matchpoint ().
  1219.  
  1220. The current implementation only supports memory (soft) breakpoints controlled by Z0 and Z0 packets. However the OpenRISC 1000 architecture and Or1ksim have hardware breakpoint and watchpoint functionality within the debug unit, which will be supported in the future.
  1221.  
  1222. The target is responsible for keeping track of any memory breakpoints set. This is managed through the hash table pointed to by rsp.mp_hash. Each matchpoint is recorded in a matchpoint entry:
  1223.  
  1224. struct mp_entry
  1225. {
  1226.   enum mp_type       type;
  1227.   unsigned long int  addr;
  1228.   unsigned long int  instr;
  1229.   struct mp_entry   *next;
  1230. };
  1231.    
  1232. When an instruction is replaced by l.trap for a memory breakpoint, the replace instruction is recorded in the hash table as a struct mp_entry with type BP_MEMORY. This allows it to be replaced when the the breakpoint is cleared.
  1233.  
  1234. The hash table is accessed by the functions mp_hash_init (), mp_hash_add (), mp_hash_lookup () and mp_hash_delete (). These are described in more detail in Section 4.3.2.1
  1235.  
  1236. 4.7.15.1.  Setting Matchpoints
  1237. Only memory (soft) breakpoints are supported. The instruction is read from memory at the location of the breakpoint and stored in the hash table (using mp_hash_add ()). A l.trap instruction (OR1K_TRAP_INSTR) is inserted in its place using set_program32 () and a reply of "OK" sent back.
  1238.  
  1239.       mp_hash_add (type, addr, eval_direct32 (addr, 0, 0));
  1240.       set_program32 (addr, OR1K_TRAP_INSTR);
  1241.       put_str_packet ("OK");
  1242.      
  1243. [Caution]   Caution
  1244. The use of eval_direct32 () with second and third arguments both zero and set_program32 () is not correct, since it ignores any caching or memory management. As a result the current implementation is only correct for configurations with no instruction MMU or instruction cache.
  1245.  
  1246. 4.7.15.2.  Clearing Matchpoints
  1247. Only memory (soft) breakpoints are supported. The instruction that was substituted by l.trap is retrieved and deleted from the hash table using mp_hash_delete (). The instruction is then put back in its original location using set_program32 ().
  1248.  
  1249. mp_hash_delete () returns the struct mp_entry that was removed from the hash table. Once the instruction information has been retrieved, its memory must be returned by calling free ().
  1250.  
  1251. It is possible to receive multiple requests to delete a breakpoint if the serial connection is poor (due to retransmissions). By checking that the entry is in the hash table, actual deletion of the breakpoint and restoration of the instruction happens at most once.
  1252.  
  1253.       mpe = mp_hash_delete (type, addr);
  1254.  
  1255.       if (NULL != mpe)
  1256.         {
  1257.           set_program32 (addr, mpe->instr);
  1258.           free (mpe);
  1259.         }
  1260.  
  1261.       put_str_packet ("OK");
  1262.          
  1263. [Caution]   Caution
  1264. The use of set_program32 () is not correct, since it ignores any caching or memory management. As a result the current implementation is only correct for configurations with no instruction MMU or instruction cache.
  1265.  
  1266. Chapter 5.  Summary
  1267. This application note has described in detail the steps required to implement a RSP server for a new architecture. That process has been illustrated using the port for the OpenRISC 1000 architecture.
  1268.  
  1269. Suggestions for corrections or improvements are welcomed. Please contact the author at jeremy.bennett@embecosm.com.
  1270.  
  1271. Glossary
  1272. big endian
  1273. A description of the relationship between byte and word addressing on a computer architecture. In a big endian architecture, the least significant byte in a data word resides at the highest byte address (of the bytes in the word) in memory.
  1274.  
  1275. The alternative is little endian addressing.
  1276.  
  1277. See also little endian.
  1278.  
  1279. General Purpose Register (GPR)
  1280. In the OpenRISC 1000 architecture, one of between 16 and 32 general purpose integer registers.
  1281.  
  1282. Although these registers are general purpose, some have specific roles defined by the architecture and the ABI. GPR 0 is always 0 and should not be written to. GPR 1 is the stack pointer, GPR 2 the frame pointer and GPR 9 the return address set by l.jal (known as the link register) and l.jalr instructions. GPR 3 through GPR 8 are used to pass arguments to functions, with scalar results returned in GPR 11.
  1283.  
  1284. See also Application Binary Interface.
  1285.  
  1286. Joint Test Action Group (JTAG)
  1287. JTAG is the usual name used for the IEEE 1149.1 standard entitled Standard Test Access Port and Boundary-Scan Architecture for test access ports used for testing printed circuit boards and chips using boundary scan.
  1288.  
  1289. This standard allows external reading of state within the board or chip. It is thus a natural mechanism for debuggers to connect to embedded systems.
  1290.  
  1291. little endian
  1292. A description of the relationship between byte and word addressing on a computer architecture. In a little endian architecture, the least significant byte in a data word resides at the lowest byte address (of the bytes in the word) in memory.
  1293.  
  1294. The alternative is big endian addressing.
  1295.  
  1296. See also big endian.
  1297.  
  1298. Memory Management Unit (MMU)
  1299. A hardware component which maps virtual address references to physical memory addresses via a page lookup table. An exception handler may be required to bring non-existent memory pages into physical memory from backing storage when accessed.
  1300.  
  1301. On a Harvard architecture (i.e. with separate logical instruction and data address spaces), two MMUs are typically needed.
  1302.  
  1303. Real Time Executive for Multiprocessor Systems (RTEMS)
  1304. An operating system for real-time embedded systems offering a POSIX interface. It offers no concept of processes or memory management.
  1305.  
  1306. Special Purpose Register (SPR)
  1307. In the OpenRISC 1000 architecture, one of up to 65536 registers controlling all aspects of the processor. The registers are arranged in groups of 2048 registers. The present architecture defines 12 groups in total.
  1308.  
  1309. In general each group controls one component of the processor. Thus there is a group to control the DMMU, the IMMU, the data and instruction caches and the debug unit. Group 0 is the system group and includes all the system configuration registers, the next and previous program counters, supervision register and saved exception registers.
  1310.  
  1311. System on Chip (SoC)
  1312. A silicon chip which includes one or more processor cores.
  1313.  
  1314. References
  1315. [1] Embecosm Application Note 2. The OpenCores OpenRISC 1000 Simulator and Tool Chain: Installation Guide. Embecosm Limited, June 2008.
  1316.  
  1317. [2] Embecosm Application Note 3. Howto: Porting the GNU Debugger: Practical Experience with the OpenRISC 1000 Architecture Embecosm Limited, August 2008.
  1318.  
  1319. [3] Debugging with GDB: The GNU Source-Level Debugger, Richard Stallman, Roland Pesch, Stan Shebbs, et al, issue 9. Free Software Foundation 2008 . http://sourceware.org/gdb/current/onlinedocs/gdb_toc.html
  1320.  
  1321. [4] GDB Internals: A guide to the internals of the GNU debugger, John Gillmore and Stan Shebbs, issue 2. Cygnus Solutions 2006 . http://sourceware.org/gdb/current/onlinedocs/gdbint_toc.html
  1322.  
  1323. [5] Doxygen: Source code documentation generator tool, Dimitri van Heesch, 2008 . http://www.doxygen.org
  1324.  
  1325. [6] OpenRISC 1000 Architectural Manual, Damjan Lampret, Chen-Min Chen, Marko Mlinar, Johan Rydberg, Matan Ziv-Av, Chris Ziomkowski, Greg McGary, Bob Gardner, Rohit Mathur and Maria Bolado, November 2005 . http://www.opencores.org/cvsget.cgi/or1k/docs/openrisc_arch.pdf
  1326.  
  1327. [7] OpenRISC 1000: ORPSoC Damjan Lampret et al. OpenCores http://opencores.org/projects.cgi/web/or1k/orpsoc
  1328.  
  1329. [8] SoC Debug Interface Igor Mohor, issue 3.0. OpenCores 14 April, 2004 . http://opencores.org/cvsweb.shtml/dbg_interface/doc/DbgSupp.pdf
  1330.  
  1331. Index
  1332. Symbols
  1333. ! packet (see RSP packet types)
  1334. 7-bit clean, Overview of the Remote Serial Protocol , The load Command , Binary Data Transfer
  1335. 8-bit clean, Overview of the Remote Serial Protocol , The load Command , Binary Data Transfer
  1336. ? packet (see RSP packet types)
  1337. A
  1338. A packet (see RSP packet types)
  1339. ABI
  1340. OpenRISC 1000 (see OpenRISC 1000)
  1341. application layer (see OSI layers)
  1342. asynchronous remote debugging, Asynchronous Remote Debugging , GDB Asynchronous Remote Command Dialogs
  1343. awatch command (see GDB commands)
  1344. B
  1345. b packet (see RSP packet types)
  1346. B packet (see RSP packet types)
  1347. bare metal, The target remote Command , RSP Server Implementation Example , Unsupported Packets , Unsupported Query Packets , Queries About Threads , File Handling
  1348. binary data (see RSP packet)
  1349. BP_HARDWARE constant, The Matchpoint Hash Table
  1350. BP_MEMORY constant, The Matchpoint Hash Table , Matchpoint Handling
  1351. break command (see GDB commands)
  1352. breakpoint
  1353. hardware, The break Command
  1354. memory (software), Exception handling , Continuing , Setting Matchpoints , Clearing Matchpoints
  1355. implementation for OpenRISC 1000, OpenRISC 1000 GDB Architectural Specification
  1356. memory (software) breakpoint, The break Command
  1357. C
  1358. c packet (see RSP packet types)
  1359. C packet (see RSP packet types)
  1360. cache (see memory cache)
  1361. checksum (see RSP packet)
  1362. continue command (see GDB commands)
  1363. control-C (see interrupt)
  1364. convenience functions, Convenience Functions
  1365. binary to hex char conversion, Conversion Between Binary and Hexadecimal Characters
  1366. binary to hex char register conversion, Conversion Between Binary and Hexadecimal Character Registers , Reading All Registers
  1367. data "unescaping", Data "Unescaping"
  1368. fixed string reply packets, Convenience String Packet Output
  1369. hex char to binary conversion, Conversion Between Binary and Hexadecimal Characters
  1370. hex char to binary register conversion, Conversion Between Binary and Hexadecimal Character Registers , Writing All Registers
  1371. next program counter, Setting the Program Counter
  1372. cpu_state data structure, Global Data Structures
  1373. cpu_state.delay_insn, Setting the Program Counter
  1374. cpu_state.pc, Setting the Program Counter , Continuing
  1375. cpu_state.regs, Writing All Registers
  1376. cpu_state.sprs, Continuing , Writing All Registers , Stepping
  1377. D
  1378. D packet (see RSP packet types)
  1379. d packet (see RSP packet types)
  1380. DCFGR (see Debug Configuration Register)
  1381. DCR (see Debug Control Register)
  1382. Debug Configuration Register (see Special Purpose Register)
  1383. Debug Control Register (see Special Purpose Register)
  1384. Debug Mode Register (see Special Purpose Register)
  1385. Debug Reason Register (see Special Purpose Register)
  1386. Debug Stop Register (see Special Purpose Register)
  1387. Debug Unit, The OpenRISC 1000 Debug Unit
  1388. JTAG interface, The OpenRISC 1000 JTAG Interface
  1389. Igor Mohor version, References
  1390. ORPSoC version, References
  1391. matchpoint, The OpenRISC 1000 Debug Unit
  1392. registers (see Special Purpose Register)
  1393. watchpoint, The OpenRISC 1000 Debug Unit
  1394. watchpoint counter, The OpenRISC 1000 Debug Unit
  1395. Debug Value Register (see Special Purpose Register)
  1396. Debug Watchpoint Counter Register (see Special Purpose Register)
  1397. debug_ignore_exception function , Exception handling
  1398. decr_pc_after_break function, The break Command
  1399. deprecated packet types (see RSP packet types)
  1400. detach command (see GDB commands)
  1401. direct serial connection (see serial device connection)
  1402. disassemble command (see GDB commands)
  1403. disconnect command (see GDB commands)
  1404. DMR (see Debug Mode Register)
  1405. Doxygen, References
  1406. use with RSP server for OpenRISC 1000, Written Documentation
  1407. DRR (see Debug Reason Register)
  1408. DSR (see Debug Stop Register)
  1409. DVR (see Debug Value Register)
  1410. DWCR (see Debug Watchpoint Counter Register)
  1411. E
  1412. Embecosm, About Embecosm
  1413. endianism, Glossary
  1414. escaped characters (see RSP packet)
  1415. eval_direct32 function, Setting Matchpoints
  1416. eval_direct8 function, Reading Memory
  1417. example
  1418. stub code for RSP server (see stub code for RSP server)
  1419. exceptionHandler function (see stub code for RSP server)
  1420. EXCEPT_NONE constant, Continuing
  1421. exec_main function, Top Level Behavior , Exception handling
  1422. extended remote debugging, Putting it All Together to Build a Server , Remote Debugging in GDB , GDB Extended Remote Command Dialogs , Simple Packets , Restart the Target , Extended Debugging Support
  1423. F
  1424. F packet (see RSP packet types)
  1425. fixed response packet types for OpenRISC 1000 (see RSP packet)
  1426. flash memory, v Packets , Flash Memory
  1427. frame pointer
  1428. in OpenRISC 1000, Glossary
  1429. free function, The Matchpoint Hash Table , Clearing Matchpoints
  1430. G
  1431. g packet (see RSP packet types)
  1432. G packet (see RSP packet types)
  1433. GDB
  1434. built in variables
  1435. $pc, The OpenRISC 1000 Architecture
  1436. $ps, The OpenRISC 1000 Architecture
  1437. Internals document, References
  1438. IRC, Other Information Channels
  1439. mailing lists, Other Information Channels
  1440. porting, References
  1441. Howto, Written Documentation
  1442. register specification, OpenRISC 1000 GDB Architectural Specification , Reading All Registers , Writing All Registers
  1443. User Guide, Written Documentation , References
  1444. website, Other Information Channels
  1445. wiki, Other Information Channels
  1446. GDB architecture specification, The stepi Command , The cont Command , The break Command , OpenRISC 1000 GDB Architectural Specification
  1447. GDB commands
  1448. awatch, The watch Command
  1449. break, The break Command
  1450. continue, Implementing Server Code on the Target , Asynchronous Remote Debugging , The target remote Command , The cont Command , Top Level Behavior , Continuing , Restart the Target
  1451. detach, The detach and disconnect Commands , Simple Packets
  1452. disassemble, Examining Memory
  1453. disconnect, The detach and disconnect Commands
  1454. hbreak, The break Command
  1455. info spr, Unsupported Query Packets
  1456. load, The load Command , Binary Data Transfer
  1457. monitor, Unsupported Query Packets
  1458. print, Examining Registers
  1459. rwatch, The watch Command
  1460. spr, Unsupported Query Packets
  1461. step, Implementing Server Code on the Target , Asynchronous Remote Debugging , The target remote Command , The stepi Command , The step Command , Top Level Behavior , Continuing , Restart the Target
  1462. stepi, The stepi Command
  1463. target extended-remote , Session Layer: The Serial Connection , Putting it All Together to Build a Server , Remote Debugging in GDB , The target extended-remote Command
  1464. target remote, Session Layer: The Serial Connection , Putting it All Together to Build a Server , Remote Debugging in GDB , The target remote Command
  1465. watch, The watch Command
  1466. gdbarch_single_step_through_delay function , The stepi Command , The cont Command
  1467. gdbserver, Putting it All Together to Build a Server , Using gdbserver
  1468. GDB_BUF_MAX constant, Query About Supported Functionality
  1469. General Purpose Register, The OpenRISC 1000 Architecture , Glossary
  1470. getDebugChar function (see stub code for RSP server)
  1471. get_packet function, Getting Packets , High Level Protocol Implementation
  1472. get_rsp_char function, Character Input , Sending Packets
  1473. GPRs (see General Purpose Register)
  1474. H
  1475. H packet (see RSP packet types)
  1476. handle_rsp function, External Code Interface , Top Level Behavior , Exception handling , Establishing the Server Listener Socket , Establishing the Client Connection , Communicating with the Client , High Level Protocol Implementation , Continuing
  1477. hardware breakpoint (see breakpoint)
  1478. Harvard architecture, Glossary
  1479. hbreak command (see GDB commands)
  1480. hex2reg function, Conversion Between Binary and Hexadecimal Character Registers , Writing All Registers
  1481. hexchars array, Conversion Between Binary and Hexadecimal Characters
  1482. I
  1483. i packet (see RSP packet types)
  1484. I packet (see RSP packet types)
  1485. interrupt
  1486. from client to server, Interrupt , Implementing Server Code on the Target , Top Level Behavior
  1487. IRC (see GDB)
  1488. J
  1489. JTAG, Glossary (see Debug Unit)
  1490. supporting with RSP server, Implementing a Custom Server for JTAG
  1491. K
  1492. k packet (see RSP packet types)
  1493. L
  1494. listen function, Establishing the Server Listener Socket
  1495. load command (see GDB commands)
  1496. M
  1497. m packet (see RSP packet types)
  1498. M packet (see RSP packet types)
  1499. mailing lists (see GDB)
  1500. matchpoint, The OpenRISC 1000 Debug Unit , Matchpoint Handling
  1501. (see also Debug Unit)
  1502. clearing for OpenRISC 1000, Clearing Matchpoints
  1503. setting for OpenRISC 1000, Setting Matchpoints
  1504. types for OpenRISC 1000, The Matchpoint Hash Table , Matchpoint Handling
  1505. memory (software) breakpoint (see breakpoint)
  1506. memory cache
  1507. limitations with access for OpenRISC 1000, Reading Memory , Writing Memory , Binary Data Transfer , Setting Matchpoints , Clearing Matchpoints
  1508. memory management unit
  1509. limitations with access for OpenRISC 1000, Reading Memory , Writing Memory , Binary Data Transfer , Setting Matchpoints , Clearing Matchpoints
  1510. MMU (see memory management unit)
  1511. mp_entry data structure, The Matchpoint Hash Table , Matchpoint Handling , Clearing Matchpoints
  1512. mp_hash_add function, The Matchpoint Hash Table , Matchpoint Handling , Setting Matchpoints
  1513. mp_hash_delete function, The Matchpoint Hash Table , Matchpoint Handling , Clearing Matchpoints
  1514. mp_hash_init function, The Matchpoint Hash Table , Matchpoint Handling
  1515. mp_hash_lookup function, The Matchpoint Hash Table , Matchpoint Handling
  1516. MP_HASH_SIZE constant, The Matchpoint Hash Table
  1517. N
  1518. Nagel's algorithm, Establishing the Client Connection
  1519. non-blocking connection, Establishing the Client Connection
  1520. non-stop execution, Asynchronous Remote Debugging , v Packets , Non-stop Support
  1521. O
  1522. OpenRISC 1000
  1523. ABI, OpenRISC 1000 GDB Architectural Specification
  1524. argument passing, Application Binary Interface (ABI)
  1525. result return register, Application Binary Interface (ABI)
  1526. stack frame alignment, Application Binary Interface (ABI)
  1527. variations from documented standard, Application Binary Interface (ABI)
  1528. architecture, The OpenRISC 1000 Architecture
  1529. GPRs (see General Purpose Register)
  1530. main memory, The OpenRISC 1000 Architecture
  1531. manual, References
  1532. SPRs (see Special Purpose Register)
  1533. link register, Glossary
  1534. tool chain, References
  1535. OpenRISC 1000 example, Rationale
  1536. Or1ksim, Or1ksim: the OpenRISC 1000 Architectural Simulator
  1537. or1ksim-rsp TCP/IP service , Establishing the Server Listener Socket
  1538. OR1K_TRAP_INSTR constant, Setting Matchpoints
  1539. OSI layers, Overview of the Remote Serial Protocol
  1540. application layer, Application Layer: Remote Serial Protocol
  1541. presentation layer, Presentation Layer: Packet Transfer
  1542. session layer, Session Layer: The Serial Connection
  1543. P
  1544. p packet (see RSP packet types)
  1545. P packet (see RSP packet types)
  1546. packet (see RSP packet)
  1547. data structure for OpenRISC 1000 (see RSP packet)
  1548. packet acknowledgment (see RSP packet)
  1549. packet format (see RSP packet)
  1550. pc_next variable, Setting the Program Counter
  1551. pipe connection, Overview of the Remote Serial Protocol , Session Layer: The Serial Connection , Implementing a Custom Server for JTAG
  1552. presentation layer (see OSI layers)
  1553. program counter
  1554. as Special Purpose Register, The OpenRISC 1000 Architecture
  1555. putDebugChar function (see stub code for RSP server)
  1556. put_packet function, Sending Packets , Convenience String Packet Output , Conversion Between Binary and Hexadecimal Characters
  1557. put_rsp_char function, Getting Packets , Character Output
  1558. put_str_packet function, Convenience String Packet Output , Conversion Between Binary and Hexadecimal Characters , Extended Debugging Support , Setting Matchpoints , Clearing Matchpoints
  1559. Q
  1560. qC packet (see RSP packet types)
  1561. qCRC packet (see RSP packet types)
  1562. QFrame packet (see RSP packet types)
  1563. qfThreadInfo packet (see RSP packet types)
  1564. qGetTLSAddr packet (see RSP packet types)
  1565. qOffsets packet (see RSP packet types)
  1566. QPassSignals packet (see RSP packet types)
  1567. qRcmd packet (see RSP packet types)
  1568. qsThreadInfo packet (see RSP packet types)
  1569. qSupported packet (see RSP packet types)
  1570. qSymbol packet (see RSP packet types)
  1571. QTDP packet (see RSP packet types)
  1572. qThreadExtraInfo packet (see RSP packet types)
  1573. QTinit packet (see RSP packet types)
  1574. QTro packet (see RSP packet types)
  1575. QTStart packet (see RSP packet types)
  1576. QTStop packet (see RSP packet types)
  1577. qXfer packet (see RSP packet types)
  1578. R
  1579. R packet, Extended Debugging Support (see RSP packet types)
  1580. r packet (see RSP packet types)
  1581. readspr, Unsupported Query Packets
  1582. reg2hex function, Conversion Between Binary and Hexadecimal Character Registers , Reading All Registers
  1583. reply packet (see RSP packet)
  1584. resp_insert_matchpoint function , Matchpoint Handling
  1585. resp_remove_matchpoint function , Matchpoint Handling
  1586. rsp data structure, Global Data Structures
  1587. (see also RSP server for OpenRISC 1000)
  1588. rsp.client_fd, Global Data Structures, Establishing the Client Connection , Character Input , Simple Packets
  1589. rsp.client_waiting , Global Data Structures, Continuing
  1590. rsp.mp_hash , Global Data Structures, Matchpoint Handling
  1591. rsp.proto_num , Global Data Structures
  1592. rsp.server_fd , Global Data Structures, Establishing the Server Listener Socket
  1593. rsp.sigval , Global Data Structures, Exception handling , Reporting the Last Exception
  1594. rsp.start_addr , Global Data Structures, Restart the Target
  1595. RSP GDB command dialogs
  1596. awatch, The watch Command
  1597. break, The break Command
  1598. continue, The cont Command
  1599. detach, The detach and disconnect Commands
  1600. disassemble, Examining Memory
  1601. disconnect, The detach and disconnect Commands
  1602. hbreak, The break Command
  1603. load, The load Command
  1604. rwatch, The watch Command
  1605. step, The step Command
  1606. stepi, The stepi Command
  1607. target extended-remote , The target extended-remote Command
  1608. target remote, The target remote Command
  1609. watch, The watch Command
  1610. RSP packet
  1611. acknowledgment, Packet Acknowledgment , Getting Packets , Sending Packets
  1612. binary data, Presentation Layer: Packet Transfer , The load Command , Binary Data Transfer
  1613. checksum, Presentation Layer: Packet Transfer , Getting Packets , Sending Packets
  1614. data structure for OpenRISC 1000, Packet Representation
  1615. deprecated packets, Deprecated Query Packets
  1616. error handling, Getting Packets , Sending Packets , Reading Memory , Writing Memory , Unsupported Query Packets , Flash Memory , Binary Data Transfer , Clearing Matchpoints
  1617. escaped characters, Presentation Layer: Packet Transfer , Binary Data Transfer
  1618. fixed response for OpenRISC 1000, Simple Packets
  1619. format, Presentation Layer: Packet Transfer , Getting Packets
  1620. maximum size, Query About Supported Functionality
  1621. reply packet, Presentation Layer: Packet Transfer
  1622. run-length encoding, Presentation Layer: Packet Transfer
  1623. types (see RSP packet types)
  1624. RSP packet types
  1625. ! packet, Extended Remote Debugging , The target extended-remote Command , Simple Packets
  1626. ? packet, Standard Remote Debugging , The target remote Command , Reporting the Last Exception
  1627. A packet, Unsupported Packets
  1628. b packet, Deprecated Packets
  1629. B packet, Deprecated Packets
  1630. c packet, Implementing Server Code on the Target , Standard Remote Debugging , The stepi Command , The cont Command , The break Command , Continuing , Stepping , Non-stop Support
  1631. C packet, Implementing Server Code on the Target , Standard Remote Debugging , The stepi Command , Unsupported Packets , Continuing
  1632. D packet, Standard Remote Debugging , The detach and disconnect Commands , Simple Packets
  1633. d packet, Deprecated Packets
  1634. deprecated packets, Application Layer: Remote Serial Protocol , Deprecated Packets
  1635. F packet, Unsupported Packets
  1636. g packet, Standard Remote Debugging , The target remote Command , The stepi Command , The step Command , The cont Command , The break Command , Reading and Writing All Registers
  1637. G packet, Standard Remote Debugging , Reading and Writing All Registers
  1638. H packet, Standard Remote Debugging , Asynchronous Remote Debugging , The target remote Command , The stepi Command , The step Command , The cont Command , Simple Packets
  1639. i packet, Implementing Server Code on the Target , Unsupported Packets
  1640. I packet, Implementing Server Code on the Target , Unsupported Packets
  1641. k packet, Standard Remote Debugging , Simple Packets
  1642. m packet, Standard Remote Debugging , Examining Memory , The stepi Command , The step Command , The cont Command , The break Command , Reading and Writing Memory , Reading Memory
  1643. M packet, Standard Remote Debugging , The load Command , Reading and Writing Memory , Writing Memory , Binary Data Transfer
  1644. p packet, Standard Remote Debugging , Reading and Writing Individual Registers
  1645. P packet, Standard Remote Debugging , The load Command , The break Command , Reading and Writing Individual Registers
  1646. q packets, Query Packets
  1647. deprecated query packets, Deprecated Query Packets
  1648. qC packet, Standard Remote Debugging , The target remote Command , Deprecated Query Packets , Queries About Threads
  1649. qCRC packet, Unsupported Query Packets
  1650. qfThreadInfo packet, Asynchronous Remote Debugging , Deprecated Query Packets , Queries About Threads
  1651. qGetTLSAddr packet, Deprecated Query Packets , Unsupported Query Packets
  1652. qL packet, Deprecated Query Packets
  1653. qOffsets packet, Standard Remote Debugging , The target remote Command , Query About Executable Relocation
  1654. qP packet, Deprecated Query Packets
  1655. qRcmd packet, Unsupported Query Packets
  1656. qsThreadInfo packet, Asynchronous Remote Debugging , Deprecated Query Packets , Queries About Threads
  1657. qSupported packet, Standard Remote Debugging , The target remote Command , Unsupported Query Packets , Query About Supported Functionality , Set Packets
  1658. qSymbol packet, Standard Remote Debugging , The target remote Command , Query About Symbol Table Data
  1659. qThreadExtraInfo packet, Asynchronous Remote Debugging , Deprecated Query Packets , Queries About Threads
  1660. qXfer packet, Unsupported Query Packets , Query About Supported Functionality
  1661. unsupported for OpenRISC 1000, Unsupported Query Packets
  1662. Q packets, Set Packets
  1663. QFrame packet, Tracepoint Packets
  1664. QPassSignals packet, Query About Supported Functionality , Set Packets
  1665. QTDP packet, Tracepoint Packets
  1666. QTinit packet, Tracepoint Packets
  1667. QTro packet, Tracepoint Packets
  1668. QTStart packet, Tracepoint Packets
  1669. QTStop packet, Tracepoint Packets
  1670. unsupported for OpenRISC 1000, Tracepoint Packets
  1671. R packet, Extended Remote Debugging , Restart the Target
  1672. r packet, Deprecated Packets
  1673. requiring no acknowledgment, Application Layer: Remote Serial Protocol
  1674. requiring simple acknowledgment, Application Layer: Remote Serial Protocol
  1675. returning data or error, Application Layer: Remote Serial Protocol
  1676. s packet, Implementing Server Code on the Target , Standard Remote Debugging , The stepi Command , The step Command , The cont Command , Stepping , Non-stop Support
  1677. S packet, Implementing Server Code on the Target , Standard Remote Debugging , The stepi Command , Unsupported Packets
  1678. T packet, Asynchronous Remote Debugging , Simple Packets
  1679. t packet, Unsupported Packets
  1680. unsupported for OpenRISC 1000, Unsupported Query Packets
  1681. unsupported for OpenRISC 1000, Unsupported Packets , Tracepoint Packets , Non-stop Support , File Handling , Flash Memory
  1682. v packets, v Packets
  1683. unsupported for OpenRISC 1000, Non-stop Support , File Handling , Flash Memory
  1684. vAttach packet, Extended Remote Debugging , Extended Debugging Support
  1685. vCont packet, Asynchronous Remote Debugging , The stepi Command , Non-stop Support
  1686. vCont? packet, Standard Remote Debugging , The stepi Command , The step Command , The cont Command , Non-stop Support
  1687. vFile packet, File Handling
  1688. vFlashDone packet, Flash Memory
  1689. vFlashErase packet, Flash Memory
  1690. vFlashWrite packet, Flash Memory
  1691. vRun packet, Extended Remote Debugging , Extended Debugging Support
  1692. X packet, Standard Remote Debugging , The load Command , Binary Data Transfer
  1693. z packets, Standard Remote Debugging , The break Command , Matchpoint Handling
  1694. z0 packet (memory breakpoint) , The break Command , Matchpoint Handling
  1695. z1 packet (memory breakpoint) , The break Command
  1696. z2 packet (write watchpoint) , The watch Command
  1697. z3 packet (read watchpoint) , The watch Command
  1698. z4 packet (access watchpoint) , The watch Command
  1699. Z packets, Standard Remote Debugging , The break Command , Matchpoint Handling
  1700. Z0 packet (memory breakpoint) , The break Command , Matchpoint Handling
  1701. Z1 packet (memory breakpoint) , The break Command
  1702. Z2 packet (write watchpoint) , The watch Command
  1703. Z3 packet (read watchpoint) , The watch Command
  1704. Z4 packet (access watchpoint) , The watch Command
  1705. RSP server for OpenRISC 1000
  1706. external code interface, External Code Interface
  1707. global data structures, Global Data Structures
  1708. rsp data structure, Global Data Structures
  1709. initialization, Top Level Behavior
  1710. location of source code, Overview of the RSP Server Implementation
  1711. matchpoint hash table, Global Data Structures, The Matchpoint Hash Table
  1712. RSP stop packet types, Extended Debugging Support
  1713. S stop packet, The target remote Command , The stepi Command , The step Command , The cont Command , The break Command , Reporting the Last Exception
  1714. Sstop packet, Extended Debugging Support
  1715. T stop packet, Asynchronous Remote Debugging
  1716. W stop packet, The target remote Command
  1717. X stop packet, The target remote Command
  1718. rsp_buf data structure, Packet Representation , Sending Packets
  1719. rsp_client_request function, Communicating with the Client , High Level Protocol Implementation
  1720. rsp_continue function, Continuing
  1721. rsp_continue_generic function, Continuing
  1722. rsp_exception function, External Code Interface , Exception handling
  1723. rsp_init function, External Code Interface , Top Level Behavior , Establishing the Server Listener Socket
  1724. rsp_query function, Query Packets
  1725. rsp_read_all_regs function, Reading and Writing All Registers , Reading and Writing Individual Registers
  1726. rsp_read_mem function, Reading and Writing Memory , Reading Memory
  1727. rsp_read_reg function, Reading and Writing Individual Registers
  1728. rsp_report_exception function, Reporting the Last Exception
  1729. rsp_restart function, Restart the Target
  1730. rsp_server_request function, Establishing the Client Connection
  1731. rsp_set function, Set Packets
  1732. rsp_step function, Stepping
  1733. rsp_step_generic function, Stepping
  1734. rsp_unescape function, Data "Unescaping"
  1735. rsp_vpkt function, v Packets
  1736. rsp_write_all_regs function, Reading and Writing All Registers , Reading and Writing Individual Registers
  1737. rsp_write_mem function, Reading and Writing Memory , Writing Memory
  1738. rsp_write_mem_bin function, Binary Data Transfer
  1739. rsp_write_reg function, Reading and Writing Individual Registers
  1740. run-length encoding (see RSP packet)
  1741. rwatch command (see GDB commands)
  1742. S
  1743. s packet (see RSP packet types)
  1744. S packet (see RSP packet types)
  1745. S stop packet (see RSP stop packet types)
  1746. serial device connection, Overview of the Remote Serial Protocol , Session Layer: The Serial Connection
  1747. server stub code (see for RSP)
  1748. session layer (see OSI layers)
  1749. set_npc function, Setting the Program Counter , Continuing , Writing All Registers , Restart the Target
  1750. set_program32 function, Setting Matchpoints , Clearing Matchpoints
  1751. set_program8 function, Writing Memory , Binary Data Transfer
  1752. set_stall_state function, Simple Packets , Continuing
  1753. SIGIO signal, Top Level Behavior
  1754. simulator
  1755. connecting via RSP, Implementing Server Code for Simulators
  1756. sim_init function, Top Level Behavior
  1757. software (memory) breakpoint (see breakpoint)
  1758. Special Purpose Register, The OpenRISC 1000 Architecture , Glossary
  1759. configuration registers
  1760. CPU Configuration Register , The OpenRISC 1000 Architecture
  1761. Debug Configuration Register , The OpenRISC 1000 Architecture
  1762. Unit Present Register , The OpenRISC 1000 Architecture
  1763. Debug Unit
  1764. Debug Control Registers , The OpenRISC 1000 Debug Unit
  1765. Debug Mode Registers , The OpenRISC 1000 Debug Unit , Continuing , Stepping
  1766. Debug Reason Register , The OpenRISC 1000 Debug Unit , Continuing
  1767. Debug Stop Register , The OpenRISC 1000 Debug Unit , Exception handling , Continuing
  1768. Debug Value Registers , The OpenRISC 1000 Debug Unit
  1769. Debug Watchpoint Counter Registers , The OpenRISC 1000 Debug Unit
  1770. program counters
  1771. Next Program Counter, The OpenRISC 1000 Architecture
  1772. Previous Program Counter, The OpenRISC 1000 Architecture
  1773. Supervision Register, The OpenRISC 1000 Architecture
  1774. SPRs (see Special Purpose Register)
  1775. SR (see Supervision Register)
  1776. sscanf function, Continuing , Reading Memory
  1777. stack frame
  1778. alignment
  1779. for OpenRISC 1000, Application Binary Interface (ABI)
  1780. stack pointer
  1781. in OpenRISC 1000, Glossary
  1782. step command (see GDB commands)
  1783. stepi command (see GDB commands)
  1784. struct rsp_buf data structure , Convenience String Packet Output , Conversion Between Binary and Hexadecimal Characters
  1785. stub code for RSP server, Rationale , Implementing Server Code on the Target
  1786. exceptionHandler, Implementing Server Code on the Target
  1787. getDebugChar, Implementing Server Code on the Target
  1788. limitations, Implementing Server Code on the Target
  1789. putDebugChar, Implementing Server Code on the Target
  1790. Supervision Register (see Special Purpose Register )
  1791. T
  1792. T packet (see RSP packet types)
  1793. T stop packet (see RSP stop packet types)
  1794. target extended-remote command (see GDB commands)
  1795. target remote command (see GDB commands)
  1796. TCP/IP connection, Overview of the Remote Serial Protocol , Session Layer: The Serial Connection , Establishing the Server Listener Socket
  1797. or1ksim-rsp service, Establishing the Server Listener Socket
  1798. TRAP exception, Exception handling , Continuing , Stepping , Extended Debugging Support
  1799. using l.trap for OpenRISC 1000, Matchpoint Handling , Setting Matchpoints , Clearing Matchpoints
  1800. U
  1801. UDP/IP connection, Overview of the Remote Serial Protocol , Session Layer: The Serial Connection
  1802. unsupported packet types for OpenRISC 1000 (see RSP packet types)
  1803. V
  1804. vAttach packet (see RSP packet types)
  1805. vCont packet (see RSP packet types)
  1806. vCont? packet (see RSP packet types)
  1807. verify_memoryarea function, Reading Memory , Writing Memory , Binary Data Transfer
  1808. vRun packet (see RSP packet types)
  1809. W
  1810. W stop packet (see RSP stop packet types)
  1811. watch command (see GDB commands)
  1812. watchpoint
  1813. in OpenRISC 1000 (see Debug Unit)
  1814. software, The watch Command
  1815. website (see GDB)
  1816. wiki (see GDB)
  1817. WP_ACCESS constant, The Matchpoint Hash Table
  1818. WP_READ constant, The Matchpoint Hash Table
  1819. WP_WRITE constant, The Matchpoint Hash Table
  1820. writespr, Unsupported Query Packets
  1821. X
  1822. X packet (see RSP packet types)
  1823. X stop packet (see RSP stop packet types)
  1824. Z
  1825. z packets (see RSP packet types)
  1826. Z packe

Raw Paste


Login or Register to edit or fork this paste. It's free.