Getting Started with Hawk

Table of ContentsChapter 1: Welcome to Hawk 56 Hawk Tools Overview7 Project Manager8 Project Spaces8 Workspaces9 Editor10 Debugger12 Ultra C/C++ CompilerChapter 2: Creating Hawk Projects 1314 The Example Applications15 Create and Modify a Hawk Project15 Create a Project Space and Project17 Creating a New Component for your Project20 More on Units22 Configure the Hawk Project22 Search Paths23 Execution Search Path23 Source Options25 Build the Module26 Add a Dependency27 Adding the Sender ComponentChapter 3: Hawk Application Debugging 2930 Preparing to do Application Debugging30 Loading the driver modulesGetting Started with Hawk 3

31 Loading the Modules individually32 Increasing the Timeouts33 Configuring Debug Support for your Project34 Application-Level Debugging Using Hawk34 Setting Up the Debugger35 Using the DebuggerChapter 4: Hawk System State Debugging 3939 Create the Driver Project41 Add the Driver Components to the Project43 Configure the Driver Makefiles43 Edit the makefile File44 Prepare the Target for Debugging45 Prepare Hawk for Debugging45 Attach to the System46 Attach to the ModuleProduct Discrepancy Report 494 Getting Started with Hawk

Chapter 1: Welcome to HawkHawk is an open, integrated development environment that supportsthird-party tools including compilers, in-circuit emulators, debuggers,and other testing tools. The Hawk IDE environment can becustom-tailored to fit your individual needs. You can add custom expertand productivity enhancement features by taking advantage of the openapplication interface. In addition to these features, you have the Hawkdevelopment environment. This environment enables you to work in aseamless workspace that integrates the following functions and tools:• Project Manager• Editor• Debugger• Ultra C/C++ Compiler5

1Welcometo HawkHawk Tools OverviewThe Hawk development environment, as shown in Figure 1-1, containsa set of tools consisting of a project manager, source code editor,debugger, and Ultra C/C++ compiler.Figure 1-1 Hawk Integrated Development EnvironmentProject Manager WindowEditor WindowOutput Window6 Getting Started with Hawk

Welcome to HawkProject Manager1The Project Manager window is located in the left portion of the HawkIDE environment. The Project Manager is responsible for the following:• Organizing each software project within the project space• Identifying the dependencies between software components• Recording detailed build information• Controlling the build processThe Project Manager organizes source files, makefiles, libraries, andadditional project files that are needed to build your application. Whereother tools include various source files and require you to manuallycreate a makefile, Hawk saves the settings to a .PJT file, and .MPJ file.The .MPJ file maintains the relationship between components and unitsand the settings for the components and units. It also replaces themakefile task so that when a build is requested, Hawk automaticallyperforms the old make utility task for you. The types of project files aresummarized in the following table.Table 1-1 Project File Types.pjt file.mpj file.mpjBackupfileMaintains a list of all the files in aproject and some project settings forthe Hawk environmentRetains the structure and setting ofthe properties in a Hawk projectIs a copy of the current .mpj filebeing savedComponents and units are the entities that the Project Manager uses toform logical associations between the various files it manages. Acomponent is equivalent to a module (module, descriptor, driver, etc.),and a unit is an individual file. For more information on these items,please refer to the Using Microware Hawk manual.Getting Started with Hawk 7

1Welcometo HawkProject SpacesProject spaces store sets of projects. Before a project can be made, aproject space has to be set up. Project spaces allow multiple projects tobe open at a time. Project Spaces appear in the Project Manager as filecabinet icons. Only one project space can be open at time.WorkspacesA workspace maintains state information about a project. It differs froma project in that it does not store the system-wide options normallystored in a configuration file. In a sense, the workspace is like a Hawkstate file that can be swapped in and out on the fly.State files retain information about the windows and buffers that wereopen during the last Hawk session and the position those windows andbuffers were in. Workspaces are like mini-state files within projects.Each workspace retains a separate set of window information. Otherstate information such as search options, response histories,bookmarks and so on are stored as part of the project.8 Getting Started with Hawk

Welcome to HawkEditor1The Editor is located in the upper right portion of the Hawk IDEenvironment, as displayed in Figure 1-2. The Editor has the followingfeatures:• Syntax highlighting • DLL extensibility(ChromaCode)• Merge and difference • Elided text (selectivedisplay)• Help manager • IDE integration• API assistance • Button links• HTML viewer • Build file supportFigure 1-2 Hawk Source Code EditorSource codeEditorwindowMore Info MoreInformation More Information More Information More-6-For More InformationTo learn more about the source code editor, please refer to the UsingMicroware Hawk manual.Getting Started with Hawk 9

