sercos Master Protocol API V2.1.x.x Hilscher Gesellschaft für Systemautomation mbh

Transcription

1 Protocol API sercos Master V2.1.x.x Hilscher Gesellschaft für Systemautomation mbh DOC081103API11EN Revision 11 English Released Public

2 Table of Contents 2/390 Table of Contents 1 Introduction About this Document List of Revisions Intended Audience System Requirements Specifications Technical Data Terms, Abbreviations and Definitions References Legal Notes Copyright Important Notes Exclusion of Liability Export Fundamentals General Access Mechanisms on netx Systems Accessing the Protocol Stack by Programming the AP Task s Queue Getting the Receiver Task Handle of the Process Queue Meaning of Source- and Destination-related Parameters Accessing the Protocol Stack via the Dual Port Memory Interface Communication via Mailboxes Using Source and Destination Variables correctly Obtaining useful Information about the Communication Channel Client/Server Mechanism Application as Client Application as Server Dual-Port Memory Cyclic Data (Input/Output Data) Input Process Data Output Process Data Acyclic Data (Mailboxes) General Structure of Messages or Packets for Non-Cyclic Data Exchange Status & Error Codes Differences between System and Channel Mailboxes Send Mailbox Receive Mailbox Channel Mailboxes (Details of Send and Receive Mailboxes) Status Common Status Extended Status Control Block Getting started / Configuration Overview about Essential Functionality Configuration of sercos Master Using the configuration tool SYCON.net Using configuration via packets Detailed Description of Master Parameters Overview Task Structure of the sercos Master Stack General Structure of the sercos Stack State Machine (Communication Phases) State Transitions Non real-time Mode (NRT Mode) Communication Phase 0 (CP0) Communication Phase 1 (CP1) Communication Phase 2 (CP2) Communication Phase 3 (CP3) Communication Phase 4 (CP4) SCP Classes...55

3 Table of Contents 3/ SCP_FixCFG / SCP_VarCFG / SCP_RTB (Real-Time Bits) SCP_Sync SCP_SysTime SCP_WD / SCP_WDCon SCP_Diag SCP_HP (Hot Plug) SCP_SMP SCP_MuX / SCP_ExtMuX (multiplex channel) SCP_SIG / SCP_RTBListProd / SCP_RTBListCons / SCP_RTBWordProd / SCP_RTBWordCons SCP_ListSeg SCP_NRT / SCP_NRTPC SCP_SIP SCP_TFTP SCP_Cap SCP_SafetyCon SCP_OvSBasic SCP_Cyc Commonly Used Values in Packets Values for Identifying Communication Phases in Packets NRT Reason Codes Stop Reason Codes For State Change Abort Bit List Layout for All Slaves Status Representation Stack Mode Flags Addressing of Slaves in Application Interface Addressing Schemes Operation Modes Procedure Commands Executing Procedure Commands via Svc Macro Functions Procedure Command Control and Acknowledge Definitions The Procedure Command Change Bit Diagnosis Slave Diagnostic Information Diagnostic Log C1D and C2D Bus Scan Ring Topology and Ring Healing Hot Plug (since V2.1.X) Process Data Connection Control (C-CON) Process Data Exchange Timing Bus-synchronous Mode Free-Run Mode (only available for DPM/SHM) NRT Channel Behavior Routing Behavior Ring Detection NRT Channel Access on DPM The Application Interface Configuration Data Packets Auto Configuration Service Process Data Image Layout Configuration Connection Control Handling Configuration (since V2.1.X) Parameters used in all Variants Parameters used for automatic Configuration of Frame Layout Common Services (all Packet Configuration Variants) Automatic Configuration of Frame Layout with automatic Timing Calculation Automatic Configuration of Frame Layout with user specified Timing Parameters Usage and Flow Diagram of automatic Configuration Packets Packets used for automatic Configuration (AutoCfg) of Frame Layout Manual Configuration of Frame Layout and Timing Parameters Usage and Flow Diagram of manual Configuration of Frame Layout Packets used for manual Configuration Unload Configuration Service Configuration Information Readout Get CP3/CP4 Timing Information Service Get Configured List Of Slaves Service (since version V2.1.X) Get Configured Slave Identification Data Service (since version V2.1.X) Get Configured Connections Of Slave Service (since version V2.1.X)

4 Table of Contents 4/ Get Connection Information Service Get Configured Connection Layout Service (since version V2.1.X) Phase Control Architecture of Communication Phase Control Services Legacy Services Status Indications Registration and Deregistration of Status Indications Common Indications Legacy Indications Diagnostic Log Diagnostic Log Entry Format Reading and Clearing Diagnostic Log Indication Handling Slave Identification Services Get Detected sercos Addresses Service Controlling the C-DEV Ident Request Bit Set Ident Request Bit Service Clear Ident Request Bit Service Service Channel Access Changes in Packets since V2.1.X Priority Level System Data Representation in the Data Part of Packets Common Parameters of Service Channel Services Macro SVC Services Macro SVC Services (Extended Length, since V2.1.X) Atomic SVC Services Atomic SVC Services (Extended Length, since V2.1.X) Fragmentation Flow Charts Hot Plug (since V2.1.X) Hot Plug Indication Hot Plug Error Acknowledgement Service Retrieval of Slave Diagnostic Information Relation: Slave Diagnostic Handles and Slave Addresses Provided Lists Usage of Slave Diagnostic Information Packets Structure of per Slave Diagnostic Data Packets Bus Scan Packet Parameter ulslaveflags Generic Bus Scan Legacy Bus Scan Manual Ring Healing Control Set Ring Healing to Manual Service Set Ring Healing to Automatic Service Request Manual Ring Healing Service Get Ring Status Service (since V2.1.X) NRT Promiscuous Control Enable NRT Promiscuous Service Disable NRT Promiscuous Service Status/Error Codes Overview Appendix LED Definitions Device Status and Device Control Device Status (S-DEV) Device Control (C-DEV) Object Dictionary General Access Procedure IDN Structure Name Attribute Unit Minimum / Maximum Data sercos Service Channel Error Codes List of Tables...384

5 Table of Contents 5/ List of Figures Contacts...390

6 Introduction 6/390 1 Introduction 1.1 About this Document This manual describes the Application interface of the sercos-master Stack. The goal of this manual is to support the developer during the integration process of the given Stack into a user Application. This sercos Master Stack is based on the Hilscher Task Layer Reference Programming Model. It is a description of how to program a Task in general, which is defined as a combination of appropriate functions belonging to the same type of protocol layer. It furthermore defines of how different Tasks have to communicate with each other in order to exchange their layer information in between. The Reference Model is commonly used by all programmers at Hilscher and shall be used by you as well when writing your Application Task on top of the Stack. 1.2 List of Revisions Rev Date Name Chapter Revision SB/RG Firmware/stack version V 2.1.x.x Details to packet based configuration added. Flow diagrams added. Some error codes added SB/RG Firmware/stack version V 2.1.x.x SB/RG Firmware/stack version V 2.1.x.x Section Technical Data: NRT channel support added, Cross communication (requires configuration by packets) added. Integrated TCP/IP stack added Table 1: List of Revisions

7 Introduction 7/ Intended Audience This manual is suitable for software developers with the following background: Knowledge of the programming language C Knowledge of the use of the real-time operating system rcx Knowledge of the Hilscher Task Layer Reference Mode Knowledge of sercos 1.4 System Requirements This software package has the following system requirements: netx-chip as CPU hardware platform operating system for task scheduling required operating system: rcx

8 Introduction 8/ Specifications The data below applies to sercos Master firmware and stack version 2.1.x.x. The firmware and stack has been written in order to meet the sercos V1.3 specification Technical Data Feature Parameter Maximum number of cyclic input data 5760 bytes (including Connection Control per Connection) Maximum number of cyclic output data 5760 bytes (including Connection Control per Connection) Maximum number of configured slave devices 511 Minimum cycle time 250 µs Acyclic communication Service channel: Read/Write/Commands Functions Bus Scan Communication phases NRT, CP0, CP1, CP2, CP3, CP4 Topology Line and double ring Redundancy Supported NRT channel Supported Hot Plug Supported Cross communication Supported, but only if the master is configured by the host application program by packets. Baud rate 100 MBit/s, full duplex Data transport layer Ethernet II, IEEE Auto crossover Supported Supported sercos version Communication Specification Version 1.3 TCP/IP stack Integrated Table 2: Technical Data of the Protocol Stack Limitations NRT communication: The second dual-port memory channel ( Ethernet Interface Task ) is not available on COMX communication modules.

