VxWorks WindML Guide: Configuration and Driver Development
🧭 1. Introduction #
WindML (Wind Media Library) is a multimedia library designed for embedded applications running on the VxWorks real-time operating system. It provides foundational graphics, video, audio, font, and input-device services, together with a driver development framework that separates application interfaces from hardware-specific implementations.
WindML exposes a unified graphics interface and mechanisms for processing input devices and input events. Its architecture allows application developers to use consistent APIs across supported hardware configurations while enabling driver developers to integrate platform-specific graphics and peripheral functionality.
The principal design objectives of WindML are:
- Simplicity: Provide flexible graphics primitives and fundamental multimedia functions without requiring applications to implement hardware-specific operations.
- Hardware portability: Support multiple processor architectures through appropriate device drivers and configuration settings.
- Operating-system integration: Integrate with supported real-time operating system environments and their device-management mechanisms.
- Driver extensibility: Provide established interfaces and reference implementations that developers can adapt to custom hardware.
WindML is primarily associated with earlier VxWorks development environments, including VxWorks 5.x and 6.x. Its availability and configuration procedures depend on the specific WindML release, processor architecture, and development environment. For newer platforms, verify the supported graphics components and compatibility requirements before reusing legacy WindML code.
🏗️ 2. WindML Architecture #
WindML consists of two principal components: the Software Development Kit (SDK) and the Device Driver Kit (DDK).
The SDK provides the APIs used by application developers. The DDK supplies driver interfaces, implementation frameworks, and reference drivers for supported hardware.
This separation allows application logic to remain largely independent of the underlying graphics, input, and multimedia devices.
Figure 1. WindML SDK architecture

2.1 Software Development Kit (SDK) #
The SDK defines the interface between application code and device drivers. It enables applications to perform graphics operations, process input events, manage fonts, and access supported multimedia functionality without directly implementing hardware-specific operations.
The primary SDK API groups include:
- Graphics-device initialization.
- Two-dimensional graphics primitives.
- Region and window management.
- Color management.
- Video support.
- JPEG support.
- Audio services.
- Event services.
- Memory management.
- Extended graphics APIs.
- Device management.
For example, an application can call a graphics API to draw a rectangle without directly manipulating the display controller registers. The SDK dispatches the operation through the relevant driver interface, allowing the hardware-specific implementation to perform the actual drawing.
The SDK therefore provides a consistent programming model while preserving the ability to optimize individual drivers for the target platform.
2.2 Device Driver Kit (DDK) #
The DDK sits between the SDK and the physical hardware. It defines driver-level data structures, function interfaces, and implementation conventions for supported output and input devices.
For many SDK operations, the corresponding driver structure contains function pointers that dispatch operations to the appropriate implementation.
For example, uglRectangle() provides an interface for drawing a rectangle. The associated graphics driver structure contains a rectangle function pointer, which is invoked to perform the hardware-specific or software-rendered drawing operation.
WindML defines several driver categories.
Graphics drivers #
Graphics drivers implement display initialization, color allocation, drawing primitives, memory allocation, and page or overlay management.
Representative implementations include VGA, BIOS, MediaGx, and IGS graphics drivers.
Video extensions #
Video functionality is provided through extensions associated with graphics drivers. Depending on the implementation, these extensions support starting and stopping video operations, streaming video, and managing video-related resources.
The IGS video extension is an example of this approach.
Font engines #
Font engines provide functions for font sizing, glyph processing, and text rendering. They generally use the graphics driver to render glyphs to the display.
Examples include the BMF bitmap font engine and the AGFA font engine.
Input drivers #
Input drivers acquire and process input information from devices such as keyboards, mice, pointing devices, and touch screens.
The driver interface abstracts the device-specific details so that applications can consume input events through the supported WindML APIs.
Audio interfaces #
WindML audio support can use device-access interfaces such as open(), close(), and ioctl() to configure and control audio hardware. The specific implementation depends on the audio subsystem and device driver available in the target environment.
Understanding the SDK/DDK boundary is essential when customizing WindML. Application-level changes generally belong in the SDK-facing code, whereas custom hardware support typically requires implementing or adapting the relevant DDK interfaces.
⚙️ 3. WindML Configuration Overview #
Before an application can use WindML, the library must be configured and built for the target hardware and required functionality.
Configuration determines which device drivers, font engines, multimedia features, and resource-management components are included in the resulting library.
Typical configuration tasks include:
- Selecting graphics output drivers and display parameters.
- Configuring keyboard, pointing-device, and touch-screen drivers.
- Selecting audio hardware and channel settings.
- Enabling the required font engine and fonts.
- Configuring event queues and memory management.
- Defining processor-specific settings.
- Selecting optional graphics features and driver extensions.
After configuration, the resulting objects and libraries must be linked into the application or incorporated into the VxWorks image, depending on the build method.
WindML can be configured in two ways:
- WindML Configuration Tool: Use the graphical configuration interface integrated with supported Tornado development environments.
- Command-line configuration: Modify configuration headers and source files directly to implement settings or device combinations that the graphical tool cannot represent.
The configuration tool is generally the preferred method for standard configurations. Direct source-file customization is useful when an application requires multiple devices of the same category, custom hardware support, or modifications to the default initialization sequence.
3.1 Standard and Custom Configurations #
A standard configuration typically includes one graphics device, one keyboard, one pointing device, a selected font engine, and optional audio support. The available choices depend on the installed WindML package and the target platform.
A custom configuration may require modifications beyond the settings exposed by the configuration tool. Examples include supporting multiple graphics devices, multiple input devices, or a user-defined driver.
When using the configuration tool, the generated configuration and build files determine which components are compiled and linked.
When configuring directly from source, the principal configuration file is:
target/src/ugl/config/uglInit.h
Depending on the required changes, developers may also need to modify uglInit.c and the configuration source file for the selected font engine.
Figure 2. WindML configuration overview