1Welcometo HawkDebuggerMicroware Hawk can be used for debugging both applications andOS-9 system components. Application processes run in user state andOS-9 system components run in system state.User state application processes are not allowed by the kernel tointerfere with the operating system, so errant pointers and bad logic donot cause a system crash or cause other processes to fail.System state is used by the components of OS-9. The operatingsystem, drivers, device descriptors and file managers operate in systemstate. In this environment, the code associated with the OS and itssubsystems has complete access to the system.Every OS-9 kernel has built-in debugging support, allowing the kernel tocontrol the process that is being debugged. As a result of this built-insupport, the debugging process for user state applications is simplified.A client-server model is used for user- and system-state debugging,where the Windows host machine is the client and the OS-9 targetmachine is the server. To successfully perform debugging, you musthave a stable TCP/IP connection between the Windows host machineand the OS-9 target machine. OS-9 must have the Microware LANCommunications Pak installed and properly functioning for thisdebugging environment to work properly.More Info MoreInformation More Information More Information More-6-For More InformationIf you do not have a fully functional TCP/IP connection establishedbetween the Windows Host machine and the OS-9 target machine,please refer to the Using Microware LAN Communications Pak orthe board guide for your Enhanced OS-9 product.10 Getting Started with Hawk

Welcome to HawkTo debug your user and system-state applications, the Hawk debuggerhas a number of powerful features, including:• Source and assembly-level breakpoints• Display and change registers• View locals• Watchpoints• Directly view and change memory• Stack back-tracing• Easy to use interface• System and process level debuggingUsing the Hawk interface, you can view the results of your debuggingsessions in the output window, as shown in Figure 1-3.1Figure 1-3 Output Window for DebuggingGetting Started with Hawk 11

1Welcometo HawkUltra C/C++ CompilerThe Ultra C/C++ compiler uses state-of-the-art optimization techniquesto obtain the maximum performance from your applications. While mostcompilers optimize your application on a file by file basis, Ultra C/C++can see and optimize your application, along with its libraries, as awhole.Also available in Hawk is the Tools.h++ class library from Rogue Wave.This internationalized C++ foundation class library provides you with120 reusable classes, including sets, bags, sorted collections, strings,linked lists, dates and times, and extensible virtual streams forpersistence.12 Getting Started with Hawk

Chapter 2: Creating Hawk ProjectsThis chapter will teach you to create and modify a Hawk project. Beforeproceeding, be sure you have completed the following:• Installed the Enhanced OS-9 software onto your host system• Connected your target system to your host system• Created an OS-9 ROM Image and transferred it to the target system• Booted your system to the mshell prompt ($)13

2CreatingHawk ProjectsThe Example ApplicationsThis chapter uses the sploop example to illustrate the process ofcreating and modifying a Hawk project. The sploop example consistsof a sending application and a receiving application that uses theSoftStax network emulation driver (sploop) to send and receive ahello world message. Figure 2-1 outlines the sploop example.Figure 2-1 Modules Used in the TutorialReceiver ApplicationSender Applicationex1_rcvex1_sndUser StateSystem StatesploopProtocol DriverThe sploop example consists of the following modules:• Two applications (ex1_snd, ex1_rcv) that will run as separateprocesses• One device driver (sploop)• Two descriptor modules (loopc0, loopc1)The required modules are included in the Enhanced OS-9 softwarepackage.More Info MoreInformation More Information More Information More-6-For More InformationUsing SoftStax contains more information about sploop.14 Getting Started with Hawk

Creating Hawk ProjectsCreate and Modify a Hawk Project2This section describes creating and modifying a Hawk project. Duringthis process, you will complete the following tasks:• Create a Project Space and Project• Configure the Hawk Project• Build the Module• Add a DependencyCreate a Project Space and ProjectBefore a project can be built, the project space that will hold it must becreated. This section describes how to create the project space and adda project to it.Step 1. From the Hawk window, select Project -> Project Space ->New. The Create a New Project Space dialog box appears.Step 2.In the Create a New Project Space dialog, enter the file name for yourproject space. For this tutorial, enter the following path::\mwos\projects\tutorial\hawk_tutorialThe name of the project space is hawk_tutorial. is the harddrive or directory holding the mwos directory.Getting Started with Hawk 15

