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 due to alias/position addressing.

    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

    59

 *   ecrt_domain_external_memory().

    60

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

    61

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

    62

 *   ecrt_slave_config_reg_pdo_entry(). This was necessary for the external

    63

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

    64

 *   is directly usable. If the domain's process data is allocated internally,

    65

 *   the start address can be retrieved with ecrt_domain_data().

    66

 * - Replaced ecrt_slave_pdo_mapping/add/clear() with

    67

 *   ecrt_slave_config_pdo() to add a Pdo to the mapping and

    68

 *   ecrt_slave_config_pdo_entry() to add a Pdo entry to a Pdo configuration.

    69

 *   ecrt_slave_config_mapping() is a convenience function for

    70

 *   both, that uses the new data types ec_pdo_info_t and ec_pdo_entry_info_t.

    71

 *   Mapped Pdo entries can now immediately be registered.

    72

 * - Renamed ec_bus_status_t, ec_master_status_t to ec_bus_state_t and

    73

 *   ec_master_state_t, respectively. Renamed ecrt_master_get_status() to

    74

 *   ecrt_master_state(), for consistency reasons.

    75

 * - Added ec_domain_state_t and ec_wc_state_t for a new output parameter

    76

 *   of ecrt_domain_state(). The domain state object does now contain

    77

 *   information, if the process data was exchanged completely.

    78

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

    79

 *   renamed ec_pdo_reg_t to ec_pdo_entry_reg_t and ecrt_domain_register_pdo()

    80

 *   to ecrt_slave_config_reg_pdo_entry().

    81

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

    82

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

    83

 *   Pdo entries.

    84

 *

    85

 * @{

    86

 */

    87

    88

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

    89

    90

#ifndef __ECRT_H__

    91

#define __ECRT_H__

    92

    93

#include <asm/byteorder.h>

    94

    95

#ifdef __KERNEL__

    96

#include <linux/types.h>

    97

#else

    98

#include <stdint.h>

    99

#endif

   100

   101

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

   102

 * Global definitions

   103

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

   104

   105

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

   106

 */

   107

#define ECRT_VER_MAJOR 1

   108

   109

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

   110

 */

   111

#define ECRT_VER_MINOR 4

   112

   113

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

   114

 */

   115

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

   116

   117

/** EtherCAT real-time interface version word.

   118

 */

   119

#define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR)

   120

   121

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

   122

 * Data types 

   123

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

   124

   125

struct ec_master;

   126

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

   127

   128

struct ec_slave_config;

   129

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

   130

   131

struct ec_domain;

   132

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

   133

   137

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

   138

   139

/** Bus state.

   140

 *

   141

 * This is used in ec_master_state_t.

   142

 */

   143

typedef enum {

   144

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

   145

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

   146

} ec_bus_state_t;

   147

   148

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

   149

   150

/** Master state.

   151

 *

   152

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

   153

 */

   154

typedef struct {

   155

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

   156

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

   157

                                the requested configuration. */

   158

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

   159

} ec_master_state_t;

   160

   161

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

   162

   163

/** Slave configuration state.

   164

 *

   165

 * \see ecrt_slave_config_state().

   166

 */

   167

typedef struct  {

   168

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

   169

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

   170

                                   the specified configuration. */

   171

} ec_slave_config_state_t;

   172

   173

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

   174

   175

/** Domain working counter interpretation.

   176

 *

   177

 * This is used in ec_domain_state_t.

   178

 */

   179

typedef enum {

   180

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

   181

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

   182

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

   183

} ec_wc_state_t;

   184

   185

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

   186

   187

/** Domain state.

   188

 *

   189

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

   190

 */

   191

typedef struct {

   192

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

   193

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

   194

} ec_domain_state_t;

   195

   196

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

   197

   198

/** Direction type for Pdo mapping functions.

   199

 */

   200

typedef enum {

   201

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

   202

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

   203

} ec_direction_t;

   204

   205

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

   206

   207

/** Pdo entry mapping.

   208

 *

   209

 * \see ecrt_slave_config_mapping().

   210

 */

   211

typedef struct {

   212

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

   213

                            configuration. */

   214

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

   215

                              Pdo configuration. */

   216

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

   217

} ec_pdo_entry_info_t;

   218

   219

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

   220

   221

/** Pdo information.

   222

 *

   223

 * \see ecrt_slave_config_mapping().

   224

 */

   225

typedef struct {

   226

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

   227

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

   228

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

   229

                              configuration. Zero means, that the default Pdo

   230

                              configuration shall be used. */

   231

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

   232

                                    array must contain at least \a

   233

                                    n_entries values. */

   234

} ec_pdo_info_t;

   235

   236

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

   237

   238

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

   239

 *

   240

 * This type is used for the array parameter of the

   241

 * ecrt_domain_reg_pdo_entry_list() convenience function.

   242

 */

   243

typedef struct {

   244

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

   245

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

   246

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

   247

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

   248

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

   249

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

   250

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

   251

                       offset in the process data. */

   252

} ec_pdo_entry_reg_t;

   253

   276

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

   277

 * Global functions

   278

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

   279

   280

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

   281

 *

   282

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

   283

 */

   284

unsigned int ecrt_version_magic(void);

   285

   286

/** Requests an EtherCAT master for realtime operation.

   287

 * 

   288

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

   289

 */

   290

ec_master_t *ecrt_request_master(

   291

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

   292

        );

   293

   294

/** Releases a requested EtherCAT master.

   295

 */

   296

void ecrt_release_master(

   297

        ec_master_t *master /**< EtherCAT master */

   298

        );

   299

   300

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

   301

 * Master methods

   302

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

   303

   304

/** Sets the locking callbacks.

   305

 *

   306

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

   307

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

   308

 * that access is forbidden at this time.

   309

 */

   310

void ecrt_master_callbacks(

   311

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

   312

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

   313

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

   314

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

   315

        );

   316

   317

/** Creates a new domain.

   318

 *

   319

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

   320

 */

   321

ec_domain_t *ecrt_master_create_domain(

   322

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

   323

        );

   324

   325

/** Obtains a slave configuration.

   326

 *

   327

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

   328

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

   329

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

   330

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

   331

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

   332

 *

   333

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

   334

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

   335

 *   ring position.

   336

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

   337

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

   338

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

   339

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

   340

 *

   341

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

   342

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

   343

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

   344

 *

   345

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

   346

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

   347

 * applied.

   348

 *

   349

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

   350

 * \retval NULL in the error case.

   351

 */

   352

ec_slave_config_t *ecrt_master_slave_config(

   353

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

   354

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

   355

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

   356

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

   357

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

   358

        );

   359

   360

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

   361

 *

   362

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

   363

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

   364

 * is operational.

   365

 *

   366

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

   367

 */

   368

int ecrt_master_activate(

   369

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

   370

        );

   371

   372

/** Sends all datagrams in the queue.

   373

 *

   374

 * \todo doc

   375

 */

   376

void ecrt_master_send(

   377

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

   378

        );

   379

   380

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

   381

 */

   382

void ecrt_master_receive(

   383

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

   384

        );

   385

   386

/** Reads the current master state.

   387

 *

   388

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

   389

 */

   390

void ecrt_master_state(

   391

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

   392

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

   393

        );

   394

   395

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

   396

 * Slave configuration methods

   397

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

   398

   399

/** Add a Pdo to the slave's Pdo mapping for the given direction.

   400

 *

   401

 * The first call of this function for a given \a dir will clear the default

   402

 * mapping.

   403

 *

   404

 * \see ecrt_slave_config_mapping()

   405

 * \return zero on success, else non-zero

   406

 */

   407

int ecrt_slave_config_pdo(

   408

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

   409

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

   410

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

   411

        );

   412

   413

/** Add a Pdo entry to the given Pdo's configuration.

   414

 *

   415

 * The first call of this function for a given \a pdo_index will clear the

   416

 * default Pdo configuration.

   417

 *

   418

 * \see ecrt_slave_config_mapping()

   419

 * \return zero on success, else non-zero

   420

 */

   421

int ecrt_slave_config_pdo_entry(

   422

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

   423

        uint16_t pdo_index, /**< Index of the Pdo to configure. */

   424

        uint16_t entry_index, /**< Index of the Pdo entry to add to the Pdo's

   425

                                configuration. */

   426

        uint8_t entry_subindex, /**< Subindex of the Pdo entry to add to the

   427

                                  Pdo's configuration. */

   428

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

   429

        );

   430

   431

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

   432

 *

   433

 * This function is a convenience function for the ecrt_slave_config_pdo()

   434

 * and ecrt_slave_config_pdo_entry() functions, that are better suitable

   435

 * for automatic code generation.

   436

 *

   437

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

   438

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

   439

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

   440

 * at configuration time:

   441

 *

   442

 * \code

   443

 * const ec_pdo_entry_info_t el3162_channel1[] = {

   444

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

   445

 *     {0x3101, 2, 16}  // value

   446

 * };

   447

 * 

   448

 * const ec_pdo_entry_info_t el3162_channel2[] = {

   449

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

   450

 *     {0x3102, 2, 16}  // value

   451

 * };

   452

 * 

   453

 * const ec_pdo_info_t el3162_mapping[] = {

   454

 *     {EC_DIR_INPUT, 0x1A00, 2, el3162_channel1},

   455

 *     {EC_DIR_INPUT, 0x1A01, 2, el3162_channel2},

   456

 * };

   457

 * 

   458

 * if (ecrt_slave_config_mapping(sc, 2, el3162_mapping))

   459

 *     return -1; // error

   460

 * \endcode

   461

 *

   462

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

   463

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

   464

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

   465

 * left empty and the slave is offline.

   466

 *

   467

 * \code

   468

 * const ec_pdo_info_t pdo_mapping[] = {

   469

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

   470

 *     {EC_DIR_INPUT, 0x1601}  // Channel 2

   471

 * };

   472

 * 

   473

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

   474

 *     return -1; // error

   475

 * \endcode

   476

 *

   477

 * \return zero on success, else non-zero

   478

 */

   479

int ecrt_slave_config_mapping(

   480

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

   481

        unsigned int n_infos, /**< Number of Pdo infos in \a pdo_infos. */

   482

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

   483

        );

   484

   485

/** Registers a Pdo entry for process data exchange in a domain.

   486

 *

   487

 * Searches the current mapping and Pdo configurations for the given Pdo

   488

 * entry. An error is raised, if the given entry is not mapped. Otherwise, the

   489

 * corresponding sync manager and FMMU configurations are provided for slave

   490

 * configuration and the respective sync manager's Pdos are appended to the

   491

 * given domain, if not already done. The offset of the requested Pdo entry's

   492