1
Transitioning Device Software
from Kernel Space
to Multiple Real Time
Processes
Migrate VxWorks 5.x projects into
VxWorks 6.x and gain access for the latest
Wind River DSO technologies
2
The demo Use Case
Producer
tProducer
allocate
Consumer
send
msgData
fill
struct SinVal
receive
tConsumer
print
Message
Queue
free
struct SinVal
This training is based on the simple producer-consumer example - running 2 tasks:
Producer - a task that constantly creates data, including a sine value. The data gets
allocated on the heap and sent via message queue.
Consumer - a task that fetches the data from the producer and “consumes” it. It will print
feedback to the shell and it will free the memory allocated for this data package.
NOTE: The demo code comes with errors - that it includes a memory leakage and a non-performant code piece. There is also
a bug that prevents the consumer from displaying correct data. You will use tools in Wind River Workbench to show where
these problems are.
3
Import code into Downloadable Kernel Module
Downloadable Kernel Module
Note: DKM stands for Download Kernel Module.
–
•
•
•
This is the well known OUT-File from VxWorks 5.5
Select File > New > VxWorks Downloadable Kernel Module Project
from the menu bar of Wind River Workbench
The New Downloadable Kernel Module
Project wizard appears:
Specify the name of the new project:
ProdConsDemo
•
4
Click Next
Import code into Downloadable Kernel Module
Downloadable Kernel Module
5
•
In the Project Structure dialog make sure no boxes are checked in the
Referenced subprojects pane.
•
Click Next
Import code into Downloadable Kernel Module
Downloadable Kernel Module
6
•
On the Build Setup and Defaults dialog,
make sure Standard is selected.
•
Click Next
Import code into Downloadable Kernel Module
Downloadable Kernel Module
7
•
Leave the Build Support dialog as it is.
•
Click Next
Import code into Downloadable Kernel Module
Downloadable Kernel Module
8
•
On the Build Specs dialog select PPC32gnu as Active build spec.
You might want to deselect all build rules first and then select just the PPC32gnu
•
Click Finish
Import code into Downloadable Kernel Module
Downloadable Kernel Module
•
9
Finally you see the new DKM project in the Project Navigator view:
•
•
•
•
•
•
10
Import code into Downloadable Kernel Module
Downloadable Kernel Module
This is finally the stage where we migrate (import) our source code into VxWorks 6.3
As the DKM project is an empty framework, we now go and import the source code.
Select Import from the context menu of the new DKM project in the Project Navigator view
The Import wizard appears.
On the Select dialog:
Select File System
Click Next
Import code into Downloadable Kernel Module
Downloadable Kernel Module
•
•
In the File system dialog, click Browse
The Import from directory dialog appears:Navigate to
C:\vx5-to-vx6\chapter3\wrwb_demo\prodconsdemo\kernel_module
Click OK
11
Import code into Downloadable Kernel Module
Downloadable Kernel Module
•
Back in the File system dialog, click the box on the left pane to select the
folder “kernel_module”
•
12
Click Finish
Import code into Downloadable Kernel Module
Downloadable Kernel Module
•
13
Finally open the ProdConsDemo project folder in the Project Navigator view
to see the project contents:
Import code into Downloadable Kernel Module
Downloadable Kernel Module
•
•
•
•
14
Select Build Project from the context menu of the ProdConsDemo project in
the Project Navigator view
The Build dialog shown here appears.
We ignore this for now.
Click Continue.
Once the build is complete the dialog
disappears anyhow. The output can be seen
on the Build Console view of Wind River
Workbench
Import code into Downloadable Kernel Module
Downloadable Kernel Module
•
•
•
15
Open the Terminal view within Workbench and connect to COM1 (9600baud)
PowerCycle your board board on and let it boot.
Wait till the VxWorks banner is out and WDB is ready:
Create Target Server and connect to the board
Downloadable Kernel Module
16
•
•
Select Target > New Connection from the menu bar of Wind River Workbench
In the Connection Type dialog select
WindRiver
VxWorks 6.x Target Server Connection
•
Click Next
Create Target Server and connect to the board
Downloadable Kernel Module
17
•
In the Target Server Options dialog
enter the IP address of your target:
•
Click Next
Create Target Server and connect to the board
Downloadable Kernel Module
18
•
Leave the Object Path Mappings
dialog unchanged.
•
Click Next
Create Target Server and connect to the board
Downloadable Kernel Module
19
•
Leave the Target State Refresh
dialog unchanged.
•
Click Next
Create Target Server and connect to the board
Downloadable Kernel Module
•
In the Connection Summary dialog
change the connection name to:
powerquicc2.
•
20
Click Finish
Create Target Server and connect to the board
Downloadable Kernel Module
21
•
Notice the new entry called powerquicc2 in the Target Manager view of Wind
River Workbench.
•
Notice further that the
connection gets established
automatically upon creation,
•
Open the tree named Kernel Tasks
in order to see the tasks
running already on the target
Download and Run Kernel Module
•
Select Run Kernel Task from the context menu of the
ProdConsDemo project in the Project
Navigator view
•
The Create, manage,
and run configurations
dialog appears:
•
Enter vStart into the
field labeled Entry Point
22
Download and Run Kernel Module (cont’)
23
•
On the Downloads pane you can see which downloadable kernel
modules are loaded by this
Run Configuration
•
By default - it is
ProdConsDemo.out
our new DKM module.
•
Other modules could
be added, if needed.
Download and Run Kernel Module (cont’)
• On the Projects to Build pane you can see which projects are
rebuilt by this Run Configuration
24
•
Again, by default it is our
new DKM.
•
Other projects could
be added, if needed.
•
Click Run to start this
Run Configuration
Download and Run Kernel Module (cont’)
•
In the Terminal your should now see the output of the running code.
• You can also open up the
Kernel Tasks tree on the
powerquicc2 connection in the
Target Manager view.
There are now two new tasks
called tProducer and tConsumer.
•
25
You could also debug those tasks now by their context menu (Attach).
Download and Run Kernel Module (cont’)
As long as you just talk about pure application code porting,
the transition from VxWorks 5.x to VxWorks 6.3 took place !
It can be that easy for many of your customers.
Of course there are other situations out there where it takes more than that.
For example when you touch
- The new file system framework
- Custom BSPs without MMU definitions
- Tornado or Sniff based customer build scenarios
Learn about your customers requirements and his application, to be able to
provide him with a smooth migration work flow process.
26
Migrate DKM to “One” Real Time Process
27
Preparations - setup environment
Make sure your board runs a VxWorks 6.3 bootloader.
If not, use a WindRiverPROBE to program the bootloader into flash.
(A prebuild image can be found in C:\Vx5-to-Vx6\chapter1\VxWorks_6.3_prebuild)
Configure the bootloader.
As for the vxWorks image use this path: C:\vx5-to-vx6\boot\vxWorks
As for the host name use host
Launch Workbench 2.5 from
C:\vx5-to-vx6\workbench-2.5\wrwb\platform\eclipse\x86-win32\bin\wrwb.exe
For the workspace, point to (or switch to)
C:\vx5-to-vx6\workspace3
28
Preparations, setup environment
By default, the project Navigator comes up with a
pre- configured VxWorks 6.3 image project.
Learn about the cp2boot build rule and the cp2boot.makefile
(This will copy your output file to a dedicated boot folder)
Launch FTP server from C:\ vx5-to-vx6 \vxworks-6.3\host\x86win32\bin\wftpd32.exe
(make sure you have the same account name & password specified, like in the
bootloader)
Build the VxWorks image.
You are now done with the preparations.
29
Migrate DKM to “one” Real Time Process
• Step 1: Create Real Time Process Project
• Step 2: Import Source Code from
C:\vx5-to-vx6\chapter3\prodconsdemo\kernel_module
•
•
•
•
•
Step 3: Build the project
Step 4: Add RTP functionality to VxWorks project
Step 5: Rebuild VxWorks and reboot target
Step 6: Modify Target Server Connection
Step 7: Run the RTP
We now continue to transfer the same demo source code
(The ProdConsDemo coming from the Kernel_Module folder)
into a single RTP
30
Create Real Time Process Project
•
•
•
•
Note: RTP stands for Real Time Process.
Select File > New > VxWorks Real Time Process Project from the menu bar of Wind
River Workbench
The New VxWorks Real Time Process
Project wizard appears:
Specify the name of the new project:
ProdConsDemo_One_RTP
•
31
Click Next
Create Real Time Process Project
•
On the Project Structure dialog make sure no boxes are checked in the Referenced
subprojects pane.
•
Click Next
32
Create Real Time Process Project
•
On the Build Setup and Defaults dialog,
make sure Standard is selected.
•
Click Next
33
Create Real Time Process Project
•
Leave the Build Support dialog as it is.
•
Click Next
34
Create Real Time Process Project
•
On the Build Specs dialog select PPC32gnu_RTP as Active build spec
•
Click Finish
35
Import Source Code
•
•
•
Select Import from the context menu of the new project in the Project Navigator view
The Import wizard appears
with the Select dialog:
Select File System
•
Click Next
36
Import Source Code
•
•
In the File system dialog, click Browse
The Import from directory navigate to
C:\vx5-to-vx6\chapter3\wrwb_demo\prodconsdemo\kernel_module
•
37
Click OK
Import Source Code
•
Back in the File system dialog, click the box on the left pane to select the folder
•
Click Finish
38
Build the project
•
•
Select Build Project from the context menu of the ProdConsDemo_One_RTP project in
the Project Navigator view
The dialog on the right appears.
•
Click Continue.
•
As the build fails, error messages (in red) appear in the Build Console view of Wind River
Workbench. Double click on the first error message line
39
Add RTP functionality to VxWorks project
•
•
40
The source file library.c opens up in the editor view of Wind River Workbench
Note the tooltip of the
error icon left to the
erroneous line shows
the compiler error
message
Add RTP functionality to VxWorks project
• library.c makes use of wdLib
– wdLib is a kernel only API which is not available for Real Time
Processes!
– Why: Because it requires use of interrupt context !
• Resolution:
– wdLib is used here to measure runtime of a loop.
– modify program logic to use task and taskDelay instead
• Note: modification can be filtered to have common source for
kernel and RTP:
– Use predefined _WRS_KERNEL macro defined in build for kernel only:
#ifdef _WRS_KERNEL
<old code for use inside kernel only>
#else
<code for use inside of RTP>
#endif
41
Add RTP functionality to VxWorks project
#include "wdLib.h"
void calibrateInt(int *wdRunning)
{
*wdRunning = 0;
}
Old scenario – for
KERNEL MODE ONLY
void calibrateLoop()
{
WDOG_ID wd = wdCreate();
static int wdRunning = 1;
MAX_CNT = 0;
wdStart(wd, sysClkRateGet(), (FUNCPTR)calibrateInt, (int)&wdRunning);
for(MAX_CNT=0;wdRunning;MAX_CNT++) ;
MAX_CNT /= 1000;
/* printf ("calib: %d\n", MAX_CNT); */
wdDelete (wd);
}
42
Add RTP functionality to VxWorks project
#include "semLib.h"
void calibrationTask(SEM_ID startSem, int *wdRunning)
{
semTake(startSem, WAIT_FOREVER);
taskDelay(sysClkRateGet());
*wdRunning = 0;
semDelete(startSem);
}
New scenario – good
for RTP MODE
void calibrateLoop()
{
volatile static int wdRunning = 1;
int myPrio = -1;
SEM_ID startSem = semBCreate(SEM_Q_PRIORITY, SEM_EMPTY);
MAX_CNT = 0;
taskPriorityGet(taskIdSelf(),&myPrio);
taskSpawn("tCalibration",myPrio-1,0,0x1000, (FUNCPTR)calibrationTask,
(int)startSem,(int)&wdRunning,3,4,5,6,7,8,9,0);
semGive(startSem);
for(MAX_CNT=0;wdRunning;MAX_CNT++) ;
MAX_CNT /= 1000;
}
43
Add RTP functionality to VxWorks project
•
44
Edit the source file library.c to replace wdLib usage
Add RTP functionality to VxWorks project
Note: There is a wrwb_demo_solution directory that already has all the proper changes!
Use those files as copy&paste resource or as generic solution backup.
The folder to look for is: C:\KernelToRtp\wrwb_demo_solution
45
Add RTP functionality to VxWorks project
•
•
•
Select Build Project from the context menu of the ProdConsDemo_One_RTP project in
the Project Navigator view to continue with the build.
As you can see, compilation works fine now.
However the build still fails during the linker run:
Why does it still not build ?
Because an RTP always needs a function main() !
46
Add RTP functionality to VxWorks project
• From VxWorks, 6.3 Application Programmer's Guide,
2.4.1:
VxWorks applications have a simple structural requirement that is common to C
programs on other operating systems—they must include a main( ) routine.
The main( ) routine can be used with the conventional argc and argv
arguments, as well as two additional optional arguments, envp and auxp:
int main
(
int argc,
/* number of arguments */
char * argv[], /* null-terminated array of argument strings */
char * envp[], /* null-terminated array of environment
variable strings */
void * auxp
/* implementation specific auxiliary vector */
);
The argv[0] argument is typically the relative path to the executable.
47
Add RTP functionality to VxWorks project
• From VxWorks, 6.3 Application Programmer's Guide, 2.3.1:
VxWorks processes can be started in a variety of ways:
•
•
•
•
interactively from the kernel shell
interactively from the host shell and debugger
automatically at boot time, using a startup facility
programmatically from applications or the kernel
Processes are terminated under the following circumstances:
•
•
•
•
•
•
When the last task in the process exits.
If any task in the process calls exit( ), regardless of whether or not other tasks are running in the
process.
If the process' main( ) routine returns.
If the kill( ) routine is used to terminate the process.
If rtpDelete( ) is called on the process—from a program, a kernel module, the C interpreter of the shell,
or from the host IDE. Or if the rtp delete command is used from the shell's command interpreter.
If a process takes an exception during its execution.
This default behavior can be changed for debugging purposes. When the error detection
and reporting facilities are included in the system, and they are set to debug mode,
processes are not terminated when an
48
exception occurs.
Add RTP functionality to VxWorks project
rtpSpawn( )
NAME
rtpSpawn( ) - spawns a new Real Time Process (RTP) in the system
SYNOPSIS
RTP_ID rtpSpawn
(
const char * rtpFileName,
const char * argv[],
const char * envp[],
int priority,
int uStackSize,
int options,
int taskOptions
)
49
/*
/*
/*
/*
/*
/*
/*
Null terminated path to executable */
Pointer to NULL terminated argv array */
Pointer to NULL terminated envp array */
Priority of initial task */
User space stack size for initial task */
The options passed to the RTP */
Task options for the RTP's initial task */
Add RTP functionality to VxWorks project
Add following code to the end of ProdConsDemo.c
#include "taskLib.h"
extern int vStart();
int main (int argc, char **argv)
{
vStart();
/* don't return - return means end of RTP */
taskSuspend(0);
return 0;
}
This text should be o.k. to use it as a copy&paste resource
50
Rebuild VxWorks and reboot target
•
The pq2Standard we have use as starting point supports kernel mode
only! In order to use Real Time Processes we need a new kernel image.
•
•
Select File > New > VxWorks Image Project from the menu bar of Wind River
Workbench
The New VxWorks Image Project wizard appears:
•
Specify the name of the new project:
pq2ForRTP
•
51
Click Next
Rebuild VxWorks and reboot target
•
On the Project Setup dialog change selection from A board support package to
An existing VxWorks Image project
•
Click Finish
52
Rebuild VxWorks and reboot target
•
•
•
53
You’ll get a new entry in the Project Navigator view in Wind River Workbench.
Open the new project. There are already a couple of source files created for the kernel
project.
Double click on the item Kernel Configuration in the project.
Rebuild VxWorks and reboot target
•
The VxWorks Image Configurator
is displayed in the editor view
of Wind River Workbench.
•
The Components pane is selected.
•
Switch to the Bundles pane
54
Rebuild VxWorks and reboot target
•
•
•
55
From the available
bundles select Real
Time Process
Development
The components of this
bundle show up on the
right side.
Click Add Bundle
Rebuild VxWorks and reboot target
•
The Include dialog comes up which lists the components to include and any components
required by them. Also the dialog calculates the increase in size of the VxWorks Image
•
Click Finish
56
Create Target Server and connect to the board
Downloadable Kernel Module
•
•
•
57
Real Time Processes are loaded from a file system. Therefore we must tell the Target
Manager of Wind River Workbench how to access our Real Time Process built on the host
from the VxWorks running on the target. Object Path Mappings provide this information.
To set these mappings, select Properties from the
context menu of the powerquicc2 connection in the
Target Manager.
In the Edit the target connection dialog switch to
the Object Path Mappings pane.
Create Target Server and connect to the board
Downloadable Kernel Module
•
•
In the Object Path Mappings pane click Add
In the dialog enter a mapping from
target path
host:c:/
to
C:\
•
Click OK
58
Create Target Server and connect to the board
Downloadable Kernel Module
•
In the Properties pane dialog you can see
the new mapping topmost.
•
Click OK
59
Run the RTP
•
•
•
60
Select Run RTP on Target from the context menu of the ProdConsDemo_One_RTP
project in the Project
Navigator view
The Create, manage,
and run configurations
dialog appears
Click Run to start this
Run Configuration
Run the RTP
•
You should now see the output of the running program via COM1
Note: Due to the BETA version of
Workbench 2.5 it most likely comes to
problems in this area. The target agent
will not pick up the RTP mechanism.
You have to re-start Workbench
then. Also – you might want to kill the
Eclipse.exe, dfwserver.exe, jawaw.exe in the
Windows TaskManager
If you see problems launching your RTP,
double check the PathMappings in your target
Connection – remove the mapping that you did
Apply and give it a try. Also - double check on the host name that
You have specified in the bootloader.
61
Wind River, the global
leader in device software
optimization (DSO), enables
companies to develop and
run software faster, better,
at lower cost, and more
reliably.
62