Programmers Guide

cifX/netX Application Programmers Guide

V0.0

Hilscher Gesellschaft für Systemautomation mbH

www.hilscher.com
DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public
Introduction 2/53

Table of Contents
1 Introduction.............................................................................................................................................4
1.1 About this Document......................................................................................................................4
1.2 List of Revisions .............................................................................................................................5
1.3 Terms, Abbreviations and Definitions ............................................................................................6
2 Programming Resources.......................................................................................................................7
2.1 Manuals and Documents ...............................................................................................................7
2.2 Product CDs/DVDs and Content....................................................................................................8
2.3 Choose a Programming Level........................................................................................................9
2.3.1 Hardware Level ............................................................................................................................... 11
2.3.2 Low Level ........................................................................................................................................ 11
2.3.3 Intermediate Level........................................................................................................................... 12
2.3.4 Driver Level ..................................................................................................................................... 12
3 Fundamentals - DPM Layout and Content .........................................................................................13
3.1 The DPM Layout ..........................................................................................................................14
3.1.1 DPM Area Definition ........................................................................................................................ 14
3.1.2 DPM Definitions, Structures and Header Files ................................................................................ 15
3.2 System Channel Structure ...........................................................................................................16
3.2.1 System Information.......................................................................................................................... 17
3.2.2 System Status ................................................................................................................................. 17
3.3 Handshake Channel.....................................................................................................................18
3.3.1 Handshake Register Functionality................................................................................................... 19
3.4 Communication Channel Structure ..............................................................................................20
3.4.1 Channel Information ........................................................................................................................ 21
3.4.2 Channel State.................................................................................................................................. 21
3.5 Data Transfer Methods and Areas ...............................................................................................22
3.5.1 Packet Definition and Transfer via a Mailbox System...................................................................... 22
3.5.2 I/O Data Transfer............................................................................................................................. 25
3.6 Communication Mechanism and Synchronization .......................................................................26
3.6.1 System Channel Handshake Register............................................................................................. 26
3.6.2 Communication Channel Handshake Register................................................................................ 27
3.6.3 Working with Handshake Registers and Flags ................................................................................ 28
3.6.3.1 Simple State and Command Handshake Flags ............................................................... 28
3.6.3.2 Synchronization Handshake Flags .................................................................................. 28
3.6.3.3 Packet Data Transfer - Handshake Flag Synchronisation ............................................... 29
3.6.3.4 I/O Data Transfer - Handshake Flag Synchronisation ..................................................... 32
3.6.3.5 Change of State Mechanism (COS) ................................................................................ 36
3.7 Programming Interface - CIFX-API ..............................................................................................40
4 Examples...............................................................................................................................................41
4.1 System Identification and Start-Up Handling ...............................................................................41
4.2 Channel Identification and Start-Up Handling..............................................................................42
4.3 Packet Transfer ............................................................................................................................43
4.3.1 Send a Packet to the Device ........................................................................................................... 43
4.3.2 Read a Packet form the Device....................................................................................................... 44
4.4 I/O Data Transfer .........................................................................................................................45
4.4.1 Write Output data to the Device ...................................................................................................... 45
4.4.2 Read Input data from Device........................................................................................................... 46
4.5 Change of State (COS) Information and Handling.......................................................................47
4.5.1 Host COS Handling ......................................................................................................................... 47
4.5.2 Communication COS Handling........................................................................................................ 48
4.6 Hardware and Protocol Stack Identification .................................................................................49
4.7 Additional Functions .....................................................................................................................49
4.8 Hardware and Driver Installation Guides .....................................................................................50
4.9 Load a Firmware to a CIFX Card .................................................................................................50
4.10 Start with an Example Program ...................................................................................................50
4.11 Protocol Stack handling via CIFX API..........................................................................................51
5 Additional Resources ..........................................................................................................................51
5.1 Protocol API Manuals...................................................................................................................51
6 Appendix ...............................................................................................................................................52

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Introduction 3/53
6.1 List of Tables ................................................................................................................................52
6.2 List of Figures...............................................................................................................................52
6.3 Contacts .......................................................................................................................................53

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Introduction 4/53

1 Introduction
1.1 About this Document
This guide is an introduction to the programming of Hilscher netX based device. It explains the fundamentals
necessary to understand the functions and the handling of Hilscher netX hardware and will show the
programming principals needed for correct device handling.
It should also help to choose the level where to start with developments, describes where to find the
necessary information.

Furthermore it explains the available information in regards to the programming level, describes necessary
synchronisation mechanism for the data transfer between a host and the netX firmware and covers all
aspects from a simple memory connection to a netX (dual-port-memory access), the use of pre-created low
level hardware functions, the netX C toolkit, the implementation of own drivers based the toolkit until the use
of Hilscher device drivers for different operating systems.

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Introduction 5/53

1.2 List of Revisions

Rev Date Name Chapter Revision
1 2013-07-26 RM 1 created

Table 1: List of Revisions

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Introduction 6/53

1.3 Terms, Abbreviations and Definitions

Term Description
cifX Communication Interface based on netX
comX Communication Module based on netX
PCI Peripheral Component Interconnect
DPM Dual-Port Memory
Physical interface to all communication board (DPM is also used for PROFIBUS-DP Master).
API Application Programming Interface
Table 2: Terms, Abbreviations and Definitions

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Programming Resources 7/53

2 Programming Resources
Hilscher offers several resources for the programming. The following list contains the most
important manuals necessary.

Hilscher Website: http:\\www.hilscher.com

2.1 Manuals and Documents

netX Dual-Port Memory Interface DPM xx.EN.pdf manual
This manual describes the memory layout of the DPM and explains the information which
can be found inside the DPM. This is the basis of a host to netX device communication.

cifX netX Toolkit -DPM TK xx EN.pdf manual

The toolkit manual describes the C toolkit, the usage, implementation and the adaptation to
own target systems.

CIFX API PR xx EN.pdf manual

The CIFX API manual describes the Hilscher standard application programming interface.
This API offers all necessary functions and information needed to handle netX based device.
With the knowledge from the DPM layout, a correlation between the information in the DPM
and the functions the API functions can be seen (e.g. what is a channel and how to
exchange asynchronous command and cyclic I/O data).

cifX Device Driver - <operating system> DRV xx EN.pdf manuals

Each operating system specific Hilscher device driver comes with an own manual, describing
the specific information and behaviour.

PC Cards CIFX <card type> UM xx EN.pdf manual

and
PC Cards cifX Software Installation UM xx EN.pdf guide
Hilscher offers netX devices in different form factor (PC boards, PCI104, Compact PCI, etc.)
for the most common hardware connections (DPM, ISA, PC104/PC104+, PCI/PCIe, serial
interface, USB, Ethernet).
Each device (card type) comes with a specific hardware installation, operation, and
description manual, including technical data, connector details, jumper settings, LED state
definitions etc. And a software installation and configuration guide.

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Programming Resources 8/53

2.2 Product CDs/DVDs and Content

Communication Solutions DVD
- Device Driver CD for Windows (NXDRV-WIN)
- Driver Toolkit CD (NXDRV-TKIT)

Device Driver CDs (NXDRV-WIN)

. (NXDRV-CE)
(NXDRV-Linux)
(NXDRV-QNX)
(NXDRV-VxWorks)
. (NXDRV-INtime)
. (NXDRV-RTX)
- Driver documentation and installation (operating system dependent)
- C development resources (header and libraries) (operating system dependent)
- Sources and Examples (operating system dependent)
- Additional manual: CIFX API manual
- Additional manual: netX Dual-Port Memory Interface DPM manual

