Femto OS

0.87

Introduction

Below, find an overview of the methodes you can use in your code. This list is only valid for version 0.87 of Femto OS. Please select the correct version first, for names, codes and descriptions made be significantly different between the versions.

Please have a look inside the file femtoos_core.h for a more elaborate discussion about the use. Methodes starting with 'gen' can be used from within a task, isr or code running in OS space. Methodes with the prefix 'task' should only be called from task, and may trigger a switch of context. Some methodes have a twin "onName" method, these are not seperately listed.

Methods related to task control.
genGetPriority	Return the current priority of a given task.
genGetLastWakeTime	Return the time the task was last woken.
genGetTaskname	Get the flash address of the task name
genResume	Resume the given task from suspension.
genSetPriority	Set a new priority for the given task.
genSuspend	Suspend a task, but do not invoke a context switch.
taskDelayFromNow	Delay your task for the given number of ticks, starting from now.
taskDelayFromWake	Delay your task for a number of ticks, starting at the last wake time.
taskFeedWatchdog	Feed the watchdog in order to prevent barking.
taskKillWatchdog	Switch off the watchdog facility for this task.
taskKillTask	Stop (in error mode) one particular task.
taskSuspendMe	Suspend this task and invoke a context switch.
taskRestart	Restart one particular task.
taskSleep	Put the current task to sleep and invoke a context switch.
taskSleepAll	Put all tasks to sleep.
taskStackCheck	Call to check how much free space is left on the task stack.
taskYield	Manual context switch

Methods related to OS control.
genAddtoTickCount	Add the given number of ticks to the tick counter.
genGetTickCount	Get the tick counter.
genLogOs	Binary oneliner about the os
genLogTask	Binary oneliners about every task
genPassFlashString	Auxiliary function to push a string on a pipe
genPipeInt16	Auxiliary function to push a Tint16 on a pipe
genReboot	Reboot the system
genTraceInfo	Custom trace facility, sends one byte over the traceline.
genTraceMarker	Custom trace facility, sends a marker traceline.

Methods related to synchronization.
genQueuClear	Clear the queu.
genQueuEmpty	See if the queu is empty.
genQueuFull	See if the queu is full.
genQueuPeek	Look ahead what the next byte to read would be.
genQueuWrite	Write a byte on the queu.
genQueuWriteable	See how many bytes can be written to the queu.
genQueuRead	Read a byte from the queu.
genQueuReadable	See how many bytes can be read from the queu.
genWaitRelease	Release all wait locks on this slot.
taskMutexRequestOnName	Call this if you want to take possession of a mutex on name.
taskMutexReleaseOnName	Release the lock on a mutex, by name
taskQueuWriteRequestOnName	Call this if you want to take possession of a queu on name.
taskQueuReadRequestOnName	Call this if you want to take possession of a queu on name.
taskQueuReleaseOnName	Release the lock on a queu, by name
taskSyncRequest	Try to obtain a lock on a queu , on a mutex or both.
taskSyncRelease	Release a queu, on a mutex or both.
taskSyncReleaseOnName	Release the lock on a queu or mutex, by name.
taskSyncWriteWriteRequestOnName	Call this if you want to take possession of queu's, mutex or a mix.
taskSyncWriteReadRequestOnName	Call this if you want to take possession of queu's, mutex or a mix.
taskSyncReadWriteRequestOnName	Call this if you want to take possession of queu's, mutex or a mix.
taskSyncReadReadRequestOnName	Call this if you want to take possession of queu's, mutex or a mix.
taskWaitForOtherTask	Lock this task until an other tasks pass on the same slot.
taskWaitForTasks	Lock this task until n other tasks pass on the same slot.

Methods related to interrupts.
isrBegin	Start the isr, switch to the isr stack.
isrEndReturn	Stop the isr, return to the place where the interrupt occured.
isrEndYield	Stop the isr, yield as quickly as possible
isrEnter	Start the isr by a context switch.
isrExit	End the isr, switch to the OS.
isrStackCheck	Call to check how much free space is left on the isr stack.
isrStartLoad	Start measuring the time spend in an isr.
isrStopLoad	Stop measuring the time spend in an isr.
taskEnableGlobalInterrupts	Enable global interrupts, trace when needed
taskDisableGlobalInterrupts	Disable global interrupts, trace when needed
taskEnterGlobalCritical	Enter global critical section
taskExitGlobalCritical	Exit global critical section
taskEnableSwitchTask	Enable task switching.
taskDisableSwitchTask	Disable task switching.
taskEnterSwitchCritical	Enter task switch critical section
taskExitSwitchCritical	Exit task switch critical section

Methods related to events.
isrFireEvent	Call this to fire an event from the isr.
genFireEvent	Call this to fire an event from any place.
genFireEventSet	Call this to release tasks waiting for an different events.
genCountEventBlocks	Call this to find out the number of blocks on a particular combination of events.
taskWaitForEvent	Call this to let the task wait for a specific event in the system.

