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 methods

    45

 *   ecrt_slave_config_dc_assign_activate() and

    46

 *   ecrt_slave_config_dc_sync_signals() to configure a slave for cyclic

    47

 *   operation, and ecrt_master_application_time(),

    48

 *   ecrt_master_sync_reference_clock() and  ecrt_master_sync_slave_clocks()

    49

 *   for offset and drift compensation. The EC_TIMEVAL2NANO() macro can be

    50

 *   used for epoch time conversion.

    51

 * - Changed the meaning of the negative return values of

    52

 *   ecrt_slave_config_reg_pdo_entry() and ecrt_slave_config_sdo*().

    53

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

    54

 *   ecrt_slave_config_create_voe_handler().

    55

 * - Renamed ec_sdo_request_state_t to ec_request_state_t, because it is also

    56

 *   used by VoE handlers.

    57

 * - Added ecrt_master_slave() to get information about a certain slave.

    58

 * - Added ecrt_slave_sdo_upload() and ecrt_slave_sdo_download() methods to

    59

 *   let an application transfer SDOs before activating the master.

    60

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

    61

 *   userspace library has to modify object internals.

    62

 * - Added 64-bit data access macros.

    63

 *

    64

 * @{

    65

 */

    66

    67

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

    68

    69

#ifndef __ECRT_H__

    70

#define __ECRT_H__

    71

    72

#ifdef __KERNEL__

    73

#include <asm/byteorder.h>

    74

#include <linux/types.h>

    75

#include <linux/time.h>

    76

#else

    77

#include <stdlib.h> // for size_t

    78

#include <stdint.h>

    79

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

    80

#endif

    81

    82

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

    83

 * Global definitions

    84

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

    85

    86

/** EtherCAT realtime interface major version number.

    87

 */

    88

#define ECRT_VER_MAJOR 1

    89

    90

/** EtherCAT realtime interface minor version number.

    91

 */

    92

#define ECRT_VER_MINOR 5

    93

    94

/** EtherCAT realtime interface version word generator.

    95

 */

    96

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

    97

    98

/** EtherCAT realtime interface version word.

    99

 */

   100

#define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR)

   101

   102

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

   103

   104

/** End of list marker.

   105

 *

   106

 * This can be used with ecrt_slave_config_pdos().

   107

 */

   108

#define EC_END ~0U

   109

   110

/** Maximum number of sync managers per slave.

   111

 */

   112

#define EC_MAX_SYNC_MANAGERS 16

   113

   114

/** Maximum string length.

   115

 *

   116

 * Used in ec_slave_info_t.

   117

 */

   118

#define EC_MAX_STRING_LENGTH 64

   119

   120

/** Timeval to nanoseconds conversion.

   121

 *

   122

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

   123

 *

   124

 * \see ecrt_master_sync_reference_clock()

   125

 *

   126

 * \param TV Pointer to struct timeval.

   127

 */

   128

#define EC_TIMEVAL2NANO(TV) \

   129

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

   130

   131

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

   132

 * Data types 

   133

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

   134

   135

struct ec_master;

   136

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

   137

   138

struct ec_slave_config;

   139

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

   140

   141

struct ec_domain;

   142

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

   143

   144

struct ec_sdo_request;

   145

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

   146

   147

struct ec_voe_handler;

   148

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

   149

   150

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

   151

   152

/** Master state.

   153

 *

   154

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

   155

 *

   156

 * \see ecrt_master_state().

   157

 */

   158

typedef struct {

   159

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

   160

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

   161

                                  The states are coded in the lower 4 bits.

   162

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

   163

                                  slave in the bus is in the corresponding

   164

                                  state:

   165

                                  - Bit 0: \a INIT

   166

                                  - Bit 1: \a PREOP

   167

                                  - Bit 2: \a SAFEOP

   168

                                  - Bit 3: \a OP */

   169

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

   170

} ec_master_state_t;

   171

   172

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

   173

   174

/** Slave configuration state.

   175

 *

   176

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

   177

 * 

   178

 * \see ecrt_slave_config_state().

   179

 */

   180

typedef struct  {

   181

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

   182

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

   183

                                    using the specified configuration. */

   184

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

   185

                                 - 1: \a INIT

   186

                                 - 2: \a PREOP

   187

                                 - 4: \a SAFEOP

   188

                                 - 8: \a OP

   189

   190

                                 Note that each state is coded in a different

   191

                                 bit! */

   192

} ec_slave_config_state_t;

   193

   194

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

   195

   196

/** Slave information.

   197

 *

   198

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

   199

 *

   200

 * \see ecrt_master_slave().

   201

 */

   202

typedef struct {

   203

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

   204

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

   205

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

   206

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

   207

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

   208

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

   209

    int16_t current_on_ebus;

   210

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

   211

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

   212

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

   213

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

   214

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

   215

} ec_slave_info_t;

   216

   217

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

   218

   219

/** Domain working counter interpretation.

   220

 *

   221

 * This is used in ec_domain_state_t.

   222

 */

   223

typedef enum {

   224

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

   225

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

   226

                        exchanged. */

   227

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

   228

} ec_wc_state_t;

   229

   230

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

   231

   232

/** Domain state.

   233

 *

   234

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

   235

 */

   236

typedef struct {

   237

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

   238

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

   239

} ec_domain_state_t;

   240

   241

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

   242

   243

/** Direction type for PDO assignment functions.

   244

 */

   245

typedef enum {

   246

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

   247

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

   248

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

   249

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

   250

} ec_direction_t;

   251

   252

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

   253

   254

/** PDO entry configuration information.

   255

 *

   256

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

   257

 *

   258

 * \see ecrt_slave_config_pdos().

   259

 */

   260

typedef struct {

   261

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

   262

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

   263

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

   264

} ec_pdo_entry_info_t;

   265

   266

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

   267

   268

/** PDO configuration information.

   269

 * 

   270

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

   271

 * 

   272

 * \see ecrt_slave_config_pdos().

   273

 */

   274

typedef struct {

   275

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

   276

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

   277

                              Zero means, that the default mapping shall be

   278

                              used (this can only be done if the slave is

   279

                              present at bus configuration time). */

   280

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

   281

                                    be \a NULL, or must contain at

   282

                                    least \a n_entries values. */

   283

} ec_pdo_info_t;

   284

   285

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

   286

   287

/** Sync manager configuration information.

   288

 *

   289

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

   290

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

   291

 * ecrt_slave_config_pdos().

   292

 */

   293

typedef struct {

   294

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

   295

                     than #EC_MAX_SYNC_MANAGERS for a valid sync manager,

   296

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

   297

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

   298

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

   299

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

   300

                            at least \a n_pdos PDOs. */

   301

} ec_sync_info_t;

   302

   303

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

   304

   305

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

   306

 *

   307

 * This type is used for the array parameter of the

   308

 * ecrt_domain_reg_pdo_entry_list()

   309

 */

   310

typedef struct {

   311

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

   312

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

   313

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

   314

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

   315

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

   316

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

   317

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

   318

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

   319

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

   320

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

   321

                                  NULL, in which case an error is raised if the

   322

                                  PDO entry does not byte-align. */

   323

} ec_pdo_entry_reg_t;

   324

   325

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

   326

   327

/** Request state.

   328

 *

   329

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

   330

 * ecrt_voe_handler_state().

   331

 */

   332

typedef enum {

   333

    EC_REQUEST_UNUSED, /**< Not requested. */

   334

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

   335

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

   336

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

   337

} ec_request_state_t;

   338

   339

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

   340

 * Global functions

   341

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

   342

   343

#ifdef __cplusplus

   344

extern "C" {

   345

#endif

   346

   347

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

   348

 *

   349

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

   350

 */

   351

unsigned int ecrt_version_magic(void);

   352

   353

/** Requests an EtherCAT master for realtime operation.

   354

 * 

   355

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

   356

 * for exclusive use.

   357

 *

   358

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

   359

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

   360

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

   361

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

   362

 *

   363

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

   364

 */

   365

ec_master_t *ecrt_request_master(

   366

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

   367

        );

   368

   369

/** Releases a requested EtherCAT master.

   370

 *

   371

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

   372

 * applications.

   373

 */

   374

void ecrt_release_master(

   375

        ec_master_t *master /**< EtherCAT master */

   376

        );

   377

   378

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

   379

 * Master methods

   380

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

   381

   382

#ifdef __KERNEL__

   383

   384

/** Sets the locking callbacks.

   385

 *

   386

 * For concurrent master access, the application has to provide a locking

   387

 * mechanism (see section FIXME in the docs). The method takes two function

   388

 * pointers and a data value as its parameters. The arbitrary \a cb_data value

   389

 * will be passed as argument on every callback. Asynchronous master access

   390

 * (like EoE processing) is only possible if the callbacks have been set.

   391

 *

   392

 * The request_cb function must return zero, to allow another instance

   393

 * (an EoE process for example) to access the master. Non-zero means,

   394

 * that access is currently forbidden.

   395

 */

   396

void ecrt_master_callbacks(

   397

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

   398

        int (*request_cb)(void *), /**< Lock request function. */

   399

        void (*release_cb)(void *), /**< Lock release function. */

   400

        void *cb_data /**< Arbitrary user data. */

   401

        );

   402

   403

#endif /* __KERNEL__ */

   404

   405

/** Creates a new process data domain.

   406

 *

   407

 * For process data exchange, at least one process data domain is needed.

   408

 * This method creates a new process data domain and returns a pointer to the

   409

 * new domain object. This object can be used for registering PDOs and

   410

 * exchanging them in cyclic operation.

   411

 *

   412

 * \return Pointer to the new domain on success, else NULL.

   413

 */

   414

ec_domain_t *ecrt_master_create_domain(

   415

        ec_master_t *master /**< EtherCAT master. */

   416

        );

   417

   418

/** Obtains a slave configuration.

   419

 *

   420

 * Creates a slave configuration object for the given \a alias and \a position

   421

 * tuple and returns it. If a configuration with the same \a alias and \a

   422

 * position already exists, it will be re-used. In the latter case, the given

   423

 * vendor ID and product code are compared to the stored ones. On mismatch, an

   424

 * error message is raised and the function returns \a NULL.

   425

 *

   426

 * Slaves are addressed with the \a alias and \a position parameters.

   427

 * - If \a alias is zero, \a position is interpreted as the desired slave's

   428

 *   ring position.

   429

 * - If \a alias is non-zero, it matches a slave with the given alias. In this

   430

 *   case, \a position is interpreted as ring offset, starting from the

   431

 *   aliased slave, so a position of zero means the aliased slave itself and a

   432

 *   positive value matches the n-th slave behind the aliased one.

   433

 *

   434

 * If the slave with the given address is found during the bus configuration,

   435

 * its vendor ID and product code are matched against the given value. On

   436

 * mismatch, the slave is not configured and an error message is raised.

   437

 *

   438

 * If different slave configurations are pointing to the same slave during bus

   439

 * configuration, a warning is raised and only the first configuration is

   440

 * applied.

   441

 *

   442

 * \retval >0 Pointer to the slave configuration structure.

   443

 * \retval NULL in the error case.

   444

 */

   445

ec_slave_config_t *ecrt_master_slave_config(

   446

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

   447

        uint16_t alias, /**< Slave alias. */

   448

        uint16_t position, /**< Slave position. */

   449

        uint32_t vendor_id, /**< Expected vendor ID. */

   450

        uint32_t product_code /**< Expected product code. */

   451

        );

   452

   453

#ifndef __KERNEL__

   454

   455

/** Obtains slave information.

   456

 *

   457

 * Tries to find the slave with the given ring position. The obtained

   458

 * information is stored in a structure. No memory is allocated on the heap in

   459

 * this function.

   460

 *

   461

 * \attention The pointer to this structure must point to a valid variable.

   462

 *

   463

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

   464

 */

   465

int ecrt_master_slave(

   466

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

   467

        uint16_t position, /**< Slave position. */

   468

        ec_slave_info_t *slave_info /**< Structure that will output the

   469

                                      information */

   470

        );

   471

   472

#endif /* ifndef __KERNEL__ */

   473

   474

/** Finishes the configuration phase and prepares for cyclic operation.

   475

 *

   476

 * This function tells the master that the configuration phase is finished and

   477

 * the realtime operation will begin. The function allocates internal memory

   478

 * for the domains and calculates the logical FMMU addresses for domain

   479

 * members. It tells the master state machine that the bus configuration is

   480

 * now to be applied.

   481

 *

   482

 * \attention After this function has been called, the realtime application is

   483

 * in charge of cyclically calling ecrt_master_send() and

   484

 * ecrt_master_receive() to ensure bus communication. Before calling this

   485

 * function, the master thread is responsible for that, so these functions may

   486

 * not be called!

   487

 *