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  *  @ingroup userapi
  36  */
  37
  38 #ifndef __objacces_h__
  39 #define __objacces_h__
  40
  41 #include <applicfg.h>
  42
  43 typedef UNS32 (*valueRangeTest_t)(UNS8 typeValue, void *Value);
  44 typedef void (* storeODSubIndex_t)(CO_Data* d, UNS16 wIndex, UNS8 bSubindex);
  45 void _storeODSubIndex (CO_Data* d, UNS16 wIndex, UNS8 bSubindex);
  46
  47 /**
  48  * @ingroup od
  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                            UNS8 sizeDataDict, UNS8 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 on 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 on 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 OD_SUCCESSFUL or SDO abort code. (See file def.h)
 105  */
 106 UNS32 _getODentry( CO_Data* d,
 107                   UNS16 wIndex,
 108                   UNS8 bSubindex,
 109                   void * pDestData,
 110                   UNS8 * pExpectedSize,
 111                   UNS8 * pDataType,
 112                   UNS8 checkAccess,
 113                   UNS8 endianize);
 114
 115 /**
 116  * @ingroup od
 117  * @brief getODentry() to read from object and endianize
 118  * @param OD Pointer on a CAN object data structure
 119  * @param wIndex The index in the object dictionary where you want to read
 120  *                an entry
 121  * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is
 122  *                  used to tell you how many valid entries you can find
 123  *                  in this index. Look at the canopen standard for further
 124  *                  information
 125  * @param *pDestData Pointer to the pointer which points to the variable where
 126  *                   the value of this object dictionary entry should be copied
 127  * @param pExpectedSize This function writes the size of the copied value (in Byte)
 128  *                      into this variable.
 129  * @param *pDataType Pointer on the type of the data. See objdictdef.h
 130  * @param checkAccess if other than 0, do not read if the data is Write Only
 131  *                    [Not used today. Put always 0].
 132  * @param endianize  Set to 1 : endianized into network byte order
 133  * @return OD_SUCCESSFUL or SDO abort code. (See file def.h)
 134  */
 135 #define getODentry( OD, wIndex, bSubindex, pDestData, pExpectedSize, \
 136                           pDataType,  checkAccess)                         \
 137        _getODentry( OD, wIndex, bSubindex, pDestData, pExpectedSize, \
 138                           pDataType,  checkAccess, 1)
 139
 140 /**
 141  * @ingroup od
 142  * @brief readLocalDict() reads an entry from the object dictionary, but in
 143  * contrast to getODentry(), readLocalDict() doesn't endianize entry and reads
 144  * entry in machine native endianness.
 145  * @param OD Pointer on a CAN object data structure
 146  * @param wIndex The index in the object dictionary where you want to read
 147  *                an entry
 148  * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is
 149  *                  used to tell you how many valid entries you can find
 150  *                  in this index. Look at the canopen standard for further
 151  *                  information
 152  * @param *pDestData Pointer to the pointer which points to the variable where
 153  *                   the value of this object dictionary entry should be copied
 154  * @param pExpectedSize This function writes the size of the copied value (in Byte)
 155  *                      into this variable.
 156  * @param *pDataType Pointer on the type of the data. See objdictdef.h
 157  * @param checkAccess if other than 0, do not read if the data is Write Only
 158  *                    [Not used today. Put always 0].
 159  * @param endianize Set to 0, data is not endianized and copied in machine native
 160  *                  endianness
 161  * @return OD_SUCCESSFUL or SDO abort code. (See file def.h)
 162  */
 163 #define readLocalDict( OD, wIndex, bSubindex, pDestData, pExpectedSize, \
 164                           pDataType,  checkAccess)                         \
 165        _getODentry( OD, wIndex, bSubindex, pDestData, pExpectedSize, \
 166                           pDataType,  checkAccess, 0)
 167
 168 /**
 169  * @brief By this function you can write an entry into the object dictionary
 170  * @param *d Pointer on a CAN object data structure
 171  * @param wIndex The index in the object dictionary where you want to write
 172  *               an entry
 173  * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is
 174  *                  used to tell you how many valid entries you can find
 175  *                  in this index. Look at the canopen standard for further
 176  *                  information
 177  * @param *pSourceData Pointer to the variable that holds the value that should
 178  *                     be copied into the object dictionary
 179  * @param *pExpectedSize The size of the value (in Byte).
 180  * @param checkAccess if other than 0, do not read if the data is Read Only or Constant
 181  * @param endianize When not 0, data is endianized into network byte order
 182  *                  when 0, data is not endianized and copied in machine native
 183  *                  endianness
 184  * @return OD_SUCCESSFUL or SDO abort code. (See file def.h)
 185  */
 186 UNS32 _setODentry( CO_Data* d,
 187                    UNS16 wIndex,
 188                    UNS8 bSubindex,
 189                    void * pSourceData,
 190                    UNS8 * pExpectedSize,
 191                    UNS8 checkAccess,
 192                    UNS8 endianize);
 193
 194 /**
 195  * @ingroup od
 196  * @brief setODentry converts SourceData from network byte order to machine native
 197  * format, and writes that to OD.
 198  * @code
 199  * // Example usage:
 200  * UNS8 B;
 201  * B = 0xFF; // set transmission type
 202  *
 203  * retcode = setODentry( (UNS16)0x1800, (UNS8)2, &B, sizeof(UNS8), 1 );
 204  * @endcode
 205  * @param d Pointer on a CAN object data structure
 206  * @param wIndex The index in the object dictionary where you want to write
 207  *               an entry
 208  * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is
 209  *                  used to tell you how many valid entries you can find
 210  *                  in this index. Look at the canopen standard for further
 211  *                  information
 212  * @param *pSourceData Pointer to the variable that holds the value that should
 213  *                     be copied into the object dictionary
 214  * @param *pExpectedSize The size of the value (in Byte).
 215  * @param checkAccess if other than 0, do not read if the data is Read Only or Constant
 216  * @param endianize Set to 1 : endianized into network byte order
 217  * @return OD_SUCCESSFUL or SDO abort code. (See file def.h)
 218  */
 219 #define setODentry( d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess) \
 220        _setODentry( d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess, 1)
 221
 222 /**
 223  * @ingroup od
 224  * @brief Writes machine native SourceData to OD.
 225  * @code
 226  * // Example usage:
 227  * UNS8 B;
 228  * B = 0xFF; // set transmission type
 229  *
 230  * retcode = writeLocalDict( (UNS16)0x1800, (UNS8)2, &B, sizeof(UNS8), 1 );
 231  * @endcode
 232  * @param d Pointer on a CAN object data structure
 233  * @param wIndex The index in the object dictionary where you want to write
 234  *               an entry
 235  * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is
 236  *                  used to tell you how many valid entries you can find
 237  *                  in this index. Look at the canopen standard for further
 238  *                  information
 239  * @param *pSourceData Pointer to the variable that holds the value that should
 240  *                     be copied into the object dictionary
 241  * @param *pExpectedSize The size of the value (in Byte).
 242  * @param checkAccess if other than 0, do not read if the data is Read Only or Constant
 243  * @param endianize Data is not endianized and copied in machine native endianness
 244  * @return OD_SUCCESSFUL or SDO abort code. (See file def.h)
 245  */
 246 #define writeLocalDict( d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess) \
 247        _setODentry( d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess, 0)
 248
 249
 250
 251 /**
 252  * @brief Scan the index of object dictionary. Used only by setODentry and getODentry.
 253  * @param *d Pointer on a CAN object data structure
 254  * @param wIndex
 255  * @param *errorCode :  OD_SUCCESSFUL if index foundor SDO abort code. (See file def.h)
 256  * @param **Callback
 257  * @return NULL if index not found. Else : return the table part of the object dictionary.
 258  */
 259  const indextable * scanIndexOD (CO_Data* d, UNS16 wIndex, UNS32 *errorCode, ODCallback_t **Callback);
 260
 261 UNS32 RegisterSetODentryCallBack(CO_Data* d, UNS16 wIndex, UNS8 bSubindex, ODCallback_t Callback);
 262
 263 #endif /* __objacces_h__ */