1

/******************************************************************************

     2

 *

     3

 *  $Id$

     4

 *

     5

 *  Copyright (C) 2006-2008  Florian Pose, Ingenieurgemeinschaft IgH

     6

 *

     7

 *  This file is part of the IgH EtherCAT master userspace library.

     8

 *

     9

 *  The IgH EtherCAT master userspace library is free software; you can

    10

 *  redistribute it and/or modify it under the terms of the GNU Lesser General

    11

 *  Public License as published by the Free Software Foundation; version 2.1

    12

 *  of the License.

    13

 *

    14

 *  The IgH EtherCAT master userspace library is distributed in the hope that

    15

 *  it will be useful, but WITHOUT ANY WARRANTY; without even the implied

    16

 *  warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

    17

 *  GNU Lesser General Public License for more details.

    18

 *

    19

 *  You should have received a copy of the GNU Lesser General Public License

    20

 *  along with the IgH EtherCAT master userspace library. If not, see

    21

 *  <http://www.gnu.org/licenses/>.

    22

 *

    23

 *  ---

    24

 *

    25

 *  The license mentioned above concerns the source code only. Using the

    26

 *  EtherCAT technology and brand is only permitted in compliance with the

    27

 *  industrial property and similar rights of Beckhoff Automation GmbH.

    28

 *

    29

 *****************************************************************************/

    30

    31

/** \file

    32

 *

    33

 * EtherCAT master application interface.

    34

 *

    35

 * \defgroup ApplicationInterface EtherCAT Application Interface

    36

 *

    37

 * EtherCAT interface for realtime applications. This interface is designed

    38

 * for realtime modules that want to use EtherCAT. There are functions to

    39

 * request a master, to map process data, to communicate with slaves via CoE

    40

 * and to configure and activate the bus.

    41

 * 

    42

 * Changed since 1.5:

    43

 *

    44

 * - Added redundancy_active flag to ec_domain_state_t.

    45

 * - Added ecrt_master_link_state() method and ec_master_link_state_t to query

    46

 *   the state of a redundant link.

    47

 * - Added the EC_HAVE_REDUNDANCY define, to check, if the interface contains

    48

 *   redundancy features.

    49

 *

    50

 * Changes in version 1.5:

    51

 *

    52

 * - Added the distributed clocks feature and the respective method

    53

 *   ecrt_slave_config_dc() to configure a slave for cyclic operation, and

    54

 *   ecrt_master_application_time(), ecrt_master_sync_reference_clock() and

    55

 *   ecrt_master_sync_slave_clocks() for offset and drift compensation. The

    56

 *   EC_TIMEVAL2NANO() macro can be used for epoch time conversion, while the

    57

 *   ecrt_master_sync_monitor_queue() and ecrt_master_sync_monitor_process()

    58

 *   methods can be used to monitor the synchrony.

    59

 * - Improved the callback mechanism. ecrt_master_callbacks() now takes two

    60

 *   callback functions for sending and receiving datagrams.

    61

 *   ecrt_master_send_ext() is used to execute the sending of non-application

    62

 *   datagrams.

    63

 * - Added watchdog configuration (method ecrt_slave_config_watchdog(),

    64

 *   #ec_watchdog_mode_t, \a watchdog_mode parameter in ec_sync_info_t and

    65

 *   ecrt_slave_config_sync_manager()).

    66

 * - Added ecrt_slave_config_complete_sdo() method to download an SDO during

    67

 *   configuration via CompleteAccess.

    68

 * - Added ecrt_master_deactivate() to remove the bus configuration.

    69

 * - Added ecrt_open_master() and ecrt_master_reserve() separation for

    70

 *   userspace.

    71

 * - Added bus information interface (methods ecrt_master(),

    72

 *   ecrt_master_get_slave(), ecrt_master_get_sync_manager(),

    73

 *   ecrt_master_get_pdo() and ecrt_master_get_pdo_entry()) to get information

    74

 *   about the currently connected slaves and the PDO entries provided.

    75

 * - Added ecrt_master_sdo_download(), ecrt_master_sdo_download_complete() and

    76

 *   ecrt_master_sdo_upload() methods to let an application transfer SDOs

    77

 *   before activating the master.

    78

 * - Changed the meaning of the negative return values of

    79

 *   ecrt_slave_config_reg_pdo_entry() and ecrt_slave_config_sdo*().

    80

 * - Implemented the Vendor-specific over EtherCAT mailbox protocol. See

    81

 *   ecrt_slave_config_create_voe_handler().

    82

 * - Renamed ec_sdo_request_state_t to #ec_request_state_t, because it is also

    83

 *   used by VoE handlers.

    84

 * - Removed 'const' from argument of ecrt_sdo_request_state(), because the

    85

 *   userspace library has to modify object internals.

    86

 * - Added 64-bit data access macros.

    87

 * - Added ecrt_slave_config_idn() method for storing SoE IDN configurations,

    88

 *   and ecrt_master_read_idn() and ecrt_master_write_idn() to read/write IDNs

    89

 *   ad-hoc via the user-space library.

    90

 * - Added ecrt_master_reset() to initiate retrying to configure slaves.

    91

 *

    92

 * @{

    93

 */

    94

    95

