EtherCAT主站IGH-- 2 -- IGH之coe_emerg

EtherCAT主站IGH-- 2 -- IGH之coe_emerg_ring.h/c文件解析

0 预览
一该文件功能
- `coe_emerg_ring.c` 文件功能函数预览
二函数功能介绍
- `coe_emerg_ring.c` 中主要函数的作用
- - - 1. `ec_coe_emerg_ring_init`
    - 2. `ec_coe_emerg_ring_clear`
    - 3. `ec_coe_emerg_ring_size`
    - 4. `ec_coe_emerg_ring_push`
    - 5. `ec_coe_emerg_ring_pop`
    - 6. `ec_coe_emerg_ring_clear_ring`
    - 7. `ec_coe_emerg_ring_overruns`
三 h文件翻译
四 c文件翻译
该文档修改记录：
总结

0 预览

一该文件功能

该文件定义了 EtherCAT CoE 紧急环形缓冲区的方法。EtherCAT 是一种实时以太网通信标准，广泛用于工业自动化控制系统。紧急环形缓冲区用于处理从站配置中的紧急消息，通过紧急消息环缓冲区，系统可以在有限的内存中存储并管理来自从站的紧急消息。

`coe_emerg_ring.c` 文件功能函数预览

函数	功能和用途	使用场景
`ec_coe_emerg_ring_init`	初始化 EtherCAT CoE 紧急环形缓冲区。	在应用程序启动时进行紧急环形缓冲区的初始化。
`ec_coe_emerg_ring_clear`	清理 EtherCAT CoE 紧急环形缓冲区。	在应用程序关闭或设备不再使用时进行清理操作。
`ec_coe_emerg_ring_size`	设置紧急环形缓冲区的大小。	在初始化或需要更改环形缓冲区大小时调用。
`ec_coe_emerg_ring_push`	添加一个新的紧急消息到环形缓冲区。	在接收到新的紧急消息时调用。
`ec_coe_emerg_ring_pop`	从环形缓冲区中移除一个紧急消息。	在需要处理或读取紧急消息时调用。
`ec_coe_emerg_ring_clear_ring`	清空环形缓冲区。	在需要清空紧急消息环形缓冲区时调用。
`ec_coe_emerg_ring_overruns`	读取环形缓冲区的溢出次数。	在需要获取环形缓冲区溢出次数时调用。

二函数功能介绍

`coe_emerg_ring.c` 中主要函数的作用

1. `ec_coe_emerg_ring_init`

void ec_coe_emerg_ring_init(
        ec_coe_emerg_ring_t *ring, /**< Emergency ring. */
        ec_slave_config_t *sc /**< Slave configuration. */
        )
{
    ring->sc = sc;
    ring->msgs = NULL;
    ring->size = 0;
    ring->read_index = 0;
    ring->write_index = 0;
    ring->overruns = 0;
}

功能和用途：初始化 EtherCAT CoE 紧急环形缓冲区。
使用场景：在应用程序启动时进行紧急环形缓冲区的初始化。

2. `ec_coe_emerg_ring_clear`

void ec_coe_emerg_ring_clear(
        ec_coe_emerg_ring_t *ring /**< Emergency ring. */
        )
{
    if (ring->msgs) {
        kfree(ring->msgs);
    }
}

功能和用途：清理 EtherCAT CoE 紧急环形缓冲区。
使用场景：在应用程序关闭或设备不再使用时进行清理操作。

3. `ec_coe_emerg_ring_size`

int ec_coe_emerg_ring_size(
        ec_coe_emerg_ring_t *ring, /**< Emergency ring. */
        size_t size /**< Maximum number of messages in the ring. */
        )
{
    ring->size = 0;

    if (size < 0) {
        size = 0;
    }

    ring->read_index = ring->write_index = 0;

    if (ring->msgs) {
        kfree(ring->msgs);
    }
    ring->msgs = NULL;

    if (size == 0) {
        return 0;
    }

    ring->msgs = kmalloc(sizeof(ec_coe_emerg_msg_t) * (size + 1), GFP_KERNEL);
    if (!ring->msgs) {
        return -ENOMEM;
    }

    ring->size = size;
    return 0;
}

功能和用途：设置紧急环形缓冲区的大小。
使用场景：在初始化或需要更改环形缓冲区大小时调用。

4. `ec_coe_emerg_ring_push`

void ec_coe_emerg_ring_push(
        ec_coe_emerg_ring_t *ring, /**< Emergency ring. */
        const u8 *msg /**< Emergency message. */
        )
{
    if (!ring->size ||
            (ring->write_index + 1) % (ring->size + 1) == ring->read_index) {
        ring->overruns++;
        return;
    }

    memcpy(ring->msgs[ring->write_index].data, msg,
            EC_COE_EMERGENCY_MSG_SIZE);
    ring->write_index = (ring->write_index + 1) % (ring->size + 1);
}