9 Introduction 9/ Terms, Abbreviations and Definitions Term Description AHS service transport handshake of the slave (acknowledge handshake) AP Application on top of the Stack API Application Programmer Interface AT Acknowledge telegram CP Communication phase IDN Identification number (of a parameter) MDT Master data telegram MHS service transport handshake of the master MST sercos header of MDT0 MTU Maximum transfer unit S3M sercos Master S3S sercos Slave SVC Service Channel Table 3: Terms, abbreviations and definitions All variables, parameters and data used in this manual have basically the LSB/MSB ( Intel ) data representation. This corresponds to the convention of the Microsoft C Compiler. 1.7 References This document based on the following specification respectively documents: [1] Hilscher Gesellschaft für Systemautomation mbh: Task Layer Reference Manual [2] Hilscher Gesellschaft für Systemautomation mbh: Dual-Port Memory Interface Manual, netx based products. Revision 12, English, 2012 [3] Hilscher Gesellschaft für Systemautomation mbh: Automatic Bus Scan, Revision 4, English, 2011 [4] sercos V1.3 Specification [5] Hilscher Gesellschaft für Systemautomation mbh: Ethernet Protocol API,. Revision 5, English, 2009 Table 4: References

10 Introduction 10/ Legal Notes Copyright Hilscher Gesellschaft für Systemautomation mbh All rights reserved. The images, photographs and texts in the accompanying material (user manual, accompanying texts, documentation, etc.) are protected by German and international copyright law as well as international trade and protection provisions. You are not authorized to duplicate these in whole or in part using technical or mechanical methods (printing, photocopying or other methods), to manipulate or transfer using electronic systems without prior written consent. You are not permitted to make changes to copyright notices, markings, trademarks or ownership declarations. The included diagrams do not take the patent situation into account. The company names and product descriptions included in this document may be trademarks or brands of the respective owners and may be trademarked or patented. Any form of further use requires the explicit consent of the respective rights owner Important Notes The user manual, accompanying texts and the documentation were created for the use of the products by qualified experts, however, errors cannot be ruled out. For this reason, no guarantee can be made and neither juristic responsibility for erroneous information nor any liability can be assumed. Descriptions, accompanying texts and documentation included in the user manual do not present a guarantee nor any information about proper use as stipulated in the contract or a warranted feature. It cannot be ruled out that the user manual, the accompanying texts and the documentation do not correspond exactly to the described features, standards or other data of the delivered product. No warranty or guarantee regarding the correctness or accuracy of the information is assumed. We reserve the right to change our products and their specification as well as related user manuals, accompanying texts and documentation at all times and without advance notice, without obligation to report the change. Changes will be included in future manuals and do not constitute any obligations. There is no entitlement to revisions of delivered documents. The manual delivered with the product applies. Hilscher Gesellschaft für Systemautomation mbh is not liable under any circumstances for direct, indirect, incidental or follow-on damage or loss of earnings resulting from the use of the information contained in this publication.

11 Introduction 11/ Exclusion of Liability The software was produced and tested with utmost care by Hilscher Gesellschaft für Systemautomation mbh and is made available as is. No warranty can be assumed for the performance and flawlessness of the software for all usage conditions and cases and for the results produced when utilized by the user. Liability for any damages that may result from the use of the hardware or software or related documents, is limited to cases of intent or grossly negligent violation of significant contractual obligations. Indemnity claims for the violation of significant contractual obligations are limited to damages that are foreseeable and typical for this type of contract. It is strictly prohibited to use the software in the following areas: for military purposes or in weapon systems; for the design, construction, maintenance or operation of nuclear facilities; in air traffic control systems, air traffic or air traffic communication systems; in life support systems; in systems in which failures in the software could lead to personal injury or injuries leading to death. We inform you that the software was not developed for use in dangerous environments requiring fail-proof control mechanisms. Use of the software in such an environment occurs at your own risk. No liability is assumed for damages or losses due to unauthorized use Export The delivered product (including the technical data) is subject to export or import laws as well as the associated regulations of different counters, in particular those of Germany and the USA. The software may not be exported to countries where this is prohibited by the United States Export Administration Act and its additional provisions. You are obligated to comply with the regulations at your personal responsibility. We wish to inform you that you may require permission from state authorities to export, re-export or import the product.

12 Fundamentals 12/390 2 Fundamentals 2.1 General Access Mechanisms on netx Systems This chapter explains the possible ways to access a Protocol Stack running on a netx system : 1. By accessing the Dual Port Memory Interface directly or via a driver. 2. By accessing the Dual Port Memory Interface via a shared memory. 3. By interfacing with the Stack Task of the Protocol Stack. The picture below visualizes these three ways: 1 2 (Extended) Status Block Send Mailbox Reveive Mailbox Output Data Image Input Data Image AP Task 3 Fieldbus Task(s) Network Abstraction Layer Network Figure 1: The three different Ways to access a Protocol Stack running on a netx System This chapter explains how to program the stack (alternative 3) correctly while the next chapter describes accessing the protocol stack via the dual-port memory interface according to alternative 1 (and 2, if the user application is executed on the netx chip in the context of the rcx operating system and uses the shared DPM). Finally, chapter 6 titled The Application Interface describes the entire interface to the protocol stack in detail. Depending on you choose the stack-oriented approach or the Dual Port Memory-based approach, you will need either the information given in this chapter or those of the next chapter to be able to work with the set of functions described in chapter 5. All of those functions use the four parameters uldest, ulsrc, uldestid and ulsrcid. This chapter and the next one inform about how to work with these important parameters.

13 Fundamentals 13/ Accessing the Protocol Stack by Programming the AP Task s Queue In general, programming the AP task or the stack has to be performed according to the rules explained in the Hilscher Task Layer Reference Manual. There you can also find more information about the variables discussed in the following Getting the Receiver Task Handle of the Process Queue To get the handle of the process queue of the CP-Task the Macro TLR_QUE_IDENTIFY() needs to be used. This macro delivers a pointer to the handle of the intended queue to be accessed (which is returned within the third parameter, phque), if you provide it with the name of the queue (and an instance of your own task). The correct ASCII-queue names for accessing the CP-Task, which you have to use as current value for the first parameter (pszidn), is ASCII Queue name Description "QUE_S3M_CP Name of the CP-Task process queue Table 5: Names of Queues in the sercos Master Firmware The returned handle has to be used as value uldest in all initiator packets the AP-Task intends to send to the CP-Task. This handle is the same handle that has to be used in conjunction with the macros like TLR_QUE_SENDPACKET_FIFO/LIFO() for sending a packet to the respective task. Note: The CP-Task provides a common access point to all master tasks when the AP- Task is not used (since V2.1.X) Meaning of Source- and Destination-related Parameters The meaning of the source- and destination-related parameters is explained in the following table: Variable Meaning uldest Application mailbox used for confirmation ulsrc Queue handle returned by TLR_QUE_IDENTIFY() as described above. ulsrcid Used for addressing at a lower level Table 6: Meaning of Source- and Destination-related Parameters. For more information about programming the AP task s stack queue, please refer to the Hilscher Task Layer Reference Model Manual. Especially the following sections might be of interest in this context: 1. Chapter 7 Queue-Packets 2. Section Queuing Mechanism

14 Fundamentals 14/ Accessing the Protocol Stack via the Dual Port Memory Interface This chapter defines the application interface of the sercos Master Stack Communication via Mailboxes The mailbox of each communication channel has two areas that are used for non-cyclic message transfer to and from the netx. Send Mailbox Receive Mailbox Packet transfer from host system to netx firmware Packet transfer from netx firmware to host system For more details about acyclic data transfer via mailboxes, see section 3.2. Acyclic Data (Mailboxes) in this context, is described in detail in section General Structure of Messages or Packets for Non-Cyclic Data Exchange while the possible codes that may appear are listed in section Status & Error Codes. Further, this section concentrates on correct addressing the mailboxes.

15 Fundamentals 15/ Using Source and Destination Variables correctly How to use uldest for Addressing rcx and the netx Protocol Stack by the System and Channel Mailbox The preferred way to address the netx operating system rcx is through the system mailbox; the preferred way to address a protocol stack is through its channel mailbox. All mailboxes, however, have a mechanism to route packets to a communication channel or the system channel, respectively. Therefore, the destination identifier uldest in a packet header has to be filled in according to the targeted receiver. See the following example: uldest = 0x20 uldest = 0x00 uldest = 0x01 uldest = 0x02 uldest = 0x20 uldest = 0x00 uldest = 0x01 uldest = 0x02 uldest = 0x20 uldest = 0x00 uldest = 0x01 uldest = 0x02 System Mailbox Channel 0 Mainbox Channel 1 Mailbox netx OS rcx AP Task 1 AP Task 2 Figure 2 - Use of uldest in Channel and System Mailbox For use in the destination queue handle, the tasks have been assigned to hexadecimal numerical values as described in the following table: uldest Description 0x0000 Packet is passed to the netx operating system rcx 0x0001 Packet is passed to communication channel 0 0x0002 Packet is passed to communication channel 1 0x0003 Packet is passed to communication channel 2 0x0004 Packet is passed to communication channel 3 0x0020 Packet is passed to communication channel of the mailbox else Reserved, do not use Table 7: Meaning of Destination-Parameter uldest.parameters The figure and the table above both show the use of the destination identifier uldest.