cifX netX Toolkit CD (NXDRV-TKIT)

- Toolkit documentation and source code
- Toolkit example implementation (Win32 / nonOS / MQX / rcX)
- Toolkit hardware functions example implementation (Win32 / WinCE / nonOS)
- Additional manual: CIFX API manual
- Additional manual: netX Dual-Port Memory Interface DPM manual
- Additional manual: Serial DPM Interface with netX manual
- Additional manual: SPI Slave DPM netX 100 500 HAL manual
- Additional manual: Second Stage Bootloader netX manual

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Programming Resources 9/53

2.3 Choose a Programming Level

Hilscher offers support to different programming levels. Programming levels are starting at the
plain dual-ported memory until up to the device driver level for the most common operating
systems.

Figure 1: Overview - Programming Levels

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Programming Resources 10/53
The following picture gives an overview of the possible development environments and the
migration to embedded systems. This should help to choose a programming level fit best to the
application needs.

Figure 2: Choose a Programming Level

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Programming Resources 11/53

2.3.1 Hardware Level

The hardware level is the direct access to the physical DPM of a netX device. Programming is
supported by offering C header files describing the DPM structures, content, states, flags, bit
masks etc.

Usage: One or more netX Chip(s) or COMX modules connected to microcontrollers

- Very limited system resources
- Highly optimized hardware access
- Dedicated function to access the hardware
- None C based development environment

Manuals: netX Dual-Port Memory Interface DPM xx EN.pdf

(Dual Port Memory layout, structures and functionalities)
CD / DVD: NXDRV-TKIT or Communication Solution DVD
Header Files: rcX_User.h Dual Port Memory structures
rcX_Public.h Asynchronous packet definitions

2.3.2 Low Level

Access to the DPM via pre-created hardware functions which are part of the "cifX netX Toolkit"
(see "Toolkit Low-Level Hardware Access Functions").

Usage: One or more netX Chip(s), COMX modules or CIFX cards connected to
microcontrollers
- DPM or ISA connection to the netX hardware
- with or without an operating system
- limited system resources (RAM/FLASH)

Programming Resources:
Manuals: netX Dual-Port Memory Interface DPM xx EN.pdf
(Dual Port Memory layout, structures and functionalities)
CIFX netX Toolkit DPM TK xx EN.pdf
CD /DVD NXDRV-TKIT or Communication Solution DVD
Source Files: Toolkit .\Examples\cifXTKitHWFunctions directory
cifXUser.h
cifXErrors.h
netX_RegDefs.h
cifXHWFunctions.h.c / cifXHWFunctions.h
cifXEndianess.c / cifXEndianess.h
cifXInterrupt.c / cifXInterrupt.h

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Programming Resources 12/53

2.3.3 Intermediate Level

Using the "cifX netX Toolkit" and CIFX API functions offered by the toolkit. Porting the toolkit to
own hardware platforms or write own device drivers.

Usage: One or more netX chip(s), COMX modules, CIFX cards connected to a host
PC system
- Support for standard Hilscher devices (complete function support)
- C / C++ development environment
- With or without an operating system
- Writing own drivers

Programming Resources:
Manuals: CIFX netX Toolkit DPM TK xx EN.pdf
CIFX API PR xx EN.pdf
CD /DVD NXDRV-TKIT or Communication Solution DVD
Source Files: Toolkit .\cifXToolkit directory

2.3.4 Driver Level

Using the CIFX API offered by a operating system drivers created by Hilscher to write own user
applications on top of a Hilscher netX based communication device.

Usage: Host PC system with an operating system or real time extension supported
by Hilscher
- COMX modules, CIFX cards connected to a host PC
- ISA / PC104 / PCI or PCIexpress bus system
- Support for standard Hilscher devices (complete function support)
- Creation own high level user applications

Programming Resources:
Manuals: CIFX API PR xx EN.pdf
CD /DVD NXDRV-xxx or Communication Solution DVD
Source Files: Comming with the driver
cifXUser.h
cifXErrors.h

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 13/53

3 Fundamentals - DPM Layout and Content

The fundamental of the netX hardware is the so call dual-ported memory (DPM) of netX based
hardware. Hilscher has defined a memory structure (netX DPM Interface structure) and
corresponding definitions suitable for the handling of communication devices, offering all
information needed by applications to manage the hardware and the underlying Hilscher
communication firmware.
It covers also system state information, the functionalities to exchange data with netX based
hardware and to synchronize data access between a host and the asynchronous working netX
firmware.

All Hilscher netX based devices processing a Hilscher standard firmware performing in the same
way.

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 14/53

3.1 The DPM Layout

The DPM structure is a representation of the hardware functions and places the functions and
corresponding information into separate, independent, areas.

Maximum DPM size = 64Kbyte

COMX modules can have a different size (e.g. 8 KByte)

3.1.1 DPM Area Definition

System Channel / System Device:
- Global system information and system services like firmware download and hardware reset etc.
- Global system state information
- General channel information

Handshake Channel:
- Special hardware registers containing synchronization flags and channel states
- Independent registers pairs for each channel
- Register pairs consists of a host dedicated and netX dedicated register
- Registers are able to create interrupts on the corresponding (host register on netX, netX register
on host side)

Communication Channel (max. 4 times):

- Dedicated channel to access a protocol stack
- Dedicated handshake registers in the "Handshake-Channel"
- Independent form other channels on the hardware
- General communication control and state information
- Protocol specific control, state and data areas
- Default layout, default size 15616 Byte

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 15/53

Application Channel:
- Dedicated channel to access a customer application running on netX
- Optional and not defined yet

netX Global Register Block:

- Direct access to netX chip registers
- Defined in the "netX Program Reference Guide"
- Functions like netX chip state / Reset / Interrupt / DMA etc.
- Needed for RAM based devices, not needed for FLASH based devices

3.1.2 DPM Definitions, Structures and Header Files

The whole DPM structures and definitions are provided by two C header files.

rcx_User.h
Definition of the DPM structure, data blocks and all global definitions offered by the DPM.
The C-header file contains all parts necessary to work with the DPM by using symbolic
names.
rcx_Public.h
Definition of "rcX Public Packet" functions.
Packets are asynchronous commands which can be sent to the hardware. A packet is the
combination of a "Packet-Header", containing global command, routing and handling
information for the packet, and a following "User-Data Area" containing command specific
data.

NOTE: All structures and definition used in the following chapters can be found in these two
header files

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 16/53

3.2 System Channel Structure

System Channel (System Device) Layout
R
e
s
System Channel e System System Send / Receive
Information Block Information Block r Control Block Status Block Mailbox
v
e
d

System Channel Structure Definition:

/*****************************************************************************/
/*! Structure of the whole system channel (DPM) (Size 512 Byte) */
/*****************************************************************************/
typedef __RCX_PACKED_PRE struct NETX_SYSTEM_CHANNELtag
{
NETX_SYSTEM_INFO_BLOCK tSystemInfo; /*!< 0x000:0x02F System information block */
NETX_CHANNEL_INFO_BLOCK atChannelInfo[NETX_MAX_SUPPORTED_CHANNELS]; /*!< 0x030:0x0AF Channel information block */
NETX_HANDSHAKE_CELL tSysHandshake; /*!< 0x0B0:0x0B3 Handshake cells used, if not
in Handshake block */
uint8_t abReserved[4]; /*!< 0x0B4:0x0B7 unused/reserved */
NETX_SYSTEM_CONTROL_BLOCK tSystemControl; /*!< 0x0B8:0x0BF System control block */
NETX_SYSTEM_STATUS_BLOCK tSystemState; /*!< 0x0C0:0x0FF System state block */
NETX_SYSTEM_SEND_MAILBOX tSystemSendMailbox; /*!< 0x100:0x17F Send mailbox */
NETX_SYSTEM_RECV_MAILBOX tSystemRecvMailbox; /*!< 0x180:0x1FF Receive mailbox */
} __RCX_PACKED_POST NETX_SYSTEM_CHANNEL;

