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.

     8

 *

     9

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

    10

 *  modify it under the terms of the GNU General Public License version 2, as

    11

 *  published by the Free Software Foundation.

    12

 *

    13

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

    14

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

    15

 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General

    16

 *  Public License for more details.

    17

 *

    18

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

    19

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

    20

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

    21

 *

    22

 *  Using the EtherCAT technology and brand is permitted in compliance with

    23

 *  the industrial property and similar rights of Beckhoff Automation GmbH.

    24

 *

    25

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

    26

    27

/** \file

    28

 *

    29

 * EtherCAT master application interface.

    30

 *

    31

 * \defgroup ApplicationInterface EtherCAT Application Interface

    32

 *

    33

 * EtherCAT interface for realtime applications. This interface is designed

    34

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

    35

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

    36

 * and to configure and activate the bus.

    37

 *

    38

 * Changes in Version 1.4:

    39

 *

    40

 * - Replaced ec_slave_t with ec_slave_config_t, separating the bus

    41

 *   configuration from the actual slaves. Therefore, renamed

    42

 *   ecrt_master_get_slave() to ecrt_master_slave_config().

    43

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

    44

 *   ecrt_master_slave_config().

    45

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

    46

 *   necessary due to alias/position addressing.

    47

 * - Added ec_slave_config_state_t for the new method

    48

 *   ecrt_slave_config_state().

    49

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

    50

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

    51

 *   added the domain methods ecrt_domain_size() and

    52

 *   ecrt_domain_external_memory().

    53

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

    54

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

    55

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

    56

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

    57

 *   immediately valid. If the domain's process data is allocated internally,

    58

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

    59

 * - Replaced ecrt_slave_pdo_mapping/add/clear() with

    60

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

    61

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

    62

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

    63

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

    64

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

    65

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

    66

 * - Renamed ec_bus_status_t, ec_master_status_t to ec_bus_state_t and

    67

 *   ec_master_state_t, respectively. Renamed ecrt_master_get_status() to

    68

 *   ecrt_master_state(), for consistency reasons.

    69

 * - Added ec_domain_state_t and #ec_wc_state_t for a new output parameter

    70

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

    71

 *   information, if the process data was exchanged completely.

    72

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

    73

 *   renamed ec_pdo_reg_t to ec_pdo_entry_reg_t and ecrt_domain_register_pdo()

    74

 *   to ecrt_slave_config_reg_pdo_entry().

    75

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

    76

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

    77

 *   registering the mapped PDO entries.

    78

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

    79

 *   scheduled for reading and writing during realtime operation.

    80

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

    81

 * - Removed the bus_state and bus_tainted flags from ec_master_state_t.

    82

 *

    83

 * @{

    84

 */

    85

    86

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

    87

    88

#ifndef __ECRT_H__

    89

#define __ECRT_H__

    90

    91

#include <asm/byteorder.h>

    92

    93

#ifdef __KERNEL__

    94

#include <linux/types.h>

    95

#else

    96

#include <stdint.h>

    97

#endif

    98

    99

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

   100

 * Global definitions

   101

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

   102

   103

/** EtherCAT realtime interface major version number.

   104

 */

   105

#define ECRT_VER_MAJOR 1

   106

   107

/** EtherCAT realtime interface minor version number.

   108

 */

   109

#define ECRT_VER_MINOR 4

   110

   111

/** EtherCAT realtime interface version word generator.

   112

 */

   113

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

   114

   115

/** EtherCAT realtime interface version word.

   116

 */

   117

#define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR)

   118

   119

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

   120

   121

/** End of list marker.

   122

 *

   123

 * This can be used with ecrt_slave_config_pdos().

   124

 */

   125

#define EC_END ~0U

   126

   127

/** Maximum number of sync managers per slave.

   128

 */

   129

#define EC_MAX_SYNC_MANAGERS 16

   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

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

   148

   149

/** Master state.

   150

 *

   151

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

   152

 *

   153

 * \see ecrt_master_state().

   154

 */

   155

typedef struct {

   156

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

   157

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

   158

                                  The states are coded in the lower 4 bits.

   159

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

   160

                                  slave in the bus is in the corresponding

   161

                                  state:

   162

                                  - Bit 0: \a INIT

   163

                                  - Bit 1: \a PREOP

   164

                                  - Bit 2: \a SAFEOP

   165

                                  - Bit 3: \a OP */

   166

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

   167

} ec_master_state_t;

   168

   169

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

   170

   171

/** Slave configuration state.

   172

 *

   173

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

   174

 * 

   175

 * \see ecrt_slave_config_state().

   176

 */

   177

typedef struct  {

   178

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

   179

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

   180

                                    using the specified configuration. */

   181

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

   182

                                 - 1: \a INIT

   183

                                 - 2: \a PREOP

   184

                                 - 4: \a SAFEOP

   185

                                 - 8: \a OP

   186

   187

                                 Note that each state is coded in a different

   188

                                 bit! */

   189

} ec_slave_config_state_t;

   190

   191

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

   192

   193

/** Domain working counter interpretation.

   194

 *

   195

 * This is used in ec_domain_state_t.

   196

 */

   197

typedef enum {

   198

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

   199

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

   200

                        exchanged. */

   201

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

   202

} ec_wc_state_t;

   203

   204

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

   205

   206

/** Domain state.

   207

 *

   208

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

   209

 */

   210

typedef struct {

   211

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

   212

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

   213

} ec_domain_state_t;

   214

   215

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

   216

   217

/** Direction type for PDO assignment functions.

   218

 */

   219

typedef enum {

   220

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

   221

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

   222

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

   223

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

   224

} ec_direction_t;

   225

   226

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

   227

   228

/** PDO entry configuration information.

   229

 *

   230

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

   231

 *

   232

 * \see ecrt_slave_config_pdos().

   233

 */

   234

