1

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

     2

 *

     3

 *  $Id$

     4

 *

     5

 *  Copyright (C) 2006  Florian Pose, Ingenieurgemeinschaft IgH

     6

 *

     7

 *  This file is part of the IgH EtherCAT Master.

     8

 *

     9

 *  The IgH EtherCAT Master is free software; you can redistribute it

    10

 *  and/or modify it under the terms of the GNU General Public License

    11

 *  as published by the Free Software Foundation; either version 2 of the

    12

 *  License, or (at your option) any later version.

    13

 *

    14

 *  The IgH EtherCAT Master is distributed in the hope that it will be

    15

 *  useful, but WITHOUT ANY WARRANTY; without even the implied warranty of

    16

 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

    17

 *  GNU General Public License for more details.

    18

 *

    19

 *  You should have received a copy of the GNU General Public License

    20

 *  along with the IgH EtherCAT Master; if not, write to the Free Software

    21

 *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

    22

 *

    23

 *  The right to use EtherCAT Technology is granted and comes free of

    24

 *  charge under condition of compatibility of product made by

    25

 *  Licensee. People intending to distribute/sell products based on the

    26

 *  code, have to sign an agreement to guarantee that products using

    27

 *  software based on IgH EtherCAT master stay compatible with the actual

    28

 *  EtherCAT specification (which are released themselves as an open

    29

 *  standard) as the (only) precondition to have the right to use EtherCAT

    30

 *  Technology, IP and trade marks.

    31

 *

    32

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

    33

    34

/** \file

    35

 *

    36

 * EtherCAT Real-Time Interface.

    37

 *

    38

 * \defgroup RealtimeInterface EtherCAT Real-Time Interface

    39

 *

    40

 * EtherCAT interface for realtime modules. This interface is designed for

    41

 * realtime modules that want to use EtherCAT. There are functions to request

    42

 * a master, to map process data, to communicate with slaves via CoE and to

    43

 * configure and activate the bus.

    44

 *

    45

 * Changes in Version 1.4:

    46

 *

    47

 * - Replaced ec_slave_t with ec_slave_config_t, separating the slave objects

    48

 *   from the requested bus configuration. Therefore, renamed

    49

 *   ecrt_master_get_slave() to ecrt_master_slave_config().

    50

 * - Replaced slave address string with alias and position values. See

    51

 *   ecrt_master_slave_config().

    52

 * - Removed ecrt_master_get_slave_by_pos(), because it is no longer

    53

 *   necessary (alias/position, slave configurations).

    54

 * - Added ec_slave_config_state_t for the new method

    55

 *   ecrt_slave_config_state().

    56

 * - Process data memory for a domain can now be allocated externally. This

    57

 *   offers the possibility to use a shared-memory-region. Therefore,

    58

 *   added the domain methods ecrt_domain_size() and ecrt_domain_memory().

    59

 * - Replaced the process data pointers in the Pdo entry registration

    60

 *   functions with a process data offset, that is now returned by

    61

 *   ecrt_domain_reg_pdo_entry(). This was necessary for the external

    62

 *   domain memory. An additional advantage is, that the returned offset value

    63

 *   is directly usable.

    64

 * - Replaced ecrt_slave_pdo_mapping/add/clear() with

    65

 *   ecrt_slave_config_mapping() that is now able to specify Pdo mapping and

    66

 *   Pdo configuration. Pdo entries mapped in this way can now immediately be

    67

 *   registered. The Pdo mapping and the configuration are described with the

    68

 *   new data types ec_pdo_info_t and ec_pdo_entry_info_t.

    69

 * - Renamed ec_bus_status_t, ec_master_status_t to ec_bus_state_t and

    70

 *   ec_master_state_t, respectively. Renamed ecrt_master_get_status() to

    71

 *   ecrt_master_state(), for consistency reasons.

    72

 * - Added ec_domain_state_t and ec_wc_state_t for a new output parameter

    73

 *   of ecrt_domain_state().

    74

 * - Former "Pdo registration" meant Pdo entry registration in fact, therefore

    75

 *   renamed ec_pdo_reg_t to ec_pdo_entry_reg_t and ecrt_domain_register_pdo()

    76

 *   to ecrt_domain_reg_pdo_entry().

    77

 * - Removed ecrt_domain_register_pdo_range(), because it's functionality can

    78

 *   be reached by specifying an explicit Pdo mapping and registering those

    79

 *   Pdo entries.

    80

 *

    81

 * @{

    82

 */

    83

    84

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

    85

    86

