Configure WindML 5.3 on VxWorks 6.9: DKM and RTP

Configure WindML 5.3 on VxWorks 6.9: DKM and RTP

🧭 1. Introduction

#

WindML 5.3 provides graphics, input-device, and multimedia functionality for embedded applications running on VxWorks. On VxWorks 6.9, WindML can be integrated into a kernel image for direct kernel-mode execution or used by a Real-Time Process (RTP) application that runs in user space.

This guide explains how to configure WindML 5.3 for a VxWorks 6.9 ARM SMP target, build the required libraries, integrate graphics and USB input drivers, and validate the configuration with the ugldemo sample.

Two deployment models are covered:

• Downloadable Kernel Module (DKM): Build WindML as a static archive (.a), link it into the VxWorks Image Project (VIP), and execute the demo as a kernel function.
• Real-Time Process (RTP): Build an RTP-compatible WindML library, link it into a separate application, generate a .vxe executable, and launch the application using rtpSp.

Both approaches use the same fundamental WindML configuration: display, graphics device, keyboard, mouse, font engine, and SMP build settings. The primary differences are the project types, build tools, middleware configuration options, and application execution mechanisms.

The example environment uses the following configuration:

The ft graphics device is specific to the example environment. If your BSP exposes another supported graphics device, select that device and configure a compatible display mode.

WindML availability, driver names, and component identifiers depend on the installed VxWorks release and BSP. Verify the available components in your own development environment before applying these settings to a different target.

📦 2. Installing the WindML Component Tree

#

Before creating WindML projects, install the WindML component definitions in the VxWorks development environment.

Copy the contents of the WindML package’s components directory into the corresponding components directory of the VxWorks installation, preserving the original directory structure.

For example:

F:\vxworks6911\components

The resulting tree should contain the WindML 5.3 component directory, including its configuration files, libraries, and sample applications.

After the component tree is installed, Wind River Workbench should expose windml under the Middleware Component category when adding components to a project.

If the WindML component does not appear, check the installation path, directory hierarchy, and compatibility between the WindML package and the installed VxWorks release.

The examples below assume that the WindML component path is:

F:\vxworks6911\components\windml-5.3

Replace F:\vxworks6911 with the actual installation root when necessary.

🧩 3. DKM Configuration and Build

#

The DKM workflow builds the WindML library, links it into the VxWorks kernel image, and runs ugldemo directly from the kernel shell.

The complete workflow is:

1. Create a DKM project configured as a library.
2. Add WindML 5.3 through the Middleware Component wizard.
3. Configure display, graphics, input, fonts, and SMP settings.
4. Build the WindML archive.
5. Add WindML and USB components to the VIP.
6. Build and boot the image.
7. Run the ugldemo kernel function.

3.1 Create the WindML Library Project

#

Open Wind River Workbench and create a new DKM project.

Assign a suitable project name.

Select the following build specification:

ARMARCH7gnu_SMP

The build specification must match the target kernel configuration. Using an incompatible architecture or multiprocessing variant can introduce ABI inconsistencies and library-linking problems.

Next, change Build tool to Librarian.

The Librarian build tool produces a static archive (.a) rather than a conventional downloadable kernel module object.

Click Finish to create the project.

3.2 Add the WindML Middleware Component

#

In the newly created project, right-click the project and select:

New → Other…

Select Middleware Component and click Next.

Select windml and click Next.

Choose Media Library 5.3.

On the next page, select Media Library Component Configuration, then click Finish.

This option configures and builds the WindML library itself. Do not select Media Library application support for this library project; that option is intended for the RTP application described later.

Once the wizard completes, the project contains the WindML middleware configuration and its associated build files.

3.3 Configure the WindML Display and Graphics Device

#

The project should now provide a config.windml editor. The configuration file is located under the project’s windml-5.3 directory.

Use the component configuration interface to add the required graphics and input components.

First, right-click Media Library and select:

New Child → Display

Next, right-click Display and select:

New Child → Graphics

Add the keyboard and mouse components through the corresponding child-component options.

Open the graphics configuration and set Device to:

ft

Select an appropriate value for Graphic Mode.

The selected resolution and display mode must be supported by the physical display hardware and the selected graphics driver.

For a different BSP, use the graphics device exposed by that BSP instead of assuming that ft is universally available.

3.4 Configure the Keyboard and Mouse

#

Set both the keyboard and mouse device types to USB2.

USB2 specifies the WindML-side input configuration. It does not independently provide USB host-controller initialization or the corresponding keyboard and mouse class drivers.

The VxWorks image must include the matching USB host-controller and device-initialization components. These dependencies are configured in Section 3.6.

If the graphics display initializes but input events are unavailable, check both the WindML device settings and the kernel’s USB configuration.

3.5 Add the BMF Font Engine

#

WindML requires a configured font engine to render text.

Right-click Display and select:

New Child → BMF Fonts

Select an available font in the configuration panel.

The BMF bitmap font engine supplies the font data needed by ugldemo and other WindML applications. A graphics context can initialize successfully while text rendering remains unavailable if the font component or font selection is missing.

For production applications, select only the fonts required by the application’s interface, subject to the capabilities of the installed WindML release.

