Downloading and Installing the Tools


Visit GNU Tools for free tools and technical support.


Main Page


If you have not already registered for free tools and technical support, click on the "Register" tab and fill out your details. Confirmation of your registration will be emailed to the email address you provide together with a password.

If you are a registered user, click on the "Log In" tab and fill out your details.


LogIn Page


We have a strict privacy policy published on the website and will never sell the information you register with us nor will that information be distributed outside our working group. We need it purely to justify the work we do and to monitor demand for our services. Having registered, enter your registered email address and password and click "Log In".


Now that you are logged into the support/download system, click on Products tab to select your desired toolchain.



For this tutorial we will be using the GNUH8 [ELF] v12.02 toolchain. You can find it into the Legacy Downloads -> Legacy Toolchains -> H8 tab, or at this link H8 toolchains



After you click it, another page will be displayed with every version of the H8 toolchain released so far. Click on the "Download" button to the right of the prefered OS version (e.g GNUH8 v12.02 Windows Tool Chain (ELF Format)) in the list.



Depending on which web browser you are using, you may now be given various options. Whichever method you use, you should save the download somewhere and then open the executable to install the GNUH8 [ELF] v04.01 tool chain.

The installer will detect any HEW v1.2 or later version you have previously installed and will automatically register the GNU tools with HEW. If you have not already installed HEW, however, you should download the latest version from the Renesas platform and install it prior to installing GNUH8. HEW comes integrated in the C/C++ Compiler Package, so for this toolchain, you can download HEW from here. For more information about installing HEW, see the documentation at Renesas High-performance Embedded Workshop or at HEW User's manual

Building a Sample Project for Renesas H8 with HEW


Launch HEW from the Start menu and select “Create a new project workspace” from the welcome menu.  Click OK to proceed.


Note: the illustrations in this section show HEW v4.09.  Users of HEW2 may notice differences between the illustrations and HEW versions below v2, however the instructions can be applied to all versions



Type the name of your project (“HewTest”) into the “Workspace Name” box.  Next, use the “Browse” button to choose a folder in which to create the project folder.  For this tutorial we will use “D:\”.  As we will be creating an H8 project, choose “H8S,H8/300” as the CPU family.  “KPIT GNUH8 [ELF]” should be selected as the tool chain.  The “C Application” project type should now be selected.  Finally, press the OK button to proceed to the next stage of project generation.



The project generator now offers you a choice of target CPUs to create your project for.  For this tutorial we will create a project for an H8 device.  “300H” should therefore be selected from the “CPU series” list and “36064” should be selected from the “CPU Type” list.  Having done this, click the “Next” button.



The “Additional CPU options” sheet allows selection of some commonly used compiler features, such as H8 normal mode code generation, to be activated. From here, you can also select which library the project will use. For now just leave the options at their default settings and click the “Next” button to proceed.



Now you can select which type of library do you want to have. A Pre-build one which contains all the basic files needed for the project, or you can opt for a Project-Build one which can be modified at will



For this example select the Target H8/300HN Simulator, as we will use this simulator for debugging purposes later, then press the "Next" button



In the next step you can modify the debugger settings, but for now leave the options at their default and click the “Next” button to proceed.



The project generator now shows you a list of the project files that will be generated.  These include Hew Test, which contains the generated application’s main() function; start.asm, which contains the startup code (this may instead be called start.s or start.src depending on the version of GNUH8 you are using); hwinit.c, in which any required hardware initialisation code is placed; and vects.c, which contains the interrupt vector table for a sample H8 Tiny device.  In most cases, these files will need to be tailored after project generation to match the specific hardware you are using.  In the case of this tutorial, however, hardware will be simulated and the generated project will not require alteration.  To generate the project click the “Finish” button.



HEW now generates the project according to our specifications.  A summary of the various selected options and generated files is presented for your information.  Click the “OK” box to complete project generation.



