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 #ifndef __objacces_h__
  35 #define __objacces_h__
  36
  37 #include <applicfg.h>
  38
  39 typedef UNS32 (*valueRangeTest_t)(UNS8 typeValue, void *Value);
  40 typedef void (* storeODSubIndex_t)(CO_Data* d, UNS16 wIndex, UNS8 bSubindex);
  41 void _storeODSubIndex (CO_Data* d, UNS16 wIndex, UNS8 bSubindex);
  42
  43 /*
  44 Print MSG_WAR (s) if error to the access to the object dictionary occurs.
  45 You must uncomment the lines
  46 //#define DEBUG_CAN
  47 //#define DEBUG_WAR_CONSOLE_ON
  48 //#define DEBUG_ERR_CONSOLE_ON
  49 in the file objaccess.c
  50 sizeDataDict : Size of the data defined in the dictionary
  51 sizeDataGiven : Size data given by the user.
  52 code : error code to print. (SDO abort code. See file def.h)
  53 Beware that sometimes, we force the sizeDataDict or sizeDataGiven to 0, when we wants to use
  54 this function but we do not have the access to the right value. One example is
  55 getSDOerror(). So do not take attention to these variables if they are null.
  56 */
  57
  58 UNS8 accessDictionaryError(UNS16 index, UNS8 subIndex,
  59                            UNS8 sizeDataDict, UNS8 sizeDataGiven, UNS32 code);
  60
  61
  62 /* _getODentry() Reads an entry from the object dictionary.\n
  63  *
  64  *    use getODentry() macro to read from object and endianize
  65  *    use readLocalDict() macro to read from object and not endianize
  66  *
  67  *  \code
  68  *  // Example usage:
  69  *  UNS8  *pbData;
  70  *  UNS8 length;
  71  *  UNS32 returnValue;
  72  *
  73  *  returnValue = getODentry( (UNS16)0x100B, (UNS8)1,
  74  *  (void * *)&pbData, (UNS8 *)&length );
  75  *  if( returnValue != SUCCESSFUL )
  76  *  {
  77  *      // error handling
  78  *  }
  79  *  \endcode
  80  *  \param wIndex The index in the object dictionary where you want to read
  81  *                an entry
  82  *  \param bSubindex The subindex of the Index. e.g. mostly subindex 0 is
  83  *                   used to tell you how many valid entries you can find
  84  *                   in this index. Look at the canopen standard for further
  85  *                   information
  86  *  \param ppbData Pointer to the pointer which points to the variable where
  87  *                 the value of this object dictionary entry should be copied
  88  *  \param pdwSize This function writes the size of the copied value (in Byte)
  89  *                 into this variable.
  90  *  \param pDataType : The type of the data. See objdictdef.h
  91  *  \param CheckAccess if other than 0, do not read if the data is Write Only
  92  *                     [Not used today. Put always 0].
  93  *  \param Endianize  when not 0, data is endianized into network byte order
  94  *                    when 0, data is not endianized and copied in machine native
  95  *                    endianness
  96  *  \return OD_SUCCESSFUL or SDO abort code. (See file def.h)
  97  */
  98 UNS32 _getODentry( CO_Data* d,
  99                   UNS16 wIndex,
 100                   UNS8 bSubindex,
 101                   void * pDestData,
 102                   UNS8 * pExpectedSize,
 103                   UNS8 * pDataType,
 104                   UNS8 checkAccess,
 105                   UNS8 endianize);
 106
 107 #define getODentry( OD, wIndex, bSubindex, pDestData, pExpectedSize, \
 108                           pDataType,  checkAccess)                         \
 109        _getODentry( OD, wIndex, bSubindex, pDestData, pExpectedSize, \
 110                           pDataType,  checkAccess, 1)
 111
 112 /*
 113  * readLocalDict() reads an entry from the object dictionary, but in
 114  * contrast to getODentry(), readLocalDict() doesn't endianize entry and reads
 115  * entry in machine native endianness.
 116  */
 117 #define readLocalDict( OD, wIndex, bSubindex, pDestData, pExpectedSize, \
 118                           pDataType,  checkAccess)                         \
 119        _getODentry( OD, wIndex, bSubindex, pDestData, pExpectedSize, \
 120                           pDataType,  checkAccess, 0)
 121
 122 /* By this function you can write an entry into the object dictionary\n
 123  *  \code
 124  *  // Example usage:
 125  *  UNS8 B;
 126  *  B = 0xFF; // set transmission type
 127  *
 128  *  retcode = setODentry( (UNS16)0x1800, (UNS8)2, &B, sizeof(UNS8), 1 );
 129  *  \endocde
 130  *  \param wIndex The index in the object dictionary where you want to write
 131  *                an entry
 132  *  \param bSubindex The subindex of the Index. e.g. mostly subindex 0 is
 133  *                   used to tell you how many valid entries you can find
 134  *                   in this index. Look at the canopen standard for further
 135  *                   information
 136  *  \param pbData Pointer to the variable that holds the value that should
 137  *                 be copied into the object dictionary
 138  *  \param dwSize The size of the value (in Byte).
 139  *  \param CheckAccess if other than 0, do not read if the data is Read Only or Constant
 140  *  \return OD_SUCCESSFUL or SDO abort code. (See file def.h)
 141  */
 142 UNS32 _setODentry( CO_Data* d,
 143                    UNS16 wIndex,
 144                    UNS8 bSubindex,
 145                    void * pSourceData,
 146                    UNS8 * pExpectedSize,
 147                    UNS8 checkAccess,
 148                    UNS8 endianize);
 149
 150 /*
 151  * setODentry converts SourceData from network byte order to machine native
 152  *            format, and writes that to OD.
 153  */
 154 #define setODentry( d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess) \
 155        _setODentry( d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess, 1)
 156
 157 /*
 158  * writeLocalDict writes machine native SourceData to OD.
 159  */
 160 #define writeLocalDict( d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess) \
 161        _setODentry( d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess, 0)
 162
 163
 164
 165 /* Scan the index of object dictionary. Used only by setODentry and getODentry.
 166  *  *errorCode :  OD_SUCCESSFUL if index foundor SDO abort code. (See file def.h)
 167  *  Return NULL if index not found. Else : return the table part of the object dictionary.
 168  */
 169  const indextable * scanIndexOD (CO_Data* d, UNS16 wIndex, UNS32 *errorCode, ODCallback_t **Callback);
 170
 171 UNS32 RegisterSetODentryCallBack(CO_Data* d, UNS16 wIndex, UNS8 bSubindex, ODCallback_t Callback);
 172
 173 #endif /* __objacces_h__ */