1

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

     2

 *

     3

 * $Id$

     4

 *

     5

 * Copyright (C) 2006  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

 * The right to use EtherCAT Technology is granted and comes free of charge

    24

 * under condition of compatibility of product made by Licensee. People

    25

 * intending to distribute/sell products based on the code, have to sign an

    26

 * agreement to guarantee that products using software based on IgH EtherCAT

    27

 * master stay compatible with the actual EtherCAT specification (which are

    28

 * released themselves as an open standard) as the (only) precondition to have

    29

 * the right to use EtherCAT Technology, IP and trade marks.

    30

 *

    31

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

    32

    33

/** \file

    34

 *

    35

 * EtherCAT master application interface.

    36

 *

    37

 * \defgroup ApplicationInterface EtherCAT Application Interface

    38

 *

    39

 * EtherCAT interface for realtime applications. This interface is designed

    40

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

    41

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

    42

 * and to configure and activate the bus.

    43

 *

    44

 * Changes in version 1.5:

    45

 *

    46

 * - Changed the return value of ecrt_request_master().

    47

 *

    48

 * Changes in Version 1.4:

    49

 *

    50

 * - Replaced ec_slave_t with ec_slave_config_t, separating the bus

    51

 *   configuration from the actual slaves. Therefore, renamed

    52

 *   ecrt_master_get_slave() to ecrt_master_slave_config().

    53

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

    54

 *   ecrt_master_slave_config().

    55

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

    56

 *   necessary due to alias/position addressing.

    57

 * - Added ec_slave_config_state_t for the new method

    58

 *   ecrt_slave_config_state().

    59

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

    60

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

    61

 *   added the domain methods ecrt_domain_size() and

    62

 *   ecrt_domain_external_memory().

    63

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

    64

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

    65

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

    66

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

    67

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

    68

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

    69

 * - Replaced ecrt_slave_pdo_mapping/add/clear() with

    70

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

    71

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

    72

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

    73

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

    74

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

    75

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

    76

 * - Renamed ec_bus_status_t, ec_master_status_t to ec_bus_state_t and

    77

 *   ec_master_state_t, respectively. Renamed ecrt_master_get_status() to

    78

 *   ecrt_master_state(), for consistency reasons.

    79

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

    80

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

    81

 *   information, if the process data was exchanged completely.

    82

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

    83

 *   renamed ec_pdo_reg_t to ec_pdo_entry_reg_t and ecrt_domain_register_pdo()

    84

 *   to ecrt_slave_config_reg_pdo_entry().

    85

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

    86

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

    87

 *   registering the mapped Pdo entries.

    88

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

    89

 *   scheduled for reading and writing during realtime operation.

    90

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

    91

 * - Removed the bus_state and bus_tainted flags from ec_master_state_t.

    92

 *

    93

 * @{

    94

 */

    95

    96

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

    97

    98

#ifndef __ECRT_H__

    99

#define __ECRT_H__

   100

   101

#ifdef __KERNEL__

   102

#include <asm/byteorder.h>

   103

#include <linux/types.h>

   104

#else

   105

#include <stdlib.h> // for size_t

   106

#include <stdint.h>

   107

#endif

   108

   109

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

   110

 * Global definitions

   111

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

   112

   113

/** EtherCAT realtime interface major version number.

   114

 */

   115

#define ECRT_VER_MAJOR 1

   116

   117

/** EtherCAT realtime interface minor version number.

   118

 */

   119

#define ECRT_VER_MINOR 5

   120

   121

/** EtherCAT realtime interface version word generator.

   122

 */

   123

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

   124

   125

/** EtherCAT realtime interface version word.

   126

 */

   127

#define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR)

   128

   129

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

   130

   131

/** End of list marker.

   132

 *

   133

 * This can be used with ecrt_slave_config_pdos().

   134

 */

   135

#define EC_END ~0U

   136

   137

/** Maximum number of sync managers per slave.

   138

 */

   139

#define EC_MAX_SYNC_MANAGERS 16

   140

   141

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

   142

 * Data types 

   143

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

   144

   145

struct ec_master;

   146

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

   147

   148

struct ec_slave_config;

   149

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

   150

   151

struct ec_domain;

   152

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

   153

   154

struct ec_sdo_request;

   155

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

   156

   157

struct ec_voe_handler;

   158

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

   159

   160

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

   161

   162

/** Master state.

   163

 *

   164

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

   165

 *

   166

 * \see ecrt_master_state().

   167

 */

   168

typedef struct {

   169

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

   170

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

   171

                                  The states are coded in the lower 4 bits.

   172

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

   173

                                  slave in the bus is in the corresponding

   174

                                  state:

   175

                                  - Bit 0: \a INIT

   176

                                  - Bit 1: \a PREOP

   177

                                  - Bit 2: \a SAFEOP

   178

                                  - Bit 3: \a OP */

   179

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

   180

} ec_master_state_t;

   181

   182

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

   183

   184

/** Slave configuration state.

   185

 *

   186

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

   187

 * 

   188

 * \see ecrt_slave_config_state().

   189

 */

   190

typedef struct  {

   191

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

   192

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

   193

                                    using the specified configuration. */

   194

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

   195

                                 - 1: \a INIT

   196

                                 - 2: \a PREOP

   197

                                 - 4: \a SAFEOP

   198

                                 - 8: \a OP

   199

   200

                                 Note that each state is coded in a different

   201

                                 bit! */

   202

} ec_slave_config_state_t;

   203

   204

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

   205

   206

/** Domain working counter interpretation.

   207

 *

   208

 * This is used in ec_domain_state_t.

   209

 */

   210

typedef enum {

   211

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

   212

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

   213

                        exchanged. */

   214

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

   215

} ec_wc_state_t;

   216

   217

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

   218

   219