Having generated the project, HEW now presents a list of project files on the left.  These can be double clicked to display the content of the file in the main editor window.  Double click “Hew Test.c” to show the application’s main() function.



Add the following instructions instead of the main() function:

unsigned char string[] = "hello world";

int count;

int main(void)

{

for (count = 0; count < 12; count++)

string[count] = 'a' + (unsigned char) count;

return 0;

}



We wish to switch on optimisation for this project.  To do so, firstly select the “KPIT GNUH8 [ELF] Toolchain” item from the “Build” menu on the menu bar.



Under Hew_test, click on "C source file" and in the C/C++ window select "Optimize" from the drop down list right to the "Category". In the compiler options dialog box that appears, select the “Object” tab. From there you can select which optimization do you want for this project. We will have for this example the default "Optimise for size". Because “C source file” is selected in the tree view on the left hand side of this dialog, this optimisation level will now be applied to all C files in our project.  By expanding the tree view on the left, settings can be changed for individual files.



Next, select the “List” from the Category drop down menu.  Click on the “Generate list file” tick box and ensure that all “Contents” are ticked.  Again, because “C source file” is selected in the tree view on the left of the dialog box, list files will be generated for all C files in our project.  Each list file will show the source code together with the assembly code the compiler generated for that source.  Each list file is generated into the configuration folder (typically a subfolder of the project folder called either “Debug” or “Release”).



Next, click on "HewTest" in the left section and select the “Link/Library” item from the right menu bar. Select "List" from the Category drop down menu and make sure that the "Generate list file(*.map) is checked



Now select "Sections" from the "Category" drop down menu. This tab allows you to change the addresses to which the various code and data sections will be linked in your target device’s address space.  The default settings are correctly configured for a sample device in the CPU family we selected when generating the project (H8 36064).  When building code for a different device you may need to modify these settings.  For now, do not modify the settings, but instead click “OK” to close the linker options dialog box.



Now that we have made some minor adjustments to the tool chain settings, we will build the project.  To do this, select “Build All” item from the “Build” menu on the menu bar.  Alternatively, you can click the “Build All” icon from the “Build” toolbar. The “Build All” icon is located fourth from left on the toolbar.



HEW now compiles, assembles and links the various project files appropriately and shows any warnings, errors or other tool chain output in the “Build” console window in the lower section of the HEW window.  If any messages appear that relate to specific project files, double clicking the message will typically display the appropriate line of that project file in the editor window for convenience.



Earlier in this tutorial, we very briefly mentioned configuration subfolders.  As well as changing compiler, assembler and linker options on a file-by-file or project-wide basis, groups of such options can be grouped together into configurations.  By default the project generator creates two configurations: “Debug” and “Release” and you will now observe that the “Debug” configuration was selected when we built the project in the last step.  The default settings for the “Debug” configuration result in debug information being generated by the assembler, compiler and linker, while the default settings for the “Release” configuration omit this information producing code suitable for production.  Each configuration can be tailored to your requirements in the compiler, assembler and linker options dialogs and additional configurations can be created and deleted as required using the “Build Configurations” menu item in the “Options” menu on the HEW menu bar.

 


Now that the project has been built with debug information we can proceed to load the code into a debugger and execute/debug the code.  Users of HEW v1.x should now proceed to Running and Debugging the Project with the HDI Debugging Interface.  Although HEW2 users can use the HDI debugging interface to execute/debug their code, HEW2 has its own debugger which is integrated within the IDE and features more mature support for ELF/DWARF2 users It is therefore recommended that HEW2 users jump ahead to Running and Debugging the Project with the HEW2 Debugger.

Running and Debugging the Project with the HDI Debugging Interface


This section of the tutorial explains how to execute/debug projects using the HDI Debugging Interface.  This is particularly appropriate for HEW v1.x users.  Although HEW2 users can use the HDI debugging interface to execute/debug their code, HEW2 has its own debugger which is integrated within the IDE and features more mature support for ELF/DWARF2 users.  It is therefore recommended that HEW2 users jump ahead to Running and Debugging the Project with the HEW2 Debugger.

