To be able to work with a process image we first have to create a description file. The description file specifies which process variables do exist, which types they have and it also specifies the layout of the process images. Section XML process definition contains more information about the details of the description file.

libpv is written in an object oriented way. As C does not offer native objects we use a struct for the storage of the object variables.

Control applications often have the requirement that no dynamic memory has to be allocated during normal operation; although libpv doesn't strictly follow this paradigm internally, it does for the object struct. The constructor (pv_init()) doesn't dynamically allocate memory for the object struct, so the calling process has to take care of the memory management here. For example, it can just allocate it on the stack:

The constructor needs some parameters. To have the API independend of future extensions, libpv uses an attribute struct which also has to be prepared by the calling process:

Here is a list of the attribute fields which have to be prepared:

Now we can instanciate our pv_engine object:

If the return value of pv_init() is != 0 an error is indicated. Usually the function just returns 0 and the object can be used.

Before process variables can be used in our program they have to be registered with our pv_engine:

It is important that process variables are registered with the correct pv_register_<type>() function, corresponding to which type has been specified in the XML description file.

All process variables which shall be used in our application have to be registered first. The pv_register_<type>() functions directly return pointers to the process variables in the mmap()ed process image.

Modern Unix systems like Linux offer concurrent execution of processes and threads. For ressources which can be shared between different execution contexts it is important that the access to the shared ressource is properly serialized.

libpv implements a locking scheme for the process variable engine objects. So whenever the process image is accessed it has to be locked first:

When pv_lock() returns we have exclusive access to the engine and can read or write process variables, for example like this:

After all changes have been done, unlock the engine:

When we don't need the engine any more, for example when the program is finished, the pv_engine object has to be destroyed:

Note that, even when the pv_engine object has been destructed, the backing store and the process image stay intact.

Special backing stores may need a special handling while reading or writing data from it or to it. In this case libpv is not directly working on the mmap()ed backing store but uses a shared memory copy. To achieve persistence it is necessary to call pv_flush(&engine, ...); to ensure the backing store updated with the new value. pv_flush() works on a per process variable base.

This changes the workflow to:

To be independent of any backing store and it's capabilities use pv_flush() every time a process variable is changed. The function does nothing if there is no need for a flush and it does the right thing if the currently used backing store needs special handling.

Sometimes it is interesting to know when a process variable has changed. libpv has an event notification mechanism which can also be used to relay events with associated data to some caller. An application can register itself to change events for as much process variables as it is interested in.

To register for an event notification we have to call

The first argument is the pv_engine handle, the second one a process variable pointer which must have been acquired before with pv_register_<type>(). Now we are registered for change notifications on this process variable and can wait for events:

This call blocks until a notification arrives. It returns immediately if there remain old notifications, so it is not possible to miss an event. As we can register for changes on as many process variables we need, this function returns independently for each notification. Due to the fact that the call to pv_event_await_syncronous() blocks until a notification arrives it should be called it in a separate thread, so that the rest of the program can do other things.

Now we block until we receive change notifications. But if you change any process variable another process is registered for a change notification to, you must generate this kind of event. To do so you must call pv_event_generate(). This is required when you change the process variable without the help of the libpv.

The easiest way to update a piece of hardware is to register a write function to process variable of interest. This write function knows how to translate the process variable's contents into something device specific.

After that register also a change notification function to the same process variable. Then call pv_event_await_syncronous(), to wait for a notification. When this call returns, simply call pv_to_device().

Here is a very simple example. It doesn' show the initializing of libpv.

 
    static int write_var1_into_hardware(pv_engine_t *engine,struct pv *pv,unsigned long data)
    {
      .... /* so something device specific */
    }

    void observe_var(void)
    {
      uint8_t *var1;

      var1 = pv_register_uint8(&engine,"ucResetCounter");

      pv_event_register(&engine,var1);
      pv_set_fn_write(&engine,var1,write_var1_into_hardware);

      while(1) {
         pv_event_await_syncronous(&engine);
         pv_to_device(&engine,var1);
      }
    }
  
  

