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

/** \file

    35

 *

    36

 * EtherCAT Real-Time Interface.

    37

 *

    38

 * \defgroup RealtimeInterface EtherCAT Real-Time Interface

    39

 *

    40

 * EtherCAT interface for realtime modules. This interface is designed for

    41

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

    42

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

    43

 * configure and activate the bus.

    44

 */

    45

    46

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

    47

    48

#ifndef __ECRT_H__

    49

#define __ECRT_H__

    50

    51

#include <asm/byteorder.h>

    52

    53

#ifdef __KERNEL__

    54

#include <linux/types.h>

    55

#else

    56

#include <stdint.h>

    57

#endif

    58

    59

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

    60

 * Global definitions

    61

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

    62

    63

/** EtherCAT real-time interface major version number.

    64

 */

    65

#define ECRT_VER_MAJOR 1

    66

    67

/** EtherCAT real-time interface minor version number.

    68

 */

    69

#define ECRT_VER_MINOR 4

    70

    71

/** EtherCAT real-time interface version word generator.

    72

 */

    73

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

    74

    75

/** EtherCAT real-time interface version word.

    76

 */

    77

#define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR)

    78

    79

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

    80

 * Data types 

    81

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

    82

    83

struct ec_master;

    84

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

    85

    86

struct ec_domain;

    87

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

    88

    89

struct ec_slave;

    90

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

    91

    92

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

    93

    94

/** Bus status.

    95

 * This is used in ec_master_status_t.

    96

 */

    97

typedef enum {

    98

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

    99

                           is offline. */

   100

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

   101

                           online. */

   102

}

   103

ec_bus_status_t;

   104

   105

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

   106

   107

/** Master status.

   108

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

   109

 */

   110

typedef struct {

   111

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

   112

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

   113

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

   114

}

   115

ec_master_status_t;

   116

   117

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

   118

   119

/** List entry for domain PDO registrations.

   120

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

   121

 * convenience function.

   122

 */

   123

typedef struct {

   124

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

   125

                                 \see ec_master_parse_slave_address() */

   126

    uint32_t vendor_id; /**< vendor ID */

   127

    uint32_t product_code; /**< product code */

   128

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

   129

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

   130

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

   131

}

   132

ec_pdo_reg_t;

   133

   134

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

   135

   136

/** Direction type for PDO mapping and range registration functions.

   137

 */

   138

typedef enum {

   139

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

   140

    EC_DIR_INPUT   /**< values read by master */

   141

}

   142

ec_direction_t;

   143

   144

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

   145

 * Global functions

   146

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

   147

   148

ec_master_t *ecrt_request_master(unsigned int master_index);

   149

void ecrt_release_master(ec_master_t *master);

   150

   151

unsigned int ecrt_version_magic(void);

   152

   153

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

   154

 * Master methods

   155

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

   156

   157

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

   158

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

   159

   160

ec_domain_t *ecrt_master_create_domain(ec_master_t *master);

   161

   162

ec_slave_t *ecrt_master_get_slave(const ec_master_t *master,

   163

        const char *address, uint32_t vendor_id, uint32_t product_code);

   164

ec_slave_t *ecrt_master_get_slave_by_pos(const ec_master_t *master,

   165

        uint16_t position, uint32_t vendor_id, uint32_t product_code);

   166

   167

int ecrt_master_activate(ec_master_t *master);

   168

   169

void ecrt_master_send(ec_master_t *master);

   170

void ecrt_master_receive(ec_master_t *master);

   171

   172

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

   173

   174

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

   175

 * Domain methods

   176

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

   177

   178

int ecrt_domain_register_pdo(ec_domain_t *domain, ec_slave_t *slave,

   179

        uint16_t pdo_entry_index, uint8_t pdo_entry_subindex, void **data_ptr);

   180

   181

int ecrt_domain_register_pdo_range(ec_domain_t *domain, ec_slave_t *slave,

   182

        ec_direction_t direction, uint16_t offset, uint16_t length,

   183

        void **data_ptr);

   184

   185

int ecrt_domain_register_pdo_list(ec_domain_t *domain,

   186

        const ec_pdo_reg_t *pdos);

   187

   188