Launch HDI.  This tutorial will assume HDI v5.01 was installed on your machine, but most steps will be applicable to any version of HDI.

Select your target from the “Create a new session on:” menu.  For simplicity, we will use a simulator rather than actual hardware.  As our project was built for a sample H8 Tiny device, which is functionally equivalent to an H8/300H family device in normal mode, the H8/300HN simulator should be selected. Click OK to proceed.



Although the H8/300HN simulator is configured with an address space typical of this device family, it is necessary to specify exactly what memory exists in our simulated device.  To specify this memory, firstly select the “Configure Map” item from the “Memory” menu on the menu bar.



Next, in the “Memory Map” dialog box, click the “Add” button.



In the “System Memory Resource Modify” dialog box, set the “Start address” to H'00000000 and the “End address” to H'0000FFFF.  The access type should be set to “Read/Write”.  When done, click the “OK” button.

[Note: This will allocate the entire 64KB address space as RAM.  While this is acceptable for this tutorial, you may wish to specify the various areas of RAM (“Read/Write”) and ROM (“Read”) for your specific target to ensure that the memory consumption of your application running on simulated hardware matches the available resources on your target hardware.  For this tutorial, however, it is recommended that you allocate the entire address space as RAM as described above.]



Note that the new memory area (H’0000-H’FFFF) is now shown in the “System memory resource” area.  To commit your changes and close the “Memory Map” dialog box, click the “Close” button.



Now we will load our tutorial application into the simulated target’s memory.  Firstly, select the “Load Program” item from the “File” menu on the menu bar.

 


Click the browse button to locate the application executable on your PC.



Using the file selection dialog box, locate the “D:\HewTest\” folder where the HEW project was created.  The files generated when HEW is building a project are stored in a folder associated with a build configuration.  Each configuration has an associated sub-folder from the project folder which has a matching name.  Hence, in the case of our “Debug” configuration, our debug executable can be found in “D:\HewTest\Debug\”.  Using the file selection dialog box, select the “D:\HewTest\Debug” folder.



The executable itself is named after the project with a “.x” extension.  Hence, in the case of our “Debug” configuration, our debug executable is located at “D:\HewTest\Debug\HewTest.x”.  In order to view files with a “.x” extension, use the “Files of type:” drop-down menu to select “All Files (*.*)”. You should now be able to select the executable code: HewTest.x.



You should now be able to select the executable code: HewTest.x.  After doing this, click “Open” to proceed.  In the “Load Program” dialog box, click the “Open” button to load the program.



HDI reports the various memory areas into which the program was loaded.  This includes both ROM and RAM sections; both code and data.  If any error relating to invalid addresses appears at this stage, be sure you configured the memory map correctly in steps 3-6.  Click “OK” to proceed.



Now our tutorial program is loaded into the target’s memory and the associated debugging information has been loaded into HDI, we can debug the application at the source code level.  To do this, we must firstly load one of the application source files. Select the “Source” item from the “View” menu on the menu bar.  A file selection dialog box will appear



Use the file selection box to locate the project directory (“D:\HewTest\” in the case of this tutorial).  By default, C source file extensions are displayed (*.c); to show all files change the selection in the “Files of type:” menu to “All Files (*.*)”.  In the first instance, we will be debugging the application’s main() function, so select the file “main.c” and click “Open”.



HDI now displays the file main.c in a window.  Notice that assembly labels are displayed against appropriate lines and both source line numbers and linked address information is shown against each line of source code.  We will now add some extra windows to give us more information about the state of the target device during program execution.  Select the “Registers” item from the “View” menu on the menu bar.  A window showing the target’s register values is displayed.