#ifndef __ECRT_H__

    87

#define __ECRT_H__

    88

    89

#include <asm/byteorder.h>

    90

    91

#ifdef __KERNEL__

    92

#include <linux/types.h>

    93

#else

    94

#include <stdint.h>

    95

#endif

    96

    97

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

    98

 * Global definitions

    99

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

   100

   101

/** EtherCAT real-time interface major version number.

   102

 */

   103

#define ECRT_VER_MAJOR 1

   104

   105

/** EtherCAT real-time interface minor version number.

   106

 */

   107

#define ECRT_VER_MINOR 4

   108

   109

/** EtherCAT real-time interface version word generator.

   110

 */

   111

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

   112

   113

/** EtherCAT real-time interface version word.

   114

 */

   115

#define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR)

   116

   117

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

   118

 * Data types 

   119

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

   120

   121

struct ec_master;

   122

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

   123

   124

struct ec_slave_config;

   125

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

   126

   127

struct ec_domain;

   128

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

   129

   130

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

   131

   132

/** Bus state.

   133

 *

   134

 * This is used in ec_master_state_t.

   135

 */

   136

typedef enum {

   137

    EC_BUS_FAILURE = -1, /**< At least one configured slave is offline. */

   138

    EC_BUS_OK            /**< All configured slaves are online. */

   139

} ec_bus_state_t;

   140

   141

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

   142

   143

/** Master state.

   144

 *

   145

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

   146

 */

   147

typedef struct {

   148

    ec_bus_state_t bus_state; /**< \see ec_bus_state_t */

   149

    unsigned int bus_tainted; /**< Non-zero, if the bus topology differs from

   150

                                the requested configuration. */

   151

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

   152

} ec_master_state_t;

   153

   154

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

   155

   156

/** Slave configuration state.

   157

 *

   158

 * \see ecrt_slave_config_state().

   159

 */

   160

typedef struct  {

   161

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

   162

    unsigned int configured : 1; /**< The slave was configured according to

   163

                                   the specified configuration. */

   164

} ec_slave_config_state_t;

   165

   166

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

   167

   168

/** Domain working counter interpretation.

   169

 *

   170

 * This is used in ec_domain_state_t.

   171

 */

   172

typedef enum {

   173

    EC_WC_ZERO = 0,   /**< No Pdos were exchanged. */

   174

    EC_WC_INCOMPLETE, /**< Some of the registered Pdos were exchanged. */

   175

    EC_WC_COMPLETE    /**< All registered Pdos were exchanged. */

   176

} ec_wc_state_t;

   177

   178

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

   179

   180

/** Domain state.

   181

 *

   182

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

   183

 */

   184

typedef struct {

   185

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

   186

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

   187

} ec_domain_state_t;

   188

   189

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

   190

   191

/** Direction type for Pdo mapping functions.

   192

 */

   193

typedef enum {

   194

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

   195

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

   196

} ec_direction_t;

   197

   198

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

   199

   200

/** Pdo entry mapping.

   201

 *

   202

 * \see ecrt_slave_config_mapping().

   203

 */

   204

typedef struct {

   205

    uint16_t index; /**< Index of the Pdo entry to add to the Pdo

   206

                            configuration. */

   207

    uint8_t subindex; /**< Subindex of the Pdo entry to add to the

   208

                              Pdo configuration. */

   209

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

   210

} ec_pdo_entry_info_t;

   211

   212

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

   213

   214

/** Pdo information.

   215

 *

   216

 * \see ecrt_slave_config_mapping().

   217

 */

   218

typedef struct {

   219

    ec_direction_t dir; /**< Pdo direction (input/output). */

   220

    uint16_t index; /**< Index of the Pdo to map. */

   221

    unsigned int n_entries; /**< Number of Pdo entries for the Pdo

   222

                              configuration. Zero means, that the default Pdo

   223

                              configuration shall be used. */

   224

    const ec_pdo_entry_info_t *entries; /**< Pdo configuration array. This

   225

                                          array must contain at least \a

   226

                                          n_entries values. */

   227

} ec_pdo_info_t;

   228

   229

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

   230

   231

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

   232

 *

   233

 * This type is used for the array parameter of the

   234

 * ecrt_domain_reg_pdo_entry_list() convenience function.

   235

 */

   236

