1

/*

     2

This file is part of CanFestival, a library implementing CanOpen Stack. 

     3

     4

Copyright (C): Edouard TISSERANT and Francis DUPIN

     5

     6

See COPYING file for copyrights details.

     7

     8

This library is free software; you can redistribute it and/or

     9

modify it under the terms of the GNU Lesser General Public

    10

License as published by the Free Software Foundation; either

    11

version 2.1 of the License, or (at your option) any later version.

    12

    13

This library is distributed in the hope that it will be useful,

    14

but WITHOUT ANY WARRANTY; without even the implied warranty of

    15

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

    16

Lesser General Public License for more details.

    17

    18

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

    19

License along with this library; if not, write to the Free Software

    20

Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

    21

*/

    22

    23

/** @file

    24

 *  @brief Responsible for accessing the object dictionary.

    25

 *

    26

 *  This file contains functions for accessing the object dictionary and

    27

 *  variables that are contained by the object dictionary.

    28

 *  Accessing the object dictionary contains setting local variables

    29

 *  as PDOs and accessing (read/write) all entries of the object dictionary

    30

 *  @warning Only the basic entries of an object dictionary are included

    31

 *           at the moment.

    32

 */

    33

    34

/** @defgroup od Object Dictionary Management

    35

 *  @brief The Object Dictionary is the heart of each CANopen device containing all communication and application objects.

    36

 *  @ingroup userapi

    37

 */

    38

    39

#ifndef __objacces_h__

    40

#define __objacces_h__

    41

    42

#include <applicfg.h>

    43

    44

typedef UNS32 (*valueRangeTest_t)(UNS8 typeValue, void *Value);

    45

typedef void (* storeODSubIndex_t)(CO_Data* d, UNS16 wIndex, UNS8 bSubindex);

    46

void _storeODSubIndex (CO_Data* d, UNS16 wIndex, UNS8 bSubindex);

    47

    48

/**

    49

 * @ingroup od

    50

 * @brief Print MSG_WAR (s) if error to the access to the object dictionary occurs.

    51

 * 

    52

 * You must uncomment the lines in the file objaccess.c :\n

    53

 * //#define DEBUG_CAN\n

    54

 * //#define DEBUG_WAR_CONSOLE_ON\n

    55

 * //#define DEBUG_ERR_CONSOLE_ON\n\n

    56

 * Beware that sometimes, we force the sizeDataDict or sizeDataGiven to 0, when we wants to use

    57

 * this function but we do not have the access to the right value. One example is

    58

 * getSDOerror(). So do not take attention to these variables if they are null.

    59

 * @param index

    60

 * @param subIndex

    61

 * @param sizeDataDict Size of the data defined in the dictionary

    62

 * @param sizeDataGiven Size data given by the user.

    63

 * @param code error code to print. (SDO abort code. See file def.h)

    64

 * @return

    65

 */ 

    66

UNS8 accessDictionaryError(UNS16 index, UNS8 subIndex, 

    67

			   UNS32 sizeDataDict, UNS32 sizeDataGiven, UNS32 code);

    68

    69

    70

/* _getODentry() Reads an entry from the object dictionary.\n

    71

 * 

    72

 *    use getODentry() macro to read from object and endianize

    73

 *    use readLocalDict() macro to read from object and not endianize   

    74

 *

    75

 * @code

    76

 * // Example usage:

    77

 * UNS8  *pbData;

    78

 * UNS8 length;

    79

 * UNS32 returnValue;

    80

 *

    81

 * returnValue = getODentry( (UNS16)0x100B, (UNS8)1, 

    82

 * (void * *)&pbData, (UNS8 *)&length );

    83

 * if( returnValue != SUCCESSFUL )

    84

 * {

    85

 *     // error handling

    86

 * }

    87

 * @endcode 

    88

 * @param *d Pointer on a CAN object data structure

    89

 * @param wIndex The index in the object dictionary where you want to read

    90

 *               an entry

    91

 * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is

    92

 *                  used to tell you how many valid entries you can find

    93

 *                  in this index. Look at the canopen standard for further

    94

 *                  information

    95

 * @param *pDestData Pointer to the pointer which points to the variable where

    96

 *                   the value of this object dictionary entry should be copied

    97

 * @param pExpectedSize This function writes the size of the copied value (in Byte)

    98

 *                      into this variable.

    99

 * @param *pDataType Pointer on the type of the data. See objdictdef.h

   100

 * @param CheckAccess if other than 0, do not read if the data is Write Only

   101

 *                    [Not used today. Put always 0].

   102

 * @param Endianize  When not 0, data is endianized into network byte order

   103

 *                   when 0, data is not endianized and copied in machine native

   104

 *                   endianness 

   105

 * @return OD_SUCCESSFUL or SDO abort code. (See file def.h)

   106

 */

   107

