qvanilla.c File Reference

"vanilla" cooperative kernel, QActive_start(), QActive_stop(), and QF_run() implementation. More...

#include "qf_pkg.h"
#include "qassert.h"

Functions
char const Q_ROM *Q_ROM_VAR	QF_getPortVersion (void)
	Returns the QF-port version.
void	QF_init (void)
	QF initialization.
void	QF_stop (void)
	Function invoked by the application layer to stop the QF application and return control to the OS/Kernel.
void	QF_run (void)
	Transfers control to QF to run the application.
void	QActive_start (QActive me, uint8_t prio, QEvent const qSto[], uint32_t qLen, void stkSto, uint32_t stkSize, QEvent const ie)
	Starts execution of an active object and registers the object with the framework.
void	QActive_stop (QActive *me)
	Stops execution of an active object and removes it from the framework's supervision.

Detailed Description

"vanilla" cooperative kernel, QActive_start(), QActive_stop(), and QF_run() implementation.

Definition in file qvanilla.c.

Function Documentation

void QActive_start	(	QActive *	me,
		uint8_t	prio,
		QEvent const *	qSto[],
		uint32_t	qLen,
		void *	stkSto,
		uint32_t	stkSize,
		QEvent const *	ie
	)

Starts execution of an active object and registers the object with the framework.

The function takes seven arguments. me is a pointer to the active object structure. prio is the priority of the active object. QF allows you to start up to 63 active objects, each one having a unique priority number between 1 and 63 inclusive, where higher numerical values correspond to higher priority (urgency) of the active object relative to the others. qSto[] and qLen arguments are the storage and size of the event queue used by this active object. stkSto and stkSize are the stack storage and size in bytes. Please note that a per-active object stack is used only when the underlying OS requies it. If the stack is not required, or the underlying OS allocates the stack internally, the stkSto should be NULL and/or stkSize should be 0. ie is an optional initialization event that can be used to pass additional startup data to the active object. (Pass NULL if your active object does not expect the initialization event).

Note:: This function is strongly OS-dependent and must be defined in the QF port to a particular platform.

The following example shows starting of the Philosopher object when a per-task stack is required:

static Philosopher l_philo[N];              /* N Philosopher active objects */
static QEvent const *l_philQueueSto[N][N];/* storage for Philo event queues */
static int l_philoStk[N][256]; /* stacks for the Philosopher active objects */

main() {
    . . .
    for (n = 0; n < N; ++n) {
        TableEvt ie;        /* initialization event for the Philosopher HSM */
        ie.philNum = n;
        Philosopher_ctor(&l_philo[n]);
        QActive_start((QActive *)&l_philo[n],       /* Philosopher number n */
                      (uint8_t)(n*10 + 1),                      /* priority */
                      l_philoQueueSto[n], Q_DIM(l_philoQueueSto[n]),/*queue */
                      l_philoStk[n], sizeof(l_philoStk[n]),/*uC/OS-II stack */
                      (QEvent const *)&ie);         /* initialization event */
    }
    . . .
}

Definition at line 97 of file qvanilla.c.

References QActive::eQueue, QActive::prio, Q_REQUIRE, QEQueue_init(), QF_ACTIVE_INIT_, QF_add_(), QF_MAX_ACTIVE, QS_FLUSH, and QActive::super.

void QActive_stop ( QActive * me )

Stops execution of an active object and removes it from the framework's supervision.

The preferred way of calling this function is from within the active object that needs to stop. In other words, an active object should stop itself rather than being stopped by some other entity. This policy works best, because only the active object itself "knows" when it has reached the appropriate state for the shutdown.

Note:: This function is strongly OS-dependent and should be defined in the QF port to a particular platform. This function is optional in embedded systems where active objects never need to be stopped.

Definition at line 114 of file qvanilla.c.

References QF_remove_().

char const Q_ROM* Q_ROM_VAR QF_getPortVersion ( void )

Returns the QF-port version.

This function returns constant version string in the format x.y.zz, where x (one digit) is the major version, y (one digit) is the minor version, and zz (two digits) is the maintenance release version. An example of the QF-port version string is "1.1.03".

See also:: QF_getVersion()

Definition at line 48 of file qvanilla.c.

References Q_ROM, and Q_ROM_VAR.

void QF_init ( void )

QF initialization.

This function initializes QF and must be called exactly once before any other QF function.

Definition at line 53 of file qvanilla.c.

void QF_run ( void )

Transfers control to QF to run the application.

QF_run() is typically called from your startup code after you initialize the QF and start at least one active object with QActive_start(). Also, QF_start() call must precede the transfer of control to QF_run(), but some QF ports might call QF_start() from QF_run(). QF_run() typically never returns to the caller.

Note:: This function is strongly platform-dependent and is not implemented in the QF, but either in the QF port or in the Board Support Package (BSP) for the given application. All QF ports must implement QF_run().; When the Quantum Kernel (QK) is used as the underlying real-time kernel for the QF, all platfrom dependencies are handled in the QK, so no porting of QF is necessary. In other words, you only need to recompile the QF platform-independent code with the compiler for your platform, but you don't need to provide any platform-specific implementation (so, no qf_port.c file is necessary). Moreover, QK implements the function QF_run() in a platform-independent way, in the modile qk.c.

Definition at line 62 of file qvanilla.c.

References QActive_get_(), QF_active_, QF_ACTIVE_DISPATCH_, QF_gc(), QF_onStartup(), QPSet64_findMax, QPSet64_notEmpty, QPSet8_findMax, QPSet8_notEmpty, and QActive::super.

void QF_stop ( void )

Function invoked by the application layer to stop the QF application and return control to the OS/Kernel.

This function stops the QF application. After calling this function, QF attempts to gracefully stop the application. This graceful shutdown might take some time to complete. The typical use of this funcition is for terminating the QF application to return back to the operating system or for handling fatal errors that require shutting down (and possibly re-setting) the system.

This function is strongly platform-specific and is not implemented in the QF, but either in the QF port or in the Board Support Package (BSP) for the given application. Some QF ports might not require implementing QF_stop() at all, because many embedded applications don't have anything to exit to.

See also:: QF_onCleanup()

Definition at line 57 of file qvanilla.c.

References QF_onCleanup().

qvanilla.c File Reference

Functions

Detailed Description

Function Documentation