typedef struct {

   235

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

   236

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

   237

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

   238

} ec_pdo_entry_info_t;

   239

   240

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

   241

   242

/** PDO configuration information.

   243

 * 

   244

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

   245

 * 

   246

 * \see ecrt_slave_config_pdos().

   247

 */

   248

typedef struct {

   249

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

   250

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

   251

                              Zero means, that the default mapping shall be

   252

                              used (this can only be done if the slave is

   253

                              present at bus configuration time). */

   254

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

   255

                                    be \a NULL, or must contain at

   256

                                    least \a n_entries values. */

   257

} ec_pdo_info_t;

   258

   259

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

   260

   261

/** Sync manager configuration information.

   262

 *

   263

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

   264

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

   265

 * ecrt_slave_config_pdos().

   266

 */

   267

typedef struct {

   268

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

   269

                     than #EC_MAX_SYNC_MANAGERS for a valid sync manager,

   270

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

   271

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

   272

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

   273

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

   274

                            at least \a n_pdos PDOs. */

   275

} ec_sync_info_t;

   276

   277

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

   278

   279

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

   280

 *

   281

 * This type is used for the array parameter of the

   282

 * ecrt_domain_reg_pdo_entry_list()

   283

 */

   284

typedef struct {

   285

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

   286

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

   287

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

   288

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

   289

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

   290

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

   291

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

   292

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

   293

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

   294

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

   295

                                  NULL, in which case an error is raised if the

   296

                                  PDO entry does not byte-align. */

   297

} ec_pdo_entry_reg_t;

   298

   299

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

   300

   301

/** SDO request state.

   302

 *

   303

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

   304

 */

   305

typedef enum {

   306

    EC_SDO_REQUEST_UNUSED, /**< Not requested. */

   307

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

   308

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

   309

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

   310

} ec_sdo_request_state_t;

   311

   312

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

   313

 * Global functions

   314

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

   315

   316

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

   317

 *

   318

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

   319

 */

   320

unsigned int ecrt_version_magic(void);

   321

   322

/** Requests an EtherCAT master for realtime operation.

   323

 * 

   324

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

   325

 * for exclusive use.

   326

 *

   327

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

   328

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

   329

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

   330

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

   331

 *

   332

 * \return Pointer to reserved master, or \a NULL on error.

   333

 */

   334

ec_master_t *ecrt_request_master(

   335

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

   336

        );

   337

   338

/** Releases a requested EtherCAT master.

   339

 *

   340

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

   341

 * applications.

   342

 */

   343

void ecrt_release_master(

   344

        ec_master_t *master /**< EtherCAT master */

   345

        );

   346

   347

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

   348

 * Master methods

   349

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

   350

   351

/** Sets the locking callbacks.

   352

 *

   353

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

   354

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

   355

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

   356

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

   357

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

   358

 *

   359

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

   360

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

   361

 * that access is currently forbidden.

   362

 */

   363

void ecrt_master_callbacks(

   364

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

   365

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

   366

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

   367

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

   368

        );

   369

   370

/** Creates a new process data domain.

   371

 *

   372

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

   373

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

   374

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

   375

 * exchanging them in cyclic operation.

   376

 *

   377

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

   378

 */

   379

ec_domain_t *ecrt_master_create_domain(

   380

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

   381

        );

   382

   383

/** Obtains a slave configuration.

   384

 *

   385

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

   386

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

   387

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

   388

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

   389

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

   390

 *

   391

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

   392

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

   393

 *   ring position.

   394

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

   395

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

   396

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

   397

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

   398

 *

   399

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

   400

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

   401

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

   402

 *

   403

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

   404

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

   405

 * applied.

   406

 *

   407

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

   408

 * \retval NULL in the error case.

   409

 */

   410

ec_slave_config_t *ecrt_master_slave_config(

   411

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

   412

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

   413

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

   414

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

   415

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

   416

        );

   417

   418

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

   419

 *

   420

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

   421

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

   422

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

   423

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

   424

 * now to be applied.

   425

 *

   426

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

   427

 * in charge of cyclically calling ecrt_master_send() and

   428

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

   429

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

   430

 * not be called!

   431

 *

   432

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

   433

 */

   434

int ecrt_master_activate(

   435

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

   436

        );

   437

   438

/** Sends all datagrams in the queue.

   439

 *

   440

 * This method takes all datagrams, that have been queued for transmission,

   441

 * puts them into frames, and passes them to the Ethernet device for sending.

   442

 *

   443

 * Has to be called cyclically by the application after ecrt_master_activate()

   444

 * has returned.

   445

 */

   446

void ecrt_master_send(

   447

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

   448

        );

   449

   450

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

   451

 *

   452

 * Queries the network device for received frames by calling the interrupt

   453

 * service routine. Extracts received datagrams and dispatches the results to

   454

 * the datagram objects in the queue. Received datagrams, and the ones that

   455

 * timed out, will be marked, and dequeued.

   456

 *

   457

 * Has to be called cyclically by the realtime application after

   458

 * ecrt_master_activate() has returned.

   459

 */

   460

void ecrt_master_receive(

   461

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

   462

        );

   463

   464

/** Reads the current master state.

   465

 *

   466

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

   467

 */

   468

void ecrt_master_state(

   469

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

   470

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

   471

        );

   472

   473

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

   474

 * Slave configuration methods

   475

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

   476

   477

/** Configure a sync manager.

   478

 *

   479

 * Sets the direction of a sync manager. This overrides the direction bits

   480

 * from the default control register from SII.

   481

 *

   482

 * \return zero on success, else non-zero

   483

 */

   484

int ecrt_slave_config_sync_manager(

   485

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

   486

        uint8_t sync_index, /**< Sync manager index. Must be less