Kernel

Main header file for the QRT kernel.

This file contains the main declarations and macros for the QRT kernel. It includes function prototypes for initializing and starting the kernel, as well as various utility macros for time conversions and MPU configurations.

Copyright

Copyright (c) 2025 TNX Software Ltd. All rights reserved. Licensed under the terms of the QuantumRT Kernel License. the LICENSE file in the root of this package for details.

Typedefs

typedef unsigned long long int qrt_u64_t

typedef unsigned int qrt_u32_t

typedef unsigned short qrt_u16_t

typedef unsigned char qrt_u8_t

typedef signed long long int qrt_s64_t

typedef signed int qrt_s32_t

typedef signed short qrt_s16_t

typedef signed char qrt_s8_t

typedef unsigned long int qrt_uptr_t

typedef signed long int qrt_sptr_t

typedef qrt_s32_t (*qrt_syscall_ext_t)(void*)

Functions

qrt_s32_t qrt_syscall_register(qrt_s32_t (*syscall)(void*), qrt_u32_t *id)

Register a System Call Extension.

Error numbers:

• EPERM Attempt to register from unprivileged thread.

• EINVAL Null pointer passed as parameter.

• ENOSPC No more System Call Extension slots available.

Parameters:

• syscall – Pointer to the System Call Extension.

• fid – Pointer to store the assigned function ID.

Returns:

0 if success, error number otherwise.

qrt_u32_t MyHardwareRead(void *param)
{
    // Simulated hardware read operation
    return *((volatile qrt_uptr_t *)param);
}

qrt_u32_t MyHardwareWrite(void *param)
{
    // Simulated hardware write operation
    *((volatile qrt_uptr_t *)param) = 0xDEADBEEFu;
    return 0u;
}

qrt_u32_t MyHardwareControl(void *param)
{
    // Simulated peripheral control operation
    return 1u; // Example success response
}

void *thread(void *arg)
{
    (void)arg;
    qrt_s32_t result;
    qrt_u32_t hw_read_fid;
    qrt_u32_t hw_write_fid;
    qrt_u32_t hw_control_fid;
    volatile qrt_uptr_t hardwareRegister = 0x40000000u; // Example hardware register
    qrt_syscall_ext_t syscalls[] = { MyHardwareRead, MyHardwareWrite,    MyHardwareControl };
    qrt_u32_t        *fid_tbl[]  = { &hw_read_id,    &hw_write_id,       &hw_control_id };

    // Initialize System Call Extensions
    for (int i = 0; i < sizeof(syscalls) / sizeof(syscalls[0]); i++)
    {
        qrt_syscall_register(syscalls[i], fid_tbl[i]);
    }
    for (;;)
    {
        // Invoke System Call Extensions
        result = qrt_syscall_invoke(hw_read_fid, (void *)&hardwareRegister);

        qrt_syscall_invoke(hw_write_fid, (void *)&hardwareRegister);

        result = qrt_syscall_invoke(hw_control_fid, NULL);
    }

    return NULL;
}

qrt_s32_t qrt_syscall_invoke(qrt_u32_t f, void *param)

Call a custom System Call.

See also

qrt_syscall_register for the use of System Call Extensions.

Parameters:

• f – Function ID.

• param – Pointer to the function parameter.

Returns:

Return value from the function passed as parameter.

void qrt_fpu_ctxenable(void)

Enables FPU usage for the current thread.

Marks the current thread as an FPU-using thread. Once enabled, the kernel will include the full floating-point context (S0–S31 and FPSCR) in context switching for this thread.

void *thread(void *arg)
{
    ...

    // Enable FPU context tracking for this thread.
    qrt_fpu_ctxenable();

    do_floating_point_work();

    // FPU no longer needed, disable FPU context tracking for this thread.
    qrt_fpu_ctxdisable();

    ...

    return NULL;
}

void qrt_fpu_ctxdisable(void)

Mark the current thread as not using the FPU.

The kernel will skip saving and restoring the FPU registers (S16–S31, FPSCR) during context switches involving this thread.

See also

qrt_fpu_ctxenable for example usage.

Warning

After calling this function, the thread must not use any FPU instructions unless FPU access is explicitly re-enabled using qrt_fpu_ctxenable(). Failing to do so may result in data corruption or undefined behavior.