Methods related to the file system.
taskFileAppendByte	Add one byte to the file, starting at the beginning when full.
taskFileClear	Clear the file by setting its size to zero, contents are unchanged.
taskFileClose	Close the file system, so other tasks may obtain access.
taskFileDirectRead	Direct read function on the file system.
taskFileDirectWrite	Direct write function on the file system.
taskFileFormat	Clean (fill with zero's) the whole diskspace.
taskFileGetSize	Get the present size of a file.
taskFileOpen	Open the file system for writing and/or reading.
taskFileReadBuffer	Read severeal bytes from the file and push them to the buffer.
taskFileReadByte	Get one byte from a file using a raw read.
taskFileReadPipe	Read severeal bytes from the file and push them to the pipe.
taskFileSetSize	Give the file a new size, contents are unchanged.
taskFileWriteBuffer	Read several bytes from the buffer and put the on file.
taskFileWriteByte	Write one byte to a file using a raw write.
taskFileWritePipe	Read several bytes from the pipe and put the on file.

Preprocessor constants
defAllEvents	Literal value to fire all events in the genFireEventSet method.
defCurrentTaskName	Literal value to specify the current task.
defCurrentTaskNumber	Value to specify the current task.
defFromFileEnd	Literal value to state to start at the end of a file.
defFromFileStart	Literal value to state to start at the beginning of a file.
defLockBlockInfinite	Use in a synchronizing method to specify it may not timeout
defLockDoNotBlock	Use in a synchronizing method to say it must return immideately
defMaxDelayTime	The highest delay time you may use.
defReadOnly	Literal value to state to open the file system in read only mode.
defReadWrite	Literal value to state to open the file system in read/write mode.
defStackInitByte	Value with which the stack is filled.
defUntilFileEnd	Literal value to state you want to run up to the end of a file.

Preprocessor functions
preBitClr	Use this function as general method to clear bits.
preEventNumberOf	Returns the event number of an event with the name "EventName".
preEqualMacros	Use to check if two macro's are equal when interpreted as strings.
preFileDefined	Use this function to see if a file is defined on a file name.
preFileNumberOf	Returns the file number of a file with the name "FileName".
preBitIsClr	Test if a bit on a particular place is cleared.
preBitIsSet	Test if a bit on a particular place is set.
preMutexDefined	Use to see if a mutex is defined on a slot name.
preQueuDefined	Use to see if a queu is defined on a slot name.
preBitSet	Use this function as general bit setter.
preSlotDefined	Use to see if a slot is in use.
preSlotNumberOf	Returns the slot number of a slot with the name "SlotName".
preTaskDefined	Use to see if a task is defined and included in the source
preTaskNumberOf	Returns the task number of a task with the name "TaskName".
preWaitDefined	Use this function to see if a wait is defined on a slot name.

Detailed descriptions

genGetPriority: Return the current priority of a given task.

Tuint08 genGetPriority(Tuint08 uiTaskNumber)

Tuint08 genGetPriorityOnName(Tlit TaskName)

Call this to retrieve the current priority of a task.Of course the information may be outdated the moment it is received. Returns a value between 0 and 7, boundary values included.

genGetLastWakeTime: Return the time the task was last woken.

Tuint16 genGetLastWakeTime(Tuint08 uiTaskNumber)

Tuint16 genGetLastWakeTimeOnName(Tlit TaskName)

When you want to know what the last time was a task was woken call this function. If it was last woken from a delay this time is always correct, otherwise activate the cfgUseCorrectWakeupTimes option. When activated, other wakeup events are recorded as well.

genGetTaskname: Get the flash address of the task name

Taddress genGetTaskname(Tuint08 uiTaskNumber)

Taddress genGetTasknameOnName(Tlit TaskName)

Call this method to get the address of the task name of the given task Note that it returns an address in flash, so take appropriate measures read the data, for example read the bytes using portFlashReadByte().

genResume: Resume the given task from suspension.

void genResume(Tuint08 uiTaskNumber)

void genResumeOnName(Tlit TaskName)

A suspended task can be resumed by this call. A task that is in an other state (running (go), terminated, sleeping) remain unchanged. So there is no harm in calling this method on such tasks.

genSetPriority: Set a new priority for the given task.

void genSetPriority(Tuint08 uiTaskNumber, Tuint08 uiNewPriority)

void genSetPriorityOnName(Tlit TaskName, Tuint08 NewPriority)

All task run in the initial priority. There are eight priorities running from 0 to 7, 0 being the lowest. The idle task runs in fictive priority -1, thus being the lowest of all. The priority can be raised or lowered at will.

genSuspend: Suspend a task, but do not invoke a context switch.

void genSuspend(Tuint08 uiTaskNumber)

void genSuspendOnName(Tlit TaskName)

Call this method if you want to suspend a particular task. The state of that task is changed to suspended immediately. This call does not force a context switch, thus if you call it with the current running task number, the method still returns and will not be scheduled again only after a context switch. The call has no effect on terminated, sleeping or tasks that already suspended. It will not work on blocked tasks eighter, since at a resume there is no garantee that the task will be released when possible. You may call suspend on running tasks that hold slots, but the tasks that are waiting their release will not be released until this task is resumed, which may be indefinitely.

taskDelayFromNow: Delay your task for the given number of ticks, starting from now.

void taskDelayFromNow(Tuint16 uiTicksToWait)

taskDelayFromNow delays your task for the given number of ticks. This value represents the minimum delay. Since the delay time is measured from the moment the delay call is issued, it cannot be used to obtain a reliable frequency.

taskDelayFromWake: Delay your task for a number of ticks, starting at the last wake time.

void taskDelayFromWake(Tuint16 uiTicksToWait)

taskDelayFromWake delays your task for the given number of ticks. The delay time is measured from the moment of last wakeup. This is automatically correct when the tasks are only stopped by delays. If however you want it to be correct in case of suspended and locked tasks as well, set cfgUseCorrectWakeupTimes to true. It can be used to obtain a reliable frequency, within the limits of the system clock and demands of other tasks.

taskFeedWatchdog: Feed the watchdog in order to prevent barking.

void taskFeedWatchdog(void)

If you activated cfgUseTaskWatchdog and fed the watchdog at least once, it is on alert. Each task has its own watchdog. After a certain time (configurable with cfgNumWatchdogDiv) it starts barking, which means it calls your bark routine if specified and subsequently restarts the task, by re-intializing the context and calling your loop code. To prevent the watchdog from barking, call taskFeedWatchdog() regularly from you code. If you want to stop its activity call taskKillWatchdog(). Please note that every loop starts with de-activated watchdog, the watchdog is activated after the first taskFeedWatchdog(). If a task got stuck and is restarted, the watchdog is de-activated! Make sure you activate it early in your code.

taskKillWatchdog: Switch off the watchdog facility for this task.

void taskKillWatchdog(void)

See also taskFeedWatchdog(). A watchdog once activated must or be fed or be killed in order to keep it quit. You can call taskKillWatchdog on a already dead watchdog.

taskKillTask: Stop (in error mode) one particular task.

void taskKillTask(Tuint08 uiTaskNumber)

void taskKillTaskOnName(Tlit TaskName)

Call this function if you want to stop a task permanently. The task is terminated and cannot be revived by resume or so. In case you have some checking activated, and the system detects an error, the task is brought to the same state. A terminated task can be restarted, provided you compiled the necessary code in. See taskResart for more information.

taskSuspendMe: Suspend this task and invoke a context switch.

void taskSuspendMe(void)

If you need to suspend your task immediately call this method. The suspended state is directly applied, a context switch is performed. This method only returns is an other task (or isr) calls genResume on your task. If you want a task in suspended mode, do not call this from an init routine, but from the beginning of the infinity loop.

taskRestart: Restart one particular task.

void taskRestart(Tuint08 uiTaskNumber)

void taskRestartOnName(Tlit TaskName)

Restart a task by recreating its context. Init or bark are NOT called again, these are for one time (harware) initialization. The context is cleared, locks are released, and the Loop is called, as if the task is new. Your (private) static variables are not cleaned or changed. The task may be terminated, running or in whatever state. You may even call it on you own task, in wich case this call does not return.

taskSleep: Put the current task to sleep and invoke a context switch.

void taskSleep(void)

Call this if you want to put the current task into low power sleep. A sleeping task is not rescheduled for operation, and cannot be woken by the user anymore (it can be restarted though). If all tasks are in sleep state, or some delays are sufficiently long, the device may go to low power sleep, see the options for details. Note that there is no call to put an other specific task to sleep. The method returns when the sleep has taken place. Never call sleep when you have a write lock on the file system, and it is unwise to call it when you hold a read lock (since it will prevent other tasks from writing). Thus call sleep after you have completed file operations (i.e. after fileClose)

taskSleepAll: Put all tasks to sleep.

void taskSleepAll(void)

Call this is you want give the OS the possibility to go to low power sleep directly. It puts all tasks into low power sleep, which should normally trigger the sleep mode. If any task is using the file system, or is blocking to get access, Femto OS waits until all file write operations have come to an end, and puts the system to sleep directly after. Tasks not using the FS at the moment of calling are put so sleep immideately. The current task may make use of the FS and is treated like other tasks. Thus if the task is in read only mode it will sleep directly; if the task is in read/write mode it will do so at taskFileClose(). See also the discussion on taskSleep(). The method returns when the sleep has taken place.

taskStackCheck: Call to check how much free space is left on the task stack.

Tuint08 taskStackCheck(Tuint08 uiExtraStackSafety)

With this function you can check on any place in your code what would happen if a context switch was made here. This function only works when cfgCheckTaskStack set to cfgTrue. Otherwise the function is still defined, but returns 0, so that it does need to be removed every time you switch the cfgCheckTaskStack setting. With the parameter uiExtraStackSafety you can supply how much extra marge you require at this place. Use this to compensate for extra stack in calls in which you cannot place this function. The uiExtraStackSafety comes onto op the normal StackSafety parameter. Thus the larger the uiExtraStackSafety the quicker an (expected) error occurs.
This function returns the amount of free (real) stackspace at the moment of calling, that would be left over, if an context save would happen right at this place, appart from the safety parameters, but the stack required for this call incluided. Thus, if it returns 0 you are living on the edge. This function also operates correctly if the stacklevel and uiExtraStackSafety together exceed the 255 byte limit.

taskYield: Manual context switch

void taskYield(void)

Call this function inside your code when you want to force a context switch. Note it makes no real sense to call it if you are the task with the highest priority for it will immediately return. Mostly you use this call as some kind of cooperative escape from part of your code where interrupts are disabled.

genAddtoTickCount: Add the given number of ticks to the tick counter.

void genAddtoTickCount(Tuint16 uiSleepTime)

With this function it is possible to add some value to the tick counter, which is shifted to the future. All missed appTick00() and appTick08() calls are NOT catched up. However an appTick16() call is performed should the tick counter roll over. This method is typically used in situations where the processor is put into a low power sleep.

genGetTickCount: Get the tick counter.

Tuint16 genGetTickCount(void)

Returns the current value of the tick counter. The tick counter is a 16 bit value running from 0 to 0xFFFF. If the tick interrupts come every ms we have a timer of approximately 65 secs.

genLogOs: Binary oneliner about the os

void genLogOs(void (*pipe)(Tchar))

Call this funcion to obtain information about the OS itself The information is piped through the given pipe method, which could be a write method on a queu, so there is no need for a separate buffer. The information is in binary form, of the following form: Id(1) StatusOs(1) LoadOs(2) LoadIdle(2) LoadIsr(2) StackOsMax(1) StackIsrMax(1) the number indicating the number of bytes to be expected.

genLogTask: Binary oneliners about every task

void genLogTask(Tuint08 uiTaskNumber, void (*pipe)(Tchar))

Call this function to obtain information about the a task in the OS. The information is piped through the given pipe method, which could be a write method on a queu, so there is no need for a separate buffer. The information is in binary form, of the following form: Id(1) TaskNr(1) Status(1) LoadOs/0(2) Name(8) TaskMonitor(1) TaskLevels(1) SlotStack(4) StackMax(1) RegUse(1) the number indicating the number of bytes to be expected.

genPassFlashString: Auxiliary function to push a string on a pipe

void genPassFlashString(Taddress pString, Tuint08 uiLength, Tchar cFilling, void (*pipe)(Tchar))

Inside genLogOs and genLogTask use is made of the function to pipe a string from flash. When uiLength == 0 this method continues and scans the string for a terminating null character. If uiLength > 0 the number of chars is exactly uiLength. If the real length of the string is shorter it is augmented with cFilling chars, otherwise the string is just truncated. The terminating null character is never copied. Note that this function when used externally uses excessive amount of stack so that is may be more efficient to just duplicate the code and inline it.

genPipeInt16: Auxiliary function to push a Tint16 on a pipe

void genPipeInt16(Tuint16 uiValue, void (*pipe)(Tchar))

Inside genLogOs and genLogTask use is made of the function to pipe a 16 bit number. It is available for the user also. Note that this function when used externally uses exessive amount of stack so that is may be more efficient to just duplicate the code and inline it.

genReboot: Reboot the system

void genReboot(void)

This call reboots, but not necessarily resets, the system. The actual result depends on the contents of portReboot(), but on the my avr it simply calls reset, which does not imply a full hardware reset. The software is fully reset though, inclusive cleaning of all variables. As this function may be called from an interrupt it may be used to reactivate a dead system. An other use is a call in a shell. Normally however, there is not much need for such a function. This function should not return.

genTraceInfo: Custom trace facility, sends one byte over the traceline.

void genTraceInfo(Tbyte bUser)

You can make use of the trace facility yourself by using this routine. It puts out one payload byte after the eventUserByteMessage trace message. If cfgCheckTrace == cfgFalse it is replaced by an empty statement. Include with

genTraceMarker: Custom trace facility, sends a marker traceline.

void genTraceMarker()

You can make use of the trace facility yourself by using this routine. Use the marker to start tracing a some later point. In the trace program you can specify how many markers must have passed before the tracing starts. If cfgCheckTrace == cfgFalse it is replaced by an empty statement.

genQueuClear: Clear the queu.

void genQueuClear(Tuint08 uiSlot)

void genQueuClearOnName(Tlit SlotName)

Call this to clear the queu. The remaining bytes are not removed, but the read and write pionters are simply reset. Be carefull with clearingto queus with write blocks on it, for those tasks may block indefinitely (if no timeout has been specified), even if cleaning means that room has become available to write some bytes.

genQueuEmpty: See if the queu is empty.

Tbool genQueuEmpty(Tuint08 uiSlot)

Tbool genQueuEmptyOnName(Tlit SlotName)

A quick method to see if the queu is empty. Interrupts are blocked only shortly inside.

genQueuFull: See if the queu is full.

Tbool genQueuFull(Tuint08 uiSlot)

Tbool genQueuFullOnName(Tlit SlotName)

A quick method to see if the queu is full. Interrupts are not blocked inside since the information is obtained in a single atomair read operation.

genQueuPeek: Look ahead what the next byte to read would be.

Tbyte genQueuPeek(Tuint08 uiSlot)

Tbyte genQueuPeekOnName(Tlit SlotName)

Instead of reading the byte from the queu, sometimes you want to know which byte is comming without removing that byte. Call this method to peek into the queu. If the queu is empty, it returns 0.

genQueuWrite: Write a byte on the queu.

void genQueuWrite(Tuint08 uiSlot, Tbyte bItem)

void genQueuWriteOnName(Tlit SlotName, Tbyte bItem)

Call this method if you want to write one byte to the queu. The execution takes place in task space, and may require some stackspace. Before you write a byte please first obtain a lock on the queu, or be sure you are the only one writing/reading (in an isr you cannot obtain a lock). The read/write methods are tick/interrupt protected. Thus it is possible to use the queu mechnism without the request/release methods, if you take care of locking and counting of the bytes yourself. This is particularly handy when working with interrupts A queu may filled in the interrupt and read in a task. If you write on a full queu the new bytes are disposed and not placed on the queu.

genQueuWriteable: See how many bytes can be written to the queu.

Tuint08 genQueuWriteable(Tuint08 uiSlot)

Tuint08 genQueuWriteableOnName(Tlit SlotName)

This method return how may bytes can be read to the queu. This is really a temporarily value, but since you know which tasks read/write on the queu, you can judge how stable it is.

genQueuRead: Read a byte from the queu.

Tbyte genQueuRead(Tuint08 uiSlot)

Tbyte genQueuReadOnName(Tlit SlotName)

Call this method if you want to read one byte from the queu. The execution takes place in task space, and may require some stackspace. Before you write a byte please first obtain a lock on the queu, or be sure you are the only one writing/reading (in an isr you cannot obtain a lock). The read/write methods are tick/interrupt protected. Thus it is possible to use the queu mechnism without the request/release methods, if you take care of locking and counting of the bytes yourself. This is particularly handy when working with interrupts A queu may filled in the interrupt and read in a task. If you read from an empty queu the returned value is 0.

genQueuReadable: See how many bytes can be read from the queu.

Tuint08 genQueuReadable(Tuint08 uiSlot)

Tuint08 genQueuReadableOnName(Tlit SlotName)

This method return how may bytes can be written to the queu. This is really a temporarily value, but since you know which tasks read/write on the queu, you can judge how stable it is.

genWaitRelease: Release all wait locks on this slot.

void genWaitRelease(Tuint08 uiSlot)

void genWaitReleaseOnName(Tlit SlotName)

Use this call to release a rendez vous started with taskWaitForTasks() or taskWaitForOtherTask(). All waiting tasks are released and return true when cfgUseTimeoutOnSync is activated. Note this method can be called from within an isr. On other speciality is that this call may also be performed from tasks not holding slots by themselfes.

taskMutexRequestOnName: Call this if you want to take possession of a mutex on name.

Tbool taskMutexRequestOnName(Tlit SlotName, Tuint16 uiTicksToWait)

Tbool taskMutexRequestOnName(Tlit SlotName)

Call this if you want to take possession of a mutex. Use the (literal) slotname. The task blocks until the mutex is available.
You must specify a timeout, if cfgUseTimeoutOnSync is activated. You can spefify anything from 2 to defMaxDelayTime. If you need an infinite wait, specify defLockBlockInfinite, and if you want an immedieate return specify defLockDoNotBlock, to make your intensions clear. The method returns true or false, if cfgUseBoolReturns was activated. True means that the lock has been obtained, false means a timeout. If cfgUseBoolReturns was deactivated it may return any numerical value.

taskMutexReleaseOnName: Release the lock on a mutex, by name

void taskMutexReleaseOnName(Tlit SlotName)

These macro make it possible to release a lock on a mutex on the basis of the name. It performs the same action as taskSyncRelease() but an extra check is included if the slot indeed holds a queu.

taskQueuWriteRequestOnName: Call this if you want to take possession of a queu on name.

Tbool taskQueuWriteRequestOnName(Tlit SlotName, Tsint08 siFreeFilling, Tuint16 uiTicksToWait)

Tbool taskQueuWriteRequestOnName(Tlit SlotName, Tsint08 siFreeFilling)

Tbool taskQueuReadRequestOnName(Tlit SlotName, Tsint08 siFreeFilling, Tuint16 uiTicksToWait)

Tbool taskQueuReadRequestOnName(Tlit SlotName, Tsint08 siFreeFilling)

Call this if you want to take possession of a queu. Use the (literal) slotname. You must specify the number of bytes you want to read or write, which can be anything from 0 up to 127, boundaries included. The task blocks until the queu is available.
You must specify a timeout, if cfgUseTimeoutOnSync is activated. You can spefify anything from 2 to defMaxDelayTime. If you need an infinite wait, specify defLockBlockInfinite, and if you want an immedieate return specify defLockDoNotBlock, to make your intensions clear. The method returns true or false, if cfgUseBoolReturns was activated. True means that the lock has been obtained, false means a timeout. If cfgUseBoolReturns was deactivated it may return any numerical value.

taskQueuReleaseOnName: Release the lock on a queu, by name

void taskQueuReleaseOnName(Tlit SlotName)

These macro make it possible to release a lock on a queu on the basis of the name. It performs the same action as taskSyncRelease() but an extra check is included if the slot indeed holds a queu.

taskSyncRequest: Try to obtain a lock on a queu , on a mutex or both.

Tbool taskSyncRequest(Tuint08 uiSlotSlot, Tsint08 siFreeLeftFilling, Tsint08 siFreeRightFilling, Tuint16 uiTicksToWait)

Tbool taskSyncRequest(Tuint08 uiSlotSlot, Tsint08 siFreeRightFilling, Tuint16 uiTicksToWait)

void taskSyncRequest(Tuint08 uiSlotSlot, Tsint08 siFreeLeftFilling, Tsint08 siFreeRightFilling)

void taskSyncRequest(Tuint08 uiSlotSlot, Tsint08 siFreeRightFilling)

The method taskSyncRequest is the general way to obtain a lock on a mutex or queu. It is even possible to obtain a simultaneos lock on two mutexes, two queus or a mutex and a queu. Simultaneous locks hold the task blocked until both resources are free. The uiSlotSlot, may contain one slot as parameter (the least significant nibble) or two slots, one in the low nibble and one in the high nibble. Only a slot in the high nibble is not allowed, even as two indentical slots. (Would not make much sense eighter). For queu's you must specify if , and how many bytes are to be read (>0) or written (<0), maximally 127 bytes.
     The request blocks until the requested number of bytes is avaiable for reading or writing. If you just want access to the queu, supply 0. For mutexes, supply zero for the free filling parameter (in practice it is ignored, but gives an error if method checking is activated)
     The method returns true or false, if cfgUseBoolReturns was activated. True means that the lock has been obtained. You can specify a timeout, if cfgUseTimeoutOnSync is activated, in which case it may return false, indicating a timeout. If cfgUseBoolReturns was deactivated it may return any value.
     Slots must be configured as queu's in the config section. Queu always fill up the lowest slot numbers, thus 1..n where n is the maximum number of queu's. The mutexes are numbered n+1 ... n+m, where m is the number of mutexes. But, it is easier to make use of named queus and muytexes. If you do, make use of the predefined macro's for easy access to the method defined below.

taskSyncRelease: Release a queu, on a mutex or both.

void taskSyncRelease(Tuint08 uiSlotSlot)

After you have taken a queu, mutex or both, you must release them with this call, to unblock other tasks. There is no obligation to release slots which are taken simultaneously in the same manner, but it is allowed. Also, you may use this function to releasy more than one slot, even if they where not taken simultaneously. This may be used to influence the way other tasks are deblocked. For clarity however, it is best to release in the same manner as the slots where locked.

taskSyncReleaseOnName: Release the lock on a queu or mutex, by name.

void taskSyncReleaseOnName(Tlit SlotLeftName, Tlit SlotRightName)

These macro make it possible to release locks on the basis of the name. If other tasks had a lock on the queu the system checks all task with respect to their lockcondition. The first task that meets the requirement will be released. Scanning is done in task number order, not in priority order. The macros containing the type of slot contain code which check the type of the slot, if cfgCheckMethodUse is activated. So preferable use these. When making use of double slots the distinction between mutex and queu cannot be made.

taskSyncWriteWriteRequestOnName: Call this if you want to take possession of queu's, mutex or a mix.

taskSyncWriteReadRequestOnName: Call this if you want to take possession of queu's, mutex or a mix.

taskSyncReadWriteRequestOnName: Call this if you want to take possession of queu's, mutex or a mix.

taskSyncReadReadRequestOnName: Call this if you want to take possession of queu's, mutex or a mix.

Tbool taskSyncWriteWriteRequestOnName(Tlit SlotLeftName, Tlit SlotRightName, Tsint08 siFreeLeftFilling, Tsint08 siFreeRightFilling, Tuint16 uiTicksToWait)

Tbool taskSyncWriteWriteRequestOnName(Tlit SlotLeftName, Tlit SlotRightName, Tsint08 siFreeLeftFilling, Tsint08 siFreeRightFilling)

Tbool taskSyncReadWriteRequestOnName(Tlit SlotLeftName, Tlit SlotRightName, Tsint08 siFreeLeftFilling, Tsint08 siFreeRightFilling, Tuint16 uiTicksToWait)

Tbool taskSyncReadWriteRequestOnName(Tlit SlotLeftName, Tlit SlotRightName, Tsint08 siFreeLeftFilling, Tsint08 siFreeRightFilling)

Tbool taskSyncWriteReadRequestOnName(Tlit SlotLeftName, Tlit SlotRightName, Tsint08 siFreeLeftFilling, Tsint08 siFreeRightFilling, Tuint16 uiTicksToWait)

Tbool taskSyncWriteReadRequestOnName(Tlit SlotLeftName, Tlit SlotRightName, Tsint08 siFreeLeftFilling, Tsint08 siFreeRightFilling)

Tbool taskSyncReadReadRequestOnName(Tlit SlotLeftName, Tlit SlotRightName, Tsint08 siFreeLeftFilling, Tsint08 siFreeRightFilling, Tuint16 uiTicksToWait)

Tbool taskSyncReadReadRequestOnName(Tlit SlotLeftName, Tlit SlotRightName, Tsint08 siFreeLeftFilling, Tsint08 siFreeRightFilling)

Call this if you want to take possession of two queu's, mutexes or one queu and one mutex. Use the (literal) slotnames. You must specify the number of bytes you want to read or write for queus, which can be anything from 0 up to 127, boundaries included. For mutexes specify 0 for the freefilling. The task blocks until both resources are available.
You must specify a timeout, if cfgUseTimeoutOnSync is activated. You can spefify anything from 2 to defMaxDelayTime. If you need an infinite wait, specify defLockBlockInfinite, and if you want an immedieate return specify defLockDoNotBlock, to make your intensions clear. The method returns true or false, if cfgUseBoolReturns was activated. True means that the lock has been obtained, false means a timeout. If cfgUseBoolReturns was deactivated it may return any numerical value.

taskWaitForOtherTask: Lock this task until an other tasks pass on the same slot.

Tbool taskWaitForOtherTask(Tuint08 uiSlot, Tuint16 uiTicksToWait)

void taskWaitForOtherTask(Tuint08 uiSlot)

Tbool taskWaitForOtherTaskOnName(Tlit SlotName, Tuint16 uiTicksToWait)

void taskWaitForOtherTaskOnName(Tlit SlotName)

Use this function to hold one task and let it wait for an other task to pass the same lock. In other words it is a simple rendezvous You can specify a timeout, if cfgUseTimeoutOnSync is activated. The function returns true if the rendezvous took place, false otherwise, if the cfgUseBoolReturns is activated. Otherwise the return value is undefined.

taskWaitForTasks: Lock this task until n other tasks pass on the same slot.

Tbool taskWaitForTasks(Tuint08 uiSlot, Tuint08 uiNumberOfTasks, Tuint16 uiTicksToWait)

void taskWaitForTasks(Tuint08 uiSlot, Tuint08 uiNumberOfTasks)

Tbool taskWaitForTasksOnName(Tlit SlotName, Tuint08 uiNumberOfTasks, Tuint16 uiTicksToWait)

void taskWaitForTasksOnName(Tlit SlotName, Tuint08 uiNumberOfTasks)

Use this function to hold one or more tasks and let it wait for the given number of tasks to pass the same lock. In other words it is a rendezvous of N (uiNumberOfTasks) tasks. Make sure N is equal on all calls because as soon as the number of tasks is equal or lower a the value specified all are released. You can specify a timeout, if cfgUseTimeoutOnSync is activated. The function returns true if the rendezvous took place, false otherwise, if the cfgUseBoolReturns is activated. Otherwise the return value is undefined.

isrBegin: Start the isr, switch to the isr stack.

isrBegin()

isrBegin() is used when you want the interrupt to be serviced as quickly as possible. No context is saved, so you are responsible for saving and restoring any registers you use, including the status register. You can however let GCC take care of this. Note that, if you use many registers, this may take more time than a context save. Andvantage is that you can interrupt the OS if you want, depending on the setting of cfgIntOsProtected. If you want to measure the time spend inside the interrupt you must manually call the irsStartLoad/isrStopLoad routines, and make sure you save the registers utilized inside as well.

isrEndReturn: Stop the isr, return to the place where the interrupt occured.

isrEndReturn()

isrEndReturn(): use this to return from a isr to the place the interrupt occured. It is your only option is you have no OS protection. Restore anything you corrupted, this is your own responsibility. The only thing the isrBegin() / isrReturn() pair takes care of is the stack switch. So inside the isr you have the ISR stack.

isrEndYield: Stop the isr, yield as quickly as possible

isrEndYield()

isrEndYield(): use this if you want a context switch directly after the handling of your interrupt. You are stil responsible for restoring any registers, so it only makes sense to use isrBegin() / isrYield() over isrEnter() / isrExit() if your response to the interrupt need to be very fast and does not require that many operations. Since this method calls taskYield() that method must be included too.

isrEnter: Start the isr by a context switch.

isrEnter()

Use isrEnter() to start an isr with a context switch. The current task is pushed to the context (so this is only available when the interrupts comes when a task is running, i.e. cfgIntOsProtected must be set) and, depening on the setting of cfgIntSwitchUsesOSstack work is continued on the OS or ISR stack. Always close the isr with isrExit(). If selected the time spend in the isr is measured automatically

isrExit: End the isr, switch to the OS.

isrExit()

isrStackCheck: Call to check how much free space is left on the isr stack.

Tuint08 isrStackCheck(Tuint08 uiExtraStackSafety)

With this function you call check the amount of free space in the isr stack. (a context switch never happens here). This function only works when cfgCheckIsrStack set to cfgTrue. Otherwise the function is still defined, but returns 0, so that it does need to be removed every time you switch the cfgCheckIsrStack setting. With the parameter uiExtraStackSafety you can supply how much extra marge you require at this place. Note that the total of present isr stacksize and uiExtraStackSafety should not exceed the 255 bytes. This function returns the amount of free (real) isr stackspace at the moment of calling, appart from the safety parameters. Of course the 2 bytes as result of the call are extra.
This function does not operate when cfgIntSwitchUsesOSstack is set to true since in that case the isr makes use of the OS stack.

isrStartLoad: Start measuring the time spend in an isr.

void isrStartLoad(void)

IsrStartLoad measures the total time spend in interrupts. You only need to call it at the beginning of your interrupt service routine if you took onw responsibility of the context save, i.e. if you came at the place with isrBegin. It starts the stopwatch for measuring the time inside an isr. You can leave the call in you code when switching off cfgUseLoadMonitor, it will be replaced by an empty statement.

isrStopLoad: Stop measuring the time spend in an isr.

void isrStopLoad(void)

IsrStopLoad measures the total time spend in interrupts. You only need to call it at the end of your interrupt service routine if you took own responsibility of the context save, i.e. before you leave with isrEndYield() or isrEndReturn(). It stops the stopwatch for measuring the time inside an isr. You can leave the call in you code when switching off cfgUseLoadMonitor, it will be replaced by an empty statement.

taskEnableGlobalInterrupts: Enable global interrupts, trace when needed

taskEnableGlobalInterrupts()

taskEnable/DisableGlobalInterrupts makes it possible to set/clear the global interrupt flag. Don't call portEnable, but call taskEnable to make you code general. Note these calls cannot be nested, i.e. they are absolute and work instantly. If cfgCheckTrace is switched on, the call is traced. Never call Enable/Disable interrupts inside critical sections.

taskDisableGlobalInterrupts: Disable global interrupts, trace when needed

taskDisableGlobalInterrupts()

taskEnterGlobalCritical: Enter global critical section

void taskEnterGlobalCritical(void)

Use taskEnter/ExitGlobalCritical if you need nested (de)activation of the global interrupts. Nesting is only active when cfgUseNestedCriticals is set, otherwise these calls are replaced by simple taskEnterGlobalCritical. Thus, in fact you can always use this call, and decide lateron on its functionality. It is the most general way. The same mechanism about interrupt tracking applies as with taskEnable/ DisableGlobalInterrupts.

taskExitGlobalCritical: Exit global critical section

void taskExitGlobalCritical(void)

Use taskEnter/ExitGlobalCritical if you need nested (de)activation of the global interrupts. Nesting is only active when cfgUseNestedCriticals is set, otherwise these calls are replaced by simple taskExitGlobalCritical. Thus, in fact you can always use this call, and decide lateron on its functionality. It is the most general way. The same mechanism about interrupt tracking applies as with taskEnable/ DisableGlobalInterrupts.

taskEnableSwitchTask: Enable task switching.

void taskEnableSwitchTask(void)

Call this to unblock context switching. The tick interrupts keep coming, and the tick counter keeps increasing and delayed task wakeup etcetera. Task switching is restored, and high priority tasks are rescheduled. Call after a taskDisableSwitchTask().
Do not call this if you make use of Enter/Exit Switch critical sections. since it disturbs the nesting counting. In fact, it is even better to use taskEnterSwitchCritical() and taskExitSwitchCritical(), even if you do not need nesting. The system then translates this to taskEnableSwitchTask or taskDisableSwitchTask.

taskDisableSwitchTask: Disable task switching.

void taskDisableSwitchTask(void)

Call this to block context switching. The tick interrupts keep coming, and the tick counter keeps increasing and delayed task wakeup etcetera. Only thing is, there is no task switch, thus by using this method a low priority task can take (keep it temporarily) full processor time, and will behave like a top priority task.
Do not call this if you make use of Enter/Exit Switch critical sections. since it disturbs the nesting counting. In fact, it is even better to use taskEnterSwitchCritical() and taskExitSwitchCritical(), even if you do not need nesting. The system then translates this to taskEnableSwitchTask or taskDisableSwitchTask.

taskEnterSwitchCritical: Enter task switch critical section

void taskEnterSwitchCritical(void)

Use taskEnter/ExitSwitchCritical if you need nested (de)activation of the task switches. Nesting is only active when cfgUseNestedCriticals is set, otherwise these calls are replaced by simple taskDisableSwitchTask() or taskEnableSwitchTask(). Thus, in fact you can always use this call, and decide lateron on its functionality. It is the most general way.

taskExitSwitchCritical: Exit task switch critical section

void taskExitSwitchCritical(void)

isrFireEvent: Call this to fire an event from the isr.

void isrFireEvent(Tuint08 uiEvent)

This method is not a regular method but a define, to be as quick as possible. It is assumend to compiler is able to compile it into a single bit-write instruction (avr). If this is not possible, be sure you only call it when interrupts are disabled, usually from an isr. GCC is able to compile this into an atomic instruction for the AVR provided you supply a constant, or if you use the isrFireEventOnName() call, and the register devAuxEventReg is the lowest I/O section (0x00-0x1F). So you should not call it with a variable. If you need to fire more events, call this function several times, once for each event. Note that this call is never traced.
     A specialty of this method is that it can be utilized on the AVR within naked signal handlers without any register saving, provided it compiles to an atomic instruction. This makes interrupt handling extremely fast. Just release some task and go on. The interrupt handles does not need to contain more that two instructions.
     Merely firing an event does not require the task to have event capabilities, it is even more efficient when the task does not include the capabilities. Waiting for an event however does.
     If you obtain a "left shift count is negative" from the compiler upon your call you have used an invalid event number, less than zero, bigger then 7 or equal to the AuxRegBit of the Femto OS (the registers for events and the Femto OS auxilairy register may be shared, but in that case you may not use the one bit Femto OS needs). Please correct the situation and do not ignore it just because it is a only warning.

genFireEvent: Call this to fire an event from any place.

void genFireEvent(Tuint08 uiEvent)

This method is a regular method or a define, depending on circumstances. If devAuxEventReg is the lowest I/O section (0x00-0x1F), and tracing is deactivated and we make no use of cfgUseEventsOnVariables then this is identical to isrFireEvent. Otherwise a special method is defined which disables global interrupts first, and subsequently traces, checks or otherwise handles the call. It may be used from any location, including an isr, but of course it can be a lot slower/larger. When cfgUseEventsOnVariables is used, you may call isrFireEvent with a variable as parameter.
Merely firing an event does not require the task to have event capabilities, it is even more efficient when the task does not include the capablities. Waiting for an event however does.
If you obtain a "left shift count is negative" from the compiler upon your call you have used an invalid event number, less than zero, bigger then 7 or equal to the AuxRegBit of the Femto OS (the registers for events and the Femto OS auxilairy register may be shared, but in that case you may not use the one bit Femto OS needs). Please correct the situation and do not ignore it just because it is only a warning.

genFireEventSet: Call this to release tasks waiting for an different events.

void genFireEventSet(Tuint08 uiEventSet)

void genFireEventSetOnNames2(Tlit EventName1, Tlit EventName2)

void genFireEventSetOnNames3(Tlit EventName1, Tlit EventName2, Tlit EventName3)

void genFireEventSetOnNames4(Tlit EventName1, Tlit EventName2, Tlit EventName3, Tlit EventName4)

void genFireEventSetOnNames5(Tlit EventName1, Tlit EventName2, Tlit EventName3, Tlit EventName4, Tlit EventName5)

void genFireEventSetOnNames6(Tlit EventName1, Tlit EventName2, Tlit EventName3, Tlit EventName4, Tlit EventName5, Tlit EventName6)

void genFireEventSetOnNames7(Tlit EventName1, Tlit EventName2, Tlit EventName3, Tlit EventName4, Tlit EventName5, Tlit EventName6,  Tlit EventName7)

void genFireAllEvents()

Using this call you may fire any combination of events simultaneously. Note it is a real function call and is not compiled to one atomic instruction. Call genFireAllEvents() to release a blocking tasks at once. The execution of this method takes place in a non interruptible realm.
Merely firing events does not require the task to have event capabilities, it is even more efficient when the task does not include the capabilities. Waiting for an event however does.

genCountEventBlocks: Call this to find out the number of blocks on a particular combination of events.

Tuint08 genCountEventBlocks(Tuint08 uiEventSet)

void genCountEventBlocksOnNames2(Tlit EventName1, Tlit EventName2)

void genCountEventBlocksOnNames3(Tlit EventName1, Tlit EventName2, Tlit EventName3)

void genCountEventBlocksOnNames4(Tlit EventName1, Tlit EventName2, Tlit EventName3, Tlit EventName4)

void genCountEventBlocksOnNames5(Tlit EventName1, Tlit EventName2, Tlit EventName3, Tlit EventName4, Tlit EventName5)

void genCountEventBlocksOnNames6(Tlit EventName1, Tlit EventName2, Tlit EventName3, Tlit EventName4, Tlit EventName5, Tlit EventName6)

void genCountEventBlocksOnNames7(Tlit EventName1, Tlit EventName2, Tlit EventName3, Tlit EventName4, Tlit EventName5, Tlit EventName6,  Tlit EventName7)

void genCountEventBlocksOnAll()

You may want to postpone firing an event until one or more tasks are actually blocking on it. Call this to get the current number of tasks blocking on all the events given. If it is called in isr or interrupt protected environment the number is accurate. If not it is a lower bound, when the calling task is the only one capable of firing the particular event.

taskWaitForEvent: Call this to let the task wait for a specific event in the system.

Tbool taskWaitForEvent(Tuint08 uiEvent, Tuint16 uiTicksToWait)

Tbool taskWaitForEvent(Tuint08 uiEvent)

void taskWaitForEventSetOnNames1(Tlit EventName1)

void taskWaitForEventSetOnNames2(Tlit EventName1, Tlit EventName2)

void taskWaitForEventSetOnNames3(Tlit EventName1, Tlit EventName2, Tlit EventName3)

void taskWaitForEventSetOnNames4(Tlit EventName1, Tlit EventName2, Tlit EventName3, Tlit EventName4)

void taskWaitForEventSetOnNames5(Tlit EventName1, Tlit EventName2, Tlit EventName3, Tlit EventName4, Tlit EventName5)

void taskWaitForEventSetOnNames6(Tlit EventName1, Tlit EventName2, Tlit EventName3, Tlit EventName4, Tlit EventName5, Tlit EventName6)

void taskWaitForEventSetOnNames7(Tlit EventName1, Tlit EventName2, Tlit EventName3, Tlit EventName4, Tlit EventName5, Tlit EventName6,  Tlit EventName7)

void taskWaitForAllEvents()

void taskWaitForEventSetOnNames1(Tlit EventName1, Tuint16 TicksToWait)

void taskWaitForEventSetOnNames2(Tlit EventName1, Tlit EventName2, Tuint16 TicksToWait)

void taskWaitForEventSetOnNames3(Tlit EventName1, Tlit EventName2, Tlit EventName3, Tuint16 TicksToWait)

void taskWaitForEventSetOnNames4(Tlit EventName1, Tlit EventName2, Tlit EventName3, Tlit EventName4, Tuint16 TicksToWait)

void taskWaitForEventSetOnNames5(Tlit EventName1, Tlit EventName2, Tlit EventName3, Tlit EventName4, Tlit EventName5, Tuint16 TicksToWait)

void taskWaitForEventSetOnNames6(Tlit EventName1, Tlit EventName2, Tlit EventName3, Tlit EventName4, Tlit EventName5, Tlit EventName6, Tuint16 TicksToWait)

void taskWaitForEventSetOnNames7(Tlit EventName1, Tlit EventName2, Tlit EventName3, Tlit EventName4, Tlit EventName5, Tlit EventName6,  Tlit EventName7, Tuint16 TicksToWait)

void taskWaitForAllEvents(Tuint16 TicksToWait)

This function is used as a lightweight alternative to synchronization to slots. There are 8 predefined events ready to use. If you call this function on one or more of those events, the task blocks until all of these events have fired. Events are typically fired one at the time, so the task is reactivated when the last event has fired. Firing event is possible from within an isr, even if the OS is set interuptable. Thus this can make you application very responsive, while not being bound to handle all matters inside an isr. Any task being able to wait for events must have the CapEvent capability.

taskFileAppendByte: Add one byte to the file, starting at the beginning when full.

void taskFileAppendByte(Tuint08 uiFileNumber, Tbyte bItem)

void taskFileAppendByteOnName(Tlit FileName, Tbyte bItem)

The call taskFileAppendByte() adds one byte to the file in a size maintained manner (only available if cfgUseFileSystemMaintainFAT is activated). The byte is first written, and subsequently the file size is increased. In case of power failure in between, it is as if the file was never exented. If the file is full, the byte is written at the beginning, so that this call may be used to implement a ring buffer. In the latter case, the filesize is set to zero first, then the byte is written and subsequently the size is set to one. Only use after taskFileOpen().

taskFileClear: Clear the file by setting its size to zero, contents are unchanged.

void taskFileClear(Tuint08 FileNumber)

void taskFileClearOnName(Tlit FileName)

If cfgUseFileSystemMaintainFAT is activated the size of each file is maintained by the Femto OS. It is however possible to change the size to zero using this call. Setting the size to zero does not really remove the file (the bytes stay present), Only use after taskFileOpen().

taskFileClose: Close the file system, so other tasks may obtain access.

void taskFileClose(void)

Every call taskFileOpen() must be closed with a call to taskFileClose(). This signals the Femto OS that you are ready read/writing. It is an error to call taskFileClose() if the file access has not been opened before. If other tasks are waiting to obtain file access, calling taskFileClose() may immideately release such blocked tasks, possibly starving the current task if it runs in lower priority.

taskFileDirectRead: Direct read function on the file system.

Tbyte taskFileDirectRead(Taddress pAddress)

Sometimes it is convenient to have direct access to the file system. Instead of using the portFSReadByte, use this macro instead. It returns the value at the given address on the file system. Make sure you only call this if you are certain you have read access. For normal file operations use taskFileReadByte() or taskFileReadBuffer() instead.

taskFileDirectWrite: Direct write function on the file system.

void taskFileDirectWrite(Taddress pAddress, Tbyte bValue)

Sometimes it is convenient to have direct access to the file system. Instead of using the portFSWriteByte, use this macro instead. It stores the value at the given address on the file system. Make sure you only call this if you are certain you have write access. For normal file operations use taskFileWriteByte() or taskFileWriteBuffer() instead.

taskFileFormat: Clean (fill with zero's) the whole diskspace.

void taskFileFormat(void)

void taskFileFormatOnName(Tlit FileName)

If you need to clean the diskspace call taskFileFormat. The space used for files (and only that part) is filled with zero's. Since the FAT is situated at the start of this region, all files are set to length zero. If you set the size of these files to other values afterwards, you can be sure that file is filled with 0x00. There is no need to clean format the filesystem before use, but you must be ensure file system integrety yourself before first use. Only use after taskFileOpen().

taskFileGetSize: Get the present size of a file.

Tuint08 taskFileGetSize(Tuint08 uiFileNumber)

Tuint08 taskFileGetSizeOnName(Tlit FileName)

If cfgUseFileSystemMaintainFAT is activated the size of each file is maintained by the Femto OS. Using the call you can obtain the size of the file. Only use after taskFileOpen().

taskFileOpen: Open the file system for writing and/or reading.

Tbool taskFileOpen(Tbool bReadOnly, Tuint16 uiTicksToWait)

Tbool taskFileOpen(Tuint16 uiTicksToWait)

void taskFileOpen(Tbool bReadOnly)

void taskFileOpen(void)

Before you can read or write a file you must request access to the file system. If you need to read only, you can specify so, thereby allowing other tasks read access to the file system too. If read only is false (or absent) you have private access to the file system, for reading and writing. As with other synchronization primitives you may specify a timeout.
The function returns true when access has been granted. If you need to use the portReadByte() or portWriteByte() directly, call taskFileOpen() first and then make your calls. Note that, due to the nature of eeprom, fileOpen() works as access protection for the whole file system, and not per file. So you may make use of several files simultaneously within the realm of taskFileOpen() - taskFileClose(). taskFileOpen() calls may not be nested.

taskFileReadBuffer: Read severeal bytes from the file and push them to the buffer.

void taskFileReadBuffer(Tuint08 uiFileNumber, Tuint08 uiOffset, Tuint08 uiSize, Taddress pBuffer)

void taskFileReadBufferOnName(Tlit FileName, Tuint08 uiOffset, Tuint08 uiSize, Taddress pBuffer)

Call this method to read one or more bytes (uiSize) from position uiOffset and write them in the buffer. You can use defFromFileStart for the uiOffset parameter. Furthermore, you can use (if cfgUseFileSystemMaintainFAT is activated) defUntilFileEnd for uiSize. Note that, depending on your design of course, you should not assume a file is present. If there was a power failure at writing, the file length may be set to zero. If the length of the file does not equal zero, you may safely assume writing has been competed, before any power interruption took place. It is an error to read beyond the file size. Only use after taskFileOpen().

taskFileReadByte: Get one byte from a file using a raw read.

Tbyte taskFileReadByte(Tuint08 uiFileNumber, Tuint08 uiOffset)

Tbyte taskFileReadByteOnName(Tlit FileName, Tuint08 uiOffset)

Call taskFileReadByte() if you need one byte from a file on a random location. It is an error (but possible if checks are switched off) to read beyond the length of the file (if cfgUseFileSystemMaintainFAT is activated) or beyond the space boundary of the file. Only use after taskFileOpen().

taskFileReadPipe: Read severeal bytes from the file and push them to the pipe.

void taskFileReadPipe(Tuint08 uiFileNumber, Tuint08 uiOffset, Tuint08 uiSize, void (*pipe)(Tchar))

void taskFileReadPipeOnName(Tlit FileName, Tuint08 uiOffset, Tuint08 uiSize, void (*pipe)(Tchar))

Call this method to read one or more bytes (uiSize) from position uiOffset and push them on the pipe. You can use defFromFileStart for the uiOffset parameter. Furthermore, you can use (if cfgUseFileSystemMaintainFAT is activated) defUntilFileEnd for uiSize. Note that, depending on your design of course, you should not assume a file is present. If there was a power failure at writing, the file length may be set to zero. If the length of the file does not equal zero, you may savely assume writing has been competed, before any power interruption took place. It is an error to read beyond the file size. Only use after taskFileOpen().

taskFileSetSize: Give the file a new size, contents are unchanged.

void taskFileSetSize(Tuint08 uiFileNumber, Tuint08 uiSize)

void taskFileSetSizeOnName(Tlit FileName, Tuint08 uiSize)

If cfgUseFileSystemMaintainFAT is activated the size of each file is maintained by the Femto OS. It is however possible to change the size using this call. If the file is extended in this way, the new bytes will not be cleaned. Using the raw access taskWriteByte() these may be filled or cleaned on beforehand. It is an error to increase the size beyond the space reserved for the file at compile time. Only use after taskFileOpen().

taskFileWriteBuffer: Read several bytes from the buffer and put the on file.

void taskFileWriteBuffer(Tuint08 uiFileNumber, Tuint08 uiOffset, Tuint08 uiSize, Taddress pBuffer)

void taskFileWriteBufferOnName(Tlit FileName, Tuint08 uiOffset, Tuint08 uiSize, Taddress pBuffer)

Call this method to read one or more bytes (uiSize) from the buffer and write them to the file, starting at the position uiOffset. You can use defFromFileStart or, if cfgUseFileSystemMaintainFAT is activated, defFromFileEnd for the uiOffset parameter. It is an error to write beyond the file space. Before any writing is done, the size of the file is set to zero. After the writing has been completed, the new size is written to the FAT (when present). The procedure is to ensure file system integrity at power failure. Only use after taskFileOpen().

taskFileWriteByte: Write one byte to a file using a raw write.

void taskFileWriteByte(Tuint08 uiFileNumber, Tuint08 uiOffset, Tbyte bItem)

void taskFileWriteByteOnName(Tlit FileName, Tuint08 uiOffset, Tbyte bItem)

Call taskFileWriteByte() if you need to write one byte to a file on a random location. The write is raw in the sense that the fileSize is not maintained. You may write bytes beyond the file length, but not beyond the space boundary. For example, you may write, zero's to a file first and afterwards set its length to the desired value. Only use after taskFileOpen().

taskFileWritePipe: Read several bytes from the pipe and put the on file.

void taskFileWritePipe(Tuint08 uiFileNumber, Tuint08 uiOffset, Tuint08 uiSize, Tchar (*pipe)(void))

void taskFileWritePipeOnName(Tlit FileName, Tuint08 uiOffset, Tuint08 uiSize, Tchar (*pipe)(void))

Call this method to read one or more bytes (uiSize) from the pipe and write them to the file, starting at the position uiOffset. You can use defFromFileStart or, if cfgUseFileSystemMaintainFAT is activated, defFromFileEnd for the uiOffset parameter. It is an error to write beyond the file space. Before any writing is done, the size of the file is set to zero. After the writing has been completed, the new size is written to the FAT (when present). The procedure is to ensure file system integrity at power failure. Only use after taskFileOpen().

defAllEvents: Literal value to fire all events in the genFireEventSet method.

#define defAllEvents

If you need to unblock all waiting tasks by firing all all events use this constant in the method genFireEventSet. It makes your intentions clear.

defCurrentTaskName: Literal value to specify the current task.

#define defCurrentTaskName

In all (external) methods accepting the TaskName parameter you can specify defCurrentTask to indicate you want to use it for the current task, if you do not know that name (for example when code is run from different tasks). Never use it as a number in your code Please be absolutely sure you are inside a real task. If you are inside an isr, inside init or bark routines, you are not in task space and the current task may not be what you expect. However, the system cannot warn you for this situation. Thus, only to be used inside code that was called from appLoop_XXX.

defCurrentTaskNumber: Value to specify the current task.

#define defCurrentTaskNumber

In all (external) methodes accepting the uiTaskNumber parameter you can specify defCurrentTaskNumber to indicate you want to use it for the current task, if you do not know that number (for example when code is run from different tasks). Please be absolutely sure you are inside a real task. If you are inside an isr, inside init or bark routines, you are not in task space and the current task may not be what you expect. However, the system cannot warn you for this situation. Thus, only to be used inside code that was called from appLoop_XXX.

defFromFileEnd: Literal value to state to start at the end of a file.

#define defFromFileEnd

In most file operation calls you can specify an offset. Instead of using the real file length (which you must know or obtain), you may use this constant to start writing the new bytes at the end of the file. This constant is only available if cfgUseFileSystemMaintainFAT is activated.

defFromFileStart: Literal value to state to start at the beginning of a file.

#define defFromFileStart

In most file operation calls you can specify an offset. Instead of using zero, you may always use this constant to make your intention clear that you want to start reading or writing from the file start.

defLockBlockInfinite: Use in a synchronizing method to specify it may not timeout

#define defLockBlockInfinite

Value you can use to indicate that a lock need not to timeout. Use this rather than supply 0 to make your intensions clear.

defLockDoNotBlock: Use in a synchronizing method to say it must return immideately

#define defLockDoNotBlock

Value you can use to indicate that a lock need timeout immideately, thus just check if you can obtain the lock, but do not wait for it. Use this rather than supply 1 to make your intensions clear.

defMaxDelayTime: The highest delay time you may use.

#define defMaxDelayTime

The highest delay time you may use. If your tick time is 1ms, and since we have a 16 bit tick counter, the maximum delay is about 65 seconds. In my opinion, this is long enough. If you want to delay tasks longer it is better to get a real time signal somewhere.

defReadOnly: Literal value to state to open the file system in read only mode.

#define defReadOnly

If cfgUseFileSystemConcurrentRead is activated, it is required to specify if you want to open the file system in read only mode, or in read/write mode. Although, you can just use a boolean there, you may want to use this constant to make your intentions mode explicit.

defReadWrite: Literal value to state to open the file system in read/write mode.

#define defReadWrite

defStackInitByte: Value with which the stack is filled.

#define defStackInitByte

For testing purposes you can fill the stack with other values that 0x00. This may be handy to see if you are not misusing a register. For the shortest code, leave it to 0x00, so the compiler can rely upon the .bss section cleaning. For a discussion how to use this setting see also cfgSysRegisterCheckByte. Also see the discussion at defStackClean.

defUntilFileEnd: Literal value to state you want to run up to the end of a file.

#define defUntilFileEnd

In most file operation calls you can specify an size. Instead of using the real file length (which you must know or obtain), you may use this constant to keep reading bytes up to the end of the file. This constant is only available if cfgUseFileSystemMaintainFAT is activated.

preBitClr: Use this function as general method to clear bits.

#define preBitClr1(p,n0)

#define preBitClr2(p,n0,n1)

#define preBitClr3(p,n0,n1,n2)

#define preBitClr4(p,n0,n1,n2,n3)

#define preBitClr5(p,n0,n1,n2,n3,n4)

#define preBitClr6(p,n0,n1,n2,n3,n4,n5)

#define preBitClr7(p,n0,n1,n2,n3,n4,n5,n6)

#define preBitClr8(p,n0,n1,n2,n3,n4,n5,n6,n7)

Use this function to clear a one or more bits on a variable, or to modify one or more bits on a variable. For the AVR, if you use something like PORTA = preBitClr1(PORTA,3), it is compiled to an atomic instruction. The method is used internally since it can also deal with the cfgUndefined constant (which is ignored).
Note: n0 .. n7 should be constants and not variables.

preEventNumberOf: Returns the event number of an event with the name "EventName".

#define preEventNumberOf(EventName)

Using this function it is possible to use static names for the event instead of numbers. It returns the event number of an event with the compile time name "EventName". This function is implicitly called in all 'OnName' variants of the API calls. Make sure you correctly spell the name, since that is not checked here (and will give rise to a compile time warning only) Preferably uses names instead of numbers in your code since the numbering depends an the inclusions and may differ at different compiles. Substitution of the numbers is done at compile time and does not require code. Cannot be used in preprocessor statements.

preEqualMacros: Use to check if two macro's are equal when interpreted as strings.

#define preEqualMacros(A,B)

This is a handy function to test if two macros are equal if they do not expand down to a number. Note it can only be used in c-like if statements (not in preprocessor code) but that does not matter since the compiler optimizer sees that the argument can be fully evaluated at compile time.

preFileDefined: Use this function to see if a file is defined on a file name.

#define preFileNumberOf(FileName)

Use this function to see if a file is defined on a file name. Can be used in preproccessor statements

preFileNumberOf: Returns the file number of a file with the name "FileName".

#define preFileNumberOf(FileName)

Using this function it is possible to use static names for the files instead of numbers. It returns the file number of a file with the compile time name "FileName". This function is implicitly called in all 'OnName' variants of the API calls. Make sure you correctly spell the name, since that is not checked here (and will give rise to a compile time warning only). Preferably uses names instead of numbers in your code since the numbering depends an the inclusions and may differ at different compiles. Substitution of the numbers is done at compile time and does not require code. Cannot be used in preprocessor statements.

preBitIsClr: Test if a bit on a particular place is cleared.

#define preBitIsClr(p,q)

Use this to quickly test if a bit is cleared on a location (0..7). On the AVR this is compiled to a atomic test if possible.

preBitIsSet: Test if a bit on a particular place is set.

#define preBitIsSet(p,q)

Use this to quickly test if a bit is set on a location (0..7). On the AVR this is compiled to a atomic test if possible.

preMutexDefined: Use to see if a mutex is defined on a slot name.

#define preMutexDefined(SlotName)

Use this function to see if a mutex is defined on a slot name. Can be used in preproccessor statements

preQueuDefined: Use to see if a queu is defined on a slot name.

#define preQueuDefined(SlotName)

Use this function to see if a queu is defined on a slot name. Can be used in preproccessor statements

preBitSet: Use this function as general bit setter.

#define preBitSet1(p,n0)

#define preBitSet2(p,n0,n1)

#define preBitSet3(p,n0,n1,n2)

#define preBitSet4(p,n0,n1,n2,n3)

#define preBitSet5(p,n0,n1,n2,n3,n4)

#define preBitSet6(p,n0,n1,n2,n3,n4,n5)

#define preBitSet7(p,n0,n1,n2,n3,n4,n5,n6)

#define preBitSet8(p,n0,n1,n2,n3,n4,n5,n6,n7)

Use this function to set a one or more bits on a variable, or to modify one or more bits on a variable. For the AVR, if you use something like PORTA = preBitSet1(PORTA,3), it is compiled to an atomic instruction. The method is used internally since it can also deal with the cfgUndefined constant (which is ignored).
Note: n0 .. n7 should be constants and not variables.

preSlotDefined: Use to see if a slot is in use.

#define preSlotDefined(SlotName)

Use this function to see if a slot is in use. Can be used in preproccessor statements

preSlotNumberOf: Returns the slot number of a slot with the name "SlotName".

#define preSlotNumberOf(SlotName)

Using this function it is possible to use static names for the slots instead of numbers. It returns the slot number of a slot with the compile time name "SlotName". This function is implicitly called in all 'OnName' variants of the API calls. Make sure you correctly spell the name, since that is not checked here (and will give rise to a compile time warning only). Preferably uses names instead of numbers in your code since the numbering depends an the inclusions and may differ at different compiles. Substitution of the numbers is done at compile time and does not require code. Cannot be used in preprocessor statements.

preTaskDefined: Use to see if a task is defined and included in the source

#define preTaskDefined(TaskName)

Use this function to see if a task is defined and included in the source Can be used in preproccessor statements

preTaskNumberOf: Returns the task number of a task with the name "TaskName".

#define preTaskNumberOf(TaskName)

Using this function it is possible to use static names for the tasks instead of numbers. It returns the task number of a task with the compile time name "TaskName". This does not equal the task name that is embedded in the code, that may be different or even absent). This function is implicitly called in all 'OnName' variants of the API calls. Make sure you correctly spell the name, since that is not checked here (and will give rise to a compile time warning only). Preferably uses names instead of numbers in your code since the numbering depends an the inclusions and may differ at different compiles. Substitution of the numbers is done at compile time and does not require code. Cannot be used in preprocessor statements.

preWaitDefined: Use this function to see if a wait is defined on a slot name.

#define preWaitDefined(SlotName)

Use this function to see if a wait is defined on a slot name. Can be used in preproccessor statements

Contact: info@femtoos.org