/************************************************************************ *            CANopenNode drvTemplate/CO_driver.h hacking * 说明： *     使用CANopenNode，drvTemplate/CO_driver.h说明了一些驱动编写相关的 * 注意事项。 * *                                    2017-3-24 深圳 南山平山村 曾剑锋 ***********************************************************************//** * CAN module object for generic microcontroller. * * This file is a template for other microcontrollers. * * @file        CO_driver.h * @ingroup     CO_driver * @author      Janez Paternoster * @copyright   2004 - 2015 Janez Paternoster * * This file is part of CANopenNode, an opensource CANopen Stack. * Project home page is <https://github.com/CANopenNode/CANopenNode>. * For more information on CANopen see <http://www.can-cia.org/>. * * CANopenNode is free and open source software: you can redistribute * it and/or modify it under the terms of the GNU General Public License * as published by the Free Software Foundation, either version 2 of the * License, or (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program. If not, see <http://www.gnu.org/licenses/>. * * Following clarification and special exception to the GNU General Public * License is included to the distribution terms of CANopenNode: * * Linking this library statically or dynamically with other modules is * making a combined work based on this library. Thus, the terms and * conditions of the GNU General Public License cover the whole combination. * * As a special exception, the copyright holders of this library give * you permission to link this library with independent modules to * produce an executable, regardless of the license terms of these * independent modules, and to copy and distribute the resulting * executable under terms of your choice, provided that you also meet, * for each linked independent module, the terms and conditions of the * license of that module. An independent module is a module which is * not derived from or based on this library. If you modify this * library, you may extend this exception to your version of the * library, but you are not obliged to do so. If you do not wish * to do so, delete this exception statement from your version. */#ifndef CO_DRIVER_H#define CO_DRIVER_H/* Include processor header file *//** * 将这里的头文件替换成与处理器相关的头文件，譬如： *   1. STM32： *     #include "common.h" *     #include "stm32f10x_conf.h" *   2. SocketCAN： *      #include <stddef.h>         /* for ‘NULL‘ */ *      #include <stdint.h>         /* for ‘int8_t‘ to ‘uint64_t‘ */ *      #include <stdbool.h>        /* for ‘true‘, ‘false‘ */ *      #include <unistd.h> *      #include <endian.h> *       *      #ifndef CO_SINGLE_THREAD *      #include <pthread.h> *      #endif *       *      #include <linux/can.h> *      #include <linux/can/raw.h> *      #include <linux/can/error.h> */#include <stddef.h>         /* for ‘NULL‘ */#include <stdint.h>         /* for ‘int8_t‘ to ‘uint64_t‘ */#include <stdbool.h>        /* for ‘true‘, ‘false‘ *//** * @defgroup CO_driver Driver * @ingroup CO_CANopen * @{ * * Microcontroller specific code for CANopenNode. * 微控制器CANopenNode专用代码 * * This file contains type definitions, functions and macros for: * 该文件包含为用于以下目的的类型定义，函数，宏 *  - Basic data types. *    基础数据类型 *  - Receive and transmit buffers for CANopen messages. *    CANopen信息发送和接收缓冲区 *  - Interaction with CAN module on the microcontroller. *    在微控制器上和CAN模块进行交互 *  - CAN receive and transmit interrupts. *    CAN信息接收和发送中断 * * This file is not only a CAN driver. There are no classic CAN queues for CAN * messages. This file provides direct connection with other CANopen * objects. It tries to provide fast responses and tries to avoid unnecessary * calculations and memory consumptions. * 这份文件不仅仅是用于CAN驱动，这里没有典型的处理CAN消息的队列，通过直接连接其他的CANopen的对象， * 主要是为了提供最快的响应速度来避免不必要的计算和内存消耗 * * CO_CANmodule_t contains an array of _Received message objects_ (of type * CO_CANrx_t) and an array of _Transmit message objects_ (of type CO_CANtx_t). * Each CANopen communication object owns one member in one of the arrays. * For example Heartbeat producer generates one CANopen transmitting object, * so it has reserved one member in CO_CANtx_t array. * SYNC module may produce sync or consume sync, so it has reserved one member * in CO_CANtx_t and one member in CO_CANrx_t array. * CO_CANmodule_t两个数组，一个是发送消息对象CO_CANrx_t，一个是接收信息的对象CO_CANtx_t， * 每一个CANopen通信对象在数组中拥有一个成员，例如： *   1. 心跳包生产者产生一个CANopen传输对象，所以他收到一个成员在CO_CANtx_t数组中。 *   2. 同步模块可能会产生sync和消费sync，所以他保留了一个成员在CO_CANtx_t中，也 *     保留一个在CO_CANrx_t中 * * ###Reception of CAN messages. * Before CAN messages can be received, each member in CO_CANrx_t must be * initialized. CO_CANrxBufferInit() is called by CANopen module, which * uses specific member. For example @ref CO_HBconsumer uses multiple members * in CO_CANrx_t array. (It monitors multiple heartbeat messages from remote * nodes.) It must call CO_CANrxBufferInit() multiple times. * 在CAN消息被接收之前，每一个CO_CANrx_t需要先被初始化，CO_CANrxBufferInit被CANopen模块 * 调用，有些特定的成员被使用，例如CO_HBconsumer使用了CO_CANrx_t多个成员，其监视远程节点 * 上的多个心跳包，所以被CO_CANrxBufferInit()调用多次。 * * Main arguments to the CO_CANrxBufferInit() function are CAN identifier * and a pointer to callback function. Those two arguments (and some others) * are copied to the member of the CO_CANrx_t array. * CO_CANrxBufferInit()主要参数是： *   1. CAN identifier； *   2. 回调的函数指针； * 这两个参数（也许包括其他的）都会被作为成员拷贝的CO_CANrx_t数组中。 * * Callback function is a function, specified by specific CANopen module * (for example by @ref CO_HBconsumer). Each CANopen module defines own * callback function. Callback function will process the received CAN message. * It will copy the necessary data from CAN message to proper place. It may * also trigger additional task, which will further process the received message. * Callback function must be fast and must only make the necessary calculations * and copying. * 回调函数是一个函数，处理特定的CANopen模块相关数据，每一个CANopen模块定义了他们 * 自己的回调函数，回调函数将处理接收到的CAN信息。他将从CAN信息中拷贝必要的数据到 * 合适的地方，当然他也可以触发额外的任务，额外的任务会进一步处理接收到的信息。 * 回调函数必须处理迅速，仅仅做那些必要的数据运算以及拷贝。 * * Received CAN messages are processed by CAN receive interrupt function. * After CAN message is received, function first tries to find matching CAN * identifier from CO_CANrx_t array. If found, then a corresponding callback * function is called. * 接收CAN信息是由CAN接收中断函数进行处理的，在接收完数据之后，函数会尝试从CO_CANrx_t * 中去查找匹配的CAN identifier，如果被找到，那么正确的回调函数就会被调用。 * * Callback function accepts two parameters: * 回调函数接收两个参数 *  - object is pointer to object registered by CO_CANrxBufferInit(). *    CO_CANrxBufferInit()中注册的对象指针 *  - msg  is pointer to CAN message of type CO_CANrxMsg_t. *    CO_CANrxMsg_t类型的CAN信息指针 * * Callback function must return #CO_ReturnError_t: CO_ERROR_NO, * CO_ERROR_RX_OVERFLOW, CO_ERROR_RX_PDO_OVERFLOW, CO_ERROR_RX_MSG_LENGTH or * CO_ERROR_RX_PDO_LENGTH. * 回调函数必须是返回如下CO_ReturnError_t类型的数据。 * * * ###Transmission of CAN messages. * Before CAN messages can be transmitted, each member in CO_CANtx_t must be * initialized. CO_CANtxBufferInit() is called by CANopen module, which * uses specific member. For example Heartbeat producer must initialize it‘s * member in CO_CANtx_t array. * 在CAN消息被发送之前，CO_CANtx_t必须先被初始化，CO_CANtxBufferInit()被CANopen模块调用， * 会使用指定的成员，例如，心跳包产生者必须在CO_CANtx_t中初始化成员。 * * CO_CANtxBufferInit() returns a pointer of type CO_CANtx_t, which contains buffer * where CAN message data can be written. CAN message is send with calling * CO_CANsend() function. If at that moment CAN transmit buffer inside * microcontroller‘s CAN module is free, message is copied directly to CAN module. * Otherwise CO_CANsend() function sets _bufferFull_ flag to true. Message will be * then sent by CAN TX interrupt as soon as CAN module is freed. Until message is * not copied to CAN module, its contents must not change. There may be multiple * _bufferFull_ flags in CO_CANtx_t array set to true. In that case messages with * lower index inside array will be sent first. * CO_CANtxBufferInit()返回CO_CANtx_t类型的指针，其中包含CAN信息可以被写入的数据缓冲区， * CAN信息通过CO_CANsend()函数进行发送，如果微处理器的CAN模块的CAN输出传输缓冲区被释放， * CAN信息将直接被拷贝进CAN模块中。 * 另外CO_CANsend()函数设置_bufferFull_标志位true，消息将会被CAN模块尽快发送，在信息被 * 拷贝到CAN模块之前，信息是不能被篡改的。因此，在CO_CANtx_t数组中，会有很多的_bufferFull_ * 标志是true，在这种情况下，小的index会先被发送出去。 *//** * @name Critical sections * CANopenNode is designed to run in different threads, as described in README. * Threads are implemented differently in different systems. In microcontrollers * threads are interrupts with different priorities, for example. * It is necessary to protect sections, where different threads access to the * same resource. In simple systems interrupts or scheduler may be temporary * disabled between access to the shared resource. Otherwise mutexes or * semaphores can be used. * 如同在README中描述的，CANopenNode被设计于运行于不同的线程。 * 线程在不同的系统中，实现的方式也是不同的，在微处理器中线程采用不同的优先级的中断来完成，例如 * 像多个线程都要访问的部分是需要被保护的，在系统中这部分共享资源在访问的时候要关闭中断和任务调度， * 当然想互斥和信号量也是可以使用的。 * * ####Reentrant functions. * Functions CO_CANsend() from C_driver.h, CO_errorReport() from CO_Emergency.h * and CO_errorReset() from CO_Emergency.h may be called from different threads. * Critical sections must be protected. Eather by disabling scheduler or * interrupts or by mutexes or semaphores. * 函数CO_CANsend()是在C_driver.h中的，CO_errorReport()/CO_errorReset()是在CO_Emergency.h中， * 他们都可能被任何线程调用，敏感的部分必须要被保护，需要采用禁止任务切换、中断，或者 * 采用互斥、信号量来处理。 * * ####Object Dictionary variables. * In general, there are two threads, which accesses OD variables: mainline and * timer. CANopenNode initialization and SDO server runs in mainline. PDOs runs * in faster timer thread. Processing of PDOs must not be interrupted by * mainline. Mainline thread must protect sections, which accesses the same OD * variables as timer thread. This care must also take the application. Note * that not all variables are allowed to be mapped to PDOs, so they may not need * to be protected. SDO server protects sections with access to OD variables. * 通常情况下，有两个线程会访问对象字典变量：主线程和定时器。CANopenNode初始化和SDO服务 * 运行于主线程，PDOs运行于快速定时器线程，PDO的处理不能被mainline打断。因为对象字典 * 能够同时被主线程、定时器访问，所以需要专门被保护，在引用层也是需要注意的。不过需要 * 注意的是，并不是所有的PDO的对象都允许被映射，可能不需要被保护。 * * ####CAN receive thread. * It partially processes received CAN data and puts them into appropriate * objects. Objects are later processed. It does not need protection of * critical sections. There is one circumstance, where CANrx should be disabled: * After presence of SYNC message on CANopen bus, CANrx should be temporary * disabled until all receive PDOs are processed. See also CO_SYNC.h file and * CO_SYNC_initCallback() function. * 专门处理CAN数据，并将其放到合适对象里，这些对象会被稍后处理，这是不需要被特殊处理的部分。 * 这是一个事件，CANrx应该被关闭，在获取到SYNC的信息的时候，CANrx应该被短暂的关闭直到PDO信息 * 被处理，请查看CO_SYNC.h文件和CO_SYNC_initCallback()函数 * @{ */    #define CO_LOCK_CAN_SEND()  /**< Lock critical section in CO_CANsend() */    #define CO_UNLOCK_CAN_SEND()/**< Unlock critical section in CO_CANsend() */    #define CO_LOCK_EMCY()      /**< Lock critical section in CO_errorReport() or CO_errorReset() */    #define CO_UNLOCK_EMCY()    /**< Unlock critical section in CO_errorReport() or CO_errorReset() */    #define CO_LOCK_OD()        /**< Lock critical section when accessing Object Dictionary */    #define CO_UNLOCK_OD()      /**< Unock critical section when accessing Object Dictionary *//** @} *//** * @defgroup CO_dataTypes Data types * @{ * * According to Misra C */    /* int8_t to uint64_t are defined in stdint.h */    typedef unsigned char           bool_t;     /**< bool_t */    typedef float                   float32_t;  /**< float32_t */    typedef long double             float64_t;  /**< float64_t */    typedef char                    char_t;     /**< char_t */    typedef unsigned char           oChar_t;    /**< oChar_t */    typedef unsigned char           domain_t;   /**< domain_t *//** @} *//** * Return values of some CANopen functions. If function was executed * successfully it returns 0 otherwise it returns <0. */typedef enum{    CO_ERROR_NO                 = 0,    /**< Operation completed successfully */    CO_ERROR_ILLEGAL_ARGUMENT   = -1,   /**< Error in function arguments */    CO_ERROR_OUT_OF_MEMORY      = -2,   /**< Memory allocation failed */    CO_ERROR_TIMEOUT            = -3,   /**< Function timeout */    CO_ERROR_ILLEGAL_BAUDRATE   = -4,   /**< Illegal baudrate passed to function CO_CANmodule_init() */    CO_ERROR_RX_OVERFLOW        = -5,   /**< Previous message was not processed yet */    CO_ERROR_RX_PDO_OVERFLOW    = -6,   /**< previous PDO was not processed yet */    CO_ERROR_RX_MSG_LENGTH      = -7,   /**< Wrong receive message length */    CO_ERROR_RX_PDO_LENGTH      = -8,   /**< Wrong receive PDO length */    CO_ERROR_TX_OVERFLOW        = -9,   /**< Previous message is still waiting, buffer full */    CO_ERROR_TX_PDO_WINDOW      = -10,  /**< Synchronous TPDO is outside window */    CO_ERROR_TX_UNCONFIGURED    = -11,  /**< Transmit buffer was not confugured properly */    CO_ERROR_PARAMETERS         = -12,  /**< Error in function function parameters */    CO_ERROR_DATA_CORRUPT       = -13,  /**< Stored data are corrupt */    CO_ERROR_CRC                = -14   /**< CRC does not match */}CO_ReturnError_t;/** * CAN receive message structure as aligned in CAN module. It is different in * different microcontrollers. It usually contains other variables. */typedef struct{    /** CAN identifier. It must be read through CO_CANrxMsg_readIdent() function. */    uint32_t            ident;    uint8_t             DLC ;           /**< Length of CAN message */    uint8_t             data[8];        /**< 8 data bytes */}CO_CANrxMsg_t;/** * Received message object */typedef struct{    uint16_t            ident;          /**< Standard CAN Identifier (bits 0..10) + RTR (bit 11) */    uint16_t            mask;           /**< Standard Identifier mask with same alignment as ident */    void               *object;         /**< From CO_CANrxBufferInit() */    void              (*pFunct)(void *object, const CO_CANrxMsg_t *message);  /**< From CO_CANrxBufferInit() */}CO_CANrx_t;/** * Transmit message object. */typedef struct{    uint32_t            ident;          /**< CAN identifier as aligned in CAN module */    uint8_t             DLC ;           /**< Length of CAN message. (DLC may also be part of ident) */    uint8_t             data[8];        /**< 8 data bytes */    volatile bool_t     bufferFull;     /**< True if previous message is still in buffer */    /** Synchronous PDO messages has this flag set. It prevents them to be sent outside the synchronous window */    volatile bool_t     syncFlag;}CO_CANtx_t;/** * CAN module object. It may be different in different microcontrollers. */typedef struct{    int32_t             CANbaseAddress; /**< From CO_CANmodule_init() */    CO_CANrx_t         *rxArray;        /**< From CO_CANmodule_init() */    uint16_t            rxSize;         /**< From CO_CANmodule_init() */    CO_CANtx_t         *txArray;        /**< From CO_CANmodule_init() */    uint16_t            txSize;         /**< From CO_CANmodule_init() */    volatile bool_t     CANnormal;      /**< CAN module is in normal mode */    /** Value different than zero indicates, that CAN module hardware filters      * are used for CAN reception. If there is not enough hardware filters,      * they won‘t be used. In this case will be *all* received CAN messages      * processed by software. */    volatile bool_t     useCANrxFilters;    /** If flag is true, then message in transmitt buffer is synchronous PDO      * message, which will be aborted, if CO_clearPendingSyncPDOs() function      * will be called by application. This may be necessary if Synchronous      * window time was expired. */    volatile bool_t     bufferInhibitFlag;    /** Equal to 1, when the first transmitted message (bootup message) is in CAN TX buffers */    volatile bool_t     firstCANtxMessage;    /** Number of messages in transmit buffer, which are waiting to be copied to the CAN module */    volatile uint16_t   CANtxCount;    uint32_t            errOld;         /**< Previous state of CAN errors */    void               *em;             /**< Emergency object */}CO_CANmodule_t;/** * Endianes. * 大小端的问题 * * Depending on processor or compiler architecture, one of the two macros must * be defined: CO_LITTLE_ENDIAN or CO_BIG_ENDIAN. CANopen itself is little endian. * 依赖于处理和编译器架构，这两个宏其中之一要被定义，cANopen本身是小端的。 */#define CO_LITTLE_ENDIAN/** * Request CAN configuration (stopped) mode and *wait* untill it is set. * 请求CAN配置参数(停止)模式并直到被设置 * * @param CANbaseAddress CAN module base address. */void CO_CANsetConfigurationMode(int32_t CANbaseAddress);/** * Request CAN normal (opearational) mode and *wait* untill it is set. * 请求cAN普通(操作)模式并直到被设置 * * @param CANmodule This object. */void CO_CANsetNormalMode(CO_CANmodule_t *CANmodule);/** * Initialize CAN module object. * 初始化CAN模块对象 * * Function must be called in the communication reset section. CAN module must * be in Configuration Mode before. * * @param CANmodule This object will be initialized. * @param CANbaseAddress CAN module base address. * @param rxArray Array for handling received CAN messages * @param rxSize Size of the above array. Must be equal to number of receiving CAN objects. * @param txArray Array for handling transmitting CAN messages * @param txSize Size of the above array. Must be equal to number of transmitting CAN objects. * @param CANbitRate Valid values are (in kbps): 10, 20, 50, 125, 250, 500, 800, 1000. * If value is illegal, bitrate defaults to 125. * * Return #CO_ReturnError_t: CO_ERROR_NO or CO_ERROR_ILLEGAL_ARGUMENT. */CO_ReturnError_t CO_CANmodule_init(        CO_CANmodule_t         *CANmodule,        int32_t                 CANbaseAddress,        CO_CANrx_t              rxArray[],        uint16_t                rxSize,        CO_CANtx_t              txArray[],        uint16_t                txSize,        uint16_t                CANbitRate);/** * Switch off CANmodule. Call at program exit. * 关闭CAN模块，程序的最后需要被调用 * * @param CANmodule CAN module object. */void CO_CANmodule_disable(CO_CANmodule_t *CANmodule);/** * Read CAN identifier from received message * 获取CAN identifier从接受到的信息中 * * @param rxMsg Pointer to received message * @return 11-bit CAN standard identifier. */uint16_t CO_CANrxMsg_readIdent(const CO_CANrxMsg_t *rxMsg);/** * Configure CAN message receive buffer. * 配置CAN信息接收缓冲区 * * Function configures specific CAN receive buffer. It sets CAN identifier * and connects buffer with specific object. Function must be called for each * member in _rxArray_ from CO_CANmodule_t. * * @param CANmodule This object. * @param index Index of the specific buffer in _rxArray_. * @param ident 11-bit standard CAN Identifier. * @param mask 11-bit mask for identifier. Most usually set to 0x7FF. * Received message (rcvMsg) will be accepted if the following * condition is true: (((rcvMsgId ^ ident) & mask) == 0). * @param rtr If true, ‘Remote Transmit Request‘ messages will be accepted. * @param object CANopen object, to which buffer is connected. It will be used as * an argument to pFunct. Its type is (void), pFunct will change its * type back to the correct object type. * @param pFunct Pointer to function, which will be called, if received CAN * message matches the identifier. It must be fast function. * * Return #CO_ReturnError_t: CO_ERROR_NO CO_ERROR_ILLEGAL_ARGUMENT or * CO_ERROR_OUT_OF_MEMORY (not enough masks for configuration). */CO_ReturnError_t CO_CANrxBufferInit(        CO_CANmodule_t         *CANmodule,        uint16_t                index,        uint16_t                ident,        uint16_t                mask,        bool_t                  rtr,        void                   *object,        void                  (*pFunct)(void *object, const CO_CANrxMsg_t *message));/** * Configure CAN message transmit buffer. * 配置CAN信息发送缓冲区 * * Function configures specific CAN transmit buffer. Function must be called for * each member in _txArray_ from CO_CANmodule_t. * * @param CANmodule This object. * @param index Index of the specific buffer in _txArray_. * @param ident 11-bit standard CAN Identifier. * @param rtr If true, ‘Remote Transmit Request‘ messages will be transmitted. * @param noOfBytes Length of CAN message in bytes (0 to 8 bytes). * @param syncFlag This flag bit is used for synchronous TPDO messages. If it is set, * message will not be sent, if curent time is outside synchronous window. * * @return Pointer to CAN transmit message buffer. 8 bytes data array inside * buffer should be written, before CO_CANsend() function is called. * Zero is returned in case of wrong arguments. */CO_CANtx_t *CO_CANtxBufferInit(        CO_CANmodule_t         *CANmodule,        uint16_t                index,        uint16_t                ident,        bool_t                  rtr,        uint8_t                 noOfBytes,        bool_t                  syncFlag);/** * Send CAN message. * 发送信息函数 * * @param CANmodule This object. * @param buffer Pointer to transmit buffer, returned by CO_CANtxBufferInit(). * Data bytes must be written in buffer before function call. * * @return #CO_ReturnError_t: CO_ERROR_NO, CO_ERROR_TX_OVERFLOW or * CO_ERROR_TX_PDO_WINDOW (Synchronous TPDO is outside window). */CO_ReturnError_t CO_CANsend(CO_CANmodule_t *CANmodule, CO_CANtx_t *buffer);/** * Clear all synchronous TPDOs from CAN module transmit buffers. * 在CAN模块中的发送缓冲区清除所有的同步TPDO * * CANopen allows synchronous PDO communication only inside time between SYNC * message and SYNC Window. If time is outside this window, new synchronous PDOs * must not be sent and all pending sync TPDOs, which may be on CAN TX buffers, * must be cleared. * * This function checks (and aborts transmission if necessary) CAN TX buffers * when it is called. Function should be called by the stack in the moment, * when SYNC time was just passed out of synchronous window. * * @param CANmodule This object. */void CO_CANclearPendingSyncPDOs(CO_CANmodule_t *CANmodule);/** * Verify all errors of CAN module. * 校验所有的额错误CAN模块 * * Function is called directly from CO_EM_process() function. * * @param CANmodule This object. */void CO_CANverifyErrors(CO_CANmodule_t *CANmodule);/** * Receives and transmits CAN messages. * 接收、发送CAN信息 * * Function must be called directly from high priority CAN interrupt. * * @param CANmodule This object. */void CO_CANinterrupt(CO_CANmodule_t *CANmodule);/** @} */#endif