Mastering UART Programming in VxWorks 7 With VxBus and POSIX I/O

Mastering UART Programming in VxWorks 7 With VxBus and POSIX I/O

🚀 Introduction

#

The Universal Asynchronous Receiver-Transmitter (UART) remains one of the most fundamental communication interfaces in embedded systems. Despite the rise of high-speed buses and networked protocols, UART continues to play a critical role in:

• Board bring-up
• Debugging consoles
• Sensor communication
• Industrial control
• Bootloaders
• Device management
• Low-level diagnostics

In VxWorks 7, UART access is built on top of the modern VxBus driver framework, which abstracts hardware details behind a standardized device model and integrates seamlessly with the POSIX I/O subsystem.

Rather than manipulating UART registers directly, developers interact with serial devices using familiar system calls such as:

• open()
• read()
• write()
• ioctl()
• close()

This article provides a comprehensive technical guide to UART programming in VxWorks 7, including:

• VxBus architecture
• UART device interaction
• POSIX serial I/O
• Runtime configuration using ioctl()
• Concurrent read/write task design
• Production-ready C implementation
• Kernel component requirements
• Build and deployment workflow

The examples and explanations target experienced embedded and RTOS developers building production-grade serial communication systems.

🏗️ VxWorks 7 UART Architecture

#

VxWorks 7 uses the VxBus framework to standardize hardware driver integration across architectures and BSPs.

Instead of binding applications directly to hardware-specific implementations, VxBus introduces a layered abstraction model.

VxWorks UART Software Stack

#

+--------------------------------------------------+
|               VxWorks Application                |
+--------------------------------------------------+
                         |
                         v  (POSIX: open, read, write, ioctl)
+--------------------------------------------------+
|                I/O System (iosLib)               |
+--------------------------------------------------+
                         |
                         v  (ttyDrv / sioLib)
+--------------------------------------------------+
|               VxBus Serial Driver                |
+--------------------------------------------------+
                         |
                         v  (Hardware Registers)
+--------------------------------------------------+
|                  Physical UART                   |
+--------------------------------------------------+

Core Architectural Components

#

VxBus

#

Provides:

• Driver registration
• Device discovery
• Resource management
• Hardware abstraction
• BSP integration

iosLib

#

The VxWorks I/O subsystem responsible for:

• File descriptor management
• Device lookup
• POSIX API routing

ttyDrv / sioLib

#

These layers provide terminal and serial abstractions:

• TTY device handling
• Buffer management
• UART configuration interfaces
• Hardware option controls

Physical UART Driver

#

The lowest layer interacts directly with:

• UART registers
• FIFOs
• Interrupts
• DMA engines
• Clock configuration

Applications remain isolated from hardware-specific implementation details.

⚙️ UART Device Registration in VxWorks

#

When a VxBus serial driver initializes, it registers one or more UART devices into the VxWorks I/O device table.

Typical device names include:

/tyCo/0
/tyCo/1
/tyCo/2

Applications open these device nodes using standard POSIX APIs.

Example:

fd = open("/tyCo/1", O_RDWR, 0);

The returned file descriptor becomes the primary interface for:

• Reading incoming serial data
• Writing outgoing data
• Runtime UART configuration

💻 Complete UART Programming Example

#

The following implementation demonstrates a production-style UART communication module for VxWorks 7.

Key Features

#

The example includes:

• UART initialization
• Baud rate configuration
• Hardware option configuration
• Raw mode operation
• Concurrent asynchronous reading
• Blocking I/O handling
• Buffer flushing
• Graceful task management

📄 Full Source Code

#

#include <vxWorks.h>
#include <ioLib.h>
#include <sioLib.h>
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <taskLib.h>

#define UART_DEV_NAME      "/tyCo/1"
#define BUFFER_SIZE        128

STATUS uart_configure(int fd, int baudRate);
void uart_read_task(int fd);

