fsm_mbox.c

Go to the documentation of this file.

/*****************************************************************************
 *
 *  Copyright (C) 2026  Florian Pose, Ingenieurgemeinschaft IgH
 *
 *  This file is part of the IgH EtherCAT Master.
 *
 *  The IgH EtherCAT Master is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU General Public License version 2, as
 *  published by the Free Software Foundation.
 *
 *  The IgH EtherCAT Master 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 the IgH EtherCAT Master; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 *
 ****************************************************************************/

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

#include "globals.h"
#include "master.h"
#include "slave.h"
#include "fsm_mbox.h"

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

void ec_fsm_mbox_state_start(ec_fsm_mbox_t *, ec_datagram_t *);
void ec_fsm_mbox_state_check(ec_fsm_mbox_t *, ec_datagram_t *);
void ec_fsm_mbox_state_fetch(ec_fsm_mbox_t *, ec_datagram_t *);
void ec_fsm_mbox_state_end(ec_fsm_mbox_t *, ec_datagram_t *);
void ec_fsm_mbox_state_error(ec_fsm_mbox_t *, ec_datagram_t *);

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

void ec_fsm_mbox_init(
        ec_fsm_mbox_t *fsm 
        )
{
    fsm->slave = NULL;
    fsm->mbox_data = NULL;
    fsm->mode = EC_FSM_MBOX_WAIT;
    fsm->jiffies_start = 0;
    fsm->timeout_ms = 0;
    fsm->state = ec_fsm_mbox_state_error;
    fsm->datagram = NULL;
    fsm->retries = 0;
    fsm->result = -EINVAL;
}

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

void ec_fsm_mbox_clear(
        ec_fsm_mbox_t *fsm 
        )
{
    ec_fsm_mbox_abort(fsm);
}

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

static void ec_fsm_mbox_start(
        ec_fsm_mbox_t *fsm, 
        ec_slave_t *slave, 
        ec_mbox_data_t *mbox_data, 
        ec_fsm_mbox_mode_t mode, 
        unsigned long jiffies_start, 
        unsigned long timeout_ms 
        )
{
    fsm->slave = slave;
    fsm->mbox_data = mbox_data;
    fsm->mode = mode;
    fsm->jiffies_start = jiffies_start;
    fsm->timeout_ms = timeout_ms;
    fsm->state = ec_fsm_mbox_state_start;
    fsm->datagram = NULL;
    fsm->retries = 0;
    fsm->result = 0;
}

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

void ec_fsm_mbox_receive(
        ec_fsm_mbox_t *fsm, 
        ec_slave_t *slave, 
        ec_mbox_data_t *mbox_data, 
        unsigned long jiffies_start, 
        unsigned long timeout_ms 
        )
{
    ec_fsm_mbox_start(fsm, slave, mbox_data, EC_FSM_MBOX_WAIT,
            jiffies_start, timeout_ms);
}

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

void ec_fsm_mbox_poll(
        ec_fsm_mbox_t *fsm, 
        ec_slave_t *slave, 
        ec_mbox_data_t *mbox_data 
        )
{
    ec_fsm_mbox_start(fsm, slave, mbox_data, EC_FSM_MBOX_POLL, jiffies, 0);
}

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

void ec_fsm_mbox_fetch_nosync(
        ec_fsm_mbox_t *fsm, 
        ec_slave_t *slave, 
        ec_mbox_data_t *mbox_data, 
        unsigned long jiffies_start, 
        unsigned long timeout_ms 
        )
{
    ec_fsm_mbox_start(fsm, slave, mbox_data, EC_FSM_MBOX_NOSYNC,
            jiffies_start, timeout_ms);
}

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

int ec_fsm_mbox_exec(
        ec_fsm_mbox_t *fsm, 
        ec_datagram_t *datagram 
        )
{
    if (fsm->state == ec_fsm_mbox_state_end ||
            fsm->state == ec_fsm_mbox_state_error) {
        return 0;
    }

    fsm->state(fsm, datagram);

    if (fsm->state == ec_fsm_mbox_state_end ||
            fsm->state == ec_fsm_mbox_state_error) {
        fsm->datagram = NULL;
        return 0;
    }

    if (datagram->state != EC_DATAGRAM_UNUSED) {
        fsm->datagram = datagram;
    }
    return 1;
}

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