System Information Block: (NETX_SYSTEM_INFO_BLOCK)

General system information for the complete device

Channel Information Block: (NETX_CHANNEL_INFO_BLOCK)

Information about available communication channels, general channel information and channel
layout.

System Control Block: (NETX_SYSTEM_CONTROL_BLOCK)

General system control functions, currently not used

System Status Block: (NETX_SYSTEM_STATUS_BLOCK)

General system and device information

System Send/Receive Mailbox: (NETX_SYSTEM_SEND /RECEIVE_MAILBOX)

System channel mailbox for asynchronous packet based commands

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 17/53

3.2.1 System Information

General system information can be obtained from the system information block
NETX_SYSTEM_INFO_BLOCK (see below).
*****************************************************************************/
/*! System information block (Size = 48 Byte) */
/*****************************************************************************/
typedef __RCX_PACKED_PRE struct NETX_SYSTEM_INFO_BLOCKtag
{
uint8_t abCookie[4]; /*!< 0x00 "netX" cookie */
uint32_t ulDpmTotalSize; /*!< 0x04 Total Size of the whole dual-port
memory in bytes */
uint32_t ulDeviceNumber; /*!< 0x08 Device number */
uint32_t ulSerialNumber; /*!< 0x0C Serial number */
uint16_t ausHwOptions[4]; /*!< 0x10 Hardware options, xC port 0..3 */
uint16_t usManufacturer; /*!< 0x18 Manufacturer Location */
uint16_t usProductionDate; /*!< 0x1A Date of production */
uint32_t ulLicenseFlags1; /*!< 0x1C License code flags 1 */
uint32_t ulLicenseFlags2; /*!< 0x20 License code flags 2 */
uint16_t usNetxLicenseID; /*!< 0x24 netX license identification */
uint16_t usNetxLicenseFlags; /*!< 0x26 netX license flags */
uint16_t usDeviceClass; /*!< 0x28 netX device class */
uint8_t bHwRevision; /*!< 0x2A Hardware revision index */
uint8_t bHwCompatibility; /*!< 0x2B Hardware compatibility index */
uint8_t bDevIdNumber; /*!< 0x2C Device identification number (rotary
switch) */
uint8_t bReserved; /*!< 0x2D Reserved byte */
uint16_t usReserved; /*!< 0x2E:0x2F Reserved */
} __RCX_PACKED_POST NETX_SYSTEM_INFO_BLOCK;

3.2.2 System Status

The system status block contains global system information and the corresponding data structure
is defined as NETX_SYSTEM_STATUS_BLOCK.

/*****************************************************************************/
/*! System status block (Size = 64 Byte) */
/*****************************************************************************/
typedef __RCX_PACKED_PRE struct NETX_SYSTEM_STATUS_BLOCKtag
{
uint32_t ulSystemCOS; /*!< 0x00 System channel change of state
acknowledge */
uint32_t ulSystemStatus; /*!< 0x04 Actual system state */
uint32_t ulSystemError; /*!< 0x08 Actual system error */
uint32_t ulBootError; /*!< 0x0C Bootup error (only set by 2nd Stage
Bootloader) */
uint32_t ulTimeSinceStart; /*!< 0x10 time since start in seconds */
uint16_t usCpuLoad; /*!< 0x14 cpu load in 0,01% units (10000 => 100%)
*/
uint16_t usReserved; /*!< 0x16 Reserved */
uint32_t ulHWFeatures; /*!< 0x18 Hardware features */
uint8_t abReserved[36]; /*!< 0x1C:3F Reserved */
} __RCX_PACKED_POST NETX_SYSTEM_STATUS_BLOCK;

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 18/53

3.3 Handshake Channel

The Handshake-Channel contains the "Channel Handshake Registers" with their channel state and
synchronization flags.
Synchronized access to data areas is always necessary if data consistency must be assured
between the host and the netX firmware, especially if a data area consists of more than one byte.
Byte consistency is guaranteed by the DPM hardware preventing concurrent access to a single
byte while multi byte areas requiring other mechanism realized by the handshake flags (software)
and by defining access rules (read only / write only areas).

Handshake Channel

Communication Communication Communication Communication

System Channel Handshake
Channel 0 Channel 1 Channel 2 Channel 3
Flags Channel
Flags Flags Flags Flags

Handshake Channel Structure Definition:

/*****************************************************************************/
/*! Handshake channel definition */
/*****************************************************************************/
typedef struct NETX_HANDSHAKE_CHANNELtag
{
NETX_HANDSHAKE_CELL tSysFlags; /*!< 0x00 System handshake flags */
NETX_HANDSHAKE_CELL tHskFlags; /*!< 0x04 not used */
NETX_HANDSHAKE_CELL tCommFlags0; /*!< 0x08 channel 0 handshake flags */
NETX_HANDSHAKE_CELL tCommFlags1; /*!< 0x0C channel 1 handshake flags */
NETX_HANDSHAKE_CELL tCommFlags2; /*!< 0x10 channel 2 handshake flags */
NETX_HANDSHAKE_CELL tCommFlags3; /*!< 0x14 channel 3 handshake flags */
NETX_HANDSHAKE_CELL tAppFlags0; /*!< 0x18 not supported yet */
NETX_HANDSHAKE_CELL tAppFlags1; /*!< 0x1C not supported yet */
uint32_t aulReserved[ 56 ]; /*!< 0x20 - 0xFF */
} NETX_HANDSHAKE_CHANNEL;

Note: Handshake Registers are able to generate interrupts.

On the host side, if the firmware writes to the netX flags and on the firmware side if the
host writes to the host flags.

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 19/53

3.3.1 Handshake Register Functionality

Each channel has an own handshaking register, except the Handshake Channel itself which does
not need a synchronization mechanism.
A handshake register is defined as a 32 bit value, divided into two parts. The "NETX Flags " and
the "HOST Flags" and a definition where only the owner of a register is allowed to read and write it,
while the opposite user is only allowed to read the register. And handshake registers are able to
generate interrupt requests.

System Channel Handshake Register Structure:

The system channel handshake register defines 8 bits for the netX firmware (netX Flags =
bNetxFlags) and 8 bits for the host application (Host Flags = bHostFlags), because it need less
synchronization flags than a communication channel (see t8Bit structure below).

System Channel Handshake Register

Bit 31 32 Bit Register Value Bit 0

Bit 7 Host Flags Bit 0 Bit 7 netX Flags Bit 0 empty empty

Communication Channel Handshake Register Structure:

The communication channel handshake register defines 16 bits for the netX firmware (netX Flags
= usNetxFlags) and 16 bits for the host application (Host Flags = usHostFlags) (see t16Bit
structure below).

Communication Channel Handshake Register

Bit 31 32 Bit Register Value Bit 0

Bit 15 Host Flags Bit 0 Bit 15 netX Flags Bit 0

Handshake register pairs are defined by the structure NETX_HANDSHAKE_CELL.

