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

    12

 *  of 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

    24

 *  the 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

 * - Imlemented the Vendor-specific over EtherCAT mailbox protocol. See

    44

 *   ecrt_slave_config_create_voe_handler().

    45

 * - Renamed ec_sdo_request_state_t to ec_request_state_t, because it is also

    46

 *   used by VoE handlers.

    47

 * - Added ecrt_master_slave() to get information about a certain slave.

    48

 * - Removed 'const' from argument of ecrt_sdo_request_state(), because the

    49

 *   userspace library has to modify object internals.

    50

 *

    51

 * Changes in Version 1.4:

    52

 *

    53

 * - Replaced ec_slave_t with ec_slave_config_t, separating the bus

    54

 *   configuration from the actual slaves. Therefore, renamed

    55

 *   ecrt_master_get_slave() to ecrt_master_slave_config().

    56

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

    57

 *   ecrt_master_slave_config().

    58

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

    59

 *   necessary due to alias/position addressing.

    60

 * - Added ec_slave_config_state_t for the new method

    61

 *   ecrt_slave_config_state().

    62

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

    63

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

    64

 *   added the domain methods ecrt_domain_size() and

    65

 *   ecrt_domain_external_memory().

    66

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

    67

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

    68

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

    69

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

    70

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

    71

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

    72

 * - Replaced ecrt_slave_pdo_mapping/add/clear() with

    73

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

    74

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

    75

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

    76

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

    77

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

    78

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

    79

 * - Renamed ec_bus_status_t, ec_master_status_t to ec_bus_state_t and

    80

 *   ec_master_state_t, respectively. Renamed ecrt_master_get_status() to

    81

 *   ecrt_master_state(), for consistency reasons.

    82

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

    83

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

    84

 *   information, if the process data was exchanged completely.

    85

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

    86

 *   renamed ec_pdo_reg_t to ec_pdo_entry_reg_t and ecrt_domain_register_pdo()

    87

 *   to ecrt_slave_config_reg_pdo_entry().

    88

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

    89

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

    90

 *   registering the mapped PDO entries.

    91

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

    92

 *   scheduled for reading and writing during realtime operation.

    93

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

    94

 * - Removed the bus_state and bus_tainted flags from ec_master_state_t.

    95

 *

    96

 * @{

    97

 */

    98

    99

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

   100

   101

#ifndef __ECRT_H__

   102

#define __ECRT_H__

   103

   104

#ifdef __KERNEL__

   105

#include <asm/byteorder.h>

   106

#include <linux/types.h>

   107

#else

   108

#include <stdlib.h> // for size_t

   109

#include <stdint.h>

   110

#endif

   111

   112

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

   113

 * Global definitions

   114

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

   115

   116

/** EtherCAT realtime interface major version number.

   117

 */

   118

#define ECRT_VER_MAJOR 1

   119

   120

/** EtherCAT realtime interface minor version number.

   121

 */

   122

#define ECRT_VER_MINOR 5

   123

   124

/** EtherCAT realtime interface version word generator.

   125

 */

   126

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

   127

   128

/** EtherCAT realtime interface version word.

   129

 */

   130

#define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR)

   131

   132

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

   133

   134

/** End of list marker.

   135

 *

   136

 * This can be used with ecrt_slave_config_pdos().

   137

 */

   138

#define EC_END ~0U

   139

   140

/** Maximum number of sync managers per slave.

   141

 */

   142

#define EC_MAX_SYNC_MANAGERS 16

   143

   144

/** Maximum string length.

   145

 *

   146

 * Used in ec_slave_info_t.

   147

 */

   148

#define EC_MAX_STRING_LENGTH 64

   149

   150

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

   151

 * Data types 

   152

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

   153

   154

struct ec_master;

   155

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

   156

   157

struct ec_slave_config;

   158

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

   159

   160

struct ec_domain;

   161

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

   162

   163

struct ec_sdo_request;

   164

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

   165

   166

struct ec_voe_handler;

   167

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

   168

   169

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

   170

   171

/** Master state.

   172

 *

   173

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

   174

 *

   175

 * \see ecrt_master_state().

   176

 */

   177

typedef struct {

   178

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

   179

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

   180

                                  The states are coded in the lower 4 bits.

   181

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

   182

                                  slave in the bus is in the corresponding

   183

                                  state:

   184

                                  - Bit 0: \a INIT

   185

                                  - Bit 1: \a PREOP

   186

                                  - Bit 2: \a SAFEOP

   187

                                  - Bit 3: \a OP */

   188

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

   189

} ec_master_state_t;

   190

   191

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

   192

   193

/** Slave configuration state.

   194

 *

   195

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

   196

 * 

   197

 * \see ecrt_slave_config_state().

   198

 */

   199

typedef struct  {

   200

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

   201

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

   202

                                    using the specified configuration. */

   203

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

   204

                                 - 1: \a INIT

   205

                                 - 2: \a PREOP

   206

                                 - 4: \a SAFEOP

   207

                                 - 8: \a OP

   208

   209

                                 Note that each state is coded in a different

   210

                                 bit! */

   211

} ec_slave_config_state_t;

   212

   213

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

   214

   215

/** Slave information.

   216

 *

   217

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

   218

 *

   219

 * \see ecrt_master_slave().

   220

 */

   221

typedef struct {

   222

    uint16_t position; /**< Offset of the slave in the ring. */

   223

    uint32_t vendor_id; /**< Vendor-ID stored on the slave. */

   224

    uint32_t product_code; /**< Product-Code stored on the slave. */

   225

    uint32_t revision_number; /**< Revision-Number stored on the slave. */

   226

    uint32_t serial_number; /**< Serial-Number stored on the slave. */

   227

    uint16_t alias; /**< The slaves alias if not equal to 0. */

   228

    int16_t current_on_ebus;

   229

    uint8_t al_state; /**< Current state of the slave. */

   230

    uint8_t error_flag; /**< Error flag for that slave. */

   231

    uint8_t sync_count; /**< Number of sync managers. */

   232

    uint16_t sdo_count; /**< Number of SDO's. */

   233

    char name[EC_MAX_STRING_LENGTH]; /**< Name of the slave. */

   234

} ec_slave_info_t;

   235

   236

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

   237

   238

/** Domain working counter interpretation.

   239

 *

   240

 * This is used in ec_domain_state_t.

   241

 */

   242

typedef enum {

   243

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

   244

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

   245

                        exchanged. */

   246

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

   247

} ec_wc_state_t;

   248

   249

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

   250

   251

/** Domain state.

   252

 *

   253

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

   254

 */

   255

typedef struct {

   256

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

   257

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

   258

} ec_domain_state_t;

   259

   260

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

   261

   262

/** Direction type for PDO assignment functions.

   263

 */

   264

typedef enum {

   265

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

   266

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

   267

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

   268

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

   269

} ec_direction_t;

   270

   271

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

   272

   273

/** PDO entry configuration information.

   274

 *

   275

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

   276

 *

   277

 * \see ecrt_slave_config_pdos().

   278

 */

   279

typedef struct {

   280

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

   281

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

   282

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

   283

} ec_pdo_entry_info_t;

   284

   285

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

   286

   287

/** PDO configuration information.

   288

 * 

   289

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

   290

 * 

   291

 * \see ecrt_slave_config_pdos().

   292

 */

   293

typedef struct {

   294

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

   295

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

   296

                              Zero means, that the default mapping shall be

   297

                              used (this can only be done if the slave is

   298

                              present at bus configuration time). */

   299

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

   300

                                    be \a NULL, or must contain at

   301

                                    least \a n_entries values. */

   302

} ec_pdo_info_t;

   303

   304

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

   305

   306

/** Sync manager configuration information.

   307

 *

   308

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

   309

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

   310

 * ecrt_slave_config_pdos().

   311

 */

   312

typedef struct {

   313

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

   314

                     than #EC_MAX_SYNC_MANAGERS for a valid sync manager,

   315

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

   316

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

   317

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

   318

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

   319

                            at least \a n_pdos PDOs. */

   320

} ec_sync_info_t;

   321

   322

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

   323

   324

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

   325

 *

   326

 * This type is used for the array parameter of the

   327

 * ecrt_domain_reg_pdo_entry_list()

   328

 */

   329

typedef struct {

   330

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

   331

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

   332

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

   333

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

   334

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

   335

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

   336

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

   337

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

   338

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

   339

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

   340

                                  NULL, in which case an error is raised if the

   341

                                  PDO entry does not byte-align. */

   342

} ec_pdo_entry_reg_t;

   343

   344

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

   345

   346

/** Request state.

   347

 *

   348

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

   349

 * ecrt_voe_handler_state().

   350

 */

   351

typedef enum {

   352

    EC_REQUEST_UNUSED, /**< Not requested. */

   353

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

   354

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

   355

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

   356

} ec_request_state_t;

   357

   358

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

   359

 * Global functions

   360

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

   361

   362

#ifdef __cplusplus

   363

extern "C" {

   364

#endif

   365

   366

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

   367

 *

   368

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

   369

 */

   370

unsigned int ecrt_version_magic(void);

   371

   372

/** Requests an EtherCAT master for realtime operation.

   373

 * 

   374

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

   375

 * for exclusive use.

   376

 *

   377

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

   378

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

   379

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

   380

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

   381

 *

   382

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

   383

 */

   384

ec_master_t *ecrt_request_master(

   385

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

   386

        );

   387

   388

/** Releases a requested EtherCAT master.

   389

 *

   390

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

   391

 * applications.

   392

 */

   393

void ecrt_release_master(

   394

        ec_master_t *master /**< EtherCAT master */

   395

        );

   396

   397

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

   398

 * Master methods

   399

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

   400

   401

#ifdef __KERNEL__

   402

   403

/** Sets the locking callbacks.

   404

 *

   405

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

   406

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

   407

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

   408

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

   409

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

   410

 *

   411

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

   412

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

   413

 * that access is currently forbidden.

   414

 */

   415

void ecrt_master_callbacks(

   416

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

   417

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

   418

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

   419

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

   420

        );

   421

   422

#endif /* __KERNEL__ */

   423

   424

/** Creates a new process data domain.

   425

 *

   426

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

   427

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

   428

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

   429

 * exchanging them in cyclic operation.

   430

 *

   431

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

   432

 */

   433

ec_domain_t *ecrt_master_create_domain(

   434

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

   435

        );

   436

   437

/** Obtains a slave configuration.

   438

 *

   439

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

   440

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

   441

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

   442

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

   443

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

   444

 *

   445

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

   446

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

   447

 *   ring position.

   448

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

   449

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

   450

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

   451

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

   452

 *

   453

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

   454

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

   455

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

   456

 *

   457

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

   458

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

   459

 * applied.

   460

 *

   461

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

   462

 * \retval NULL in the error case.

   463

 */

   464

ec_slave_config_t *ecrt_master_slave_config(

   465

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

   466

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

   467

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

   468

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

   469

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

   470

        );

   471

   472

/** Obtains slave information.

   473

 *

   474

 * Tries to find the slave with the given ring position. The obtained

   475

 * information is stored in a structure. No memory is allocated on the heap in

   476

 * this function.

   477

 *

   478

 * \attention The pointer to this structure must point to a valid variable.

   479

 *

   480

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

   481

 */

   482

int ecrt_master_slave(

   483

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

   484

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

   485

        ec_slave_info_t *slave_info /**< Structure that will output the

   486

                                      information */