# HG changeset patch # User greg # Date 1247731617 -7200 # Node ID f9be4262c68d039f6b2f8d6070f34c027db6d294 # Parent 0bb927393dd0eee8439ff02f688a8ac31a24ef71 Add doxygen comments in headers file modify Doxyfile diff -r 0bb927393dd0 -r f9be4262c68d doc/doxygen/Doxyfile --- a/doc/doxygen/Doxyfile Wed Jul 15 17:19:09 2009 +0200 +++ b/doc/doxygen/Doxyfile Thu Jul 16 10:06:57 2009 +0200 @@ -287,23 +287,23 @@ # Private class members and static file members will be hidden unless # the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES -EXTRACT_ALL = YES +EXTRACT_ALL = NO # If the EXTRACT_PRIVATE tag is set to YES all private members of a class # will be included in the documentation. -EXTRACT_PRIVATE = YES +EXTRACT_PRIVATE = NO # If the EXTRACT_STATIC tag is set to YES all static members of a file # will be included in the documentation. -EXTRACT_STATIC = YES +EXTRACT_STATIC = NO # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) # defined locally in source files will be included in the documentation. # If set to NO only classes defined in header files are included. -EXTRACT_LOCAL_CLASSES = YES +EXTRACT_LOCAL_CLASSES = NO # This flag is only useful for Objective-C code. When set to YES local # methods, which are defined in the implementation section but not in @@ -326,21 +326,21 @@ # various overviews, but no documentation section is generated. # This option has no effect if EXTRACT_ALL is enabled. -HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_MEMBERS = YES # If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all # undocumented classes that are normally visible in the class hierarchy. # If set to NO (the default) these classes will be included in the various # overviews. This option has no effect if EXTRACT_ALL is enabled. -HIDE_UNDOC_CLASSES = NO +HIDE_UNDOC_CLASSES = YES # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all # friend (class|struct|union) declarations. # If set to NO (the default) these declarations will be included in the # documentation. -HIDE_FRIEND_COMPOUNDS = NO +HIDE_FRIEND_COMPOUNDS = YES # If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any # documentation blocks found inside the body of a function. @@ -454,13 +454,13 @@ # at the bottom of the documentation of classes and structs. If set to YES the # list will mention the files that were used to generate the documentation. -SHOW_USED_FILES = YES +SHOW_USED_FILES = NO # If the sources in your project are distributed over multiple directories # then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy # in the documentation. The default is NO. -SHOW_DIRECTORIES = YES +SHOW_DIRECTORIES = NO # Set the SHOW_FILES tag to NO to disable the generation of the Files page. # This will remove the Files entry from the Quick Index and from the @@ -544,8 +544,31 @@ # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = ../../include ../../src ../../drivers - +INPUT = \ +../../include/unix/canfestival.h \ +../../include/can.h \ +../../include/can_driver.h \ +../../include/data.h \ +../../include/emcy.h \ +../../include/nmtMaster.h \ +../../include/nmtSlave.h \ +../../include/pdo.h \ +../../include/sdo.h \ +../../include/timers_driver.h \ +../../include/timer.h \ +../../include/states.h \ +../../include/objacces.h \ +../../src/nmtMaster.c \ +../../drivers/unix/unix.c \ +../../drivers/win32/win32.cpp \ +../../src/timer.c \ +../../src/objacces.c \ +../../src/states.c \ +../../drivers/timers_unix/timers_unix.c \ +../../src/sdo.c \ +../../src/pdo.c + +#../../drivers/timers_win32/timers_win32.cpp \ # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is # also the default input encoding. Doxygen uses libiconv (or the iconv built diff -r 0bb927393dd0 -r f9be4262c68d include/can.h --- a/include/can.h Wed Jul 15 17:19:09 2009 +0200 +++ b/include/can.h Thu Jul 16 10:06:57 2009 +0200 @@ -20,16 +20,11 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ -/** - * @defgroup can CAN Management - * @ingroup userapi - */ - #ifndef __can_h__ #define __can_h__ #include "applicfg.h" -/** Used for the Can message structure */ + /* union SHORT_CAN { struct { UNS8 b0,b1; } b; @@ -45,16 +40,13 @@ /** * @brief The CAN message structure * @ingroup can - * @{ */ typedef struct { - UNS16 cob_id; /* l'ID du mesg */ - UNS8 rtr; /**< remote transmission request. 0 if not rtr, - 1 for a rtr message */ - UNS8 len; /**< message length (0 to 8) */ - UNS8 data[8]; /**< data */ + UNS16 cob_id; /**< message's ID */ + UNS8 rtr; /**< remote transmission request. (0 if not rtr message, 1 if rtr message) */ + UNS8 len; /**< message's length (0 to 8) */ + UNS8 data[8]; /**< message's datas */ } Message; -/** @} */ #define Message_Initializer {0,0,0,{0,0,0,0,0,0,0,0}} diff -r 0bb927393dd0 -r f9be4262c68d include/can_driver.h --- a/include/can_driver.h Wed Jul 15 17:19:09 2009 +0200 +++ b/include/can_driver.h Thu Jul 16 10:06:57 2009 +0200 @@ -1,5 +1,5 @@ /* -This file is part of CanFestival, a library implementing CanOpen Stack. +This file is part of CanFestival, a library implementing CanOpen Stack. Copyright (C): Edouard TISSERANT and Francis DUPIN @@ -30,16 +30,20 @@ #include "applicfg.h" #include "can.h" -/** - * @brief The CAN board configuration +/** + * @brief The CAN board configuration * @ingroup can - * @{ */ + +//struct struct_s_BOARD { +// char busname[100]; /**< The bus name on which the CAN board is connected */ +// char baudrate[4]; /**< The board baudrate */ +//}; + struct struct_s_BOARD { - char * busname; - char * baudrate; + char * busname; /**< The bus name on which the CAN board is connected */ + char * baudrate; /**< The board baudrate */ }; -/** @} */ #ifndef DLL_CALL #define DLL_CALL(funcname) funcname##_driver @@ -69,7 +73,7 @@ fc = m->cob_id >> 7; switch(fc) { - case SYNC: + case SYNC: if(m->cob_id == 0x080) MSG("SYNC "); else diff -r 0bb927393dd0 -r f9be4262c68d include/data.h --- a/include/data.h Wed Jul 15 17:19:09 2009 +0200 +++ b/include/data.h Thu Jul 16 10:06:57 2009 +0200 @@ -51,7 +51,7 @@ /** * @ingroup od - * @brief This structure contains all necessary information for a CanOpen node + * @brief This structure contains all necessary informations to define a CANOpen node */ struct struct_CO_Data { /* Object dictionary */ diff -r 0bb927393dd0 -r f9be4262c68d include/nmtMaster.h --- a/include/nmtMaster.h Wed Jul 15 17:19:09 2009 +0200 +++ b/include/nmtMaster.h Thu Jul 16 10:06:57 2009 +0200 @@ -35,49 +35,49 @@ /** * @ingroup nmtmaster - * @brief Transmit a NMT message on the bus number bus_id - * to the slave whose node_id is ID + * @brief Transmit a NMT message on the network to the slave whose nodeId is node ID. * - * bus_id is hardware dependant - * cs represents the order of state changement: - * - cs = NMT_Start_Node // Put the node in operational mode - * - cs = NMT_Stop_Node // Put the node in stopped mode - * - cs = NMT_Enter_PreOperational // Put the node in pre_operational mode - * - cs = NMT_Reset_Node // Put the node in initialization mode - * - cs = NMT_Reset_Comunication // Put the node in initialization mode + * @param *d Pointer to a CAN object data structure + * @param nodeId Id of the slave node + * @param cs The order of state changement \n\n + * + * Allowed states : + * - cs = NMT_Start_Node // Put the node in operational mode + * - cs = NMT_Stop_Node // Put the node in stopped mode + * - cs = NMT_Enter_PreOperational // Put the node in pre_operational mode + * - cs = NMT_Reset_Node // Put the node in initialization mode + * - cs = NMT_Reset_Comunication // Put the node in initialization mode + * * The mode is changed according to the slave state machine mode : * - initialisation ---> pre-operational (Automatic transition) * - pre-operational <--> operational * - pre-operational <--> stopped - * - pre-operational, operational, stopped -> initialisation\n - * @param *d Pointer on a CAN object data structure - * @param Node_ID Id of the slave node - * @param cs State changement - * @return canSend(bus_id,&m) + * - pre-operational, operational, stopped -> initialisation + * \n\n + * @return errorcode + * - 0 if the NMT message was send + * - 1 if an error occurs */ -UNS8 masterSendNMTstateChange (CO_Data* d, UNS8 Node_ID, UNS8 cs); +UNS8 masterSendNMTstateChange (CO_Data* d, UNS8 nodeId, UNS8 cs); /** * @ingroup nmtmaster - * @brief Transmit a Node_Guard message on the bus number bus_id - * to the slave whose node_id is nodeId + * @brief Transmit a NodeGuard message on the network to the slave whose nodeId is node ID * - * bus_id is hardware dependant - * @param *d Pointer on a CAN object data structure + * @param *d Pointer to a CAN object data structure * @param nodeId Id of the slave node - * @return canSend(bus_id,&m) + * @return + * - 0 is returned if the NodeGuard message was send. + * - 1 is returned if an error occurs. */ UNS8 masterSendNMTnodeguard (CO_Data* d, UNS8 nodeId); /** * @ingroup nmtmaster - * @brief Prepare a Node_Guard message transmission on the bus number bus_id - * to the slave whose node_id is nodeId + * @brief Ask the state of the slave node whose nodeId is node Id. * - * Put nodeId = 0 to send an NMT broadcast. - * This message will ask for the slave, whose node_id is nodeId, its state - * bus_id is hardware dependant - * @param *d Pointer on a CAN object data structure + * To ask states of all nodes on the network (NMT broadcast), nodeId must be equal to 0 + * @param *d Pointer to a CAN object data structure * @param nodeId Id of the slave node */ void masterRequestNodeState (CO_Data* d, UNS8 nodeId); diff -r 0bb927393dd0 -r f9be4262c68d include/nmtSlave.h --- a/include/nmtSlave.h Wed Jul 15 17:19:09 2009 +0200 +++ b/include/nmtSlave.h Thu Jul 16 10:06:57 2009 +0200 @@ -32,10 +32,9 @@ #include "data.h" /** - * @brief Threat the reception of a NMT message from the master - * bus_id is hardware dependant - * @param *d Pointer on the CAN data structure - * @param *m Pointer on the message received + * @brief Threat the reception of a NMT message from the master. + * @param *d Pointer to the CAN data structure + * @param *m Pointer to the message received * @return * - 0 if OK * - -1 if the slave is not allowed, by its state, to receive the message @@ -45,7 +44,6 @@ /** * @brief Transmit the boot-Up frame when the slave is moving from initialization * state to pre_operational state. - * bus_id is hardware dependant * @param *d Pointer on the CAN data structure * @return canSend(bus_id,&m) */ diff -r 0bb927393dd0 -r f9be4262c68d include/objacces.h --- a/include/objacces.h Wed Jul 15 17:19:09 2009 +0200 +++ b/include/objacces.h Thu Jul 16 10:06:57 2009 +0200 @@ -46,7 +46,6 @@ void _storeODSubIndex (CO_Data* d, UNS16 wIndex, UNS8 bSubindex); /** - * @ingroup od * @brief Print MSG_WAR (s) if error to the access to the object dictionary occurs. * * You must uncomment the lines in the file objaccess.c :\n @@ -85,7 +84,7 @@ * // error handling * } * @endcode - * @param *d Pointer on a CAN object data structure + * @param *d Pointer to a CAN object data structure * @param wIndex The index in the object dictionary where you want to read * an entry * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is @@ -96,13 +95,15 @@ * the value of this object dictionary entry should be copied * @param pExpectedSize This function writes the size of the copied value (in Byte) * into this variable. - * @param *pDataType Pointer on the type of the data. See objdictdef.h + * @param *pDataType Pointer to the type of the data. See objdictdef.h * @param CheckAccess if other than 0, do not read if the data is Write Only * [Not used today. Put always 0]. * @param Endianize When not 0, data is endianized into network byte order * when 0, data is not endianized and copied in machine native * endianness - * @return OD_SUCCESSFUL or SDO abort code. (See file def.h) + * @return + * - OD_SUCCESSFUL is returned upon success. + * - SDO abort code is returned if error occurs . (See file def.h) */ UNS32 _getODentry( CO_Data* d, UNS16 wIndex, @@ -116,7 +117,7 @@ /** * @ingroup od * @brief getODentry() to read from object and endianize - * @param OD Pointer on a CAN object data structure + * @param OD Pointer to a CAN object data structure * @param wIndex The index in the object dictionary where you want to read * an entry * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is @@ -127,11 +128,12 @@ * the value of this object dictionary entry should be copied * @param pExpectedSize This function writes the size of the copied value (in Byte) * into this variable. - * @param *pDataType Pointer on the type of the data. See objdictdef.h - * @param checkAccess if other than 0, do not read if the data is Write Only - * [Not used today. Put always 0]. + * @param *pDataType Pointer to the type of the data. See objdictdef.h + * @param checkAccess Flag that indicate if a check rights must be perfomed (0 : no , other than 0 : yes) * @param endianize Set to 1 : endianized into network byte order - * @return OD_SUCCESSFUL or SDO abort code. (See file def.h) + * @return + * - OD_SUCCESSFUL is returned upon success. + * - SDO abort code is returned if error occurs . (See file def.h) */ #define getODentry( OD, wIndex, bSubindex, pDestData, pExpectedSize, \ pDataType, checkAccess) \ @@ -143,7 +145,7 @@ * @brief readLocalDict() reads an entry from the object dictionary, but in * contrast to getODentry(), readLocalDict() doesn't endianize entry and reads * entry in machine native endianness. - * @param OD Pointer on a CAN object data structure + * @param OD Pointer to a CAN object data structure * @param wIndex The index in the object dictionary where you want to read * an entry * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is @@ -154,21 +156,22 @@ * the value of this object dictionary entry should be copied * @param pExpectedSize This function writes the size of the copied value (in Byte) * into this variable. - * @param *pDataType Pointer on the type of the data. See objdictdef.h + * @param *pDataType Pointer to the type of the data. See objdictdef.h * @param checkAccess if other than 0, do not read if the data is Write Only * [Not used today. Put always 0]. * @param endianize Set to 0, data is not endianized and copied in machine native * endianness - * @return OD_SUCCESSFUL or SDO abort code. (See file def.h) + * @return + * - OD_SUCCESSFUL is returned upon success. + * - SDO abort code is returned if error occurs . (See file def.h) */ #define readLocalDict( OD, wIndex, bSubindex, pDestData, pExpectedSize, \ pDataType, checkAccess) \ _getODentry( OD, wIndex, bSubindex, pDestData, pExpectedSize, \ pDataType, checkAccess, 0) -/** - * @brief By this function you can write an entry into the object dictionary - * @param *d Pointer on a CAN object data structure +/* By this function you can write an entry into the object dictionary + * @param *d Pointer to a CAN object data structure * @param wIndex The index in the object dictionary where you want to write * an entry * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is @@ -178,11 +181,13 @@ * @param *pSourceData Pointer to the variable that holds the value that should * be copied into the object dictionary * @param *pExpectedSize The size of the value (in Byte). - * @param checkAccess if other than 0, do not read if the data is Read Only or Constant + * @param checkAccess Flag that indicate if a check rights must be perfomed (0 : no , other than 0 : yes) * @param endianize When not 0, data is endianized into network byte order * when 0, data is not endianized and copied in machine native * endianness - * @return OD_SUCCESSFUL or SDO abort code. (See file def.h) + * @return + * - OD_SUCCESSFUL is returned upon success. + * - SDO abort code is returned if error occurs . (See file def.h) */ UNS32 _setODentry( CO_Data* d, UNS16 wIndex, @@ -203,7 +208,7 @@ * * retcode = setODentry( (UNS16)0x1800, (UNS8)2, &B, sizeof(UNS8), 1 ); * @endcode - * @param d Pointer on a CAN object data structure + * @param d Pointer to a CAN object data structure * @param wIndex The index in the object dictionary where you want to write * an entry * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is @@ -213,16 +218,37 @@ * @param *pSourceData Pointer to the variable that holds the value that should * be copied into the object dictionary * @param *pExpectedSize The size of the value (in Byte). - * @param checkAccess if other than 0, do not read if the data is Read Only or Constant + * @param checkAccess Flag that indicate if a check rights must be perfomed (0 : no , other than 0 : yes) * @param endianize Set to 1 : endianized into network byte order - * @return OD_SUCCESSFUL or SDO abort code. (See file def.h) - */ -#define setODentry( d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess) \ - _setODentry( d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess, 1) - -/** - * @ingroup od + * @return + * - OD_SUCCESSFUL is returned upon success. + * - SDO abort code is returned if error occurs . (See file def.h) + */ +#define setODentry( d, wIndex, bSubindex, pSourceData, pExpectedSize, \ + checkAccess) \ + _setODentry( d, wIndex, bSubindex, pSourceData, pExpectedSize, \ + checkAccess, 1) + +/** @fn UNS32 writeLocalDict(d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess) + * @ingroup od + * @hideinitializer * @brief Writes machine native SourceData to OD. + * @param d Pointer to a CAN object data structure + * @param wIndex The index in the object dictionary where you want to write + * an entry + * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is + * used to tell you how many valid entries you can find + * in this index. Look at the canopen standard for further + * information + * @param *pSourceData Pointer to the variable that holds the value that should + * be copied into the object dictionary + * @param *pExpectedSize The size of the value (in Byte). + * @param checkAccess Flag that indicate if a check rights must be perfomed (0 : no , other than 0 : yes) + * @param endianize Data is not endianized and copied in machine native endianness + * @return + * - OD_SUCCESSFUL is returned upon success. + * - SDO abort code is returned if error occurs . (See file def.h) + * \n\n * @code * // Example usage: * UNS8 B; @@ -230,19 +256,6 @@ * * retcode = writeLocalDict( (UNS16)0x1800, (UNS8)2, &B, sizeof(UNS8), 1 ); * @endcode - * @param d Pointer on a CAN object data structure - * @param wIndex The index in the object dictionary where you want to write - * an entry - * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is - * used to tell you how many valid entries you can find - * in this index. Look at the canopen standard for further - * information - * @param *pSourceData Pointer to the variable that holds the value that should - * be copied into the object dictionary - * @param *pExpectedSize The size of the value (in Byte). - * @param checkAccess if other than 0, do not read if the data is Read Only or Constant - * @param endianize Data is not endianized and copied in machine native endianness - * @return OD_SUCCESSFUL or SDO abort code. (See file def.h) */ #define writeLocalDict( d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess) \ _setODentry( d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess, 0) @@ -251,7 +264,7 @@ /** * @brief Scan the index of object dictionary. Used only by setODentry and getODentry. - * @param *d Pointer on a CAN object data structure + * @param *d Pointer to a CAN object data structure * @param wIndex * @param *errorCode : OD_SUCCESSFUL if index foundor SDO abort code. (See file def.h) * @param **Callback diff -r 0bb927393dd0 -r f9be4262c68d include/pdo.h --- a/include/pdo.h Wed Jul 15 17:19:09 2009 +0200 +++ b/include/pdo.h Thu Jul 16 10:06:57 2009 +0200 @@ -78,11 +78,13 @@ /** * @ingroup pdo - * @brief Transmit a PDO request frame on the bus bus_id - * to the slave. - * bus_id is hardware dependant + * @brief Transmit a PDO request frame on the network to the slave. * @param *d Pointer on a CAN object data structure * @param RPDOIndex Index of the receive PDO + * @return + * - CanFestival file descriptor is returned upon success. + * - 0xFF is returned if RPDO Index is not found. + * @return 0xFF if error, other in success. */ UNS8 sendPDOrequest( CO_Data* d, UNS16 RPDOIndex ); diff -r 0bb927393dd0 -r f9be4262c68d include/sdo.h --- a/include/sdo.h Wed Jul 15 17:19:09 2009 +0200 +++ b/include/sdo.h Thu Jul 16 10:06:57 2009 +0200 @@ -188,7 +188,6 @@ * to store a new SDO. * ie a line which value of the field "state" is "SDO_RESET" * An unused line have the field "state" at the value SDO_RESET - * bus_id is hardware dependant * @param *d Pointer on a CAN object data structure * @param whoami Create the line for a SDO_SERVER or SDO_CLIENT. * @param *line Pointer on a SDO line @@ -199,7 +198,6 @@ /** * @brief Search for the line, in the transfers array, which contains the * beginning of the reception of a fragmented SDO - * bus_id is hardware dependant * @param *d Pointer on a CAN object data structure * @param nodeId correspond to the message node-id * @param whoami takes 2 values : look for a line opened as SDO_CLIENT or SDO_SERVER @@ -218,7 +216,6 @@ /** * @brief Bytes in the line structure which must be transmited (or received) - * bus_id is hardware dependant. * @param *d Pointer on a CAN object data structure * @param line SDO line * @param *nbBytes Pointer on nbBytes @@ -228,7 +225,6 @@ /** * @brief Store in the line structure the nb of bytes which must be transmited (or received) - * bus_id is hardware dependant. * @param *d Pointer on a CAN object data structure * @param line SDO line * @param nbBytes @@ -238,7 +234,6 @@ /** * @brief Transmit a SDO frame on the bus bus_id - * bus_id is hardware dependant * @param *d Pointer on a CAN object data structure * @param whoami Takes 2 values : SDO_CLIENT or SDO_SERVER * @param sdo SDO Structure which contains the sdo to transmit @@ -264,7 +259,6 @@ /** * @brief Treat a SDO frame reception - * bus_id is hardware dependant * call the function sendSDO * @param *d Pointer on a CAN object data structure * @param *m Pointer on a CAN message structure @@ -277,17 +271,18 @@ /** * @ingroup sdo - * @brief Used by the application to send a SDO request frame to write the data *data - * at the index and subIndex indicated - * bus_id is hardware dependant - * @param *d Pointer on a CAN object data structure - * @param nodeId In the dictionary of the slave whose node_id is nodeId + * @brief Used to send a SDO request frame to write the data at the index and subIndex indicated + * @param *d Pointer to a CAN object data structure + * @param nodeId Node Id of the slave * @param index At index indicated * @param subIndex At subIndex indicated * @param count number of bytes to write in the dictionnary. * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value. - * @param *data Pointer on data - * @return 0xFF if error, else return 0 + * @param *data Pointer to data + * @return + * - 0 is returned upon success. + * - 0xFE is returned when no sdo client to communicate with node. + * - 0xFF is returned when error occurs. */ UNS8 writeNetworkDict (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS32 count, UNS8 dataType, void *data); @@ -295,17 +290,20 @@ /** * @ingroup sdo * @brief Used to send a SDO request frame to write in a distant node dictionnary. - * The function Callback which must be defined in the user code is called at the + * @details The function Callback which must be defined in the user code is called at the * end of the exchange. (on succes or abort). - * @param *d Pointer on a CAN object data structure - * @param nodeId In the dictionary of the slave whose node_id is nodeId + * @param *d Pointer to a CAN object data structure + * @param nodeId Node Id of the slave * @param index At index indicated * @param subIndex At subIndex indicated * @param count number of bytes to write in the dictionnary. * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value. - * @param *data Pointer on data + * @param *data Pointer to data * @param Callback Callback function - * @return 0xFF if error, else return 0 + * @return + * - 0 is returned upon success. + * - 0xFE is returned when no sdo client to communicate with node. + * - 0xFF is returned when error occurs. */ UNS8 writeNetworkDictCallBack (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS32 count, UNS8 dataType, void *data, SDOCallback_t Callback); @@ -313,115 +311,130 @@ /** * @ingroup sdo * @brief Used to send a SDO request frame to write in a distant node dictionnary. - * The function Callback which must be defined in the user code is called at the + * @details The function Callback which must be defined in the user code is called at the * end of the exchange. (on succes or abort). First free SDO client parameter is * automatically initialized for specific node if not already defined. - * @param *d Pointer on a CAN object data structure - * @param nodeId In the dictionary of the slave whose node_id is nodeId + * @param *d Pointer to a CAN object data structure + * @param nodeId Node Id of the slave * @param index At index indicated * @param subIndex At subIndex indicated * @param count number of bytes to write in the dictionnary. * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value. - * @param *data Pointer on data + * @param *data Pointer to data * @param Callback Callback function * @param endianize When not 0, data is endianized into network byte order * when 0, data is not endianized and copied in machine native * endianness - * @return 0xFF if error, else return 0 + * @return + * - 0 is returned upon success. + * - 0xFF is returned when error occurs. */ UNS8 writeNetworkDictCallBackAI (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS32 count, UNS8 dataType, void *data, SDOCallback_t Callback, UNS8 endianize); /** * @ingroup sdo - * @brief Used by the application to send a SDO request frame to read - * @param *d Pointer on a CAN object data structure - * @param nodeId In the dictionary of the slave whose node_id is nodeId - * @param index At index indicated - * @param subIndex At subIndex indicated - * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value. * bus_id is hardware dependant - * @return 0xFF if error, else return 0 + * @brief Used to send a SDO request frame to read. + * @param *d Pointer to a CAN object data structure + * @param nodeId Node Id of the slave + * @param index At index indicated + * @param subIndex At subIndex indicated + * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value. + * @return + * - 0 is returned upon success. + * - 0xFE is returned when no sdo client to communicate with node. + * - 0xFF is returned when error occurs. */ UNS8 readNetworkDict (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 dataType); /** * @ingroup sdo * @brief Used to send a SDO request frame to read in a distant node dictionnary. - * The function Callback which must be defined in the user code is called at the + * @details The function Callback which must be defined in the user code is called at the * end of the exchange. (on succes or abort). * @param *d Pointer on a CAN object data structure - * @param nodeId In the dictionary of the slave whose node_id is nodeId + * @param nodeId Node Id of the slave * @param index At index indicated * @param subIndex At subIndex indicated * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value. * @param Callback Callback function - * @return 0xFF if error, else return 0 + * @return + * - 0 is returned upon success. + * - 0xFE is returned when no sdo client to communicate with node. + * - 0xFF is returned when error occurs. */ UNS8 readNetworkDictCallback (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 dataType, SDOCallback_t Callback); /** * @ingroup sdo * @brief Used to send a SDO request frame to read in a distant node dictionnary. - * The function Callback which must be defined in the user code is called at the + * @details The function Callback which must be defined in the user code is called at the * end of the exchange. (on succes or abort). First free SDO client parameter is * automatically initialized for specific node if not already defined. * @param *d Pointer on a CAN object data structure - * @param nodeId In the dictionary of the slave whose node_id is nodeId + * @param nodeId Node Id of the slave * @param index At index indicated * @param subIndex At subIndex indicated * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value. * @param Callback Callback function - * @return 0xFF if error, else return 0 + * @return + * - 0 is returned upon success. + * - 0xFF is returned when error occurs. */ UNS8 readNetworkDictCallbackAI (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 dataType, SDOCallback_t Callback); /** * @ingroup sdo - * @brief Use this function after a readNetworkDict to get the result. - * @param *d Pointer on a CAN object data structure - * @param nodeId In the dictionary of the slave whose node_id is nodeId - * @param *data Pointer on data - * @param *size Pointer on size - * @param *abortCode Pointer on the abortcode. 0 = not available. Else : SDO abort code. (received if return SDO_ABORTED_RCV) + * @brief Use this function after calling readNetworkDict to get the result. + * + * @param *d Pointer to a CAN object data structure + * @param nodeId Node Id of the slave + * @param *data Pointer to the datas + * @param *size Pointer to the size + * @param *abortCode Pointer to the abortcode. (0 = not available. Else : SDO abort code. (received if return SDO_ABORTED_RCV) * * * @return - * - SDO_FINISHED // data is available - * - SDO_ABORTED_RCV // Transfert failed. (abort SDO received) - * - SDO_ABORTED_INTERNAL // Transfert failed. Internal abort. - * - SDO_UPLOAD_IN_PROGRESS // Data not yet available - * - SDO_DOWNLOAD_IN_PROGRESS // Should not arrive ! + * - SDO_FINISHED // datas are available + * - SDO_ABORTED_RCV // Transfert failed (abort SDO received) + * - SDO_ABORTED_INTERNAL // Transfert failed (internal abort) + * - SDO_UPLOAD_IN_PROGRESS // Datas are not yet available + * - SDO_DOWNLOAD_IN_PROGRESS // Download is in progress + * \n\n + * example : * @code - * example : * UNS32 data; * UNS8 size; * readNetworkDict(0, 0x05, 0x1016, 1, 0) // get the data index 1016 subindex 1 of node 5 - * while (getReadResultNetworkDict (0, 0x05, &data, &size) != SDO_UPLOAD_IN_PROGRESS); + * while (getReadResultNetworkDict (0, 0x05, &data, &size) == SDO_UPLOAD_IN_PROGRESS); * @endcode */ UNS8 getReadResultNetworkDict (CO_Data* d, UNS8 nodeId, void* data, UNS32 *size, UNS32 * abortCode); /** - * @brief Use this function after a writeNetworkDict to get the result of the write - * It is mandatory to call this function because it is releasing the line used for the transfer. - * @param *d Pointer on a CAN object data structure - * @param nodeId In the dictionary of the slave whose node_id is nodeId - * @param *abortCode Pointer on the abortcode. 0 = not available. Else : SDO abort code. (received if return SDO_ABORTED_RCV) + * @ingroup sdo + * @brief Use this function after calling writeNetworkDict function to get the result of the write. + * @details It is mandatory to call this function because it is releasing the line used for the transfer. + * @param *d Pointer to a CAN object data structure + * @param nodeId Node Id of the slave + * @param *abortCode Pointer to the abortcode + * - 0 = not available. + * - SDO abort code (received if return SDO_ABORTED_RCV) * * @return : - * - SDO_FINISHED // data is available - * - SDO_ABORTED_RCV // Transfert failed. (abort SDO received) - * - SDO_ABORTED_INTERNAL // Transfert failed. Internal abort. - * - SDO_DOWNLOAD_IN_PROGRESS // Data not yet available - * - SDO_UPLOAD_IN_PROGRESS // Should not arrive ! - * + * - SDO_FINISHED // datas are available + * - SDO_ABORTED_RCV // Transfert failed (abort SDO received) + * - SDO_ABORTED_INTERNAL // Transfert failed (Internal abort) + * - SDO_DOWNLOAD_IN_PROGRESS // Datas are not yet available + * - SDO_UPLOAD_IN_PROGRESS // Upload in progress + * \n\n + * example : * @code - * example : * UNS32 data = 0x50; * UNS8 size; * UNS32 abortCode; * writeNetworkDict(0, 0x05, 0x1016, 1, size, &data) // write the data index 1016 subindex 1 of node 5 - * while (getWriteResultNetworkDict (0, 0x05, &abortCode) != SDO_DOWNLOAD_IN_PROGRESS); + * while (getWriteResultNetworkDict (0, 0x05, &abortCode) == SDO_DOWNLOAD_IN_PROGRESS); * @endcode */ UNS8 getWriteResultNetworkDict (CO_Data* d, UNS8 nodeId, UNS32 * abortCode); diff -r 0bb927393dd0 -r f9be4262c68d include/timer.h --- a/include/timer.h Wed Jul 15 17:19:09 2009 +0200 +++ b/include/timer.h Thu Jul 16 10:06:57 2009 +0200 @@ -1,5 +1,5 @@ /* -This file is part of CanFestival, a library implementing CanOpen Stack. +This file is part of CanFestival, a library implementing CanOpen Stack. Copyright (C): Edouard TISSERANT and Francis DUPIN @@ -53,12 +53,40 @@ /* --------- prototypes --------- */ /*#define SetAlarm(d, id, callback, value, period) printf("%s, %d, SetAlarm(%s, %s, %s, %s, %s)\n",__FILE__, __LINE__, #d, #id, #callback, #value, #period); _SetAlarm(d, id, callback, value, period)*/ +/** + * @ingroup timer + * @brief Set an alarm to execute a callback function when expired. + * @param *d Pointer to a CAN object data structure + * @param id The alarm Id + * @param callback A callback function + * @param value Call the callback function at current time + value + * @param period Call periodically the callback function + * @return handle The timer handle + */ TIMER_HANDLE SetAlarm(CO_Data* d, UNS32 id, TimerCallback_t callback, TIMEVAL value, TIMEVAL period); + +/** + * @ingroup timer + * @brief Delete an alarm before expiring. + * @param handle A timer handle + * @return The timer handle + */ TIMER_HANDLE DelAlarm(TIMER_HANDLE handle); + void TimeDispatch(void); -/* --------- to be defined in user app ---------*/ +/** + * @ingroup timer + * @brief Set a timerfor a given time. + * @param value The time value. + */ void setTimer(TIMEVAL value); + +/** + * @ingroup timer + * @brief Get the time elapsed since latest timer occurence. + * @return time elapsed since latest timer occurence + */ TIMEVAL getElapsedTime(void); #endif /* #define __timer_h__ */ diff -r 0bb927393dd0 -r f9be4262c68d include/timers_driver.h --- a/include/timers_driver.h Wed Jul 15 17:19:09 2009 +0200 +++ b/include/timers_driver.h Thu Jul 16 10:06:57 2009 +0200 @@ -31,6 +31,8 @@ #include "timer.h" // For use from CAN driver + + /** * @ingroup timer * @brief Acquire mutex @@ -42,12 +44,12 @@ * @brief Release mutex */ void LeaveMutex(void); + void WaitReceiveTaskEnd(TASK_HANDLE*); /** * @ingroup timer - * @brief Initialize Timer - * + * @brief Initialize Timer */ void TimerInit(void); @@ -70,7 +72,6 @@ * @param Callback A callback function */ void StopTimerLoop(TimerCallback_t Callback); -/** @} */ /** * @brief Stop the timer task diff -r 0bb927393dd0 -r f9be4262c68d include/unix/canfestival.h --- a/include/unix/canfestival.h Wed Jul 15 17:19:09 2009 +0200 +++ b/include/unix/canfestival.h Thu Jul 16 10:06:57 2009 +0200 @@ -24,59 +24,64 @@ /** * @ingroup can - * @{ - */ - -/** - * @ingroup can * @brief Unload CAN driver interface * @param handle The library handle - * @return 0 if succes + * @return + * - 0 is returned upon success. + * - -1 is returned if the CAN driver interface can't be unloaded. */ UNS8 UnLoadCanDriver(LIB_HANDLE handle); /** * @ingroup can - * @brief Load CAN driver interface + * @brief Load CAN driver interface. * @param *driver_name The location of the library to load - * @return handle The library handle + * @return + * - handle of the CAN driver interface is returned upon success. + * - NULL is returned if the CAN driver interface can't be loaded. */ LIB_HANDLE LoadCanDriver(const char* driver_name); /** * @brief Send a CAN message * @param port CanFestival file descriptor - * @param *m The message to send + * @param *m The CAN message to send * @return 0 if succes */ UNS8 canSend(CAN_PORT port, Message *m); /** * @ingroup can - * @brief Open a CANopen device - * @param *board Pointer on the board structure that contains busname and baudrate - * @param *d Pointer on the CAN object data structure - * @return port CanFestival file descriptor + * @brief Open a CANOpen device + * @param *board Pointer to the board structure that contains busname and baudrate + * @param *d Pointer to the CAN object data structure + * @return + * - CanFestival file descriptor is returned upon success. + * - NULL is returned if the CANOpen board can't be opened. */ CAN_PORT canOpen(s_BOARD *board, CO_Data * d); /** * @ingroup can - * @brief Close a CANopen device - * @param *d Pointer on the CAN object data structure - * @return 0 if succes + * @brief Close a CANOpen device + * @param *d Pointer to the CAN object data structure + * @return + * - 0 is returned upon success. + * - errorcode if error. (if implemented) */ int canClose(CO_Data * d); /** * @ingroup can - * @brief Change the CANopen device baudrate + * @brief Change the CANOpen device baudrate * @param port CanFestival file descriptor * @param *baud The new baudrate to assign - * @return 0 if succes + * @return + * - 0 is returned upon success or if not supported by the CAN driver. + * - errorcode from the CAN driver is returned if an error occurs. (if implemented in the CAN driver) */ UNS8 canChangeBaudRate(CAN_PORT port, char* baud); -/** @} */ + #ifdef __cplusplus