/*****************************************************************************/

    96

    97

#ifndef __ECRT_H__

    98

#define __ECRT_H__

    99

   100

#ifdef __KERNEL__

   101

#include <asm/byteorder.h>

   102

#include <linux/types.h>

   103

#include <linux/time.h>

   104

#else

   105

#include <stdlib.h> // for size_t

   106

#include <stdint.h>

   107

#include <sys/time.h> // for struct timeval

   108

#endif

   109

   110

/******************************************************************************

   111

 * Global definitions

   112

 *****************************************************************************/

   113

   114

/** EtherCAT realtime interface major version number.

   115

 */

   116

#define ECRT_VER_MAJOR 1

   117

   118

/** EtherCAT realtime interface minor version number.

   119

 */

   120

#define ECRT_VER_MINOR 5

   121

   122

/** EtherCAT realtime interface version word generator.

   123

 */

   124

#define ECRT_VERSION(a, b) (((a) << 8) + (b))

   125

   126

/** EtherCAT realtime interface version word.

   127

 */

   128

#define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR)

   129

   130

/******************************************************************************

   131

 * Feature flags

   132

 *****************************************************************************/

   133

   134

/** Defined, if the redundancy features are available.

   135

 *

   136

 * I. e. if the \a redundancy_active flag in ec_domain_state_t and the

   137

 * ecrt_master_link_state() method are available.

   138

 */

   139

#define EC_HAVE_REDUNDANCY

   140

   141

/*****************************************************************************/

   142

   143

/** End of list marker.

   144

 *

   145

 * This can be used with ecrt_slave_config_pdos().

   146

 */

   147

#define EC_END ~0U

   148

   149

/** Maximum number of sync managers per slave.

   150

 */

   151

#define EC_MAX_SYNC_MANAGERS 16

   152

   153

/** Maximum string length.

   154

 *

   155

 * Used in ec_slave_info_t.

   156

 */

   157

#define EC_MAX_STRING_LENGTH 64

   158

   159

/** Maximum number of slave ports. */

   160

#define EC_MAX_PORTS 4

   161

   162

/** Timeval to nanoseconds conversion.

   163

 *

   164

 * This macro converts a Unix epoch time to EtherCAT DC time.

   165

 *

   166

 * \see void ecrt_master_application_time()

   167

 *

   168

 * \param TV struct timeval containing epoch time.

   169

 */

   170

#define EC_TIMEVAL2NANO(TV) \

   171

    (((TV).tv_sec - 946684800ULL) * 1000000000ULL + (TV).tv_usec * 1000ULL)

   172

   173

/******************************************************************************

   174

 * Data types

   175

 *****************************************************************************/

   176

   177

struct ec_master;

   178

typedef struct ec_master ec_master_t; /**< \see ec_master */

   179

   180

struct ec_slave_config;

   181

typedef struct ec_slave_config ec_slave_config_t; /**< \see ec_slave_config */

   182

   183

struct ec_domain;

   184

typedef struct ec_domain ec_domain_t; /**< \see ec_domain */

   185

   186

struct ec_sdo_request;

   187

typedef struct ec_sdo_request ec_sdo_request_t; /**< \see ec_sdo_request. */

   188

   189

struct ec_voe_handler;

   190

typedef struct ec_voe_handler ec_voe_handler_t; /**< \see ec_voe_handler. */

   191

   192