16 Fundamentals 16/390 A remark on the special channel identifier 0x0020 (= Channel Token). The Channel Token is valid for any mailbox. That way the application uses the same identifier for all packets without actually knowing which mailbox or communication channel is applied. The packet stays 'local'. The system mailbox is a little bit different, because it is used to communicate to the netx operating system rcx. The rcx has its own range of valid commands codes and differs from a communication channel. Unless there is a reply packet, the netx operating system returns it to the same mailbox the request packet went through. Consequently, the host application has to return its reply packet to the mailbox the request was received from How to use ulsrc and ulsrcid Generally, a netx protocol stack can be addressed through its communication channel mailbox. The example below shows how a host application addresses a protocol stack running in the context of a netx chip. The application is identified by a number (#444 in this example). The application consists of three processes identified by the numbers #11, #22 and #33. These processes communicate through the channel mailbox with the AP task of the protocol stack. Have a look at the following figure: Application #444 Process #11 Process #22 Process #33 Channel Mailbox netx Protocol stack AP Task 1 Figure 3 - Using ulsrc and ulsrcid

17 Fundamentals 17/390 Example: This example applies to command messages initiated by a process in the context of the host application. If the process #22 sends a packet through the channel mailbox to the AP task, the packet header has to be filled in as follows: Object Destination Queue Handle Source Queue Handle Destination Identifier Variable Name uldest = 32 Numeric Value Explanation (0x0020) This value needs always to be set to 0x0020 (the channel token) when accessing the protocol stack via the local communication channel mailbox. ulsrc = 444 Denotes the host application (#444). uldestid = 0 In this example, it is not necessary to use the destination identifier. Source Identifier ulsrcid = 22 Denotes the process number of the process within the host application and needs therefore to be supplied by the programmer of the host application. Table 8 Example for correct Use of Source- and Destination-related parameters.: For packets through the channel mailbox, the application uses 32 (= 0x20, Channel Token) for the destination queue handler uldest. The source queue handler ulsrc and the source identifier ulsrcid are used to identify the originator of a packet. The destination identifier uldestid can be used to address certain resources in the protocol stack. It is not used in this example. The source queue handler ulsrc has to be filled in. Therefore, its use is mandatory; the use of ulsrcid is optional. The netx operating system passes the request packet to the protocol stack's AP task. The protocol stack then builds a reply to the packet and returns it to the mailbox. The application has to make sure that the packet finds its way back to the originator (process #22 in the example) How to Route rcx Packets To route an rcx packet the source identifier ulsrcid and the source queues handler ulsrc in the packet header hold the identification of the originating process. The router saves the original handle from ulsrcid and ulsrc. The router uses a handle of its own choices for ulsrcid and ulsrc before it sends the packet to the receiving process. That way the router can identify the corresponding reply packet and matches the handle from that packet with the one stored earlier. Now the router replaces its handles with the original handles and returns the packet to the originating process.

18 Fundamentals 18/ Obtaining useful Information about the Communication Channel A communication channel represents a part of the Dual Port Memory and usually consists of the following elements: Output Data Image Input Data Image Send Mailbox Receive Mailbox Control Block is used to transfer cyclic process data to the network (normal or highpriority) is used to transfer cyclic process data from the network (normal or highpriority) is used to transfer non-cyclic data to the netx is used to transfer non-cyclic data from the netx allows the host system to control certain channel functions Common Status Block holds information common to all protocol stacks Extended Status Block holds protocol specific network status information This section describes a procedure how to obtain useful information for accessing the communication channel(s) of your netx device and to check if it is ready for correct operation. Proceed as follows: 1. Start with reading the channel information block within the system channel (usually starting at address 0x0030). 2. Then you should check the hardware assembly options of your netx device. They are located within the system information block following offset 0x0010 and stored as data type UINT16. The following table explains the relationship between the offsets and the corresponding xc Ports of the netx device: 0x0010 0x0012 0x0014 0x0016 Hardware Assembly Options for xc Port[0] Hardware Assembly Options for xc Port[1] Hardware Assembly Options for xc Port[2] Hardware Assembly Options for xc Port[3] Check each of the hardware assembly options whether its value has been set to RCX_HW_ASSEMBLY_ETHERNET = 0x0080. If true, this denotes that this xcport is suitable for running the sercos Master protocol stack. Otherwise, this port is designed for another communication protocol. In most cases, xc Port[2] will be used for field bus systems, while xc Port[0] and xc Port[1] are normally used for Ethernet communication.

19 Fundamentals 19/ You can find information about the corresponding communication channel (0 3) under the following addresses: 0x0050 Communication Channel 0 0x0060 Communication Channel 1 0x0070 Communication Channel 2 0x0080 Communication Channel 3 In devices which support only one communication system which is usually the case (either a single field bus system or a single standard for Industrial-Ethernet communication), always communication channel 0 will be used. In devices supporting more than one communication system you should also check the other communication channels. 4. There you can find such information as the ID (containing channel number and port number) of the communication channel, the size and the location of the handshake cells, the overall number of blocks within the communication channel and the size of the channel in bytes. Evaluate this information precisely in order to access the communication channel correctly. The information is delivered as follows: Size of Channel in Bytes Address Data Type Description 0x0050 UINT8 Channel Type = COMMUNICATION (must have the fixed value define RCX_CHANNEL_TYPE_COMMUNICATION = 0x05) 0x0051 UINT8 ID (Channel Number, Port Number) 0x0052 UINT8 Size / Position Of Handshake Cells 0x0053 UINT8 Total Number Of Blocks Of This Channel 0x0054 UINT32 Size Of Channel In Bytes 0x0058 UINT8[8] Reserved (set to zero) These addresses correspond to communication channel 0, for communication channels 1, 2 and 3 you have to add an offset of 0x0010, 0x0020 or 0x0030 to the address values, respectively.

20 Fundamentals 20/ Client/Server Mechanism Application as Client The host application may send request packets to the netx firmware at any time (transition 1 2). Depending on the protocol stack running on the netx, parallel packets are not permitted (see protocol specific manual for details). The netx firmware sends a confirmation packet in return, signaling success or failure (transition 3 4) while processing the request. The host application has to register with the netx firmware in order to receive indication packets (transition 5 6). Depending on the protocol stack, this is done either implicit (if application opens a TCP/UDP socket) or explicit. Details on when and how to register for certain events is described in the protocol specific manual. Depending on the command code of the indication packet, a response packet to the netx firmware may or may not be required (transition 7 8). Figure 4: Transition Chart Application as Client The host application sends request packets to the netx firmware. The netx firmware sends a confirmation packet in return. The host application receives indication packets from the netx firmware. The host application sends response packet to the netx firmware (may not be required). Request Confirmation Indication Response

21 Fundamentals 21/ Application as Server The host application has to register with the netx firmware in order to receive indication packets. Depending on the protocol stack, this is done either implicit (if application opens a TCP/UDP socket) or explicit. Details on when and how to register for certain events is described in the protocol specific manual. When an appropriate event occurs and the host application is registered to receive such a notification, the netx firmware passes an indication packet through the mailbox (transition 1 2). The host application is expected to send a response packet back to the netx firmware (transition 3 4). Figure 5: Transition Chart Application as Server The netx firmware passes an indication packet through the mailbox. The host application sends response packet to the netx firmware. Indication Response

22 Dual-Port Memory 22/390 3 Dual-Port Memory All data in the dual-port memory is structured in blocks. According to their functions, these blocks use different data transfer mechanisms. For example, data transfer through mailboxes uses a synchronized handshake mechanism between host system and netx firmware. The same is true for IO data images, when a buffered handshake mode is configured. Other blocks, like the status block, are read by the host application and use no synchronization mechanism. Types of blocks in the dual-port memory are outlined below: Mailbox transfer non-cyclic messages or packages with a header for routing information Data Area Control Block Status Block Change of State holds the process image for cyclic I/O data or user defined data structures is used to signal application related state to the netx firmware holds information regarding the current network state collection of flags that initiate execution of certain commands or signal a change of state 3.1 Cyclic Data (Input/Output Data) The input block holds the process data image received from the network whereas the output block holds data sent to the network Process data transfer through the data blocks can be synchronized by using a handshake mechanism (configurable). If in uncontrolled mode, the protocol stack updates the process data in the input and output data image in the dual-port memory for each valid bus cycle. No handshake bits are evaluated and no buffers are used. The application can read or write process data at any given time without obeying the synchronization mechanism otherwise carried out via handshake location. This transfer mechanism is the simplest method of transferring process data between the protocol stack and the application. This mode can only guarantee data consistency over a byte. For the controlled / buffered mode, the protocol stack updates the process data in the internal input buffer for each valid bus cycle. Each IO block uses handshake bits for access synchronization. Input and output data block handshake operates independently from each other. When the application toggles the input handshake bit, the protocol stack copies the data from the internal buffer into the input data image of the dual-port memory. Now the application can copy data from the dual-port memory and then give control back to the protocol stack by toggling the appropriate input handshake bit. When the application/driver toggles the output handshake bit, the protocol stack copies the data from the output data image of the dual-port memory into the internal buffer. From there the data is transferred to the network. The protocol stack toggles the handshake bits back, indicating to the application that the transfer is finished and a new data exchange cycle may start. This mode guarantees data consistency over both input and output area.

23 Dual-Port Memory 23/ Input Process Data The input data block is used by field bus and industrial Ethernet protocols that utilize a cyclic data exchange mechanism. The input data image is used to receive cyclic data from the network. The default size of the input data image is 5760 byte. However, not all available space is actually used by the protocol stack. Depending on the specific protocol, the area actually available for user data might be much smaller than 5760 byte. An input data block may or may not be available in the dual-port memory. It is always available in the default memory map (see the netx Dual-Port Memory Manual). Input Data Image Offset Type Name Description 0x2680 UINT8 abpd0input[5760] Input Data Image Cyclic Data From The Network Table 9: Input Data Image Output Process Data The output data block is used by field bus and industrial Ethernet protocols that utilize a cyclic data exchange mechanism. The output data Image is used to send cyclic data from the host to the network. The default size of the output data image is 5760 byte. However, not all available space is actually used by the protocol stack. Depending on the specific protocol, the area actually available for user data might be much smaller than 5760 byte. An output data block may or may not be available in the dual-port memory. It is always available in the default memory map (see netx DPM Manual). Output Data Image Offset Type Name Description 0x1000 UINT8 abpd0output[5760] Output Data Image Cyclic Data To The Network Table 10: Output Data Image

24 Dual-Port Memory 24/ Acyclic Data (Mailboxes) The mailbox of each communication channel has two areas that are used for non-cyclic message transfer to and from the netx processor. Send Mailbox Receive Mailbox Packet transfer from host system to firmware Packet transfer from firmware to host system The send and receive mailbox areas are used by field bus and industrial Ethernet protocols providing a non-cyclic data exchange mechanism. Another use of the mailbox system is to allow access to the firmware running on the netx chip itself for diagnostic and identification purposes. The send mailbox is used to transfer acyclic data to the network or to the firmware. The receive mailbox is used to transfer acyclic data from the network or from the firmware. A send/receive mailbox may or may not be available in the communication channel. It depends on the function of the firmware whether or not a mailbox is needed. The location of the system mailbox and the channel mailbox is described in the netx DPM Interface Manual. Note: Each mailbox can hold one packet at a time. The netx firmware stores packets that are not retrieved by the host application in a packet queue. This queue has limited space and may fill up so new packets maybe lost. To avoid these data loss situations, it is strongly recommended to empty the mailbox frequently, even if packets are not expected by the host application. Unexpected command packets should be returned to the sender with an Unknown Command in the status field; unexpected reply messages can be discarded.

25 Dual-Port Memory 25/ General Structure of Messages or Packets for Non-Cyclic Data Exchange The non-cyclic packets through the netx mailbox have the following structure: Structure Information Type: Variable Type Value / Range Description Head - Structure Information 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 ulsta UINT32 Status / Error Code ulcmd UINT32 Command / Response ulext UINT32 Extension Flags ulrout UINT32 Routing Information Data - Structure Information User Data Specific To The Command Table 11: General Structure of Packets for non-cyclic Data Exchange. Some of the fields are mandatory; some are conditional; others are optional. However, the size of a packet is always at least 10 double-words or 40 bytes. Depending on the command, a packet may or may not have a data field. If present, the content of the data field is specific to the command, respectively the reply. Destination Queue Handle The uldest field identifies a task queue in the context of the netx firmware. The task queue represents the final receiver of the packet and is assigned to a protocol stack. The uldest field has to be filled out in any case. Otherwise, the netx operating system cannot route the packet. This field is mandatory.

26 Dual-Port Memory 26/390 Source Queue Handle The ulsrc field identifies the sender of the packet. In the context of the netx firmware (inter-task communication) this field holds the identifier of the sending task. Usually, a driver uses this field for its own handle, but it can hold any handle of the sending process. Using this field is mandatory. The receiving task does not evaluate this field and passes it back unchanged to the originator of the packet. Destination Identifier The uldestid field identifies the destination of an unsolicited packet from the netx firmware to the host system. It can hold any handle that helps to identify the receiver. Therefore, its use is mandatory for unsolicited packets. The receiver of unsolicited packets has to register for this. Source Identifier The ulsrcid field identifies the originator of a packet. This field is used by a host application, which passes a packet from an external process to an internal netx task. The ulsrcid field holds the handle of the external process. When netx operating system returns the packet, the application can identify the packet and returns it to the originating process. The receiving task on the netx does not evaluate this field and passes it back unchanged. For inter-task communication, this field is not used. Length of Data Field The ullen field holds the size of the data field in bytes. It defines the total size of the packet s payload that follows the packet s header. The size of the header is not included in ullen. So the total size of a packet is the size from ullen plus the size of packet s header. Depending on the command, a data field may or may not be present in a packet. If no data field is included, the length field is set to zero. Identifier The ulid field is used to identify a specific packet among others of the same kind. That way the application or driver can match a specific reply or confirmation packet to a previous request packet. The receiving task does not change this field and passes it back to the originator of the packet. Its use is optional in most of the cases. However, it is mandatory for sequenced packets. Example: Downloading big amounts of data that does not fit into a single packet. For a sequence of packets the identifier field is incremented by one for every new packet. Status / Error Code The ulsta field is used in response or confirmation packets. It informs the originator of the packet about success or failure of the execution of the command. The field may be also used to hold status information in a request packet.

27 Dual-Port Memory 27/390 Command / Response The ulcmd field holds the command code or the response code, respectively. The command/response is specific to the receiving task. If a task is not able to execute certain commands, it will return the packet with an error indication. A command is always even (the least significant bit is zero). In the response packet, the command code is incremented by one indicating a confirmation to the request packet. Extension Flags The extension field ulext is used for controlling packets that are sent in a sequenced manner. The extension field indicates the first, last or a packet of a sequence. If sequencing is not required, the extension field is not used and set to zero. Routing Information The ulrout field is used internally by the netx firmware only. It has no meaning to a driver type application and therefore set to zero. User Data Field This field contains data related to the command specified in ulcmd field. Depending on the command, a packet may or may not have a data field. The length of the data field is given in the ullen field.

28 Dual-Port Memory 28/ Status & Error Codes The following status and error codes can be returned in ulsta: Status and Error Codes Code (Symbolic Constant) Numerical Value Meaning RCX_S_OK 0x0000 SUCCESS, STATUS OKAY RCX_E_UNKNOWN_COMMAND 0xC UNKNOWN COMMAND RCX_E_UNKNOWN_DESTINATION 0xC UNKNOWN DESTINATION RCX_E_UNKNOWN_DESTINATION_ID 0xC UNKNOWN DESTINATION ID RCX_E_INVALID_LENGTH 0xC INVALID LENGTH RCX_E_INVALID_EXTENSION 0xC INVALID EXTENSION RCX_E_QUE_UNKNOWN 0xC02B0001 UNKNOWN QUEUE RCX_E_QUE_INDEX_UNKNOWN 0xC02B0002 UNKNOWN QUEUE INDEX RCX_E_TASK_UNKNOWN 0xC02B0003 UNKNOWN TASK RCX_E_TASK_INDEX_UNKNOWN 0xC02B0004 UNKNOWN TASK INDEX RCX_E_TASK_HANDLE_INVALID 0xC02B0005 INVALID TASK HANDLE RCX_E_TASK_INFO_IDX_UNKNOWN 0xC02B0006 UNKNOWN INDEX RCX_E_FILE_XFR_TYPE_INVALID 0xC02B0007 INVALID TRANSFER TYPE RCX_E_FILE_REQUEST_INCORRECT 0xC02B0008 INVALID FILE REQUEST Table 12: Status and Error Codes Differences between System and Channel Mailboxes The mailbox system on netx provides a non-cyclic data transfer channel for field bus and industrial Ethernet protocols. Another use of the mailbox is allowing access to the firmware running on the netx chip itself for diagnostic purposes. There is always a send and a receive mailbox. Send and receive mailboxes utilize handshake bits to synchronize these data or diagnostic packages through the mailbox. There is a pair of handshake bits for both the send and receive mailbox. The netx operating system rcx only uses the system mailbox. The system mailbox, however, has a mechanism to route packets to a communication channel. A channel mailbox passes packets to its own protocol stack only.

29 Dual-Port Memory 29/ Send Mailbox The send mailbox area is used by protocols utilizing a non-cyclic data exchange mechanism. Another use of the mailbox system is to provide access to the firmware running on the netx chip itself. The send mailbox is used to transfer non-cyclic data to the network or to the protocol stack. The size is 1596 bytes for the send mailbox in the default memory layout. The mailbox is accompanied by counters that hold the number of packages that can be accepted Receive Mailbox The receive mailbox area is used by protocols utilizing a non-cyclic data exchange mechanism. Another use of the mailbox system is to provide access to the firmware running on the netx chip itself. The receive mailbox is used to transfer non-cyclic data from the network or from the protocol stack. The size is 1596 bytes for the receive mailbox in the default memory layout. The mailbox is accompanied by counters that hold the number of waiting packages (for the receive mailbox) Channel Mailboxes (Details of Send and Receive Mailboxes) Master Status Offset Type Name Description 0x0200 UINT16 uspackagesaccepted Packages Accepted Number of Packages that can be Accepted 0x0202 UINT16 usreserved Reserved Set to 0 0x0204 UINT8 absendmbx[ 1596 ] Send Mailbox Non Cyclic Data To The Network or to the Protocol Stack 0x0840 UINT16 uswaitingpackages Packages waiting Counter of packages that are waiting to be processed 0x0842 UINT16 usreserved Reserved Set to 0 0x0844 UINT8 abrecvmbx[ 1596 ] Receive Mailbox Non Cyclic Data from the network or from the protocol stack Table 13: Channel Mailboxes.

30 Dual-Port Memory 30/390 Channel Mailboxes Structure typedef struct tagnetx_send_mailbox_block UINT16 uspackagesaccepted; UINT16 usreserved; UINT8 absendmbx[ 1596 ]; } NETX_SEND_MAILBOX_BLOCK; typedef struct tagnetx_recv_mailbox_block UINT16 uswaitingpackages; UINT16 usreserved; UINT8 abrecvmbx[ 1596 ]; } NETX_RECV_MAILBOX_BLOCK; 3.3 Status A status block is present within the communication channel. It contains information about network and task related issues. In some respects, status and control block are used together in order to exchange information between host application and netx firmware. The application reads a status block whereas the control block is written by the application. Both status and control block have registers that use the Change of State mechanism (see also section of the netx Dual-Port- Memory manual) Common Status The Common Status Block contains information that is the same for all communication channels. The start offset of this block depends on the size and location of the preceding blocks. The status block is always present in the dual-port memory All Implementations The structure outlined below is common to all protocol stacks.