2CreatingHawk ProjectsStep 3.Click OK. Hawk creates a project space file calledhawk_tutorial.psp, and the Create a New Project Space dialog isreplaced by the Project Properties dialog box.Figure 2-2 Project Properties dialog boxProjectPropertiesList BoxNew ProjectbuttonStep 4.Step 5.Step 6.Step 7.Click the New Project button. The Add New Project toProject Space dialog box appears.Enter hawk_tutorial (the name of the project) in the Filename field.It is not necessary to enter the full path because the current directory iscorrect. Also, it is permissible to use the same name as the projectspace because the project file will have a different extension. Projectspaces use the .psp extension, and projects use the .pjt extension.Click OK. The new project, hawk_tutorial appears in the ProjectProperties List Box as part of the hawk_tutorial project space.Click OK to dismiss the Project Properties dialog box.16 Getting Started with Hawk

Creating Hawk ProjectsCreating a New Component for your Project2Once the project space and project have been created, you need tocreate a new component. A component is a grouping of files withunique settings. Although not all components create an output, mostcomponents do build binary objects such as a library, a descriptor, or amodule. The following table lists the valid component types:Table 2-1 Valid Component TypesType Output BuilderModule Module Ultra C++Collection n/a n/aDescriptor Module Ultra C++ orEditmodDriver Module Ultra C++File Manager Module Ultra C++I-Code Library *.i or *.il Ultra C++O-Code Library *.l libgenSubroutine Module Module Ultra C++Getting Started with Hawk 17

2CreatingStep 1.Hawk ProjectsTo create a new component, click on the NewComponent button on the right side of the Project Manager window.Figure 2-3 The New Component Button18 Getting Started with Hawk

Creating Hawk ProjectsStep 2.The Create New Component dialog box appears. Projects consists ofmultiple components. For this example, we will start with onecomponent, the receiver process. Type the following into thecomponent dialog box:Name: receiverDescription: receiver process for the sploop (example 1)sender/receiver applicationChip: Type: ModulePsect File:• The Psect File text box can be left blank. The Ultra C/C++ compilerwill use the correct psect file for the executive option mode in use.2More Info MoreInformation More Information More Information More-6-For More InformationSee Using Ultra C/C++ for additional information about default psectfiles.Step 3.Step 4.Step 5.Step 6.Step 7.Click Next>> to display the Units dialog box. Components consists ofunits, which can be library, header, or source files.At the Look in menu item, browse to:\Src\Spf\Examples\Example1Select the ex1_rcv.c file and add by clicking the down arrow abovethe Added Units list box. The ex1_rcv.c full path list should nowappear in the Added Units list box.Leave the Generate Dependency Information check box selectedand Click Finish at the bottom of the window. The GeneratingDependencies dialog box appears while dependency information iscreated.When complete, the Components frame should have a folder calledreceiver, and the Contents frame will contain a file calledex1_rcv.c.Save the project by selecting Project -> Save.Getting Started with Hawk 19

2CreatingHawk ProjectsNoteIf you select a different processor for a component, the componentsettings override the project settings only for this component.NoteThe component name is a module name by default. If the componentname contains a space, Hawk inserts an underline for the modulename. Also, if you have more than one component to enter, you mustfirst create the project and add more components later.More on UnitsA unit is a single file which is added to a component. Since a unit is afile, it has an extension that identifies its type. Hawk recognizes thefollowing types of file extensions:Table 2-2 File Extensions Recognized by HawkExtension Type Builder Viewer*.c, *.cpp,*.cxxUltra C++ SourceFileUltra C++texteditor*.rRelocatable objectfile (ROF)Ultra C++rdump*.i, *.il I-Code file or library Ultra C++ idump*.l O-Code library Ultra C++ libgen20 Getting Started with Hawk

Creating Hawk ProjectsTable 2-2 File Extensions Recognized by Hawk2Extension Type Builder Viewer*.aAssembler SourceFileUltra C++texteditor*.des Descriptor File editmod texteditor*.mak Makefile (any type) OS9make texteditor*. OS-9 Module n/a identGetting Started with Hawk 21

