Apparatus and method for providing a wait for status change capability for a host computer system

[0002] 1. Field of the Invention

[0003] This invention relates to debugging a computer system and software functions associated therewith.

[0004] 2. Description of the Related Art

[0005] The time and cost of developing and debugging new hardware and software products is a significant factor in product development. A capable and cost efficient debug environment can decrease the cost and time to bring a new product to market. The need to provide software debug support is particularly acute within the embedded products industry, where specialized on-chip circuitry is often combined with a processor core.

[0006] Logic analyzers, read-only memory (ROM) emulators and in-circuit emulators (ICE) have commonly been used to help provide debug support. In-circuit emulators do provide certain advantages over other debug environments, offering complete control and visibility over memory and register contents, as well as overlay and trace memory in case system memory is insufficient. Use of traditional in-circuit emulators, which involves interfacing a custom emulator back-end with a processor socket to allow communication between emulation equipment and the target system, is becoming increasingly difficult and expensive in today's age of exotic packages and shrinking product life cycles.

[0007] A variety of hardware solutions with varying on-chip debug capability through various debug ports are being provided by the various processor manufacturers. Some advanced processors multiplex debug pins in time. In such processors, the address bus is used to report software trace information during a BTA-(Branch Target Address) cycle.

[0008] A common approach is to use a serial interface such as provided by IEEE 1149.1 (Joint Test Action Group (JTAG)), for providing debug support. In such an approach, the debug hardware provided on chip communicates with a host debug computer through the JTAG port.

[0009] In the “background Debug Mode” by Motorola, Inc. limited on-chip debug circuitry is provided for basic run control. Through a dedicated serial link requiring additional pins, a debugger can start and stop the target system and apply basic code breakpoints by inserting special instructions in system memory. Once halted, special commands are used to inspect memory variables and register contents.

[0010] Thus, the debug tool manufacturers are faced with a wide variety of processor and hardware debug approaches that they are required to support. Typically a common core debug capability is shared among the various approaches, particularly among product offerings from the same manufacturer. For instance, many debug tools support the capability to start and stop the processor, read and write to various storage locations within the processor and/or target system and to set breakpoints. However, every time a new or modified debug port is provided on a processor, new software has to be generated by the debug tool vendors to support the new or modified ports. It would be desirable to limit the amount of new software that has to be generated by the debug tool vendors in response to enhancements or changes to debug hardware on target microprocessors. In addition, it would be desirable to standardize software interfaces as much as possible in order to help achieve that goal.

[0011] Accordingly, the invention provides for a standard procedural interface operating on a host computer. In one embodiment the invention provides a host computer system for operating in a debug environment that includes a target computer system coupled to the host computer system. The host computer system includes a status register which can be interrogated. A programming interface encoded in computer readable media and executable on the host computer system, provides at least one callable function that determines whether a value of a selected bit or bits of the status register have changed from a predetermined state. The called function returns to a calling function in response to the change in value of the selected bit or bits. Otherwise, the called function waits for the change in value of the bit(s). In one embodiment, the status register includes at least one status bit that indicates a state of the target computer system and a status bit that indicates a state of the host computer system.

[0012] In another embodiment, the invention provides a method for detecting and indicating a status in a computer system debug environment that includes a target computer system and a host computer system. The method includes calling a function on the host computer. The function evaluates whether a state represented in a status register in the host computer has changed from a predetermined state. If the state represented in the status register has changed from the predetermined state, the method returns from the called function and if not, the function waits for the change in state.

[0013] The present invention may be better understood, and its numerous objects, features, and advantages made apparent to those skilled in the art by referencing the accompanying drawings.

[0014] FIG. 1 is a block diagram of a target and host computer system in a debug environment.

[0015] FIG. 2 illustrates operation of a List( ) function according to one embodiment of the invention.

[0016] FIG. 3 illustrates operation of a ReadList( ) function according to one embodiment of the invention.

