Introduction #
Containers provide a powerful way to package VxWorks applications, isolating them from the rest of the system. With VxWorks, you can transform applications into containers, upload them to DockerHub (a cloud-based repository for container images) and deploy them to VxWorks target boards like the Raspberry Pi 4 Model B.
In this guide, I’ll walk you through converting a sample VxWorks Real-Time Process (RTP) into a container, pushing it to DockerHub, and running it on a VxWorks system. VxWorks, developed by Wind River, is a robust Real-Time Operating System (RTOS) with a board support package (BSP) tailored for the Raspberry Pi 4, an affordable, compact single-board computer.
Before proceeding, ensure you’ve completed the setup in ‘Using VxWorks 7 Containers With DockerHub on a Raspberry Pi 4 Model B Board’.
Prerequisites #
To follow this guide, you’ll need:
Hardware: #
- Raspberry Pi 4 Model B (4GB RAM) running VxWorks
- USB-to-Serial TTL cable
- Micro-SD card
Software: #
- Windows workstation with Wind River VxWorks 7 (SR21.07) installed
Accounts and Tools: #
- DockerHub account (sign up at hub.docker.com)
- Workstation configured with the buildah utility (see VxWorks Container Programmer’s Guide: Configure the Build Workstation for Containers)
Related Resources #
For deeper insights, consult:
- VxWorks Container Programmer’s Guide (Wind River documentation)
Setting Up Container-Enabled VxWorks Projects #
Let’s prepare the VxWorks environment for containers.
Build the VxWorks Source Build (VSB) Project #
Open a Windows command shell and set up the VxWorks environment:
cd <WIND_HOME> // Your VxWorks installation directory
wrenv -p vxworks\21.07
cd <YOUR_WORKSPACE> // Your workspace directory
Create and configure the VSB project for Raspberry Pi 4:
vxprj vsb create -S -bsp rpi_4 -smp rpiVSB
cd rpiVSB
vxprj vsb layer add CONTAINER_RUNTIME
vxprj vsb layer add CONTAINER_MANAGER
vxprj vsb layer add PYTHON
vxprj vsb layer add CONTAINER_EXAMPLES
vxprj vsb config -s -add _WRS_CONFIG_CONTAINER_PYTHON_WEB_SERVER=y
Build the VSB:
vxprj vsb build -j 16
cd ..
Create the VxWorks Image Project (VIP) #
Generate the VIP:
vxprj vip create -vsb rpiVSB llvm -profile PROFILE_DEVELOPMENT rpiVIP
cd rpiVIP
Add container and filesystem components:
vxprj vip component add INCLUDE_CONTAINER_RUNTIME INCLUDE_CONTAINER_SHELL_CMD
vxprj vip component add INCLUDE_DISK_UTIL INCLUDE_RAM_DISK INCLUDE_OVERLAY_FS
vxprj vip parameter set RAM_DISK_SIZE 0x4000000
vxprj vip component add INCLUDE_STANDALONE_SYM_TBL INCLUDE_STANDALONE_DTB
vxprj vip component add INCLUDE_PYTHON_SUPPORT INCLUDE_ROMFS
mkdir romfs
Enable Public Internet Access #
Configure networking:
vxprj vip component add INCLUDE_CONTAINER_MANAGER INCLUDE_IPDNSC
vxprj vip component add INCLUDE_PING INCLUDE_IFCONFIG
vxprj vip parameter setstring DNSC_PRIMARY_NAME_SERVER "8.8.8.8"
vxprj vip parameter set SEC_VAULT_KEY_ENCRYPTING_PW "vault_passwd"
vxprj vip component add INCLUDE_IPCOM_USE_TIME_CMD
Note: Use a strong password for SEC_VAULT_KEY_ENCRYPTING_PW (mix of uppercase, lowercase, and numbers). On Linux hosts, escape the string: \"vault_passwd\".
Add Raspberry Pi 4 Components #
vxprj vip component add DRV_END_FDT_BCM_GENETv5 INCLUDE_XBD_PART_LIB
vxprj vip component add DRV_FDT_BRCM_2711_PCIE DRV_FDT_BRCM_2711_EMMC2
vxprj vip component add DRV_SDSTORAGE_CARD
Add Container Certificate #
mkdir romfs\vxc\ca-certs
copy ..\..\vxworks\21.07\os\container\manager\ca-certs\ca-certificates.crt romfs\vxc\ca-certs\
Configure the Bootline #
Edit rpi_4_0_1_2_0\rpi-4b.dts, locate the chosen node, and update the bootargs. Example:
bootargs = "genet(0,0)host:vxworks h=192.168.1.105 e=192.168.1.107:ffffff00 g=192.168.1.1 u=target pw=vx tn=RPi4";
Build the VIP #
vxprj build
Create the Philosophers RTP Project #
This example uses the “Dining Philosophers” problem from Wind River Workbench to demonstrate synchronization in VxWorks.
- Open Wind River Workbench.
- Go to File > New > Example, select Philosophers Demonstration Program.
- Set rpiVSB as the VSB and build the RTP.
Containerize the Philosophers RTP #
Set Up the Container Directory #
cd <YOUR_WORKSPACE>
mkdir philContainer
Copy the RTP Executable #
copy philosophers\rpiVSB_ARMARCH8Allvm_LP64_ld\philosophers\Debug\philosophers.vxe philContainer\.
Create the Dockerfile #
In philContainer, create a file named Dockerfile (no .txt extension):
FROM scratch
WORKDIR /vxbin
COPY philosophers.vxe /vxbin
ENTRYPOINT ["philosophers.vxe"]
LABEL com.windriver.vxworks.rtp.rtpStackSize 0x400000
LABEL com.windriver.vxworks.rtp.rtpPriority 50
LABEL com.windriver.vxworks.rtp.rtpOptions 0x80
LABEL com.windriver.vxworks.rtp.rtpTaskOptions 0x00
Note: If your editor adds .txt, rename it: rename Dockerfile.txt Dockerfile.
Build the Container Image #
In philContainer:
wsl buildah bud --arch arm64 --os vxworks -f Dockerfile -t philosophers
cd ..
Push to DockerHub #
wsl buildah push philosophers oci:philosophers.oci
wsl buildah push --creds <dockerAccountName>:<dockerAccountPassword> philosophers docker://<dockerAccountName>/philosophers.oci
Replace <dockerAccountName> and <dockerAccountPassword> with your DockerHub credentials.
Deploy to the VxWorks Target #
Set the Date #
On the VxWorks shell:
-> cmd
[vxWorks *]# date 2025-02-22 // Use today's date
ok
Verify Connectivity #
[vxWorks *]# ping "www.google.com"
Wait for the Ethernet LEDs to stabilize if needed.
Pull and Unpack the Container #
[vxWorks *]# vxc pull <dockerAccountName>/philosophers.oci -k
[vxWorks *]# vxc unpack --image philosophers.oci --rootfs layered /ram0/bundle
Create and Inspect the Container #
[vxWorks *]# vxc create --bundle /ram0/philosophers phil
[vxWorks *]# cd /overlay/phil
[vxWorks *]# ls
Start the Container #
[vxWorks *]# vxc start phil
You’ll see output like:
Running claim-based solution.
Philosopher 1 is thinking...
Stop the Container #
[vxWorks *]# vxc kill phil