include/objacces.h

   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__ */