void ecrt_domain_process(ec_domain_t *domain);

   189

void ecrt_domain_queue(ec_domain_t *domain);

   190

   191

int ecrt_domain_state(const ec_domain_t *domain);

   192

   193

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

   194

 * Slave methods

   195

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

   196

   197

int ecrt_slave_conf_sdo8(ec_slave_t *slave, uint16_t sdo_index,

   198

                         uint8_t sdo_subindex, uint8_t value);

   199

int ecrt_slave_conf_sdo16(ec_slave_t *slave, uint16_t sdo_index,

   200

                          uint8_t sdo_subindex, uint16_t value);

   201

int ecrt_slave_conf_sdo32(ec_slave_t *slave, uint16_t sdo_index,

   202

                          uint8_t sdo_subindex, uint32_t value);

   203

   204

void ecrt_slave_pdo_mapping_clear(ec_slave_t *, ec_direction_t);

   205

int ecrt_slave_pdo_mapping_add(ec_slave_t *, ec_direction_t, uint16_t);

   206

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

   207

   208

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

   209

 * Bitwise read/write macros

   210

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

   211

   212

/** Read a certain bit of an EtherCAT data byte.

   213

 * \param DATA EtherCAT data pointer

   214

 * \param POS bit position

   215

 */

   216

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

   217

   218

/** Write a certain bit of an EtherCAT data byte.

   219

 * \param DATA EtherCAT data pointer

   220

 * \param POS bit position

   221

 * \param VAL new bit value

   222

 */

   223

#define EC_WRITE_BIT(DATA, POS, VAL) \

   224

    do { \

   225

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

   226

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

   227

    } while (0)

   228

   229

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

   230

 * Read macros

   231

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

   232

   233

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

   234

 * \return EtherCAT data value

   235

 */

   236

#define EC_READ_U8(DATA) \

   237

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

   238

   239

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

   240

 * \param DATA EtherCAT data pointer

   241

 * \return EtherCAT data value

   242

 */

   243

#define EC_READ_S8(DATA) \

   244

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

   245

   246

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

   247

 * \param DATA EtherCAT data pointer

   248

 * \return EtherCAT data value

   249

 */

   250

#define EC_READ_U16(DATA) \

   251

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

   252

   253

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

   254

 * \param DATA EtherCAT data pointer

   255

 * \return EtherCAT data value

   256

 */

   257

#define EC_READ_S16(DATA) \

   258

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

   259

   260

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

   261

 * \param DATA EtherCAT data pointer

   262

 * \return EtherCAT data value

   263

 */

   264

#define EC_READ_U32(DATA) \

   265

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

   266

   267

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

   268

 * \param DATA EtherCAT data pointer

   269

 * \return EtherCAT data value

   270

 */

   271

#define EC_READ_S32(DATA) \

   272

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

   273

   274

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

   275

 * Write macros

   276

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

   277

   278

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

   279

 * \param DATA EtherCAT data pointer

   280

 * \param VAL new value

   281

 */

   282

#define EC_WRITE_U8(DATA, VAL) \

   283

    do { \

   284

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

   285

    } while (0)

   286

   287

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

   288

 * \param DATA EtherCAT data pointer

   289

 * \param VAL new value

   290

 */

   291

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

   292

   293

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

   294

 * \param DATA EtherCAT data pointer

   295

 * \param VAL new value

   296

 */

   297

#define EC_WRITE_U16(DATA, VAL) \

   298

    do { \

   299

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

   300

        cpu_to_le16s(DATA); \

   301

    } while (0)

   302

   303

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

   304

 * \param DATA EtherCAT data pointer

   305

 * \param VAL new value

   306

 */

   307

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

   308

   309

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

   310

 * \param DATA EtherCAT data pointer

   311

 * \param VAL new value

   312

 */

   313

#define EC_WRITE_U32(DATA, VAL) \

   314

    do { \

   315

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

   316

        cpu_to_le32s(DATA); \

   317

    } while (0)

   318

   319

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

   320

 * \param DATA EtherCAT data pointer

   321

 * \param VAL new value

   322

 */

   323

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

   324

   325

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

   326

   327

#endif