API references

1 GeMRTOS API Functions categories #

1.1 Critical Section category ˆˆEˆˆL #

The Critical Section category in GeMRTOS provides essential macros for protecting shared data structures during concurrent task execution. These macros are specifically designed to manage access to GeMRTOS data structures, ensuring that operations on shared resources are executed atomically to prevent race conditions and maintain data integrity. Proper implementation of these critical section macros is crucial for protecting GeMRTOS-specific data structures from unexpected behaviors that may arise from simultaneous access by multiple tasks or processors. This category empowers developers to create secure and efficient real-time applications by ensuring that critical operations on data structures are performed without interruption or conflict.

gm_GeMRTOSCriticalSectionEnter
gm_GeMRTOSCriticalSectionExit

1.2 Frozen Mode category ˆˆEˆˆL #

The Frozen Mode category in GeMRTOS includes functions and macros that manage system behavior during critical operational states. This mode allows the system to temporarily suspend certain tasks and processes to preserve resources and maintain stability under specific conditions. By entering Frozen Mode, developers can prevent unwanted interruptions and manage timing more effectively, particularly in scenarios that require precise timing or resource allocation. Functions related to Frozen Mode enable the configuration of thresholds and control mechanisms, allowing for efficient activation and deactivation of this mode as needed. This capability is essential for optimizing performance and ensuring system reliability in real-time applications.

gm_FrozenModeDisable
gm_FrozenModeEnable
gm_GatedClockDisable
gm_GatedClockEnable
gm_StatusFrozenModeEnableGet
gm_SystemReset
gm_TimeCountersReset
gm_TimeCoutersHold
gm_TimeCoutersUnhold
gm_TimeCoutersUnreset
gu_FrozenModeThresholdGet
gu_FrozenModeThresholdSet
gu_FrozenModeTimeGet

1.3 IRQ Management category ˆˆEˆˆL #

The IRQ Management category in GeMRTOS encompasses functions and macros designed to handle interrupt requests (IRQs) efficiently within the real-time operating system. This category provides essential tools for enabling, disabling, and managing interrupts, allowing tasks to respond promptly to external events and system signals. Effective IRQ management is crucial for optimizing system performance, as it facilitates the prioritization of tasks and ensures that critical events are addressed in a timely manner.

gm_IrqDisable
gm_IrqEnable
gm_NextOccTimeProcessor
gm_TriggerPrcIRQ

1.4 Message Queue category ˆˆEˆˆL #

The Message Queue category in GeMRTOS provides essential functions and macros for implementing inter-task communication through message passing mechanisms. This category enables tasks to exchange data and synchronize their operations efficiently, facilitating seamless collaboration within a real-time system.
By utilizing the Message Queue category, developers can create, send, and receive messages between tasks, allowing for asynchronous communication that enhances system responsiveness. The functions within this category support various operations, including message queue creation, message enqueuing and dequeuing to ensure robust data exchange.
With the capability to configure message priorities and handling, the Message Queue category not only streamlines communication but also aids in managing task dependencies and resource sharing. This is particularly important in complex applications where timely and reliable message transfer is critical. By ensuring effective inter-task communication, the Message Queue category plays a vital role in optimizing performance and contributing to the overall reliability of the GeMRTOS environment.

gu_MessageQueueCreate
gu_MessageQueuePrintf
gu_MessageQueueReceive
gu_MessageQueueSend
gu_MessageQueueSubscribe

1.5 Processor category ˆˆEˆˆL #

The Processor category in GeMRTOS includes functions and macros that provide critical tools for managing processor-level operations and configurations within the real-time operating system. This category facilitates the control of individual processors, allowing developers to optimize task scheduling, interrupt handling, and overall system performance. Functions in this category enable manipulation of processor states, including halting, resuming, and managing processor interrupts, as well as retrieving processor-specific information. The Processor category is essential for developing robust real-time applications that require precise control over processing resources, promoting responsiveness, and achieving effective synchronization between tasks and hardware components.

gm_PRC_INT_DSB
gm_PRC_INT_ENB
gm_ProcessorHalt
gm_ProcessorId
gm_ProcessorInterrupt
gm_ProcessorWaitForIrq

1.6 Scheduling List category ˆˆEˆˆL #

The Scheduling List category in GeMRTOS encompasses functions and macros designed to facilitate the management and manipulation of hybrid scheduling lists within the real-time operating system. These tools provide essential data structure capabilities that allow developers to create, modify, and traverse collections of tasks efficiently, enabling dynamic and flexible scheduling approaches.
By using the Scheduling List category functions, developers can implement effective algorithms for task prioritization, resource allocation, and event handling, all while maintaining high performance and minimal overhead. The functions within this category support various operations such as adding and removing tasks, adjusting priorities, and specifying scheduling criteria. Notably, the configuration of scheduling list exclusions can help prevent real-time anomalies, ensuring that critical tasks receive the attention they need while balancing processor loads effectively.
Integration of the Scheduling List category into real-time applications enhances task organization and scheduling efficiency, enabling the system to respond rapidly to changes in workload and processor availability. This capability is critical for applications where timing, responsiveness, and resource management are paramount.

gu_SchedulingListAssociateProcessor
gu_SchedulingListAssociateTask
gu_SchedulingListCreate
gu_SchedulingListExclusionSet

1.7 Semaphore and Mutex category ˆˆEˆˆL #

The Semaphore and Mutex category in GeMRTOS encompasses functions and macros designed to facilitate synchronization and resource management among concurrent tasks within the real-time operating system. Semaphores and mutexes are essential for controlling access to shared resources, preventing race conditions, and ensuring data integrity by regulating how tasks interact with one another.
By utilizing the Semaphore and Mutex category, developers can create and manage both binary and counting semaphores, and mutexes, allowing for fine-grained control over task execution and resource allocation. The functions within this category enable operations such as semaphore and mutex creation, waiting, and signaling, effectively coordinating task activities and synchronizing their behavior.
The use of semaphores and mutexes is crucial in environments where multiple tasks need to access shared resources without conflict, as it helps maintain system stability and performance. Additionally, by leveraging semaphores and mutexes, developers can enhance the efficiency of their applications, ensuring that critical tasks are executed in a timely manner while preventing task starvation and optimizing resource utilization.

gu_SemaphoreCreateBinary
gu_SemaphoreCreateMutex
gu_SemaphoreCreateRecursiveMutex
gu_SemaphoreGetCount
gu_SemaphoreGive
gu_SemaphoreTake

1.8 Signal category ˆˆEˆˆL #

The Signal category in GeMRTOS provides essential functions and macros for implementing event-driven synchronization mechanisms between tasks within the real-time operating system. Signals serve as lightweight notification tools that allow tasks to communicate important state changes, alerts, or operational events efficiently.
By utilizing the Signal category, developers can create and manage signals that facilitate asynchronous task coordination, enabling tasks to respond promptly to specific events without polling or constant checking. Functions within this category support operations such as signal creation, allowing tasks to seamlessly be notified when critical actions need to take place.

gu_SignalCreate
gu_SignalDestroy

1.9 System category ˆˆEˆˆL #

The System category in GeMRTOS encompasses critical functions and macros that provide core capabilities for managing and configuring the operating environment. This category is vital for overseeing system-level operations, resource management, and overall application behavior within the real-time operating system.
By utilizing the System category, developers can access functions that facilitate system initialization, configuration of kernel parameters, and management of system states.

gm_ERETAddressSet
gm_MutexNestedValue
gm_ReadInputs
gm_StatusFrozenModeActiveGet
gm_WriteOutputs
gu_fprintf
gu_printf

1.10 Task category ˆˆEˆˆL #

The Task category in GeMRTOS includes essential functions and macros for creating, managing, and scheduling tasks within the real-time operating system. This category is fundamental for implementing multitasking, allowing applications to perform multiple operations concurrently and efficiently utilize system resources.
By leveraging the Task category, developers can create tasks with specified priority levels, resource requirements, and execution parameters, enabling fine control over how tasks are executed and scheduled. Functions within this category support a wide range of operations, including task creation, and suspension, as well as priority management.
The flexibility offered by the Task category supports responsive applications that can adapt to dynamic conditions in real-time environments. The Task category is crucial for building robust, efficient, and responsive applications in the GeMRTOS ecosystem, facilitating the seamless management of concurrent operations in complex real-time systems.

gu_TaskCreate
gu_TaskDelay
gu_TaskDelayTime
gu_TaskGetCurrentTCB
gu_TaskKill
gu_TaskPeriodSet
gu_TaskReadyPrioritySet
gu_TaskResume
gu_TaskRunPrioritySet
gu_TaskStartWithOffset
gu_TaskSuspend
gu_TaskTypeSet

1.11 Time Management category ˆˆEˆˆL #

In GeMRTOS, the core time management tasks revolve around manipulating system times and time intervals to support precise task synchronization and scheduling. These functions enable setting, reading, and adjusting system clocks, as well as defining time intervals for specific operations. Through effective time manipulation, developers can coordinate task execution and ensure activities occur at exact moments, maintaining the system’s deterministic behavior.

gm_StatusCountingTimeGet
gm_StatusResetCountingTimeGet
gm_SystemTimePrescaleGet
gm_SystemTimePrescaleSet
gm_TimeIntervalGet
gu_SystemTotalTimeGet

1.12 Trigger category ˆˆEˆˆL #

The Trigger category in GeMRTOS encompasses functions and macros that facilitate event-driven mechanisms within the real-time operating system. These functions enable tasks to respond to specific events, interrupts, or conditions, enhancing the system's interactivity and responsiveness. Triggers play a crucial role in synchronization, allowing tasks to be activated based on the occurrence of defined events, thereby optimizing resource utilization and improving overall system efficiency.

gu_TriggerCreate
gu_TriggerDisable
gu_TriggerDisableHook
gu_TriggerEnable
gu_TriggerEnableHook
gu_TriggerRegisterTask
gu_TriggerRelease
gu_TriggerSetTimeoutType
gu_TriggerWait

2 GeMRTOS Functions #

__________________________________________________________________

2.1 gm_GeMRTOSCriticalSectionEnter #

Prototype

void gm_GeMRTOSCriticalSectionEnter;  /* macro: GRTOS_USER_CRITICAL_SECTION_GET */

Description: The gm_GeMRTOSCriticalSectionEnter macro defines the entry point into a critical section for the management of kernel data. It is designed to ensure that modifications to shared kernel resources occur safely, although it may be interrupted while waiting for the GeMRTOS controller mutex. This macro should be utilized whenever there is a need to modify kernel data to prevent data corruption and maintain system stability.

Parameters
The gm_GeMRTOSCriticalSectionEnter macro does not accept any parameters.

Returns
The gm_GeMRTOSCriticalSectionEnter macro does not return any value but blocks the code execution until the GeMRTOS controller mutex is granted.

Thread-safety
Blocking — waits until the hardware mutex is granted. Not reentrant unless nested mutex is enabled.

Error conditions
None returned; execution blocks indefinitely if mutex is never released.

Preconditions
Must not already hold the GeMRTOS mutex (unless nested mutex is active via gm_MutexNestedValue).

Postconditions
The calling processor holds the GeMRTOS controller hardware mutex.

See also
gm_GeMRTOSCriticalSectionExit
gm_IrqDisable
gm_IrqEnable
gm_ProcessorInterrupt
gm_ProcessorWaitForIrq
__________________________________________________________________

2.2 gm_GeMRTOSCriticalSectionExit #

Prototype

void gm_GeMRTOSCriticalSectionExit;  /* macro: GRTOS_USER_CRITICAL_SECTION_RELEASE */