2CreatingHawk ProjectsConfigure the Hawk ProjectSearch PathsThe next task is to configure your project to use correct search paths forlibraries, header files, and storing intermediate and executablemodules.Hawk already knows the location of the default header files andlibraries, but we will set this information again to show how it is done.Complete the following steps for this task:Step 1.Step 2.Select the Project -> Properties menu item. The Propertieswindow for Hawk_tutorial is displayed.The General tab is pre-configured with the default chip that wasselected when the project was created.Select the Folders tab. The Folders tab enables you to addadditional include files, libraries, and the destination for intermediateand executable modules.Enter the folderlocation for theintermediateoutput for theproject.Enter thefolder locationfor theexecutionoutput for theClick on thefolder icon touse thebrowserUnder the Output Folders section, add the following intermediatepath by typing::\mwos\SRC\SPF\EXAMPLES\EXAMPLE122 Getting Started with Hawk

Creating Hawk ProjectsExecution Search PathComplete the following steps to configure the Execution search path.2Step 1.Step 2.Step 3.Step 4.Step 5.Under the Output Folders section, click the Browse icon for theExecution text box. The Select Folders dialog box appears.Select the tutorial folder. The resulting path in the Add Folder text boxshould be as follows: :\mwos\projects\tutorialClick the green plus sign (+) to add this path to the Selected FoldersList.Click OK to close the Select Folders dialog box.Click the Green Check Mark button at the top of the Properties dialogbox to save the new path.Source OptionsComplete the following steps to configure the source file options in theProperties dialog box:Step 1.Step 2.Step 3.Select the Source tab.Select either the C or C++ language.Specify how closely the compiler should follow ANSI standards.NoteThe Link, Debug, and Make tabs enable you to configure manyoptions but typically can be left with the default setup for normaloperation.Step 4.Click the green check mark in the upper left hand corner of theProperties dialog to save changes to the project’s properties.Getting Started with Hawk 23

2CreatingHawk ProjectsStep 5.Click Close to close the Properties dialog box.24 Getting Started with Hawk

Creating Hawk ProjectsBuild the Module2Complete the following steps to build your Receiver module. Thissection describes how to start the build and how to include apre-compiled library.Step 1.Step 2.Step 3.Step 4.Under the Project menu, select Build.A Build Complete dialog box appears and shows the progress of thebuild. It ends this build by stating that there were errors. These errorsare shown in the Build tab window. You may have to scroll to see all ofthe errors. The linker should say that there are many unresolvedite_xxx calls. The errors occur because the receiver process uses theitem.l library, which was not included automatically. Hawk recognizesdefault OS-9 libraries and includes them automatically, but it does notautomatically resolve any calls to the networking or graphics I/O systemlibraries.Click OK in the Build Complete dialog box.Right click on the Receiver folder in the Components frame.Select Unit Maintenance. The Unit Maintenance dialog appears.Add ExistingUnits button.Step 5.Click the Add Existing Units button. The Select One or MoreFiles to Add to Project dialog box appears.Getting Started with Hawk 25

2CreatingHawk ProjectsStep 6.Step 7.Step 8.Step 9.Step 10.Select O-Code Files (*.o, *.l) from the Files of Type: drop-down listbox.At the Look in box, browse to \OS9000\ProcessorName\LIBDouble click on the item.l file to add it to the Unit Maintenancedialog box.Leave the Generate Dependency Information check box selectedand click OK. The item.l file should now be included in the Contentsof Receiver pane below ex1_rcv.c.Now rebuild the project by selecting Project -> Build. You will beleft with one unresolved error.Add a DependencyIn the previous section, there was one unresolved error left after thebuild command executed: the sleep() function. sleep() resides inthe sys_clib.l library. In this case, sys_clib.l is included as adependency instead of as a unit. All Microware-provided objects withoutassociated sources must be included this way.Step 1.Step 2.Step 3.Step 4.Step 5.Step 6.Step 7.Click OK in the Build Complete dialog box to dismiss it.Select Project -> Properties.Select the Link tab in the properties window.In the O-Code Libraries box, browse tomwos\OS9000\Processor Name\LIB\sys_clib.l.Click on sys_clib.l and click Open to include sys_clib.l as anO-Code library.Click the green check mark button in the upper left hand corner of theProperties dialog to save the O-Code library changes.Click on the Click Close to close the Properties dialog box.26 Getting Started with Hawk

Creating Hawk ProjectsStep 8.Rebuild the project again using Project -> Build. This time thebuild should complete without errors.2Adding the Sender ComponentAdd the sender component to the Hawk project.Step 1.Step 2.Step 3.Click the New Component button in the project dialog.Complete the fields in the Create New Component dialog for thesender process.Name: senderDescription: sender process for the sploop (example 1)sender/receiver applicationChip: Type: ModulePsect File:Click Next to display the Units dialog and add ex1_snd.c anditem.l.NoteThe ex1_snd.c file is in the same directory as ex1_rcv.c.:\mwos\SRC\SPF\EXAMPLES\EXAMPLE1\The item.l file is in the following directory::\mwos\OS9000\\LIB\Step 4.Step 5.Leave the Generate Dependency Information check box selectedand click Finish.Rebuild the project by selecting Project -> Build.Getting Started with Hawk 27

