1

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

     2

 *

     3

 *  $Id$

     4

 *

     5

 *  Copyright (C) 2006  Florian Pose, Ingenieurgemeinschaft IgH

     6

 *

     7

 *  This file is part of the IgH EtherCAT Master.

     8

 *

     9

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

    10

 *  and/or modify it under the terms of the GNU General Public License

    11

 *  as published by the Free Software Foundation; either version 2 of the

    12

 *  License, or (at your option) any later version.

    13

 *

    14

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

    15

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

    16

 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

    17

 *  GNU General Public License for more details.

    18

 *

    19

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

    20

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

    21

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

    22

 *

    23

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

    24

 *  charge under condition of compatibility of product made by

    25

 *  Licensee. People intending to distribute/sell products based on the

    26

 *  code, have to sign an agreement to guarantee that products using

    27

 *  software based on IgH EtherCAT master stay compatible with the actual

    28

 *  EtherCAT specification (which are released themselves as an open

    29

 *  standard) as the (only) precondition to have the right to use EtherCAT

    30

 *  Technology, IP and trade marks.

    31

 *

    32

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

    33

    34

/**

    35

   \file

    36

   EtherCAT realtime interface.

    37

*/

    38

    39

/**

    40

   \defgroup RealtimeInterface EtherCAT realtime interface

    41

   EtherCAT interface for realtime modules.

    42

   This interface is designed for realtime modules that want to use EtherCAT.

    43

   There are functions to request a master, to map process data, to communicate

    44

   with slaves via CoE and to configure and activate the bus.

    45

*/

    46

    47

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

    48

    49

#ifndef __ECRT_H__

    50

#define __ECRT_H__

    51

    52

#include <asm/byteorder.h>

    53

    54

#ifdef __KERNEL__

    55

#include <linux/types.h>

    56

#else

    57

#include <stdint.h>

    58

#endif

    59

    60

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

    61

    62

#define ECRT_VER_MAJOR 1

    63

#define ECRT_VER_MINOR 3

    64

    65

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

    66

#define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR)

    67

    68

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

    69

    70

struct ec_master;

    71

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

    72

    73

struct ec_domain;

    74

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

    75

    76

struct ec_slave;

    77

typedef struct ec_slave ec_slave_t; /**< \see ec_slave */

    78

    79

/**

    80

 * Bus status.

    81

 */

    82

    83

typedef enum {

    84

    EC_BUS_FAILURE = -1, /**< At least one slave with process data exchange

    85

                           is offline. */

    86

    EC_BUS_OK            /**< All slaves with process data exchange are

    87

                           online. */

    88

}

    89

ec_bus_status_t;

    90

    91

/**

    92

 * Master status.

    93

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

    94

 */

    95

    96

typedef struct {

    97

    ec_bus_status_t bus_status; /**< \see ec_bus_status_t */

    98

    unsigned int bus_tainted; /**< non-zero, if the bus topology is invalid */

    99

    unsigned int slaves_responding; /**< number of responging slaves */

   100

}

   101

ec_master_status_t;

   102

   103

/**

   104

 * List entry for domain PDO registrations.

   105

 * This type is used as a parameter for the ecrt_domain_register_pdo_list()

   106

 * convenience function.

   107

 */

   108

   109

typedef struct {

   110

    const char *slave_address; /**< slave address string

   111

                                 \see ec_master_parse_slave_address() */

   112

    uint32_t vendor_id; /**< vendor ID */

   113

    uint32_t product_code; /**< product code */

   114

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

   115

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

   116

    void **data_ptr; /**< address of the process data pointer */

   117

}

   118

ec_pdo_reg_t;

   119

   120

/**

   121

 * Direction type for PDO mapping and range registration functions.

   122

 */

   123

   124

typedef enum {

   125

    EC_DIR_OUTPUT, /**< values written by master */

   126

    EC_DIR_INPUT   /**< values read by master */

   127

}

   128

ec_direction_t;

   129

   130

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

   131

 *  Global functions

   132

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

   133

   134

ec_master_t *ecrt_request_master(unsigned int master_index);

   135

