1

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

     2

 *

     3

 *  $Id$

     4

 *

     5

 *  Copyright (C) 2006-2012  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

 * - Added ecrt_sdo_request_index() to change SDO index and subindex after

    50

 *   handler creation.

    51

 * - Added interface for retrieving CoE emergency messages, i. e.

    52

 *   ecrt_slave_config_emerg_size(), ecrt_slave_config_emerg_pop(),

    53

 *   ecrt_slave_config_emerg_clear(), ecrt_slave_config_emerg_overruns() and

    54

 *   the defines EC_HAVE_EMERGENCY and EC_COE_EMERGENCY_MSG_SIZE.

    55

 * - Added interface for direct EtherCAT register access: Added data type

    56

 *   ec_reg_request_t and methods ecrt_slave_config_create_reg_request(),

    57

 *   ecrt_reg_request_data(), ecrt_reg_request_state(),

    58

 *   ecrt_reg_request_write(), ecrt_reg_request_read() and the feature flag

    59

 *   EC_HAVE_REG_ACCESS.

    60

 * - Added method to select the reference clock,

    61

 *   ecrt_master_select_reference_clock() and the feature flag

    62

 *   EC_HAVE_SELECT_REF_CLOCK to check, if the method is available.

    63

 * - Added method to get the reference clock time,

    64

 *   ecrt_master_reference_clock_time() and the feature flag

    65

 *   EC_HAVE_REF_CLOCK_TIME to have the possibility to synchronize the master

    66

 *   clock to the reference clock.

    67

 * - Changed the datatypes of the shift times in ecrt_slave_config_dc() to

    68

 *   int32_t to correctly display negative shift times.

    69

 * - Added ecrt_slave_config_reg_pdo_entry_pos() and the feature flag

    70

 *   EC_HAVE_REG_BY_POS for registering PDO entries with non-unique indices

    71

 *   via their positions in the mapping.

    72

 *

    73

 * Changes in version 1.5:

    74

 *

    75

 * - Added the distributed clocks feature and the respective method

    76

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

    77

 *   ecrt_master_application_time(), ecrt_master_sync_reference_clock() and

    78

 *   ecrt_master_sync_slave_clocks() for offset and drift compensation. The

    79

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

    80

 *   ecrt_master_sync_monitor_queue() and ecrt_master_sync_monitor_process()

    81

 *   methods can be used to monitor the synchrony.

    82

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

    83

 *   callback functions for sending and receiving datagrams.

    84

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

    85

 *   datagrams.

    86

 * - Added watchdog configuration (method ecrt_slave_config_watchdog(),

    87

 *   #ec_watchdog_mode_t, \a watchdog_mode parameter in ec_sync_info_t and

    88

 *   ecrt_slave_config_sync_manager()).

    89

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

    90

 *   configuration via CompleteAccess.

    91

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

    92

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

    93

 *   userspace.

    94

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

    95

 *   ecrt_master_get_slave(), ecrt_master_get_sync_manager(),

    96

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

    97

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

    98

 * - Added ecrt_master_sdo_download(), ecrt_master_sdo_download_complete() and

    99

 *   ecrt_master_sdo_upload() methods to let an application transfer SDOs

   100

 *   before activating the master.

   101

 * - Changed the meaning of the negative return values of

   102

 *   ecrt_slave_config_reg_pdo_entry() and ecrt_slave_config_sdo*().

   103

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

   104

 *   ecrt_slave_config_create_voe_handler().

   105

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

   106

 *   used by VoE handlers.

   107

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

   108

 *   userspace library has to modify object internals.

   109

 * - Added 64-bit data access macros.

   110

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

   111

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

   112

 *   ad-hoc via the user-space library.

   113

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

   114

 *

   115

 * @{

   116

 */

   117

   118

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

   119

   120

#ifndef __ECRT_H__

   121

#define __ECRT_H__

   122

   123

#ifdef __KERNEL__

   124

#include <asm/byteorder.h>

   125

#include <linux/types.h>

   126

#include <linux/time.h>

   127

#else

   128

#include <stdlib.h> // for size_t

   129

#include <stdint.h>

   130

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

   131

#endif

   132

   133

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

   134

 * Global definitions

   135

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

   136

   137

/** EtherCAT realtime interface major version number.

   138

 */

   139

#define ECRT_VER_MAJOR 1

   140

   141

/** EtherCAT realtime interface minor version number.

   142

 */

   143

#define ECRT_VER_MINOR 5

   144

   145

/** EtherCAT realtime interface version word generator.

   146

 */

   147

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

   148

   149

/** EtherCAT realtime interface version word.

   150

 */

   151

#define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR)

   152

   153

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

   154

 * Feature flags

   155

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

   156

   157

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

   158

 *

   159

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

   160

 * ecrt_master_link_state() method are available.

   161

 */

   162

#define EC_HAVE_REDUNDANCY

   163

   164

/** Defined, if the CoE emergency ring feature is available.

   165

 *

   166

 * I. e. if the ecrt_slave_config_emerg_*() methods are available.

   167

 */

   168

#define EC_HAVE_EMERGENCY

   169

   170

/** Defined, if the register access interface is available.

   171

 *

   172

 * I. e. if the methods ecrt_slave_config_create_reg_request(),

   173

 * ecrt_reg_request_data(), ecrt_reg_request_state(), ecrt_reg_request_write()

   174

 * and ecrt_reg_request_read() are available.

   175

 */

   176

#define EC_HAVE_REG_ACCESS

   177

   178

/* Defined if the method ecrt_master_select_reference_clock() is available.

   179

 */

   180

#define EC_HAVE_SELECT_REF_CLOCK

   181

   182

/* Defined if the method ecrt_master_reference_clock_time() is available.

   183

 */

   184

#define EC_HAVE_REF_CLOCK_TIME

   185

   186

/* Defined if the method ecrt_slave_config_reg_pdo_entry_pos() is available.

   187

 */

   188

#define EC_HAVE_REG_BY_POS

   189

   190

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

   191

   192

/** End of list marker.

   193

 *

   194

 * This can be used with ecrt_slave_config_pdos().

   195

 */

   196

#define EC_END ~0U

   197

   198

/** Maximum number of sync managers per slave.

   199

 */

   200

#define EC_MAX_SYNC_MANAGERS 16

   201

   202

/** Maximum string length.

   203

 *

   204

 * Used in ec_slave_info_t.

   205

 */

   206

#define EC_MAX_STRING_LENGTH 64

   207

   208

/** Maximum number of slave ports. */

   209

#define EC_MAX_PORTS 4

   210

   211

/** Timeval to nanoseconds conversion.

   212

 *

   213

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

   214

 *

   215

 * \see void ecrt_master_application_time()

   216

 *

   217

 * \param TV struct timeval containing epoch time.

   218

 */

   219

#define EC_TIMEVAL2NANO(TV) \

   220

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

   221

   222

/** Size of a CoE emergency message in byte.

   223

 *

   224

 * \see ecrt_slave_config_emerg_pop().

   225

 */

   226

#define EC_COE_EMERGENCY_MSG_SIZE 8

   227

   228

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

   229

 * Data types

   230

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

   231

   232

struct ec_master;

   233

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

   234

   235

struct ec_slave_config;

   236

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

   237

   238

struct ec_domain;

   239

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

   240

   241

struct ec_sdo_request;

   242

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

   243

   244

struct ec_voe_handler;

   245

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

   246

   247

struct ec_reg_request;

   248

typedef struct ec_reg_request ec_reg_request_t; /**< \see ec_sdo_request. */

   249

   250

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

   251

   252

/** Master state.

   253

 *

   254

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

   255

 *

   256

 * \see ecrt_master_state().

   257

 */

   258

typedef struct {

   259

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

   260

                                      Ethernet devices. */

   261

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

   262

                                  The states are coded in the lower 4 bits.

   263

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

   264

                                  slave in the bus is in the corresponding

   265

                                  state:

   266

                                  - Bit 0: \a INIT

   267

                                  - Bit 1: \a PREOP

   268

                                  - Bit 2: \a SAFEOP

   269

                                  - Bit 3: \a OP */

   270

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

   271

                                up. */

   272

} ec_master_state_t;

   273

   274

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

   275

   276

/** Redundant link state.

   277

 *

   278

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

   279

 *

   280

 * \see ecrt_master_link_state().

   281

 */

   282

typedef struct {

   283

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

   284

                                      link. */

   285

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

   286

                                  the given link.  The states are coded in the

   287

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

   288

                                  that at least one slave in the bus is in the

   289

                                  corresponding state:

   290

                                  - Bit 0: \a INIT

   291

                                  - Bit 1: \a PREOP

   292

                                  - Bit 2: \a SAFEOP

   293

                                  - Bit 3: \a OP */

   294

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

   295

                               */

   296

} ec_master_link_state_t;

   297

   298

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

   299

   300

/** Slave configuration state.

   301

 *

   302

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

   303

 *

   304

 * \see ecrt_slave_config_state().

   305

 */

   306

typedef struct  {

   307

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

   308

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

   309

                                    using the specified configuration. */

   310

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

   311

                                 - 1: \a INIT

   312

                                 - 2: \a PREOP

   313

                                 - 4: \a SAFEOP

   314

                                 - 8: \a OP

   315

   316

                                 Note that each state is coded in a different

   317

                                 bit! */

   318

} ec_slave_config_state_t;

   319

   320

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

   321

   322

/** Master information.

   323

 *

   324

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

   325

 *

   326

 * \see ecrt_master().

   327

 */

   328

typedef struct {

   329

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

   330

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

   331

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

   332

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

   333

} ec_master_info_t;

   334

   335

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

   336

   337

/** EtherCAT slave port descriptor.

   338

 */

   339

typedef enum {

   340

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

   341

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

   342

    EC_PORT_EBUS, /**< Port is an E-Bus. */

   343

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

   344

} ec_slave_port_desc_t;

   345

   346

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

   347

   348

/** EtherCAT slave port information.

   349

 */

   350

typedef struct {

   351

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

   352

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

   353

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

   354

} ec_slave_port_link_t;

   355

   356

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

   357

   358

/** Slave information.

   359

 *

   360

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

   361

 *

   362

 * \see ecrt_master_get_slave().

   363

 */

   364

typedef struct {

   365

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

   366

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

   367

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

   368

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

   369

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

   370

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

   371

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

   372

    struct {

   373

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

   374

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

   375

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

   376

                                 measurement. */

   377

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

   378

                               port.  */

   379

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

   380

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

   381

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

   382

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

   383

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

   384

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

   385

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

   386

} ec_slave_info_t;

   387

   388

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

   389

   390

/** Domain working counter interpretation.

   391

 *

   392

 * This is used in ec_domain_state_t.

   393

 */

   394

typedef enum {

   395

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

   396

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

   397

                        exchanged. */

   398

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

   399

} ec_wc_state_t;

   400

   401

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

   402

   403

/** Domain state.

   404

 *

   405

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

   406

 */

   407

typedef struct {

   408

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

   409

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

   410

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

   411

} ec_domain_state_t;

   412

   413

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

   414

   415

/** Direction type for PDO assignment functions.

   416

 */

   417

typedef enum {

   418

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

   419

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

   420

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

   421

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

   422

} ec_direction_t;

   423

   424

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

   425

   426

/** Watchdog mode for sync manager configuration.

   427

 *

   428

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

   429

 */

   430

typedef enum {

   431

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

   432

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

   433

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

   434

} ec_watchdog_mode_t;

   435

   436

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

   437

   438

/** PDO entry configuration information.

   439

 *

   440

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

   441

 *

   442

 * \see ecrt_slave_config_pdos().

   443

 */

   444

typedef struct {

   445

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

   446

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

   447

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

   448

} ec_pdo_entry_info_t;

   449

   450

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

   451

   452

/** PDO configuration information.

   453

 *

   454

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

   455

 *

   456

 * \see ecrt_slave_config_pdos().

   457

 */

   458

typedef struct {

   459

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

   460

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

   461

                              Zero means, that the default mapping shall be

   462

                              used (this can only be done if the slave is

   463

                              present at bus configuration time). */

   464

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

   465

                                    be \a NULL, or must contain at

   466

                                    least \a n_entries values. */

   467

} ec_pdo_info_t;

   468

   469

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

   470

   471

/** Sync manager configuration information.

   472

 *

   473

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

   474

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

   475

 * ecrt_slave_config_pdos().

   476

 */

   477

typedef struct {

   478

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

   479

                     than #EC_MAX_SYNC_MANAGERS for a valid sync manager,

   480

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

   481

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

   482

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

   483

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

   484

                            at least \a n_pdos PDOs. */

   485

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