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.

    45

 *

    46

 * Changes in version 1.5:

    47

 *

    48

 * - Added the distributed clocks feature and the respective method

    49

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

    50

 *   ecrt_master_application_time(), ecrt_master_sync_reference_clock() and

    51

 *   ecrt_master_sync_slave_clocks() for offset and drift compensation. The

    52

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

    53

 *   ecrt_master_sync_monitor_queue() and ecrt_master_sync_monitor_process()

    54

 *   methods can be used to monitor the synchrony.

    55

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

    56

 *   callback functions for sending and receiving datagrams.

    57

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

    58

 *   datagrams.

    59

 * - Added watchdog configuration (method ecrt_slave_config_watchdog(),

    60

 *   #ec_watchdog_mode_t, \a watchdog_mode parameter in ec_sync_info_t and

    61

 *   ecrt_slave_config_sync_manager()).

    62

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

    63

 *   configuration via CompleteAccess.

    64

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

    65

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

    66

 *   userspace.

    67

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

    68

 *   ecrt_master_get_slave(), ecrt_master_get_sync_manager(),

    69

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

    70

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

    71

 * - Added ecrt_master_sdo_download(), ecrt_master_sdo_download_complete() and

    72

 *   ecrt_master_sdo_upload() methods to let an application transfer SDOs

    73

 *   before activating the master.

    74

 * - Changed the meaning of the negative return values of

    75

 *   ecrt_slave_config_reg_pdo_entry() and ecrt_slave_config_sdo*().

    76

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

    77

 *   ecrt_slave_config_create_voe_handler().

    78

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

    79

 *   used by VoE handlers.

    80

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

    81

 *   userspace library has to modify object internals.

    82

 * - Added 64-bit data access macros.

    83

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

    84

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

    85

 *   ad-hoc via the user-space library.

    86

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

    87

 *

    88

 * @{

    89

 */

    90

    91

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

    92

    93

#ifndef __ECRT_H__

    94

#define __ECRT_H__

    95

    96

#ifdef __KERNEL__

    97

#include <asm/byteorder.h>

    98

#include <linux/types.h>

    99

#include <linux/time.h>

   100

#else

   101

#include <stdlib.h> // for size_t

   102

#include <stdint.h>

   103

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

   104

#endif

   105

   106

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

   107

 * Global definitions

   108

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

   109

   110

/** EtherCAT realtime interface major version number.

   111

 */

   112

#define ECRT_VER_MAJOR 1

   113

   114

/** EtherCAT realtime interface minor version number.

   115

 */

   116

#define ECRT_VER_MINOR 5

   117

   118

/** EtherCAT realtime interface version word generator.

   119

 */

   120

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

   121

   122

/** EtherCAT realtime interface version word.

   123

 */

   124

#define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR)

   125

   126

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

   127

   128

/** End of list marker.

   129

 *

   130

 * This can be used with ecrt_slave_config_pdos().

   131

 */

   132

#define EC_END ~0U

   133

   134

/** Maximum number of sync managers per slave.

   135

 */

   136

#define EC_MAX_SYNC_MANAGERS 16

   137

   138

/** Maximum string length.

   139

 *

   140

 * Used in ec_slave_info_t.

   141

 */

   142

#define EC_MAX_STRING_LENGTH 64

   143

   144

/** Maximum number of slave ports. */

   145

#define EC_MAX_PORTS 4

   146

   147

/** Timeval to nanoseconds conversion.

   148

 *

   149

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

   150

 *

   151

 * \see void ecrt_master_application_time()

   152

 *

   153

 * \param TV struct timeval containing epoch time.

   154

 */

   155

#define EC_TIMEVAL2NANO(TV) \

   156

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

   157

   158

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

   159

 * Data types

   160

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

   161

   162

struct ec_master;

   163

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

   164

   165

struct ec_slave_config;

   166

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

   167

   168

struct ec_domain;

   169

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

   170

   171

struct ec_sdo_request;

   172

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

   173

   174

struct ec_voe_handler;

   175

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

   176

   177

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

   178

   179

/** Master state.

   180

 *

   181

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

   182

 *

   183

 * \see ecrt_master_state().

   184

 */

   185

typedef struct {

   186

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

   187

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

   188

                                  The states are coded in the lower 4 bits.

   189

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

   190

                                  slave in the bus is in the corresponding

   191

                                  state:

   192

                                  - Bit 0: \a INIT

   193

                                  - Bit 1: \a PREOP

   194

                                  - Bit 2: \a SAFEOP

   195

                                  - Bit 3: \a OP */

   196

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

   197

} ec_master_state_t;

   198

   199

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

   200

   201

/** Slave configuration state.

   202

 *

   203

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

   204

 *

   205

 * \see ecrt_slave_config_state().

   206

 */

   207

typedef struct  {

   208

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

   209

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

   210

                                    using the specified configuration. */

   211

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

   212

                                 - 1: \a INIT

   213

                                 - 2: \a PREOP

   214

                                 - 4: \a SAFEOP

   215

                                 - 8: \a OP

   216

   217

                                 Note that each state is coded in a different

   218

                                 bit! */

   219

} ec_slave_config_state_t;

   220

   221

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

   222

   223

/** Master information.

   224

 *

   225

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

   226

 *

   227

 * \see ecrt_master().

   228

 */

   229

typedef struct {

   230

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

   231

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

   232

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

   233

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

   234

} ec_master_info_t;

   235

   236

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

   237

   238

/** EtherCAT slave port descriptor.

   239

 */

   240

typedef enum {

   241

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

   242

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

   243

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

   244

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

   245

} ec_slave_port_desc_t;

   246

   247

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

   248

   249

/** EtherCAT slave port information.

   250

 */

   251

typedef struct {

   252

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

   253

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

   254

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

   255

} ec_slave_port_link_t;

   256

   257

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

   258

   259

/** Slave information.

   260

 *

   261

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

   262

 *

   263

 * \see ecrt_master_get_slave().

   264

 */

   265

typedef struct {

   266

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

   267

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

   268

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

   269

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

   270

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

   271

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

   272

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

   273

    struct {

   274

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

   275

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

   276

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

   277

                                 measurement. */

   278

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

   279

                               port.  */

   280

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

   281

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

   282

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

   283

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

   284

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

   285

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

   286

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

   287

} ec_slave_info_t;

   288

   289

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

   290

   291

/** Domain working counter interpretation.

   292

 *

   293

 * This is used in ec_domain_state_t.

   294

 */

   295

typedef enum {

   296

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

   297

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

   298

                        exchanged. */

   299

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

   300

} ec_wc_state_t;

   301

   302

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

   303

   304

/** Domain state.

   305

 *

   306

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

   307

 */

   308

typedef struct {

   309

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

   310

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

   312

} ec_domain_state_t;

   313

   314

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

   315

   316

/** Direction type for PDO assignment functions.

   317

 */

   318

typedef enum {

   319

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

   320

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

   321

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

   322

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

   323

} ec_direction_t;

   324

   325

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

   326

   327

/** Watchdog mode for sync manager configuration.

   328

 *

   329

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

   330

 */

   331

typedef enum {

   332

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

   333

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

   334

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

   335

} ec_watchdog_mode_t;

   336

   337

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

   338

   339

/** PDO entry configuration information.

   340

 *

   341

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

   342

 *

   343

 * \see ecrt_slave_config_pdos().

   344

 */

   345

typedef struct {

   346

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

   347

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

   348

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

   349

} ec_pdo_entry_info_t;

   350

   351

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

   352

   353

/** PDO configuration information.

   354

 *

   355

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

   356

 *

   357

 * \see ecrt_slave_config_pdos().

   358

 */

   359

typedef struct {

   360

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

   361

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

   362

                              Zero means, that the default mapping shall be

   363

                              used (this can only be done if the slave is

   364

                              present at bus configuration time). */

   365

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

   366

                                    be \a NULL, or must contain at

   367

                                    least \a n_entries values. */

   368

} ec_pdo_info_t;

   369

   370

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

   371

   372

/** Sync manager configuration information.

   373

 *

   374

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

   375

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

   376

 * ecrt_slave_config_pdos().

   377

 */

   378

typedef struct {

   379

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

   380

                     than #EC_MAX_SYNC_MANAGERS for a valid sync manager,

   381

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

   382

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

   383

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

   384

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

   385

                            at least \a n_pdos PDOs. */

   386

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

   387

} ec_sync_info_t;

   388

   389

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

   390

   391

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

   392

 *

   393

 * This type is used for the array parameter of the

   394

 * ecrt_domain_reg_pdo_entry_list()

   395

 */

   396

typedef struct {

   397

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

   398

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

   399

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

   400

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

   401

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

   402

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

   403

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

   404

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

   405

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

   406

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

   407

                                  NULL, in which case an error is raised if the

   408

                                  PDO entry does not byte-align. */

   409

} ec_pdo_entry_reg_t;

   410

   411

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

   412

   413

/** Request state.

   414

 *

   415

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

   416

 * ecrt_voe_handler_state().

   417

 */

   418

typedef enum {

   419

    EC_REQUEST_UNUSED, /**< Not requested. */

   420

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

   421

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

   422

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

   423

} ec_request_state_t;

   424

   425

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

   426

   427

/** Application-layer state.

   428

 */

   429

typedef enum {

   430

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

   431

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

   432

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

   433

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

   434

} ec_al_state_t;

   435

   436

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

   437

 * Global functions

   438

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

   439

   440

#ifdef __cplusplus

   441

extern "C" {

   442

#endif

   443

   444

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

   445

 *

   446

 * \return Value of ECRT_VERSION_MAGIC() at EtherCAT master compile time.

   447

 */

   448

unsigned int ecrt_version_magic(void);

   449

   450

/** Requests an EtherCAT master for realtime operation.

   451

 *

   452

 * Before an application can access an EtherCAT master, it has to reserve one

   453

 * for exclusive use.

   454

 *

   455

 * In userspace, this is a convenience function for ecrt_open_master() and

   456

 * ecrt_master_reserve().

   457

 *

   458

 * This function has to be the first function an application has to call to

   459

 * use EtherCAT. The function takes the index of the master as its argument.

   460

 * The first master has index 0, the n-th master has index n - 1. The number

   461

 * of masters has to be specified when loading the master module.

   462

 *

   463

 * \return Pointer to the reserved master, otherwise \a NULL.

   464

 */

   465

ec_master_t *ecrt_request_master(

   466

        unsigned int master_index /**< Index of the master to request. */

   467

        );

   468

   469

#ifndef __KERNEL__

   470

   471

/** Opens an EtherCAT master for userspace access.

   472

 *

   473

 * This function has to be the first function an application has to call to

   474

 * use EtherCAT. The function takes the index of the master as its argument.

   475

 * The first master has index 0, the n-th master has index n - 1. The number

   476

 * of masters has to be specified when loading the master module.

   477

 *

   478

 * For convenience, the function ecrt_request_master() can be used.

   479

 *

   480

 * \return Pointer to the opened master, otherwise \a NULL.

   481

 */

   482

ec_master_t *ecrt_open_master(

   483

        unsigned int master_index /**< Index of the master to request. */

   484

        );

   485