Description: The gm_GeMRTOSCriticalSectionExit macro exits the critical section from the current processor, allowing other processors to enter. It is essential to use this macro in all user functions that execute kernel functions or modify kernel data, ensuring that the critical section is properly released and preventing potential deadlocks or resource contention.

Parameters
The gm_GeMRTOSCriticalSectionExit macro does not accept any parameters.

Returns
The gm_GeMRTOSCriticalSectionExit macro does not return any value.

Thread-safety
Must be called by the processor that called gm_GeMRTOSCriticalSectionEnter.

Error conditions
Undefined behavior if called without a prior matching Enter.

Preconditions
The calling processor must hold the GeMRTOS mutex.

Postconditions
The GeMRTOS mutex is released; other processors may acquire it.

See also
gm_GeMRTOSCriticalSectionEnter
gm_IrqDisable
gm_IrqEnable
gm_ProcessorInterrupt
gm_ProcessorWaitForIrq
__________________________________________________________________

2.3 gm_FrozenModeDisable #

Prototype

void gm_FrozenModeDisable;  /* macro: GRTOS_CMD_FRZ_DSB_SET */

Description: The gm_FrozenModeDisable macro disables the frozen mode event. By default, the frozen mode starts in a disabled state.

Parameters
The gm_FrozenModeDisable macro does not accept any parameters.

Returns
The gm_FrozenModeDisable macro does not return any value.

Thread-safety
Must be called within a critical section (GeMRTOS mutex held).

Error conditions
None.

Preconditions
GeMRTOS mutex must be held.

Postconditions
Frozen mode is disabled; system stays in non-frozen mode regardless of time threshold.

2.4 gm_FrozenModeEnable #

Prototype

void gm_FrozenModeEnable;  /* macro: GRTOS_CMD_FRZ_ENB_SET */

Description: The gm_FrozenModeEnable macro enables the frozen mode event. By default, the frozen mode starts in a disabled state. Before invoking this macro, ensure that the frozen threshold is properly configured using the gu_FrozenModeThresholdSet function. The gm_FrozenModeDisable macro disables the frozen mode.

Parameters
The gm_FrozenModeEnable macro does not accept any parameters.

Returns
The gm_FrozenModeEnable macro does not return any value.

Thread-safety
Must be called within a critical section.

Error conditions
None.

Preconditions
GeMRTOS mutex must be held. Frozen threshold (gu_FrozenModeThresholdSet) should be configured first.

Postconditions
Frozen mode is enabled; controller will switch to frozen mode when system time exceeds the next event by the threshold.

2.5 gm_GatedClockDisable #

Prototype

void gm_GatedClockDisable;  /* macro: GRTOS_CMD_GATED_CLOCK_DIS */

Description: The gm_GatedClockDisable macro enables the output clock of the the GeMRTOS controller. It may be used in special applications.

Parameters
The gm_GatedClockDisable macro does not accept any parameters.

Returns
The gm_GatedClockDisable macro does not return any value.

Thread-safety
Must be called within a critical section.

Error conditions
None.

Preconditions
GeMRTOS mutex must be held.

Postconditions
The gated clock output port of the GeMRTOS controller is driven low.

2.6 gm_GatedClockEnable #

Prototype

void gm_GatedClockEnable;  /* macro: GRTOS_CMD_GATED_CLOCK_ENB */

Description: The gm_GatedClockEnable macro enables the output clock of the the GeMRTOS controller. It may be used in special applications.

Parameters
The gm_GatedClockEnable macro does not accept any parameters.

Returns
The gm_GatedClockEnable macro does not return any value.

Thread-safety
Must be called within a critical section.

Error conditions
None.

Preconditions
GeMRTOS mutex must be held.

Postconditions
The gated clock output port mirrors the GeMRTOS controller input clock.

2.7 gm_StatusFrozenModeEnableGet #

Prototype

G_INT32 gm_StatusFrozenModeEnableGet;  /* macro: GRTOS_CMD_GET_FRZ_ENB */

Description: gm_StatusFrozenModeEnableGet returns the status of the enable of the frozen mode (G_TRUE if enabled, G_FALSE if disabled). The execution of gm_FrozenModeEnable enables the frozen mode. The execution of gm_FrozenModeDisable disables the frozen mode.

Parameters
gm_StatusFrozenModeEnableGet has no parameter.

Returns
The gm_StatusFrozenModeEnableGet macro returns the time prescale.

Thread-safety
Read-only; safe to call within a critical section.

Error conditions
None.

Preconditions
GeMRTOS mutex should be held for a consistent read.

Postconditions
None.

2.8 gm_SystemReset #

Prototype

void gm_SystemReset;  /* writes CTRL_RESET_BIT to CTRL register */

Description: The gm_SystemReset macro resets the GeMRTOS controller. Is is executed only by the GeMRTOS kernel.

Parameters
The gm_SystemReset macro does not accept any parameters.

Returns
The gm_SystemReset macro does not return any value.

Thread-safety
Resets the entire GeMRTOS controller; all state is lost.

Error conditions
Does not return; system restarts.

Preconditions
GeMRTOS mutex must be held.

Postconditions
All GeMRTOS controller registers are reset to their initial state.

2.9 gm_TimeCountersReset #

Prototype

void gm_TimeCountersReset;  /* macro: GRTOS_CMD_TM_CNT_CLR */

Description: The gm_TimeCountersReset macro resets and holds reset the time counters. Is is executed only by the GeMRTOS kernel.

Parameters
The gm_TimeCountersReset macro does not accept any parameters.

Returns
The gm_TimeCountersReset macro does not return any value.

Thread-safety
Must be called within a critical section.

Error conditions
None.

Preconditions
Called at system startup before gm_TimeCoutersUnreset.

Postconditions
System time counters are reset and held at zero.

2.10 gm_TimeCoutersHold #

Prototype

void gm_TimeCoutersHold;  /* writes CTRL_TM_CNTS_HLD_BIT */

Description: The gm_TimeCoutersHold macro holds the time counters. Is is executed only by the GeMRTOS kernel.

Parameters
The gm_TimeCoutersHold macro does not accept any parameters.

Returns
The gm_TimeCoutersHold macro does not return any value.

Thread-safety
Must be called within a critical section.

Error conditions
None.

Preconditions
GeMRTOS mutex must be held.

Postconditions
All time counters are frozen at their current values.

2.11 gm_TimeCoutersUnhold #

Prototype

void gm_TimeCoutersUnhold;  /* clears CTRL_TM_CNTS_HLD_BIT */

Description: The gm_TimeCoutersUnhold macro unholds the time counters running from its current state. Is is executed only by the GeMRTOS kernel.

Parameters
The gm_TimeCoutersUnhold macro does not accept any parameters.

Returns
The gm_TimeCoutersUnhold macro does not return any value.

Thread-safety
Must be called within a critical section.

Error conditions
None.

Preconditions
GeMRTOS mutex must be held. gm_TimeCoutersHold must have been called first.

Postconditions
Time counters resume incrementing from the held values.

2.12 gm_TimeCoutersUnreset #

Prototype

void gm_TimeCoutersUnreset;  /* clears CTRL_TM_CNTS_CLR_BIT */

Description: The gm_TimeCoutersUnreset macro unresets theSystemTime Register for running. Is is executed only by the GeMRTOS kernel.

Parameters
The gm_TimeCoutersUnreset macro does not accept any parameters.

Returns
The gm_TimeCoutersUnreset macro does not return any value.

Thread-safety
Must be called within a critical section.

Error conditions
None.

Preconditions
gm_TimeCountersReset must have been called first. GeMRTOS mutex must be held.

Postconditions
Time counters are released and begin incrementing.

2.13 gu_FrozenModeThresholdGet #

Prototype

G_UINT64 gu_FrozenModeThresholdGet(void);  /* reads FRZ_THR register pair */

Description: The gu_FrozenModeThresholdGet function retrieves the value of the Frozen Time Threshold register from the GeMRTOS controller (R_FRZ_TM_THR). By default, the frozen mode is disabled, and the frozen threshold is set to zero. This function is useful for determining the current threshold value, which is critical for managing the activation of frozen mode.

Parameters
The gu_FrozenModeThresholdGet function does not accept any parameters

Returns
The gu_FrozenModeThresholdGet function returns the current value of the Frozen Time Threshold register in the GeMRTOS controller.

Thread-safety
Safe to call from task context; acquires mutex internally.

Error conditions
None.

Preconditions
None.

Postconditions
None.

2.14 gu_FrozenModeThresholdSet #

Prototype

G_UINT32 gu_FrozenModeThresholdSet(G_UINT64 time_set);  /* GRTOS_CMD_FRZ_TM_THR_SET */

Description: The gu_FrozenModeThresholdSet function sets the value of the Frozen Time Threshold register in the GeMRTOS controller. By default, the frozen mode is disabled, and the frozen threshold is initialized to zero. This function is essential for configuring the threshold that determines when the frozen mode becomes active when it is enabled.

Parameters
The gu_FrozenModeThresholdSet function accepts the following parameter:

timeset: The frozen threshold value specified in system ticks units. This value establishes the interval of delay in processing timed events after which the frozen mode will be triggered when frozen mode is enabled.

Returns
The gu_FrozenModeThresholdSet function does not return any value.

Thread-safety
Safe to call from task context; acquires mutex internally.

Error conditions
None.

Preconditions
None.

Postconditions
The frozen threshold is updated; frozen mode will activate when system time exceeds the next event time by this threshold.

2.15 gu_FrozenModeTimeGet #

Prototype

G_UINT64 gu_FrozenModeTimeGet(void);  /* reads FRZ_TM register pair */

Description: gu_FrozenModeTimeGet returns the accumulated time the system was in Frozen Mode. This time is hold in the R_FRZ_CNT register of the GeMRTOS controller.

Parameters
The gu_FrozenModeTimeGet function has no parameter.

Returns
The gu_FrozenModeTimeGet function returns the accumulated time the system was in Frozen Mode, hold in the the R_FRZ_CNT register of the GeMRTOS controller.

Thread-safety
Safe from task context.

Error conditions
None.

Preconditions
None.

Postconditions
None.

2.16 gm_IrqDisable #

Prototype

void gm_IrqDisable(G_INT32 irq);  /* macro: GRTOS_CMD_IRQ_ENB_CLR(irq) */

Description: The gm_IrqDisable macro disables the specified device interrupt request event (IRQ) in the GeMRTOS controller. The gm_IrqEnable(irq)macro enables the irq external interrupt in the GeMRTOS controller. This macro is essential for managing interrupt handling and preventing specified DIRQs from triggering.

Parameters
The gm_IrqDisable macro accepts the following parameter:

irq:The number of the IRQ to be disabled.

Returns
The gm_IrqDisable macro does not return any value.

Thread-safety
Must be called within a critical section.

Error conditions
Undefined behavior if irq is out of range [1, ALT_NIRQ].

Preconditions
GeMRTOS mutex must be held. irq must be a valid IRQ index.

Postconditions
The specified device interrupt request is disabled in the GeMRTOS controller.

See also
gm_IrqEnable
gm_NextOccTimeProcessor
gm_ProcessorInterrupt
gm_ProcessorWaitForIrq
gm_TriggerPrcIRQ
__________________________________________________________________

2.17 gm_IrqEnable #

Prototype

void gm_IrqEnable(G_INT32 irq);  /* macro: GRTOS_CMD_IRQ_ENB_SET(irq) */

Description: The gm_IrqEnable macro enables the specified device interrupt request event (DIRQ) in the GeMRTOS controller. This macro is crucial for allowing specified DIRQ to trigger. The gm_IrqDisable(irq)macro disables the irq external interrupt in the GeMRTOS controller.