/*****************************************************************************/
/*! Handshake cell definition */
/*****************************************************************************/
typedef __RCX_PACKED_PRE union NETX_HANDSHAKE_CELLtag
{
__RCX_PACKED_PRE struct
{
volatile uint8_t abData[2]; /*!< Data value, not belonging to handshake */
volatile uint8_t bNetxFlags; /*!< Device status flags (8Bit Mode) */
volatile uint8_t bHostFlags; /*!< Device command flags (8Bit Mode) */
} __RCX_PACKED_POST t8Bit;

__RCX_PACKED_PRE struct
{
volatile uint16_t usNetxFlags; /*!< Device status flags (16Bit Mode) */
volatile uint16_t usHostFlags; /*!< Device command flags (16Bit Mode)*/
} __RCX_PACKED_POST t16Bit;
volatile uint32_t ulValue; /*!< Handshake cell value */
} __RCX_PACKED_POST NETX_HANDSHAKE_CELL;

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 20/53

3.4 Communication Channel Structure

Communication Channel Layout
R
e
s
e Common Common Extended Send / Receive INPUT / OUTPUT
r Control Block Status Block Status Block Mailbox Data Areas
v
e
d

Communication Channel Structure Definition (NETX_DEFAULT_COMM_CHANNEL):

/*****************************************************************************/
/*! Structure of the DEFAULT communication channel (Size 15616 Byte) */
/*****************************************************************************/
typedef __RCX_PACKED_PRE struct NETX_DEFAULT_COMM_CHANNELtag
{
NETX_HANDSHAKE_BLOCK tReserved; /*!< 0x000:0x007 Reserved for later use */
NETX_CONTROL_BLOCK tControl; /*!< 0x008:0x00F Control block */
NETX_COMMON_STATUS_BLOCK tCommonStatus; /*!< 0x010:0x04F Common status block */
NETX_EXTENDED_STATUS_BLOCK tExtendedStatus; /*!< 0x050:0x1FF Extended status block */
NETX_SEND_MAILBOX_BLOCK tSendMbx; /*!< 0x200:0x83F Send mailbox block */
NETX_RECV_MAILBOX_BLOCK tRecvMbx; /*!< 0x840:0xE7F Recveice mailbox block */
uint8_t abPd1Output[NETX_HP_IO_DATA_SIZE]; /*!< 0xE80:0xEBF Process data 1 output area */
uint8_t abPd1Input[NETX_HP_IO_DATA_SIZE]; /*!< 0xEC0:0xEFF Process data 1 input area */
uint8_t abReserved1[256]; /*!< 0xF00:0xFFF Reserved */
uint8_t abPd0Output[NETX_IO_DATA_SIZE]; /*!< 0x1000:0x267F Process data 0 output area */
uint8_t abPd0Input[NETX_IO_DATA_SIZE]; /*!< 0x2680:0x3CFF Process data 0 input area */
} __RCX_PACKED_POST NETX_DEFAULT_COMM_CHANNEL;

Common Control Block: (NETX_CONTROL_BLOCK)

Common communication channel and protocol stack control functions

Common Status Block: (NETX_COMMON_STATUS_BLOCK)

Common communication channel and protocol stack status information

Extended Status Block: (NETX_EXTENDED_STATUS_BLOCK)

Protocol stack specific state information

Send/Receive Mailbox: (NETX_SEND_MAILBOX_BLOCK / NETX_RECEIVE_MAILBOX_BLOCK)

Communication channel mailbox system for asynchronous packet based commands.

INPUT/OUTPUT Areas: (abPd(x)Output / abPd(x)Input)

Communication channel cyclic process data images (Input / Output data areas)

Note: An 8 kbyte Communication Channel Structure is also available (see

NETX_8K_DPM_COMM_CHANNEL).

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 21/53
3.4.1 Channel Information
General communication channel information about all available channels is located in the "System
Channel -> Channel Information Block".

3.4.2 Channel State

Communication channel general state and protocol stack specific states are offered by the
following structures:
Common Status Block => NETX_COMMON_STATUS_BLOCK
General communication channel information.
Extended Status Block => NETX_EXTENDED_STATUS_BLOCK
Protocol stack specific channel information.

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 22/53

3.5 Data Transfer Methods and Areas

The netX firmware offers two general methods to exchange data with it.
Non-Cyclic data via Packets and a Mailbox System
Non-cyclic data are binary data streams named "Packets". A packet is a structure which
consists of a header with general administration information (command / length / source /
destination etc) and a data area. The mailbox system contains two memory areas used to
exchange packets between the host and the netX device.
Cyclic data via Input/Output Data Areas
Cyclic data are the field bus protocol stack input and output data which are cyclical
exchanged between members of a field bus network.

3.5.1 Packet Definition and Transfer via a Mailbox System

A packet is a memory area including command and data areas which should be transferred to and
back from the hardware.
Packets are exchanged with the firmware by using a "Mailbox System".
A "Mailbox System" defines one memory area to send packets to the firmware and one area to
receive packets from the firmware.
Access synchronisation to these areas is done by "Handshake-Register-Flags" (see Handshake
Registers), signalling the state of the "Mailbox Memory Area" (empty or full).
To simplify the send and receive handling the mailbox system and their state flags are divided into
a send direction and receive direction with separate handshake flags.

General Packet Definition:

Packet Header -> tHeader
Variable Data Type Description
ulDest UINT32 Destination Queue Handle
ulSrc UINT32 Source Queue Handle
ulDestId UINT32 Destination Queue Reference
ulSrcId UINT32 Source Queue Reference
ulLen UINT32 Packet Data Length (in Bytes)
ulId UINT32 Packet Identification As Unique Number
ulState UINT32 Status / Error Code
ulCmd UINT32 Command / Response
ulExt UINT32 Reserved
ulRout UINT32 Routing Information
Packet Data -> tData
Variable Data Type Description
… … User Data => Specific to ulCmd
Table 3: General Packet Structure

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 23/53

Default Packet Structure from rcX_User.h

/*****************************************************************************/
/*! Default RCX packet header structure */
/*****************************************************************************/
typedef __RCX_PACKED_PRE struct RCX_PACKET_HEADERtag
{
uint32_t ulDest; /*!< 00:04, Destination of packet, process queue */
uint32_t ulSrc; /*!< 04:04, Source of packet, process queue */
uint32_t ulDestId; /*!< 08:04, Destination reference of packet*/
uint32_t ulSrcId; /*!< 12:04, Source reference of packet */
uint32_t ulLen; /*!< 16:04, Length of packet data without header */
uint32_t ulId; /*!< 20:04, Identification handle of sender */
uint32_t ulState; /*!< 24:04, Status code of operation */
uint32_t ulCmd; /*!< 28:04, Packet command */
uint32_t ulExt; /*!< 32:04, Extension */
uint32_t ulRout; /*!< 36:04, Router (internal use only) */
} __RCX_PACKED_POST RCX_PACKET_HEADER;

/*****************************************************************************/
/*! Default RCX packet structure, including user data */
/*****************************************************************************/
typedef __RCX_PACKED_PRE struct RCX_PACKETtag
{
RCX_PACKET_HEADER tHeader; /*!< Packet header */
uint8_t abData[RCX_MAX_DATA_SIZE]; /*!< Packet data */
} __RCX_PACKED_POST RCX_PACKET;

Mailbox System:

Mailbox System
Host Application

Send Mailbox Receive Mailbox

netX Firmware

The netX firmware defines 2 mailbox structures:

System Channel Mailbox
NETX_SYSTEM_SEND_MAILBOX / NETX_SYSTEM_RECEIVE_MAILBOX
Communication Channel Mailbox
NETX_SEND_MAILBOX_BLOCK / NETX_RECV_MAILBOX_BLOCK

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 24/53

Example: System Channel Mailbox Structure

/*****************************************************************************/
/*! System send packet mailbox (Size 128 Byte) */
/*****************************************************************************/
typedef __RCX_PACKED_PRE struct NETX_SYSTEM_SEND_MAILBOXtag
{
uint16_t usPackagesAccepted; /*!< Number of packages that can be accepted */
uint16_t usReserved; /*!< Reserved */
uint8_t abSendMbx[NETX_SYSTEM_MAILBOX_MIN_SIZE]; /*!< Send mailbox packet buffer */
} __RCX_PACKED_POST NETX_SYSTEM_SEND_MAILBOX;

/*****************************************************************************/
/*! System receive packet mailbox (Size 128 Byte) */
/*****************************************************************************/
typedef __RCX_PACKED_PRE struct NETX_SYSTEM_RECV_MAILBOXtag
{
uint16_t usWaitingPackages; /*!< Number of packages waiting to be processed */
uint16_t usReserved; /*!< Reserved */
uint8_t abRecvMbx[NETX_SYSTEM_MAILBOX_MIN_SIZE]; /*!< Receive mailbox packet buffer */
} __RCX_PACKED_POST NETX_SYSTEM_RECV_MAILBOX;

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 25/53

3.5.2 I/O Data Transfer

I/O data areas containing the cyclic process data of a fieldbus protocol stack. These areas are also
divided into output and input areas with dedicated synchronisation flags for each area and transfer
direction.

INPUT/OUTPUT Data Areas

Host Application

OUTPUT Data Area INPUT Data Area

netX Firmware

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 26/53

3.6 Communication Mechanism and Synchronization

Handshake registers are used to signal general channel information, activate commands and for
synchronised data access to the mailbox system, I/O data areas and to handle change of state
information (COS).

3.6.1 System Channel Handshake Register

netX System Flags (NSF)
=> read and written by the netX firmware, host is only allowed to read
Host System Flags (HSF)
=> read and written by the host, netX firmware is only allowed to read

Host System Flags (HSF)

HSF_RECV_MBX_ACK
HSF_SEND_MBX_CMD
HSF_NETX_COS_ACK
HSF_HOST_COS_CMD
HSF_BOOTSTART
HSF_RESET
15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Host System Flags
|| || || ||
15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 netX System Flags
NSF_READY
NSF_ERROR
NSF_HOST_COS_ACK
NSF_NETX_COS_CMD
NSF_SEND_MBX_ACK
NSF_RECV_MBX_CMD
netX System Flags (NSF)
Table 4: Host System Flags / netX System Flags

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 27/53

3.6.2 Communication Channel Handshake Register

netX Communication Flags (NCF)
=> read and written by the netX firmware, host is only allowed to read
Host Communication Flags (HCF)
=> read and written by the host, netX firmware is only allowed to read

Host Communication Flags (HCF)

HCF_PD1_IN_ACK (not supported yet)
HCF_PD1_OUT_CMD (not supported yet)
HCF_PD0_IN_ACK
HCF_PD0_OUT_CMD
HCF_RECV_MBX_ACK
HCF_SEND_MBX_CMD
HCF_NETX_COS_ACK
HCF_HOST_COS_CMD
unused
15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Host Communication Flags
|| || || || || || || ||
15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 netX Communication Flags
NCF_COMMUNICATING
NCF_ERROR
NCF_HOST_COS_ACK
NCF_NETX_COS_CMD
NCF_SEND_MBX_ACK
NCF_RECV_MBX_CMD
NCF_PD0_OUT_ACK
NCF_PD0_IN_CMD
NCF_PD1_OUT_ACK (not supported yet)
NCF_PD1_IN_CMD (not supported yet)
netX Communication Flags (NCF)
Table 5: Host Communication Flags / netX Communication Channel Flags

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 28/53

3.6.3 Working with Handshake Registers and Flags

Handshake flags are located in the handshake registers and either used to signal a specific state,
activate a specific command or, in conjunction with another flag, to create a synchronised data
access.

3.6.3.1 Simple State and Command Handshake Flags

These flags just having two states (signaled = 1 / none signaled = 0).

0 State / Command is inactive

1 State / Command is active

System Channel State / Command Flags:

HSF_RESET 1 = Activate a RESET on the device / 0 = do nothing
HSF_BOOTSTART 1 = Activate the Bootloader of the device / 0 = do nothing
NSF_READY 1 = System Channel is READY / 0 = System Channel is not READY
NSF_ERROR 1 = System Channel error / 0 = no error

Communication Channel State / Command Flags:

NCF_COMMUNICATING 1 = Communicating / 0 = not Communicating
NCF_ERROR 1 = Error / 0 = no error

3.6.3.2 Synchronization Handshake Flags

A netX system defines 3 different synchronization mechanisms realized by handshake flags.
Therefore pairs of handshake bits are defined. One bit form the host handshake flags and one bit
from the netX handshake flags. Both together are used to handle the synchronisation.

Following functions are synchronized:

Packet Data Transfer via the mailbox system
I/O data transfer mechanism
COS - Change Of State mechanism

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 29/53

3.6.3.3 Packet Data Transfer - Handshake Flag Synchronisation

The following flags pairs are used for packet data transfer (mailbox handling).The flags are found
in the system channel handshake register and the communication channel handshake register
(ulNetxFlags / ulHostFlags):
System Channel Flags
HSF_SEND_MBX_CMD / NSF_SEND_MBX_ACK
NSF_RECV_MBX_CMD / HSF_RECV_MBX_ACK
Communication Channel Flags
HCF_SEND_MBX_CMD / NCF_SEND_MBX_ACK
NCF_RECV_MBX_CMD / HCF_RECV_MBX_ACK

General Mailbox Definition:

Handshake Flag Status Handshake Flag Mailbox State

SYSTEM CHANNEL - Send Mailbox

0 0 EMPTY
1 1 EMPTY
HSF_SEND_MBX_CMD NSF_SEND_MBX_ACK
1 0 FULL
0 1 FULL
SYSTEM CHANNEL - Receive Mailbox
0 0 EMPTY
1 1 EMPTY
NSF_RECV_MBX_CMD HSF_RECV_MBX_ACK
1 0 FULL
0 1 FULL

COMMUNICATION CHANNEL - Send Mailbox

Handshake Flag Status Handshake Flag Mailbox State

0 0 EMPTY

1 1 EMPTY
HCF_SEND_MBX_CMD NCF_SEND_MBX_ACK
1 0 FULL

0 1 FULL

COMMUNICATION CHANNEL - Receive Mailbox

0 0 EMPTY

1 1 EMPTY
NCF_RECV_MBX_CMD HCF_RECV_MBX_ACK
1 0 FULL

0 1 FULL

Evaluation of the actual mailbox state can be done by an easy XOR relation between the involved
flags:
if (0 == ((usHostFlags ^ usNetxFlags) & HCF_SEND_MAILBOX))
/* Mailbox empty */
else
/* Mailbox full */

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 30/53

Example: Host sending a packet to the device (HCF_SEND / send mailbox)

Stage Flags Mailbox State Description

1 Mailbox is inactive / no packet sent to device

HCF_SEND_MBX_CMD NCF_SEND_MBX_ACK EMPTY Access allowed by host

1 1

0 0

2 Host sends a packet to the device