void ecrt_release_master(ec_master_t *master);

   136

   137

unsigned int ecrt_version_magic(void);

   138

   139

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

   140

 *  Master methods

   141

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

   142

   143

void ecrt_master_callbacks(ec_master_t *master, int (*request_cb)(void *),

   144

                           void (*release_cb)(void *), void *cb_data);

   145

   146

ec_domain_t *ecrt_master_create_domain(ec_master_t *master);

   147

   148

ec_slave_t *ecrt_master_get_slave(const ec_master_t *, const char *,

   149

        uint32_t vendor_id, uint32_t product_code);

   150

ec_slave_t *ecrt_master_get_slave_by_pos(const ec_master_t *, uint16_t,

   151

        uint32_t vendor_id, uint32_t product_code);

   152

   153

int ecrt_master_activate(ec_master_t *master);

   154

   155

void ecrt_master_send(ec_master_t *master);

   156

void ecrt_master_receive(ec_master_t *master);

   157

   158

void ecrt_master_get_status(const ec_master_t *master, ec_master_status_t *);

   159

   160

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

   161

 *  Domain Methods

   162

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

   163

   164

int ecrt_domain_register_pdo(ec_domain_t *domain, ec_slave_t *slave,

   165

        uint16_t pdo_index, uint8_t pdo_subindex, void **data_ptr);

   166

   167

int ecrt_domain_register_pdo_range(ec_domain_t *domain, ec_slave_t *slave,

   168

        ec_direction_t direction, uint16_t offset, uint16_t length,

   169

        void **data_ptr);

   170

   171

int ecrt_domain_register_pdo_list(ec_domain_t *domain,

   172

        const ec_pdo_reg_t *pdos);

   173

   174

void ecrt_domain_process(ec_domain_t *domain);

   175

void ecrt_domain_queue(ec_domain_t *domain);

   176

   177

int ecrt_domain_state(const ec_domain_t *domain);

   178

   179

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

   180

 *  Slave Methods

   181

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

   182

   183

int ecrt_slave_conf_sdo8(ec_slave_t *slave, uint16_t sdo_index,

   184

                         uint8_t sdo_subindex, uint8_t value);

   185

int ecrt_slave_conf_sdo16(ec_slave_t *slave, uint16_t sdo_index,

   186

                          uint8_t sdo_subindex, uint16_t value);

   187

int ecrt_slave_conf_sdo32(ec_slave_t *slave, uint16_t sdo_index,

   188

                          uint8_t sdo_subindex, uint32_t value);

   189

   190

void ecrt_slave_pdo_mapping_clear(ec_slave_t *, ec_direction_t);

   191

int ecrt_slave_pdo_mapping_add(ec_slave_t *, ec_direction_t, uint16_t);

   192

int ecrt_slave_pdo_mapping(ec_slave_t *, ec_direction_t, unsigned int, ...);

   193

   194

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

   195

 *  Bitwise read/write macros

   196

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

   197

   198

/**

   199

 * Read a certain bit of an EtherCAT data byte.

   200

 * \param DATA EtherCAT data pointer

   201

 * \param POS bit position

   202

 */

   203

   204

#define EC_READ_BIT(DATA, POS) ((*((uint8_t *) (DATA)) >> (POS)) & 0x01)

   205

   206

/**

   207

 * Write a certain bit of an EtherCAT data byte.

   208

 * \param DATA EtherCAT data pointer

   209

 * \param POS bit position

   210

 * \param VAL new bit value

   211

 */

   212

   213

#define EC_WRITE_BIT(DATA, POS, VAL) \

   214

    do { \

   215

        if (VAL) *((uint8_t *) (DATA)) |=  (1 << (POS)); \

   216

        else     *((uint8_t *) (DATA)) &= ~(1 << (POS)); \

   217

    } while (0)

   218

   219

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

   220

 *  Read macros

   221

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

   222

   223

/**

   224

 * Read an 8-bit unsigned value from EtherCAT data.

   225

 * \return EtherCAT data value

   226

 */

   227

   228

