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 Realtime Interface.

    37

 *

    38

 * \defgroup RealtimeInterface EtherCAT Realtime Interface

    39

 *

    40

 * EtherCAT interface for realtime applications. This interface is designed

    41

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

    42

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

    43

 * and to 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

 * - Pdo entry registration functions do not return a process data pointer,

    61

 *   but an offset in the domain's process data. In addition, an optional bit

    62

 *   position can be requested. This was necessary for the external domain

    63

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

    64

 *   immediately valid. 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_assign_add() to add a Pdo to a sync manager's Pdo

    68

 *   assignment and ecrt_slave_config_pdo_mapping_add() to add a Pdo entry to a

    69

 *   Pdo's mapping. ecrt_slave_config_pdos() is a convenience function

    70

 *   for both, that uses the new data types ec_pdo_info_t and

    71

 *   ec_pdo_entry_info_t. Pdo entries, that are mapped with these functions

    72

 *   can now immediately be registered, even if the bus is offline.

    73

 * - Renamed ec_bus_status_t, ec_master_status_t to ec_bus_state_t and

    74

 *   ec_master_state_t, respectively. Renamed ecrt_master_get_status() to

    75

 *   ecrt_master_state(), for consistency reasons.

    76

 * - Added ec_domain_state_t and ec_wc_state_t for a new output parameter

    77

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

    78

 *   information, if the process data was exchanged completely.

    79

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

    80

 *   renamed ec_pdo_reg_t to ec_pdo_entry_reg_t and ecrt_domain_register_pdo()

    81

 *   to ecrt_slave_config_reg_pdo_entry().

    82

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

    83

 *   be reached by specifying an explicit Pdo assignment/mapping and

    84

 *   registering the mapped Pdo entries.

    85

 * - Added an Sdo access interface, working with Sdo requests. These can be

    86

 *   scheduled for reading and writing during realtime operation.

    87

 * - Exported ecrt_slave_config_sdo(), the generic Sdo configuration function.

    88

 * - Removed the bus_state and bus_tainted flags from ec_master_state_t.

    89

 *

    90

 * @{

    91

 */

    92

    93

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

    94

    95

#ifndef __ECRT_H__

    96

#define __ECRT_H__

    97

    98

#include <asm/byteorder.h>

    99

   100

#ifdef __KERNEL__

   101

#include <linux/types.h>

   102

#else

   103

#include <stdint.h>

   104

#endif

   105

   106

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

   107

 * Global definitions

   108

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

   109

   110

/** EtherCAT realtime interface major version number.

   111

 */

   112

#define ECRT_VER_MAJOR 1

   113

   114

/** EtherCAT realtime interface minor version number.

   115

 */

   116

#define ECRT_VER_MINOR 4

   117

   118

/** EtherCAT realtime interface version word generator.

   119

 */

   120

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

   121

   122

/** EtherCAT realtime interface version word.

   123

 */

   124

#define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR)

   125

   126

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

   127

   128

/** End of the Pdo entry list.

   129

 *

   130

 * This is used in ecrt_slave_config_pdos().

   131

 */

   132

#define EC_END ~0U

   133

   134

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

   135

 * Data types 

   136

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

   137

   138

struct ec_master;

   139

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

   140

   141

struct ec_slave_config;

   142

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

   143

   144

struct ec_domain;

   145

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

   146

   147

struct ec_sdo_request;

   148

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

   149

   150

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

   151

   152

/** Master state.

   153

 *

   154

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

   155

 */

   156

typedef struct {

   157

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

   158

} ec_master_state_t;

   159

   160

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

   161

   162

/** Slave configuration state.

   163

 *

   164

 * \see ecrt_slave_config_state().

   165

 */

   166

typedef struct  {

   167

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

   168

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

   169

                                   the specified configuration. */

   170

} ec_slave_config_state_t;

   171

   172

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

   173

   174

/** Domain working counter interpretation.

   175

 *

   176

 * This is used in ec_domain_state_t.

   177

 */

   178

typedef enum {

   179

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

   180

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

   181

                        exchanged. */

   182

    EC_WC_COMPLETE    /**< All registered process data 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 assignment 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 information.

   208

 *

   209

 * This can be used to map multiple Pdo entries into a given Pdo using

   210

 * ecrt_slave_config_pdos().

   211

 */

   212

typedef struct {

   213

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

   214

                            mapping. */

   215

    uint8_t subindex; /**< Subindex of the Pdo entry. */

   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

 * This can be use to assign multiple Pdos to a sync manager using

   224

 * ecrt_slave_config_pdos().

   225

 */

   226

typedef struct {

   227

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

   228

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

   229

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

   230

                              Zero means, that the default mapping shall be

   231

                              used (this can only be done if the slave is

   232

                              present at bus configuration time). */

   233

    ec_pdo_entry_info_t *entries; /**< Array of Pdo entries to map. This must

   234

                                    contain at least \a n_entries values. */

   235

} ec_pdo_info_t;

   236

   237

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

   238

   239

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

   240

 *

   241

 * This type is used for the array parameter of the

   242

 * ecrt_domain_reg_pdo_entry_list()

   243

 */

   244

typedef struct {

   245

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

   246

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

   247

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

   248

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

   249

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

   250

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

   251

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

   252

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

   253

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

   254

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

   255

                                 NULL, in which case an error is raised if the

   256

                                 Pdo entry does not byte-align. */

   257

} ec_pdo_entry_reg_t;

   258

   259

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

   260

   261

/** Sdo request state.

   262

 *

   263

 * This is used as return type of ecrt_sdo_request_state().

   264

 */

   265

typedef enum {

   266

    EC_SDO_REQUEST_UNUSED, /**< Not requested. */

   267

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

   268

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

   269

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

   270

} ec_sdo_request_state_t;

   271

   272

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

   273

 * Global functions

   274

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

   275

   276

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

   277

 *

   278

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

   279

 */

   280

unsigned int ecrt_version_magic(void);

   281

   282

/** Requests an EtherCAT master for realtime operation.

   283

 * 

   284

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

   285

 */

   286

ec_master_t *ecrt_request_master(

   287

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

   288

        );

   289

   290

/** Releases a requested EtherCAT master.

   291

 */

   292

void ecrt_release_master(

   293

        ec_master_t *master /**< EtherCAT master */

   294

        );

   295

   296

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

   297

 * Master methods

   298

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

   299

   300

/** Sets the locking callbacks.

   301

 *

   302

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

   303

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

   304

 * that access is forbidden at this time.

   305

 */

   306

void ecrt_master_callbacks(

   307

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

   308

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

   309

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

   310

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

   311

        );

   312

   313

/** Creates a new domain.

   314

 *

   315

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

   316

 */

   317

ec_domain_t *ecrt_master_create_domain(

   318

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

   319

        );

   320

   321

/** Obtains a slave configuration.

   322

 *

   323

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

   324

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

   325

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

   326

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

   327

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

   328

 *

   329

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

   330

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

   331

 *   ring position.

   332

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

   333

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

   334

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

   335

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

   336

 *

   337

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

   338

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

   339

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

   340

 *

   341

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

   342

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

   343

 * applied.

   344

 *

   345

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

   346

 * \retval NULL in the error case.

   347

 */

   348

ec_slave_config_t *ecrt_master_slave_config(

   349

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

   350

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

   351

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

   352

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

   353

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

   354

        );

   355

   356

/** Finishes the configuration phase and prepares for realtime mode.

   357

 *

   358

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

   359

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

   360

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

   361

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

   362

 * now to be applied.

   363

 *

   364

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

   365

 * in charge of cyclically calling ecrt_master_send() and

   366

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

   367

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

   368

 * not be called!

   369

 *

   370

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

   371

 */

   372

int ecrt_master_activate( ec_master_t *master /**< EtherCAT master. */);

   373

   374

/** Sends all datagrams in the queue.

   375

 *

   376

 * This has to be called cyclically by the realtime application after

   377

 * ecrt_master_activate() has returned.

   378

 */

   379

void ecrt_master_send(

   380

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

   381

        );

   382

   383

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

   384

 *

   385

 * This has to be called cyclically by the realtime application after

   386

 * ecrt_master_activate() has returned.

   387

 */

   388

void ecrt_master_receive(

   389

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

   390

        );

   391

   392

/** Reads the current master state.

   393

 *

   394

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

   395

 */

   396

void ecrt_master_state(

   397

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

   398

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

   399

        );

   400

   401

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

   402

 * Slave configuration methods

   403

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

   404

   405

/** Add a Pdo to a sync manager's Pdo assignment.

   406

 *

   407

 * \see ecrt_slave_config_pdos()

   408

 * \return zero on success, else non-zero

   409

 */

   410

int ecrt_slave_config_pdo_assign_add(

   411

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

   412

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

   413

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

   414

        );

   415

   416

/** Clear a sync manager's Pdo assignment.

   417

 *

   418

 * This can be called before assigning Pdos via

   419

 * ecrt_slave_config_pdo_assign_add(), to clear the default assignment.

   420

 */

   421

void ecrt_slave_config_pdo_assign_clear(

   422

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

   423

        ec_direction_t dir /**< Sync manager direction (input/output). */

   424

        );

   425

   426

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

   427

 *

   428

 * \see ecrt_slave_config_pdos()

   429

 * \return zero on success, else non-zero

   430

 */

   431

int ecrt_slave_config_pdo_mapping_add(

   432

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

   433

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

   434

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

   435

                                mapping. */

   436

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

   437

                                  Pdo's mapping. */

   438

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

   439

        );

   440

   441

/** Clear the mapping of a given Pdo.

   442

 *

   443

 * This can be called before mapping Pdo entries via

   444

 * ecrt_slave_config_pdo_mapping_add(), to clear the default mapping.

   445

 */

   446

void ecrt_slave_config_pdo_mapping_clear(

   447

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

   448

        uint16_t pdo_index /**< Index of the Pdo. */

   449

        );

   450

   451

/** Specify the Pdo assignment and (optionally) the Pdo mappings.

   452

 *

   453

 * This function is a convenience wrapper for the functions

   454

 * ecrt_slave_config_pdo_assign_clear(), ecrt_slave_config_pdo_assign_add(),

   455

 * ecrt_slave_config_pdo_mapping_clear() and

   456

 * ecrt_slave_config_pdo_mapping_add(), that are better suitable for automatic

   457

 * code generation.

   458

 *

   459

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

   460

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

   461

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

   462

 * configuration time:

   463

 *

   464

 * \code

   465

 * const ec_pdo_entry_info_t el3162_channel1[] = {

   466

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

   467

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

   468

 * };

   469

 * 

   470

 * const ec_pdo_entry_info_t el3162_channel2[] = {

   471

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

   472

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

   473

 * };

   474

 * 

   475

 * const ec_pdo_info_t el3162_pdos[] = {

   476

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

   477

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

   478

 * };

   479

 * 

   480

 * if (ecrt_slave_config_pdos(sc, 2, el3162_pdos))

   481

 *     return -1; // error

   482

 * \endcode

   483

 * 

   484

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

   485

 * entries for each assigned Pdo are taken from the Pdo's default mapping.

   486

 * Please note, that Pdo entry registration will fail, if the Pdo

   487

 * configuration is left empty and the slave is offline.

   488

 *

   489