3.2 Configuring Graphics Devices #
Graphics configuration defines the display hardware and operating parameters used by WindML.
The principal settings include:
- Graphics driver type, such as MediaGx or VGA.
- Display resolution.
- Frame-buffer color depth and pixel format.
- Display refresh rate.
- Output type, such as CRT or flat-panel display.
Additional graphics features can be enabled or excluded according to application requirements and driver capabilities:
- Software cursor.
- Overlay surfaces.
- Video extensions.
- JPEG support.
- Alpha blending.
- Double buffering.
These features are optional and hardware-dependent. A configuration option should only be enabled when the selected driver and target implementation support it.
Reducing unnecessary features can simplify the build and reduce the memory footprint of an embedded application.
3.3 Configuring Keyboard Devices #
Keyboard configuration specifies the keyboard driver and the device name used by the application.
The default device name is:
/keyboard/0
The appropriate driver must be selected for the target hardware. Keyboard layout and key-mapping settings may also need to be configured to match the intended user interface.
3.4 Configuring Pointing Devices #
Pointing-device configuration specifies the input driver and the device name used to identify the device.
Typical device names include:
| Device type | Default device name |
|---|---|
| PS/2 mouse | /mouse/0 |
| Serial pointer | /tyCo/0 |
| Touch screen | /touchscreen/0 |
These names are examples associated with the corresponding drivers. Confirm the conventions used by the installed WindML release and target configuration before relying on them.
Custom device names can be defined through configuration macros when supported by the selected implementation.
3.5 Configuring Font Engines #
A font engine is required when an application needs to display text through WindML.
The BMF bitmap font engine is a standard option in the described environment. Other font engines, such as AGFA, may be available depending on the installed package.
Font configuration typically involves:
- Selecting the font engine.
- Enabling Unicode support when required.
- Setting glyph-cache parameters.
- Selecting the fonts to include in the application.
- Configuring the memory pool used for font caching.
For command-line configuration, the relevant source files are located in:
target/src/ugl/config
The general filename format is uglFontengineCfg.c, where Fontengine identifies the font engine. For the BMF bitmap font engine, the file is uglBmfCfg.c.
The font-engine configuration file determines which font descriptors are registered and made available to applications.
3.6 Configuring Audio #
Audio configuration specifies the audio driver or device implementation and the number of hardware channels to use.
The available settings depend on the selected audio implementation. If audio functionality is unnecessary for the target application, excluding unsupported or unused audio components can simplify the overall configuration.
3.7 Miscellaneous Configuration Options #
WindML also provides configuration options that affect event processing, memory allocation, and processor-specific initialization.
Event queue size #
The event queue size determines how many events can be buffered for WindML applications. The default described by this configuration is 100 events.
Applications with higher event rates may require a different setting. Queue sizing should account for event production rates, scheduling delays, memory constraints, and the application’s event-consumption behavior.
Memory management #
WindML can use a dedicated memory pool or the VxWorks system memory pool.
When a dedicated pool is configured, supported WindML allocations are obtained from that pool. When the system pool is selected, allocations use the system memory-management facilities.
The appropriate choice depends on the application’s memory constraints, resource-isolation requirements, and the capabilities of the installed WindML implementation.
Processor-specific settings #
Some processor architectures require additional configuration parameters.
For example, historical PowerPC platforms may use different memory models, including the PowerPC Reference Platform (PreP) and Common Hardware Reference Platform (CHRP).
The selected model must match the actual target platform and the requirements of the installed BSP and toolchain.
🛠️ 4. Configuring WindML with the Tornado Configuration Tool #
For supported Tornado environments, the graphical configuration tool provides the primary workflow for selecting devices, configuring display characteristics, choosing font engines, and building the WindML library.
In the Windows-based Tornado environment, open the configuration tool through:
Tornado → Tools → WindML
The exact menu layout and available options depend on the installed Tornado and WindML versions.
Figure 3. WindML configuration tool