#define EC_READ_U8(DATA) \

   229

    ((uint8_t) *((uint8_t *) (DATA)))

   230

   231

/**

   232

 * Read an 8-bit signed value from EtherCAT data.

   233

 * \param DATA EtherCAT data pointer

   234

 * \return EtherCAT data value

   235

 */

   236

   237

#define EC_READ_S8(DATA) \

   238

     ((int8_t) *((uint8_t *) (DATA)))

   239

   240

/**

   241

 * Read a 16-bit unsigned value from EtherCAT data.

   242

 * \param DATA EtherCAT data pointer

   243

 * \return EtherCAT data value

   244

 */

   245

   246

#define EC_READ_U16(DATA) \

   247

     ((uint16_t) le16_to_cpup((void *) (DATA)))

   248

   249

/**

   250

 * Read a 16-bit signed value from EtherCAT data.

   251

 * \param DATA EtherCAT data pointer

   252

 * \return EtherCAT data value

   253

 */

   254

   255

#define EC_READ_S16(DATA) \

   256

     ((int16_t) le16_to_cpup((void *) (DATA)))

   257

   258

/**

   259

 * Read a 32-bit unsigned value from EtherCAT data.

   260

 * \param DATA EtherCAT data pointer

   261

 * \return EtherCAT data value

   262

 */

   263

   264

#define EC_READ_U32(DATA) \

   265

     ((uint32_t) le32_to_cpup((void *) (DATA)))

   266

   267

/**

   268

 * Read a 32-bit signed value from EtherCAT data.

   269

 * \param DATA EtherCAT data pointer

   270

 * \return EtherCAT data value

   271

 */

   272

   273

#define EC_READ_S32(DATA) \

   274

     ((int32_t) le32_to_cpup((void *) (DATA)))

   275

   276

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

   277

 *  Write macros

   278

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

   279

   280

/**

   281

 * Write an 8-bit unsigned value to EtherCAT data.

   282

 * \param DATA EtherCAT data pointer

   283

 * \param VAL new value

   284

 */

   285

   286

#define EC_WRITE_U8(DATA, VAL) \

   287

    do { \

   288

        *((uint8_t *)(DATA)) = ((uint8_t) (VAL)); \

   289

    } while (0)

   290

   291

/**

   292

 * Write an 8-bit signed value to EtherCAT data.

   293

 * \param DATA EtherCAT data pointer

   294

 * \param VAL new value

   295

 */

   296

   297

#define EC_WRITE_S8(DATA, VAL) EC_WRITE_U8(DATA, VAL)

   298

   299

/**

   300

 * Write a 16-bit unsigned value to EtherCAT data.

   301

 * \param DATA EtherCAT data pointer

   302

 * \param VAL new value

   303

 */

   304

   305

#define EC_WRITE_U16(DATA, VAL) \

   306

    do { \

   307

        *((uint16_t *) (DATA)) = (uint16_t) (VAL); \

   308

        cpu_to_le16s(DATA); \

   309

    } while (0)

   310

   311

/**

   312

 * Write a 16-bit signed value to EtherCAT data.

   313

 * \param DATA EtherCAT data pointer

   314

 * \param VAL new value

   315

 */

   316

   317

#define EC_WRITE_S16(DATA, VAL) EC_WRITE_U16(DATA, VAL)

   318

   319

/**

   320

 * Write a 32-bit unsigned value to EtherCAT data.

   321

 * \param DATA EtherCAT data pointer

   322

 * \param VAL new value

   323

 */

   324

   325

#define EC_WRITE_U32(DATA, VAL) \

   326

    do { \

   327

        *((uint32_t *) (DATA)) = (uint32_t) (VAL); \

   328

        cpu_to_le16s(DATA); \

   329

    } while (0)

   330

   331

/**

   332

 * Write a 32-bit signed value to EtherCAT data.

   333

 * \param DATA EtherCAT data pointer

   334

 * \param VAL new value

   335

 */

   336

   337

#define EC_WRITE_S32(DATA, VAL) EC_WRITE_U32(DATA, VAL)

   338

   339

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

   340

   341

#endif