FIXME: This chapter is a should be, currently not realized in this way.

In this example three independent clients sharing one process image to control a process that communicates with different kind of hardware.

They are sharing a process image with the definition shown below:

<oio>
 <group id="can_bus">
  <port id="can_message" index="1">
   <portPvChannel>
    <pv id="position_request" val="0">
     <type>bool</type>
     <offset>0</offset>
    </pv>
   </portPvChannel>
  </port>
  <port id="can_message" index="2">
   <portPvChannel>
    <pv id="overheating" val="0">
     <type>bool</type>
     <offset>4</offset>
    </pv>
   </portPvChannel>
  </port>
 </group>
 <group id="pos_encoder">
  <port id="pos_handling" index="1">
   <portPvChannel>
    <pv id="current_pos" val="0">
     <type>uint32_t</type>
     <offset>8</offset>
    </pv>
   </portPvChannel>
  </port>
 </group>
 <group id="i2c_bus">
  <port id="temperature" index="1">
   <portPvChannel>
    <pv id="motor_temp" val="0">
     <type>uint32_t</type>
     <offset>12</offset>
    </pv>
   </portPvChannel>
  </port>
 </group>
</oio>
  

Every time the encoder client reads in a different position than the last read, it stores the new value into process variable current_pos. Also it generates an event as a change notification. The sensors client does it similarly, but stores new temperature values into process variable motor_temp and also generates a change notification. If the motor temperature exceeds a critical limit, it sets process variable overheating and also generates a change notification. If the CAN client receives a query for current position message, it sets and generates a change notification on process variable position_request.

In this example a libpv based client on a target controls some LEDs. You can modify the amount of LEDs with a JVISU applet on your host.

To control the LEDs itself this example uses GPIO framwork based on sysfs entries to set and clear the LEDs. To control the LEDs from outside, there are also some process variables to calculate how many LEDs should be on or off. These are the vars, the JVISU is working with.

            
<processimage>
 <!-- physical outputs -->

 <port id="leds_set">
  <device prefix="/sys/devices/platform/nxdkn-gpio.0/led_set"/>
  <portPvChannel>
   <pv id="leds_set" val="0">
    <name></name>
    <type>uint32_t</type>
    <offset>0x0<offset>
   <pv>
  </portPvChannel>
 <port>

 <port id="leds_clear">
  <device prefix="/sys/devices/platform/nxdkn-gpio.0/led_clear"/>
  <portPvChannel>
   <pv id="leds_clear" val="0">
    <name></name>
    <type>uint32_t</type>
    <offset>0x4</offset>
   </pv>
  </portPvChannel>
 </port>

 <!-- logical PVs -->

 <pv id="level">
  <name></name>
  <type>uint8_t</type>
  <offset>0xC</offset>
 </pv>

 <pv id="fill">
  <name></name>
  <type>uint8_t</type>
  <offset>0xD</offset>
 </pv>

</processimage>
 
          

Char "|" means one of the listed items, "()" means required but more than one choice, "[]" means optional

	<pv id="yourUniqueIdentifier" [val="defaultValue"]>
		[<repeat>Count</repeat>]
		<type>(uint8_t | uint16_t | uint32_t | uint64_t |
			  int8_t | int16_t | int32_t | int64_t |
			  float | double | string | bool) </type>
		(<offset>Value</offset> | <offset/>)
		<name [language 1]>text</name>
		[<name [language 2]>text</name>]
		....
		[<scale>
			<poly>
				<coeff order=order1>factor</coeff>
				[<coeff order=order2>factor</coeff>]
				....
			</poly>
		</scale>]
		[<unit><factor [scale=value] [name=char]>UnitChar</factor>]
		[<min>val</min>]
		[<max>val</max>]
	</pv>

libpv handles all <pv> tags in it. To define a process variable use the <pv> tag for one resource.

You can add as much own tags as you want or need. It depends on your application what other information is needed. But you should locate all this additional information outside the <pv> tag. So the <pv> tag is one of the inner levels, everything beside it on the same level is up to you.