3.6 Configure the SMP Build Variable

#

The WindML library must be built for the same multiprocessing configuration as the target kernel.

In Workbench, right-click the project and select:

Properties → Build Properties → Variables → New…

Create the following build variable:

The VXBUILD=SMP setting tells the WindML build system to use the SMP-specific configuration where applicable. It must agree with the ARMARCH7gnu_SMP build specification.

Leaving this variable unset or setting it inconsistently with the intended kernel build can produce an incompatible configuration.

After completing the graphics, input, font, and SMP settings, build the WindML library project.

The expected output is a static archive (.a) suitable for integration into the VxWorks image.

3.7 Configure the VxWorks Image Project

#

Create a new VxWorks Image Project (VIP), or open an existing VIP for the target board.

Under Kernel Configuration, include the following components or their exact equivalents in the installed VxWorks release:

INCLUDE_WINDML
INCLUDE_RTP
INCLUDE_SHARED_DATA
INCLUDE_USB_XHCI_HCD_INIT
INCLUDE_USB_GEN2_KEYBOARD_INIT
INCLUDE_USB_GEN2_MOUSE_INIT

The underscore-separated USB component identifiers shown above use the conventional VxWorks component-name format. If the Workbench component tree exposes different identifiers for your installed release, select the corresponding components from that tree and verify their actual build macros.

The USB components must be supported by the target hardware and its BSP. The xHCI component is appropriate only when the platform uses a compatible xHCI host controller.

Build the VIP after confirming that the WindML library configuration matches the image.

In the described Workbench configuration, the image build automatically links the WindML archive from the associated library project. A separate manual archive-linking step is not required when this project relationship is configured correctly.

Verify the build output to confirm that the expected library is included.

3.8 Run ugldemo in Kernel Mode

#

The ugldemo sample is available at:

F:\vxworks6911\components\windml-5.3\samples\demo\ugldemo.c

Add this source file to the VxWorks Image Project so that the demo is compiled into the kernel image.

Rebuild the VIP and boot the resulting VxWorks image on the target.

From the kernel shell, invoke:

ugldemo(0, 1);

Because ugldemo is linked into the kernel image, it is executed as a kernel function. It is not launched using rtpSp.

Ensure that the symbol is available to the shell and that the image includes the required WindML, graphics, font, and input components.

A successful run should initialize the WindML demo on the configured ft display.

🚀 4. RTP Configuration and Build

#

The RTP workflow uses the same WindML display and input configuration, but the demo executes as a separate user-space process.

Two projects are required:

1. An RTP-type WindML library project that produces a static archive.
2. An RTP application project that links the library and produces a .vxe executable.

The kernel image must still provide the required WindML and device-driver infrastructure.

4.1 Create the RTP WindML Library Project

#

Create a new project using the RTP project type.

For the library project, configure the following settings:

Although this project uses the RTP project type, the Librarian build tool is still used to produce the WindML library archive.

Repeat the display and graphics configuration described in Sections 3.3–3.5:

• Add the Display and Graphics components.
• Select the appropriate graphics device, such as ft.
• Choose a supported graphics mode.
• Configure the USB2 mouse and keyboard.
• Add the BMF font component and select a font.
• Set VXBUILD to SMP.

Build this library project before creating the application.

The resulting archive provides the WindML implementation that the RTP application will use.

4.2 Create the RTP Application Project

#

Create a separate RTP application project.

Assign a project name.

Select the same build specification:

ARMARCH7gnu_SMP

Consistency between the target image, WindML library, and RTP application is essential. Confirm that the architecture, ABI, and multiprocessing settings agree across the three projects.

Change Build tool to Linker.

The Linker build tool generates the RTP executable, which uses the .vxe extension.

Click Finish to create the application project.

4.3 Add WindML Application Support

#

In the RTP application project, right-click and select:

New → Other… → Middleware Component

Select the RTP application project you just created.

Choose Media Library 5.3.

On the next page, select Media Library application support.

This distinction is important:

• Media Library Component Configuration is used when creating the WindML library.
• Media Library application support is used when preparing an application that consumes WindML.

The application-support option configures the RTP-side integration required by the executable. Selecting the library-configuration option again does not replace this application-specific setup.

Click Finish to add the component.

4.4 Set the RTP Application Build Variable

#

Configure the SMP build variable for the RTP application.

Right-click the application project and select:

Properties → Build Properties → Variables → New…

Create the following variable:

The variable must agree with the ARMARCH7gnu_SMP build specification and the WindML library configuration.

4.5 Add the Demo Source and Build the Application

#

Add the sample source file to the RTP application project:

F:\vxworks6911\components\windml-5.3\samples\demo\ugldemo.c

Build the project using the Linker build tool.

The output should be a .vxe executable. Verify that the generated executable is linked against the WindML library built in Section 4.1 and that all required symbols have been resolved.

If the link fails, review the application-support configuration, library dependencies, and consistency of the library and application build specifications.

4.6 Deploy and Run the RTP Application

#

Copy the generated .vxe file to a filesystem accessible from the target.

The following example assumes that the file has been copied to /bd0:

