PART III: CUSTOMIZING THE OPERATING SYSTEM
8.7 Monitoring Semaphores During Debugging
During multi-process debugging, you can monitor multiple data structures such as kernel tasks, real-time processes, message queues, semaphores, and other resources. For example, you can monitor a semaphore used to control a device that two processes are using. Or you can set an RTP that uses a system resource to watch that resource during Step Over system calls.
In this section, you learn how to open the Kernel Objects view and view selected resources. For more information about the Kernel Objects view, as well as a guide to the icons and their meanings, open the view and press the help key for your host.
To open the Kernel Objects view and view selected resources, do the following:
1. Connect to your target in the Remote Systems view, as described in 7. Connecting to VxWorks Targets.
2. Open the Kernel Objects view, in one of the following ways:
In the Advanced Device Development perspective, click the Kernel Objects tab to bring it to the foreground.
In the Device Debug perspective, select Window > Show View > Kernel Objects.
3. Click the pull-down arrow (at the far right of the tool bar) and select your target connection.
NOTE: Be aware that when you open a view using Show View, it may appear in a different location from where it usually appears in another perspective. You can move it if you like by clicking its name tab and dragging it to your preferred location.
8 Running and Debugging VxWorks Applications 8.7 Monitoring Semaphores During Debugging
The Kernel Objects view appears. System resources are displayed in a hierarchical tree.
4. To see specific instances of a type of resource, or to display which tasks belong to which executable, click the plus sign to expand the entries in the tree.
5. Double-click a resource to examine it in the Kernel Objects view. Properties and their current values are displayed in the Properties view.
PA R T V
Deploying Applications
9 Deploying VxWorks Systems ... 123
9
Deploying VxWorks Systems
9.1 Introduction 123
9.2 Reconfiguring VxWorks for Deployment 123
9.3 Adding Kernel Applications to a VxWorks Image 125
9.4 Example: Bundling RTPs and Libraries with a VxWorks Image 128
9.1 Introduction
This chapter presents the different ways you can deploy your applications. You can begin planning for deployment after you have completed your development work and are satisfied that your code runs on the intended target and functions as you intended.
How you deploy an application depends on whether there is a file system on the target, or the target accesses the application on disk or on a host, or if you need to bundle the applications and libraries into a ROMFS inside your kernel image.
For more in-depth information about this topic, see the following documents:
VxWorks Application Programmer’s Guide: RTP Applications
VxWorks Kernel Programmer’s Guide: Kernel Applications
9.2 Reconfiguring VxWorks for Deployment
The tasks in this section show you how to reconfigure VxWorks for deployment.
You should reconfigure VxWorks before you deploy your application if the required functionality for the deployed system is different from that needed during development.
For example, if Workbench tools do not have to communicate with the image once it is deployed, you can remove WDB agent functionality from the image. A quick
way to do this is to exclude the WDB components from your VIP using the Kernel Configuration Editor.
Another reason to reconfigure before deployment, is to reduce the footprint of the application. Resource-constrained or performance-driven systems may require that you exclude unnecessary VxWorks functionality, as well as all the supporting code from other components.
An example of this is System Viewer instrumentation. The System Viewer adds to the overall footprint of a kernel image, and the semaphore and other support for System Viewer increase the kernel size as well.
To exclude components across several components, you should create a VSB project, exclude the functionality, then base a VIP on your configured VSB.
Excluding Components Using the Kernel Editor
In this task, you exclude WDB agent services from a VIP using the Kernel Configuration Editor.
This process is described in Excluding Components from a Kernel Image, p.40, and is included here for convenience.
To exclude WDB agent services from a VIP, do the following:
1. Expand your VIP project, then double-click the Kernel Configuration node to open the Kernel Configuration Editor.
2. Right-click in the Component Configuration pane, then select Find from the context menu.
3. In the Find dialog’s Find Scope pane, select Description, then in the Pattern field, type WDB. The dialog displays a list of matching entries.
4. Select WDB agent components, then click Find. The Component Configuration tree displays it in context.
5. Right-click WDB agent components, then select Exclude.
The Exclude dialog displays all the WDB-related components that will be excluded from the kernel image.
6. Click Next. Workbench determines if there are any dependent components that must also be excluded along with the WDB components, and displays them.
7. To complete the configuration, click Finish.
The Kernel Configuration Editor shows the WDB agent components, but it is no longer bold. This means that the components are installed and available,
! CAUTION: When VxWorks is configured with the WDB target agent, it is enabled on UDP port 17185. This service provides full access to VxWorks memory, and allows for writing to memory as well as for calling routines. Wind River recommends removing WDB from VxWorks for production systems.
To disable the WDB Target Agent, use the Kernel Configuration Editor to exclude the WDB components from your kernel image; see Excluding Components from a Kernel Image, p.40.
9 Deploying VxWorks Systems 9.3 Adding Kernel Applications to a VxWorks Image
but not included in your kernel image. There is also an overlay icon that indicates that the component has changed. The change has not yet been saved, however. The change will be saved automatically when your project is built.
8. In the Project Explorer, right-click your project and select Build Project, or click the Build Projects icon on the toolbar. The WDB components are excluded from the resulting VxWorks kernel image.
Excluding Components Using a VSB Project
In this task, you exclude System Viewer agent services from your VIP using the Kernel Configuration Editor.
This process is described in 4.9 Example: Customizing VxWorks Libraries as a Base For a VIP, p.50, and is included here for convenience.
To exclude System Viewer components from a project, do the following:
1. Double-click your VSB, then double-click the Source Build Configuration node.
2. Search for System Viewer components in the following way:
a. Right-click in the Option pane, then select Find.
b. Type a letter or two of the option’s name into the Pattern field, using wildcard characters if necessary.In this case, typing an S displays Enable System Viewer Instrumentation Support.
c. Select Enable System Viewer Instrumentation Support and click Find.
The component appears in the Option pane.
3. In the Option pane, right-click Enable System Viewer Instrumentation Support and select Change value.
4. Scroll to the right (if necessary) and from the drop-down list select n to deactivate System Viewer support.
5. Press CTRL+S to save your changes, or close the editor and select Yes when you are prompted to save.
6. Build the project by right-clicking it in the Project Explorer, then selecting Build Project. Since you are recompiling the VxWorks libraries, this can take awhile.
If the project builds successfully, Build Finished in Project ‘project_name’
appears in the Build Console.
9.3 Adding Kernel Applications to a VxWorks Image
In this section, you learn how to add an application to a VxWorks Image project (VIP) so that VxWorks starts the application automatically. When you build a VIP with application subprojects, it helps assure correct linking and
dependency-checking.
Only application projects like downloadable kernel modules or user-defined projects can be linked to a VIP this way, because they are solely source code containers. Linking object files or object codes to the VxWorks image is done differently, by editing the Makefile and setting the EXTRA_MODULE or LIBS macros.
This example includes the following tasks:
Task 1: Link the application projects to the VIP.
Task 2: Add the application initialization routines to the VIP.
Task 3: Configure the VxWorks kernel to support your application.
Task 4: Build the VIP.
Before You Begin
You must have created kernel application projects, populated them with code, and successfully built the projects. Then, you can make the kernel application project a subproject of a VxWorks Image project.
Task 1: Link the application projects to the VIP.
In this task, you establish the links between your applications and the VIP.
To link applications to the VIP, do the following:
1. Right-click the project that you want to make into a subproject and choose Project References > Add as Project Reference.
2. In the dialog, click the check box next to the superproject that should be the parent of your application. Highlighting the project is not enough.
3. Click OK to create the link. The application project appears under the VIP in the Project Explorer.
Task 2: Add the application initialization routines to the VIP.
In this task, you add the application routines to the VIP. Later, when VxWorks boots, it initializes all operating system components (as needed) and passes control to the application for initialization.
To add application initialization routines to the VIP, do the following:
1. To add kernel application initialization calls to VxWorks, double-click userAppInit.c to open the file for editing.
2. In the usrAppInit( ) function, add the necessary calls to start your application.
3. Close the file, and select Yes when prompted to save the changes.
Task 3: Configure the VxWorks kernel to support your application.
In this task, you configure VxWorks to support the calls your application makes to the kernel. This enables the application to link to your image.
NOTE: If your BSP provides a “bare-bones” VxWorks configuration, you may want to use the Kernel Configuration Editor Autoscale facility to detect and add most of the VxWorks functionality you require.
9 Deploying VxWorks Systems 9.3 Adding Kernel Applications to a VxWorks Image
To configure VxWorks to support your application, do the following:
1. Double-click the VIP to expand it.
2. Double-click the Kernel Configuration node to open the Kernel Configuration Editor.
3. Right-click in the Component Configuration pane, then select Autoscale. Click Yes to continue.
Autoscale compiles your code, analyzes the symbols in your object modules, maps them to components, and shows you those components.
4. Do one of the following, and then click OK:
To include specific components, click the check box next to the component.
To include all of the components, click Select All.
Autoscale next analyzes your code, and shows you the components that do not seem to be required by your application.
5. Do one of the following.
To exclude any of those components, click the check box next to them.
To accept Autoscale’s judgement that all are unneeded, click Select All.
Be careful when you elect the components to remove. Autoscale is not infallible. Some of the listed components may still be needed by your application.
6. Click OK. Autoscale removes the selected components, and returns to the Component Configuration pane.
Task 4: Build the VIP.
In this task, you build the VIP you configured in this example so it links to and launches your applications
There may be some components that Autoscale did not detect, or it may have suggested that you remove a component that you actually need. If you Autoscale, build, and get link errors, you need to repeat Task 3: Configure the VxWorks kernel to support your application. You can then add the necessary additional
components from the Kernel Configuration Editor.
To build the VIP for this example, do the following:
In the Project Explorer, right-click the VIP and deselect Build Project.
Workbench automatically saves the changes you made in the Kernel Configuration Editor, then builds your project.
For more information about Autoscale and the Kernel Configuration Editor, open the editor and press the help key for your host.
9.4 Example: Bundling RTPs and Libraries with a VxWorks Image
In this example, you bundle RTPs and Libraries with a VxWorks image, to complete the deployment phase that follows the 6.12 Example: Working with RTPs, Shared Libraries, and Plug-Ins, p.85.
In the prerequisite example, you created two RTP applications and a library, and then configured your applications to call the library either as a shared library at run time, or as a plug-in when needed by the application. You then ran the applications manually in the VxWorks simulator.
In this final phase, you create a way of statically identifying the run time location of your shared library, instead of typing the entire LD_LIBRARY_PATH command when you launch the applications. You must do this for both applications, because the application that uses the library as a plug-in also needs to be able to find libc.so.1. You must also add initialization code, so VxWorks can start your applications automatically.
Here are the steps you will follow:
1. Set the target-side run path for an application.
2. Change fooPlugRtpApp to reference ROMFS instead of the workspace.
3. Rebuild your RTP applications.
4. Create a VxWorks ROMFS File System project.
5. Set up the ROMFS target file system.
6. Rebuild your VxWorks image project
7. Restart the VxWorks simulator and view ROMFS contents.
8. Launch the RTP applications and disconnect the VxWorks simulator.
9. Add the application initialization routines.
10. Verify that your application launches automatically.
Step 1: Set the target-side run path for an application.
In this task, you use the -rpath compiler option to set the target-side run path for the application.
To set the target-side run path for an application, do the following:
1. In fooRtpApp, right-click the build target fooRtpApp (fooRtpApp.vxe), then select Properties.
2. In the Build Properties dialog, select the Build Tools tab to bring it forward.
Then, verify that the build tool is set to Linker and the active build spec is one of the following:
SIMPENTIUMdiab_RTP for Windows and Linux
SIMSPARCSOLARISdiab_RTP for Solaris
3. Click Tool Flags, verify that Create a dynamic executable is selected, and then click OK.
9 Deploying VxWorks Systems 9.4 Example: Bundling RTPs and Libraries with a VxWorks Image
4. In the text field next to Tool Flags, append the directory that will hold the shared library on your target (this is known as the run path), in one of the following ways:
For the Wind River Compiler, type the following command:
-rpath /romfs/lib
For the Wind River GNU Compiler, type the following command:
-Wl,-rpath /romfs/lib
/romfs is the default root directory of the ROMFS created by the VxWorks ROMFS File System project that you will create to hold your applications and library in Step 4:Create a VxWorks ROMFS File System project., p.129.
5. Click OK to save your settings and close the dialog.
6. In fooPlugRtpApp, do the following:
a. Open the build properties for fooPlugRtpApp (fooPlugRtpApp.vxe).
b. On the Build Tools tab, make sure Linker and the correct build spec are selected.
c. Click Tool Flags and verify that Create a dynamic executable is selected.
d. Append the correct -rpath compiler option to the Tool Flags command.
e. Click OK to save your settings.
Step 2: Change fooPlugRtpApp to reference ROMFS instead of the workspace.
In this task, you modify the application so it references ROMFS instead of the workspace, as the deployed location for the applications and library.
To change the application reference to ROMFS, do the following:
1. In fooPlugRtpApp, double-click fooPlugRtpApp.c to open it in the editor.
2. Change the dlopen call to:
handle = dlopen("/romfs/lib/barLib.so", RTLD_NOW);
3. Close fooPlugRtpApp.c, and click Yes to save your changes.
Step 3: Rebuild your RTP applications.
In this task, you rebuild the RTP applications to incorporate your changes.
To rebuild the RTP applications, do the following:
1. Right-click fooPlugRtpApp and select Rebuild Project.
2. Right-click fooRtpApp and select Rebuild Project.
Both applications should build without errors.
Step 4: Create a VxWorks ROMFS File System project.
In this task, you create a VxWorks ROMFS file system project that you will use to create the target file system where your applications and library will reside.
To create a VxWorks ROMFS file system project, do the following:
1. In the Project Explorer, select VIPsimpc so the new ROMFS project will become a subproject of your VIP.
2. Select File > New > VxWorks ROMFS File System Project.
3. In the Project name field, type romfsFS.
4. Leave Create project in workspace selected, and click Finish.
Your project appears under VIPsimpc in the Project Explorer, and the File System Contents editor opens.
Step 5: Set up the ROMFS target file system.
In this task, you set up the ROMFS target file system and include your applications and library.
To set up the ROMFS target file system, do the following:
1. In the upper left corner of the File System Contents editor, click Show all projects.
2. In the editor, create bin and lib directories, in the following way:
a. Click New Folder, then type bin in the Name field. Click OK.
b. Click New Folder again, then type lib in the Name field.
c. Click OK.
The new directories appear in the Target contents pane.
3. Add your application binaries in the following way:
a. Click the bin directory to select it.
b. In the Host contents pane, open fooPlugRtpApp and select fooPlugRtpApp (fooPlugRtpApp.vxe).
c. Click Add.1
4. With the bin directory still selected, open fooRtpApp and select fooRtpApp (fooRtpApp.vxe), and click Add.
In the Target contents pane, the bin directory should contain fooPlugRtpApp.vxe and fooRtpApp.vxe.
5. Add your shared library in the following way:
a. Click the lib directory to select it.
NOTE: To add a folder, its contents and subfolders to the target, under Host contents click to highlight a folder that contains files; then click Add Folder recursive.
You can also drag and drop folders and files from the Host contents tree to the Target contents tree.
You cannot add empty folders to the Target contents using these techniques.
1. If you select something in the Target contents pane and then need to unselect it, click in the pane and press ESC.
9 Deploying VxWorks Systems 9.4 Example: Bundling RTPs and Libraries with a VxWorks Image
b. In the Host contents pane, open barLib and select barLib (barLib.so).
c. Click Add.
6. With the lib directory still selected, add the VxWorks standard shared library in the following way:
a. Click Add External.
b. Navigate to installDir/vxworks-6.x/target/usr/root/cpuTool/bin.
Substitute the correct path for installDir, the correct version number for 6.x, and for cpuTool, and select SIMPENTIUMdiab for Windows and Linux or SIMSPARCSOLARISdiab for Solaris.
c. Select libc.so.1 and click Open.
In the Target contents pane, the lib directory should contain barLib.so and libc.so.1.
7. Close the File System Contents editor, and click Yes to save the changes.
Step 6: Rebuild your VxWorks image project
In this task, you rebuild the VxWorks image project to include the changes you
In this task, you rebuild the VxWorks image project to include the changes you