31 Dual-Port Memory 31/390 Common Status Structure Definition Common Status Offset Type Name Description 0x0010 UINT32 ulcommunicationcos Communication Change of State READY, RUN, RESET REQUIRED, NEW, CONFIG AVAILABLE, CONFIG LOCKED 0x0014 UINT32 ulcommunicationstate Communication State 0x0018 UINT32 ulcommunicationerror Communication Error 0x001C UINT16 usversion Version 0x001E UINT16 uswatchdogtime Watchdog Timeout NOT CONFIGURED, STOP, IDLE, OPERATE Unique Error Number According to Protocol Stack Version Number of this Diagnosis Structure Configured Watchdog Time 0x0020 UINT16 ushandshakemode Handshake Mode Process Data Transfer Mode (see netx DPM Interface Manual) 0x0022 UINT16 usreserved Reserved Set to 0 0x0024 UINT32 ulhostwatchdog Host Watchdog Joint Supervision Mechanism Protocol Stack Writes, Host System Reads 0x0028 UINT32 ulerrorcount Error Count Total Number of Detected Error Since Power- Up or Reset 0x002C UINT32 ulerrorloglnd Error Log Indicator Total Number Of Entries In The Error Log Structure (not supported yet) 0x0030 UINT32 ulreserved[2] Reserved Set to 0 Table 14: Common Status Structure Definition