Parameters
The gm_IrqEnable macro accepts the following parameter:

irq:The number of the DIRQ to be enabled.

Returns
The gm_IrqEnable macro does not return any value.

Thread-safety
Must be called within a critical section.

Error conditions
Undefined behavior if irq is out of range.

Preconditions
GeMRTOS mutex must be held. A trigger must be associated with this IRQ via gu_TriggerCreate.

Postconditions
The specified device interrupt request will trigger a processor interrupt when the device asserts it.

See also
gm_IrqDisable
gm_NextOccTimeProcessor
gm_ProcessorInterrupt
gm_ProcessorWaitForIrq
gm_TriggerPrcIRQ
__________________________________________________________________

2.18 gm_NextOccTimeProcessor #

Prototype

void gm_NextOccTimeProcessor(G_INT32 processor);  /* macro: GRTOS_CMD_NXT_TM_PRC_SET(processor) */

Description: The gm_NextOccTimeProcessor macro ets the Next Occurrence TimeProcessorin the GRTOS controller, or 0 if the next occurence time task is not executing.

Parameters
The gm_NextOccTimeProcessor macro accepts the following parameter:

processor:CPU_ID of processor executing the next occurrence time task..

Returns
The gm_NextOccTimeProcessor macro does not return any value.

Thread-safety
Must be called within a critical section.

Error conditions
Undefined behavior if processor is not a valid CPUID.

Preconditions
GeMRTOS mutex must be held.

Postconditions
The GeMRTOS controller knows which processor executes the next timed event; it will interrupt that processor when the event occurs.

See also
gm_IrqDisable
gm_IrqEnable
gm_TriggerPrcIRQ
__________________________________________________________________

2.19 gm_TriggerPrcIRQ #

Prototype

void gm_TriggerPrcIRQ(G_INT32 proc);  /* macro: GRTOS_CMD_PRC_INT(proc) */

Description: The gm_TriggerPrcIRQ macro interrupts the processor proc. If proc interrupt is enabled in the GRTOS controller, then the processor is interrupted.

Parameters
The gm_TriggerPrcIRQ macro accepts the following parameter:

proc:CPU_ID of processor to interrupt.

Returns
The gm_TriggerPrcIRQ macro does not return any value.

Thread-safety
Must be called within a critical section.

Error conditions
Undefined behavior if proc is not a valid CPUID.

Preconditions
GeMRTOS mutex must be held. Target processor must have interrupts enabled.

Postconditions
The target processor is interrupted and enters its interrupt handler.

See also
gm_IrqDisable
gm_IrqEnable
gm_NextOccTimeProcessor
gm_ProcessorInterrupt
gm_ProcessorWaitForIrq
__________________________________________________________________

2.20 gu_MessageQueueCreate #

Prototype

GS_RCB *gu_MessageQueueCreate(void);  /* calls gu_queue_create() */

Description: The gu_MessageQueueCreate function creates a new message queue resource. This resource is implemented using a GS_RCB structure, extended with fields from aT_QUEUE_RESOURCEstructure. The created queue includes event lists for producers (waiting to send) and MQreceivers (waiting to receive) messages. Producer tasks add themselves to the producer event list when they are waiting to send a message. This function can be called from either the main application code or from within a task. If called within a task, it must be called before any message send or receive operations; otherwise, an error will occur.

Parameters
The gu_MessageQueueCreate function takes no parameters.

Returns
The gu_MessageQueueCreate function returns a pointer ( GS_RCB *) to the newly created message queue resource. This pointer is essential for all subsequent operations in the queue. A NULL pointer is returned if there is insufficient memory to create the queue or if no more queue resources are available.

Thread-safety
Safe from task context or initialization.

Error conditions
Returns NULL if no free RCB is available.

Preconditions
GeMRTOS must be initialized.

Postconditions
A new message queue RCB is allocated. Subscribers must be added with gu_MessageQueueSubscribe before sending.

See also
gu_MessageQueuePrintf
gu_MessageQueueReceive
gu_MessageQueueSend
gu_MessageQueueSubscribe
__________________________________________________________________

2.21 gu_MessageQueuePrintf #

Prototype

G_UINT32 gu_MessageQueuePrintf(GS_RCB *prcb, const char *format, ...);

Description: The gu_MessageQueuePrintf function sends a formatted message to a message queue. The calling task will block until the message is successfully delivered to all MQreceivers subscribed to the queue.

Parameters
The function accepts the following parameters:

prcb: A pointer to the GS_RCB structure representing the message queue. This pointer is the value returned by gu_MessageQueueCreate when the queue was created.
format: A null-terminated string containing the format string, similar to the standard printf function. This string can include format specifiers (e.g., d, s, x) that are replaced by subsequent arguments.

Returns
The function returns G_TRUE if the message was successfully sent to the queue, and G_FALSE otherwise.

Thread-safety
Safe from task context.

Error conditions
Returns negative value on send failure.

Preconditions
prcb must point to a valid message queue RCB created by gu_MessageQueueCreate.

Postconditions
A formatted string message is enqueued for delivery to all subscribers.

See also
gu_MessageQueueCreate
gu_MessageQueueReceive
gu_MessageQueueSend
gu_MessageQueueSubscribe
__________________________________________________________________

2.22 gu_MessageQueueReceive #

Prototype

int gu_MessageQueueReceive(GS_RCB *prcb);

Description: The gu_MessageQueueReceive function retrieves the next message from a message queue. The calling task must have previously subscribed to the queue using gu_MessageQueueSubscribe. The received message is copied into the buffer specified by buffer_msg. If the message is larger than buffer_length, it will be truncated to fit the buffer.

Parameters
The function takes three parameters:

prcb: A pointer to the GS_RCB structure of the message queue from which to receive the message.

Returns
The gu_MessageQueueReceive function returns an integer representing the number of bytes actually received. This value may be less than buffer_length if the received message was shorter than the buffer or if the message was truncated due to buffer size limitations.

Thread-safety
Task context only; blocks until a message arrives.

Error conditions
Returns 0 if timeout or no message; returns message length on success.

Preconditions
The calling task must have subscribed via gu_MessageQueueSubscribe. buffer_msg must point to a buffer of at least buffer_length bytes.

Postconditions
The message is copied into buffer_msg; the task resumes.

See also
gu_MessageQueueCreate
gu_MessageQueuePrintf
gu_MessageQueueSend
gu_MessageQueueSubscribe
__________________________________________________________________

2.23 gu_MessageQueueSend #

Prototype

int gu_MessageQueueSend(GS_RCB *prcb, const char *pmsg, int msg_length, G_UINT64 timeout);

Description: The gu_MessageQueueSend function transmits a message to a message queue. The sending task blocks until the message has been successfully delivered to all subscribed MQreceivers or until a timeout occurs.

Parameters
The function uses the following parameters:

prcb: A pointer to the GS_RCB structure representing the message queue resource. This pointer was returned by gu_MessageQueueCreate when the queue was created.
pmsg: A pointer to the message data to be sent
msg_length: An integer representing the length of the message to be sent, in bytes.
timeout: Agt_timevalue specifying the timeout period for sending the message.

Returns
The gu_MessageQueueSend function returns G_TRUE if the message was successfully sent within the timeout period, and G_FALSE otherwise. G_FALSE indicates either a timeout or another error condition.

Thread-safety
Safe from task context.

Error conditions
Returns negative on timeout or queue error. Returns 0 on success.

Preconditions
prcb must be a valid queue. pmsg must not be NULL. msg_length must be positive.

Postconditions
Message is delivered to all active subscribers; sender blocks until all consumers receive it or timeout expires.

See also
gu_MessageQueueCreate
gu_MessageQueuePrintf
gu_MessageQueueReceive
gu_MessageQueueSubscribe
__________________________________________________________________

2.24 gu_MessageQueueSubscribe #

Prototype

GS_ECB *gu_MessageQueueSubscribe(GS_TCB *ptcb, GS_RCB *presource, void *buffer_msg, G_UINT32 buffer_length);

Description: The gu_MessageQueueSubscribe function subscribes the task to a message queue resource. This subscription is crucial for message delivery; a consumer task must be subscribed to a queue before it can receive messages using gu_MessageQueueReceive. Furthermore, the execution of this function for each receiving task allows the message queue to track the number of MQreceivers subscribed. This count is essential for producers; a producer message is only considered fully delivered when it has been received by every subscribed consumer. The message queue must have been previously created using gu_MessageQueueCreate.

Parameters
The function uses the following parameters:

ptcb: A pointer to theTaskControl Block ( GS_TCB ) of the task being subscribed to the queue.
presource: A pointer to the GS_RCB structure representing the message queue resource to which the task is subscribing.
buffer_msg: A pointer to the memory buffer where the received message will be stored.
buffer_length: An integer specifying the maximum number of bytes to receive.

Returns
The gu_MessageQueueSubscribe function returns a pointer to theGS_ECBstructure associated with the message queue resource. A NULL return value likely indicates an error.

Thread-safety
Safe from task context or initialization.

Error conditions
Returns NULL if no free ECB is available.

Preconditions
ptcb and presource must be valid pointers. Typically called before the queue is used.

Postconditions
The task is registered as a consumer; it will receive all future messages sent to the queue.

See also
gu_MessageQueueCreate
gu_MessageQueuePrintf
gu_MessageQueueReceive
gu_MessageQueueSend
__________________________________________________________________

2.25 gm_PRC_INT_DSB #

Prototype

void gm_PRC_INT_DSB;  /* macro: GRTOS_CMD_PRC_INT_DSB */

Description: The gm_PRC_INT_DSB macro disables the processor interrupt from the GeMRTOS controller.

Parameters
The gm_PRC_INT_DSB macro does not require any parameters.

Returns
The gm_PRC_INT_DSB macro returns control to the calling function when the processor is interrupted and the ISR routine executed, allowing it to resume execution.

Thread-safety
Affects only the calling processor’s interrupt enable in the GeMRTOS controller.

Error conditions
None.

Preconditions
None.

Postconditions
The GeMRTOS controller will not generate processor interrupt requests for the calling processor.

See also
gm_PRC_INT_ENB
gm_ProcessorHalt
gm_ProcessorId
gm_ProcessorInterrupt
gm_ProcessorWaitForIrq
__________________________________________________________________

2.26 gm_PRC_INT_ENB #

Prototype

void gm_PRC_INT_ENB;  /* macro: GRTOS_CMD_PRC_INT_ENB */

Description: The gm_PRC_INT_ENB macro enables the processor interrupt from the GeMRTOS controller.

Parameters
The gm_PRC_INT_ENB macro does not require any parameters.

Returns
The gm_PRC_INT_ENB macro returns control to the calling function when the processor is interrupted and the ISR routine executed, allowing it to resume execution.

Thread-safety
Affects only the calling processor.

Error conditions
None.

Preconditions
None.

Postconditions
The GeMRTOS controller is enabled to interrupt the calling processor on events.

See also
gm_PRC_INT_DSB
gm_ProcessorHalt
gm_ProcessorId
gm_ProcessorInterrupt
gm_ProcessorWaitForIrq
__________________________________________________________________

2.27 gm_ProcessorHalt #

Prototype

void gm_ProcessorHalt;  /* macro: GRTOS_CMD_HALT_PROCESSOR */

