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 userspace library.

     8

 * 

     9

 * The IgH EtherCAT master userspace library is free software; you can

    10

 * redistribute it and/or modify it under the terms of the GNU Lesser General

    11

 * Public License as published by the Free Software Foundation; version 2.1 of

    12

 * the License.

    13

 *

    14

 * The IgH EtherCAT master userspace library is distributed in the hope that

    15

 * it will be useful, but WITHOUT ANY WARRANTY; without even the implied

    16

 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

    17

 * GNU Lesser General Public License for more details.

    18

 *

    19

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

    20

 * along with the IgH EtherCAT master userspace library. If not, see

    21

 * <http://www.gnu.org/licenses/>.

    22

 * 

    23

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

    24

 * industrial property and similar rights of Beckhoff Automation GmbH.

    25

 *

    26

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

    27

    28

/** \file

    29

 *

    30

 * EtherCAT master application interface.

    31

 *

    32

 * \defgroup ApplicationInterface EtherCAT Application Interface

    33

 *

    34

 * EtherCAT interface for realtime applications. This interface is designed

    35

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

    36

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

    37

 * and to configure and activate the bus.

    38

 *

    39

 * Changes in version 1.5:

    40

 *

    41

 * - Changed the meaning of the negative return values of

    42

 *   ecrt_slave_config_reg_pdo_entry() and ecrt_slave_config_sdo*().

    43

 *

    44

 * Changes in Version 1.4:

    45

 *

    46

 * - Replaced ec_slave_t with ec_slave_config_t, separating the bus

    47

 *   configuration from the actual slaves. Therefore, renamed

    48

 *   ecrt_master_get_slave() to ecrt_master_slave_config().

    49

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

    50

 *   ecrt_master_slave_config().

    51

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

    52

 *   necessary due to alias/position addressing.

    53

 * - Added ec_slave_config_state_t for the new method

    54

 *   ecrt_slave_config_state().

    55

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

    56

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

    57

 *   added the domain methods ecrt_domain_size() and

    58

 *   ecrt_domain_external_memory().

    60

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

    61

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

    62

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

    63

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

    64

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

    65

 * - Replaced ecrt_slave_pdo_mapping/add/clear() with

    69

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

    71

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

    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.

    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

    85

 *   scheduled for reading and writing during realtime operation.

    87

 * - Removed the bus_state and bus_tainted flags from ec_master_state_t.

    88

 *

    89

 * @{

    90

 */

    91

    92

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

    93

    94

#ifndef __ECRT_H__

    95

#define __ECRT_H__

    96

    97

#ifdef __KERNEL__

    98

#include <asm/byteorder.h>

    99

#include <linux/types.h>

   100

#else

   101

#include <stdlib.h> // for size_t

   102

#include <stdint.h>

   103

#endif

   104

   105

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

   106

 * Global definitions

   107

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

   108

   109

/** EtherCAT realtime interface major version number.

   110

 */

   111

#define ECRT_VER_MAJOR 1

   112

   113

/** EtherCAT realtime interface minor version number.

   114

 */

   115

#define ECRT_VER_MINOR 5

   116

   117

/** EtherCAT realtime interface version word generator.

   118

 */

   119

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

   120

   121

/** EtherCAT realtime interface version word.

   122

 */

   123

#define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR)

   124

   125

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

   126

   127

/** End of list marker.

   128

 *

   129

 * This can be used with ecrt_slave_config_pdos().

   130

 */

   131

#define EC_END ~0U

   132

   133

/** Maximum number of sync managers per slave.

   134

 */

   135

#define EC_MAX_SYNC_MANAGERS 16

   136

   137

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

   138

 * Data types 

   139

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

   140

   141

struct ec_master;

   142

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

   143

   144

struct ec_slave_config;

   145

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

   146

   147

struct ec_domain;

   148

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

   149

   150

struct ec_sdo_request;

   151

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

   152

   153

struct ec_voe_handler;

   154

typedef struct ec_voe_handler ec_voe_handler_t; /**< \see ec_voe_handler. */

   155

   156

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

   157

   158

/** Master state.

   159

 *

   160

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

   161

 *

   162

 * \see ecrt_master_state().

   163

 */

   164

typedef struct {

   165

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

   166

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

   167

                                  The states are coded in the lower 4 bits.

   168

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

   169

                                  slave in the bus is in the corresponding

   170

                                  state:

   171

                                  - Bit 0: \a INIT

   172

                                  - Bit 1: \a PREOP

   173

                                  - Bit 2: \a SAFEOP

   174

                                  - Bit 3: \a OP */

   175

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

   176

} ec_master_state_t;

   177

   178

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

   179

   180

/** Slave configuration state.

   181

 *

   182

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

   183

 * 

   184

 * \see ecrt_slave_config_state().

   185

 */

   186

typedef struct  {

   187

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

   188

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

   189

                                    using the specified configuration. */

   190

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

   191

                                 - 1: \a INIT

   192

                                 - 2: \a PREOP

   193

                                 - 4: \a SAFEOP

   194

                                 - 8: \a OP

   195

   196

                                 Note that each state is coded in a different

   197

                                 bit! */

   198

} ec_slave_config_state_t;

   199

   200

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

   201

   202

/** Domain working counter interpretation.

   203

 *

   204

 * This is used in ec_domain_state_t.

   205

 */

   206

