/**
* @file
* @brief QF/C port to POSIX/P-threads, GNU-C compiler
* @ingroup ports
* @cond
******************************************************************************
* Last updated for version 6.3.2
* Last updated on 2018-06-16
*
* Q u a n t u m L e a P s
* ---------------------------
* innovating embedded systems
*
* Copyright (C) 2005-2018 Quantum Leaps, LLC. All rights reserved.
*
* This program is 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 3 of the License, or
* (at your option) any later version.
*
* Alternatively, this program may be distributed and modified under the
* terms of Quantum Leaps commercial licenses, which expressly supersede
* the GNU General Public License and are specifically designed for
* licensees interested in retaining the proprietary status of their code.
*
* 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 .
*
* Contact information:
* https://www.state-machine.com
* mailto:info@state-machine.com
******************************************************************************
* @endcond
*/
#define QP_IMPL /* this is QP implementation */
#include "qf_port.h" /* QF port */
#include "qf_pkg.h"
#include "qassert.h"
#ifdef Q_SPY /* QS software tracing enabled? */
#include "qs_port.h" /* include QS port */
#else
#include "qs_dummy.h" /* disable the QS software tracing */
#endif /* Q_SPY */
#include /* for PTHREAD_STACK_MIN */
#include /* for mlockall() */
Q_DEFINE_THIS_MODULE("qf_port")
/* Global objects ==========================================================*/
pthread_mutex_t QF_pThreadMutex_;
/* Local objects ===========================================================*/
static pthread_mutex_t l_startupMutex;
static bool l_isRunning;
static struct timespec l_tick;
static int_t l_tickPrio;
enum { NANOSLEEP_NSEC_PER_SEC = 1000000000 }; /* see NOTE05 */
/* QF functions ============================================================*/
void QF_init(void) {
extern uint_fast8_t QF_maxPool_;
extern QTimeEvt QF_timeEvtHead_[QF_MAX_TICK_RATE];
/* lock memory so we're never swapped out to disk */
/*mlockall(MCL_CURRENT | MCL_FUTURE); uncomment when supported */
/* init the global mutex with the default non-recursive initializer */
pthread_mutex_init(&QF_pThreadMutex_, NULL);
/* init the startup mutex with the default non-recursive initializer */
pthread_mutex_init(&l_startupMutex, NULL);
/* lock the startup mutex to block any active objects started before
* calling QF_run()
*/
pthread_mutex_lock(&l_startupMutex);
/* clear the internal QF variables, so that the framework can (re)start
* correctly even if the startup code is not called to clear the
* uninitialized data (as is required by the C Standard).
*/
QF_maxPool_ = (uint_fast8_t)0;
QF_bzero(&QF_timeEvtHead_[0], (uint_fast16_t)sizeof(QF_timeEvtHead_));
QF_bzero(&QF_active_[0], (uint_fast16_t)sizeof(QF_active_));
l_tick.tv_sec = 0;
l_tick.tv_nsec = NANOSLEEP_NSEC_PER_SEC/100L; /* default clock tick */
l_tickPrio = sched_get_priority_min(SCHED_FIFO); /* default tick prio */
}
/****************************************************************************/
int_t QF_run(void) {
struct sched_param sparam;
QF_onStartup(); /* invoke startup callback */
/* try to set the priority of the ticker thread, see NOTE01 */
sparam.sched_priority = l_tickPrio;
if (pthread_setschedparam(pthread_self(), SCHED_FIFO, &sparam) == 0) {
/* success, this application has sufficient privileges */
}
else {
/* setting priority failed, probably due to insufficient privieges */
}
/* unlock the startup mutex to unblock any active objects started before
* calling QF_run()
*/
pthread_mutex_unlock(&l_startupMutex);
l_isRunning = true;
while (l_isRunning) { /* the clock tick loop... */
QF_onClockTick(); /* clock tick callback (must call QF_TICK_X()) */
nanosleep(&l_tick, NULL); /* sleep for the number of ticks, NOTE05 */
}
QF_onCleanup(); /* invoke cleanup callback */
pthread_mutex_destroy(&l_startupMutex);
pthread_mutex_destroy(&QF_pThreadMutex_);
return (int_t)0; /* return success */
}
/*..........................................................................*/
void QF_setTickRate(uint32_t ticksPerSec, int_t tickPrio) {
Q_REQUIRE_ID(300, ticksPerSec != (uint32_t)0);
l_tick.tv_nsec = NANOSLEEP_NSEC_PER_SEC / ticksPerSec;
l_tickPrio = tickPrio;
}
/*..........................................................................*/
void QF_stop(void) {
l_isRunning = false; /* stop the loop in QF_run() */
}
/*..........................................................................*/
static void *thread_routine(void *arg) { /* the expected POSIX signature */
QActive *act = (QActive *)arg;
/* block this thread until the startup mutex is unlocked from QF_run() */
pthread_mutex_lock(&l_startupMutex);
pthread_mutex_unlock(&l_startupMutex);
/* loop until m_thread is cleared in QActive_stop() */
do {
QEvt const *e = QActive_get_(act); /* wait for the event */
QHSM_DISPATCH(&act->super, e); /* dispatch to the HSM */
QF_gc(e); /* check if the event is garbage, and collect it if so */
} while (act->thread != (uint8_t)0);
QF_remove_(act); /* remove this object from the framework */
pthread_cond_destroy(&act->osObject); /* cleanup the condition variable */
return (void *)0; /* return success */
}
/*..........................................................................*/
void QActive_start_(QActive * const me, uint_fast8_t prio,
QEvt const *qSto[], uint_fast16_t qLen,
void *stkSto, uint_fast16_t stkSize,
QEvt const *ie)
{
pthread_t thread;
pthread_attr_t attr;
struct sched_param param;
/* p-threads allocate stack internally */
Q_REQUIRE_ID(600, stkSto == (void *)0);
QEQueue_init(&me->eQueue, qSto, qLen);
pthread_cond_init(&me->osObject, 0);
me->prio = (uint8_t)prio;
QF_add_(me); /* make QF aware of this active object */
QHSM_INIT(&me->super, ie); /* take the top-most initial tran. */
/* SCHED_FIFO corresponds to real-time preemptive priority-based scheduler
* NOTE: This scheduling policy requires the superuser privileges
*/
pthread_attr_init(&attr);
pthread_attr_setschedpolicy(&attr, SCHED_FIFO);
/* see NOTE04 */
param.sched_priority = prio
+ (sched_get_priority_max(SCHED_FIFO)
- QF_MAX_ACTIVE - 3);
pthread_attr_setschedparam(&attr, ¶m);
pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED);
if (stkSize == 0U) {
/* set the allowed minimum */
stkSize = (uint_fast16_t)PTHREAD_STACK_MIN;
}
pthread_attr_setstacksize(&attr, (size_t)stkSize);
if (pthread_create(&thread, &attr, &thread_routine, me) != 0) {
/* Creating the p-thread with the SCHED_FIFO policy failed. Most
* probably this application has no superuser privileges, so we just
* fall back to the default SCHED_OTHER policy and priority 0.
*/
pthread_attr_setschedpolicy(&attr, SCHED_OTHER);
param.sched_priority = 0;
pthread_attr_setschedparam(&attr, ¶m);
Q_ALLEGE(pthread_create(&thread, &attr, &thread_routine, me)== 0);
}
pthread_attr_destroy(&attr);
me->thread = (uint8_t)1;
}
/*..........................................................................*/
void QActive_stop(QActive * const me) {
me->thread = (uint8_t)0; /* stop the QActive thread loop */
}
/*****************************************************************************
* NOTE01:
* In Linux, the scheduler policy closest to real-time is the SCHED_FIFO
* policy, available only with superuser privileges. QF_run() attempts to set
* this policy as well as to maximize its priority, so that the ticking
* occurrs in the most timely manner (as close to an interrupt as possible).
* However, setting the SCHED_FIFO policy might fail, most probably due to
* insufficient privileges.
*
* NOTE02:
* On some Linux systems nanosleep() might actually not deliver the finest
* time granularity. For example, on some Linux implementations, nanosleep()
* could not block for shorter intervals than 20ms, while the underlying
* clock tick period was only 10ms. Sometimes, the select() system call can
* provide a finer granularity.
*
* NOTE03:
* Any blocking system call, such as nanosleep() or select() system call can
* be interrupted by a signal, such as ^C from the keyboard. In this case this
* QF port breaks out of the event-loop and returns to main() that exits and
* terminates all spawned p-threads.
*
* NOTE04:
* According to the man pages (for pthread_attr_setschedpolicy) the only value
* supported in the Linux p-threads implementation is PTHREAD_SCOPE_SYSTEM,
* meaning that the threads contend for CPU time with all processes running on
* the machine. In particular, thread priorities are interpreted relative to
* the priorities of all other processes on the machine.
*
* This is good, because it seems that if we set the priorities high enough,
* no other process (or thread running within) can gain control over the CPU.
*
* However, QF limits the number of priority levels to QF_MAX_ACTIVE.
* Assuming that a QF application will be real-time, this port reserves the
* three highest Linux priorities for the ISR-like threads (e.g., the ticker,
* I/O), and the rest highest-priorities for the active objects.
*
* NOTE05:
* In some (older) Linux kernels, the POSIX nanosleep() system call might
* deliver only 2*actual-system-tick granularity. To compensate for this,
* you would need to reduce (by 2) the constant NANOSLEEP_NSEC_PER_SEC.
*/