Description: The gm_ProcessorHalt macro places the processor into halt mode, effectively stopping its execution until an interrupt is issued for this processor by the GeMRTOS controller. This mode is often used to conserve power or to wait for external events before resuming normal operation. When G_DEBUG_WAITING_LOOP is defined equal to 0, gm_ProcessorHalt is implemented by asserting the waitrequest signal when processor reads the wait bit of ADDR_REG_0 address in the processor memory of the GeMRTOS controller. When G_DEBUG_WAITING_LOOP is defined not equal to 0, gm_ProcessorHalt is implemented as a waiting loop reading the the wait bit of ADDR_REG_0 address in the processor memory of the GeMRTOS controller in order to be complilance with debugging tools that does not support processor halted with waitrequest signal.

Parameters
The gm_ProcessorHalt macro does not require any parameters.

Returns
The gm_ProcessorHalt macro returns control to the calling function when the processor is interrupted and the ISR routine executed, allowing it to resume execution.

Thread-safety
Halts the calling processor; execution resumes on next interrupt.

Error conditions
None.

Preconditions
None.

Postconditions
Processor is in halt/idle state until the next interrupt fires.

See also
gm_PRC_INT_DSB
gm_PRC_INT_ENB
gm_ProcessorId
gm_ProcessorInterrupt
gm_ProcessorWaitForIrq
__________________________________________________________________

2.28 gm_ProcessorId #

Prototype

G_INT32 gm_ProcessorId;  /* macro: GRTOS_CMD_PRC_ID */

Description: The gm_ProcessorId macro retrieves the ID of the current processor. This macro is useful for identifying the processor.

Parameters
The gm_ProcessorId macro does not accept any parameters.

Returns
The gm_ProcessorId macro returns the ID of the current processor.

Thread-safety
Safe to call from any context; reads a processor-specific register.

Error conditions
None.

Preconditions
None.

Postconditions
None.

See also
gm_PRC_INT_DSB
gm_PRC_INT_ENB
gm_ProcessorHalt
gm_ProcessorInterrupt
gm_ProcessorWaitForIrq
__________________________________________________________________

2.29 gm_ProcessorInterrupt #

Prototype

void gm_ProcessorInterrupt(G_INT32 proc);  /* macro: GRTOS_CMD_PRC_INT(proc) */

Description: gm_ProcessorInterrupt issues an interrupt for the processor with the specified ID and waits until it reaches the ISR and disables its interrupt in the GeMRTOS controller.

Parameters
The gm_ProcessorInterrupt macro accepts the following parameter:

proc:The ID of the processor to be interrupted. This specifies which processor will receive the interrupt signal.

Returns
The gm_ProcessorInterrupt macro returns when the target processor disables its interrupt in the GeMRTOS controller.

Thread-safety
Must be called within a critical section.

Error conditions
Undefined if proc is an invalid CPUID.

Preconditions
GeMRTOS mutex must be held. Target processor must be running and have interrupts enabled.

Postconditions
The target processor is interrupted; the caller waits until the target enters its IRQ handler.

See also
gm_PRC_INT_DSB
gm_PRC_INT_ENB
gm_ProcessorHalt
gm_ProcessorId
gm_ProcessorWaitForIrq
__________________________________________________________________

2.30 gm_ProcessorWaitForIrq #

Prototype

void gm_ProcessorWaitForIrq;  /* waits in low-power state for next GeMRTOS IRQ */

Description: The gm_ProcessorWaitForIrq macro halts the processor until an interrupt occurs on one of the specified masked IRQs. This function is useful for enabling the processor to wait for specific interrupt events.

Parameters
The gm_ProcessorWaitForIrq macro accepts the following parameter:

IRQ_mask:A mask of the DIRQs that the processor will wait for. This mask specifies which interrupts should wake the processor from its halted state. The interrupt should be disabled in order to be used to wake up the processor.

Returns
The gm_ProcessorWaitForIrq macro does not return any value.

Thread-safety
Affects only the calling processor.

Error conditions
None.

Preconditions
None.

Postconditions
Processor resumes execution upon receiving the next GeMRTOS controller interrupt.

See also
gm_PRC_INT_DSB
gm_PRC_INT_ENB
gm_ProcessorHalt
gm_ProcessorId
gm_ProcessorInterrupt
__________________________________________________________________

2.31 gu_SchedulingListAssociateProcessor #

Prototype

G_UINT32 gu_SchedulingListAssociateProcessor(GS_LCB *plcb, G_UINT32 cpu_id, G_UINT32 priority);

Description: The gu_SchedulingListAssociateProcessor function associates a system processor with a specified scheduling list. The priority is assigned to the association between the processor and the scheduling list. When tasks are ready to execute, the processor will select and execute the task from the highest priority scheduling list that it is associated with. The association with the lowest numerical value indicates the highest priority, ensuring that tasks in the most critical scheduling lists are prioritized for execution.

Parameters
The following parameters are required for the gu_SchedulingListAssociateProcessor function:

plcb: A pointer to theGS_LCBstructure representing the scheduling list to be associated with the processor.
cpu_id: The ID of the processor to be associated with the scheduling list.
priority: The priority level for the association. A lower value indicates a higher priority, and the processor will first search the scheduling lists associated with the highest priority tasks that are ready to execute.

Returns
The gu_SchedulingListAssociateProcessor function returns G_TRUE if the association is successful. It returns G_FALSE if the association fails.

Thread-safety
Safe from task context or initialization.

Error conditions
Returns G_FALSE (0) on failure (invalid arguments or no free PCBAssocLCB slot).

Preconditions
plcb must have been created by gu_SchedulingListCreate. cpu_id must be a valid processor ID.

Postconditions
The processor with the given cpu_id will service tasks in plcb at the specified priority.

See also
gu_SchedulingListAssociateTask
gu_SchedulingListCreate
gu_SchedulingListExclusionSet
__________________________________________________________________

2.32 gu_SchedulingListAssociateTask #

Prototype

G_UINT32 gu_SchedulingListAssociateTask(struct gs_tcb *ptcb, struct gs_lcb *plcb);

Description: The gu_SchedulingListAssociateTask function assigns a task to a specific scheduling list. Once assigned, the task will be scheduled according to the priority discipline defined for that scheduling list.

Parameters
The function accepts two parameters:

ptcb: A pointer to the GS_TCB structure representing the task to be assigned.
plcb: A pointer to theGS_LCBstructure representing the scheduling list to which the task should be added.

Returns
The gu_SchedulingListAssociateTask function returns G_TRUE if the task was successfully assigned to the scheduling list, and G_FALSE otherwise.

Thread-safety
Safe from task context or initialization.

Error conditions
Returns G_FALSE on failure.

Preconditions
Both ptcb and plcb must be valid. Task should be in Waiting state.

Postconditions
The task is assigned to the scheduling list; it will compete for processors associated with that list.

See also
gu_SchedulingListAssociateProcessor
gu_SchedulingListCreate
gu_SchedulingListExclusionSet
__________________________________________________________________

2.33 gu_SchedulingListCreate #

Prototype

GS_LCB *gu_SchedulingListCreate(enum lcbtype lcb_type);

Description: The gu_SchedulingListCreate function creates a new scheduling list. The type of scheduling discipline used by the list is determined by the lcbtype parameter.

Parameters
The function accepts one parameter:

lcbtype: An enumeration value specifying the type of scheduling list to create. This defines the scheduling discipline that will govern task scheduling within the new scheduling list.

Returns
The gu_SchedulingListCreate function returns a pointer (GS_LCB*) to the newly createdGS_LCBstructure. This pointer is essential for all subsequent operations involving this specific scheduling list. A '(GS_LCB*) 0' return value indicates failure to create the scheduling list.

Thread-safety
Safe from task context or initialization.

Error conditions
Returns NULL if no free LCB is available.

Preconditions
lcbtype must be GS_LCBTypeFP (fixed priority) or GS_LCBTypeEDF (earliest deadline first).

Postconditions
A new scheduling list is allocated and linked into the kernel LCB list.

See also
gu_SchedulingListAssociateProcessor
gu_SchedulingListAssociateTask
gu_SchedulingListExclusionSet
__________________________________________________________________

2.34 gu_SchedulingListExclusionSet #

Prototype

G_UINT32 gu_SchedulingListExclusionSet(GS_LCB *plcb, G_UINT32 exclusion);

Description: The gu_SchedulingListExclusionSet function sets the exclusion level for a scheduling list. The exclusion level limits the number of tasks from that list that can be simultaneously in the execution state. This mechanism can be used for load balancing or to ensure real-time properties by protecting against multiprocessor anomalies. Setting the exclusion to 1 can help safeguard real-time task scheduling from anomalies within the scheduling list.

Parameters
The function accepts two parameters:

plcb: A pointer to theGS_LCBstructure of the scheduling list whose exclusion level is to be modified.
exclusion: An integer value that specifies the new exclusion level. A value of 1 ensures that multiple tasks from the scheduling list do not run concurrently on different processors. Values between 2 and the number of processors assigned to the scheduling list determine the number of tasks that can execute simultaneously on different processors. Additionally, values exceeding the number of processors assigned to the scheduling list will have no effect.

Returns
The function returns a G_TRUE.

Thread-safety
Safe from task context or initialization.

Error conditions
Returns G_FALSE on failure.

Preconditions
plcb must be a valid scheduling list. exclusion must be ≥ 0 (0 means no limit).

Postconditions
At most exclusion processors may simultaneously execute tasks from this list (prevents real-time anomalies).

See also
gu_SchedulingListAssociateProcessor
gu_SchedulingListAssociateTask
gu_SchedulingListCreate
__________________________________________________________________

2.35 gu_SemaphoreCreateBinary #

Prototype

GS_RCB *gu_SemaphoreCreateBinary(int initial_count);  /* gu_sem_create(1) */

Description: Creates a binary semaphore, and returns a handle by which the semaphore can be referenced. The semaphore is created in the 'empty' state, meaning the semaphore must first be given using the gu_SemaphoreGive()

Parameters
The following parameter is required.

initial_count: The count value assigned to the semaphore when it is created.

Returns
If the semaphore is created successfully then a handle to the semaphore is returned, NULL otherwise

Thread-safety
Safe from task context or initialization.

Error conditions
Returns NULL if no free RCB is available.

Preconditions
None.

Postconditions
A binary semaphore (initial count 1) is allocated. Use gu_SemaphoreTake/gu_SemaphoreGive to operate it.

See also
gu_SemaphoreCreateMutex
gu_SemaphoreCreateRecursiveMutex
gu_SemaphoreGetCount
gu_SemaphoreGive
gu_SemaphoreTake
__________________________________________________________________

2.36 gu_SemaphoreCreateMutex #

Prototype

GS_RCB *gu_SemaphoreCreateMutex(void);  /* gu_sem_create(1), non-recursive */

Description: Creates a mutex, and returns a handle by which the created mutex can be referenced. Mutexes are taken using gu_SemaphoreTake(), and given using gu_SemaphoreGive().

Parameters
The function takes no parameters.

Returns
If the mutex type semaphore was created successfully then a handle to the created mutex is returned, NULL otherwise

Thread-safety
Safe from task context or initialization.

Error conditions
Returns NULL if no free RCB is available.

Preconditions
None.

Postconditions
A non-recursive mutex semaphore is allocated with initial count 1.

See also
gu_SemaphoreCreateBinary
gu_SemaphoreCreateRecursiveMutex
gu_SemaphoreGetCount
gu_SemaphoreGive
gu_SemaphoreTake
__________________________________________________________________

2.37 gu_SemaphoreCreateRecursiveMutex #

Prototype

GS_RCB *gu_SemaphoreCreateRecursiveMutex(void);

Description: Creates a recursive mutex, and returns a handle by which the mutex can be referenced. Recursive mutexes are 'taken' (obtained) using the gu_SemaphoreTakeRecursive() and given (released) using the gu_SemaphoreGiveRecursive() API functions respectively.