typedef enum {

   207

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

   208

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

   209

                        exchanged. */

   210

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

   211

} ec_wc_state_t;

   212

   213

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

   214

   215

/** Domain state.

   216

 *

   217

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

   218

 */

   219

typedef struct {

   220

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

   221

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

   222

} ec_domain_state_t;

   223

   224

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

   225

   227

 */

   228

typedef enum {

   229

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

   230

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

   231

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

   232

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

   233

} ec_direction_t;

   234

   235

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

   236

   238

 *

   239

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

   240

 *

   241

 * \see ecrt_slave_config_pdos().

   242

 */

   243

typedef struct {

   247

} ec_pdo_entry_info_t;

   248

   249

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

   250

   252

 * 

   253

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

   254

 * 

   255

 * \see ecrt_slave_config_pdos().

   256

 */

   257

typedef struct {

   260

                              Zero means, that the default mapping shall be

   261

                              used (this can only be done if the slave is

   262

                              present at bus configuration time). */

   264

                                    be \a NULL, or must contain at

   265

                                    least \a n_entries values. */

   266

} ec_pdo_info_t;

   267

   268

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

   269

   270

/** Sync manager configuration information.

   271

 *

   274

 * ecrt_slave_config_pdos().

   275

 */

   276

typedef struct {

   277

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

   278

                     than #EC_MAX_SYNC_MANAGERS for a valid sync manager,

   279

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

   280

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

   284

} ec_sync_info_t;

   285

   286

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

   287

   289

 *

   290

 * This type is used for the array parameter of the

   291

 * ecrt_domain_reg_pdo_entry_list()

   292

 */

   293

typedef struct {

   294

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

   295

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

   296

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

   297

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

   301

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

   302

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

   303

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

   304

                                  NULL, in which case an error is raised if the

   306

} ec_pdo_entry_reg_t;

   307

   308

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

   309

   310

/** Request state.

   311

 *

   312

 * This is used as return type for ecrt_sdo_request_state() and

   313

 * ecrt_voe_handler_state().

   314

 */

   315

typedef enum {

   316

    EC_REQUEST_UNUSED, /**< Not requested. */

   317

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

   318

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

   319

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

   320

} ec_request_state_t;

   321

   322

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

   323

 * Global functions

   324

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

   325

   326

#ifdef __cplusplus

   327

extern "C" {

   328

#endif

   329

   330

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

   331

 *

   332

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

   333

 */

   334

unsigned int ecrt_version_magic(void);

   335

   336

/** Requests an EtherCAT master for realtime operation.

   337

 * 

   338

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

   339

 * for exclusive use.

   340

 *

   341

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

   342

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

   343

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

   344

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

   345

 *

   346

 * \return Pointer to the reserved master, otherwise \a NULL.

   347

 */

   348

ec_master_t *ecrt_request_master(

   349

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

   350

        );

   351

   352

/** Releases a requested EtherCAT master.

   353

 *

   354

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

   355

 * applications.

   356

 */

   357

void ecrt_release_master(

   358

        ec_master_t *master /**< EtherCAT master */

   359

        );

   360

   361

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

   362

 * Master methods

   363

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

   364

   365

#ifdef __KERNEL__

   366

   367

/** Sets the locking callbacks.

   368

 *

   369

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

   370

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

   371

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

   372

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

   373

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

   374

 *

   375

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

   376

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

   377

 * that access is currently forbidden.

   378

 */

   379

void ecrt_master_callbacks(

   380

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

   381

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

   382

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

   383

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

   384

        );

   385

   386

#endif /* __KERNEL__ */

   387

   388

/** Creates a new process data domain.

   389

 *

   390

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

   391

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

   393

 * exchanging them in cyclic operation.

   394

 *

   395

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

   396

 */

   397

ec_domain_t *ecrt_master_create_domain(

   398

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

   399

        );

   400

   401

/** Obtains a slave configuration.

   402

 *

   403

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

   404

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

   405

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

   406

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

   407

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

   408

 *

   409

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

   410

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

   411

 *   ring position.

   412

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

   413

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

   414

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

   415

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

   416

 *

   417

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

   418

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

   419

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

   420

 *

   421

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

   422

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

   423

 * applied.

   424

 *

   425

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

   426

 * \retval NULL in the error case.

   427

 */

   428

ec_slave_config_t *ecrt_master_slave_config(

   429

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

   430

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

   431

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

   432

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

   433

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

   434

        );

   435

   436

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

   437

 *

   438

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

   439

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

   440

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

   441

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

   442

 * now to be applied.

   443

 *

   444

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

   445

 * in charge of cyclically calling ecrt_master_send() and

   446

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

   447

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

   448

 * not be called!

   449

 *

   450

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

   451

 */

   452

int ecrt_master_activate(

   453

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

   454

        );

   455

   456

/** Sends all datagrams in the queue.

   457

 *

   458

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

   459

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

   460

 *

   461

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

   462

 * has returned.

   463

 */

   464

void ecrt_master_send(

   465

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

   466

        );

   467

   468

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

   469

 *

   470

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

   471

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

   472

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

   473

 * timed out, will be marked, and dequeued.

   474

 *

   475

 * Has to be called cyclically by the realtime application after

   476

 * ecrt_master_activate() has returned.

   477

 */

   478

void ecrt_master_receive(

   479

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

   480

        );

   481

   482

/** Reads the current master state.

   483

 *

   484

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

   485

 */

   486

void ecrt_master_state(