4.1 Creating a New Configuration #
To define a new WindML configuration:
- Enter a configuration name in the Configuration File field.
- Select the target processor type. The tool displays processor-specific settings when applicable.
- Open the Graphics configuration page and select the graphics driver, output device, color depth, resolution, refresh rate, and optional components.
- Open the Input page and configure the pointing device and keyboard, including their device names.
- Select a font engine from the installed font engines.
- If using the UGL Bitmap Font engine, configure Unicode support, glyph-cache size, and the fonts required by the application.
- Open the Audio page and select the audio hardware, device name, and required channel.
- Open the Miscellaneous page and configure build options, debugging settings, library targets, and dedicated memory-pool settings where applicable.
- Save the configuration.
The resulting configuration determines the components that are compiled and the options used to initialize them at runtime.
When preparing a production build, review the selected options carefully. Enabling every available extension is not necessary and may increase the resulting library’s size and resource requirements.
4.2 Building the WindML Library #
The configuration tool provides several build targets. Their output paths and names may incorporate the target CPU and toolchain; the paths below use CpuTool as a placeholder.
Build VxWorks archive #
This option rebuilds the configured WindML objects under:
objCpuToolvx
The objects are added to the archive:
libCpuToolvx.a
This archive is intended for use when building the VxWorks image.
Build WindML archive #
This option builds the configured WindML objects under:
objCpuToolUgl
The objects are added to:
libCpuToolUgl.a
This archive contains the configured WindML objects for use as a separate library.
Build WindML object #
This option builds the configured SDK objects, device drivers, and font engines under the corresponding object directory and produces a downloadable target object, described in this environment as:
lib/CpuTool.o
The exact output filename and location depend on the build configuration.
Build Example Programs #
This option builds the example-program target using the configured WindML components. In the described environment, it follows the same build operation as the WindML archive target.
The build option should be selected according to how the resulting components will be integrated into the application or VxWorks image.
4.3 Cleaning Build Artifacts #
The Clean button removes the selected target’s generated build artifacts.
The behavior depends on the selected build target:
- Build Example Programs: Clears the associated targets in
objCpuToolUgland the correspondinglibCpuToolUgl.aarchive. - Build VxWorks archive: Clears the associated targets in
objCpuToolvx; according to the described tool behavior, the WindML objects already contained inlibCpuToolvx.aare not necessarily removed from that archive by this operation.
The exact cleanup behavior should be verified against the installed WindML version.
When changing driver selections or compiler settings, ensure that stale object files and libraries cannot be reused unintentionally. A clean rebuild can help prevent configuration mismatches from producing confusing link or runtime failures.
💻 5. Command-Line Configuration #
Command-line configuration provides direct control over WindML configuration files and initialization logic.
This method is generally more appropriate when the standard configuration tool cannot express the required device combination or custom initialization sequence.
For example, supporting multiple graphics devices, keyboards, or pointing devices may require source-level changes rather than selecting a single driver through the graphical interface.
The main configuration files are located in:
target/src/ugl/config
The principal files are:
uglInit.h: Defines the selected drivers, display parameters, font engine, input configuration, audio settings, memory manager, and other compile-time options.uglInit.c: Implements WindML initialization and deinitialization logic, includinguglInitialize()anduglDeinitialize(). It provides the initialization path for the standard device configuration and may require modification when multiple devices or nonstandard initialization behavior are needed.
Font-engine configuration files, such as uglBmfCfg.c, must also be updated when the set of available fonts changes.
Because the macros and initialization interfaces are release-dependent, use the configuration files shipped with the installed WindML package as the authoritative reference.
5.1 Editing uglInit.h
#
The uglInit.h file organizes the major compile-time configuration options into several groups:
- Device-driver selection.
- Font-engine selection.
- Input-device configuration.
- Graphics-device configuration.
- Audio-device configuration.
- Font-engine parameters.
- Memory-manager configuration.
- Processor-specific and miscellaneous settings.
The following examples illustrate a typical legacy WindML configuration. They must be checked against the headers and driver names supported by the target release.
Selecting device drivers #
WindML uses INCLUDE_* macros to select the relevant driver implementations.
The following example selects VGA graphics, a standard PC AT keyboard, a PS/2 mouse, and no audio driver:
/* Specify the graphics device to use. Select one supported driver. */
#undef INCLUDE_BIOS_GRAPHICS
#undef INCLUDE_CHIPS_GRAPHICS
#undef INCLUDE_CUSTOM_GRAPHICS
#undef INCLUDE_IGS_GRAPHICS
#undef INCLUDE_MEDIAGX_GRAPHICS
#undef INCLUDE_SA11XX_GRAPHICS
#undef INCLUDE_SIMULATOR_GRAPHICS
#undef INCLUDE_Q2SD_GRAPHICS
#undef INCLUDE_M821_GRAPHICS
#define INCLUDE_VGA_GRAPHICS
/* Specify the keyboard type. */
#define INCLUDE_PC_AT_KEYBOARD
#undef INCLUDE_CUSTOM_KEYBOARD
#undef INCLUDE_SIMULATOR_KEYBOARD
/* Specify the pointing-device type. */
#undef INCLUDE_ASSABET_POINTER
#undef INCLUDE_CUSTOM_POINTER
#undef INCLUDE_MS_POINTER
#define INCLUDE_PS2_POINTER
#undef INCLUDE_SIMULATOR_POINTER
/* Specify the audio hardware. */
#undef INCLUDE_IGS_AUDIO
#undef INCLUDE_CUSTOM_AUDIOThe selected macros must correspond to drivers available in the installed WindML distribution. Defining a macro for an unavailable driver can cause build or link failures.
Selecting the font engine #
To enable the BMF bitmap font engine in the described environment:
/* Specify the font engine. */
#define INCLUDE_BMF_FONTSOnly select a font engine that is installed and supported by the target configuration.
Configuring input-device names #
The device name used by a pointing device can be changed through the relevant configuration macros.
For example, to assign a custom serial-pointer name of /tyCo/1, the configuration may use:
#define SYS_POINTER_NAME "/tyCo/1"
#include <ugl/config/uglDepend.h>Place the definition before the inclusion of uglDepend.h, as required by this configuration approach.
The macro name and its effect depend on the target WindML release. Confirm that the selected driver uses this configuration symbol before applying the change.
Configuring keyboard key mapping #
Keyboard layout settings determine how input key codes are interpreted by the application.
A representative configuration is:
/* Specify the keyboard key mapping. */
#define INCLUDE_KMAP_ENGLISH_US
#undef INCLUDE_KMAP_ENGLISH_UK
#undef INCLUDE_KMAP_GERMAN
#undef INCLUDE_KMAP_ITALIAN
#undef INCLUDE_KMAP_FRENCH
#undef INCLUDE_KMAP_SWEDISH
#undef INCLUDE_KMAP_NONESelect the key-mapping configuration that matches the intended keyboard layout. The available mappings depend on the installed WindML release.
5.2 Configuring Graphics Parameters #
The graphics configuration determines the display dimensions, refresh rate, frame-buffer format, and optional graphics features.
The following example configures an 800 × 600 display at 60 Hz, selects an 8-bit indexed frame-buffer format, and enables JPEG support and a software cursor.
/*
* Specify display characteristics.
*/
#define UGL_DISPLAY_WIDTH 800
#define UGL_DISPLAY_HEIGHT 600
#define UGL_REFRESH_RATE 60
/*
* Select a supported flat-panel type if required.
* With these options disabled, the configuration
* defaults to a CRT monitor in the described setup.
*/
#undef INCLUDE_UGL_KYOCERA_KCS057QV1AA
#undef INCLUDE_UGL_SHARP_LM9V385
#undef INCLUDE_UGL_SHARP_LQ039Q2DS01
/*
* Specify the frame-buffer format.
*/
#undef INCLUDE_UGL_MONO
#undef INCLUDE_UGL_GREYSCALE2
#undef INCLUDE_UGL_GRAYSCALE4
#undef INCLUDE_UGL_GRAYSCALE8
#undef INCLUDE_UGL_INDEXED4
#define INCLUDE_UGL_INDEXED8
#undef INCLUDE_UGL_ARGB4444
#undef INCLUDE_UGL_RGB565
#undef INCLUDE_UGL_ARGB8888
/*
* Select optional graphics components.
*/
#undef INCLUDE_UGL_ALPHA
#undef INCLUDE_UGL_DOUBLE_BUFFERING
#define INCLUDE_UGL_JPEG
#undef INCLUDE_UGL_OVERLAY
#define INCLUDE_UGL_SW_CURSOR
#undef INCLUDE_UGL_VIDEOThe configuration represents the following settings:
- Resolution: 800 × 600 pixels.
- Refresh rate: 60 Hz.
- Display output: CRT in the described configuration.
- Pixel format: 8-bit indexed color.
- JPEG extension: Enabled.
- Software cursor: Enabled.
- Alpha blending, double buffering, overlays, and video: Disabled.
An 8-bit indexed frame buffer represents pixel colors through a palette rather than storing a complete RGB value for every pixel. The actual display capabilities and supported pixel formats are determined by the selected graphics driver and hardware.
Similarly, enabling a compile-time feature does not guarantee that the underlying hardware supports it. Verify the driver implementation and its dependencies before enabling optional components.
5.3 Configuring the Font Engine #
Font-engine parameters are generally defined in uglInit.h, while the available font descriptors are specified in the corresponding font configuration source file.
For the BMF font engine, a representative configuration is:
/* Configure the glyph-cache size. */
#define BMF_FONT_GLYPH_CACHE_SIZE UGL_BMF_GLYPH_CACHE_SIZE_MAX
/* Select the memory pool for the glyph cache. */
#define BMF_FONT_GLYPH_CACHE_MEM_POOL UGL_DEFAULT_MEM_POOL_ID
/* Enable Unicode font support. */
#define INCLUDE_UGL_BMF_UNICODEThese settings select the configured glyph-cache capacity, specify the memory pool used by the cache, and enable Unicode support.
The selected cache size and memory-pool identifier must be supported by the installed WindML release. The maximum cache size is not necessarily appropriate for every embedded target; memory availability and application requirements should determine the final value.
5.4 Editing Font Configuration Files #
The font configuration source file controls which font descriptors are registered and available to applications.
For the BMF bitmap font engine, edit:
target/src/ugl/config/uglBmfCfg.c
The file contains external references to font descriptors and a data structure listing the fonts to include.
A representative configuration is:
extern const UGL_BMF_FONT_DESC uglBMFFont_Lucida_Sans_12;
extern const UGL_BMF_FONT_DESC uglBMFFont_Helvetica_Bold_12;
extern const UGL_BMF_FONT_DESC uglBMFFont_Lucida_Sans_8;
extern const UGL_BMF_FONT_DESC uglBMFFont_Courier_12;
const UGL_BMF_FONT_DESC *uglBMFFontData[] =
{
&uglBMFFont_Lucida_Sans_12,
&uglBMFFont_Helvetica_Bold_12,
&uglBMFFont_Lucida_Sans_8,
&uglBMFFont_Courier_12,
NULL
};The uglBMFFontData array enumerates the font descriptors made available through this configuration.
To add a font, declare its descriptor and include its address in the array.
For example, to register an 18-point Courier Bold Oblique font, add the corresponding external declaration:
extern const UGL_BMF_FONT_DESC uglBMFFont_Courier_Bold_Oblique_18;Then add the font to the array:
const UGL_BMF_FONT_DESC *uglBMFFontData[] =
{
&uglBMFFont_Lucida_Sans_12,
&uglBMFFont_Helvetica_Bold_12,
&uglBMFFont_Lucida_Sans_8,
&uglBMFFont_Courier_12,
&uglBMFFont_Courier_Bold_Oblique_18,
NULL
};The font descriptor symbol must match the definition supplied by the installed WindML package or the custom font implementation. Declaring a symbol without providing the corresponding definition can result in a linker error.
The original WindML font resources described by this configuration are located under:
target/src/ugl/fonts/bmf
When additional fonts are required, the font resources and their associated descriptor definitions must be added using the conventions of the installed release. The font configuration must then be updated, and the relevant library or target object rebuilt.
5.5 When uglInit.c Must Be Modified
#
Most standard configuration changes can be expressed through uglInit.h and the associated font configuration files.
Changes that introduce multiple devices or alter the default initialization sequence may also require edits to uglInit.c.
This file contains the implementation of:
uglInitialize(), which initializes the configured WindML environment.uglDeinitialize(), which deinitializes the environment.
The standard implementation is designed around a conventional configuration with one graphics device, one keyboard, one pointing device, one font engine, and one audio device.
When a custom implementation requires more than one device of a given type, verify that initialization, device registration, resource ownership, and deinitialization are all handled correctly.
Direct modifications should preserve the lifecycle requirements of the selected drivers. Incorrect initialization order or incomplete cleanup can cause device-access failures, resource leaks, or inconsistent behavior during repeated initialization.
🔍 6. Build and Integration Considerations #
Correct configuration is only one part of a successful WindML integration. The resulting library must also be compatible with the target image, toolchain, driver implementation, and runtime initialization sequence.
6.1 Verify Driver and Configuration Compatibility #
Before building, confirm that:
- The selected driver exists in the installed WindML package.
- The driver supports the target processor and board.
- The selected resolution and pixel format are supported.
- Optional extensions are compatible with the graphics driver.
- Input-device names and key mappings match the application configuration.
- Font resources and descriptor symbols are available.
- Memory-pool and processor-specific settings match the target environment.
Historical WindML releases may use different macro names, source layouts, and build conventions. Do not assume that an example copied from another release can be used unchanged.
6.2 Choose the Appropriate Build Artifact #
Select the build target according to the intended deployment model.
Use the VxWorks archive when WindML objects must be included in the VxWorks image. Use a standalone WindML archive when the application build requires a separate library. Select the downloadable object target when the configured WindML components are intended to be integrated into a downloadable target program.
After changing compile-time options, rebuild the relevant objects and archives. Ensure that the linker uses the newly generated artifact rather than an earlier library containing a different driver configuration.
6.3 Validate Runtime Behavior #
After integration, verify that the application can initialize the display, access input devices, render text, and invoke the required graphics operations.
Testing should cover the enabled optional components as well as the standard display path. Where memory allocation or event processing is significant, observe resource consumption and validate behavior under representative workloads.
For custom drivers, test initialization, drawing or input operations, error handling, and cleanup independently before relying on the driver in a larger application.
WindML integration guidance for specific legacy environments is available in the VxWorks 6.9 and WindML 5.3 configuration tutorial. Developers working with newer environments should also consult the WindML graphics demo guidance for VxWorks 7, keeping in mind that legacy WindML support and graphics components vary by release.
✅ 7. Conclusion #
WindML provides a layered multimedia architecture for VxWorks applications, separating application-facing APIs from the hardware-specific implementations required by graphics, font, input, and audio devices.
The SDK exposes reusable application interfaces, while the DDK provides driver structures, function pointers, and reference implementations that can be adapted to target hardware. Correct configuration determines which components are built, how devices are initialized, and which features are available to the application.
For standard configurations, the Tornado WindML Configuration Tool simplifies driver selection, display configuration, font selection, and library generation. For specialized hardware or nonstandard device combinations, direct modifications to uglInit.h, uglInit.c, and the relevant font configuration files provide additional flexibility.
Reliable customization requires consistent driver selection, valid font descriptors, appropriate resource settings, compatible build artifacts, and correct runtime initialization. By following these practices, developers can maintain a modular WindML configuration while adapting the graphics and multimedia subsystem to the requirements of their embedded applications.