/** Domain state.

   220

 *

   221

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

   222

 */

   223

typedef struct {

   224

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

   225

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

   226

} ec_domain_state_t;

   227

   228

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

   229

   230

/** Direction type for Pdo assignment functions.

   231

 */

   232

typedef enum {

   233

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

   234

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

   235

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

   236

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

   237

} ec_direction_t;

   238

   239

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

   240

   241

/** Pdo entry configuration information.

   242

 *

   243

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

   244

 *

   245

 * \see ecrt_slave_config_pdos().

   246

 */

   247

typedef struct {

   248

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

   249

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

   250

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

   251

} ec_pdo_entry_info_t;

   252

   253

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

   254

   255

/** Pdo configuration information.

   256

 * 

   257

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

   258

 * 

   259

 * \see ecrt_slave_config_pdos().

   260

 */

   261

typedef struct {

   262

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

   263

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

   264

                              Zero means, that the default mapping shall be

   265

                              used (this can only be done if the slave is

   266

                              present at bus configuration time). */

   267

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

   268

                                    be \a NULL, or must contain at

   269

                                    least \a n_entries values. */

   270

} ec_pdo_info_t;

   271

   272

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

   273

   274

/** Sync manager configuration information.

   275

 *

   276

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

   277

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

   278

 * ecrt_slave_config_pdos().

   279

 */

   280

typedef struct {

   281

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

   282

                     than #EC_MAX_SYNC_MANAGERS for a valid sync manager,

   283

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

   284

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

   285

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

   286

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

   287

                            at least \a n_pdos Pdos. */

   288

} ec_sync_info_t;

   289

   290

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

   291

   292

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

   293

 *

   294

 * This type is used for the array parameter of the

   295

 * ecrt_domain_reg_pdo_entry_list()

   296

 */

   297

typedef struct {

   298

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

   299

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

   300

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

   301

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

   302

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

   303

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

   304

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

   305

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

   306

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

   307

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

   308

                                  NULL, in which case an error is raised if the

   309

                                  Pdo entry does not byte-align. */

   310

} ec_pdo_entry_reg_t;

   311

   312

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

   313

   314

/** Request state.

   315

 *

   316

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

   317

 * ecrt_voe_handler_state().

   318

 */

   319

typedef enum {

   320

    EC_REQUEST_UNUSED, /**< Not requested. */

   321

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

   322

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

   323

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

   324

} ec_request_state_t;

   325

   326

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

   327

 * Global functions

   328

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

   329

   330

#ifdef __cplusplus

   331

extern "C" {

   332

#endif

   333

   334

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

   335

 *

   336

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

   337

 */

   338

unsigned int ecrt_version_magic(void);

   339

   340

/** Requests an EtherCAT master for realtime operation.

   341

 * 

   342

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

   343

 * for exclusive use.

   344

 *

   345

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

   346

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

   347

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

   348

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

   349

 *

   350

 * \attention In kernel context, the returned pointer has to be checked for

   351

 * errors using the IS_ERR() macro.

   352

 *

   353

 * \return If \a IS_ERR() returns zero, the result is a pointer to the

   354

 * reserved master, otherwise, the result is an error code.

   355

 */

   356

ec_master_t *ecrt_request_master(

   357

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

   358

        );

   359

   360

/** Releases a requested EtherCAT master.

   361

 *

   362

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

   363

 * applications.

   364

 */

   365

void ecrt_release_master(

   366

        ec_master_t *master /**< EtherCAT master */

   367

        );

   368

   369

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

   370

 * Master methods

   371

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

   372

   373

#ifdef __KERNEL__

   374

   375

/** Sets the locking callbacks.

   376

 *

   377

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

   378

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

   379

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

   380

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

   381

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

   382

 *

   383

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

   384

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

   385

 * that access is currently forbidden.

   386

 */

   387

void ecrt_master_callbacks(

   388

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

   389

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

   390

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

   391

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

   392

        );

   393

   394

#endif /* __KERNEL__ */

   395

   396

/** Creates a new process data domain.

   397

 *

   398

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

   399

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

   400

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

   401

 * exchanging them in cyclic operation.

   402

 *

   403

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

   404

 */

   405

ec_domain_t *ecrt_master_create_domain(

   406

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

   407

        );

   408

   409

/** Obtains a slave configuration.

   410

 *

   411

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

   412

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

   413

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

   414

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

   415

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

   416

 *

   417

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

   418

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

   419

 *   ring position.

   420

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

   421

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

   422

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

   423

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

   424

 *

   425

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

   426

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

   427

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

   428

 *

   429

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

   430

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

   431

 * applied.

   432

 *

   433

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

   434

 * \retval NULL in the error case.

   435

 */

   436

ec_slave_config_t *ecrt_master_slave_config(

   437

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

   438

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

   439

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

   440

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

   441

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

   442

        );

   443

   444

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

   445

 *

   446

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

   447

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

   448

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

   449

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

   450

 * now to be applied.

   451

 *

   452

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

   453

 * in charge of cyclically calling ecrt_master_send() and

   454

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

   455

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

   456

 * not be called!

   457

 *

   458

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

   459

 */

   460

int ecrt_master_activate(

   461

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

   462

        );

   463

   464

/** Sends all datagrams in the queue.

   465

 *

   466

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

   467

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

   468

 *

   469

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

   470

 * has returned.

   471

 */

   472

void ecrt_master_send(

   473

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

   474

        );

   475

   476

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

   477

 *

   478

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

   479

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

   480

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

   481

 * timed out, will be marked, and dequeued.

   482

 *

   483

 * Has to be called cyclically by the realtime application after

   484

 * ecrt_master_activate() has returned.

   485

 */

   486

void ecrt_master_receive(

   487

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