Now we will add a breakpoint to the body of the for(...) loop in the main() function.  Position the mouse pointer in the “BP” column to the left of source line 24 starting the “string[count]...” (see illustration) and double click the left mouse button.  A red dot appears in the “BP” column for line 24 indicating that the breakpoint has been set.



With the breakpoint set, we can start execution.  Select the “Reset Go” item from the “Debug” menu on the menu bar.  This will reset the CPU and then continue executing the code until the breakpoint.



The yellow line in the source code window indicates that the target’s program counter is positioned at an area of program code corresponding to the highlighted line of source code.  The simple tutorial program generated by the HEW project generator for GNUH8 simply initialises a string in RAM to “hello world\n” and then changes each letter in turn until the string is changed to “abcdefghijkl”.  We will watch the string variable in RAM to see this happen character by character.  Position the mouse over the “string” variable on line 24 in the source window and click the left mouse button.  This positions the text cursor over the variable.  Now click the right mouse button to bring up a context menu.  From this select “Add Watch”.



A new “Watch Window” is displayed showing the string variable’s address in RAM, C type and value.  Next, select the “Go” item from the “Run” menu on the menu bar.



You will see the first character of the “string” variable has changed in the watch window so that string now reads, “aello world\n”.  Register values that were modified during code execution are highlighted in red in the “Registers” window.



We will now add a further window to our session.  This window will display a mixed view of both source code and the generated machine code for that source.  This will allow us to see and step through the individual instructions executed on the target.  To add this window, click the left mouse button anywhere in the source code window and then click the right mouse button to show the context menu.  From this, select “Go to disassembly”.



The new “Disassembly” window appears.  Note that the yellow highlighting now shows the individual instruction that will be executed next.



Now we will use another debugging feature of HDI.  Select the “Breakpoints” item from the “View” menu on the menu bar.  This displays a new “Breakpoints” window showing the breakpoint we added earlier.  This time we wish to temporarily disable the breakpoint, so position the mouse pointer over the single line in the “Breakpoints” window and click the right mouse button.  From the context menu that appears, select the “Disable” item.  The breakpoint is now disabled and will not interrupt execution.



As a final demonstration of debugging, we will execute a specific range of instructions starting from the highlighted instruction.  Close the “Breakpoints” window, position the mouse pointer over the “Disassembly” window and click the left mouse button.  Now locate the “RTS instruction” at address 0x015A.  Position the mouse pointer over the instruction and click the left mouse button.  Now click the right mouse button and select “Go To Cursor” from the context menu.



The yellow highlighting now indicates that execution stopped just before executing the “RTS” instruction.  Notice also that the “string” variable in the watch window now shows the value “abcdefghijkl” and the register values have changed once more. This completes the HDI debugging interface tutorial.  Note that you can use the “Save Session” item in the “File” menu on the menu bar to save your entire session including simulator configuration and window layout.  This will save you having to reconfigure these settings each time you debug your code.



In the tutorial we selected a CPU target, configured the target’s memory and loaded a simple application which we then debugged at both C and assembly level.  We used the basic breakpoint, execution and watch features of HDI.  You may wish to now read through Running and Debugging the Project with the HEW2 Debugger to see how HEW2’s integrated debugger can be used to debug the same project.

Running and Debugging the Project with the HEW2 Debugger


This section of the tutorial explains how to execute/debug projects using HEW2’s integrated debugger.  Users of HEW v1.x and HDI may instead prefer to see Running and Debugging the Project with the HDI Debugging Interface.

If you haven’t done so already, launch HEW2 and load the tutorial project workspace from “D:\”.  Ensure the “Debug” configuration is selected and the project has been built see Building a Sample Project for Renesas H8 with HEW for full details).



Select the “Debug Settings” item from the “Debug” menu on the menu bar.