To describe a more complex I/O system extend the XML files specified above with the following tags:

Every client that calls libpv's pv_init() will connect itself to a process image. At this point libpv reads in the process description within the XML process description file on a per client basis. From this file libpv creates an internal representation with a linked list of process variable elements and calculates the needed size to store all of these elements. At this point of time all process variables are only known as their types, their sizes and their offset they will later reside at.

To breath some life into it (e.g. to give each process variable a value) a real memory area to store process variable values is needed. To do so libpv opens a data file from a backing store and maps this file into the client's memory space and also shares this chunk of memory globally. This chunk of memory is called the process image and the calling client is now connected to it.

When the file is successfully mapped, accessing every process variable in this process image is possible, while the operating system is responsible to write back this memory area to the backing store every time something was changed.

With this procedure, in the case of a power fail and after a restart of the system, the last process variable values written to the backing store are restored automatically and the client can continue at this point just before the fail.

There are maybe special environments and backing stores where this procedure cannot be used. If your backing store is a flash memory device and you are using a filesystem on it that can't handle writeable mappings (JFFS2 is such a filesystem) libpv automatically uses a different way: It also shares the process image as a chunk of memory between all connected clients. But it's really only memory. In this case the client is responsible to tell libpv that it has changed something in the process image to handle the write back in a correct manner by libpv. So for each client's modification in the process image a pc_flush() is required.

Process variables also can represent hardware states. Their state can represent a piece of control hardware (e.g. write only) or some kind of sensors (e.g. read only). But they reside in a chunk of memory and that means some kind of connection or update mechanism between a process variable and the hardware is required. At first there is a polling mechanism based on the library functions:

Call these functions whenever you need an update of your process variable or external hardware. But to let it work someone has to translate the process variable's value into device dependend value and vice versa. This can be done by a read or write function registered to a process variable. To register a read function (to update from external hardware values into process variable) use pv_set_fn_read(). To register a write function (to update from process variable into external hardware) use pv_set_fn_write()

These device dependent update functions are defined to:

To read or write data from or to a device you can use the file handle pv->device_file. It's already opened and usable. Do everything here to read or feed your device. You gain access to the process variable by using pv_to_abs_addr(engine,pv) to get a pointer to it. It's up to yourself to cast this pointer to its right size. pv->type may help in this case. Currently the data parameter is not used and always 0.

This is an easy way to communicate with a hardware driver. It uses data I/O based on a device node. More complex systems are imaginable. At this point only you are knowing how to deal with your hardware.

TBD

For change notification (events) there is a dedicated server required. It manages all clients that share this process image and also handles all the required work to distribute change notifications to all interested clients.

When the event server starts, it creates a message queue and waits for messages. Whenever a new client starts, it sends a message to the server and registers itself. Nothing else happens until the client also registers for notification. This is an additional message from the client to the server. In this case the server adds this request to a list linked to the process variable of interest.

Details: The server creates an unique ID first. It uses IPC's ftok() function to create this unique ID from the name of the given process image file and the number "43". With this unique ID it creates a message queue name with the pattern /pve_<ID as decimal> (see pv_types.h, macro QUEUE_NAME for current implementation). So there is exactly one message queue per process image. If any client generates this unique ID in the same way, it can open a connection to the server of the given process image file.

On the other hand, the client does a similar thing: But it doesn't use an unique ID, it uses its process ID instead. So it creates a message queue with the name /clnt_<PID as decimal> to wait for notifications (see pv_types.h, macro QUEUE_CLIENT for current implementation).

Whenever a client changes a process variable and calls pv_event_generate() this also sends a message to the server. The server only follows the list linked to this process variable and sends a change notification to each registered client in the list.

Removing a notification and removing the whole client are also simple messages to the server. Removing a client forces a complete deregister of notifications of all managed process variables.

The server can handle unlimited process variables, registerd client and registered notifications, because all are linked lists. The only limit is the available memory space and - maybe - computing power.

Bugs: If a client quits without the "Deregister Client" message, the server handles this client further on as active!