typedef struct {

   237

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

   238

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

   239

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

   240

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

   241

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

   242

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

   243

    uint8_t *offset; /**< Pointer to a variable to store the Pdo's

   244

                       offset in the process data. */

   245

} ec_pdo_entry_reg_t;

   246

   247

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

   248

 * Global functions

   249

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

   250

   251

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

   252

 *

   253

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

   254

 */

   255

unsigned int ecrt_version_magic(void);

   256

   257

/** Requests an EtherCAT master for realtime operation.

   258

 * 

   259

 * \return pointer to reserved master, or NULL on error

   260

 */

   261

ec_master_t *ecrt_request_master(

   262

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

   263

        );

   264

   265

/** Releases a requested EtherCAT master.

   266

 */

   267

void ecrt_release_master(

   268

        ec_master_t *master /**< EtherCAT master */

   269

        );

   270

   271

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

   272

 * Master methods

   273

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

   274

   275

/** Sets the locking callbacks.

   276

 *

   277

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

   278

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

   279

 * that access is forbidden at this time.

   280

 */

   281

void ecrt_master_callbacks(

   282

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

   283

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

   284

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

   285

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

   286

        );

   287

   288

/** Creates a new domain.

   289

 *

   290

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

   291

 */

   292

ec_domain_t *ecrt_master_create_domain(

   293

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

   294

        );

   295

   296

/** Obtains a slave configuration.

   297

 *

   298

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

   299

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

   300

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

   301

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

   302

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

   303

 *

   304

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

   305

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

   306

 *   ring position.

   307

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

   308

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

   309

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

   310

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

   311

 *

   312

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

   313

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

   314

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

   315

 *

   316

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

   317

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

   318

 * applied.

   319

 *

   320

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

   321

 * \retval NULL in the error case.

   322

 */

   323

ec_slave_config_t *ecrt_master_slave_config(

   324

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

   325

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

   326

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

   327

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

   328

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

   329

        );

   330

   331

/** Applies the bus configuration and switches to realtime mode.

   332

 *

   333

 * Does the complete configuration and activation for all slaves. Sets sync

   334

 * managers and FMMUs, and does the appropriate transitions, until the slave

   335

 * is operational.

   336

 *

   337

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

   338

 */

   339

int ecrt_master_activate(

   340

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

   341

        );

   342

   343

/** Sends all datagrams in the queue.

   344

 *

   345

 * \todo doc

   346

 */

   347

void ecrt_master_send(

   348

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

   349

        );

   350

   351

/** Fetches received frames from the hardware and processes the datagrams.

   352

 */

   353

void ecrt_master_receive(

   354

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

   355

        );

   356

   357

/** Reads the current master state.

   358

 *

   359

 * Stores the master state information in the given \a state structure.

   360

 */

   361

void ecrt_master_state(

   362

        const ec_master_t *master, /**< EtherCAT master. */

   363

        ec_master_state_t *state /**< Structure to store the information. */

   364

        );

   365

   366

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

   367

 * Slave configuration methods

   368

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

   369

   370

/** Specify the Pdo mapping and (optionally) the Pdo configuration.

   371

 *

   372

 * The following example shows, how to specify a complete Pdo mapping

   373

 * including the Pdo configuration. With this information, the master is able

   374

 * to reserve the complete process data, even if the slave is not present

   375

 * at configuration time:

   376

 *

   377

 * \code

   378

 * const ec_pdo_info_t complete_mapping[] = {

   379

 *     {EC_DIR_INPUT, 0x1600, 2, { // channel 1

   380

 *         {0x7000, 0, 16}, // value

   381

 *         {0x7000, 1, 8},  // status

   382

 *     }},

   383

 *     {EC_DIR_INPUT, 0x1601, 2, { // channel 2 

   384

 *         {0x7001, 0, 16}, // value

   385

 *         {0x7001, 1, 8},  // status

   386

 *     }}

   387

 * };

   388

 * 

   389

 * if (ecrt_slave_config_mapping(slave_config_ana_in, 2, complete_mapping)) {

   390

 *     // error

   391

 * }

   392

 * \endcode

   393

 *

   394

 * The next example shows, how to configure only the Pdo mapping. The entries

   395

 * for each mapped Pdo are taken from the default Pdo configuration. Please

   396

 * note, that Pdo entry registration will fail, if no Pdo configuration is

   397

 * specified and the slave is offline.

   398

 *

   399

 * \code

   400

 * const ec_pdo_info_t pdo_mapping[] = {

   401

 *     {EC_DIR_INPUT, 0x1600}, // Channel 1

   402

 *     {EC_DIR_INPUT, 0x1601}  // Channel 2

   403

 * };

   404

 * 

   405

 * if (ecrt_slave_config_mapping(slave_config_ana_in, 2, pdo_mapping)) {

   406

 *     // error

   407

 * }

   408

 * \endcode

   409

 *

   410

 * \return zero on success, else non-zero

   411

 */

   412

