This TechTip provides some helpful tips on how to debug a vxWorks �bootrom_uncmp� image using Wind River�s Workbench environment and the OCD Emulator Tools.  

The concepts presented in this TechTip are applicable to both command-line builds and Workbench project specific builds.    

The PowerPC architecture will be used as an example in this TechTip, but the concepts apply to other CPU architectures. Wind River�s wrSbcPowerQuiccII BSP is used as an illustration throughout the TechTip.  

A �bootrom_uncmp� is an uncompressed image that starts in ROM (Flash) and gets copied into RAM for faster execution.  

To debug a �bootrom_uncmp� image, the user must consider if the ROM portion of the image is to be debugged or the RAM portion of the image (or both).   

The following concepts are described in this TechTip:
-    Build Type
-    BSP Modification
-    Debugging ROM Image
-    Debugging RAM Image

This TechTip will discuss how to debug both the ROM and RAM portions.  Before debugging either image, it is important that the correct build type be selected and that debug information be included in the build.  

Build Type:  
When building a bootrom_uncmp image it is important that a bootrom_uncmp.hex image be built.   

When a bootrom_uncmp.hex image is built, a bootrom_uncmp (ELF) image is first built and then some additional processing is performed on it using the objcopyppc utility (Wind River Compiler).  The extra processing looks similar to the following:  

objcopyppc -O srec --gap-fill=0   bootrom_uncmp out.tmp1
objcopyppc -I srec -O binary out.tmp1 out.tmp2
objcopyppc -I binary -O srec --adjust-vma= out.tmp2 bootrom_uncmp.hex

Burning a Flash image with a build type other than a hex image will result in an incorrect image.  

BSP Modifications:  

When a bootrom_ucmp image is built, a temporary bootInit_uncmp.c pseudo file is created in the BSP directory.  This file is derived from the all/bootInit.c file and is renamed to include an _uncmp identifier.   During the build process, symbol information is generated against this temporary file; unfortunately this file is deleted at the end of the build process.   

In order to debug both the ROM and RAM based portions of a bootrom_uncmp image, four modifications to the BSP are necessary:  
- Copy the system�s rules.bsp file to the local BSP directory  
- Modify the local rules.bsp file to retain the bootInit_uncmp.c file  
- Modify the makefile to include the new localized rules.bsp file  
- Modify the makefile to include the �g debug flag  

The steps are:  

a.)    Copy the rules.bsp to the BSP directory.  
The rules.bsp file is normally referenced by the BSP�s makefile as follows:   
$(TGT_DIR)/h/make/rules.bsp  

where  TGT_DIR = $(WIND_BASE)/target  

copy    $(WIND_BASE)/target/h/make/rules.bsp  <the BSP directory>  

b.)    Edit the local rules.bsp file  
    Search for this:  

bootInit_uncmp.o : depend.$(BSP_NAME) $(BOOTINIT) bootInit.o
- @ $(RM) $@
- @ $(RM) bootInit_uncmp.c
$(CP) $(BOOTINIT) bootInit_uncmp.c
$(CC) $(OPTION_OBJECT_ONLY) $(CFLAGS_PIC) -DUNCOMPRESS bootInit_uncmp.c
# - @ $(RM) bootInit_uncmp.c            <<<< COMMENTED OUT THIS LINE <<<<<<

Commenting out the last line will retain the bootInit_uncmp.c file.

As note -- there is an alternate method of obtaining the bootInit_uncmp.c file. Instead of copying the rules.bsp file to the BSP directory, and commenting out the line that deletes the file,  the all/bootInit.c file can be copied into the BSP directory and renamed.  The file will need to be made read-only, otherwise it is deleted during a clean or target build rule.  

c.) Change the Makefile so that it refers to the local copy of the rules.bsp file.  
    At the bottom of the Makefile  

        Change this:  
            include $(TGT_DIR)/h/make/rules.bsp  

        To this:  
            include $(TGT_DIR)/config/$(TARGET_DIR)/rules.bsp                         
     
d.) Modify the Makefile to include Debug Information:  
In order to debug a bootrom_uncmp image, it needs to be compiled with symbolic debug information.  Depending on the vintage of the BSP, the ADDED_CFLAGS or the EXTRA_DEFINE  makefile variable can be specified to include a -g flag.    

EXTRA_DEFINE    = -g   

(It may also be useful to add the �O0 flag to reduce the optimization level to a minimum.)  


Debugging ROM/Flash portion of image:  
For the Flash portion of the bootrom_uncmp image, the bootrom_uncmp ELF file is used (the ELF file is the file named �bootrom_uncmp�).  For this symbol file, an offset must be calculated and specified in Workbench�s Reset and Download tab.     

The reason an offset is needed is because the symbol information is generated in reference to RAM_HIGH_ADRS verses ROM_TEXT_ADRS. This can be verified by using the nmppc utility to view the symbol addresses. All symbols are referenced starting at the value of RAM_HIGH_ADRS (makefile/config.h variable).  

As an example, if you look for the symbol �romInit�,  it's at the very beginning of RAM_HIGH_ADRS verses the place it is actually executing from --- ROM_TEXT_ADRS:  

nmppc bootrom_uncmp | grep romInit
01d00000 T _romInit
01d00000 T romInit


To debug the ROM portion of the bootrom_uncmp image, you need to specify an offset of:    ROM_TEXT_ADRS - RAM_HIGH_ADRS  


For the case of the wrSBC8260PQII,  RAM_HIGH_ADRS is  0x01D00000 and ROM_TEXT_ADRS is 0xFFF00100.  This results in an offset of:   
FFF00100 � 01D00000 = FE200100

The ROM portion of the image is from romInit (romInit.s file) up through the functions in bootInit_uncmp.c   -- romStart to the call to usrInit.  Recall,  bootInit_uncmp.c is a temporary pseudo file created from all/bootInit.c.  

Unfortunately there is no symbolic information generated for the assembly modules in a standard vxWorks image (romInit.s and sysAlib.s).  The reason for this is because these modules are built using the compiler instead of the assembler. The advantage of this method is that you can #include C header files and use common defines between the C and assembler modules.  


Debugging RAM portion of image:  
As stated earlier, a bootrom_uncmp image starts off in ROM, copies itself into RAM, and continues execution in RAM.  The image is copied into RAM at the location specified by the RAM_HIGH_ADRS (makefile/config.h variable).  The first code to be executed out of RAM is usrInit.  

Since the bootrom_uncmp symbol file is relative to RAM_HIGH_ADRS, and this is where the image is being copied to, there is no need to specify a bias offset when debugging the RAM portion of the image.

One very important thing to keep in mind when debugging the RAM portion of the image is that the first breakpoint to be inserted should be a Hardware Breakpoint.  This is necessary since a Software Breakpoint would be overwritten by the copy operation of the ROM portion of the image.   (Software breakpoints are implemented by an opcode swap at the breakpoint location.)  

After the hardware breakpoint is hit, software breakpoints can then be used for the remainder of the image since the image has already been copied into place.