/*****************************************************************************/

   193

   194

/** Master state.

   195

 *

   196

 * This is used for the output parameter of ecrt_master_state().

   197

 *

   198

 * \see ecrt_master_state().

   199

 */

   200

typedef struct {

   201

    unsigned int slaves_responding; /**< Sum of responding slaves on all

   202

                                      Ethernet devices. */

   203

    unsigned int al_states : 4; /**< Application-layer states of all slaves.

   204

                                  The states are coded in the lower 4 bits.

   205

                                  If a bit is set, it means that at least one

   206

                                  slave in the bus is in the corresponding

   207

                                  state:

   208

                                  - Bit 0: \a INIT

   209

                                  - Bit 1: \a PREOP

   210

                                  - Bit 2: \a SAFEOP

   211

                                  - Bit 3: \a OP */

   212

    unsigned int link_up : 1; /**< \a true, if at least one Ethernet link is

   213

                                up. */

   214

} ec_master_state_t;

   215

   216

/*****************************************************************************/

   217

   218

/** Redundant link state.

   219

 *

   220

 * This is used for the output parameter of ecrt_master_link_state().

   221

 *

   222

 * \see ecrt_master_link_state().

   223

 */

   224

typedef struct {

   225

    unsigned int slaves_responding; /**< Sum of responding slaves on the given

   226

                                      link. */

   227

    unsigned int al_states : 4; /**< Application-layer states of the slaves on

   228

                                  the given link.  The states are coded in the

   229

                                  lower 4 bits.  If a bit is set, it means

   230

                                  that at least one slave in the bus is in the

   231

                                  corresponding state:

   232

                                  - Bit 0: \a INIT

   233

                                  - Bit 1: \a PREOP

   234

                                  - Bit 2: \a SAFEOP

   235

                                  - Bit 3: \a OP */

   236

    unsigned int link_up : 1; /**< \a true, if the given Ethernet link is up.

   237

                               */

   238

} ec_master_link_state_t;

   239

   240

/*****************************************************************************/

   241

   242

/** Slave configuration state.

   243

 *

   244

 * This is used as an output parameter of ecrt_slave_config_state().

   245

 *

   246

 * \see ecrt_slave_config_state().

   247

 */

   248

typedef struct  {

   249

    unsigned int online : 1; /**< The slave is online. */

   250

    unsigned int operational : 1; /**< The slave was brought into \a OP state

   251

                                    using the specified configuration. */

   252

    unsigned int al_state : 4; /**< The application-layer state of the slave.

   253

                                 - 1: \a INIT

   254

                                 - 2: \a PREOP

   255

                                 - 4: \a SAFEOP

   256

                                 - 8: \a OP

   257

   258

                                 Note that each state is coded in a different

   259

                                 bit! */

   260

} ec_slave_config_state_t;

   261

   262

/*****************************************************************************/

   263

   264

/** Master information.

   265

 *

   266

 * This is used as an output parameter of ecrt_master().

   267

 *

   268

 * \see ecrt_master().

   269

 */

   270

typedef struct {

   271

   unsigned int slave_count; /**< Number of slaves in the bus. */

   272

   unsigned int link_up : 1; /**< \a true, if the network link is up. */

   273

   uint8_t scan_busy; /**< \a true, while the master is scanning the bus */

   274

   uint64_t app_time; /**< Application time. */

   275

} ec_master_info_t;

   276

   277

/*****************************************************************************/

   278

   279

/** EtherCAT slave port descriptor.

   280

 */

   281

typedef enum {

   282

    EC_PORT_NOT_IMPLEMENTED, /**< Port is not implemented. */

   283

    EC_PORT_NOT_CONFIGURED, /**< Port is not configured. */

   284

    EC_PORT_EBUS, /**< Port is an e-bus. */

   285

    EC_PORT_MII /**< Port is a mii. */

   286

} ec_slave_port_desc_t;

   287

   288

/*****************************************************************************/

   289

   290

/** EtherCAT slave port information.

   291

 */

   292

typedef struct {

   293

    uint8_t link_up; /**< Link detected. */

   294

    uint8_t loop_closed; /**< Loop closed. */

   295

    uint8_t signal_detected; /**< Detected signal on RX port. */

   296

} ec_slave_port_link_t;

   297

   298