int ecrt_slave_config_mapping(

   413

        ec_slave_config_t *sc, /**< Slave configuration. */

   414

        unsigned int n_entries, /**< Number of Pdos in \a pdos to map. */

   415

        const ec_pdo_info_t pdos[] /**< List with Pdo mapping. */

   416

        );

   417

   418

/** Add a configuration value for an 8-bit SDO.

   419

 *

   420

 * \todo doc

   421

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

   422

 */

   423

int ecrt_slave_config_sdo8(

   424

        ec_slave_config_t *sc, /**< Slave configuration */

   425

        uint16_t sdo_index, /**< Index of the SDO to configure. */

   426

        uint8_t sdo_subindex, /**< Subindex of the SDO to configure. */

   427

        uint8_t value /**< Value to set. */

   428

        );

   429

   430

/** Add a configuration value for a 16-bit SDO.

   431

 *

   432

 * \todo doc

   433

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

   434

 */

   435

int ecrt_slave_config_sdo16(

   436

        ec_slave_config_t *sc, /**< Slave configuration */

   437

        uint16_t sdo_index, /**< Index of the SDO to configure. */

   438

        uint8_t sdo_subindex, /**< Subindex of the SDO to configure. */

   439

        uint16_t value /**< Value to set. */

   440

        );

   441

   442

/** Add a configuration value for a 32-bit SDO.

   443

 *

   444

 * \todo doc

   445

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

   446

 */

   447

int ecrt_slave_config_sdo32(

   448

        ec_slave_config_t *sc, /**< Slave configuration */

   449

        uint16_t sdo_index, /**< Index of the SDO to configure. */

   450

        uint8_t sdo_subindex, /**< Subindex of the SDO to configure. */

   451

        uint32_t value /**< Value to set. */

   452

        );

   453

   454

/** Outputs the state of the slave configuration.

   455

 *

   456

 * Stores the state information in the given \a state structure.

   457

 */

   458

void ecrt_slave_config_state(

   459

        const ec_slave_config_t *sc, /**< Slave configuration */

   460

        ec_slave_config_state_t *state /**< State object to write to. */

   461

        );

   462

   463

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

   464

 * Domain methods

   465

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

   466

   467

/** Registers a single Pdo entry for a domain.

   468

 *

   469

 * \return On success, the function returns the offset in the domain's process

   470

 *         data, which can be zero or greater. On failure, it returns a value

   471

 *         less than zero.

   472

 */

   473

   474

int ecrt_domain_reg_pdo_entry(

   475

        ec_domain_t *domain, /**< Domain. */

   476

        ec_slave_config_t *sc, /**< Slave configuration. */

   477

        uint16_t entry_index, /**< Index of the Pdo entry to register. */

   478

        uint8_t entry_subindex /**< Subindex of the Pdo entry to register. */

   479

        );

   480

   481

/** Registers a bunch of Pdo entries for a domain.

   482

 *

   483

 * \todo doc

   484

 * \attention The registration array has to be terminated with an empty

   485

 *            structure, or one with the \a index field set to zero!

   486

 * \return 0 on success, else non-zero.

   487

 */

   488

int ecrt_domain_reg_pdo_entry_list(

   489

        ec_domain_t *domain, /**< Domain. */

   490

        const ec_pdo_entry_reg_t *pdo_entry_regs /**< Array of Pdo

   491

                                                   registrations. */

   492

        );

   493