In the “Debug Settings” dialog box that appears, select the “Target”.  For simplicity, we will use a simulator rather than actual hardware.  As our project was built for a sample H8 device, the H8/300HN simulator should be selected (“H8/300HN Simulator”).  HEW2 will warn you that “Target options will be emptied if you change the target”.  Click “Yes” to proceed.



Now select the “Default Format”.  Be sure to select the “Elf/Dwarf2 KPIT” option as any other selection, including “Elf/Dwarf2” is incorrect and may cause HEW2 to become unstable or read the debug information in your project file incorrectly.



Next we will inform HEW2 of the application we wish to debug.  Click the “Add” button on the “Debug Settings” dialog box.  This will cause a “Download Module” dialog box to be displayed.



Click the “Browse” button on the “Download Module” dialog box and a file selection dialog box will appear. Usually it opens in the project Debug folder. If not use this to navigate to the “D:\HewTest\Debug\” folder.  In this folder, select the file “HewTest.x” and then click the “Open” button to confirm the selection.



HEW2 returns you to the “Download Module” dialog box.  As before, be sure to select the “Elf/Dwarf2 for KPIT” option as any other selection, including “Elf/Dwarf2” is incorrect and may cause HEW2 to become unstable or read the debug information in your project file incorrectly.  Ensure that the “Offset” field is at its default value of 00000000 and the “Download debug information only” option is off (again, this is its default value).  Now click the “OK” button on the “Download Module” dialog box and then click “OK” on the “Debug Settings” dialog box.  HEW2 now loads various debug components and you should notice that a number of new toolbars are added to the user interface.



Although the H8/300HN simulator is configured with an address space typical of this device family, it is necessary to specify exactly what memory exists in our simulated device.  To specify this memory, select the “Memory Resource” button from the debug menu bar.



HEW2 now presents a “Simulator Memory Resource” dialog box.  Click on the “Add” button right to the Memory Resource as we will be adding a memory area to the simulated target.



In the “System Memory Resource Modify” dialog box, set the “Start address” to H'00000000 and the “End address” to H'0000FFFF.  The access type should be set to “Read/Write”.  When done, click the “OK” button.

[Note: This will allocate the entire 64KB address space as RAM.  While this is acceptable for this tutorial, you may wish to specify the various areas of RAM (“Read/Write”) and ROM (“Read”) for your specific target to ensure that the memory consumption of your application running on simulated hardware matches the available resources on your target hardware.  For this tutorial, however, it is recommended that you allocate the entire address space as RAM as described above.]



Note that the new memory area (H’0000-H’FFFF) is now shown in the “Simulator Memory Resource” area.  To commit your changes click the “Apply” button.



Now we will download our tutorial application into the simulated target’s memory.  Select the “Download Modules” item from the “Debug” menu on the menu bar.  In the sub-menu that is displayed, select the option “D:\HewTest\Debug\HewTest.x - H'00000000”.  HEW2 will now download the tutorial program into the simulator’s memory.  This includes both ROM and RAM sections; both code and data.  If any error relating to invalid addresses appears at this stage, be sure you configured the memory map correctly in the earlier stages.  If no messages are reported, the download was successful. 

[Note: In HEW2 there are a number of ways to download the tutorial application.  Selecting “Rebuild All” item from the “Build” menu on the menu bar will give you the option of downloading the created module.  Alternatively, right clicking the “HewTest.x” entry in the project files view will display a context menu from which “Download module” can be selected.]



Now our tutorial program is loaded into the target’s memory and the associated debugging information has been loaded into the HEW2 debugger, we can debug the application at the source code level.  To do this, we must firstly display one of the application source files.  Double click the file “Hew Test.c” in the “Projects” tab.  By default this is located on the left hand side of the HEW2 window.



HEW2 now displays the file "Hew Test.c" in the editor window.  Notice that assembly labels are displayed against appropriate lines and linked address information is shown against each line of source code.  We will now add some extra windows to give us more information about the state of the target device during program execution.  Select the “CPU” item from the “View” menu on the menu bar.  Now select “Registers” from the sub-menu that is displayed.  A frame showing the target’s register values is added to the HEW2 window. 



