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

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

    61

 *   functions with a process data offset, that is now returned either byte-

    62

 *   or bitwise by ecrt_slave_config_reg_pdo_entry() or

    63

 *   ecrt_slave_config_reg_pdo_entry_bitwise(), respectively. This was

    64

 *   necessary for the external domain memory. An additional advantage is,

    65

 *   that the returned offset is immediately valid. If the domain's

    66

 *   process data is allocated internally, the start address can be retrieved

    67

 *   with ecrt_domain_data().

    68

 * - Replaced ecrt_slave_pdo_mapping/add/clear() with

    69

 *   ecrt_slave_config_pdo_assign_add() to add a Pdo to a sync manager's Pdo

    70

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

    71

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

    72

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

    73

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

    74

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

    75

 * - Renamed ec_bus_status_t, ec_master_status_t to ec_bus_state_t and

    76

 *   ec_master_state_t, respectively. Renamed ecrt_master_get_status() to

    77

 *   ecrt_master_state(), for consistency reasons.

    78

 * - Added ec_domain_state_t and ec_wc_state_t for a new output parameter

    79

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

    80

 *   information, if the process data was exchanged completely.

    81

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

    82

 *   renamed ec_pdo_reg_t to ec_pdo_entry_reg_t and ecrt_domain_register_pdo()

    83

 *   to ecrt_slave_config_reg_pdo_entry().

    84

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

    85

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

    86

 *   Pdo entries.

    87

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

    88

 *   scheduled for reading and writing during realtime operation.

    89

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

    90

 * - Removed the bus_state and bus_tainted flags from ec_master_state_t.

    91

 *

    92

 * @{

    93

 */

    94

    95

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

    96

    97

#ifndef __ECRT_H__

    98

#define __ECRT_H__

    99

   100

#include <asm/byteorder.h>

   101

   102

#ifdef __KERNEL__

   103

#include <linux/types.h>

   104

#else

   105

#include <stdint.h>

   106

#endif

   107

   108

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

   109

 * Global definitions

   110

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

   111

   112

/** EtherCAT realtime interface major version number.

   113

 */

   114

#define ECRT_VER_MAJOR 1

   115

   116

/** EtherCAT realtime interface minor version number.

   117

 */

   118

#define ECRT_VER_MINOR 4

   119

   120

/** EtherCAT realtime interface version word generator.

   121

 */

   122

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

   123

   124

/** EtherCAT realtime interface version word.

   125

 */

   126

#define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR)

   127

   128

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

   129

   130

/** End of the Pdo list.

   131

 *

   132

 * This is used in ecrt_slave_config_pdos().

   133

 */

   134

#define EC_END ~0U

   135

   136

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

   137

 * Data types 

   138

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

   139

   140

struct ec_master;

   141

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

   142

   143

struct ec_slave_config;

   144

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

   145

   146

struct ec_domain;

   147

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

   148

   149

struct ec_sdo_request;

   150

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

   151

   152

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

   153

   154

/** Master state.

   155

 *

   156

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

   157

 */

   158

typedef struct {

   159

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

   160

} ec_master_state_t;

   161

   162

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

   163

   164

/** Slave configuration state.

   165

 *

   166

 * \see ecrt_slave_config_state().

   167

 */

   168

typedef struct  {

   169

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

   170

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

   171

                                   the specified configuration. */

   172

} ec_slave_config_state_t;

   173

   174

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

   175

   176

/** Domain working counter interpretation.

   177

 *

   178

 * This is used in ec_domain_state_t.

   179

 */

   180

typedef enum {

   181

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

   182

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

   183

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

   184

} ec_wc_state_t;

   185

   186

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

   187

   188

/** Domain state.

   189

 *

   190

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

   191

 */

   192

typedef struct {

   193

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

   194

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

   195

} ec_domain_state_t;

   196

   197

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

   198

   199

/** Direction type for Pdo mapping functions.

   200

 */

   201

typedef enum {

   202

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

   203

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

   204

} ec_direction_t;

   205

   206

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

   207

   208

/** Pdo entry information.

   209

 *

   210

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

   211

 * ecrt_slave_config_pdos().

   212

 */

   213

typedef struct {

   214

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

   215

                            configuration. */

   216

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

   217

                              Pdo configuration. */

   218

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

   219

} ec_pdo_entry_info_t;

   220

   221

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

   222

   223

/** Pdo information.

   224

 *

   225

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

   226

 * ecrt_slave_config_pdos().

   227

 */

   228

typedef struct {

   229

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

   230

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

   231

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

   232

                              Zero means, that the default mapping shall be

   233

                              used. */

   234

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

   235

                                    contain at least \a n_entries values. */

   236

} ec_pdo_info_t;

   237

   238

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

   239

   240

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

   241

 *

   242

 * This type is used for the array parameter of the

   243

 * ecrt_domain_reg_pdo_entry_list() and

   244

 * ecrt_domain_reg_pdo_entry_list_bitwise() convenience functions.

   245

 */

   246

typedef struct {

   247

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

   248

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

   249

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

   250

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

   251

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

   252

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

   253

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

   254

                       offset in the process data. This can either be byte-

   255

                       or bitwise, depending on whether

   256

                       ecrt_domain_reg_pdo_entry_list() or

   257

                       ecrt_domain_reg_pdo_entry_list_bitwise() was called. */

   258

} ec_pdo_entry_reg_t;

   259

   260

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

   261

   262

/** Sdo request state.

   263

 *

   264

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

   265

 */

   266

typedef enum {

   267

    EC_SDO_REQUEST_UNUSED, /**< Not requested. */

   268

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

   269

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

   270

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

   271

} ec_sdo_request_state_t;

   272

   273

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

   274

 * Global functions

   275

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

   276

   277

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

   278

 *

   279

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

   280

 */

   281

unsigned int ecrt_version_magic(void);

   282

   283

/** Requests an EtherCAT master for realtime operation.

   284

 * 

   285

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

   286

 */

   287

ec_master_t *ecrt_request_master(

   288

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

   289

        );

   290

   291

/** Releases a requested EtherCAT master.

   292

 */

   293

void ecrt_release_master(

   294

        ec_master_t *master /**< EtherCAT master */

   295

        );

   296

   297

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

   298

 * Master methods

   299

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

   300

   301

/** Sets the locking callbacks.

   302

 *

   303

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

   304

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

   305

 * that access is forbidden at this time.

   306

 */

   307

void ecrt_master_callbacks(

   308

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

   309

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

   310

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

   311

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

   312

        );

   313

   314

/** Creates a new domain.

   315

 *

   316

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

   317

 */

   318

ec_domain_t *ecrt_master_create_domain(

   319

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

   320

        );

   321

   322

/** Obtains a slave configuration.

   323

 *

   324

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

   325

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

   326

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

   327

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

   328

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

   329

 *

   330

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

   331

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

   332

 *   ring position.

   333

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

   334

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

   335

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

   336

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

   337

 *

   338

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

   339

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

   340

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

   341

 *

   342

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

   343

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

   344

 * applied.

   345

 *

   346

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

   347

 * \retval NULL in the error case.

   348

 */

   349

ec_slave_config_t *ecrt_master_slave_config(

   350

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

   351

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

   352

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

   353

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

   354

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

   355

        );

   356

   357

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

   358

 *

   359

 * This function has to be called after all Pdo entries are registered. It

   360

 * tells the master that the configuration phase is finished and the realtime

   361

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

   362

 * domains and calculates the logical FMMU addresses for domain members. It

   363

 * tells the master state machine that the bus configuration is now to be

   364

 * applied.

   365

 *

   366

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

   367

 * in charge of cyclically calling ecrt_master_send() and

   368

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

   369

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

   370

 * not be called!

   371

 *

   372

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

   373

 */

   374

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

   375

   376

/** Sends all datagrams in the queue.

   377

 *

   378

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

   379

 * ecrt_master_activate() has returned.

   380

 */

   381

void ecrt_master_send(

   382

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

   383

        );

   384

   385

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

   386

 *

   387

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

   388

 * ecrt_master_activate() has returned.

   389

 */

   390

void ecrt_master_receive(

   391

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

   392

        );

   393

   394

/** Reads the current master state.

   395

 *

   396

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

   397

 */

   398

void ecrt_master_state(

   399

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

   400

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

   401

        );

   402

   403

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

   404

 * Slave configuration methods

   405

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

   406

   407

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

   408

 *

   409

 * \see ecrt_slave_config_pdos()

   410

 * \return zero on success, else non-zero

   411

 */

   412

int ecrt_slave_config_pdo_assign_add(

   413

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

   414

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

   415

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

   416

        );

   417

   418

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

   419

 *

   420

 * This can be called before assigning Pdos via

   421

 * ecrt_slave_config_pdo_assign_add(), to clear the default assignment.

   422

 */

   423

void ecrt_slave_config_pdo_assign_clear(

   424

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

   425

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

   426

        );

   427

   428

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

   429

 *

   430

 * \see ecrt_slave_config_pdos()

   431

 * \return zero on success, else non-zero

   432

 */

   433

int ecrt_slave_config_pdo_mapping_add(

   434

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

   435

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

   436

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

   437

                                mapping. */

   438

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

   439

                                  Pdo's mapping. */

   440

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

   441

        );

   442

   443

/** Clear the mapping of a given Pdo.

   444

 *

   445

 * This can be called before mapping Pdo entries via

   446

 * ecrt_slave_config_pdo_mapping_add(), to clear the default mapping.

   447

 */

   448

void ecrt_slave_config_pdo_mapping_clear(

   449

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

   450

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

   451

        );

   452

   453

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

   454

 *

   455

 * This function is a convenience wrapper for the functions

   456

 * ecrt_slave_config_pdo_assign_clear(), ecrt_slave_config_pdo_assign_add(),

   457

 * ecrt_slave_config_pdo_mapping_clear() and

   458

 * ecrt_slave_config_pdo_mapping_add(), that are better suitable for automatic

   459

 * code generation.

   460

 *

   461

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

   462

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

   463

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

   464

 * configuration time:

   465

 *

   466

 * \code

   467

 * const ec_pdo_entry_info_t el3162_channel1[] = {

   468

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

   469

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

   470

 * };

   471

 * 

   472

 * const ec_pdo_entry_info_t el3162_channel2[] = {

   473

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

   474

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

   475

 * };

   476

 * 

   477

 * const ec_pdo_info_t el3162_pdos[] = {

   478

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

   479

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

   480

 * };

   481

 * 

   482

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

   483

 *     return -1; // error

   484

 * \endcode

   485

 * 

   486

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

   487

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

   488

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

   489

 * configuration is left empty and the slave is offline.