/*****************************************************************************/

   299

   300

/** Slave information.

   301

 *

   302

 * This is used as an output parameter of ecrt_master_get_slave().

   303

 *

   304

 * \see ecrt_master_get_slave().

   305

 */

   306

typedef struct {

   307

    uint16_t position; /**< Offset of the slave in the ring. */

   308

    uint32_t vendor_id; /**< Vendor-ID stored on the slave. */

   309

    uint32_t product_code; /**< Product-Code stored on the slave. */

   310

    uint32_t revision_number; /**< Revision-Number stored on the slave. */

   311

    uint32_t serial_number; /**< Serial-Number stored on the slave. */

   312

    uint16_t alias; /**< The slaves alias if not equal to 0. */

   313

    int16_t current_on_ebus; /**< Used current in mA. */

   314

    struct {

   315

        ec_slave_port_desc_t desc; /**< Physical port type. */

   316

        ec_slave_port_link_t link; /**< Port link state. */

   317

        uint32_t receive_time; /**< Receive time on DC transmission delay

   318

                                 measurement. */

   319

        uint16_t next_slave; /**< Ring position of next DC slave on that

   320

                               port.  */

   321

        uint32_t delay_to_next_dc; /**< Delay [ns] to next DC slave. */

   322

    } ports[EC_MAX_PORTS]; /**< Port information. */

   323

    uint8_t al_state; /**< Current state of the slave. */

   324

    uint8_t error_flag; /**< Error flag for that slave. */

   325

    uint8_t sync_count; /**< Number of sync managers. */

   326

    uint16_t sdo_count; /**< Number of SDOs. */

   327

    char name[EC_MAX_STRING_LENGTH]; /**< Name of the slave. */

   328

} ec_slave_info_t;

   329

   330

/*****************************************************************************/

   331

   332

/** Domain working counter interpretation.

   333

 *

   334

 * This is used in ec_domain_state_t.

   335

 */

   336

typedef enum {

   337

    EC_WC_ZERO = 0,   /**< No registered process data were exchanged. */

   338

    EC_WC_INCOMPLETE, /**< Some of the registered process data were

   339

                        exchanged. */

   340

    EC_WC_COMPLETE    /**< All registered process data were exchanged. */

   341

} ec_wc_state_t;

   342

   343

/*****************************************************************************/

   344

   345

/** Domain state.

   346

 *

   347

 * This is used for the output parameter of ecrt_domain_state().

   348

 */

   349

typedef struct {

   350

    unsigned int working_counter; /**< Value of the last working counter. */

   351

    ec_wc_state_t wc_state; /**< Working counter interpretation. */

   352

    unsigned int redundancy_active; /**< Redundant link is in use. */

   353

} ec_domain_state_t;

   354

   355

/*****************************************************************************/

   356

   357

/** Direction type for PDO assignment functions.

   358

 */

   359

typedef enum {

   360

    EC_DIR_INVALID, /**< Invalid direction. Do not use this value. */

   361

    EC_DIR_OUTPUT, /**< Values written by the master. */

   362

    EC_DIR_INPUT, /**< Values read by the master. */

   363

    EC_DIR_COUNT /**< Number of directions. For internal use only. */

   364

} ec_direction_t;

   365

   366

/*****************************************************************************/

   367

   368

/** Watchdog mode for sync manager configuration.

   369

 *

   370

 * Used to specify, if a sync manager's watchdog is to be enabled.

   371

 */

   372

typedef enum {

   373

    EC_WD_DEFAULT, /**< Use the default setting of the sync manager. */

   374

    EC_WD_ENABLE, /**< Enable the watchdog. */

   375

    EC_WD_DISABLE, /**< Disable the watchdog. */

   376

} ec_watchdog_mode_t;

   377

   378

/*****************************************************************************/

   379

   380

/** PDO entry configuration information.

   381

 *

   382

 * This is the data type of the \a entries field in ec_pdo_info_t.

   383

 *

   384

 * \see ecrt_slave_config_pdos().

   385

 */

   386

typedef struct {

   387

    uint16_t index; /**< PDO entry index. */

   388

    uint8_t subindex; /**< PDO entry subindex. */

   389

    uint8_t bit_length; /**< Size of the PDO entry in bit. */

   390

} ec_pdo_entry_info_t;

   391

   392