Parameters
The function takes no parameters.

Returns
If the mutex type semaphore was created successfully then a handle to the created mutex is returned, NULL otherwise

Thread-safety
Safe from task context or initialization.

Error conditions
Returns NULL if no free RCB is available.

Preconditions
None.

Postconditions
A recursive mutex is allocated; the same task may take it multiple times without deadlock.

See also
gu_SemaphoreCreateBinary
gu_SemaphoreCreateMutex
gu_SemaphoreGetCount
gu_SemaphoreGive
gu_SemaphoreTake
__________________________________________________________________

2.38 gu_SemaphoreGetCount #

Prototype

G_UINT32 gu_SemaphoreGetCount(const GS_RCB *presource);

Description: Returns the count of a semaphore. The semaphore must have previously been created with a call to gu_SemaphoreCreateBinary(), gu_SemaphoreCreateMutex()orgu_SemaphoreCreateCounting().

Parameters
The function takes the following parameters.

presource: A handle to the semaphore being taken - obtained when the semaphore was created.

Returns
If the semaphore is a counting semaphore then the semaphores current count value is returned. If the semaphore is a binary semaphore then 1 is returned if the semaphore is available, and 0 is returned if the semaphore is not available.

Thread-safety
Read-only; consistent result requires holding the mutex.

Error conditions
Undefined if presource is NULL.

Preconditions
presource must be a valid semaphore RCB.

Postconditions
None.

See also
gu_SemaphoreCreateBinary
gu_SemaphoreCreateMutex
gu_SemaphoreCreateRecursiveMutex
gu_SemaphoreGive
gu_SemaphoreTake
__________________________________________________________________

2.39 gu_SemaphoreGive #

Prototype

G_UINT32 gu_SemaphoreGive(GS_RCB *presource);  /* replaces gu_sem_post() */

Description: The gu_SemaphoreGive function releases a semaphore or mutex previously acquired. If tasks are waiting to acquire the resource, the highest-priority waiting task will be granted the resource. If no tasks are waiting, the semaphore's internal count is incremented.

Parameters
The function accepts one parameter:

presource: A pointer to the GS_RCB structure representing the semaphore resource. This pointer was returned by the gu_SemaphoreCreate function.

Returns
The gu_SemaphoreGive function returns G_TRUE if the semaphore was successfully released, and G_FALSE otherwise.

Thread-safety
Safe from task context.

Error conditions
Returns G_FALSE (0) if the semaphore count would exceed its maximum.

Preconditions
presource must be a valid semaphore. The calling task should currently hold the semaphore (for mutex use).

Postconditions
Semaphore count is incremented by 1; the highest-priority waiting task (if any) is released.

See also
gu_SemaphoreCreateBinary
gu_SemaphoreCreateMutex
gu_SemaphoreCreateRecursiveMutex
gu_SemaphoreGetCount
gu_SemaphoreTake
__________________________________________________________________

2.40 gu_SemaphoreTake #

Prototype

G_UINT32 gu_SemaphoreTake(GS_RCB *presource, G_UINT64 ticks_to_wait);  /* replaces gu_sem_wait(): second argument is now a tick timeout, not a boolean. G_LATEST_TIME waits indefinitely, 0 returns immediately */

Description: The gu_SemaphoreTake function attempts to acquire a semaphore or mutex. If the resource's current count is greater than 0, the resource is granted to the calling task, and the count is decremented. If the count is 0, the behavior depends on the blocking parameter: if blocking is G_TRUE, the task is suspended until the semaphore becomes available; if blocking is G_FALSE, the function returns immediately without blocking. When blocking, the task's ready priority is determined by its ready priority.

Parameters
The function uses the following parameters:

presource: A pointer to the GS_RCB structure representing the semaphore resource, as returned by gu_SemaphoreCreate.
ticks_to_wait: The time to wait in system time units. If zero, no time to wait an returns immediatly. Set G_LATEST_TIME if want to wait for until the resource become available.

Returns
The gu_SemaphoreTake function returns G_TRUE if the semaphore was granted to the task, and G_FALSE when the semaphore was unavailable and blocking was G_FALSE.

Thread-safety
Task context only; may block.

Error conditions
Returns G_FALSE (0) if blocking is 0 and the semaphore is not available. Returns G_TRUE on success.

Preconditions
Must be called from a task. presource must be a valid semaphore RCB.

Postconditions
On success, semaphore count is decremented by 1.

See also
gu_SemaphoreCreateBinary
gu_SemaphoreCreateMutex
gu_SemaphoreCreateRecursiveMutex
gu_SemaphoreGetCount
gu_SemaphoreGive
__________________________________________________________________

2.41 gu_SignalCreate #

Prototype

GS_SCB *gu_SignalCreate(enum scbtype type, G_UINT32 priority, void *pxcb, void *signal_code, void *signal_arg);

Description: The gu_SignalCreate function creates a signal of a specified type and associates it with a task or other system entity. The signal's priority determines its execution order when multiple signals are pending.

Parameters
The function takes the following parameters:

Type: An enumeration value specifying the type of signal to create (e.g., G_SCBType_TCB_ABORTED).
Priority: An integer representing the priority of the signal. Higher priority signals are executed before lower priority signals when multiple signals are pending.
pxcb: A pointer to a control structure. This structure could represent various system entities like tasks, resources, processors, or events, to which the signal is linked.
Signal_Code: A pointer to the function that implements the signal's behavior (the signal handler).
Signal_Arg: A pointer to an argument that will be passed to the Signal_Code function when the signal is executed.

Returns
The gu_SignalCreate function returns a pointer to the newly createdGS_SCBstructure. A NULL return indicates failure.

Thread-safety
Safe from task context or initialization.

Error conditions
Returns NULL if no free SCB is available.

Preconditions
Signal_Code must be a valid function pointer. pxcb must point to the control block (TCB, RCB, ECB, or KCB) to associate the signal with.

Postconditions
A signal is created and linked to the specified control block. It executes Signal_Code when the signal condition occurs.

See also
gu_SignalDestroy
__________________________________________________________________

2.42 gu_SignalDestroy #

Prototype

G_UINT32 gu_SignalDestroy(GS_SCB *pscb);

Description: The gu_SignalDestroy function removes a signal from a control block. This disassociates the signal from its associated task or system entity, preventing further execution of the signal's handler.

Parameters
The function accepts one parameter:

pscb: A pointer to theGS_SCBstructure representing the signal to be removed.

Returns
The gu_SignalDestroy function returns G_TRUE if the signal was successfully removed, and G_FALSE otherwise.

Thread-safety
Safe from task context.

Error conditions
Returns G_FALSE if pscb is invalid.

Preconditions
pscb must be a valid signal control block previously created.

Postconditions
The signal is unlinked from its associated control block and its SCB is returned to the free pool.

See also
gu_SignalCreate
__________________________________________________________________

2.43 gm_ERETAddressSet #

Prototype

void gm_ERETAddressSet(G_INT32 address);  /* writes ADDR_ERET_REG */

Description: The gm_ERETAddressSet macro sets the register where the return from interrupt code is stored in the internal registers of the GeMRTOS controller. When such an address is read, it means the processor is returning from interrupt and consequently the GeMRTOS controller Mutex is released, if it is not nested.

Parameters
The gm_ERETAddressSet has no parameter.

value:The offset in the GeMRTOS Global Region where the return from interrupt instruction is located.

Returns
The gm_ERETAddressSet macro does not return any value.

Thread-safety
Kernel use only; must be called within a critical section.

Error conditions
None.

Preconditions
GeMRTOS mutex must be held. For kernel initialization only.

Postconditions
When the processor reads this address, the GeMRTOS controller automatically releases the mutex (unless nested).

See also
gm_MutexNestedValue
gm_ReadInputs
gm_StatusFrozenModeActiveGet
gm_WriteOutputs
gu_fprintf
gu_printf
__________________________________________________________________

2.44 gm_MutexNestedValue #

Prototype

void gm_MutexNestedValue(G_INT32 value);  /* IOWR_GRTOS_MTX_NESTED(value) */

Description: The gm_MutexNestedValue macro sets the GeMRTOS controller Mutex nested parameter according to the value. If value is equal to 0, the Mutex is released next time a released is performed. Otherwise, if value is not 0, the the Mutex is not released.

Parameters
The gm_MutexNestedValue has one parameter:

data:If 0 the Mutex released is enabled, otherwise the Mutex released is disabled.

Returns
The gm_MutexNestedValue macro does not return any value.

Thread-safety
Must be called within a critical section.

Error conditions
None.

Preconditions
GeMRTOS mutex must be held.

Postconditions
Mutex nesting behavior updated; allows the same processor to re-enter the critical section without deadlock when value > 0.

See also
gm_ERETAddressSet
gm_ReadInputs
gm_StatusFrozenModeActiveGet
gm_WriteOutputs
gu_fprintf
gu_printf
__________________________________________________________________

2.45 gm_ReadInputs #

Prototype

G_INT32 gm_ReadInputs(void);  /* reads INOUTS register */

Description: The gm_ReadInputs macro transfer the data from the gemrtos_phy input conduit of GeMRTOS controller.

Parameters
The gm_ReadInputs macro does not require any parameter.

Returns
The gm_ReadInputs does returns the data from the gemrtos_phy input conduit of GeMRTOS controller.

Thread-safety
Read-only; safe within a critical section.

Error conditions
None.

Preconditions
GeMRTOS mutex should be held for a consistent read.

Postconditions
None.

See also
gm_ERETAddressSet
gm_MutexNestedValue
gm_StatusFrozenModeActiveGet
gm_WriteOutputs
gu_fprintf
gu_printf
__________________________________________________________________

2.46 gm_StatusFrozenModeActiveGet #

Prototype

G_INT32 gm_StatusFrozenModeActiveGet;  /* macro: GRTOS_CMD_GET_FRZ_ACT */

Description: gm_StatusFrozenModeActiveGet returns the status of the frozen mode event (G_TRUE if active, G_FALSE if inactive).

Parameters
gm_StatusFrozenModeActiveGet has no parameter.

Returns
The gm_StatusFrozenModeActiveGet macro returns the time prescale.

Thread-safety
Read-only.

Error conditions
None.

Preconditions
None.

Postconditions
None.

See also
gm_ERETAddressSet
gm_MutexNestedValue
gm_ReadInputs
gm_WriteOutputs
gu_fprintf
gu_printf
__________________________________________________________________

2.47 gm_WriteOutputs #

Prototype

void gm_WriteOutputs(G_INT32 data);  /* gu_write_outputs(data): writes ADDR_LEDS */

Description: The gm_WriteOutputs macro transfer the data input to the gemrtos_phy output conduit of GeMRTOS controller.

Parameters
The gm_WriteOutputs macro requires the following parameter:

data:Data to be transfered the the gemrtos_phy output conduit of GeMRTOS controller.

Returns
The gm_WriteOutputs macro does not return any value.

Thread-safety
Must be called within a critical section.

Error conditions
None.

Preconditions
GeMRTOS mutex must be held.

Postconditions
The INOUTS register output bits are updated with data.

See also
gm_ERETAddressSet
gm_MutexNestedValue
gm_ReadInputs
gm_StatusFrozenModeActiveGet
gu_fprintf
gu_printf
__________________________________________________________________

2.48 gu_fprintf #

Prototype

void gu_fprintf(const char *format, ...);

Description: The gu_fprintf function formats text and writes it to standard error output (stderr).

Parameters
The following parameter is required for the gu_fprintf function:

format: A string that may contain format specifiers like d, s, etc., which control the formatting of subsequent arguments.