2CreatingHawk ProjectsThe next step is to debug the project you built. See Chapter 3 for thebasic steps involved in user-state application debugging with Hawk.28 Getting Started with Hawk

Hawk Application DebuggingChapter 3: Hawk ApplicationDebugging3This chapter covers user-state debugging. The process model used byOS-9 consists of two environments: user-state and system-state.User-state is the execution environment for application processes.Generally, user-state processes do not deal directly with the specifichardware configuration of the system.System-state is the environment in which OS-9 system calls andinterrupt service routines are executed. System-state routines oftendeal with the physical hardware present on a system.This chapter will cover debugging user-state applications.Getting Started with Hawk 29

3HawkApplication DebuggingPreparing to do Application DebuggingBefore you can do application debugging with Hawk. The followingmust be true:• SoftStax is included into the bootfile• The sploop protocol driver and descriptors are loaded onto thetarget• Timeouts must be increased for the receiver and sender processes• Source level debugging must be enabled in HawkThe remainder of this section will discuss how to perform these tasks.NoteIf you followed the board guide for your version of Enhanced OS-9,then you should already have a ROM Image with Softstax enabled. Ityou do not have SoftStax enabled, you need to rebuild your OS-9 ROMImage.Loading the driver modulesThe sploop example requires three modules loaded onto your system.The three modules are the sploop protocol driver module, the loopc0descriptor module, and the loopc1 desciptor module.They can be loaded in one of two ways: loading them individuallythrough Hawk, or adding the modules to a bootfile. Since the modulesare needed only for this example we will load them individually throughHawk.30 Getting Started with Hawk

Hawk Application Debugging3More Info MoreInformation More Information More Information More-6-For More InformationIf you want to learn how to add your own modules to a bootfile see theConfiguration Wizard’s help file.Loading the Modules individuallyThe modules are loaded with the Load command found under theTarget menu. To load the modules you need to perform the followingsteps.Step 1.Step 2.Step 3.Step 4.Step 5.Step 6.Type the following command in the Serial window:spfndpd >>/nil &ndpio>>/nil&This starts user-state debugging on the target, puts the process in thebackground, and redirects the output to NIL. The target is now ready tocommunicate with the Hawk debugger on the host PC.Select Target->Load to open the Load Module dialog box.Click on the browse button and navigate to the directory holding thedriver and descriptor modules. The directory is located in the followingpath: mwos\OS9000\\CMDS\BOOTOBJS\SPFClick loopc0 to select it and click Open.Click Load in the Load Module dialog box. The module is loaded ontoyour reference board.Repeat steps 2- 5 for loopc1 and sploop.Now your reference board has the drivers and descriptors needed tomake this example work loaded onto it.Getting Started with Hawk 31

3HawkApplication DebuggingIncreasing the TimeoutsFor application debugging, you must increase the timeouts of senderand receiver, by completing the following steps:Step 1.Step 2.Step 3.Step 4.Edit the ex1_snd.c file by clicking on the sender component anddouble-clicking the ex1_snd.c file. Follow the same procedure forex1_rcv.cChange timeouts from 10 to 100 on the following lines in ex1_snd.c164 connect_npb.ntfy_timeout = 10;168 fehangup_npb.ntfy_timeout = 10;172 datavail_npb.ntfy_timeout = 10;Change timeouts from 10 to 100 on the following lines in ex1_rcv.c.180 incall_npb.ntfy_timeout = 10;184 fehangup_npb.ntfy_timeout = 10;188 datavail_npb.ntfy_timeout = 10;Save and close the files.Rebuild the project using Project->Build.Save the project by selecting Project -> Save.32 Getting Started with Hawk

Hawk Application DebuggingConfiguring Debug Support for your Project3Step 1.Step 2.Select Project->Properties to bring up the Properties dialog box.In the Source tab, select the Code Generation category. In the DebugSupport field, check Source Level to enable source leveldebugging.Check theSource Levelbutton for thetype of debugsupport youwant.Step 3.Step 4.Step 5.Click the Green check mark button to save your changes.Click the Close button to dismiss the Properties dialog box.Save the project by selecting Project -> Save.Getting Started with Hawk 33