- Checking for state 1
- Copy packet data to send mailbox
- Toggle HCF_SEND_MBX_CMD (1->0 or 0->1)

0 1 FULL Access switched to netX

1 0

3 netX firmware gets an interrupt and processes following functions

- Checking the handshake flags pairs(send mailbox flags not equal => Packet in mailbox available)
- Access to mailbox is allowed
- Firmware copies the packet from the mailbox to internal RAM
- Firmware frees the mailbox by toggle NCF_SEND_MBX_ACK (0->1 or 1->0)

HCF_SEND_MBX_CMD NCF_SEND_MBX_ACK EMPTY netX has freed the mailbox

and access is switched
0 0
back to host
1 1

Back to step 1

Example: netX device sending a packet to the host (NCF_RECV / receive mailbox)
Stap Flags Mailbox State Description

1 Mailbox is inactive / no packet sent to device

NCF_RECV_MBX_CMD HCF_RECV_MBX_ACK EMPTY Access allowed by netX

1 1

0 0

2 netX sends a packet to the device

- Checking for state 1
- Copy packet data to receive mailbox
- Toggle NCF_RECV_MBX_CMD (1->0 or 0->1)

0 1 FULL Access switched to host

1 0

3 Host polls the flags and processes following functions

- Checking the handshake flags pairs(receive mailbox flags not equal => Packet in mailbox available)
- Access to mailbox is allowed
- Host copies the packet from the mailbox to internal RAM
- Host frees the mailbox by toggle HCF_RECEIVE_MBX_ACK (0->1 or 1->0)

NCF_RECV_MBX_CMD HCF_RECV_MBX_ACK EMPTY Host has freed the mailbox

and access is switched back
0 0
to netX
1 1

Back to step 1

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 31/53
NOTE: The system mailbox works in the same way, just the flags are named different and are
located in a different handshake register
HSF_SEND_MBX_CMD / NSF_SEND_MBX_ACK
NSF_RECV_MBX_CMD / HSF_RECV_MBX_ACK

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 32/53

3.6.3.4 I/O Data Transfer - Handshake Flag Synchronisation

The following flags pairs are used for I/O data transfer synchronization, the flags are found in the
communication channel handshake register (ulNetxFlags / ulHostFlags):
I/O Data Exchange
HCF_PDO_OUT_CMD / NCF_PD0_OUT_ACK
HCF_PDO_IN_CMD / NCF_PD0_IN_ACK

The I/O data transfer uses an additional definition (Handshake Mode) which defines the initiator of
a data transfer.
Handshake Mode Definition:
Buffered Host Controlled Mode Host initiates the INPUT/OUTPUT data update
Buffered Device Controlled Mode Device initiates the INPUT/OUTPUT data update

The combination of the flag state and the handshake mode is used to handle the I/O data transfer.

Example: Read INPUT data by the host in "Buffered Host Controlled Mode"
Step Flags INPUT State Description

1 Read INPUT process data by the host

HCF_PDO_IN_CMD NCF_PDO_IN_ACK FREE Access allowed by host

1 1

0 0

2 Host reads INPUT data in "Buffered Host Controlled Mode"

- Checking for state 1
- Copy INPUT data from the device to a local buffer
- Signal device to update INPUT data
- Toggle HCF_PDO_IN_CMD (1->0 or 0->1)

0 1 BUSY Access switched to device

which should update the data
1 0

3 Device updates the INPUT data area with local buffer holding the latest data received by the
fieldbus connection.
- Device getting an interrupt signalling changes in the host flags
- Checks the state of HCF_PDO_IN_CMD and NCF_PDO_IN_ACK
- Copies the actual local input data into the input process data area in the DPM
- Toggle NCF_PDO_IN_CMD (1->0 or 0->1)

HCF_PDO_IN_CMD NCF_PDO_IN_ACK DONE Device has updated the

INPUT data, access is
0 0
switched back to host
1 1

Host polls flags or waits on an I/O read event and processes following functions
- Copy the data from the DPM to a local buffer
- Processes the input data

Back to step 1

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 33/53

Example: Write OUTPUT data by the host in "Buffered Host Controlled Mode"
Step Flags OUTPUT Description
State

1 Write OUTPUT data to the output process data area

HCF_PDO_OUT_CMD NCF_PDO_OUT_ACK FREE Access allowed by host

1 1

0 0

2 Host writes OUTPUT data in "Buffered Host Controlled Mode"

- Checking for state 1
- Copy local OUTPUT data to the output process data area
- Signal device to take the OUTPUT data
- Toggle HCF_PDO_OUT_CMD (1->0 or 0->1)

0 1 DATA Access switched to device

available which should take the data
1 0

3 Device takes the OUTPUT data and copies the data to a local output buffer and sending the data
with the next bus cycle.
- Device getting an interrupt signalling changes in the host flags
- Checks the state of HCF_PDO_OUT_CMD and NCF_PDO_OUT_ACK
- Copies the actual OUTPUT data from the DPM to a local output buffer
- Toggle NCF_PDO_OUT_ACK (1->0 or 0->1)

HCF_PDO_OUT_CMD NCF_PDO_OUT_ACK DONE Device has taken the

OUTPUT data, access is
0 0
switched back to host
1 1

Back to step 1

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 34/53

ATTENTION: In "Device Controlled Mode" the initiator of the transfer changes from HOST to
netX and therefore also the flag meanings are changing (_CMD flags becoming
_ACK flags and _ACK flags becoming _CMD flags).

Example: Read INPUT data by the host in "Buffered Device Controlled Mode"
Step Flags OUTPUT Description
State

1 Read INPUT data by the host

NCF_PDO_IN_ACK HCF_PDO_IN_CMD FREE Access allowed by device

1 1

0 0

2 Device gets new INPUT data from the field bus connection and signals them to the host
"Buffered Device Controlled Mode"
- Checking for state 1
- Copy local INPUT data to the input process data area in the DPM
- Signal host to take the INPUT data
- Toggle NCF_PDO_IN_ACK (1->0 or 0->1)

0 1 DATA Access switched to the host,

available which should take the data
1 0

3 Host polls the handshake flags or waits on an INPUT event..

- Checks the state of NCF_PDO_IN_ACK and HCF_PDO_IN_CMD
- Copies the actual INPUT data from the DPM to a local input buffer
- Toggle HCF_PDO_IN_CMD (1->0 or 0->1)

NCF_PDO_IN_ACK HCF_PDO_IN_CMD DONE Host has taken the INPUT

data, access is switched
0 0
back to device
1 1

Back to step 1

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 35/53

Example: Write OUTPUT data by the host in "Buffered Device Controlled Mode"
Step Flags OUTPUT Description
State

1 Write OUTPUT data by the host

NCF_PDO_IN_ACK HCF_PDO_IN_CMD FREE Access allowed by device

1 1

0 0

2 Device gets new OUTPUT data from the DPM and copies them to the local output data buffer
"Buffered Device Controlled Mode"
- Checking for state 1
- Copy OUTPUT data from the DPM to the local output process data
- Signal host, data taken from the OUTPUT process data area
- Toggle NCF_PDO_OUT_ACK (1->0 or 0->1)

0 1 DATA Access switched to the host,

available which could place new
1 0
OUTPUT into the DPM

3 Host polls the handshake flags or waits on OUTPUT event

- Checks the state of NCF_PDO_OUT_ACK and HCF_PDO_OUT_CMD
- Copies the actual OUTPUT data from a local buffer to the DPM output process data area
- Toggle HCF_PDO_OUT_CMD (1->0 or 0->1)

