QK/C platform-independent public interface. More...

#include "qequeue.h"
#include "qmpool.h"
#include "qpset.h"

Defines
#define	QF_EQUEUE_TYPE QEQueue
	This macro defines the type of the event queue used for the active objects.
#define	QACTIVE_EQUEUE_WAIT_(me_) (Q_ASSERT((me_)->eQueue.frontEvt != (QEvt *)0))
	Platform-dependent macro defining how QF should block the calling task when the QF native queue is empty.
#define	QACTIVE_EQUEUE_SIGNAL_(me_)
	Platform-dependent macro defining how QF should signal the active object task that an event has just arrived.
#define	QACTIVE_EQUEUE_ONEMPTY_(me_) QPSet64_remove(&QK_readySet_, (me_)->prio)
	Platform-dependent macro defining the action QF should take when the native QF event queue becomes empty.
#define	QF_EPOOL_TYPE_ QMPool
	This macro defines the type of the event pool used in this QF port.
#define	QF_EPOOL_INIT_(p_, poolSto_, poolSize_, evtSize_) (QMPool_init(&(p_), (poolSto_), (poolSize_), (QMPoolSize)(evtSize_)))
	Platform-dependent macro defining the event pool initialization.
#define	QF_EPOOL_EVENT_SIZE_(p_) ((QEvtSize)(p_).blockSize)
	Platform-dependent macro defining how QF should obtain the event pool block-size.
#define	QF_EPOOL_GET_(p_, e_) ((e_) = (QEvt *)QMPool_get(&(p_)))
	Platform-dependent macro defining how QF should obtain an event e_ from the event pool p_.
#define	QF_EPOOL_PUT_(p_, e_) (QMPool_put(&(p_), (e_)))
	Platform-dependent macro defining how QF should return an event e_ to the event pool p_.
Typedefs
typedef uint8_t	QMutex
	QK Mutex type.
Functions
void	QK_sched_ (uint8_t p)
	QK scheduler.
void	QK_schedExt_ (uint8_t p)
	QK extended scheduler.
uint8_t	QK_schedPrio_ (void)
	Find the highest-priority task ready to run.
void	QK_init (void)
	QK initialization.
void	QK_onIdle (void)
	QK idle callback (customized in BSPs for QK)
char_t const Q_ROM *Q_ROM_VAR	QK_getVersion (void)
	get the current QK version number string
QMutex	QK_mutexLock (uint8_t const prioCeiling)
	QK priority-ceiling mutex lock.
void	QK_mutexUnlock (QMutex mutex)
	QK priority-ceiling mutex unlock.
Variables
uint8_t	QK_currPrio_
uint8_t	QK_intNest_

Detailed Description

QK/C platform-independent public interface.

This header file must be included directly or indirectly in all modules (*.c files) that use QK/C.

Definition in file qk.h.

Define Documentation

#define QACTIVE_EQUEUE_ONEMPTY_ ( me_ ) QPSet64_remove(&QK_readySet_, (me_)->prio)

Platform-dependent macro defining the action QF should take when the native QF event queue becomes empty.

The macro is necessary only when the native QF event queue is used. The signaling of task involves unblocking the task if it is blocked.

Note:: QACTIVE_EQUEUE_ONEMPTY_ is called from a critical section. It should not leave the critical section.; This is just an example of QACTIVE_EQUEUE_ONEMPTY_ for the QK-port of QF. In other QF ports you need to define the macro appropriately for the underlying kernel/OS you're using.

Definition at line 161 of file qk.h.

Referenced by QActive_get_().

#define QACTIVE_EQUEUE_SIGNAL_ ( me_ )

Value:

do { \
        QPSet64_insert(&QK_readySet_, (me_)->prio); \
        if (QK_intNest_ == (uint8_t)0) { \
            uint8_t p = QK_schedPrio_(); \
            if (p != (uint8_t)0) { \
                QK_sched_(p); \
            } \
        } \
    } while (0)

Platform-dependent macro defining how QF should signal the active object task that an event has just arrived.

The macro is necessary only when the native QF event queue is used. The signaling of task involves unblocking the task if it is blocked.

Note:: QACTIVE_EQUEUE_SIGNAL_ is called from a critical section. It might leave the critical section internally, but must restore the critical section before exiting to the caller.; This is just an example of QACTIVE_EQUEUE_SIGNAL_ for the QK-port of QF. In other QF ports you need to define the macro appropriately for the underlying kernel/OS you're using.

Definition at line 138 of file qk.h.

Referenced by QActive_postFIFO(), and QActive_postLIFO().

#define QACTIVE_EQUEUE_WAIT_ ( me_ ) (Q_ASSERT((me_)->eQueue.frontEvt != (QEvt *)0))

Platform-dependent macro defining how QF should block the calling task when the QF native queue is empty.

QK ready-set of active objects

Note:: This is just an example of QACTIVE_EQUEUE_WAIT_ for the QK-port of QF. QK never activates a task that has no events to process, so in this case the macro asserts that the queue is not empty. In other QF ports you need to define the macro appropriately for the underlying kernel/OS you're using.

Definition at line 107 of file qk.h.

Referenced by QActive_get_().

#define QF_EPOOL_EVENT_SIZE_ ( p_ ) ((QEvtSize)(p_).blockSize)

Platform-dependent macro defining how QF should obtain the event pool block-size.

Note:: This is a specific implementation for the QK-port of QF. In other QF ports you need to define the macro appropriately for the underlying kernel/OS you're using.

Definition at line 192 of file qk.h.

Referenced by QF_poolInit().

#define QF_EPOOL_GET_	(	p_,
		e_
	)	((e_) = (QEvt *)QMPool_get(&(p_)))

Platform-dependent macro defining how QF should obtain an event e_ from the event pool p_.