Returns
The gu_fprintf function returns G_TRUE.

Thread-safety
Thread-safe; uses internal semaphore serialization.

Error conditions
None returned; output may be silently dropped if the JTAG UART buffer is full.

Preconditions
JTAG UART for STDERR must be included in the Platform Designer project.

Postconditions
Formatted string sent to STDERR JTAG UART.

See also
gm_ERETAddressSet
gm_MutexNestedValue
gm_ReadInputs
gm_StatusFrozenModeActiveGet
gm_WriteOutputs
gu_printf
__________________________________________________________________

2.49 gu_printf #

Prototype

void gu_printf(const char *format, ...);

Description: The gu_printf function formats text and writes it to standard output.

Parameters
The following parameter is required for the gu_printf function:

format: A string that may contain format specifiers like d, s, etc., which control the formatting of subsequent arguments.

Returns
The gu_printf function returns G_TRUE.

Thread-safety
Thread-safe; uses internal semaphore serialization.

Error conditions
None returned; output may be silently dropped if the JTAG UART buffer is full.

Preconditions
JTAG UART for STDIO must be included in the Platform Designer project.

Postconditions
Formatted string sent to STDIO JTAG UART.

See also
gm_ERETAddressSet
gm_MutexNestedValue
gm_ReadInputs
gm_StatusFrozenModeActiveGet
gm_WriteOutputs
gu_fprintf
__________________________________________________________________

2.50 gu_TaskCreate #

Prototype

void *gu_TaskCreate(void *task_code, void *p_arg, const char *format, ...);  /* gu_GetTask() + configuration calls */

Description: The gu_TaskCreate function creates a task with default settings and returns a pointer to its GS_TCB structure.Taskparameters can be modified before creation by adjusting default settings or after creation using task-related functions. While the function requires only TaskCode and p_arg, it allows for optional task description formatting using a printf-style format string and arguments.

Parameters
The function uses the following parameters:

TaskCode: A pointer to the function that implements the task's code (the task's entry point). It is the name of the function that implements the task code.
p_arg: A pointer to an argument that will be passed to the TaskCode function each time the task is invoked. This is a void * and can be cast to other types within the task code.
format: A format string, similar to printf, used to create a description string for the task (up to G_TCB_DESCRIPTION_LENGTH characters). This string can contain format specifiers that are replaced by subsequent arguments.

Returns
The gu_TaskCreate function returns a pointer to the GS_TCB structure of the newly created task. This pointer should be used in all subsequent calls related to that task. A NULL return indicates task creation failure.

Thread-safety
Safe from main() or task context.

Error conditions
Returns NULL if no free TCB or stack memory is available.

Preconditions
GeMRTOS must be initialized. TaskCode must be a valid function pointer. Stack size is set by the G_TASK_STACKSIZE compile-time constant (default 4096 bytes).

Postconditions
A new TCB is allocated; task is placed in Waiting state. Call gu_TaskTypeSet, gu_SchedulingListAssociateTask, and gu_TaskReadyPrioritySet to configure it before its first release.

See also
gu_TaskDelay
gu_TaskDelayTime
gu_TaskGetCurrentTCB
gu_TaskKill
gu_TaskPeriodSet
gu_TaskReadyPrioritySet
gu_TaskResume
gu_TaskRunPrioritySet
gu_TaskStartWithOffset
gu_TaskSuspend
gu_TaskTypeSet
__________________________________________________________________

2.51 gu_TaskDelay #

Prototype

G_UINT32 gu_TaskDelay(G_UINT32 hours, G_UINT32 minutes, G_UINT32 seconds, G_UINT32 ms);

Description: The gu_TaskDelay function suspends the execution of the currently running task for a specified time interval. This function is useful within the infinite loop of a task to create periodic behavior.

Parameters
The function uses the following parameters to define the sleep interval:

hours: The number of hours to sleep
minutes: The number of minutes to sleep.
seconds: The number of seconds to sleep.
ms: The number of milliseconds to sleep.

Returns
The gu_TaskDelay function always returns G_TRUE.

Thread-safety
Task context only; suspends the calling task.

Error conditions
Returns G_FALSE on error. All time arguments must be non-negative.

Preconditions
Must be called from a task. The time arguments must form a valid duration (e.g., seconds < 60).

Postconditions
Calling task is moved to Waiting state and released after the specified duration.

See also
gu_TaskCreate
gu_TaskDelayTime
gu_TaskGetCurrentTCB
gu_TaskKill
gu_TaskPeriodSet
gu_TaskReadyPrioritySet
gu_TaskResume
gu_TaskRunPrioritySet
gu_TaskStartWithOffset
gu_TaskSuspend
gu_TaskTypeSet
__________________________________________________________________

2.52 gu_TaskDelayTime #

Prototype

G_UINT32 gu_TaskDelayTime(gt_time ticks);

Description: The gu_TaskDelayTime function suspends the execution of the current task for a specified number of system clock ticks. This function provides a more direct way to specify sleep duration compared to gu_TaskDelay, using the system's time units directly.

Parameters
The function takes one parameter:

ticks: The number of system clock ticks for which the task should sleep.

Returns
The gu_TaskDelayTime function always returns G_TRUE.

Thread-safety
Task context only.

Error conditions
Returns G_FALSE on error. ticks must be greater than 0.

Preconditions
Must be called from a task.

Postconditions
Calling task is suspended for ticks system-time units.

See also
gu_TaskCreate
gu_TaskDelay
gu_TaskGetCurrentTCB
gu_TaskKill
gu_TaskPeriodSet
gu_TaskReadyPrioritySet
gu_TaskResume
gu_TaskRunPrioritySet
gu_TaskStartWithOffset
gu_TaskSuspend
gu_TaskTypeSet
__________________________________________________________________

2.53 gu_TaskGetCurrentTCB #

Prototype

GS_TCB *gu_TaskGetCurrentTCB(void);  /* gu_PCB_GetCurrentTCB() */

Description: The gu_TaskGetCurrentTCB function retrieves a pointer to theTaskControl Block ( GS_TCB ) of the currently executing task.

Parameters
This function takes no parameters.

Returns
The gu_TaskGetCurrentTCB function returns a pointer to the GS_TCB structure of the currently running task.

Thread-safety
Safe from task context.

Error conditions
Returns NULL if called from initialization context before any task is running.

Preconditions
None.

Postconditions
None.

See also
gu_TaskCreate
gu_TaskDelay
gu_TaskDelayTime
gu_TaskKill
gu_TaskPeriodSet
gu_TaskReadyPrioritySet
gu_TaskResume
gu_TaskRunPrioritySet
gu_TaskStartWithOffset
gu_TaskSuspend
gu_TaskTypeSet
__________________________________________________________________

2.54 gu_TaskKill #

Prototype

G_UINT32 gu_TaskKill(GS_TCB *ptcb);

Description: The gu_TaskKill function terminates a task and releases all associated resources, returning them to the free lists.

Parameters
The function takes one parameter:

ptcb: A pointer to the GS_TCB structure of the task to be terminated.

Returns
The gu_TaskKill function always returns G_TRUE.

Thread-safety
Safe from task context.

Error conditions
Returns G_FALSE if ptcb is invalid or already killed.

Preconditions
ptcb must be a valid TCB. Killing a task that holds a mutex may cause deadlock; ensure resources are released first.

Postconditions
The task is destroyed in any state; its TCB and stack are freed.

See also
gu_TaskCreate
gu_TaskDelay
gu_TaskDelayTime
gu_TaskGetCurrentTCB
gu_TaskPeriodSet
gu_TaskReadyPrioritySet
gu_TaskResume
gu_TaskRunPrioritySet
gu_TaskStartWithOffset
gu_TaskSuspend
gu_TaskTypeSet
__________________________________________________________________

2.55 gu_TaskPeriodSet #

Prototype

G_UINT32 gu_TaskPeriodSet(struct gs_tcb *ptcb, unsigned int hours, unsigned int minutes, unsigned int seconds, unsigned int ms);

Description: The gu_TaskPeriodSet function sets the period for the next invocation of a task. The current task invocation period remains unaffected; the new period will apply only to subsequent invocations.

Parameters
The function uses the following parameters:

ptcb: A pointer to the GS_TCB structure of the task whose period is to be set.
hours: The number of hours in the new period.
minutes: The number of minutes in the new period.
seconds: The number of seconds in the new period.
ms: The number of milliseconds in the new period.

Returns
The gu_TaskPeriodSet function always returns G_TRUE.

Thread-safety
Safe from task context or initialization.

Error conditions
Returns G_FALSE on invalid arguments.

Preconditions
ptcb must be valid. Task type should be G_TCBType_Periodic (or G_TCBType_Periodic_Skip).

Postconditions
The task period is updated; the next release time is recalculated.

See also
gu_TaskCreate
gu_TaskDelay
gu_TaskDelayTime
gu_TaskGetCurrentTCB
gu_TaskKill
gu_TaskReadyPrioritySet
gu_TaskResume
gu_TaskRunPrioritySet
gu_TaskStartWithOffset
gu_TaskSuspend
gu_TaskTypeSet
__________________________________________________________________

2.56 gu_TaskReadyPrioritySet #

Prototype

G_UINT32 gu_TaskReadyPrioritySet(struct gs_tcb *ptcb, G_UINT64 priority);

Description: The gu_TaskReadyPrioritySet function sets the ready priority of a task. This priority determines the task's position in the ready queue and influences its scheduling order. Note that larger values of priority represent lower priority; smaller values indicate higher priority.

Parameters
The function takes two parameters:

ptcb: A pointer to the GS_TCB structure of the task whose ready priority is to be set.
priority: A G_UINT64 value representing the new ready priority for the task. Larger values indicate lower priority; smaller values indicate higher priority.

Returns
The gu_TaskReadyPrioritySet function always returns G_TRUE.

Thread-safety
Safe from task context or initialization.

Error conditions
Returns G_FALSE on error.

Preconditions
ptcb must be valid. Lower priority value means higher scheduling priority.

Postconditions
The task’s ready-state priority is updated.

See also
gu_TaskCreate
gu_TaskDelay
gu_TaskDelayTime
gu_TaskGetCurrentTCB
gu_TaskKill
gu_TaskPeriodSet
gu_TaskResume
gu_TaskRunPrioritySet
gu_TaskStartWithOffset
gu_TaskSuspend
gu_TaskTypeSet
__________________________________________________________________

2.57 gu_TaskResume #

Prototype

G_UINT32 gu_TaskResume(GS_TCB *ptcb);

Description: The gu_TaskResume function resumes a task that is currently in a waiting state.

Parameters
The function takes one parameter:

ptcb: A pointer to the GS_TCB structure of the task to be resumed.

Returns
The gu_TaskResume function returns G_TRUE if the task was successfully resumed and G_FALSE otherwise.

Thread-safety
Safe from task context.

Error conditions
Returns G_FALSE if the task is not in a suspended (Waiting) state.

Preconditions
ptcb must be a valid TCB in Waiting state.

Postconditions
Task is moved to Ready state and may be dispatched to a processor.

See also
gu_TaskCreate
gu_TaskDelay
gu_TaskDelayTime
gu_TaskGetCurrentTCB
gu_TaskKill
gu_TaskPeriodSet
gu_TaskReadyPrioritySet
gu_TaskRunPrioritySet
gu_TaskStartWithOffset
gu_TaskSuspend
gu_TaskTypeSet
__________________________________________________________________

2.58 gu_TaskRunPrioritySet #

Prototype

G_UINT32 gu_TaskRunPrioritySet(struct gs_tcb *ptcb, G_UINT64 priority);

