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.

    49

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

    50

 *   callback functions for sending and receiving datagrams.

    51

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

    52

 *   datagrams.

    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_open_master() and ecrt_master_reserve() separation for

    57

 *   userspace.

    58

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

    59

 *   ecrt_master_get_slave(), ecrt_master_get_sync_manager(),

    60

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

    61

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

    62

 * - Added ecrt_master_sdo_download() and ecrt_master_sdo_upload()

    63

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

    64

 * - Changed the meaning of the negative return values of

    65

 *   ecrt_slave_config_reg_pdo_entry() and ecrt_slave_config_sdo*().

    66

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

    67

 *   ecrt_slave_config_create_voe_handler().

    68

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

    69

 *   used by VoE handlers.

    70

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

    71

 *   userspace library has to modify object internals.

    72

 * - Added 64-bit data access macros.

    73

 *

    74

 * @{

    75

 */

    76

    77

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

    78

    79

#ifndef __ECRT_H__

    80

#define __ECRT_H__

    81

    82

#ifdef __KERNEL__

    83

#include <asm/byteorder.h>

    84

#include <linux/types.h>

    85

#include <linux/time.h>

    86

#else

    87

#include <stdlib.h> // for size_t

    88

#include <stdint.h>

    89

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

    90

#endif

    91

    92

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

    93

 * Global definitions

    94

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

    95

    96

/** EtherCAT realtime interface major version number.

    97

 */

    98

#define ECRT_VER_MAJOR 1

    99

   100

/** EtherCAT realtime interface minor version number.

   101

 */

   102

#define ECRT_VER_MINOR 5

   103

   104

/** EtherCAT realtime interface version word generator.

   105

 */

   106

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

   107

   108

/** EtherCAT realtime interface version word.

   109

 */

   110

#define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR)

   111

   112

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

   113

   114

/** End of list marker.

   115

 *

   116

 * This can be used with ecrt_slave_config_pdos().

   117

 */

   118

#define EC_END ~0U

   119

   120

/** Maximum number of sync managers per slave.

   121

 */

   122

#define EC_MAX_SYNC_MANAGERS 16

   123

   124

/** Maximum string length.

   125

 *

   126

 * Used in ec_slave_info_t.

   127

 */

   128

#define EC_MAX_STRING_LENGTH 64

   129

   130

/** Timeval to nanoseconds conversion.

   131

 *

   132

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

   133

 *

   134

 * \see void ecrt_master_application_time()

   135

 *

   136

 * \param TV struct timeval containing epoch time.

   137

 */

   138

#define EC_TIMEVAL2NANO(TV) \

   139

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

   140

   141

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

   142

 * Data types 

   143

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

   144

   145

struct ec_master;

   146

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

   147

   148

struct ec_slave_config;

   149

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

   150

   151

struct ec_domain;

   152

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

   153

   154

struct ec_sdo_request;

   155

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

   156

   157

struct ec_voe_handler;

   158

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

   159

   160

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

   161

   162

/** Master state.

   163

 *

   164

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

   165

 *

   166

 * \see ecrt_master_state().

   167

 */

   168

typedef struct {

   169

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

   170

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

   171

                                  The states are coded in the lower 4 bits.

   172

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

   173

                                  slave in the bus is in the corresponding

   174

                                  state:

   175

                                  - Bit 0: \a INIT

   176

                                  - Bit 1: \a PREOP

   177

                                  - Bit 2: \a SAFEOP

   178

                                  - Bit 3: \a OP */

   179

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

   180

} ec_master_state_t;

   181

   182

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

   183

   184

/** Slave configuration state.

   185

 *

   186

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

   187

 * 

   188

 * \see ecrt_slave_config_state().

   189

 */

   190

typedef struct  {

   191

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

   192

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

   193

                                    using the specified configuration. */

   194

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

   195

                                 - 1: \a INIT

   196

                                 - 2: \a PREOP

   197

                                 - 4: \a SAFEOP

   198

                                 - 8: \a OP

   199

   200

                                 Note that each state is coded in a different

   201

                                 bit! */

   202

} ec_slave_config_state_t;

   203

   204

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

   205

   206

#ifndef __KERNEL__

   207

   208

/** Master information.

   209

 *

   210

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

   211

 *

   212

 * \see ecrt_master().

   213

 */

   214

typedef struct {

   215

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

   216

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

   218

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

   219

} ec_master_info_t;

   220

   221

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

   222

   223

/** Slave information.

   224

 *

   225

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

   226

 *

   227

 * \see ecrt_master_get_slave().

   228

 */

   229

typedef struct {

   230

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

   231

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

   232

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

   233

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

   234

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

   235

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

   236

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

   237

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

   238

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

   239

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

   240

    uint16_t sdo_count; /**< Number of SDO's. */

   241

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

   242

} ec_slave_info_t;

   243

   244

#endif // #ifndef __KERNEL__

   245

   246

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

   247

   248

/** Domain working counter interpretation.

   249

 *

   250

 * This is used in ec_domain_state_t.

   251

 */

   252

typedef enum {

   253

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

   254

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

   255

                        exchanged. */

   256

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

   257

} ec_wc_state_t;

   258

   259

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

   260

   261

/** Domain state.

   262

 *

   263

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

   264

 */

   265

typedef struct {

   266

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

   267

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

   268

} ec_domain_state_t;

   269

   270

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

   271

   272

/** Direction type for PDO assignment functions.

   273

 */

   274

typedef enum {

   275

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

   276

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

   277

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

   278

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

   279

} ec_direction_t;

   280

   281

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

   282

   283

/** Watchdog mode for sync manager configuration.

   284

 *

   285

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

   286

 */

   287

typedef enum {

   288

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

   289

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

   290

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

   291

} ec_watchdog_mode_t;

   292

   293

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

   294

   295

/** PDO entry configuration information.

   296

 *

   297

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

   298

 *

   299

 * \see ecrt_slave_config_pdos().

   300

 */

   301

typedef struct {

   302

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

   303

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

   304

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

   305

} ec_pdo_entry_info_t;

   306

   307

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

   308

   309

/** PDO configuration information.

   310

 * 

   311

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

   312

 * 

   313

 * \see ecrt_slave_config_pdos().

   314

 */

   315

typedef struct {

   316

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

   317

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

   318

                              Zero means, that the default mapping shall be

   319

                              used (this can only be done if the slave is

   320

                              present at bus configuration time). */

   321

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

   322

                                    be \a NULL, or must contain at

   323

                                    least \a n_entries values. */

   324

} ec_pdo_info_t;

   325

   326

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

   327

   328

/** Sync manager configuration information.

   329

 *

   330

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

   331

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

   332

 * ecrt_slave_config_pdos().

   333

 */

   334

typedef struct {

   335

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

   336

                     than #EC_MAX_SYNC_MANAGERS for a valid sync manager,

   337

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

   338

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

   339

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

   340

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

   341

                            at least \a n_pdos PDOs. */

   342

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

   343

} ec_sync_info_t;

   344

   345

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

   346

   347

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

   348

 *

   349

 * This type is used for the array parameter of the

   350

 * ecrt_domain_reg_pdo_entry_list()

   351

 */

   352

typedef struct {

   353

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

   354

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

   355

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

   356

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

   357

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

   358

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

   359

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

   360

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

   361

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

   362

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

   363

                                  NULL, in which case an error is raised if the

   364

                                  PDO entry does not byte-align. */

   365

} ec_pdo_entry_reg_t;

   366

   367

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

   368

   369

/** Request state.

   370

 *

   371

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

   372

 * ecrt_voe_handler_state().

   373

 */

   374

typedef enum {

   375

    EC_REQUEST_UNUSED, /**< Not requested. */

   376

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

   377

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

   378

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

   379

} ec_request_state_t;

   380

   381

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

   382

 * Global functions

   383

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

   384

   385

#ifdef __cplusplus

   386

extern "C" {

   387

#endif

   388

   389

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

   390

 *

   391

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

   392

 */

   393

unsigned int ecrt_version_magic(void);

   394

   395

/** Requests an EtherCAT master for realtime operation.

   396

 * 

   397

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

   398

 * for exclusive use.

   399

 *

   400

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

   401

 * ecrt_master_reserve().

   402

 *

   403

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

   404

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

   405

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

   406

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

   407

 *

   408

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

   409

 */

   410

ec_master_t *ecrt_request_master(

   411

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

   412

        );

   413

   414

#ifndef __KERNEL__

   415

   416

/** Opens an EtherCAT master for userspace access.

   417

 *

   418

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

   419

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

   420

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

   421

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

   422

 *

   423

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

   424

 *

   425

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

   426

 */

   427

ec_master_t *ecrt_open_master(

   428

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

   429

		);

   430

   431

#endif // #ifndef __KERNEL__

   432

   433

/** Releases a requested EtherCAT master.

   434

 *

   435

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

   436

 * applications.

   437

 */

   438

void ecrt_release_master(

   439

        ec_master_t *master /**< EtherCAT master */

   440

        );

   441

   442

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

   443

 * Master methods

   444

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

   445

   446

#ifndef __KERNEL__

   447

   448

/** Reserves an EtherCAT master for realtime operation.

   449

 *

   450

 * Before an application can use PDO/domain registration functions or SDO

   451

 * request functions on the master, it has to reserve one for exclusive use.

   452

 *

   453

 * \return 0 in case of success, else < 0

   454

 *

   455

 */

   456

int ecrt_master_reserve(

   457

		ec_master_t *master /**< EtherCAT master */

   458

		);

   459

   460

#endif // #ifndef __KERNEL__

   461

   462

#ifdef __KERNEL__

   463

   464

/** Sets the locking callbacks.

   465

 *

   466

 * For concurrent master access, i. e. if other instances than the application

   467

 * want to send and receive datagrams on the bus, the application has to

   468

 * provide a callback mechanism. This method takes two function pointers as

   469

 * its parameters. Asynchronous master access (like EoE processing) is only

   470

 * possible if the callbacks have been set.

   471

 *

   472

 * The task of the send callback (\a request_cb) is to decide, if the bus is

   473

 * currently accessible. In this case, it can call the ecrt_master_send_ext()

   474

 * method.

   475

 *

   476

 * The task of the receive callback (\a receive_cb) is to decide, if a call to

   477

 * ecrt_master_receive() is allowed and to execute it respectively.

   478

 */

   479

void ecrt_master_callbacks(

   480

        ec_master_t *master, /**< EtherCAT master */

   481

        void (*send_cb)(ec_master_t *), /**< Datagram sending callback. */

   482

        void (*receive_cb)(ec_master_t *) /**< Receive callback. */

   483

        );

   484

   485

#endif /* __KERNEL__ */

   486