32 Dual-Port Memory 32/390 Common Status Block Structure Reference typedef struct NETX_COMMON_STATUS_BLOCK_Ttag UINT32 ulcommunicationcos; UINT32 ulcommunicationstate; UINT32 ulcommunicationerror; UINT16 usversion; UINT16 uswatchdogtime; UINT16 ausreserved[2]; UINT32 ulhostwatchdog; UINT32 ulerrorcount; UINT32 ulerrorlogind; UINT32 ulreserved[2]; union NETX_MASTER_STATUS_T tmasterstatus; /* for master implementation */ UINT32 aulreserved[6]; /* otherwise reserved */ } unstackdepended; } NETX_COMMON_STATUS_BLOCK_T; Common Status Block Structure Reference typedef struct NETX_COMMON_STATUS_BLOCK_Ttag UINT32 ulcommunicationcos; UINT32 ulcommunicationstate; UINT32 ulcommunicationerror; UINT16 usversion; UINT16 uswatchdogtime; UINT16 ausreserved[2]; UINT32 ulhostwatchdog; UINT32 ulerrorcount; UINT32 ulerrorlogind; UINT32 ulreserved[2]; union NETX_MASTER_STATUS_T tmasterstatus; /* for master implementation */ UINT32 aulreserved[6]; /* otherwise reserved */ } unstackdepended; } NETX_COMMON_STATUS_BLOCK_T;

33 Dual-Port Memory 33/390 Communication Change of State (All Implementations) The communication change of state register contains information about the current operating status of the communication channel and its firmware. Every time the status changes, the netx protocol stack toggles the netx Change of State Command flag in the netx communication flags register (see section of the netx DPM Interface Manual). The application then has to toggle the netx Change of State Acknowledge flag back acknowledging the new state (see section of the netx DPM Interface Manual). ulcommunicationcos - netx writes, Host reads Bit Short name Name D31..D7 unused, set to zero D6 Restart Required Enable RCX_COMM_COS_RESTART_REQUIRED_ENABLE D5 Restart Required RCX_COMM_COS_RESTART_REQUIRED D4 Configuration New RCX_COMM_COS_CONFIG_NEW D3 Configuration Locked RCX_COMM_COS_CONFIG_LOCKED D2 Bus On RCX_COMM_COS_BUS_ON D1 Running RCX_COMM_COS_RUN D0 Ready RCX_COMM_COS_READY Table 15: Communication State of Change

34 Dual-Port Memory 34/390 Communication Change of State Flags (netx System Application) Bit Definition / Description 0 Ready (RCX_COMM_COS_READY) The Ready flag is set as soon as the protocol stack is started properly. Then the protocol stack is awaiting a configuration. As soon as the protocol stack is configured properly, the Running flag is set, too. 1 Running (RCX_COMM_COS_RUN) 0-1 -The Running flag is set when the protocol stack has been configured properly. Then the protocol stack is awaiting a network connection. Now both the Ready flag and the Running flag are set. 2 Bus On (RCX_COMM_COS_BUS_ON) 0-1 -The Bus On flag is set to indicate to the host system whether or not the protocol stack has the permission to open network connections. If set, the protocol stack has the permission to communicate on the network; if cleared, the permission was denied and the protocol stack will not open network connections. 3 Configuration Locked (RCX_COMM_COS_CONFIG_LOCKED) 0-1 -The Configuration Locked flag is set, if the communication channel firmware has locked the configuration database against being overwritten. Re-initializing the channel is not allowed in this state. To unlock the database, the application has to clear the Lock Configuration flag in the control block (see page 41). 4 Configuration New (RCX_COMM_COS_CONFIG_NEW) 0-1 -The Configuration New flag is set by the protocol stack to indicate that a new configuration became available, which has not been activated. This flag may be set together with the Restart Required flag. 5 Restart Required (RCX_COMM_COS_RESTART_REQUIRED) 0-1 -The Restart Required flag is set when the channel firmware requests to be restarted. This flag is used together with the Restart Required Enable flag below. Restarting the channel firmware may become necessary, if a new configuration was downloaded from the host application or if a configuration upload via the network took place. 6 Restart Required Enable (RCX_COMM_COS_RESTART_REQUIRED_ENABLE) The Restart Required Enable flag is used together with the Restart Required flag above. If set, this flag enables the execution of the Restart Required command in the netx firmware (for details on the Enable mechanism see section of the netx DPM Interface Manual)) Reserved, set to 0 Table 16: Meaning of Communication Change of State Flags