Description: The gu_TaskRunPrioritySet function sets the run-time priority of a task. This priority determines the task's execution order when it is running. Larger values of priority represent lower priority; smaller values represent higher priority.

Parameters
The function takes these parameters:

ptcb: A pointer to the GS_TCB structure of the task whose run-time priority is to be set.
priority: A G_UINT64 value specifying the new run-time priority. Larger values mean lower priority, and smaller values mean higher priority.

Returns
The gu_TaskRunPrioritySet function always returns G_TRUE.

Thread-safety
Safe from task context or initialization.

Error conditions
Returns G_FALSE on error.

Preconditions
ptcb must be valid.

Postconditions
The task’s running-state (execution) priority is updated.

See also
gu_TaskCreate
gu_TaskDelay
gu_TaskDelayTime
gu_TaskGetCurrentTCB
gu_TaskKill
gu_TaskPeriodSet
gu_TaskReadyPrioritySet
gu_TaskResume
gu_TaskStartWithOffset
gu_TaskSuspend
gu_TaskTypeSet
__________________________________________________________________

2.59 gu_TaskStartWithOffset #

Prototype

G_UINT32 gu_TaskStartWithOffset(GS_TCB *ptcb,unsigned int hours, unsigned int minutes, unsigned int seconds, unsigned int ms);

Description: The gu_TaskStartWithOffset function starts a previously created task for execution, allowing the specification of a time offset for the task's first execution. This offset determines when the task will begin running relative to the time the function is called.

Parameters
The function uses the following parameters:

ptcb: A pointer to the GS_TCB structure of the task to be started (obtained from gu_ TaskCreate during task creation).
hours: The number of hours in the starting offset.
minutes: The number of minutes in the starting offset.
seconds: The number of seconds in the starting offset.
ms: The number of milliseconds in the starting offset.

Returns
The gu_TaskStartWithOffset function returns G_TRUE upon successful task startup.

Thread-safety
Safe from task context or initialization.

Error conditions
Returns G_FALSE on invalid arguments.

Preconditions
ptcb must be valid. Task must be in Waiting state.

Postconditions
Task is scheduled for its first release at current_time + offset.

See also
gu_TaskCreate
gu_TaskDelay
gu_TaskDelayTime
gu_TaskGetCurrentTCB
gu_TaskKill
gu_TaskPeriodSet
gu_TaskReadyPrioritySet
gu_TaskResume
gu_TaskRunPrioritySet
gu_TaskSuspend
gu_TaskTypeSet
__________________________________________________________________

2.60 gu_TaskSuspend #

Prototype

G_UINT32 gu_TaskSuspend(GS_TCB *ptcb);

Description: The gu_TaskSuspend function suspends a task, changing its state to waiting.

Parameters
The function takes one parameter:

ptcb: A pointer to the GS_TCB structure of the task to be suspended.

Returns
The gu_TaskSuspend function always returns G_TRUE.

Thread-safety
Safe from task context (including self-suspension).

Error conditions
Returns G_FALSE if the task is not in Running or Ready state.

Preconditions
ptcb must be valid. Task must be in Running or Ready state.

Postconditions
Task is moved to Waiting state; a new task is dispatched to the freed processor.

See also
gu_TaskCreate
gu_TaskDelay
gu_TaskDelayTime
gu_TaskGetCurrentTCB
gu_TaskKill
gu_TaskPeriodSet
gu_TaskReadyPrioritySet
gu_TaskResume
gu_TaskRunPrioritySet
gu_TaskStartWithOffset
gu_TaskTypeSet
__________________________________________________________________

2.61 gu_TaskTypeSet #

Prototype

G_UINT32 gu_TaskTypeSet(struct gs_tcb *ptcb, enum tcbtype type);

Description: The gu_TaskTypeSet function sets the type of a task. The valid task types are G_TCBType_Periodic and G_TCBType_OneShot.

Parameters
The function takes these parameters:

ptcb: A pointer to the GS_TCB structure of the task whose type is to be modified.
type: The type must be either G_TCBType_Periodic or G_TCBType_OneShot. Any other value will result in failure.

Returns
The gu_TaskTypeSet function returns G_TRUE if the task type was successfully set, and G_FALSE otherwise.

Thread-safety
Safe from task context or initialization.

Error conditions
Returns G_FALSE on invalid type.

Preconditions
type must be one of: G_TCBType_OneShot, G_TCBType_Periodic, G_TCBType_Periodic_Skip, G_TCBType_ISR, G_TCBType_IDLE.

Postconditions
Task type is set; this affects scheduling and completion behavior.

See also
gu_TaskCreate
gu_TaskDelay
gu_TaskDelayTime
gu_TaskGetCurrentTCB
gu_TaskKill
gu_TaskPeriodSet
gu_TaskReadyPrioritySet
gu_TaskResume
gu_TaskRunPrioritySet
gu_TaskStartWithOffset
gu_TaskSuspend
__________________________________________________________________

2.62 gm_StatusCountingTimeGet #

Prototype

G_INT32 gm_StatusCountingTimeGet(void);  /* GRTOS_GET_INTERVAL (first read resets counter) */

Description: gm_StatusCountingTimeGet returns the status of the TIME_HOLD bit (G_TRUE or G_FALSE). The execution of gm_TimeCoutersHold holds the time counters in its current state. The execution of gm_TimeCoutersUnhold unholds the time counters.

Parameters
gm_StatusCountingTimeGet has no parameter.

Returns
The gm_StatusCountingTimeGet macro returns the time prescale.

Thread-safety
Must be called within a critical section.

Error conditions
None.

Preconditions
GeMRTOS mutex must be held for a meaningful reading.

Postconditions
The internal elapsed-time counter is reset to zero after this read.

See also
gm_StatusResetCountingTimeGet
gm_SystemTimePrescaleGet
gm_SystemTimePrescaleSet
gm_TimeIntervalGet
gu_SystemTotalTimeGet
__________________________________________________________________

2.63 gm_StatusResetCountingTimeGet #

Prototype

G_INT32 gm_StatusResetCountingTimeGet(void);  /* reads and resets ELAPSE_TM register */

Description: gm_StatusResetCountingTimeGet return the status of the time reset counter bit (G_TRUE or G_FALSE). When G_TRUE, the time counters are reset and hold. The time counters are reset and hold reset, when executing gm_TimeCountersReset. The time counters are release to run again when execution gm_TimeCoutersUnreset.

Parameters
The gm_StatusResetCountingTimeGet macro has no parameter.

Returns
The gm_StatusResetCountingTimeGet macro returns the time prescale.

Thread-safety
Must be called within a critical section.

Error conditions
None.

Preconditions
GeMRTOS mutex must be held.

Postconditions
The elapsed-time counter is reset; the returned value is the interval since the last reset.

See also
gm_StatusCountingTimeGet
gm_SystemTimePrescaleGet
gm_SystemTimePrescaleSet
gm_TimeIntervalGet
gu_SystemTotalTimeGet
__________________________________________________________________

2.64 gm_SystemTimePrescaleGet #

Prototype

G_INT32 gm_SystemTimePrescaleGet(void);  /* macro: GRTOS_CMD_GET_TIME_PRESCALE */

Description: The gm_SystemTimePrescaleGet macro returns the time prescale. This prescale is used to obtaine the system time unit from the system clock.

Parameters
The gm_SystemTimePrescaleGet macro has no parameter.

Returns
The gm_SystemTimePrescaleGet macro returns the time prescale.

Thread-safety
Read-only; safe within a critical section.

Error conditions
None.

Preconditions
None.

Postconditions
None.

See also
gm_StatusCountingTimeGet
gm_StatusResetCountingTimeGet
gm_SystemTimePrescaleSet
gm_TimeIntervalGet
gu_SystemTotalTimeGet
__________________________________________________________________

2.65 gm_SystemTimePrescaleSet #

Prototype

void gm_SystemTimePrescaleSet(G_INT32 scale);  /* macro: GRTOS_CMD_SET_TIME_PRESCALE(scale) */

Description: The gm_SystemTimePrescaleSet macro sets the system clock prescale to get the system time unit. By default, the prescale is set to configure a 10MHz frecuency for system time units. The gm_SystemTimePrescaleGet macro returns the time prescale.

Parameters
The gm_SystemTimePrescaleSet has one parameter:

scale:The prescale configuration.

Returns
The gm_SystemTimePrescaleSet macro does not return any value.

Thread-safety
Must be called within a critical section.

Error conditions
Undefined if scale is 0.

Preconditions
GeMRTOS mutex must be held. Typically set during initialization to achieve 10 MHz ticks from the system clock.

Postconditions
System time counter increments every scale clock cycles.

See also
gm_StatusCountingTimeGet
gm_StatusResetCountingTimeGet
gm_SystemTimePrescaleGet
gm_TimeIntervalGet
gu_SystemTotalTimeGet
__________________________________________________________________

2.66 gm_TimeIntervalGet #

Prototype

G_INT32 gm_TimeIntervalGet(void);  /* macro: GRTOS_GET_INTERVAL */

Description: The gm_TimeIntervalGet macro resets the Interval Time Counter, returning the last value.

Parameters
The gm_TimeIntervalGet macro has no parameter.

Returns
The gm_TimeIntervalGet macro returns the time prescale.

Thread-safety
Read-only within a critical section.

Error conditions
None.

Preconditions
None.

Postconditions
The interval counter is reset.

See also
gm_StatusCountingTimeGet
gm_StatusResetCountingTimeGet
gm_SystemTimePrescaleGet
gm_SystemTimePrescaleSet
gu_SystemTotalTimeGet
__________________________________________________________________

2.67 gu_SystemTotalTimeGet #

Prototype

G_UINT64 gu_SystemTotalTimeGet(void);  /* GRTOS_CMD_SYS_TM_GET */

Description: gu_SystemTotalTimeGet returns the total system time. It is the time in non frozen mode plus the time in frozen mode.

Parameters
The gu_SystemTotalTimeGet macro has no parameter. It has to be noted that temporal constraints (deadline, period) are related to system time, obtained using the gu_SystemTimeGet function, which is the time in non frozen mode.

Returns
The gu_SystemTotalTimeGet macro returns the total system time.

Thread-safety
Safe from task context.

Error conditions
None.

Preconditions
None.

Postconditions
None.

See also
gm_StatusCountingTimeGet
gm_StatusResetCountingTimeGet
gm_SystemTimePrescaleGet
gm_SystemTimePrescaleSet
gm_TimeIntervalGet
__________________________________________________________________

2.68 gu_TriggerCreate #

Prototype

GS_RCB *gu_TriggerCreate(int irq_id, G_UINT64 ticks_to_wait);

Description: The function creates a trigger resource. It accepts an irq_id argument to allow associating the trigger resource with a hardware interrupt.

Parameters
The trigger is created and initilized with the following paramenters:

irq_id: The irq_id argument specifies the number of the hardware interrupt to associate with the trigger resource. Setting this argument to -1 indicates that no association with a hardware interrupt is desired.
ticks_to_wait: Timeout for trigger in number of ticks.

Returns
The gu_TriggerCreate function returns a pointer to the newly created trigger resource. This pointer must be used to reference the trigger resource in all subsequent trigger-related functions.

Thread-safety
Safe from task context or initialization.

Error conditions
Returns NULL if no free RCB is available or irq_id is out of range.

Preconditions
irq_id must be in [0, ALT_NIRQ-1]. The IRQ must be connected in Platform Designer.

Postconditions
A trigger RCB is allocated and associated with irq_id. Call gu_TriggerRegisterTask to associate tasks.