/*******************************************************************************
*
* uart_example_main - Main UART demonstration entry point
*
* RETURNS: OK or ERROR
*/
STATUS uart_example_main(void)
{
    int fd;
    const char *tx_msg = "Hello from VxWorks 7 UART!\r\n";

    printf("[UART_MAIN] Opening device: %s...\n", UART_DEV_NAME);

    fd = open(UART_DEV_NAME, O_RDWR, 0);

    if (fd == ERROR)
    {
        perror("[UART_MAIN] Error opening UART device");
        return ERROR;
    }

    if (uart_configure(fd, 115200) != OK)
    {
        printf("[UART_MAIN] UART configuration failed.\n");
        close(fd);
        return ERROR;
    }

    printf("[UART_MAIN] Transmitting data...\n");

    ssize_t bytesWritten = write(fd, tx_msg, strlen(tx_msg));

    if (bytesWritten == ERROR)
    {
        perror("[UART_MAIN] Write error");
        close(fd);
        return ERROR;
    }

    printf("[UART_MAIN] Successfully wrote %zd bytes.\n", bytesWritten);

    TASK_ID readTaskId =
        taskSpawn(
            "tUartRead",
            100,
            VX_FP_TASK,
            4096,
            (FUNCPTR)uart_read_task,
            fd, 0, 0, 0, 0, 0, 0, 0, 0, 0);

    if (readTaskId == TASK_ID_ERROR)
    {
        perror("[UART_MAIN] Failed to spawn read task");
        close(fd);
        return ERROR;
    }

    return OK;
}

/*******************************************************************************
*
* uart_configure - Configure UART parameters
*
* RETURNS: OK or ERROR
*/
STATUS uart_configure(int fd, int baudRate)
{
    if (ioctl(fd, FIOBAUDRATE, baudRate) == ERROR)
    {
        perror("[UART_CONF] Failed to set Baud Rate");
        return ERROR;
    }

    if (ioctl(fd, FIOSETOPTIONS, OPT_RAW) == ERROR)
    {
        perror("[UART_CONF] Failed to enable RAW mode");
        return ERROR;
    }

    int hwOptions = CS8 | STOPB;

    if (ioctl(fd, SIO_HW_OPTS_SET, hwOptions) == ERROR)
    {
        perror("[UART_CONF] Failed to configure hardware options");
        return ERROR;
    }

    if (ioctl(fd, FIOFLUSH, 0) == ERROR)
    {
        perror("[UART_CONF] Failed to flush buffers");
        return ERROR;
    }

    printf("[UART_CONF] UART configured successfully (8N1).\n");

    return OK;
}

/*******************************************************************************
*
* uart_read_task - UART receive task
*/
void uart_read_task(int fd)
{
    char rxBuffer[BUFFER_SIZE];
    ssize_t bytesRead;

    printf("[UART_READ] Read task started.\n");

    while (1)
    {
        memset(rxBuffer, 0, sizeof(rxBuffer));

        bytesRead = read(fd, rxBuffer, sizeof(rxBuffer) - 1);

        if (bytesRead > 0)
        {
            rxBuffer[bytesRead] = '\0';

            printf(
                "[UART_READ] Received %zd bytes: %s\n",
                bytesRead,
                rxBuffer);

            if (strncmp(rxBuffer, "QUIT", 4) == 0)
            {
                printf("[UART_READ] Quit command received.\n");
                break;
            }
        }
        else if (bytesRead == ERROR)
        {
            perror("[UART_READ] Read error");
            break;
        }
    }

    close(fd);
}

🔍 Understanding the VxWorks I/O Subsystem

#

The open() call interacts with the VxWorks I/O system managed by:

• iosLib

Internally, VxWorks performs:

1. Device table lookup
2. Driver resolution
3. File descriptor allocation
4. Driver instance binding

When opening:

"/tyCo/1"

the I/O subsystem maps the path to the appropriate VxBus serial driver instance.

This design provides:

• Hardware abstraction
• Portability across BSPs
• Unified driver interfaces
• POSIX compatibility

⚡ UART Configuration Using ioctl()

#

Most UART runtime configuration occurs through:

• ioctl()

This API forwards device-specific control requests to the underlying serial driver.

🧠 Baud Rate Configuration

#

ioctl(fd, FIOBAUDRATE, baudRate);

This request instructs the driver to:

• Calculate UART clock divisors
• Program baud rate generator registers
• Update internal timing configuration

Typical supported rates include:

• 9600
• 19200
• 38400
• 57600
• 115200
• Higher custom rates depending on hardware

🧵 RAW Mode vs Line Mode

#

By default, some VxWorks serial channels initialize in:

• OPT_LINE

mode.

Line mode may perform:

• Line buffering
• Echo handling
• Backspace processing
• Newline translation