35 Dual-Port Memory 35/390 Communication State (All Implementations) The communication state field contains information regarding the current network status of the communication channel. Depending on the implementation, all or a subset of the definitions below is supported. UNKNOWN #define RCX_COMM_STATE_UNKNOWN 0x NOT_CONFIGURED #define RCX_COMM_STATE_NOT_CONFIGURED 0x STOP #define RCX_COMM_STATE_STOP 0x IDLE #define RCX_COMM_STATE_IDLE 0x OPERATE #define RCX_COMM_STATE_OPERATE 0x Communication Channel Error (All Implementations) This field holds the current error code of the communication channel. If the cause of error is resolved, the communication error field is set to zero (= RCX_SYS_SUCCESS) again. Not all of the error codes are supported in every implementation. Protocol stacks may use a subset of the error codes below. SUCCESS #define RCX_SYS_SUCCESS 0x Runtime Failures WATCHDOG TIMEOUT #define RCX_E_WATCHDOG_TIMEOUT 0xC000000C Initialization Failures (General) INITIALIZATION FAULT #define RCX_E_INIT_FAULT 0xC DATABASE ACCESS FAILED #define RCX_E_DATABASE_ACCESS_FAILED 0xC Configuration Failures NOT CONFIGURED #define RCX_E_NOT_CONFIGURED 0xC (General) CONFIGURATION FAULT #define RCX_E_CONFIGURATION_FAULT 0xC INCONSISTENT DATA SET #define RCX_E_INCONSISTENT_DATA_SET 0xC DATA SET MISMATCH #define RCX_E_DATA_SET_MISMATCH 0xC INSUFFICIENT LICENSE #define RCX_E_INSUFFICIENT_LICENSE 0xC PARAMETER ERROR #define RCX_E_PARAMETER_ERROR 0xC INVALID NETWORK ADDRESS #define RCX_E_INVALID_NETWORK_ADDRESS 0xC NO SECURITY MEMORY #define RCX_E_NO_SECURITY_MEMORY 0xC

36 Dual-Port Memory 36/390 Network Failures (General) NETWORK FAULT #define RCX_COMM_NETWORK_FAULT 0xC CONNECTION CLOSED #define RCX_COMM_CONNECTION_CLOSED 0xC CONNECTION TIMED OUT #define RCX_COMM_CONNECTION_TIMEOUT 0xC LONELY NETWORK #define RCX_COMM_LONELY_NETWORK 0xC DUPLICATE NODE #define RCX_COMM_DUPLICATE_NODE 0xC CABLE DISCONNECT #define RCX_COMM_CABLE_DISCONNECT 0xC Version (All Implementations) The version field holds version of this structure. It starts with one; zero is not defined. STRUCTURE VERSION #define RCX_STATUS_BLOCK_VERSION 0x0001 Watchdog Timeout (All Implementations) This field holds the configured watchdog timeout value in milliseconds. The application may set its watchdog trigger interval accordingly. If the application fails to copy the value from the host watchdog location to the device watchdog location, the protocol stack will interrupt all network connections immediately regardless of their current state. For details, see section 4.13 of the netx DPM Interface Manual. Host Watchdog (All Implementations) The protocol stack supervises the host system using the watchdog function. If the application fails to copy the value from the device watchdog location (section of the netx DPM Interface Manual) to the host watchdog location (section of the netx DPM Interface Manual), the protocol stack assumes that the host system has some sort of problem and shuts down all network connections. For details on the watchdog function, refer to section 4.13 of the netx DPM Interface Manual. Error Count (All Implementations) This field holds the total number of errors detected since power-up, respectively after reset. The protocol stack counts all sorts of errors in this field no matter if they were network related or caused internally. Error Log Indicator (All Implementations) Not supported yet: The error log indicator field holds the number of entries in the internal error log. If all entries are read from the log, the field is set to zero.

37 Dual-Port Memory 37/ Master Implementation In addition to the common status block as outlined in the previous section, a master firmware maintains the following structure. Master Status Structure Definition typedef struct tagnetx_master_status UINT32 ulslavestate; UINT32 ulslaveerrlogind; UINT32 ulnumofconfigslaves; UINT32 ulnumofactiveslaves; UINT32 ulnumofdiagslaves; UINT32 ulreserved; } NETX_MASTER_STATUS; Master Status Offset Type Name Description 0x0010 Structure See common structure in table Common Status Block 0x0038 UINT32 ulslavestate Slave State OK, FAILED (At Least One Slave) 0x003C UINT32 ulslaveerrlogind Slave Error Log Indicator Slave Diagnosis Data Available: EMPTY, AVAILABLE 0x0040 UINT32 ulnumofconfigslaves Configured Slaves Number of Configured Slaves On The Network 0x0044 UINT32 ulnumofactiveslaves Active Slaves Number of Slaves Running Without Problems 0x0048 UINT32 ulnumofdiagslaves Faulted Slaves Number of Slaves Reporting Diagnostic Issues 0x004C UINT32 ulreserved Reserved Set to 0 Table 17: Master Status Structure Definition Slave State The slave state field is available for master implementations only. It indicates whether the master is in cyclic data exchange to all configured slaves. In case there is at least one slave missing or if the slave has a diagnostic request pending, the status is set to FAILED. For protocols that support non-cyclic communication only, the slave state is set to OK as soon as a valid configuration is found. Status and Error Codes Code (Symbolic Constant) Numerical Value Meaning RCX_SLAVE_STATE_UNDEFINED 0x0000 UNDEFINED RCX_SLAVE_STATE_OK 0x0001 OK RCX_SLAVE_STATE_FAILED 0x0002 FAILED (at least one slave) Others are reserved Table 18: Status and Error Codes

38 Dual-Port Memory 38/390 Slave Error Log Indicator The error log indicator field holds the number of entries in the internal error log. If all entries are read from the log, the field is set to zero. Note: This function is not yet supported. Number of Configured Slaves The firmware maintains a list of slaves to which the master has to open a connection. This list is derived from the configuration database created by SYCON.net (see 6.1). This field holds the number of configured slaves. Number of Active Slaves The firmware maintains a list of slaves to which the master has successfully opened a connection. Ideally, the number of active slaves is equal to the number of configured slaves. For certain fieldbus systems it could be possible that the slave is shown as activated, but still has a problem in terms of a diagnostic issue. This field holds the number of active slaves. Number of Faulted Slaves If a slave encounters a problem, it can provide an indication of the new situation to the master in certain fieldbus systems. As long as those indications are pending and not serviced, the field holds a value unequal zero. If no more diagnostic information is pending, the field is set to zero Slave Implementation The slave firmware uses only the common structure as outlined in section of the Hilscher netx Dual-Port-Memory Manual.

39 Dual-Port Memory 39/ Extended Status The content of the channel specific extended status block is specific to the implementation. Depending on the protocol, a status area may or may not be present in the dual-port memory. It is always available in the default memory map (see section of netx Dual-Port Memory Manual). Note: Have in mind, that all offsets mentioned in this section are relative to the beginning of the common status block, as the start offset of this block depends on the size and location of the preceding blocks. Extended Status Block Offset Type Name Description 0x50 UINT8 abextendedstatus[432] Extended Status Area Protocol Stack Specific Status Area Table 19: Extended Status Block Extended Status Block Structure typedef struct NETX_EXTENDED_STATUS_BLOCK_Ttag UINT8 abextendedstatus[432]; } NETX_EXTENDED_STATUS_BLOCK_T For the sercos Master protocol implementation, the extended status area is structured as follows: typedef struct SIII_MA_AP_EXTENDED_STATUS_DATA_Ttag TLR_UINT32 ulcompletecyclescount; TLR_UINT32 ulcycleswithlostframescount; TLR_UINT32 ulmarker0; TLR_UINT32 ulvalidsynchinputdataexchangescount; TLR_UINT32 ulcompletedsynchinputdataexchangescount; TLR_UINT32 ulblockedsynchinputdataexchangescount; TLR_UINT32 ulvalidsynchoutputdataexchangescount; TLR_UINT32 ulcompletedsynchoutputdataexchangescount; TLR_UINT32 ulblockedsynchoutputdataexchangescount; TLR_UINT32 ulmarker1; TLR_UINT32 ulbufferedbusinputdataexchangescount; TLR_UINT32 ulbufferedbusoutputdataexchangescount; TLR_UINT32 ulcompletedbusinputdataexchangescount; TLR_UINT32 ulmarker2; TLR_UINT32 ulvalidbuffereddpminputdataexchangescount; TLR_UINT32 ulblockedbuffereddpminputdataexchangescount; TLR_UINT32 ulvalidbuffereddpmoutputdataexchangescount; TLR_UINT32 ulblockedbuffereddpmoutputdataexchangescount; } SIII_MA_AP_EXTENDED_STATUS_DATA_T;