[0017] FIG. 4 is a flow diagram illustrating a wait function according to one embodiment of the invention. Note that the use of the same reference symbols in different drawings indicates similar or identical items.

[0018] As discussed, different processor manufacturers implement their implement their debug port differently for various reasons. However, the differences in port implementation may be hidden behind a procedural interface layer which is used by tools driving the debug connection between the target processor and the host debug computer.

[0019] FIG. 1 shows the major software and hardware blocks of a debug environment implementing an embodiment of the present invention. Target processor 10 is coupled to the host computer system 12 via bus 14. Bus 14 may be any of a variety of buses. For example, bus 14 may be implemented in accordance with IEEE 1149.1 (JTAG) or variations thereof. Note that the processor that comprises target processor 10 can vary, particularly in the areas of on-chip registers and breakpoint control mechanisms. Target computer system 18 may be a single integrated circuit such as may be found in embedded processor applications or may include multiple integrated circuits including processor, memory and other integrated circuits.

[0020] The present invention defines a low-level procedural interface 16 for the services provided by the lower level functions 17 implementing a debug driver. The low level services described herein are implemented by a group of functions which together provide a software debug driver. By agreeing on a standard procedural interface for controlling the host debug port 19, tool development complexity and costs can be reduced.

[0021] However, implementation details of lower level services can vary according to specific processor implementation and target hardware debug port implementation. For example, if a JTAG port is the debug port that is available on a particular processor, the low level routines that actually toggle the JTAG lines appropriately to read and write information to the JTAG port on the target system will differ from the routines that are provided if a more robust debug port is provided on the target system. An exemplary target debug port is described in “Debug Interface Including a Compact Trace Record Storage”, application Ser. No. 08/992,361, filed Dec. 17, 1997, naming Daniel Mann as an inventor, which is incorporated herein by reference. However, the procedural interface described does not have to change according to each change in implementation of debug hardware on the target processor. For those systems that have more advanced ports, the procedural calls described herein may end up running more efficiently.

[0022] As is known in the art, execution of a computer process involves a calling hierarchy of proceedings, functions, routines or methods. Although the terms procedure, function, routine and method may have distinct meanings in other contexts, e.g., the particular programming environment being utilized, for purposes of this description, groups of software instructions which may be called or invoked are generally referred to herein as functions without loss of generality. Table 1 describes an exemplary group of functions which provide a set of functions operable in the host computer to support target services.

[0023] The various functions in table 1 are described in more detail below. The notation <in> refers to a parameter passed to the service routine, and <out> refers to an output value, that is a pointer which will be referenced to obtain a memory location updated by the successful completion of the service routine. Passing output parameters by reference is exemplary and other approaches to pass parameters (e.g. by value) are known in the art and also within the scope of this invention. The commands grouped under the type “kernel debug” are used when the processor is not running; that is, when kernel mode debugging is being performed. The “kernel debug” and “kernel run control” commands are issued to a stopped processor. The other commands provide for run-time communication with the target, and control of the host debug system.

[0024] A debug service may return an error code. Each service returns an enumerated value of type return_error_t. An exemplary corresponding enumeration is shown below:

[0025] It is often more convenient to have a text string describing an error, rather than a simple error code number. The Error( ) routine returns a string describing the error number passed. The ErrorString parameter points to a pointer which will be set to the address of the selected character string.

[0026] The Attach( ) function establishes a connection with the target processor. In an x86 debug environment, the target x86 processor always runs in little-endian, but the host processor may run in big-endian or little-endian. If the host wishes data structures passed to this driver to be converted from little-endian to big-endian, it may set the <HostEndian> parameter to non zero.

[0027] return_error_t Attach(INT32 HostEndian) <in>

[0028] The Read( ) function reads target and system resource into a buffer in the host system known as the object array. The data takes the form of objects of size ObjectSize bytes. They could be read from contiguous memory, register or other address space. The number of objects read is given by ObjectCount.

[0029] An exemplary Read( ) call is shown below:

