Fix Grayed-Out VxWorks Workbench Components and CDF Dependencies

Table of Contents

Fix Grayed-Out VxWorks Workbench Components and CDF Dependencies

When developing custom drivers for VxWorks, it is common to define a component through a Component Description File (CDF) and have Workbench expose that component in the configuration interface.

However, a component may appear grayed out or italicized even though Workbench can discover the CDF file. In most cases, this does not mean that the CDF itself is invalid. Instead, Workbench has identified the component but cannot satisfy one or more of its build-time dependencies.

This issue commonly occurs when a custom driver is kept entirely inside the BSP directory rather than being installed into the standard VxWorks component directories.

Understanding how Workbench resolves CDF modules, source files, and build dependencies makes the problem straightforward to diagnose.

🔍 Why Does Workbench Gray Out a Component?
#

Workbench uses Component Description Files to describe configurable VxWorks components. A CDF specifies information such as the component name, initialization routine, dependencies, and modules required during the build.

For example, consider the following Freescale DMA driver definition:

Component DRV_DMA_FSL {
    NAME        Freescale DMA Controller Driver
    SYNOPSIS    Freescale DMA Controller Driver
    MODULES     vxbFslDma.o
    REQUIRES    INCLUDE_VXBUS \
                INCLUDE_PLB_BUS \
                INCLUDE_DMA_SYS
    _CHILDREN   FOLDER_DRIVERS
    INIT_RTN    vxbFslDmaRegister();
    PROTOTYPE   void vxbFslDmaRegister(void);
    _INIT_ORDER hardWareInterFaceBusInit
    INIT_AFTER  INCLUDE_PLB_BUS
}

The important line is:

MODULES vxbFslDma.o

This tells the VxWorks configuration system that the component requires the vxbFslDma.o object module.

If Workbench cannot resolve that module through its configured search paths, the component becomes unavailable in the configuration interface.

How Workbench Finds the CDF
#

Workbench normally searches locations such as:

target/config/comps/vxWorks

and the active BSP directory.

Therefore, placing a CDF directly inside the BSP directory can be enough for Workbench to discover and display the component.

However, CDF discovery and module resolution are separate operations.

Workbench may successfully find:

DRV_DMA_FSL.cdf

while failing to resolve:

vxbFslDma.o

The result is a component that appears in the GUI but remains grayed out or italicized.

CDF Location Does Not Automatically Define the Module Search Path
#

This distinction is particularly important when keeping driver source files inside the BSP:

BSP/
├── Makefile
├── config.h
├── sysLib.c
├── vxbFslDma.c
├── vxbFslDma.o
└── DRV_DMA_FSL.cdf

The presence of vxbFslDma.o beside the CDF does not necessarily mean that:

MODULES vxbFslDma.o

will resolve correctly.

The MODULES dependency is evaluated according to the VxWorks build system’s module search rules rather than simply relative to the CDF’s physical location.

🛠️ Solution 1: Remove `MODULES` and Use `EXTRA_MODULES`
#

One straightforward approach is to let the BSP Makefile manage the object file instead of declaring it through MODULES.

Remove:

MODULES vxbFslDma.o

from the CDF:

Component DRV_DMA_FSL {
    NAME        Freescale DMA Controller Driver
    SYNOPSIS    Freescale DMA Controller Driver
    REQUIRES    INCLUDE_VXBUS \
                INCLUDE_PLB_BUS \
                INCLUDE_DMA_SYS
    _CHILDREN   FOLDER_DRIVERS
    INIT_RTN    vxbFslDmaRegister();
    PROTOTYPE   void vxbFslDmaRegister(void);
    _INIT_ORDER hardWareInterFaceBusInit
    INIT_AFTER  INCLUDE_PLB_BUS
}

Then add the object module to the BSP Makefile:

EXTRA_MODULES += vxbFslDma.o

This separates two responsibilities:

The CDF describes the configurable component and its initialization dependencies.
The Makefile tells the BSP build system which object modules must be linked.

This is often the cleanest solution when the driver is tightly coupled to a specific BSP.

When This Approach Is Preferable
#

Using EXTRA_MODULES is particularly useful when:

The driver source belongs exclusively to the BSP.
The driver does not need to be distributed as a reusable VxWorks component.
You want the BSP Makefile to control compilation and linking.
You want to avoid depending on global VxWorks module search paths.

The resulting architecture is simple:

CDF
 │
 ├── Component definition
 ├── REQUIRES dependencies
 └── INIT_RTN
       │
       ▼
BSP Makefile
       │
       └── EXTRA_MODULES
               │
               ▼
          vxbFslDma.o

📁 Solution 2: Specify the Source Through `CONFIGLETTES`
#

Another option is to explicitly associate the source file with the component using CONFIGLETTES.

For example:

Component DRV_DMA_FSL {
    NAME        Freescale DMA Controller Driver
    SYNOPSIS    Freescale DMA Controller Driver

    CONFIGLETTES ../../../config/bsp/vxbFslDma.c

    REQUIRES    INCLUDE_VXBUS \
                INCLUDE_PLB_BUS \
                INCLUDE_DMA_SYS

    _CHILDREN   FOLDER_DRIVERS

    INIT_RTN    vxbFslDmaRegister();
    PROTOTYPE   void vxbFslDmaRegister(void);

    _INIT_ORDER  hardWareInterFaceBusInit
    INIT_AFTER   INCLUDE_PLB_BUS
}