UNS32 _getODentry( CO_Data* d, 

   108

		  UNS16 wIndex,

   109

		  UNS8 bSubindex,

   110

		  void * pDestData,

   111

		  UNS32 * pExpectedSize,

   112

		  UNS8 * pDataType,

   113

		  UNS8 checkAccess,

   114

		  UNS8 endianize);

   115

   116

/** 

   117

 * @ingroup od

   118

 * @brief getODentry() to read from object and endianize

   119

 * @param OD Pointer on a CAN object data structure

   120

 * @param wIndex The index in the object dictionary where you want to read

   121

 *                an entry

   122

 * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is

   123

 *                  used to tell you how many valid entries you can find

   124

 *                  in this index. Look at the canopen standard for further

   125

 *                  information

   126

 * @param *pDestData Pointer to the pointer which points to the variable where

   127

 *                   the value of this object dictionary entry should be copied

   128

 * @param pExpectedSize This function writes the size of the copied value (in Byte)

   129

 *                      into this variable.

   130

 * @param *pDataType Pointer on the type of the data. See objdictdef.h

   131

 * @param checkAccess if other than 0, do not read if the data is Write Only

   132

 *                    [Not used today. Put always 0].

   133

 * @param endianize  Set to 1 : endianized into network byte order 

   134

 * @return OD_SUCCESSFUL or SDO abort code. (See file def.h)

   135

 */

   136

#define getODentry( OD, wIndex, bSubindex, pDestData, pExpectedSize, \

   137

		          pDataType,  checkAccess)                         \

   138

       _getODentry( OD, wIndex, bSubindex, pDestData, pExpectedSize, \

   139

		          pDataType,  checkAccess, 1)            

   140

   141

/** 

   142

 * @ingroup od

   143

 * @brief readLocalDict() reads an entry from the object dictionary, but in 

   144

 * contrast to getODentry(), readLocalDict() doesn't endianize entry and reads

   145

 * entry in machine native endianness. 

   146

 * @param OD Pointer on a CAN object data structure

   147

 * @param wIndex The index in the object dictionary where you want to read

   148

 *                an entry

   149

 * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is

   150

 *                  used to tell you how many valid entries you can find

   151

 *                  in this index. Look at the canopen standard for further

   152

 *                  information

   153

 * @param *pDestData Pointer to the pointer which points to the variable where

   154

 *                   the value of this object dictionary entry should be copied

   155

 * @param pExpectedSize This function writes the size of the copied value (in Byte)

   156

 *                      into this variable.

   157

 * @param *pDataType Pointer on the type of the data. See objdictdef.h

   158

 * @param checkAccess if other than 0, do not read if the data is Write Only

   159

 *                    [Not used today. Put always 0].

   160

 * @param endianize Set to 0, data is not endianized and copied in machine native

   161

 *                  endianness 

   162

 * @return OD_SUCCESSFUL or SDO abort code. (See file def.h)

   163

 */

   164

#define readLocalDict( OD, wIndex, bSubindex, pDestData, pExpectedSize, \

   165

		          pDataType,  checkAccess)                         \

   166

       _getODentry( OD, wIndex, bSubindex, pDestData, pExpectedSize, \

   167

		          pDataType,  checkAccess, 0)

   168

   169