/*****************************************************************************/

   393

   394

/** PDO configuration information.

   395

 *

   396

 * This is the data type of the \a pdos field in ec_sync_info_t.

   397

 *

   398

 * \see ecrt_slave_config_pdos().

   399

 */

   400

typedef struct {

   401

    uint16_t index; /**< PDO index. */

   402

    unsigned int n_entries; /**< Number of PDO entries in \a entries to map.

   403

                              Zero means, that the default mapping shall be

   404

                              used (this can only be done if the slave is

   405

                              present at bus configuration time). */

   406

    ec_pdo_entry_info_t *entries; /**< Array of PDO entries to map. Can either

   407

                                    be \a NULL, or must contain at

   408

                                    least \a n_entries values. */

   409

} ec_pdo_info_t;

   410

   411

/*****************************************************************************/

   412

   413

/** Sync manager configuration information.

   414

 *

   415

 * This can be use to configure multiple sync managers including the PDO

   416

 * assignment and PDO mapping. It is used as an input parameter type in

   417

 * ecrt_slave_config_pdos().

   418

 */

   419

typedef struct {

   420

    uint8_t index; /**< Sync manager index. Must be less

   421

                     than #EC_MAX_SYNC_MANAGERS for a valid sync manager,

   422

                     but can also be \a 0xff to mark the end of the list. */

   423

    ec_direction_t dir; /**< Sync manager direction. */

   424

    unsigned int n_pdos; /**< Number of PDOs in \a pdos. */

   425

    ec_pdo_info_t *pdos; /**< Array with PDOs to assign. This must contain

   426

                            at least \a n_pdos PDOs. */

   427

    ec_watchdog_mode_t watchdog_mode; /**< Watchdog mode. */

   428

} ec_sync_info_t;

   429

   430

/*****************************************************************************/

   431

   432

/** List record type for PDO entry mass-registration.

   433

 *

   434

 * This type is used for the array parameter of the

   435

 * ecrt_domain_reg_pdo_entry_list()

   436

 */

   437

typedef struct {

   438

    uint16_t alias; /**< Slave alias address. */

   439

    uint16_t position; /**< Slave position. */

   440

    uint32_t vendor_id; /**< Slave vendor ID. */

   441

    uint32_t product_code; /**< Slave product code. */

   442

    uint16_t index; /**< PDO entry index. */

   443

    uint8_t subindex; /**< PDO entry subindex. */

   444

    unsigned int *offset; /**< Pointer to a variable to store the PDO entry's

   445

                       (byte-)offset in the process data. */

   446

    unsigned int *bit_position; /**< Pointer to a variable to store a bit

   447

                                  position (0-7) within the \a offset. Can be

   448

                                  NULL, in which case an error is raised if the

   449

                                  PDO entry does not byte-align. */

   450

} ec_pdo_entry_reg_t;

   451

   452

/*****************************************************************************/

   453

   454

/** Request state.

   455

 *

   456

 * This is used as return type for ecrt_sdo_request_state() and

   457

 * ecrt_voe_handler_state().

   458

 */

   459

typedef enum {

   460

    EC_REQUEST_UNUSED, /**< Not requested. */

   461

    EC_REQUEST_BUSY, /**< Request is being processed. */

   462

    EC_REQUEST_SUCCESS, /**< Request was processed successfully. */

   463

    EC_REQUEST_ERROR, /**< Request processing failed. */

   464

} ec_request_state_t;

   465

   466

/*****************************************************************************/

   467

   468

/** Application-layer state.

   469

 */

   470

typedef enum {

   471

    EC_AL_STATE_INIT = 1, /**< Init. */

   472

    EC_AL_STATE_PREOP = 2, /**< Pre-operational. */

   473

    EC_AL_STATE_SAFEOP = 4, /**< Safe-operational. */

   474

    EC_AL_STATE_OP = 8, /**< Operational. */

   475

} ec_al_state_t;

   476

   477

/******************************************************************************

   478

 * Global functions

   479

 *****************************************************************************/

   480

   481

#ifdef __cplusplus

   482

extern "C" {

   483

#endif

   484

   485

/** Returns the version magic of the realtime interface.