qrt_s32_t qrt_kernel_boot(pthread_t *thread, const pthread_attr_t *attr, void *(*start_routine)(void*), void *arg)

Starts the kernel.

Error numbers:

• ENOMEM Not enough memory to start the kernel, increase the kernel heap size QRT_CFG_KERNEL_HEAP_SIZE or increase the thread stack pool size QRT_CFG_STACK_POOL_SIZE

  .

  This function transitions the system from initialization to multithreading mode, allowing the scheduler to begin executing threads. Once the kernel is started, this function does not return.

Once the kernel is started, further modifications to system initialization should not be attempted.

// Example: System initialization before starting the kernel

void *main_thread(void *arg)
{
   for (;;)
   {
      // Thread work here
   }
   return NULL;
}

void *thread(void *arg)
{
   for (;;)
   {
      // Thread work here
   }
   return NULL;
}

int main(void)
{
    ...

    // Initialize board-specific hardware
    BSP_Init();

    // Start the kernel
    qrt_kernel_boot(NULL, NULL, main_thread, NULL);

    // Main turned into main thread

    // Now we can create threads, kernel objects, etc.

    // Create application threads
    pthread_create(NULL, NULL, thread, NULL);
    
    ...
}

Note

This function must be called after all necessary system initialization is complete.

Parameters:

• thread – Pointer to the thread handle. NULL if not needed.

• attr – Pointer to the thread attributes. NULL for default attributes.

• start_routine – Pointer to the function to be executed by the thread.

• arg – Argument to be passed to the thread function.

Returns:

0 if success, error number otherwise.

qrt_s32_t qrt_kernel_idlehookregister(void (*hook_function)(void))

Register an idle hook function to be called when the system is idle. Registering an idle hook requires the thread to be privileged if MPU is enabled.

Note

The idle hook function is called from privileged context which exposes an attack vector if untrusted code is executed. It is users responsibility to ensure the hook function does not compromise system security.

Note

System Calls from idle hook lead to undefined behavior.

Parameters:

• hook_function – Pointer to the idle hook function. NULL pointer to unregister the idle hook.

Returns:

Returns 0 on success, or EPERM if called from unprivileged thread when MPU is enabled.

qrt_s32_t qrt_systimer_configure(void (*reloadPtr)(qrt_u32_t), qrt_u32_t (*getCountPtr)(void), qrt_u32_t max_period, qrt_u32_t frequency_hz, qrt_s32_t irqn)

Configure the System Timer. Must be called before the kernel is started.

Error numbers:

• EINVAL Invalid function pointer was passed.

• EINVAL IRQ number < 0 was passed.

Parameters:

• reloadPtr – Pointer to the function to reload the timer.

• getCountPtr – Pointer to the function to get the current timer count.

• max_period – Maximum timer period in ticks.

• frequency_hz – Timer frequency in Hz.

• irqn – Interrupt request number for the timer.

Returns:

Returns 0 on success, or an error number on failure.

qrt_s32_t qrt_systimer_getmonotonic(qrt_u64_t *ticks)

Get monotonic System Timer count.

The monotonic counter is used to track the time elapsed since the system started.

Parameters:

• ticks – Pointer to store the current monotonic tick count.

Returns:

0 on success, EINVAL if the kernel is not running.

void qrt_systimer_handler(void)

System Timer Handler. Must be called from the host timer interrupt handler.

void SysTick_Handler(void)
{
   qrt_systimer_handler();
}

qrt_s32_t qrt_defer_call(void (*deferred_function)(qrt_u32_t), qrt_u32_t parameter)

Defer a function call to the kernel.

Error numbers:

• ENOSPC Deferred call buffer is full.

• EINVAL Invalid pointer to deferred function.

Parameters:

• deferred_function – Pointer to the deferred function.

• parameter – Parameter to the deferred function.

Returns:

0 on success, error number otherwise.

void my_deferred_function(qrt_u32_t param)
{
    // Process the deferred action.
    do_some_work(param);

    // Kernel calls can be made here.
    sem_post(&sem);
}

void ISR_Handler(void)
{
    // Defer function execution to kernel context.
    qrt_defer_call(my_deferred_function, 3);
}