rtpSp "/bd0/app_name.vxe"

Replace app_name.vxe with the actual output filename.

The /bd0 filesystem must be mounted and accessible to the target before the command is executed. If another filesystem is used, substitute its path.

The kernel image must contain the components needed by the application, including WindML, RTP support, shared-data support where required, and the appropriate graphics and input drivers.

rtpSp starts the executable as a real-time process. Unlike the DKM test, the application runs in user space rather than being invoked as a kernel function.

A successful execution should open the WindML demo on the configured display.

🔍 5. Troubleshooting and Validation

#

A successful build does not necessarily mean that graphics and input devices will initialize correctly at runtime. Validate each layer independently to isolate problems.

5.1 WindML Does Not Appear in Workbench

#

If windml is unavailable under Middleware Component, verify that the WindML 5.3 component tree has been installed under the correct VxWorks components directory.

Check the directory hierarchy, component configuration files, and compatibility between WindML and the installed Workbench/VxWorks release.

5.2 Library Build or Link Errors

#

If the WindML library fails to build or the VIP cannot link it:

• Confirm that the project uses the ARMARCH7gnu_SMP build specification.
• Verify that VXBUILD=SMP is defined where required.
• Ensure that Media Library Component Configuration was selected for the library project.
• Check that the VIP references the correct library project and build output.
• Inspect linker errors for missing symbols or incompatible library dependencies.

Do not assume that any .a archive is interchangeable with another archive built for a different architecture or operating-system configuration.

5.3 Display Initialization Fails

#

If the demo runs but no display appears, verify:

• The Graphics component is a child of Display.
• The selected graphics device is supported by the target BSP.
• The Graphic Mode is supported by the display hardware.
• INCLUDE_WINDML is enabled in the VIP.
• The WindML library was built with the expected configuration.
• The image includes the required graphics implementation.

If the target uses a device other than ft, reconfigure the WindML graphics component to match the actual hardware.

5.4 USB Input Does Not Work

#

If the display works but keyboard or mouse input fails, verify the USB2 input configuration in config.windml.

Then confirm that the VIP includes the appropriate USB host-controller and keyboard/mouse initialization components. A WindML-side USB2 selection does not automatically guarantee that the underlying USB stack is initialized.

Also check that the USB host-controller type matches the physical hardware and that the selected device drivers are available in the installed VxWorks release.

5.5 Fonts or Text Are Missing

#

If graphics render but text is absent, inspect the BMF Fonts component and its selected font.

Verify that the font data is available in the configured library and that the application uses a supported font configuration.

5.6 DKM Works but RTP Fails

#

If the kernel-mode demo works but the RTP application fails, focus on the RTP-specific configuration.

Confirm that:

• The RTP library project was built successfully.
• The RTP application uses Media Library application support.
• The application uses the ARMARCH7gnu_SMP build specification and VXBUILD=SMP.
• The VIP includes INCLUDE_RTP.
• Shared-data support is present where required by the selected WindML configuration.
• The .vxe file is accessible at the path passed to rtpSp.
• The target has the required WindML and graphics components.

This comparison helps separate RTP integration issues from failures in the underlying graphics device or WindML configuration.

📋 6. DKM and RTP Configuration Reference

#

The following table summarizes the configuration differences between the two approaches.

The VIP must provide the required runtime components:

INCLUDE_WINDML
INCLUDE_RTP
INCLUDE_SHARED_DATA
INCLUDE_USB_XHCI_HCD_INIT
INCLUDE_USB_GEN2_KEYBOARD_INIT
INCLUDE_USB_GEN2_MOUSE_INIT

Verify the USB component names against the actual components provided by the installed VxWorks release.

🔗 7. Related VxWorks Resources

#

For additional guidance on WindML graphics configuration and USB input-device integration, consult these related resources:

• Running a WindML Graphics Demo on VxWorks 7 — discusses WindML demo execution in a later VxWorks environment and explains the distinction between legacy WindML and newer graphics options.
• VxWorks USB Keyboard Driver Development — provides additional context on USB keyboard driver initialization and integration with the VxWorks device interfaces.

These resources cover different software releases and may use different components, tools, or configuration procedures. Confirm compatibility before applying their instructions to VxWorks 6.9 with WindML 5.3.

✅ 8. Conclusion

#

WindML 5.3 can be integrated into a VxWorks 6.9 ARM SMP system through either a DKM-based kernel configuration or an RTP-based application configuration.

The DKM approach builds WindML into a static archive, links it into the VxWorks image, and allows ugldemo to execute directly in the kernel. The RTP approach builds a separate WindML library and links it into a .vxe application that runs as a user-space process.

Both approaches depend on consistent build specifications, the VXBUILD=SMP setting, correctly configured graphics and input devices, and the required kernel components.

For the example environment, the essential settings are the ARMARCH7gnu_SMP build specification, the ft graphics device, USB2 keyboard and mouse support, and a configured BMF font engine.

Once these elements are aligned, ugldemo provides a practical way to validate WindML initialization, graphics output, and input-device integration. The same configuration principles can then be applied to more complex embedded graphical applications while preserving the separation between kernel integration and user-space execution.