[0030] The selected target space, starting at address TargetAddress, is read into the host buffer pointed to by pBuffer.

[0031] The TargetSpace parameter selects the target address space. Each processor has an enumerated list of address spaces, such as memory, register, I/O, cache and more. It is up to the function caller to be aware of the space enumerations applicable for the target processor in use.

[0032] For example, target space may be

[0033] 0=physical memory space

[0034] 1=I/O space

[0035] 2=registers

[0036] 3=serial communication parameters

[0037] 4=raw trace data

[0038] 5=unused

[0039] It may be assumed in certain embodiments that the calling function is aware of any address boundary limitations which apply to reading objects from target memory in order to simplify the function. If that is the case, access violations or alignment faults which occur will not be dealt with by the Read( ) function and may not be reported. Zero is returned on normal completion. If an error is detected, then a non-zero error number is returned. A more complex implementation may account for access violation or alignment faults in a variety of target processors.

[0040] The serial communication parameters space ID can be used to obtain information about host buffers utilized by the Send( ) and Receive( ) routines. A transmit (TX) buffer in the host may be used to store data transmitted by the target processor to the host. A receive (RX) buffer may be used by the host to store data to be received by the target processor. The size of the buffers may be e.g., 4K. Other sizes are of course possible and will depend on implementation details of particular host systems. When this space ID is used, an array of four 32-bit objects are returned:

[0041] space available in RX buffer

[0042] size of RX buffer

[0043] unused space in TX buffer

[0044] size of TX buffer.

[0045] The function Write( ) is the reverse of Read( ), it moves an array of objects into the target processor or system from the memory buffer pointed to by pbuffer. No attempt is made to verify the data is successfully written.

[0046] An exemplary Write( ) call is shown below

[0047] Another exemplary TargetSpace parameter, which may be local to a particular function, may be used to indicate the target address space as follows:

[0048] 0=physical memory space

[0049] 1=I/O space

[0050] 2=register

[0051] 3=not used

[0052] After a Write( ) has been used, the Verify( ) function can verify the write was successful. The same pBuffer supplied to Write( ) is provided again. This time the target data is read and confirmed with the pBuffer data. If they match, zero is returned.

[0053] An exemplary Verify call is shown below

[0054] The TargetSpace parameter may indicate target space as follows

[0055] When the same data value must be written to target memory (or other address space), the Fill( ) function rather than Write( ) can be used. In that case only a single data object is provided in place of the array of objects pointed to by pbuffer. That can be very useful when writing zero or FF . . . FF to memory. An exemplary Fill( ) call is shown below:

[0056] The Move( ) function copies data from one location to another within the same target space. As with other Debug functions, Object size is in bytes and ObjectCount determines the number of objects copied. An exemplary Move( ) call is shown below:

[0057] When execution stops, it is frequently necessary to examine a recurring set of target resources; such as the program counter, status register and the like. One way to do this is to first program a list of desired resources using the function List( ). The passed parameter p TargetList points to a data structure having entries describing target resources, in the form shown below:

[0058] The number of entries in the data structure is given by ObjectCount. The List function can copy the array (list) into a location which can be accessed when ReadList( ) is called. Referring to FIG. 2, an exemplary list is shown at 201 having n elements in the data structure, with each element including a space, address and size parameter. The size of the list n is given by ObjectCount. The List( ) function moves the data structure at 201, which may be created interactively on the screen, to the data structure stored at 203 which is accessible by the ReadList( ) function. An exemplary List( ) call is shown below.

[0059] The list can be changed at any time by making a call to List( ) and presenting a new list of resources. A list typically contains a list of target registers which are examined at each processor halt, such as the program counter and breakpoint control registers. Note that various embodiments are possible with the ReadList( ) function. For instance, while the whole list may be copied over, in another embodiment, a target resource could be added to the data structure at 203 by invoking List( ). In that way, the list could be “grown” one target resource at a time. In another embodiment, multiple lists may be maintained.