3HawkApplication DebuggingApplication-Level Debugging Using HawkThis section describes application-level debugging. Application-leveldebugging is also known as user-state debugging. During this process,you will complete the following tasks:Setting Up the DebuggerUsing the DebuggerSetting Up the DebuggerThe procedure in this section assumes that your reference board is notrunning.Step 1.Step 2.Apply power to your reference board.Click Connect—the left-most button in the Serial window. Use thedefault Com Port Options. The command prompt displays once theboard has booted.NoteIf the Serial window is not visible, do the following steps to open it:1. Select Tools->Customize->Toolbars2. In the Toolbar Customization dialog box, select Serial.3. Select the Visible check box and click Close.Step 3.Step 4.Step 5.Step 6.Load your newly created sender program by selectingTarget->Load.Browse to the mwos\Projects\tutorial folder.Click on the sender module in the list box and click Open to select thesender program.Click Load to load the sender module on the target.34 Getting Started with Hawk

Hawk Application DebuggingStep 7.Step 8.Step 9.Step 10.Step 11.Select Debug->Connect on the top menu bar. The Connect dialogbox appears.Click the Fork tab. The Connect window displays the target machinename (or IP address) in the Target text box. If the name is incorrect,enter the correct DNS name or IP Address.In the Program box, browse to the receiver module in the\PROJECTS folder and click Open.Click OK. Since the debugger does not know where the accompanyingsource code is located, you will receive an error at this point. Follow theprompts to select ex1_rcv.c. ex1_rcv.c is atmwos\SRC\SPF\EXAMPLES\EXAMPLE1Click Open to select ex1_rcv.c source file.3Using the DebuggerThe next task is to step through the code. At this point the ex1_rcv.csource code is displayed in the Source Code window with ayellow-outlined arrow pointing to the main() line. Also, the Debugtoolbar is displayed. Complete the following steps to use the debugger.Figure 3-1 The Debug toolbarRefork processRun ProcessAnimate processStep over sourceStep into assemblyPause the processRun to cursorStep into sourceReturn from functionStep over assemblyGetting Started with Hawk 35

3HawkApplication DebuggingStep 1.Click the Step into source button to scroll through the code. Theoutput of receiver goes to the Process I/O window. The Process I/Owindow appears when the process creates output.NoteAs you scroll through the code notice a large while() loop. Thereceiver sleeps until it gets a signal. It then wakes up and checks forincoming calls. If there is an incoming call, it reads the data, prints whatit gets, then returns Message Received to the sender.Step 2.Step 3.Set a breakpoint at line 242 (if (incall_flag)). Breakpoints areset in the Breakpoints window.Click on the Toggle Breakpoints Visibility button on theDatawindows Toolbar to open the Breakpoint window.Figure 3-2 Datawindows ToolbarToggle Process I/O visibilityToggle Assembly visibilityToggle Locals visibilityToggle Watch VisibilityToggle Call Stack visibilityToggle Memory visibilityToggle Breakpoints visibilityToggle the MPU Registers visibilityToggle FPU Registers VisibilityToggle MMU Registers visibilityToggle “Special” Registers visibilityToggle Exceptions VisibilityStep 4.Step 5.Step 6.Right click in the Breakpoint window and select Insert from thecontextual menu. The Add Breakpoint window appears.Leave the Breakpoint Type set to Source.Click on the file selector button to the right of the File text box andnavigate to the source file being debugged. In this case, the source fileis ex1_rcv.c which is located inmwos\SRC\SPF\EXAMPLES\EXAMPLE1.36 Getting Started with Hawk

Hawk Application DebuggingStep 7.Step 8.Step 9.Step 10.Step 11.Enter the line number where you want to place your breakpoint into theLine # spin box.Click OK. The dialog box closes and the breakpoint is set on the linespecified as indicated with a red dot.Select the Run process button, indicated by a green arrow, on theDebug toolbar to allow the Receiver to free-run. By looking throughthe source code, you’ll notice that the receiver application sleepsindefinitely until a signal wakes the process up.Type Sender in the serial window. A yellow arrow should appear to theright of the red ball where you set the breakpoint.Exit the debugger by selecting Debug -> Exit Debugger from themain window.3NoteIf Exit Debugger is not available or the Hawk user interface appearsto be locked up, telnet to the target and terminate the receiverprocess by typing procs. From this, determine the process ID of thereceiver, and type kill .You have now completed the basics of application debugging usingHawk.More Info MoreInformation More Information More Information More-6-For More InformationSee Using Hawk for more information on debugging applications.Getting Started with Hawk 37