40 Dual-Port Memory 40/390 The meaning of these parameters is: Extended Status Block (SIII_MA_AP_EXTENDED_STATUS_DATA_T) Offset Type Name / Description 0x50 UINT32 ulcompletecyclescount Counter for complete communication cycles 0x54 UINT32 ulcycleswithlostframescount Counter for communication cycles with lost frames 0x58 UINT32 ulmarker0 Marker 0 0x5C UINT32 ulvalidsynchinputdataexchangescount Counter for valid synchronous input data exchanges 0x60 UINT32 ulcompletedsynchinputdataexchangescount Counter for completed synchronous input data exchanges 0x64 UINT32 ulblockedsynchinputdataexchangescount Counter for blocked synchronous input data exchanges 0x68 UINT32 ulvalidsynchoutputdataexchangescount Counter for valid synchronous output data exchanges 0x6C UINT32 ulcompletedsynchoutputdataexchangescount Counter for completed synchronous output data exchanges 0x70 UINT32 ulblockedsynchoutputdataexchangescount Counter for blocked synchronous output data exchanges 0x74 UINT32 ulmarker1 Marker 1 0x78 UINT32 ulbufferedbusinputdataexchangescount Counter for buffered bus synchronous input data exchanges 0x7C UINT32 ulbufferedbusoutputdataexchangescount Counter for buffered bus synchronous output data exchanges 0x80 UINT32 ulcompletedbusinputdataexchangescount Counter for completed bus synchronous input data exchanges 0x84 UINT32 ulmarker2 Marker 2 0x88 UINT32 ulvalidbuffereddpminputdataexchangescount Counter for valid buffered DPM input data exchanges 0x8C UINT32 ulblockedbuffereddpminputdataexchangescount Counter for blocked buffered bus DPM input data exchanges 0x90 UINT32 ulvalidbuffereddpmoutputdataexchangescount Counter for valid buffered DPM input data exchanges 0x94 UINT32 ulblockedbuffereddpmoutputdataexchangescount Counter for blocked buffered bus DPM input data exchanges Table 20: Extended Status Block (for sercos Master Protocol Stack)

41 Dual-Port Memory 41/ Control Block A control block is always present within the communication channel. In some respects, control and status block are used together in order to exchange information between host application and netx firmware. The control block is written by the application, whereas the application reads a status block. Both control and status block have registers that use the Change of State mechanism (see also section of the netx Dual-Port-Memory manual.) The following gives an example of the use of control and status block. The host application wishes to lock the configuration settings of a communication channel to protect them against changes. The application sets the Lock Configuration flag in the control block to the communication channel firmware. As a result, the channel firmware sets the Configuration Locked flag in the status block (see below), indicating that the current configuration settings cannot be deleted, altered, overwritten or otherwise changed. The control block of a dual-port memory features a watchdog function to allow the operating system running on the netx supervise the host application and vice versa. The control area is always present in the dual-port memory. Control Block Offset Type Name Description 0x0008 UINT32 ulapplicationcos Application Change Of State State Of The Application Program INITIALIZATION, LOCK CONFIGURATION 0x000C UINT32 uldevicewatchdog Device Watchdog Host System Writes, Protocol Stack Reads Table 21: Communication Control Block Communication Control Block Structure typedef struct tagnetx_control_block UINT32 ulapplicationcos; UINT32 uldevicewatchdog; } NETX_CONTROL_BLOCK; For more information concerning the Control Block please refer to the netx DPM Interface Manual.

42 Getting started / Configuration 42/390 4 Getting started / Configuration This section explains some essential information you should know when starting to work with the sercos Master Protocol API. 4.1 Overview about Essential Functionality You can find the most commonly used functionality of the sercos Master Protocol API within the following sections of this document: Topic Section Section Name Number Set configuration DPM Configuration Cyclic data transfer (Input/Output) 5.10 Process Data Acyclic data transfer Read IDN Data Block Element Service (Macro) (Records) Write IDN Data Block Element Service (Macro) Table 22: Overview about Essential Functionality (Cyclic and acyclic Data Transfer) 4.2 Configuration of sercos Master The master can be configured by using different means. This includes the following methods: Configuration via SYCON.net Timing parameters are specified by the user Configuration via packets Automatic configuration of frame layout with automatic timing calculation (since V2.1.X) Automatic configuration of frame layout with user specified timing parameters (since V2.1.X) Manual configuration of frame layout and timing parameters The configuration via SYCON.net evaluates the SDDML files provided for the slaves to be used and is therefore the easiest method. All configuration variants via packets provide full control of the process image layout. This includes the following: Placement of connection controls Placement of connection data Connection data of a single connection is always placed consecutively in the process image