功能和用途：添加一个新的紧急消息到环形缓冲区。
使用场景：在接收到新的紧急消息时调用。

5. `ec_coe_emerg_ring_pop`

int ec_coe_emerg_ring_pop(
        ec_coe_emerg_ring_t *ring, /**< Emergency ring. */
        u8 *msg /**< Memory to store the emergency message. */
        )
{
    if (ring->read_index == ring->write_index) {
        return -ENOENT;
    }

    memcpy(msg, ring->msgs[ring->read_index].data, EC_COE_EMERGENCY_MSG_SIZE);
    ring->read_index = (ring->read_index + 1) % (ring->size + 1);
    return 0;
}

功能和用途：从环形缓冲区中移除一个紧急消息。
使用场景：在需要处理或读取紧急消息时调用。

6. `ec_coe_emerg_ring_clear_ring`

int ec_coe_emerg_ring_clear_ring(
        ec_coe_emerg_ring_t *ring /**< Emergency ring. */
        )
{
    ring->read_index = ring->write_index;
    ring->overruns = 0;
    return 0;
}

功能和用途：清空环形缓冲区。
使用场景：在需要清空紧急消息环形缓冲区时调用。

7. `ec_coe_emerg_ring_overruns`

int ec_coe_emerg_ring_overruns(
        ec_coe_emerg_ring_t *ring /**< Emergency ring. */
        )
{
    return ring->overruns;
}

功能和用途：读取环形缓冲区的溢出次数。
使用场景：在需要获取环形缓冲区溢出次数时调用。

三 h文件翻译

这个头文件定义了 EtherCAT CoE（CANopen over EtherCAT）紧急消息的环形缓冲区结构和相关函数接口，包括初始化、清除、推入和弹出消息的函数。主要用于处理从站设备的紧急消息。

/******************************************************************************\
 *
 *  $Id$
 *
 *  版权所有 (C) 2012 Florian Pose, Ingenieurgemeinschaft IgH
 *
 *  本文件是 IgH EtherCAT 主站的一部分。
 *
 *  IgH EtherCAT 主站是免费软件；您可以根据自由软件基金会发布的 GNU 通用公共许可证第2版的条款重新分发和/或修改它。
 *
 *  IgH EtherCAT 主站的分发目的是希望它有用，但没有任何保证；甚至没有适销性或特定用途适用性的隐含保证。详情请参阅 GNU 通用公共许可证。
 *
 *  您应该已经收到了与 IgH EtherCAT 主站一起提供的 GNU 通用公共许可证的副本；如果没有，请写信给自由软件基金会，地址是：51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA。
 *
 *  ---
 *
 *  上述许可证仅适用于源代码。使用 EtherCAT 技术和品牌仅允许在遵守 Beckhoff Automation GmbH 的工业产权和类似权利的情况下使用。
 *****************************************************************************/

/**
   \file
   EtherCAT CoE 紧急环形缓冲区结构。
*/

/*****************************************************************************/

#ifndef __EC_COE_EMERG_RING_H__
#define __EC_COE_EMERG_RING_H__

#include "globals.h"

/*****************************************************************************/

/** EtherCAT CoE 紧急消息记录。
 */
typedef struct {
    u8 data[EC_COE_EMERGENCY_MSG_SIZE]; /**< 消息数据。 */
} ec_coe_emerg_msg_t;

/*****************************************************************************/

/** EtherCAT CoE 紧急环形缓冲区。
 */
typedef struct {
    ec_slave_config_t *sc; /**< 拥有该环的从站配置。 */

    ec_coe_emerg_msg_t *msgs; /**< 消息环。 */
    size_t size; /**< 环的大小。 */

    unsigned int read_pos; /**< 读取位置。 */
    unsigned int write_pos; /**< 写入位置。 */
    unsigned int stored; /**< 已存储的消息数量。 */
} ec_coe_emerg_ring_t;

/*****************************************************************************/

void ec_coe_emerg_ring_init(ec_coe_emerg_ring_t *ring, ec_slave_config_t *sc, size_t size);
void ec_coe_emerg_ring_clear(ec_coe_emerg_ring_t *ring);
int ec_coe_emerg_ring_push(ec_coe_emerg_ring_t *ring, const u8 *data);
int ec_coe_emerg_ring_pop(ec_coe_emerg_ring_t *ring, u8 *data);

/*****************************************************************************/

#endif

四 c文件翻译

