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

 * Changes in version 1.5:

    43

 *

    44

 * - Added the distributed clocks feature and the respective method

    45

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

    46

 *   ecrt_master_application_time(), ecrt_master_sync_reference_clock() and

    47

 *   ecrt_master_sync_slave_clocks() for offset and drift compensation. The

    48

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

    49

 *   ecrt_master_sync_monitor_queue() and ecrt_master_sync_monitor_process()

    50

 *   methods can be used to monitor the synchrony.

    51

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

    52

 *   callback functions for locking and unlocking the fsm datagram queue.

    53

 * - Added watchdog configuration (method ecrt_slave_config_watchdog(),

    54

 *   #ec_watchdog_mode_t, \a watchdog_mode parameter in ec_sync_info_t and

    55

 *   ecrt_slave_config_sync_manager()).

    56

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

    57

 *   configuration via CompleteAccess.

    58

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

    59

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

    60

 *   userspace.

    61

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

    62

 *   ecrt_master_get_slave(), ecrt_master_get_sync_manager(),

    63

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

    64

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

    65

 * - Added ecrt_master_sdo_download() and ecrt_master_sdo_upload()

    66

 *   methods to let an application transfer SDOs before activating the master.

    67

 * - Changed the meaning of the negative return values of

    68

 *   ecrt_slave_config_reg_pdo_entry() and ecrt_slave_config_sdo*().

    69

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

    70

 *   ecrt_slave_config_create_voe_handler().

    71

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

    72

 *   used by VoE handlers.

    73

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

    74

 *   userspace library has to modify object internals.

    75

 * - Added 64-bit data access macros.

    76

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

    77

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

    78

 *   ad-hoc via the user-space library.

    79

 * - Added support for overlapping PDOs which allows inputs to use the same

    80

 *   space as outputs on the frame. This reduces the frame length.

    81

 *

    82

 *

    83

 * @{

    84

 */

    85

    86

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

    87

    88

#ifndef __ECRT_H__

    89

#define __ECRT_H__

    90

    91

#ifdef __KERNEL__

    92

#include <asm/byteorder.h>

    93

#include <linux/types.h>

    94

#include <linux/time.h>

    95

#else

    96

#include <stdlib.h> // for size_t

    97

#include <stdint.h>

    98

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

    99

#endif

   100

   101

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

   102

 * Global definitions

   103

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

   104

   105

/** EtherCAT realtime interface major version number.

   106

 */

   107

#define ECRT_VER_MAJOR 1

   108

   109

/** EtherCAT realtime interface minor version number.

   110

 */

   111

#define ECRT_VER_MINOR 5

   112

   113

/** EtherCAT realtime interface version word generator.

   114

 */

   115

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

   116

   117

/** EtherCAT realtime interface version word.

   118

 */

   119

#define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR)

   120

   121

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

   122

   123

/** End of list marker.

   124

 *

   125

 * This can be used with ecrt_slave_config_pdos().

   126

 */

   127

#define EC_END ~0U

   128

   129

/** Maximum number of sync managers per slave.

   130

 */

   131

#define EC_MAX_SYNC_MANAGERS 16

   132

   133

/** Maximum string length.

   134

 *

   135

 * Used in ec_slave_info_t.

   136

 */

   137

#define EC_MAX_STRING_LENGTH 64

   138

   139

/** Maximum number of slave ports. */

   140

#define EC_MAX_PORTS 4

   141

   142

/** Timeval to nanoseconds conversion.

   143

 *

   144

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

   145

 *

   146

 * \see void ecrt_master_application_time()

   147

 *

   148

 * \param TV struct timeval containing epoch time.

   149

 */

   150

#define EC_TIMEVAL2NANO(TV) \

   151

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

   152

   153

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

   154

 * Data types

   155

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

   156

   157

struct ec_master;

   158

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

   159

   160

struct ec_slave_config;

   161

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

   162

   163

struct ec_domain;

   164

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

   165

   166

struct ec_sdo_request;

   167

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

   168

   169

struct ec_voe_handler;

   170

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

   171

   172

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

   173

   174

/** Master state.

   175

 *

   176

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

   177

 *

   178

 * \see ecrt_master_state().

   179

 */

   180

typedef struct {

   181

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

   182

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

   183

                                  The states are coded in the lower 4 bits.

   184

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

   185

                                  slave in the bus is in the corresponding

   186

                                  state:

   187

                                  - Bit 0: \a INIT

   188

                                  - Bit 1: \a PREOP

   189

                                  - Bit 2: \a SAFEOP

   190

                                  - Bit 3: \a OP */

   191

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

   192

} ec_master_state_t;

   193

   194

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

   195

   196

/** Slave configuration state.

   197

 *

   198

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

   199

 *

   200

 * \see ecrt_slave_config_state().

   201

 */

   202

typedef struct  {

   203

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

   204

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

   205

                                    using the specified configuration. */

   206

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

   207

                                 - 1: \a INIT

   208

                                 - 2: \a PREOP

   209

                                 - 4: \a SAFEOP

   210

                                 - 8: \a OP

   211

   212

                                 Note that each state is coded in a different

   213

                                 bit! */

   214

} ec_slave_config_state_t;

   215

   216

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

   217

   218

/** Master information.

   219

 *

   220

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

   221

 *

   222

 * \see ecrt_master().

   223

 */

   224

typedef struct {

   225

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

   226

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

   227

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

   228

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

   229

} ec_master_info_t;

   230

   231

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

   232

   233

/** EtherCAT slave port descriptor.

   234

 */

   235

typedef enum {

   236

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

   237

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

   238

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

   239

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

   240

} ec_slave_port_desc_t;

   241

   242

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

   243

   244

/** EtherCAT slave port information.

   245

 */

   246

typedef struct {

   247

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

   248

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

   249

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

   250

} ec_slave_port_link_t;

   251

   252

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

   253

   254

/** Slave information.

   255

 *

   256

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

   257

 *

   258

 * \see ecrt_master_get_slave().

   259

 */

   260

typedef struct {

   261

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

   262

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

   263

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

   264

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

   265

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

   266

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

   267

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

   268

    struct {

   269

        ec_slave_port_desc_t desc;

   270

        ec_slave_port_link_t link;

   271

        uint32_t receive_time;

   272

        uint16_t next_slave;

   273

        uint32_t delay_to_next_dc;

   274

    } ports[EC_MAX_PORTS];

   275

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

   276

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

   277

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

   278

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

   279

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

   280

} ec_slave_info_t;

   281

   282

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

   283

   284

/** Domain working counter interpretation.

   285

 *

   286

 * This is used in ec_domain_state_t.

   287

 */

   288

typedef enum {

   289

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

   290

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

   291

                        exchanged. */

   292

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

   293

} ec_wc_state_t;

   294

   295

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

   296

   297

/** Domain state.

   298

 *

   299

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

   300

 */

   301

typedef struct {

   302

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

   303

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

   304

} ec_domain_state_t;

   305

   306

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

   307

   308

/** Direction type for PDO assignment functions.

   309

 */

   310

typedef enum {

   311

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

   312

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

   313

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

   314

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

   315

} ec_direction_t;

   316

   317

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

   318

   319

/** Watchdog mode for sync manager configuration.

   320

 *

   321

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

   322

 */

   323

typedef enum {

   324

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

   325

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

   326

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

   327

} ec_watchdog_mode_t;

   328

   329

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

   330

   331

/** PDO entry configuration information.

   332

 *

   333

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

   334

 *

   335

 * \see ecrt_slave_config_pdos().

   336

 */

   337

typedef struct {

   338

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

   339

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

   340

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

   341

} ec_pdo_entry_info_t;

   342

   343

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

   344

   345

/** PDO configuration information.

   346

 *

   347

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

   348

 *

   349

 * \see ecrt_slave_config_pdos().

   350

 */

   351

typedef struct {

   352

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

   353

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

   354

                              Zero means, that the default mapping shall be

   355

                              used (this can only be done if the slave is

   356

                              present at bus configuration time). */

   357

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

   358

                                    be \a NULL, or must contain at

   359

                                    least \a n_entries values. */

   360

} ec_pdo_info_t;

   361

   362

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

   363

   364

/** Sync manager configuration information.

   365

 *

   366

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

   367

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

   368

 * ecrt_slave_config_pdos().

   369

 */

   370

typedef struct {

   371

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

   372

                     than #EC_MAX_SYNC_MANAGERS for a valid sync manager,

   373

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

   374

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

   375

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

   376

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

   377

                            at least \a n_pdos PDOs. */

   378

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

   379

} ec_sync_info_t;

   380

   381

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

   382

   383

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

   384

 *

   385

 * This type is used for the array parameter of the

   386

 * ecrt_domain_reg_pdo_entry_list()

   387

 */

   388

typedef struct {

   389

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

   390

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

   391

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

   392

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

   393

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

   394

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

   395

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

   396

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

   397

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

   398

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

   399

                                  NULL, in which case an error is raised if the

   400

                                  PDO entry does not byte-align. */

   401

} ec_pdo_entry_reg_t;

   402

   403

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

   404

   405

/** Request state.

   406

 *

   407

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

   408

 * ecrt_voe_handler_state().

   409

 */

   410

typedef enum {

   411

    EC_REQUEST_UNUSED, /**< Not requested. */

   412

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

   413

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

   414

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

   415

} ec_request_state_t;

   416

   417

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

   418

   419

/** Application-layer state.

   420

 */

   421

typedef enum {

   422

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

   423

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

   424

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

   425

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

   426

} ec_al_state_t;

   427

   428

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

   429

 * Global functions

   430

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

   431

   432

#ifdef __cplusplus

   433

extern "C" {

   434

#endif

   435

   436

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

   437

 *

   438

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

   439

 */

   440

unsigned int ecrt_version_magic(void);

   441

   442

/** Requests an EtherCAT master for realtime operation.

   443

 *

   444

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

   445

 * for exclusive use.

   446

 *

   447

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

   448

 * ecrt_master_reserve().

   449

 *

   450

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

   451

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

   452

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

   453

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

   454

 *

   455

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

   456

 */

   457

ec_master_t *ecrt_request_master(

   458

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

   459

        );

   460

   461

#ifndef __KERNEL__

   462

   463

/** Opens an EtherCAT master for userspace access.

   464

 *

   465

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

   466

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

   467

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

   468

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

   469

 *

   470

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

   471

 *

   472

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

   473

 */

   474

ec_master_t *ecrt_open_master(

   475

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

   476

        );

   477

   478

#endif // #ifndef __KERNEL__

   479

   480

/** Releases a requested EtherCAT master.

   481

 *

   482

 * After use, a master it has to be released to make it available for other

   483

 * applications.

   484

 */

   485

void ecrt_release_master(