NCF_PDO_OUT_ACK HCF_PDO_OUT_CMD DONE Host has placed new

OUTPUT data into the DPM,
0 0
access is switched back to
1 1 device

Back to step 1

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 36/53

3.6.3.5 Change of State Mechanism (COS)

A communication channel has more options and commands than bits in the handshake flag
register.
Therefore a so called "Change of State (COS)" mechanism is defined which extends the direct
usable handshake flags by another 32 Bit value with additional states.
Furthermore the COS mechanism expects an acknowledgement if a state change was signalled,
before another state change will be signalled.

This mechanism is direction oriented and distinguishes between state changes from the host
application and form the device:
Device state changes are named "Communication COS Handling"
Application state changes are named "Application COS Handling"

Communication COS Handling:

Change Of State (COS) - Communication COS Handling

Host Application DPM Layout

3 4
Communication Channel
Communication Channel 5

Common Status Block structure

Handshake Register NETX_COMMON_STATUS_BLOCK
netXFlags Host Flags Offset 0x0010 = ulCommunicationCOS

NCF_HOST_COS_CMD HCF_HOST_COS_ACK

2 1

netX Firmware

The netX device "COS" flags are located in the "Common Status Block" structure
NETX_COMMON_STATUS_BLOCK of a communication channel.

Common Status Block Structure

typedef struct NETX_COMMON_STATUS_BLOCKtag
{
UINT32 ulCommunicationCOS;
UINT32 ulCommunicationState;
UINT32 ulCommunicationError;
UINT16 usVersion;
UINT16 usWatchdogTime;
UINT8 bPDInHskMode;
UINT8 bPDInSource;
UINT8 bPDOutHskMode;
UINT8 bPDOutSource;
UINT32 ulHostWatchdog;
UINT32 ulErrorCount;

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 37/53
UINT8 bErrorLogInd;
UINT8 bErrorPDInCnt;
UINT8 bErrorPDOutCnt;
UINT8 bErrorSyncCnt;
UINT8 bSyncHskMode;
UINT8 bSyncSource;
UINT16 ausReserved[3];
union
{
NETX_MASTER_STATUS tMasterStatusBlock; /* for master implementation */
UINT32 aulReserved[6]; /* otherwise reserved */
} uStackDepended;
} NETX_COMMON_STATUS_BLOCK;

Example: Communication COS handling initiated by the device

Step Flags COS State Description

1 Device updates COS state information

NCF_NETX_COS_CMD HCF_NETX_COS_ACK FREE Access to COS flags allowed

by the device
1 1

0 0

2 Device updates COS information and signals new COS state

- Checking for state 1
- Copy new COS state to ulCommunicationCOS
- Signal host, new COS information
- Toggle NCF_NETX_COS_CMD (1->0 or 0->1)

0 1 new COS Access switched to the host,

information which could read COS
1 0
available information

3 Host polls the handshake flags

- Checks the state of NCF_NETX_COS_CMD and HCF_NETX_COS_ACK
- Copies the COS information from ulCommunicationCOS to a local buffer
- Toggle HCF_NETX_COS_ACK (1->0 or 0->1)

NCF_NETX_COS_CMD HCF_NETX_COS_ACK DONE Host has the new COS

information, access is
0 0
switched back to device
1 1

Back to step 1

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 38/53

Application COS Handling:

Change Of State (COS) - Application COS Handling

Host Application DPM Layout

5 1
2 Communication Channel
Communication Channel
Control Block structure
Handshake Register NETX_CONTROL_BLOCK
netXFlags Host Flags Offset 0x0008 = ulApplicationCOS

3
NCF_APP_COS_ACK HCF_APP_COS_CMD

netX Firmware

The application "COS" flags are located in the "Control Block" structure NETX_CONTROL_BLOCK
of a communication channel.

Control Block Structure

typedef struct NETX_CONTROL_BLOCKtag
{
UINT32 ulApplicationCOS;
UINT32 ulDeviceWatchdog;
} NETX_CONTROL_BLOCK;

Example: Application COS handling initiated by the host

Step Flags COS State Description

1 Application updates state information

HCF_APP_COS_CMD HCF_NETX_COS_ACK FREE Access to COS flags allowed

by the host
1 1

0 0

2 Host updates COS information and signals new COS state

- Checking for state 1
- Copy new COS state to ulApplicationCOS
- Signal device, new COS information
- Toggle HCF_APP_COS_CMD (1->0 or 0->1)

0 1 new COS Access switched to device,

information which could read COS
1 0
available information

3 Device gets an interrupt

- Checks the state of HCF_APP_COS_CMD and NCF_APP_COS_ACK
- Copies the COS information from ulApplicationCOS to a local buffer

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 39/53
- Toggle NCF_APP_COS_ACK (1->0 or 0->1)

HCF_APP_COS_CMD NCF_APP_COS_ACK DONE Devicehas the new COS

information, access is
0 0
switched back to host
1 1

Back to step 1

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Fundamentals - DPM Layout and Content 40/53

3.7 Programming Interface - CIFX-API

The CIFX API is the general application programming interface (API) which offers all necessary
function to handle a netX device.

The API offers general handling functions and functions corresponding to the DPM components
described above.
Example API functions:
Asynchronous Services (Packets)
API Function Description
xChannelGetMBXState Retrieve the channels mailbox state
xChannelGetPacket Read a packet from the channel receive mailbox
xChannelPutPacket Send a packet via the channel send mailbox
...........