Note:: This is a specific implementation for the QK-port of QF. In other QF ports you need to define the macro appropriately for the underlying kernel/OS you're using.

Definition at line 201 of file qk.h.

#define QF_EPOOL_INIT_	(	p_,
		poolSto_,
		poolSize_,
		evtSize_
	)	(QMPool_init(&(p_), (poolSto_), (poolSize_), (QMPoolSize)(evtSize_)))

Platform-dependent macro defining the event pool initialization.

Note:: This is a specific implementation for the QK-port of QF. In other QF ports you need to define the macro appropriately for the underlying kernel/OS you're using.

Definition at line 182 of file qk.h.

Referenced by QF_poolInit().

#define QF_EPOOL_PUT_	(	p_,
		e_
	)	(QMPool_put(&(p_), (e_)))

Platform-dependent macro defining how QF should return an event e_ to the event pool p_.

Note:: This is a specific implementation for the QK-port of QF. In other QF ports you need to define the macro appropriately for the underlying kernel/OS you're using.

Definition at line 210 of file qk.h.

Referenced by QF_gc().

#define QF_EPOOL_TYPE_ QMPool

This macro defines the type of the event pool used in this QF port.

Note:: This is a specific implementation for the QK-port of QF. In other QF ports you need to define the macro appropriately for the underlying kernel/OS you're using.

Definition at line 174 of file qk.h.

#define QF_EQUEUE_TYPE QEQueue

This macro defines the type of the event queue used for the active objects.

Note:: This is just an example of the macro definition. Typically, you need to define it in the specific QF port file (qf_port.h). In case of QK, which always depends on the native QF queue, this macro is defined at the level of the platform-independent interface qk.h.

Definition at line 62 of file qk.h.

Typedef Documentation

typedef uint8_t QMutex

QK Mutex type.

QMutex represents the priority-ceiling mutex available in QK.

See also:: QK_mutexLock(); QK_mutexUnlock()

Definition at line 279 of file qk.h.

Function Documentation

char_t const Q_ROM* Q_ROM_VAR QK_getVersion ( void )

get the current QK version number string

Returns:: version of the QK as a constant 6-character string of the form x.y.zz, where x is a 1-digit major version number, y is a 1-digit minor version number, and zz is a 2-digit release number.

See also:: QK_getPortVersion()

Definition at line 62 of file qk.c.

References QF_getVersion().

void QK_init ( void )

QK initialization.

QK_init() is called from QF_init() in qk.c. This function is defined in the QK ports.

Referenced by QF_init().

QMutex QK_mutexLock ( uint8_t const prioCeiling )

QK priority-ceiling mutex lock.

Lock the QK scheduler up to the priority level prioCeiling.

Note:: This function should be always paired with QK_mutexUnlock(). The code between QK_mutexLock() and QK_mutexUnlock() should be kept to the minimum.

    QMutex mux;
    . . .
    mux = QK_mutexLock(PRIO_CEILING);

    /* access the shared resource */

    QK_mutexUnlock(mux);

    . . .

Definition at line 54 of file qk_mutex.c.

References QK_ceilingPrio_, QS_BEGIN_NOCRIT_, QS_END_NOCRIT_, QS_QK_MUTEX_LOCK, QS_TIME_, and QS_U8_.

void QK_mutexUnlock ( QMutex mutex )

QK priority-ceiling mutex unlock.

Note:: This function should be always paired with QK_mutexLock(). The code between QK_mutexLock() and QK_mutexUnlock() should be kept to the minimum.

    QMutex mux;
    . . .
    mux = QK_mutexLock(PRIO_CEILING);

    /* access the shared resource */

    QK_mutexUnlock(mux);

    . . .

Definition at line 73 of file qk_mutex.c.

References QK_ceilingPrio_, QK_sched_(), QK_schedPrio_(), QS_BEGIN_NOCRIT_, QS_END_NOCRIT_, QS_QK_MUTEX_UNLOCK, QS_TIME_, and QS_U8_.

void QK_onIdle ( void )

QK idle callback (customized in BSPs for QK)

QK_onIdle() is called continuously by the QK idle loop. This callback gives the application an opportunity to enter a power-saving CPU mode, or perform some other idle processing.

Note:: QK_onIdle() is invoked with interrupts enabled and must also return with interrupts enabled.

See also:: QF_onIdle()

Referenced by QF_run().

void QK_sched_ ( uint8_t p )

QK scheduler.

Note:: QK_sched_() must be always called with interrupts disabled. The scheduler might enable interrupts internally, but always returns with interrupts disabled.

Definition at line 70 of file qk_sched.c.

References QActive_get_(), QF_active_, QF_gc(), QF_INT_DISABLE, QF_INT_ENABLE, QK_currPrio_, QK_TLS, QPSet64_findMax, QPSet8_findMax, QS_aoObj_, QS_BEGIN_NOCRIT_, QS_END_NOCRIT_, QS_QK_SCHEDULE, QS_TIME_, QS_U8_, and QActive::super.

Referenced by QK_mutexUnlock().

void QK_schedExt_ ( uint8_t p )

QK extended scheduler.

Note:: QK_schedExt_() must be always called with interrupts disabled. The scheduler might enable the interrupts internally, but always returns with interrupts disabled.

Definition at line 48 of file qk_ext.c.

References QActive_get_(), QF_active_, QF_gc(), QF_INT_DISABLE, QF_INT_ENABLE, QK_currPrio_, QK_EXT_SAVE, QK_TLS, QPSet64_findMax, QPSet8_findMax, QS_aoObj_, QS_BEGIN_NOCRIT_, QS_END_NOCRIT_, QS_QK_SCHEDULE, QS_TIME_, QS_U8_, and QActive::super.