The important difference is that the CDF now explicitly provides the source-file path:

CONFIGLETTES ../../../config/bsp/vxbFslDma.c

This allows the configuration system to locate the source without relying on the implicit module resolution behavior of:

MODULES vxbFslDma.o

Choosing Between `MODULES` and `CONFIGLETTES`
#

The two mechanisms serve different purposes.

MODULES is primarily concerned with object modules participating in the build:

MODULES vxbFslDma.o

CONFIGLETTES provides an explicit path to configuration-related source content:

CONFIGLETTES ../../../config/bsp/vxbFslDma.c

Therefore, the correct choice depends on how the driver is integrated into the BSP build system.

If the driver is already compiled and managed as a BSP object, EXTRA_MODULES is generally more straightforward.

If the source itself must be explicitly referenced by the component configuration, an appropriate CONFIGLETTES path can be used.

🔧 Recommended BSP Integration Pattern
#

For BSP-specific drivers, a clean organization is to keep the component description, source code, and build configuration clearly separated:

BSP/
├── Makefile
├── config.h
├── sysLib.c
├── vxbFslDma.c
├── vxbFslDma.h
└── DRV_DMA_FSL.cdf

The CDF should describe the logical component:

Component DRV_DMA_FSL {
    NAME        Freescale DMA Controller Driver
    SYNOPSIS    Freescale DMA Controller Driver

    REQUIRES    INCLUDE_VXBUS \
                INCLUDE_PLB_BUS \
                INCLUDE_DMA_SYS

    _CHILDREN   FOLDER_DRIVERS

    INIT_RTN    vxbFslDmaRegister();
    PROTOTYPE   void vxbFslDmaRegister(void);

    _INIT_ORDER  hardWareInterFaceBusInit
    INIT_AFTER   INCLUDE_PLB_BUS
}

The BSP Makefile handles the compiled module:

EXTRA_MODULES += vxbFslDma.o

This avoids unnecessarily coupling the CDF to a particular object-file search path.

🧩 Understanding the Dependency Chain
#

A useful way to troubleshoot grayed-out VxWorks components is to distinguish three separate layers:

CDF Discovery
     │
     ▼
Component appears in Workbench
     │
     ▼
Dependency Resolution
     │
     ├── REQUIRES
     ├── INIT_AFTER
     └── INIT_ORDER
     │
     ▼
Build Dependency Resolution
     │
     ├── MODULES
     ├── CONFIGLETTES
     └── Makefile / EXTRA_MODULES
     │
     ▼
Component becomes buildable

A CDF can therefore be visible while still being unavailable.

For example:

MODULES vxbFslDma.o

may fail because the object cannot be located, even though the component itself has already been successfully parsed.

This explains why moving the CDF into the BSP directory can make the component appear in Workbench without actually making it selectable.

⚠️ Common Troubleshooting Checks
#

When a VxWorks component remains grayed out or italicized, check the following items systematically.

1. Verify the CDF Is Being Discovered
#

Confirm that Workbench can locate the CDF in either the standard component directory or the active BSP directory.

If it does not appear at all, the problem is component discovery rather than dependency resolution.

2. Check `MODULES`
#

If the component contains:

MODULES vxbFslDma.o

verify that the build system can resolve the object module.

Do not assume that placing the object next to the CDF automatically makes it visible.

3. Check `REQUIRES`
#

Verify that all required components exist:

REQUIRES INCLUDE_VXBUS \
         INCLUDE_PLB_BUS \
         INCLUDE_DMA_SYS

A missing required component can also prevent the component from being selected.

4. Check Initialization Ordering
#

Statements such as:

_INIT_ORDER hardWareInterFaceBusInit
INIT_AFTER INCLUDE_PLB_BUS

must reference valid initialization groups and components.

Incorrect initialization dependencies can cause configuration problems even when the source module itself is valid.

5. Check the BSP Makefile
#

If the object is intentionally managed by the BSP build system, explicitly add it:

EXTRA_MODULES += vxbFslDma.o

This is often preferable to relying on implicit CDF module lookup.

🚀 Practical Takeaway
#

A grayed-out or italicized component in VxWorks Workbench does not necessarily indicate a problem with the CDF syntax itself. It often means that Workbench successfully discovered the component but could not resolve one of its dependencies.

The most important distinction is:

CDF discovery ≠ module resolution

If a BSP-specific driver is maintained entirely inside the BSP directory, a practical solution is to keep the CDF focused on component metadata and dependencies while allowing the BSP Makefile to manage the driver object:

/* CDF */
Component DRV_DMA_FSL {
    NAME        Freescale DMA Controller Driver
    SYNOPSIS    Freescale DMA Controller Driver

    REQUIRES    INCLUDE_VXBUS \
                INCLUDE_PLB_BUS \
                INCLUDE_DMA_SYS

    _CHILDREN   FOLDER_DRIVERS

    INIT_RTN    vxbFslDmaRegister();
    PROTOTYPE   void vxbFslDmaRegister(void);
}

# BSP Makefile
EXTRA_MODULES += vxbFslDma.o

This approach keeps BSP-specific source files under BSP control, avoids unnecessary changes to global VxWorks component directories, and eliminates one of the most common causes of unavailable custom components in Workbench.

For more reusable drivers intended to become independent VxWorks components, a conventional component-directory structure with properly defined CDF, source, build, and dependency metadata is generally more appropriate.