int ec_fsm_mbox_result(
        const ec_fsm_mbox_t *fsm 
        )
{
    return fsm->result;
}

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

int ec_fsm_mbox_holds_lock(
        const ec_fsm_mbox_t *fsm 
        )
{
    return fsm->state == ec_fsm_mbox_state_check ||
        fsm->state == ec_fsm_mbox_state_fetch;
}

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

void ec_fsm_mbox_abort(
        ec_fsm_mbox_t *fsm 
        )
{
    if (ec_fsm_mbox_holds_lock(fsm)) {
        ec_read_mbox_lock_clear(fsm->slave);
    }

    if (fsm->state != ec_fsm_mbox_state_end &&
            fsm->state != ec_fsm_mbox_state_error) {
        fsm->result = -ECANCELED;
        fsm->state = ec_fsm_mbox_state_error;
    }
    fsm->datagram = NULL;
}

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

static int ec_fsm_mbox_data_available(
        const ec_fsm_mbox_t *fsm 
        )
{
    return smp_load_acquire(&fsm->mbox_data->payload_size) > 0;
}

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

static int ec_fsm_mbox_timed_out(
        const ec_fsm_mbox_t *fsm, 
        unsigned long now 
        )
{
    return (now - fsm->jiffies_start) * 1000 / HZ >= fsm->timeout_ms;
}

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

static void ec_fsm_mbox_fail(
        ec_fsm_mbox_t *fsm, 
        ec_datagram_t *datagram, 
        int result 
        )
{
    ec_read_mbox_lock_clear(fsm->slave);
    datagram->state = EC_DATAGRAM_UNUSED;
    fsm->result = result;
    fsm->state = ec_fsm_mbox_state_error;
}

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

void ec_fsm_mbox_state_start(
        ec_fsm_mbox_t *fsm, 
        ec_datagram_t *datagram 
        )
{
    ec_slave_t *slave = fsm->slave;

    if (ec_fsm_mbox_data_available(fsm)) {
        // data were already received by another read request
        datagram->state = EC_DATAGRAM_UNUSED;
        fsm->state = ec_fsm_mbox_state_end;
        return;
    }

    if (ec_read_mbox_locked(slave)) {
        // another state machine reads the mailbox
        datagram->state = EC_DATAGRAM_UNUSED;

        if (fsm->mode == EC_FSM_MBOX_POLL) {
            fsm->result = -EBUSY;
            fsm->state = ec_fsm_mbox_state_error;
        } else if (ec_fsm_mbox_timed_out(fsm, jiffies)) {
            fsm->result = -ETIMEDOUT;
            fsm->state = ec_fsm_mbox_state_error;
        }
        return;
    }

    fsm->retries = EC_FSM_RETRIES;

    if (fsm->mode == EC_FSM_MBOX_NOSYNC) {
        ec_slave_mbox_prepare_fetch(slave, datagram); // can not fail.
        fsm->state = ec_fsm_mbox_state_fetch;
    } else {
        ec_slave_mbox_prepare_check(slave, datagram); // can not fail.
        fsm->state = ec_fsm_mbox_state_check;
    }
}

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