Now we will add a breakpoint to the body of the for(...) loop in the main() function.  Position the mouse pointer on source line 39, which starts “string[count]...” (see illustration) and click the right mouse button.  In the context menu that appears, select the “Toggle Breakpoint” item.



Observe that a red dot appears in the column closest to the program code on line 42 indicating that the breakpoint has been set. With the breakpoint set, we can start execution.  Select the “Reset Go” item from the “Debug” menu on the menu bar.  This will reset the CPU and then continue executing the code until the breakpoint.



The HEW2 debugger may ask you to locate the source file that contains the breakpoint.  This is because the debug information generated by the tool chain indicates the file name but not the entire path to the source code.  You should therefore select the file “main.c” from the project directory (“D:\HewTest\”) and click the “Open” button.



The yellow arrow in the editor window over the red breakpoint dot indicates that the target’s program counter is positioned at an area of program code corresponding to the indicated line of source code and that the breakpoint has interrupted program execution.  The simple tutorial program generated by the HEW project generator for GNUH8 simply initialises a string in RAM to “hello world\n” and then changes each letter in turn until the string is changed to “abcdefghijkl”.  We will watch the string variable in RAM to see this happen character by character.  Position the mouse over the “string” variable on line 39 in the editor window and click the right mouse button to bring up a context menu.  From this select “Instant Watch”.



HEW2 displays an “Instant Watch” window containing “string”.  Click on the “Add” button.



A new “Watch Window” is displayed showing the string variable’s address in RAM, C type and value.  At this time you may need to adjust the height and/or position of the various frames in the HEW2 window so you can see the necessary information.  Next, select the “Go” item from the “Debug” menu on the menu bar.



You will see the first character of the “string” variable has changed in the watch window so that string now reads, “aello world\n”.  Register values that were modified during code execution are highlighted in red in the “Registers” window.



We will now add a further window to our session.  This window will display a mixed view of both source code and the generated machine code for that source.  This will allow us to see and step through the individual instructions executed on the target.  To add this window, click on the "View" tab from the menu bar and select “Disassembly”.

[Note: due to a known bug in early versions of HEW2, you may need to switch back to the main.c source window and then return to the Disassembly window using the Window menu on the menu bar in order for the Disassembly view to appear correctly. 



The new “Disassembly” window appears.  Note that the yellow arrow overlaid on the red breakpoint dot now shows the individual instruction that will be executed next.  In order to view both source and disassembled object code in the disassembly view, click on the second button on top of the dissasembly window.  Source code lines are added to the disassembled object code.



This time we wish to temporarily disable the breakpoint, so position the mouse pointer over the single line in the “Breakpoints” view and click the right mouse button.  From the context menu that appears, select the “Disable” item.  The breakpoint is now disabled and will not interrupt execution. 



As a final demonstration of debugging, we will execute a specific range of instructions starting from the highlighted instruction.  Close the “Breakpoints” view using the “X” button at the top left of the view.  Now position the mouse pointer over the “Disassembly” window and click the left mouse button.  Locate the “RTS instruction” at address its address.  Position the mouse pointer over the instruction and click the right mouse button and select “Go To Cursor” from the context menu.



If you will return to the C source code you will see that the yellow arrow indicate that execution stopped just before exiting the main instruction.  Notice also that the “string” variable in the watch window now shows the value “abcdefghijkl” and the register values have changed once more.


This completes the HEW2 debugging interface tutorial.  Note that you can use the “Save Session” item in the “File” menu on the menu bar to save your entire session including simulator configuration and window layout.  This will save you having to reconfigure these settings each time you debug your code.

In the tutorial we selected a CPU target, configured the target’s memory and loaded a simple application which we then debugged at both C and assembly level.  We used the basic breakpoint, execution and watch features of HEW.