3HawkApplication Debugging38 Getting Started with Hawk

Hawk System State DebuggingChapter 4: Hawk System StateDebugging4This section describes debugging system-state modules. As mentionedearlier, system-state debugging is needed only for device driver or otherhardware dependent code. The example we will use in this section willrevolve around debugging a RAM disk driver. During this debuggingprocess, you will complete the following tasks:• Create the Driver Project• Prepare the Target for Debugging• Attach to the System• Attach to the ModuleCreate the Driver ProjectThe first task is to create a new project space and project to hold thedriver. The process is very similar to building an application module. It isalso possible to add driver projects to application projects, but it is notnecessary for the current example .Step 1. From the Hawk window, select Project -> Project Space ->New. The Create a New Project Space dialog box appears.Step 2.In the Create a New Project Space dialog box, enter the file name foryour project space. For this tutorial, enter the following path::\mwos\projects\tutorial\sys_state_tutorialThe name of the project space is sys_state_tutorial. is thehard drive or directory holding the mwos directory.Getting Started with Hawk 39

4HawkSystem State DebuggingStep 3.Click OK. Hawk creates a project space file calledsys_state_tutorial.psp, and the Create a New Project Spacedialog box is replaced by the Project Properties dialog box.Figure 4-1 Project Properties dialog boxNew ProjectbuttonStep 4.Step 5.Step 6.Click the New Project button. The add New Project toProject Space dialog box appears.Enter sys_state_tutorial (the name of the project) in theFilename field.Click OK. The new project, sys_state_tutorial appears in theProject Properties List Box as part of the hawk_tutorial projectspace.40 Getting Started with Hawk

Hawk System State DebuggingAdd the Driver Components to the Project4Once the project space and project have been created, the drivercomponents need to be added to the project.Step 1.Click on the New Component button on the right side of the ProjectManager window.Step 2.More Info MoreInformation More Information More Information More-6-In the component window, enter the following:Name: ramDescription: RAM disk device driverChip: Type: Driver (the psect will automatically change to drvstart.r)For More InformationSee Using Ultra C/C++ for additional information about default psectfiles.Getting Started with Hawk 41

4HawkSystem State DebuggingStep 3.Step 4.Step 5.Step 6.Step 7.Step 8.Step 9.Step 10.Click Next>> . The New Units window appears.At the Look in menu item, browse to:\OS9000\SRC\IO\RBF\DRVR\RAMDRVRSelect the following files and add them to the project by clicking thedown arrow above the Added Units block.drvrstat.cinit.cmain.cmisc.cmove.cparity.cread.cstat.cterm.cwrite.cChange the Files of Type box to read Header Files (*.h,*.hpp) and add the following files:prototyp.hram.hChange the Files of Type box to all and add the following file:makefileDe-select the Generate Dependency Information check box. Wedon’t want Hawk to generate dependencies because we will use theexisting makefiles to generate the driver modules.Click Finish. A new ram component appears in the project window.Save the project by selecting Project -> Save.42 Getting Started with Hawk

Hawk System State DebuggingConfigure the Driver Makefiles4The next task is to configure the makefile to properly build thedebugging version of the RAM disk driver. Complete the followingsteps:Step 1.Step 2.Step 3.Step 4.Right click on the makefile file and select Properties.Select the Make tab and configure the menu as follows:Make: os9make -f%b%eForced Make: os9make -f%b%e clean allClick on the green check mark button to save the changes.Click Close to dismiss the Properties window.Edit the makefile FileThe next task is to edit the makefile file. Complete the followingsteps:Step 1.Step 2.Step 3.Double-click the file in the component window or select File -> Openfrom the File menu.At the DEBUG= macro, remove the comment character “#” in front of the-g option.The -g option causes the compiler to create a ram.dbg file thatprovides the symbol information map for source level debugging ofdevice drivers.Right click on the makefile file and select Rebuild. The debuggingversion of the ram driver is placed in the following directory:mwos\OS9000\\CMDS\BOOTOBJS\ram.Getting Started with Hawk 43

