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

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

    50

 * 

    51

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

    52

 * //#define DEBUG_CAN\n

    53

 * //#define DEBUG_WAR_CONSOLE_ON\n

    54

 * //#define DEBUG_ERR_CONSOLE_ON\n\n

    55

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

    56

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

    57

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

    58

 * @param index

    59

 * @param subIndex

    60

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

    61

 * @param sizeDataGiven Size data given by the user.

    62

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

    63

 * @return

    64

 */ 

    65

UNS8 accessDictionaryError(UNS16 index, UNS8 subIndex, 

    66

			   UNS32 sizeDataDict, UNS32 sizeDataGiven, UNS32 code);

    67

    68

    69

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

    70

 * 

    71

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

    72

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

    73

 *

    74

 * @code

    75

 * // Example usage:

    76

 * UNS8  *pbData;

    77

 * UNS8 length;

    78

 * UNS32 returnValue;

    79

 *

    80

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

    81

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

    82

 * if( returnValue != SUCCESSFUL )

    83

 * {

    84

 *     // error handling

    85

 * }

    86

 * @endcode 

    87

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

    88

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

    89

 *               an entry

    90

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

    91

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

    92

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

    93

 *                  information

    94

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

    95

 *                   the value of this object dictionary entry should be copied

    96

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

    97

 *                      into this variable.

    98

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

    99

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

   100

 *                    [Not used today. Put always 0].

   101

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

   102

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

   103

 *                   endianness 

   104

 * @return 

   105

 * - OD_SUCCESSFUL is returned upon success. 

   106

 * - SDO abort code is returned if error occurs . (See file def.h)

   107

 */

   108

UNS32 _getODentry( CO_Data* d, 

   109

		  UNS16 wIndex,

   110

		  UNS8 bSubindex,

   111

		  void * pDestData,

   112

		  UNS32 * pExpectedSize,

   113

		  UNS8 * pDataType,

   114

		  UNS8 checkAccess,

   115

		  UNS8 endianize);

   116

   117

/** 

   118

 * @ingroup od

   119

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

   120

 * @param OD Pointer to a CAN object data structure

   121

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

   122

 *                an entry

   123

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

   124

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

   125

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

   126

 *                  information

   127

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

   128

 *                   the value of this object dictionary entry should be copied

   129

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

   130

 *                      into this variable.

   131

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

   132

 * @param checkAccess Flag that indicate if a check rights must be perfomed (0 : no , other than 0 : yes)

   133

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

   134

 * @return 

   135

 * - OD_SUCCESSFUL is returned upon success. 

   136

 * - SDO abort code is returned if error occurs . (See file def.h)

   137

 */

   138

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

   139

		          pDataType,  checkAccess)                         \

   140

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

   141

		          pDataType,  checkAccess, 1)            

   142

   143

/** 

   144

 * @ingroup od

   145

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

   146

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

   147

 * entry in machine native endianness. 

   148

 * @param OD Pointer to a CAN object data structure

   149

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

   150

 *                an entry

   151

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

   152

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

   153

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

   154

 *                  information

   155

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

   156

 *                   the value of this object dictionary entry should be copied

   157

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

   158

 *                      into this variable.

   159

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

   160

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

   161

 *                    [Not used today. Put always 0].

   162

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

   163

 *                  endianness 

   164

 * @return 

   165

 * - OD_SUCCESSFUL is returned upon success. 

   166

 * - SDO abort code is returned if error occurs . (See file def.h)

   167

 */

   168

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

   169

		          pDataType,  checkAccess)                         \

   170

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

   171

		          pDataType,  checkAccess, 0)

   172

   173

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

   174

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

   175

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

   176

 *               an entry

   177

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

   178

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

   179

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

   180

 *                  information

   181

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

   182

 *                     be copied into the object dictionary

   183

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

   184

 * @param checkAccess Flag that indicate if a check rights must be perfomed (0 : no , other than 0 : yes)

   185

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

   186

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

   187

 *                  endianness   

   188

 * @return 

   189

 * - OD_SUCCESSFUL is returned upon success. 

   190

 * - SDO abort code is returned if error occurs . (See file def.h)

   191

 */

   192

UNS32 _setODentry( CO_Data* d,

   193

                   UNS16 wIndex,

   194

                   UNS8 bSubindex,

   195

                   void * pSourceData,

   196

                   UNS32 * pExpectedSize,

   197

                   UNS8 checkAccess,

   198

                   UNS8 endianize);

   199

   200

/**

   201

 * @ingroup od

   202

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

   203

 * format, and writes that to OD.

   204

 * @code

   205

 * // Example usage:

   206

 * UNS8 B;

   207

 * B = 0xFF; // set transmission type

   208

 *

   209

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

   210

 * @endcode

   211

 * @param d Pointer to a CAN object data structure

   212

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

   213

 *               an entry

   214

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

   215

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

   216

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

   217

 *                  information

   218

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

   219

 *                     be copied into the object dictionary

   220

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

   221

 * @param checkAccess Flag that indicate if a check rights must be perfomed (0 : no , other than 0 : yes)

   222

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

   223

 * @return 

   224

 * - OD_SUCCESSFUL is returned upon success. 

   225

 * - SDO abort code is returned if error occurs . (See file def.h)

   226

 */

   227

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

   228

                  checkAccess) \

   229

       _setODentry( d, wIndex, bSubindex, pSourceData, pExpectedSize, \

   230

                  checkAccess, 1)

   231

   232

/** @fn UNS32 writeLocalDict(d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess)

   233

 * @ingroup od

   234

 * @hideinitializer

   235

 * @brief Writes machine native SourceData to OD.

   236

 * @param d Pointer to a CAN object data structure

   237

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

   238

 *               an entry

   239

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

   240

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

   241

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

   242

 *                  information

   243

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

   244

 *                     be copied into the object dictionary

   245

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

   246

 * @param checkAccess Flag that indicate if a check rights must be perfomed (0 : no , other than 0 : yes)

   247

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

   248

 * @return 

   249

 * - OD_SUCCESSFUL is returned upon success. 

   250

 * - SDO abort code is returned if error occurs . (See file def.h)

   251

 * \n\n

   252

 * @code

   253

 * // Example usage:

   254

 * UNS8 B;

   255

 * B = 0xFF; // set transmission type

   256

 *

   257

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

   258

 * @endcode

   259

 */

   260

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

   261

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

   262

   263

   264

   265

/**

   266

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

   267

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

   268

 * @param wIndex

   269

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

   270

 * @param **Callback

   271

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

   272

 */

   273

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

   274

   275

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

   276

   277

#endif /* __objacces_h__ */