Cyclic Data Services (I/O's)

API Function Description
xChannelIORead Instructs the device to place the latest data into the DPM input
data area and passes them to the user
xChannelIOWrite Copies the data to the DPM send data area and waits for the
firmware to retrieve them
..........

The complete API is described can be found in the "cifX API PR xx EN.pdf" manual.

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Examples 41/53

4 Examples
4.1 System Identification and Start-Up Handling
This flow chart describes the necessary start-up handling to identify a running netX boot loader or
firmware.

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Examples 42/53

4.2 Channel Identification and Start-Up Handling

After successful identified a system start-up, the following need to be done to verify a running
communication stacks.

Read channel type from

channel information block

no
Channel Type ==
RCX_CHANNEL_TYPE_COMMUNICATION?
yes

Get channel information from

channel information block:
Size of Channel In Bytes
Communication Class
Protocol Class

Read subblock layout

Read netX flags of communication

channel handshake register

no
no
RCX_COMM_COS_READY bit set? Timeout expired?
yes
yes

All communication channels

identified

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Examples 43/53

4.3 Packet Transfer

4.3.1 Send a Packet to the Device

CIFX-API Function: xChannelPutPacket()

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Examples 44/53

4.3.2 Read a Packet form the Device

CIFX-API Function: xChannelGetPacket()

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Examples 45/53

4.4 I/O Data Transfer

4.4.1 Write Output data to the Device

no
data length < = output area size?
yes

Read netX flags of communication

channel handshake register

no
no
HCF_PD0_OUT_CMD == NCF_PD0_OUT_ACK? Timeout expired?
yes
yes

Copy data to output area

Toggle HCF_PD0_OUT_CMD

Output area exchange done Exchange output area failed

CIFX-API Function: xChannelIOWrite()

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Examples 46/53

4.4.2 Read Input data from Device

CIFX-API Function: xChannelIORead()

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Examples 47/53

4.5 Change of State (COS) Information and Handling

4.5.1 Host COS Handling

CIFX-API Function: xChanneltHostState()

xChannelBusState()
xChannelConfigLog()

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Examples 48/53

4.5.2 Communication COS Handling

Read netX flags of communication

channel handshake register

no
no
HCF_NETX_COS_ACK != NCF_NETX_COS_CMD? Timeout expired?
yes
yes

Read communicaion COS bits

from common status block

Read netX flags of communication

channel handshake register

Toggle HCF_NETX_COS_ACK

Communication COS acknowledged No communication COS

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Examples 49/53

4.6 Hardware and Protocol Stack Identification

The DPM contains information to determine the hardware type and the protocol stack type. And if
the protocol is a master or slave stack.

Hardware Identification
This information can be found in the "System Information Block"
Device Class => DPM Offset 0x0028 usDeviceClass
Hardware Assembly Option
Defines which communication hardware is offered by the device
This information can be found in the "System Information Block"
Hardware Option => DPM Offset 0x0010 ausHwOptions

Protocol Stack Identification

The protocol stack identification per communication channel can be found in the Channel I
"Channel Information Block"
Therefore evaluate the channel type (bChannelType = COMMUNICATION) and read the
communication class (usCommunicationClass) and protocol class (usProtocolClass).

This information can be found in the "netX Dual Port Memory Interface DPM...pdf" manual.

4.7 Additional Functions

System and Channel Information
Can be read via xSysdeviceInfo()
Handshake States
Can be read via a xChannelInfo() function
Transfer Packet
If a synchronous packet transfer must be realized, where the user function has to wait until
the answer to the previously command packet is received, a transfer packet functions must
be implemented by using xChannelPutPacket() and xChannelGetPacket().
Interrupt mode / Event handling
Event handling can be used if the hardware is handled in interrupt mode. Than the toolkit /
drivers are able to create events for an application to signall state changes of the hardware.
The user application can use the xChannelRegisterEvent() function to use hardware events.
Watchdog
The CIFX API offers a watchdog function per channel, where the protocol stack is able to
supervise an user application and if the user application failes, the bus communication can
be stopped. See xChannelWatchdog() function in the CIFX API.
DMA
PCI bus based netX hardware is able to work as a bus master DMA device. This means the
hardware can active read and write data form the memory of a host system.
The netX DMA mode is limited to the Input/Output data from the netX hardware.
The CIFX API offers a xChannelDMAState() functions to switch the I/O data exchange with

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Examples 50/53
the hardware to DMA mode assumed, the hardware is PCI bus based and runs in interrupt
mode.

4.8 Hardware and Driver Installation Guides

Hilscher devices are delivered with a hardware and driver installation guide describing the step by step
handling to get a working netX device into a PC based host system

A description on how to install and pre-configure the hardware you will found under:
.\documentation\Installation - "cifX Device Driver Installation for Windows"

4.9 Load a Firmware to a CIFX Card

Hilscher offers different communication devices. PC based CIFX cards like CIFX50 / CIFX70 / CIFX90
devices, which are PCI bus based so not store the firmware and configuration file on the hardware.

Such devices must be pre-loaded with a firmware to be usable by a configuration tool or by any application
which want a field bus protocol firmware.

Actual firmware can be taken from the "Communication Solution DVD" (either shipped with the device or
downloadable Hilscher web site the following link:
http://de.hilscher.com/hcde/files_software/Communication_Solutions_DVD_20xx-xx-1..............

Go to the "Firmware" sub-directory and choose the appropriate firmware for your hardware (like described in
the "cifX Device Driver Installation for Windows" manual.

On COMX module the firmware is stored on the hardware and a firmware download during start-up is not
necessary.

4.10 Start with an Example Program

After loading the hardware with the necessary firmware (in case of PCI based devices) it is possible to use it
and to start with example programs (e.g. "cifxTest_console example" from the CIFX Driver CD, see
.\examples\cifXTest_console)

This example contains most of the CIFX API functions in separate source modules an mostly contains a
corresponding project file (e.g. Microsoft Visual Studio project under Windows) which can be used to compile
and run the example.

The main function of the example can be found in the source module cifXTest_console.cpp which than calls
the function RunCifXConsoleTest() in the source module cifXConsole_Main.cpp for further processing.

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Additional Resources 51/53

4.11 Protocol Stack handling via CIFX API

An overview of the minimal necessary API functions and the order how they should be called can be found in
the CIFX-API manual Chapter 5 and 6.

5 Additional Resources
5.1 Protocol API Manuals
Each fieldbus protocol stack has it own documentation, describing the protocol specific functions
and commands.
Protocol API manuals can be found on the "Communication Solution DVD" in the
.\Documentation\Programming Manuals\ directory and the manual file names are containing the
protocol stack name, e.g. "PROFIBUS Master Protocol API....pdf"

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Appendix 52/53

6 Appendix
6.1 List of Tables
Table 1: List of Revisions .................................................................................................................................................... 5
Table 2: Terms, Abbreviations and Definitions.................................................................................................................... 6
Table 3: General Packet Structure .................................................................................................................................... 22
Table 4: Host System Flags / netX System Flags ............................................................................................................. 26
Table 5: Host Communication Flags / netX Communication Channel Flags ..................................................................... 27

6.2 List of Figures

Figure 1: Overview - Programming Levels .......................................................................................................................... 9
Figure 2: Choose a Programming Levels .......................................................................................................................... 10

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013
Appendix 53/53

6.3 Contacts

Headquarters

Germany
Hilscher Gesellschaft für
Systemautomation mbH
Rheinstrasse 15
65795 Hattersheim
Phone: +49 (0) 6190 9907-0
Fax: +49 (0) 6190 9907-50
E-Mail: info@hilscher.com
Support
Phone: +49 (0) 6190 9907-99
E-Mail: de.support@hilscher.com

Subsidiaries

China Japan
Hilscher Systemautomation (Shanghai) Co. Ltd. Hilscher Japan KK
200010 Shanghai Tokyo, 160-0022
Phone: +86 (0) 21-6355-5161 Phone: +81 (0) 3-5362-0521
E-Mail: info@hilscher.cn E-Mail: info@hilscher.jp
Support Support
Phone: +86 (0) 21-6355-5161 Phone: +81 (0) 3-5362-0521
E-Mail: cn.support@hilscher.com E-Mail: jp.support@hilscher.com

France Korea
Hilscher France S.a.r.l. Hilscher Korea Inc.
69500 Bron Suwon, Gyeonggi, 443-734
Phone: +33 (0) 4 72 37 98 40 Phone: +82 (0) 31-695-5515
E-Mail: info@hilscher.fr E-Mail: info@hilscher.kr
Support
Phone: +33 (0) 4 72 37 98 40 Switzerland
E-Mail: fr.support@hilscher.com Hilscher Swiss GmbH
4500 Solothurn
India Phone: +41 (0) 32 623 6633
Hilscher India Pvt. Ltd. E-Mail: info@hilscher.ch
New Delhi - 110 065 Support
Phone: +91 11 43055431 Phone: +49 (0) 6190 9907-99
E-Mail: info@hilscher.in E-Mail: ch.support@hilscher.com

Italy USA
Hilscher Italia S.r.l. Hilscher North America, Inc.
20090 Vimodrone (MI) Lisle, IL 60532
Phone: +39 02 25007068 Phone: +1 630-505-5301
E-Mail: info@hilscher.it E-Mail: info@hilscher.us
Support Support
Phone: +39 02 25007068 Phone: +1 630-505-5301
E-Mail: it.support@hilscher.com E-Mail: us.support@hilscher.com

cifX/netX Application Programmers Guide |

DOC13xxxxPGxxEN | Revision 0 | English | 2014-02 | development | Public © Hilscher, 2013