/**

   170

 * @brief By this function you can write an entry into the object dictionary

   171

 * @param *d Pointer on a CAN object data structure

   172

 * @param wIndex The index in the object dictionary where you want to write

   173

 *               an entry

   174

 * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is

   175

 *                  used to tell you how many valid entries you can find

   176

 *                  in this index. Look at the canopen standard for further

   177

 *                  information

   178

 * @param *pSourceData Pointer to the variable that holds the value that should

   179

 *                     be copied into the object dictionary

   180

 * @param *pExpectedSize The size of the value (in Byte).

   181

 * @param checkAccess if other than 0, do not read if the data is Read Only or Constant

   182

 * @param endianize When not 0, data is endianized into network byte order

   183

 *                  when 0, data is not endianized and copied in machine native

   184

 *                  endianness   

   185

 * @return OD_SUCCESSFUL or SDO abort code. (See file def.h)

   186

 */

   187

UNS32 _setODentry( CO_Data* d,

   188

                   UNS16 wIndex,

   189

                   UNS8 bSubindex,

   190

                   void * pSourceData,

   191

                   UNS32 * pExpectedSize,

   192

                   UNS8 checkAccess,

   193

                   UNS8 endianize);

   194

   195

/**

   196

 * @ingroup od

   197

 * @brief setODentry converts SourceData from network byte order to machine native 

   198

 * format, and writes that to OD.

   199

 * @code

   200

 * // Example usage:

   201

 * UNS8 B;

   202

 * B = 0xFF; // set transmission type

   203

 *

   204

 * retcode = setODentry( (UNS16)0x1800, (UNS8)2, &B, sizeof(UNS8), 1 );

   205

 * @endcode

   206

 * @param d Pointer on a CAN object data structure

   207

 * @param wIndex The index in the object dictionary where you want to write

   208

 *               an entry

   209

 * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is

   210

 *                  used to tell you how many valid entries you can find

   211

 *                  in this index. Look at the canopen standard for further

   212

 *                  information

   213

 * @param *pSourceData Pointer to the variable that holds the value that should

   214

 *                     be copied into the object dictionary

   215

 * @param *pExpectedSize The size of the value (in Byte).

   216

 * @param checkAccess if other than 0, do not read if the data is Read Only or Constant

   217

 * @param endianize Set to 1 : endianized into network byte order

   218

 * @return OD_SUCCESSFUL or SDO abort code. (See file def.h)

   219

 */

   220

#define setODentry( d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess) \

   221

       _setODentry( d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess, 1)

   222

   223

/**

   224

 * @ingroup od

   225

 * @brief Writes machine native SourceData to OD.

   226

 * @code

   227

 * // Example usage:

   228

 * UNS8 B;

   229

 * B = 0xFF; // set transmission type

   230

 *

   231

 * retcode = writeLocalDict( (UNS16)0x1800, (UNS8)2, &B, sizeof(UNS8), 1 );

   232

 * @endcode

   233

 * @param d Pointer on a CAN object data structure

   234

 * @param wIndex The index in the object dictionary where you want to write

   235

 *               an entry

   236

 * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is

   237

 *                  used to tell you how many valid entries you can find

   238

 *                  in this index. Look at the canopen standard for further

   239

 *                  information

   240

 * @param *pSourceData Pointer to the variable that holds the value that should

   241

 *                     be copied into the object dictionary

   242

 * @param *pExpectedSize The size of the value (in Byte).

   243

 * @param checkAccess if other than 0, do not read if the data is Read Only or Constant

   244

 * @param endianize Data is not endianized and copied in machine native endianness 

   245

 * @return OD_SUCCESSFUL or SDO abort code. (See file def.h)

   246

 */

   247

#define writeLocalDict( d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess) \

   248

       _setODentry( d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess, 0)

   249

   250

   251

   252

/**

   253

 * @brief Scan the index of object dictionary. Used only by setODentry and getODentry.

   254

 * @param *d Pointer on a CAN object data structure

   255

 * @param wIndex

   256

 * @param *errorCode :  OD_SUCCESSFUL if index foundor SDO abort code. (See file def.h)

   257

 * @param **Callback

   258

 * @return NULL if index not found. Else : return the table part of the object dictionary.

   259

 */

   260

 const indextable * scanIndexOD (CO_Data* d, UNS16 wIndex, UNS32 *errorCode, ODCallback_t **Callback);

   261

   262

UNS32 RegisterSetODentryCallBack(CO_Data* d, UNS16 wIndex, UNS8 bSubindex, ODCallback_t Callback);

   263

   264

#endif /* __objacces_h__ */