4HawkSystem State DebuggingNoteDo not choose the component build by right clicking on the componentto get the contextual menu. Be sure to build by clicking on the file. Thiswill invoke the non-Hawk makefile.Prepare the Target for DebuggingBefore this example can be performed, the OS-9 ROM Image musthave certain services added and other services disabled.Step 1.Step 2.Step 3.Open the configuration wizard and do the following:• Enable the RAM disk(Configure->Bootfile->Disk Configuration, Ram Disk tab)• Disable SoftStax(Configure->Bootfile->Network Configuration, SoftStax Setup tab)• Enable Remote Ethernet Debugging(Configure->Coreboot->Main Configuration, Debugger Tab)• Set your Ethernet IP address(Configure->Coreboot->Main Configuration, Ethernet Tab)• Check that the User State Debugging Modules is selected in theMaster Builder window (to load undpd)Load the bootfile onto your target. Use the directions found in the BoardGuide for your target system.Reboot your target and type the following command at the mshellprompt to start the application debugger daemon.undpd >>/nil&44 Getting Started with Hawk

Hawk System State DebuggingPrepare Hawk for Debugging4Do the following to set up the Hawk IDE for debugging.Step 1.Step 2.Step 3.Step 4.Step 5.Step 6.Step 7.Select Debug -> Options.In the Options window, select the Folders tab. Boxes for inputtingthe source and object code search folder locations are displayed.Click the Source Code Browse button. This displays the SelectFolders window.From this window delete all current selected folders and addmwos\OS9000\SRC\IO\RBF\DRVR\RAMDRVR.Click OK.Select the object code folders browse button and addmwos\OS9000\\CMDS\BOOTOBJS.Close the Options window by clicking OK.Attach to the SystemThe next task is to attach the debugger to the system. Complete thefollowing steps:NoteIn order to set breakpoints in system code, we must stop the target bytyping break at the Serial Console window.1. Open the Serial Window and type break.2. Select Debug -> Connect.3. At the Connect window, select the Attach tab.4. Select type: System.Getting Started with Hawk 45

4HawkSystem State Debugging5. Enter the target’s name in the Target: field.6. Click OK. After a short time, the debugging environment appears.7. Select Debug -> View.8. De-select the Assembly item so that it is not checked. You aresource code debugging.The debugger can be customized for a number of windows that you canselectively display or hide.Attach to the ModuleThe next task is to attach to the module you will test. Complete thefollowing steps:Step 1.Step 2.Step 3.Step 4.Step 5.Step 6.Select Debug -> Connect and highlight Module in the Type box.Type ram in the Module box.Click OK.Select Debug -> View -> Browse Symbol. This selection displaysthe symbol browser window. It should have the ram module icon andname in the window.Expand the ram icon and select the read.c file.Add a breakpoint in the read.c file. Breakpoints are set in theBreakpoints window.46 Getting Started with Hawk

Hawk System State DebuggingStep 7.Click on the Toggle Breakpoints Visibility button on theDatawindows Toolbar to open the Breakpoint window.4Figure 4-2 Datawindows ToolbarToggle Process I/O visibilityToggle Assembly visibilityToggle Locals visibilityToggle Watch VisibilityToggle Call Stack visibilityToggle Memory visibilityToggle Breakpoints visibilityToggle the MPU Registers visibilityToggle FPU Registers VisibilityToggle MMU Registers visibilityToggle “Special” Registers visibilityToggle Exceptions VisibilityStep 8.Step 9.Step 10.Step 11.Step 12.Step 13.Step 14.Step 15.Right click in the Breakpoint window and select Insert from thecontextual menu. The Add Breakpoint window appears.Leave the Breakpoint Type set to Source.Click on the file selector button to the right of the File text box andnavigate to the source file being debugged. In this case, the source fileis ex1_rcv.c which is located inmwos\SRC\SPF\EXAMPLES\EXAMPLE1.Enter the line number where you want to place your breakpoint into theLine # spin box.Click OK. The dialog box closes and the breakpoint is set on the linespecified as indicated with a red dot.Minimize the Symbol Browser window.Select the green arrow on the debugging bar to start the system. Oncethe green arrow is selected, the serial console should print out***Warning*** - breakpoints halt timesharing.Type dir /r0 and you should see the breakpoint you set in thedebugger window.Getting Started with Hawk 47

4HawkSystem State Debugging48 Getting Started with Hawk

Product Discrepancy ReportTo: Microware Customer SupportFAX: 515-224-1352From:_____________________________________________Company: _________________________________________Phone:____________________________________________Fax:__________________ Email:_______________________Product Name:Description of Problem:_________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________Host Platform ______________________________________Target Platform _____________________________________49