See also
gu_TriggerDisable
gu_TriggerDisableHook
gu_TriggerEnable
gu_TriggerEnableHook
gu_TriggerRegisterTask
gu_TriggerRelease
gu_TriggerSetTimeoutType
gu_TriggerWait
__________________________________________________________________

2.69 gu_TriggerDisable #

Prototype

G_UINT32 gu_TriggerDisable(GS_RCB *ptrigger);

Description: The gu_TriggerDisable function disables the trigger resource, preventing it from being activated using either the gu_TriggerRelease function or the associated hardware interrupt.

Parameters
The disabling of the trigger resource is performed with the following parameter:

ptrigger: Handle of the trigger.

Returns
The function returns G_TRUE if the operation was successful.

Thread-safety
Safe from task context.

Error conditions
Returns G_FALSE if ptrigger is NULL or trigger not created.

Preconditions
Trigger must have been created with gu_TriggerCreate.

Postconditions
The IRQ is disabled; the trigger will not fire until re-enabled.

See also
gu_TriggerCreate
gu_TriggerDisableHook
gu_TriggerEnable
gu_TriggerEnableHook
gu_TriggerRegisterTask
gu_TriggerRelease
gu_TriggerSetTimeoutType
gu_TriggerWait
__________________________________________________________________

2.70 gu_TriggerDisableHook #

Prototype

G_UINT32 gu_TriggerDisableHook(GS_RCB *ptrigger, void (*code_callback)(void *), void *p_arg);

Description: The gu_TriggerDisableHook function sets the hook function to be called after the trigger resource is disabled.

Parameters
The disable hook function is specified using the following parameters:

ptrigger: Handle of the trigger.
code_callback: This parameter defines the name of the function to be executed as a hook function when the trigger resource is disabled.
p_arg: This parameter represents the value to be passed to the hook function when it is called. This allows the same hook function to be used for multiple trigger resources with different parameter values.

Returns
The function returns G_TRUE if the disable hook function was successfully configured; otherwise, it returns G_FALSE.

Thread-safety
Safe from task context or initialization.

Error conditions
Returns G_FALSE on invalid arguments.

Preconditions
Trigger must exist. code_callback must be a valid function pointer or NULL.

Postconditions
code_callback is called (with p_arg) each time this trigger is disabled.

See also
gu_TriggerCreate
gu_TriggerDisable
gu_TriggerEnable
gu_TriggerEnableHook
gu_TriggerRegisterTask
gu_TriggerRelease
gu_TriggerSetTimeoutType
gu_TriggerWait
__________________________________________________________________

2.71 gu_TriggerEnable #

Prototype

G_UINT32 gu_TriggerEnable(GS_RCB *ptrigger);

Description: The gu_TriggerEnable function enables the trigger resource, allowing it to be activated using either the gu_TriggerRelease function or the associated hardware interrupt.

Parameters
The enabling of the trigger resource is performed with the following parameters:

ptrigger: Handle of the trigger.

Returns
The function returns G_TRUE if the operation was successful.

Thread-safety
Safe from task context.

Error conditions
Returns G_FALSE if ptrigger is NULL or trigger not created.

Preconditions
Trigger must have been created. Typically called after gu_TriggerWait returns to re-arm the trigger.

Postconditions
The IRQ is enabled; the next device interrupt will release registered tasks.

See also
gu_TriggerCreate
gu_TriggerDisable
gu_TriggerDisableHook
gu_TriggerEnableHook
gu_TriggerRegisterTask
gu_TriggerRelease
gu_TriggerSetTimeoutType
gu_TriggerWait
__________________________________________________________________

2.72 gu_TriggerEnableHook #

Prototype

G_UINT32 gu_TriggerEnableHook(GS_RCB *ptrigger, void (*code_callback)(void *), void *p_arg);

Description: The gu_TriggerEnableHook sets the hook function to be called before the trigger resource is enabled.

Parameters
The gu_TriggerEnableHook function requires the following paramenters:

ptrigger: Handle of the trigger.
code_callback: This parameter defines the name of the function to be executed as a hook function when the trigger resource is enabled.
p_arg: This parameter represents the value to be passed to the hook function when it is called. This allows the same hook function to be used for multiple trigger resources with different parameter values.

Returns
The function returns G_TRUE if the enable hook function was successfully configured; otherwise, it returns G_FALSE.

Thread-safety
Safe from task context or initialization.

Error conditions
Returns G_FALSE on invalid arguments.

Preconditions
Trigger must exist. code_callback must be a valid function pointer or NULL.

Postconditions
code_callback is called (with p_arg) each time this trigger is enabled.

See also
gu_TriggerCreate
gu_TriggerDisable
gu_TriggerDisableHook
gu_TriggerEnable
gu_TriggerRegisterTask
gu_TriggerRelease
gu_TriggerSetTimeoutType
gu_TriggerWait
__________________________________________________________________

2.73 gu_TriggerRegisterTask #

Prototype

G_UINT32 gu_TriggerRegisterTask(struct gs_tcb *ptcb, GS_RCB *ptrigger);

Description: The gu_TriggerRegisterTask function associates a task with a trigger resource.

Parameters
The task registration with the trigger resource is performed using the following parameters:

ptcb: This is a pointer to the GS_TCB structure of the task to be associated with the trigger resource.
ptrigger: Handle of the trigger.

Returns
The gu_TriggerRegisterTask function returns G_TRUE if the task registration with the trigger resource is successful; otherwise, it returns G_FALSE.

Thread-safety
Safe from task context or initialization.

Error conditions
Returns G_FALSE if ptcb is invalid or ptrigger has not been created.

Preconditions
ptrigger must exist (created by gu_TriggerCreate). ptcb must be valid.

Postconditions
The task is registered; when the trigger fires it will be released.

See also
gu_TriggerCreate
gu_TriggerDisable
gu_TriggerDisableHook
gu_TriggerEnable
gu_TriggerEnableHook
gu_TriggerRelease
gu_TriggerSetTimeoutType
gu_TriggerWait
__________________________________________________________________

2.74 gu_TriggerRelease #

Prototype

GS_TRGStatus gu_TriggerRelease(GS_RCB *ptrigger);

Description: The function activates a trigger resource. If the trigger resource is enabled and all associated tasks are in a waiting state for the trigger, then the tasks are resumed or restarted.

Parameters
The trigger resource is activated using the following parameter:

ptrigger: Handle of the trigger.

Returns
Returns the trigger status after activation (GS_TRGStatus).

Thread-safety
Safe from task context.

Error conditions
Returns G_FALSE if ptrigger is NULL or invalid.

Preconditions
Trigger must exist.

Postconditions
All tasks registered to this trigger are moved from Waiting to Ready state.

See also
gu_TriggerCreate
gu_TriggerDisable
gu_TriggerDisableHook
gu_TriggerEnable
gu_TriggerEnableHook
gu_TriggerRegisterTask
gu_TriggerSetTimeoutType
gu_TriggerWait
__________________________________________________________________

2.75 gu_TriggerSetTimeoutType #

Prototype

G_UINT32 gu_TriggerSetTimeoutType(GS_RCB *ptrigger, GS_TRGTimeOutType type);

Description: Sets the trigger timeout type for a givenTrigger. This function assigns the specified timeout type to the provided task control block's TRGType member.

Parameters
The gu_TriggerSetTimeoutType requires the following parameters:

ptrigger: Pointer to the trigger ( GS_RCB *) whose timeout type is to be set.
type: The timeout type to be assigned (valid values are: GS_TRGTimeOutType_disabled, GS_TRGTimeOutType_restart_when_enable, GS_TRGTimeOutType_restart_when_timeout, GS_TRGTimeOutType_no_restart.

Returns
The function returns G_TRUE to indicate success.

Thread-safety
Safe from task context or initialization.

Error conditions
Returns G_FALSE on invalid arguments.

Preconditions
ptrigger must be a valid trigger RCB. Use before the first gu_TriggerWait.

Postconditions
The timeout behavior for waiting tasks is configured.

See also
gu_TriggerCreate
gu_TriggerDisable
gu_TriggerDisableHook
gu_TriggerEnable
gu_TriggerEnableHook
gu_TriggerRegisterTask
gu_TriggerRelease
gu_TriggerWait
__________________________________________________________________

2.76 gu_TriggerWait #

Prototype

GS_TRGStatus gu_TriggerWait(void);

Description: The gu_TriggerWait function places the task into a waiting state for the trigger resource it is registered to. It can be executed anywhere in the task's code, and the same effect occurs when the task completes its execution (assuming it's not an infinite loop).

Parameters
The gu_TriggerWait function does not require any parameters, as the task automatically waits for the trigger resource it is associated with.

Returns
Returns a GS_TRGStatus value: G_TRGStatus_triggered if the trigger fired, or G_TRGStatus_timeout if a timeout occurred.

Thread-safety
Task context only; suspends the calling task.

Error conditions
Returns status code indicating whether trigger fired (G_TRGStatus_triggered) or timed out.

Preconditions
Calling task must be registered to a trigger via gu_TriggerRegisterTask. Must be called from task context.

Postconditions
Task is moved to Waiting state; resumes when its registered trigger fires or a timeout occurs.

See also
gu_TriggerCreate
gu_TriggerDisable
gu_TriggerDisableHook
gu_TriggerEnable
gu_TriggerEnableHook
gu_TriggerRegisterTask
gu_TriggerRelease
gu_TriggerSetTimeoutType
__________________________________________________________________

__________________________________________________________________

2.77 gu_ConvertTime #

Prototype

G_UINT64 gu_ConvertTime(unsigned int hours, unsigned int minutes, unsigned int seconds, unsigned int ms);

Description: Converts a wall-clock duration into the system tick value used by every GeMRTOS timeout and period argument. Use it wherever a function expects a G_UINT64 tick count instead of computing ticks by hand.

Parameters

hours — hours component of the duration.
minutes — minutes component.
seconds — seconds component.
ms — milliseconds component.

Returns The equivalent duration expressed in system ticks.

___________

2.78 gu_SemaphoreCreateCounting #

Prototype

GS_RCB *gu_SemaphoreCreateCounting(int max_count, int initial_count);

Description: Creates a counting semaphore and returns a handle by which it can be referenced. A counting semaphore grants up to max_count simultaneous holders, which suits pools of interchangeable resources.

Parameters

max_count — maximum number of grants the semaphore may hold.
initial_count — grants available immediately after creation.

Returns Handle to the new semaphore, or 0 if it could not be created.

2.79 gu_SemaphoreDestroy #

Prototype

G_UINT32 gu_SemaphoreDestroy(GS_RCB *psemaphore);

Description: Destroys a semaphore and returns its resource control block to the free pool.

Parameters

psemaphore — handle returned by a gu_SemaphoreCreate* function.

Returns G_TRUE on success, G_FALSE otherwise.

_____________________

2.80 gu_MessageQueueDestroy #

Prototype

G_UINT32 gu_MessageQueueDestroy(GS_RCB *prcb);

Description: Destroys a message queue and returns its resource control block to the free pool.

Parameters

prcb — handle returned by gu_MessageQueueCreate.

Returns G_TRUE on success, G_FALSE otherwise.

_____________________

2.81 gu_TriggerDestroy #

Prototype

G_UINT32 gu_TriggerDestroy(GS_RCB *ptrigger);

Description: Destroys a trigger resource, returning its resource control block and its timeout event to the free pool.

Parameters

ptrigger — handle returned by gu_TriggerCreate.

Returns G_TRUE on success, G_FALSE otherwise.

Avalon MM, GeMRTOS, Nios 2, Nios V, RISC-V

Still stuck? How can we help?