[0060] A call to the function ReadList( ) fills the buffer pointed to by pBuffer with target resource information which was previously selected and is stored in 203. Any target resource can be examined, and in any prescribed sequence. An exemplary ReadList( ) call is shown below:

[0061] return_error_t ReadList (object_list₁₃t pBuffer[ ]) <in>

[0062] FIG. 3 illustrates the operation of the ReadList( ) function. Assume the size of the list is passed as a parameter or available as a global parameter. The count value, used as the loop counter, is initialized to zero in 301. An access operation is performed in 303 (such as a read operation) using the information contained in one element of the list pointed to by listpointer. The accessed data is stored at a location pointed to by the buffer pointer in 305. The count is incremented in 307 and compared to determine if the end of the list has been reached in 309. If not, the access command accesses the next target resource identified in the list. Note that if multiple lists are maintained, e.g., when using multiple breakpoints, the function also has to be told which list to traverse. Thus, the use of the ReadList( ) function in conjunction with the List( ) function provides a useful way to access target resources.

[0063] When a processor is halted, execution can be restarted by calling the function Go( ). The processor may continue to run until an event causing it to re-enter debug mode is encountered. The Go( ) function returns after starting processor execution. It does not wait to return after execution possibly stops at some time in the future.

[0064] return_error_t Go( )

[0065] Most processors are equipped with some means of single-stepping an assembly-level instruction. A call to the function Step( ) initiates a single-step, and the function returns immediately. With some processors, a single-step may cause the execution of emulation routines or other support software, which is target dependant. Consequently, the address where the processor next stops can not always be assumed from the address in use when the single-step order was issued. An exemplary Step call is shown below:

[0066] return_error_t Step(INT32 StepCount) <in>

[0067] The Version( ) function obtains software driver information as well as hardware identification information. For example, SwVersion and HwVersion maybe 32-bit values divided into 3 fields. SwVersion, (16-bit Software provider ID)(8-bit major number)(8-bit minor number) and HwVersion, (16-bit Hardware provider ID)(8-bit major number)(8-bit minor number). An exemplary Version( ) call is shown below:

[0068] Calling the Break( ) function causes processor execution to be immediately (or as quickly as possible) stopped. The processor may enter a debug mode state and await kernel mode debug commands. An exemplary Break( ) call is shown below:

[0069] return_error_t Break( )

[0070] The Reset( ) function activates a processor or system reset. An enumerated parameter <Type> can be used to select the desired reset operation. If the processor is already halted in Debug mode when reset is requested, the processor may immediately reenter Debug mode after the processor reset sequence is performed.

[0071] A processor which is running while a reset is requested, may reset and then continue running unless the enter-debug-mode-on-reset option has been selected by the processor. An exemplary Reset( ) call is shown below:

[0072] return_error_t Reset(INT32 Type) <in>

[0073] The Status( ) function provides the content of a status register 20 (see FIG. 1), which in one embodiment is a 32-bit status word. The term status register is a term intended to cover a memory location of any appropriate number of bits or bytes as is appropriate for any particular host system. In one embodiment the upper 16 bits are debug driver and processor dependent. The lower 16-bits may be reserved. The Status( ) function can preferably be called at any time without stopping target execution. Depending on the processor state, several status bits may be set at the same time. Seven exemplary status bits are shown below which are processor and debug driver independent. Other status bits in other implementations may of course be utilized.

[0074] The (R/S) bit indicates if the processor is currently running or not. The RX bit indicates that the buffer holding data to be sent to the target via the Send( ) command is full. The TX bit indicates that the processor has transmitted data to the host and it should be collected via a call to Receive( ). Thus, the status register can include status information of both the host system and the target system. An exemplary call is shown below:

[0075] return_error_t Status(UINT32 *status) <out>