/******************************************************************************\
 *
 *  $Id$
 *
 *  版权所有 (C) 2012 Florian Pose, Ingenieurgemeinschaft IgH
 *
 *  本文件是 IgH EtherCAT 主站的一部分。
 *
 *  IgH EtherCAT 主站是免费软件；您可以根据自由软件基金会发布的 GNU 通用公共许可证第2版的条款重新分发和/或修改它。
 *
 *  IgH EtherCAT 主站的分发目的是希望它有用，但没有任何保证；甚至没有适销性或特定用途适用性的隐含保证。详情请参阅 GNU 通用公共许可证。
 *
 *  您应该已经收到了与 IgH EtherCAT 主站一起提供的 GNU 通用公共许可证的副本；如果没有，请写信给自由软件基金会，地址是：51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA。
 *
 *  ---
 *
 *  上述许可证仅适用于源代码。使用 EtherCAT 技术和品牌仅允许在遵守 Beckhoff Automation GmbH 的工业产权和类似权利的情况下使用。
 *
 *  vim: expandtab
 *****************************************************************************/

/** \file
 * EtherCAT CoE 紧急环形缓冲区方法。
 */

/*****************************************************************************/

#include <linux/slab.h>

#include "coe_emerg_ring.h"

/*****************************************************************************/

/** 紧急环形缓冲区构造函数。
 */
void ec_coe_emerg_ring_init(
        ec_coe_emerg_ring_t *ring, /**< 紧急环。 */
        ec_slave_config_t *sc /**< 从站配置。 */
        )
{
    ring->sc = sc;
    ring->msgs = NULL;
    ring->size = 0;
    ring->read_index = 0;
    ring->write_index = 0;
    ring->overruns = 0;
}

/*****************************************************************************/

/** 紧急环形缓冲区析构函数。
 */
void ec_coe_emerg_ring_clear(
        ec_coe_emerg_ring_t *ring /**< 紧急环。 */
        )
{
    if (ring->msgs) {
        kfree(ring->msgs);
    }
}

/*****************************************************************************/

/** 设置环的大小。
 *
 * \return 成功时返回零，否则返回负错误代码。
 */
int ec_coe_emerg_ring_size(
        ec_coe_emerg_ring_t *ring, /**< 紧急环。 */
        size_t size /**< 环中最大消息数。 */
        )
{
    ring->size = 0;

    if (size < 0) {
        size = 0;
    }

    ring->read_index = ring->write_index = 0;

    if (ring->msgs) {
        kfree(ring->msgs);
    }
    ring->msgs = NULL;

    if (size == 0) {
        return 0;
    }

    ring->msgs = kmalloc(sizeof(ec_coe_emerg_msg_t) * (size + 1), GFP_KERNEL);
    if (!ring->msgs) {
        return -ENOMEM;
    }

    ring->size = size;
    return 0;
}

/*****************************************************************************/

/** 添加一个新的紧急消息。
 */
void ec_coe_emerg_ring_push(
        ec_coe_emerg_ring_t *ring, /**< 紧急环。 */
        const u8 *msg /**< 紧急消息。 */
        )
{
    if (!ring->size ||
            (ring->write_index + 1) % (ring->size + 1) == ring->read_index) {
        ring->overruns++;
        return;
    }

    memcpy(ring->msgs[ring->write_index].data, msg,
            EC_COE_EMERGENCY_MSG_SIZE);
    ring->write_index = (ring->write_index + 1) % (ring->size + 1);
}

/*****************************************************************************/

/** 从环形缓冲区中移除一个紧急消息。
 *
 * \return 成功时返回零，否则返回负错误代码。
 */
int ec_coe_emerg_ring_pop(
        ec_coe_emerg_ring_t *ring, /**< 紧急环。 */
        u8 *msg /**< 用于存储紧急消息的内存。 */
        )
{
    if (ring->read_index == ring->write_index) {
        return -ENOENT;
    }

    memcpy(msg, ring->msgs[ring->read_index].data, EC_COE_EMERGENCY_MSG_SIZE);
    ring->read_index = (ring->read_index + 1) % (ring->size + 1);
    return 0;
}

/*****************************************************************************/

/** 清空环。
 *
 * \return 成功时返回零，否则返回负错误代码。
 */
int ec_coe_emerg_ring_clear_ring(
        ec_coe_emerg_ring_t *ring /**< 紧急环。 */
        )
{
    ring->read_index = ring->write_index;
    ring->overruns = 0;
    return 0;
}

/*****************************************************************************/

/** 读取环溢出次数。
 *
 * \return 溢出次数。
 */
int ec_coe_emerg_ring_overruns(
        ec_coe_emerg_ring_t *ring /**< 紧急环。 */
        )
{
    return ring->overruns;
}

/*****************************************************************************/