void ec_fsm_mbox_state_check(
        ec_fsm_mbox_t *fsm, 
        ec_datagram_t *datagram 
        )
{
    ec_slave_t *slave = fsm->slave;
    int verbose = fsm->mode != EC_FSM_MBOX_POLL;

    if (fsm->datagram->state == EC_DATAGRAM_TIMED_OUT && fsm->retries--) {
        ec_slave_mbox_prepare_check(slave, datagram); // can not fail.
        return;
    }

    if (fsm->datagram->state != EC_DATAGRAM_RECEIVED) {
        if (verbose) {
            EC_SLAVE_ERR(slave, "Failed to receive mailbox check"
                    " datagram: ");
            ec_datagram_print_state(fsm->datagram);
        }
        ec_fsm_mbox_fail(fsm, datagram, -EIO);
        return;
    }

    if (fsm->datagram->working_counter != 1) {
        if (verbose) {
            EC_SLAVE_ERR(slave, "Reception of mailbox check"
                    " datagram failed: ");
            ec_datagram_print_wc_error(fsm->datagram);
        }
        ec_fsm_mbox_fail(fsm, datagram, -EIO);
        return;
    }

    if (ec_slave_mbox_check(fsm->datagram)) {
        ec_slave_mbox_prepare_fetch(slave, datagram); // can not fail.
        fsm->retries = EC_FSM_RETRIES;
        fsm->state = ec_fsm_mbox_state_fetch;
        return;
    }

    // mailbox empty

    if (ec_fsm_mbox_data_available(fsm)) {
        // data were already received by another read request
        ec_read_mbox_lock_clear(slave);
        datagram->state = EC_DATAGRAM_UNUSED;
        fsm->state = ec_fsm_mbox_state_end;
        return;
    }

    if (fsm->mode == EC_FSM_MBOX_POLL) {
        ec_fsm_mbox_fail(fsm, datagram, -EAGAIN);
        return;
    }

    if (ec_fsm_mbox_timed_out(fsm, fsm->datagram->jiffies_received)) {
        ec_fsm_mbox_fail(fsm, datagram, -ETIMEDOUT);
        return;
    }

    ec_slave_mbox_prepare_check(slave, datagram); // can not fail.
    fsm->retries = EC_FSM_RETRIES;
}

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

void ec_fsm_mbox_state_fetch(
        ec_fsm_mbox_t *fsm, 
        ec_datagram_t *datagram 
        )
{
    ec_slave_t *slave = fsm->slave;
    int verbose = fsm->mode != EC_FSM_MBOX_POLL;

    if (fsm->datagram->state == EC_DATAGRAM_TIMED_OUT && fsm->retries--) {
        ec_slave_mbox_prepare_fetch(slave, datagram); // can not fail.
        return;
    }

    if (fsm->datagram->state != EC_DATAGRAM_RECEIVED) {
        if (verbose) {
            EC_SLAVE_ERR(slave, "Failed to receive mailbox fetch"
                    " datagram: ");
            ec_datagram_print_state(fsm->datagram);
        }
        ec_fsm_mbox_fail(fsm, datagram, -EIO);
        return;
    }

    // a mailbox error response is not dispatched by the receive path
    ec_slave_mbox_take_error(fsm->mbox_data, fsm->datagram);

    ec_read_mbox_lock_clear(slave);
    datagram->state = EC_DATAGRAM_UNUSED;

    if (ec_fsm_mbox_data_available(fsm)) {
        fsm->state = ec_fsm_mbox_state_end;
        return;
    }

    if (fsm->mode == EC_FSM_MBOX_NOSYNC) {
        // no data in the mailbox, or a message of another protocol
        fsm->result = -EAGAIN;
        fsm->state = ec_fsm_mbox_state_error;
        return;
    }

    if (fsm->datagram->working_counter != 1) {
        if (verbose) {
            EC_SLAVE_ERR(slave, "Reception of mailbox fetch"
                    " datagram failed: ");
            ec_datagram_print_wc_error(fsm->datagram);
        }
        fsm->result = -EIO;
        fsm->state = ec_fsm_mbox_state_error;
        return;
    }

    if (fsm->mode == EC_FSM_MBOX_POLL) {
        // message of another protocol
        fsm->result = -EAGAIN;
        fsm->state = ec_fsm_mbox_state_error;
        return;
    }

    // message of another protocol: continue waiting
    fsm->state = ec_fsm_mbox_state_start;
    fsm->state(fsm, datagram);
}

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

void ec_fsm_mbox_state_end(
        ec_fsm_mbox_t *fsm, 
        ec_datagram_t *datagram 
        )
{
}

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

void ec_fsm_mbox_state_error(
        ec_fsm_mbox_t *fsm, 
        ec_datagram_t *datagram 
        )
{
}

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