[0076] The Wait( ) function has similarities to the Status( ) function. One difference is that the Wait( ) may not return immediately. A wait-test condition is verified before the function returns. The call to the Wait( ) function passes a parameter containing a predetermined compare value along with a Mask parameter. The wait-test operates as illustrated in FIG. 4. Once the function is called, the function compares the current value of the status register to the compare value in 401 to see if any bits have changed. The predetermined value may be, e.g., an old value of the status register. The predetermined value may also be a then current value of the status register (when passed as a parameter) and the calling function wants to know when the status register changes from its then current value. Of course the compare parameter can be any value desired. The compare in 401 can be accomplished by XORing the current value with the compare value. The results from 401 indicates those bits that have different values from the predetermined value as non-zero bits. Only certain of the bits may be of interest. The mask parameter identifies those bits. Those bits that are of interest are determined by binary ANDing the result of 401 with the mask parameter in 403. If the result of 403 is non-zero that means that bits of interest have changed from the “old status” value. If the result is non-zero, the function returns to the calling function in 402.

[0077] Otherwise the function waits for a bit of interest to change by returning to 401 to again compare the current value of the status register with the predetermined value. In order to avoid a lock-up situation, a timeout may be provided as shown in step 408. After a delay, for example, of 30 seconds, Wait( ) may return to the calling function with a time-out error if the time out condition is defected in 408. In addition, a call to Wait( ) need not block execution of other host software depending of course on the operating system being utilized on the host. For instance, the function may make a call to the host operating system at 409 enabling the execution thread of the wait function to be suspended for a period of time and allowing other tasks operating in the operating system to continue. In that way, system resources are not continually tied up.

[0078] The wait function enables a change in a status bit value to be detected. Should any one of the selected bits change, the Wait( ) function returns. Until the necessary change condition is detected, the function can block execution of the host thread that called the Wait( ) function.

[0079] The current status value is returned in NewStatus; Wait( ) normally returns NO_ERROR. However, it may return immediately, or at any time, with a non zero error value indicating why the Wait( ) call can not proceed. If no bits of interest have changed, the function returns to 401 and continues to check for a change in the current status value.

[0080] An exemplary Wait( ) call is shown below:

[0081] The Send( ) function allows date to be sent to the running processor. The Send( ) function is used to send Length characters from the buffer pointed to by pBuffer to the target processor. The function returns before the transfer has been accomplished. That requires the pBuffer data to be temporally held in a local driver buffer before transmission to the target. If Send( ) is unable to accept the data for transmission then it returns a non zero error value, otherwise it returns zero.

[0082] The status bit STATUS_RX_FULL returned by Status( ) and Wait( ) can be used to determine when the debug driver is ready to transmit more data. The amount of available buffer space can be determined by calling Read( ). If <ByteCount> is greater than the currently available space, the SendO will be completely rejected.

[0083] The driver may break the data into byte or word sized portions before transporting them to the target. It is up to target resident software to support an interrupt or poll-mode routine to receive and process the data. Typically this is built into the target operating system. The Send( ) function applies no meaning to the data, it merely ensures transmission. An exemplary call to Send( ) is shown below:

[0084] Whenever the debug driver determines the target processor has data which it wishes to transfer to the host, the data will be read by the driver and held in a local host buffer. Via Status( ), a debug user can determine there is data waiting in the receive (TX) buffer. If a Receive( ) is not immediately issued, the data will continue to accumulate in the driver's buffer.

[0085] The Receive( ) function copies the data from the receive queue into the buffer pointed to by pBuffer. The buffer's length is given by Length. The number of bytes actually copied is returned in *Count. An exemplary call to Receive( ) function is shown below:

[0086] The description of the invention set forth herein is illustrative, and is not intended to limit the scope of the invention as set forth in the following claims. For instance, in certain embodiments, the debug driver may also provide abstract high-level debug concepts, such as virtual and physical addressing at cost of higher complexity. Other variations and modifications of the embodiments disclosed herein, may be made based on the description set forth herein, without departing from the scope and spirit of the invention as set forth in the following claims.