43 Getting started / Configuration 43/ Using the configuration tool SYCON.net The easiest way to configure the sercos Master is using Hilscher s configuration tool SYCON.net. First, you need to create a project in SYCON.net. This is described in detail in the SYCON.net documentation. Configure the bus and master parameters as described in the SYCON.net documentation. After you completed your project, you can right-click on the icon of the sercos Master and select "Connect". You will see that the name of the sercos Master will get a green background. Now right-click on the icon again and select "Download". This will download the configuration files into the firmware. It is stored in a RAM Disk in a channel dependent directory ("PORT_0" for channel 0, "PORT_1 for channel 1, etc.). After the download is finished, the driver requests the sercos Master firmware to perform a Channel-Init. All current connections will be shut down by the firmware and a restart will be performed. During this restart, the configuration that has been downloaded previously will be evaluated and used.

44 Getting started / Configuration 44/ Using configuration via packets The following sections will outline the different variants for configuring the master via packets. All variants provide full control of the process image layout. In addition, some variants provide additional control of frame layout and timing parameters. If the slaves require writes to particular IDNs, these must be explicitly specified via Add InitCmd Service Note: The master must be in communication phase NRT to accept configuration via packets. The following packet configuration variants are possible: Automatic configuration of frame layout with automatic timing calculation (since V2.1.X) Automatic configuration of frame layout with user specified timing parameters (since V2.1.X) Manual configuration of frame layout and timing parameters Automatic configuration of frame layout with automatic timing calculation This configuration method is selected within the field ulstackconfigurationflags of Begin a new Configuration Transfer Service by setting the bits 2 and 5. For details, see chapter Automatic Configuration of Frame Layout with automatic Timing Calculation The automatic timing calculation has four different selectable timing options (depending on bits 4 and bits 3 of ulstackconfigurationflags): No NRT during CP3/CP4 MDT/AT/NRT MDT/NRT/AT; minimum sized NRT channel and AT placed close to its end MDT/NRT/AT; maximum sized NRT channel and AT placed close to end of cycle The maximum possible MTU is determined internally by master. The timing variants are described in chapter Configurable Timing Variants in more detail. The following parameters of Begin a new Configuration Transfer Service are evaluated: Communication cycle time Communication timeout (Allowed MST losses) Output Process Data image size Input Process Data image size Minimum CP0 Wait Cycles For detailed description of the parameters, see Detailed Description of Master Parameters. For detailed explanation of how to use the configuration method, see Automatic Configuration of Frame Layout with automatic Timing Calculation.

45 Getting started / Configuration 45/ Automatic configuration of frame layout with user specified timing parameters This configuration method is selected within the field ulstackconfigurationflags of Begin a new Configuration Transfer Service by setting the bit 2 and keeping bit 5 cleared. For details, see chapter 0 Automatic Configuration of Frame Layout with user specified Timing Parameters. All timing parameters have to be determined by the user. The frame layout is calculated by the master internally. Note: The timing parameters must be suitable for the frame layout calculated by the master i.e. the frames must fit into the specified timing. The following parameters of Begin a new Configuration Transfer Service are evaluated: Communication cycle time Communication timeout (Allowed MST losses) Command value valid time (t 3 ) AT Transmission Starting Time (t 1 ) NRT transmission start time (t 6 ) NRT transmission end time (t 7 ) Synchronization time NRT channel MTU Output Process Data image size Input Process Data image size Minimum CP0 Wait Cycles For detailed description of the parameters, see Detailed Description of Master Parameters. For detailed explanation of how to use the configuration method, see Automatic Configuration of Frame Layout with user specified Timing Parameters Automatic Configuration of Frame Layout with user specified Timing Parameters.

46 Getting started / Configuration 46/ Manual configuration of frame layout and timing parameters This configuration method is selected within the field ulstackconfigurationflags of Begin a new Configuration Transfer Service by keeping the bits 2 and 5 cleared. For details, see chapter Manual Configuration of Frame Layout and Timing Parameters. All timing parameters have to be determined by the user. The frame layout is specified via configuration packets. The timing parameters must be suitable for the frame layout specified by the packets i.e. the frames must fit into the specified timing. The following parameters of Begin a new Configuration Transfer Service are evaluated: Communication cycle time Communication timeout (Allowed MST losses) Command value valid time (t 3 ) AT Transmission Starting Time (t 1 ) NRT transmission start time (t 6 ) NRT transmission end time (t 7 ) Synchronization time NRT channel MTU Output Process Data image size Input Process Data image size Minimum CP0 Wait Cycles For detailed description of the parameters, see Detailed Description of Master Parameters. For detailed explanation of how to use the configuration method, see Manual Configuration of Frame Layout and Timing Parameters.

47 Getting started / Configuration 47/ Detailed Description of Master Parameters Both the bus and the master need to be configured. The accurate choice of the bus parameters is the foundation of correctly operating data exchange on the sercos Master network. The following table contains relevant information about the bus parameters (including the master s parameters) for the sercos Master firmware such as a short explanation of the meaning of the parameter and ranges of allowed values: Parameter Meaning Range of Value / Value Communication Cycle Time (t Scyc ) Communication Cycle Time Do not use values of t Scyc lower than (250 µs). Minimum Value (31,250 µs) Maximum Value (65000,000 µs) Communication Timeout Communication Timeout Allowed number of successive MDT errors (relevant for CP3/4) range depends on slave Command value valid time (t 3 ) AT Transmission Starting Time (t 1 ) Command value valid time (t 3 ) Time how long a specific command value remains valid. AT Transmission Starting Time (t 1 ) Starting Time of AT0-3 Transmission Minimum Value 0 Maximum Value tscyc Minimum Value 0 Maximum Value tscyc NRT transmission start time (t 6 ) NRT transmission time (Start) Minimum Value 0 Maximum Value tscyc NRT transmission end time (t 7 ) NRT transmission time (End) Minimum Value 0 Maximum Value tscyc Synchronization time Synchronization time Minimum Value 0 Maximum Value tpcyc Sync Jitter Sync Jitter Allowed degree of deviation in the precision of timing signals Minimum Value n/a Maximum Value t Scyc / 2 NRT channel MTU NRT channel Requested MTU depends on Communication Phase Minimum Value: 46 Maximum Value: 1500 Process Data Output Size (MDT) Process Data Output Size (configurable, avoid odd values) Minimum Value 0 Maximum Value 5760 Process Data Input Size (AT) Process Data Input Size (configurable, avoid odd values) Minimum Value 0 Maximum Value 5760 Minimum CP0 Wait Cycles Minimum CP0 Wait Cycles Minimum number of cycles to wait for in CP0 to detect all slaves Minimum Value 100 Table 23: Bus and Master Parameters, their Meanings and their Ranges of allowed Values

48 Getting started / Configuration 48/ Communication Cycle Time (t Scyc ) The communication cycle time specifies the actual bus cycle used in CP3 and CP4. The value is written to the IDN S on all slaves by the master. The specification of communication cycle time (t Scyc ) defines 31,25 µs, 62,5 µs, 125 µs, 250 µs, 500 µs, 750 µs, 1 ms, 1,25 ms... up to 65 ms in steps of 250 µs. Note: Due to processing required within the master, the minimum value of t Scyc is 250 µs Communication Timeout This parameter specifies the allowed MST losses a slave has to accept in CP3/CP4. Any higher amount of successive MDT losses is considered an error by slaves and result into a fallback. The value is written into the IDN S on all slaves by the master. This value should be higher than any allowed data losses specified on the connections to ensure that the master can still communicate with the slaves Command Value Valid Time This parameter describes the command value valid time. In the sercos specification this value is often denominated as t 3. This item corresponds to IDN S AT Transmission Starting Time (t 1 ) The AT Transmission starting time specifies when the AT0 telegram is sent on the bus after the MST. The value is written into the IDN S by the master on all slaves supporting SCP_Sync NRT Transmission Time (t 6, t 7 ) The NRT Transmission Time parameters specify the start and the end time of the NRT window. They are written into the IDN S on all slaves by the master. The minimum NRT window has to be 6.72 µs. If t 6 is 0, the NRT channel is completely switched off. If the difference between t 7 and t 6 is less than 125 µs, then the NRT channel MTU must be adjusted very precisely, see section Sync Jitter below Feedback acquisition time (Synchronization time) (t 4 ) The feedback acquisition time specifies when the feedbacks should be taken by the slaves supporting SCP_Sync. The reference time point for t 4 is t Sref which is determined by synchronization measurement. t Sref is reached by all slaves at the same time. Slaves supporting SCP_Sync will optionally produce the CON-CLK at the specified time point. The parameter is written to IDN S on all slaves supporting SCP_Sync.

49 Getting started / Configuration 49/ Sync Jitter The master calculates the maximum synchronization jitter. This information is used by the slave for the calculation of its MST window. The parameter is stored in IDN S NRT channel Requested MTU The parameter defines the largest frame that can be sent through the NRT frame. The parameter is written to IDN S on all slaves supporting SCP_NRT Process Data Output Size (MDT) This parameter determines the size of the area to be used for Process Data Output. It may not exceed the size of available space in DPM which is 5760 bytes. The parameter should be dividable by 2 without remainder Process Data Input Size (AT) This parameter determines the size of the area to be used for Process Data Input. It may not exceed the size of available space in DPM which is 5760 bytes. The parameter should be dividable by 2 without remainder Minimum CP0 Wait Cycles The master will check for the specified amount of consecutively received identical CP0 frames to consider the detection stable. If a change occurs, the master will reset its internal counter.

50 Overview 50/390 5 Overview This chapter explains the task structure of the sercos Master Protocol stack, the various communication phases defined in the sercos standard and their transitions and the meaning of the device status, device control and connection control words. 5.1 Task Structure of the sercos Master Stack General Structure of the sercos Stack The illustration below displays the internal structure of the tasks which together represent the sercos Master Stack: Figure 6: Internal Structure of sercos Master Firmware For the explanation of the different kinds of arrows see lower left corner of figure. The dual-port memory is used for exchange of information, data and packets. Configuration and IO data will be transferred using this way. The user application only accesses the task located in the highest layer namely the AP task which constitutes the application interface of the sercos Master stack. If the NRT functionality is used the user application also accesses the Ethernet Interface Task.

51 Overview 51/390 The sercos Master protocol stack consists of the following tasks: 1. sercos-ap-task (Application) 2. sercos-master CP-Task (Communication) 3. sercos-master NRT-Task (Non Realtime data/ip-channel) together with the Ethernet Interface Task and the EDD-Task 4. sercos-master SVC-Task (Service channel) Together these tasks represent the core of the sercos Master stack. They provide the following functionality: sercos-master AP-Task This task is actually present in all stack implementations for netx controller and has in all variants basically the same functionality. This task handles the interface to DPM, analyses received configuration data and sends request to bus-specific tasks e.g. CP-Task sercos-master CP-Task The CP-Task is responsible for the following: Communication Phase Switching Topology Control Configuration sercos-master NRT-Task The NRT-Task is responsible for the following: Collision Buffer Handling Drv_Edd interfacing Ethernet Bridging sercos-master SVC-Task The SVC-Task is responsible for the following: SVC state machines per slave Triple Buffer Mechanism (LFW only) The triple buffer mechanism provides a consistent synchronous access procedure from both sides (DPM and AP task). The triple buffer technique ensures that the access will always affect the last written cell. In bus synchronous operation, the triple buffer is bypassed and a shorter process data path is used. Consistency is guaranteed by DPM handshakes.

52 Overview 52/ State Machine (Communication Phases) This section explains the general states in which the master can be. It discusses some of the most important aspects of the various communication phases and their transitions. It also explains the structure of the sent data telegrams depending on the communication phase State Transitions The following illustration explains the possible transitions between the states of the sercos master: Figure 7: Permitted Communication Phase Transitions When switching between two states, the sercos master is temporarily in an intermediate state CPS (Communication phase switching).