This behavior is unsuitable for most embedded binary protocols.

Enabling raw mode:

ioctl(fd, FIOSETOPTIONS, OPT_RAW);

disables all line processing.

In raw mode:

• Bytes are delivered immediately
• No newline interpretation occurs
• Binary payloads remain unmodified

This is essential for:

• Protocol parsers
• Binary communication
• Sensor interfaces
• Industrial serial devices

🔧 Hardware Option Configuration

#

Hardware framing parameters are configured using:

ioctl(fd, SIO_HW_OPTS_SET, hwOptions);

Example Configuration

#

int hwOptions = CS8 | STOPB;

This configures:

• 8 data bits
• 1 stop bit
• No parity

Common UART Framing Options

#

Actual behavior may vary slightly depending on the BSP and UART controller implementation.

🔄 Buffer Flushing

#

UART FIFOs and software ring buffers may contain stale data during startup.

The following call clears both receive and transmit buffers:

ioctl(fd, FIOFLUSH, 0);

This helps avoid:

• Garbage data
• Partial frames
• Initialization artifacts

during startup sequences.

🧵 Task-Based UART Concurrency

#

VxWorks is a deterministic multitasking RTOS.

Blocking Read Behavior

#

In raw mode:

read()

typically blocks until data becomes available.

If UART reading occurs in the main task, the application could stall indefinitely waiting for input.

🚦 Using taskSpawn() for Asynchronous Reading

#

To avoid blocking the primary application flow, UART reading is delegated to a dedicated task.

Example:

taskSpawn(...)

This creates an independent execution context:

• tUartRead

Advantages of Dedicated UART Tasks

#

This design enables:

• Asynchronous serial reception
• Concurrent transmit/receive operation
• Better responsiveness
• Deterministic scheduling
• Simplified protocol parsing

Since VxWorks tasks share the same address space, the file descriptor can safely be shared across tasks.

📦 Required Kernel Components

#

To successfully build and run the UART example, several VxWorks kernel components must be included in the VIP configuration.

Required Components

#

Without these components, serial devices may not initialize correctly.

🛠️ Compilation Workflow

#

The code can be compiled using:

• Wind River Workbench
• Command-line cross compiler

Example ARM Build Command

#

ccarm \
    -march=armv7-a \
    -mfloat-abi=hard \
    -O2 \
    -I$WIND_BASE/target/h \
    -D_WRS_KERNEL \
    -c uart_example.c \
    -o uart_example.o

Compiler flags vary depending on:

• Architecture
• BSP
• Toolchain
• Floating-point configuration

🚀 Loading and Executing on Target

#

After compilation, the object module can be loaded into the target system.

Load Module

#

-> ld < uart_example.o

Execute Entry Function

#

-> uart_example_main

Successful execution should:

1. Open the UART device
2. Configure serial parameters
3. Transmit startup data
4. Spawn asynchronous receive task
5. Begin continuous UART listening

🛡️ Production Considerations

#

Production UART systems often require additional robustness features.

Recommended Enhancements

#

Timeouts

#

Consider using:

• select()
• Non-blocking I/O
• Timer watchdogs

to prevent indefinite blocking.

Ring Buffers

#

High-throughput systems should implement:

• Circular buffers
• Lock-free queues
• DMA-assisted reception

for improved scalability.

Synchronization

#

Shared UART resources may require:

• Semaphores
• Mutexes
• Message queues

to coordinate concurrent access safely.

Error Handling

#

Production code should monitor:

• Framing errors
• Overrun conditions
• Parity errors
• Disconnect events

through driver-specific status interfaces.

🏁 Conclusion

#

UART programming in VxWorks 7 combines the determinism of a real-time operating system with the flexibility of a modern POSIX-style I/O framework.

Through the VxBus infrastructure, developers gain:

• Hardware abstraction
• Portability
• Standardized APIs
• Driver modularity

while retaining full access to low-level serial configuration and high-performance communication.

By leveraging:

• open()
• read()
• write()
• ioctl()
• taskSpawn()

developers can build reliable and scalable UART communication systems suitable for:

• Industrial automation
• Aerospace platforms
• Embedded Linux migration projects
• Board support package development
• High-reliability RTOS applications

Mastering the interaction between VxBus, the VxWorks I/O subsystem, and UART device drivers is essential for building production-grade embedded communication software on VxWorks 7.