1. 2 Transitioning Device Software from Kernel Space to Multiple Real Time Processes Migrate VxWorks 5.x projects into VxWorks 6.x and gain access for

1

2

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

3

Producer

tProducer

Consumer

tConsumer

struct SinVal

allocate

fill

struct SinVal

print free

msgData

Message Queue

send receive

The demo Use Case

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.

4

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

• Click Next

Import code into Downloadable Kernel ModuleDownloadable Kernel Module

5

• In the Project Structure dialog make sure no boxes are checked in the Referenced subprojects pane.

• Click Next


6

• On the Build Setup and Defaults dialog, make sure Standard is selected.

• Click Next


7

• Leave the Build Support dialog as it is.

• Click Next


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


9

• Finally you see the new DKM project in the Project Navigator view:


10

• 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


11

• 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


12

• Back in the File system dialog, click the box on the left pane to select the folder “kernel_module”

• Click Finish


13

• Finally open the ProdConsDemo project folder in the Project Navigator view to see the project contents:


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


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:


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 boardDownloadable Kernel Module

17

• In the Target Server Options dialog enter the IP address of your target:

• Click Next


18

• Leave the Object Path Mappings

dialog unchanged.

• Click Next


19

• Leave the Target State Refresh

dialog unchanged.

• Click Next


20

• In the Connection Summary dialog change the connection name to:

powerquicc2.

• Click Finish


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


22

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

23

Download and Run Kernel Module (cont’)• On the Downloads pane you can see which downloadable kernel

modules are loaded by this Run Configuration

• By default - it is ProdConsDemo.outour new DKM module.

• Other modules couldbe added, if needed.

24

• On the Projects to Build pane you can see which projects are rebuilt by this Run Configuration

• Again, by default it is our new DKM.

• Other projects couldbe added, if needed.

• Click Run to start this Run Configuration

Download and Run Kernel Module (cont’)

25

• 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.

• You could also debug those tasks now by their context menu (Attach).


26

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.


27

Migrate DKM to “One” Real Time Process

28

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 fromC:\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

Preparations - setup environment

29

By default, the project Navigator comes up with apre- 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\x86-win32\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.

Preparations, setup environment

30

• 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

Migrate DKM to “one” Real Time Process

31

• 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

• Click Next

Create Real Time Process Project

32

• On the Project Structure dialog make sure no boxes are checked in the Referenced subprojects pane.

• Click Next


33

• On the Build Setup and Defaults dialog,

make sure Standard is selected.

• Click Next


34

• Leave the Build Support dialog as it is.

• Click Next


35

• On the Build Specs dialog select PPC32gnu_RTP as Active build spec

• Click Finish


36

• 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

Import Source Code

37

• In the File system dialog, click Browse• The Import from directory navigate to

C:\vx5-to-vx6\chapter3\wrwb_demo\prodconsdemo\kernel_module

• Click OK

Import Source Code

38

• Back in the File system dialog, click the box on the left pane to select the folder

• Click Finish

Import Source Code

39

• 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

Build the 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

41

• 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


42

#include "wdLib.h"

void calibrateInt(int *wdRunning){*wdRunning = 0;}

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);}

Old scenario – for

KERNEL MODE ONLY


43

#include "semLib.h"

void calibrationTask(SEM_ID startSem, int *wdRunning){semTake(startSem, WAIT_FOREVER);taskDelay(sysClkRateGet());*wdRunning = 0;semDelete(startSem);}

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;}

New scenario – good

for RTP MODE


44

• Edit the source file library.c to replace wdLib usage


45

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


46

• 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() !


47

• 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.


48

• 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 exception occurs.


49

rtpSpawn( )

NAME

rtpSpawn( ) - spawns a new Real Time Process (RTP) in the system

SYNOPSIS

RTP_ID rtpSpawn (

const char * rtpFileName, /* Null terminated path to executable */const char * argv[], /* Pointer to NULL terminated argv array */ const char * envp[], /* Pointer to NULL terminated envp array */ int priority, /* Priority of initial task */ int uStackSize, /* User space stack size for initial task */int options, /* The options passed to the RTP */ int taskOptions /* Task options for the RTP's initial task */

)


50

#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


Add following code to the end of ProdConsDemo.c

51

• 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

• Click Next

Rebuild VxWorks and reboot target

52

• On the Project Setup dialog change selection from A board support package to

An existing VxWorks Image project

• Click Finish


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.


54

• The VxWorks Image Configurator

is displayed in the editor view

of Wind River Workbench.

• The Components pane is selected.

• Switch to the Bundles pane


55

• From the available bundles select Real Time Process Development

• The components of this bundle show up on the right side.

• Click Add Bundle


56

• 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


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.


58

• In the Object Path Mappings pane click Add• In the dialog enter a mapping from

target path host:c:/

to C:\

• Click OK


59

• In the Properties pane dialog you can see the new mapping topmost.

• Click OK


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

61

• 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 Workbenchthen. Also – you might want to kill theEclipse.exe, dfwserver.exe, jawaw.exe in the Windows TaskManager

If you see problems launching your RTP,double check the PathMappings in your targetConnection – remove the mapping that you did Apply and give it a try. Also - double check on the host name thatYou have specified in the bootloader.

Run the RTP

62

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.

Documents

1. 2 Transitioning Device Software from Kernel Space to Multiple Real Time Processes Migrate VxWorks 5.x projects into VxWorks 6.x and gain access for