mark3c.h

Go to the documentation of this file.

/*===========================================================================
     _____        _____        _____        _____
 ___|    _|__  __|_    |__  __|__   |__  __| __  |__  ______
|    \  /  | ||    \      ||     |     ||  |/ /     ||___   |
|     \/   | ||     \     ||     \     ||     \     ||___   |
|__/\__/|__|_||__|\__\  __||__|\__\  __||__|\__\  __||______|
    |_____|      |_____|      |_____|      |_____|

--[Mark3 Realtime Platform]--------------------------------------------------

Copyright (c) 2012 - 2019 m0slevin, all rights reserved.
See license.txt for more information
===========================================================================*/
#pragma once

#include "mark3cfg.h"
#include "fake_types.h"

#include <stdint.h>
#include <stdbool.h>

#if defined(__cplusplus)
extern "C" {
#endif

//---------------------------------------------------------------------------
// Define a series of handle types to be used in place of the underlying classes
// of Mark3.
#if KERNEL_EVENT_FLAGS
typedef void* EventFlag_t;         
#endif                             // #if KERNEL_EVENT_FLAGS
typedef void* Mailbox_t;           
typedef void* Message_t;           
typedef void* MessagePool_t;       
typedef void* MessageQueue_t;      
typedef void* Mutex_t;             
typedef void* Notify_t;            
typedef void* Semaphore_t;         
typedef void* Thread_t;            
typedef void* Timer_t;             
typedef void* ConditionVariable_t; 
typedef void* ReaderWriterLock_t;  
typedef void* Coroutine_t;         

//---------------------------------------------------------------------------
// Function pointer types used by Kernel APIs
#if KERNEL_THREAD_CREATE_CALLOUT
typedef void (*thread_create_callout_t)(Thread_t hThread_);
#endif // #if KERNEL_THREAD_CREATE_CALLOUT
#if KERNEL_THREAD_EXIT_CALLOUT
typedef void (*thread_exit_callout_t)(Thread_t hThread_);
#endif // #if KERNEL_THREAD_EXIT_CALLOUT
#if KERNEL_CONTEXT_SWITCH_CALLOUT
typedef void (*thread_context_callout_t)(Thread_t hThread_);
#endif // #if KERNEL_CONTEXT_SWITCH_CALLOUT
typedef void (*kernel_debug_print_t)(const char* szString_);
typedef void (*coroutine_callback_t)(Coroutine_t caller, void* pvContext);

//---------------------------------------------------------------------------
// Use the sizes of the structs in fake_types.h to generate opaque object-blobs
// that get instantiated as kernel objects (from the C++ code) later.
#define THREAD_SIZE (sizeof(Fake_Thread))
#define TIMER_SIZE (sizeof(Fake_Timer))
#define SEMAPHORE_SIZE (sizeof(Fake_Semaphore))
#define MUTEX_SIZE (sizeof(Fake_Mutex))
#define MESSAGE_SIZE (sizeof(Fake_Message))
#define MESSAGEQUEUE_SIZE (sizeof(Fake_MessageQueue))
#define MAILBOX_SIZE (sizeof(Fake_Mailbox))
#define NOTIFY_SIZE (sizeof(Fake_Notify))
#if KERNEL_EVENT_FLAGS
#define EVENTFLAG_SIZE (sizeof(Fake_EventFlag))
#endif // #if KERNEL_EVENT_FLAGS
#define MESSAGEPOOL_SIZE (sizeof(Fake_MessagePool))
#define CONDITIONVARIABLE_SIZE (sizeof(Fake_ConditionVariable))
#define READERWRITERLOCK_SIZE (sizeof(Fake_ReaderWriterLock))
#define COROUTINE_SIZE (sizeof(Fake_Coroutine))
#if KERNEL_EVENT_FLAGS
//---------------------------------------------------------------------------
typedef enum {
    EVENT_FLAG_ALL_SET,        
    EVENT_FLAG_ANY_SET,        
    EVENT_FLAG_ALL_CLEAR,      
    EVENT_FlAG_ANY_CLEAR,      
    EVENT_FLAG_PENDING_UNBLOCK 
} event_flag_operation_t;
#endif // #if KERNEL_EVENT_FLAGS

//---------------------------------------------------------------------------
typedef enum {
    THREAD_STATE_EXIT = 0, 
    THREAD_STATE_READY,    
    THREAD_STATE_BLOCKED,  
    THREAD_STATE_STOP,     
    THREAD_STATE_INVALID   
} thread_state_t;

//---------------------------------------------------------------------------
// Macros for declaring opaque buffers of an appropriate size for the given
// kernel objects
#define TOKEN_1(x, y) x##y
#define TOKEN_2(x, y) TOKEN_1(x, y)

// Ensure that opaque buffers are sized to the nearest word - which is
// a platform-dependent value.
#define WORD_ROUND(x) (((x) + (sizeof(K_WORD) - 1)) / sizeof(K_WORD))

#define DECLARE_THREAD(name)                                                                                           \
    K_WORD   TOKEN_2(__thread_, name)[WORD_ROUND(THREAD_SIZE)];                                                        \
    Thread_t name = (Thread_t)TOKEN_2(__thread_, name);

#define DECLARE_TIMER(name)                                                                                            \
    K_WORD  TOKEN_2(__timer_, name)[WORD_ROUND(TIMER_SIZE)];                                                           \
    Timer_t name = (Timer_t)TOKEN_2(__timer_, name);

#define DECLARE_SEMAPHORE(name)                                                                                        \
    K_WORD      TOKEN_2(__semaphore_, name)[WORD_ROUND(SEMAPHORE_SIZE)];                                               \
    Semaphore_t name = (Semaphore_t)TOKEN_2(__semaphore_, name);

#define DECLARE_MUTEX(name)                                                                                            \
    K_WORD  TOKEN_2(__mutex_, name)[WORD_ROUND(MUTEX_SIZE)];                                                           \
    Mutex_t name = (Mutex_t)TOKEN_2(__mutex_, name);

#define DECLARE_MESSAGE(name)                                                                                          \
    K_WORD    TOKEN_2(__message_, name)[WORD_ROUND(MESSAGE_SIZE)];                                                     \
    Message_t name = (Message_t)TOKEN_2(__message_, name);

#define DECLARE_MESSAGEPOOL(name)                                                                                      \
    K_WORD        TOKEN_2(__messagepool_, name)[WORD_ROUND(MESSAGEPOOL_SIZE)];                                         \
    MessagePool_t name = (MessagePool_t)TOKEN_2(__messagepool_, name);

#define DECLARE_MESSAGEQUEUE(name)                                                                                     \
    K_WORD         TOKEN_2(__messagequeue_, name)[WORD_ROUND(MESSAGEQUEUE_SIZE)];                                      \
    MessageQueue_t name = (MessageQueue_t)TOKEN_2(__messagequeue_, name);

#define DECLARE_MAILBOX(name)                                                                                          \
    K_WORD    TOKEN_2(__mailbox_, name)[WORD_ROUND(MAILBOX_SIZE)];                                                     \
    Mailbox_t name = (Mailbox_t)TOKEN_2(__mailbox_, name);

#define DECLARE_NOTIFY(name)                                                                                           \
    K_WORD   TOKEN_2(__notify_, name)[WORD_ROUND(NOTIFY_SIZE)];                                                        \
    Notify_t name = (Notify_t)TOKEN_2(__notify_, name);

#if KERNEL_EVENT_FLAGS
#define DECLARE_EVENTFLAG(name)                                                                                        \
    K_WORD      TOKEN_2(__eventflag_, name)[WORD_ROUND(EVENTFLAG_SIZE)];                                               \
    EventFlag_t name = (EventFlag_t)TOKEN_2(__eventflag_, name);
#endif // #if KERNEL_EVENT_FLAGS

#define DECLARE_CONDITIONVARIABLE(name)                                                                                \
    K_WORD              TOKEN_2(__condvar_, name)[WORD_ROUND(EVENTFLAG_SIZE)];                                         \
    ConditionVariable_t name = (ConditionVariable_t)TOKEN_2(__condvar_, name);

#define DECLARE_READERWRITERLOCK(name)                                                                                 \
    K_WORD             TOKEN_2(__readerwriterlock_, name)[WORD_ROUND(EVENTFLAG_SIZE)];                                 \
    ReaderWriterLock_t name = (ReaderWriterLock_t)TOKEN_2(__readerwriterlock_, name);

#define DECLARE_COROUTINE(name) \
    K_WORD             TOKEN_2(__coroutine_, name)[WORD_ROUND(COROUTINE_SIZE)]; \
    Coroutine_t name = (Coroutine_t)TOKEN_2(__coroutine_, name);

//---------------------------------------------------------------------------
// Allocate-once Memory managment APIs
void* Alloc_Memory(size_t eSize_);

void Free_Memory(void* pvObject_);

Semaphore_t Alloc_Semaphore(void);
void        Free_Semaphore(Semaphore_t handle);

Mutex_t Alloc_Mutex(void);
void    Free_Mutex(Mutex_t handle);

#if KERNEL_EVENT_FLAGS

EventFlag_t Alloc_EventFlag(void);
void        Free_EventFlag(EventFlag_t handle);
#endif // #if KERNEL_EVENT_FLAGS

Message_t Alloc_Message(void);
void      Free_Message(Message_t handle);

MessageQueue_t Alloc_MessageQueue(void);
void           Free_MessageQueue(MessageQueue_t handle);

MessagePool_t Alloc_MessagePool(void);
void          Free_MessagePool(MessagePool_t handle);

Notify_t Alloc_Notify(void);
void     Free_Notify(Notify_t handle);

Mailbox_t Alloc_Mailbox(void);
void      Free_Mailbox(Mailbox_t handle);

Thread_t Alloc_Thread(void);
void     Free_Thread(Thread_t handle);

Timer_t Alloc_Timer(void);
void    Free_Timer(Timer_t handle);

//---------------------------------------------------------------------------
// Kernel APIs
void Kernel_Init(void);
void Kernel_Start(void);
bool Kernel_IsStarted(void);

typedef void (*panic_func_t)(uint16_t u16PanicCode_);
void Kernel_SetPanic(panic_func_t pfPanic_);
bool Kernel_IsPanic(void);
void Kernel_Panic(uint16_t u16Cause_);

#if KERNEL_THREAD_CREATE_CALLOUT

void Kernel_SetThreadCreateCallout(thread_create_callout_t pfCreate_);
#endif // #if KERNEL_THREAD_CREATE_CALLOUT

#if KERNEL_THREAD_EXIT_CALLOUT

void Kernel_SetThreadExitCallout(thread_exit_callout_t pfExit_);
#endif // #if KERNEL_THREAD_EXIT_CALLOUT

#if KERNEL_CONTEXT_SWITCH_CALLOUT

void Kernel_SetThreadContextSwitchCallout(thread_context_callout_t pfContext_);
#endif // #if KERNEL_CONTEXT_SWITCH_CALLOUT

#if KERNEL_THREAD_CREATE_CALLOUT

thread_create_callout_t Kernel_GetThreadCreateCallout(void);
#endif // #if KERNEL_THREAD_CREATE_CALLOUT

#if KERNEL_THREAD_EXIT_CALLOUT

thread_exit_callout_t Kernel_GetThreadExitCallout(void);
#endif // #if KERNEL_THREAD_EXIT_CALLOUT

#if KERNEL_CONTEXT_SWITCH_CALLOUT

thread_context_callout_t Kernel_GetThreadContextSwitchCallout(void);
#endif // #if KERNEL_CONTEXT_SWITCH_CALLOUT

#if KERNEL_STACK_CHECK

void Kernel_SetStackGuardThreshold(uint16_t u16Threshold_);

uint16_t Kernel_GetStackGuardThreshold(void);
#endif // #if KERNEL_STACK_CHECK

uint32_t Kernel_GetTicks(void);

//---------------------------------------------------------------------------
// Scheduler APIs
void Scheduler_Enable(bool bEnable_);
bool Scheduler_IsEnabled(void);
Thread_t Scheduler_GetCurrentThread(void);

typedef void (*thread_entry_func_t)(void* pvArg_);
//---------------------------------------------------------------------------
// Thread APIs
void Thread_Init(Thread_t            handle,
                 K_WORD*             pwStack_,
                 uint16_t            u16StackSize_,
                 PORT_PRIO_TYPE      uXPriority_,
                 thread_entry_func_t pfEntryPoint_,
                 void*               pvArg_);
void Thread_Start(Thread_t handle);
void Thread_Stop(Thread_t handle);

#if KERNEL_NAMED_THREADS

void Thread_SetName(Thread_t handle, const char* szName_);
const char* Thread_GetName(Thread_t handle);
#endif // #if KERNEL_NAMED_THREADS

PORT_PRIO_TYPE Thread_GetPriority(Thread_t handle);
PORT_PRIO_TYPE Thread_GetCurPriority(Thread_t handle);

#if KERNEL_ROUND_ROBIN

void Thread_SetQuantum(Thread_t handle, uint16_t u16Quantum_);
uint16_t Thread_GetQuantum(Thread_t handle);
#endif // #if KERNEL_ROUND_ROBIN

void Thread_SetPriority(Thread_t handle, PORT_PRIO_TYPE uXPriority_);
void Thread_Exit(Thread_t handle);
void Thread_Sleep(uint32_t u32TimeMs_);

#if KERNEL_EXTENDED_CONTEXT

void* Thread_GetExtendedContext(Thread_t handle);

void Thread_SetExtendedContext(Thread_t handle, void* pvData_);
#endif // #if KERNEL_EXTENDED_CONTEXT

void Thread_Yield(void);

void Thread_CoopYield(void);

void Thread_SetID(Thread_t handle, uint8_t u8ID_);
uint8_t Thread_GetID(Thread_t handle);

#if KERNEL_STACK_CHECK

uint16_t Thread_GetStackSlack(Thread_t handle);
#endif // #if KERNEL_STACK_CHECK

thread_state_t Thread_GetState(Thread_t handle);

//---------------------------------------------------------------------------
// Timer APIs
typedef void (*timer_callback_t)(Thread_t hOwner_, void* pvData_);
void Timer_Init(Timer_t handle);
void Timer_Start(Timer_t handle, bool bRepeat_, uint32_t u32IntervalMs_, timer_callback_t pfCallback_, void* pvData_);

void Timer_Restart(Timer_t handle);

void Timer_Stop(Timer_t handle);

//---------------------------------------------------------------------------
// Semaphore APIs
void Semaphore_Init(Semaphore_t handle, uint16_t u16InitVal_, uint16_t u16MaxVal_);
void Semaphore_Post(Semaphore_t handle);
void Semaphore_Pend(Semaphore_t handle);
bool Semaphore_TimedPend(Semaphore_t handle, uint32_t u32WaitTimeMS_);

//---------------------------------------------------------------------------
// Mutex APIs
void Mutex_Init(Mutex_t handle);
void Mutex_Claim(Mutex_t handle);
void Mutex_Release(Mutex_t handle);
bool Mutex_TimedClaim(Mutex_t handle, uint32_t u32WaitTimeMS_);

#if KERNEL_EVENT_FLAGS
//---------------------------------------------------------------------------
// EventFlag APIs
void EventFlag_Init(EventFlag_t handle);
uint16_t EventFlag_Wait(EventFlag_t handle, uint16_t u16Mask_, event_flag_operation_t eMode_);
uint16_t EventFlag_TimedWait(EventFlag_t handle, uint16_t u16Mask_, event_flag_operation_t eMode_, uint32_t u32TimeMS_);
void EventFlag_Set(EventFlag_t handle, uint16_t u16Mask_);
void EventFlag_Clear(EventFlag_t handle, uint16_t u16Mask_);
uint16_t EventFlag_GetMask(EventFlag_t handle);
#endif // #if KERNEL_EVENT_FLAGS

//---------------------------------------------------------------------------
// Notification APIs
void Notify_Init(Notify_t handle);
void Notify_Signal(Notify_t handle);
void Notify_Wait(Notify_t handle, bool* pbFlag_);
bool Notify_TimedWait(Notify_t handle, uint32_t u32WaitTimeMS_, bool* pbFlag_);

//---------------------------------------------------------------------------
// Atomic Functions
uint8_t Atomic_Set8(uint8_t* pu8Source_, uint8_t u8Val_);
uint16_t Atomic_Set16(uint16_t* pu16Source_, uint16_t u16Val_);
uint32_t Atomic_Set32(uint32_t* pu32Source_, uint32_t u32Val_);
uint8_t Atomic_Add8(uint8_t* pu8Source_, uint8_t u8Val_);
uint16_t Atomic_Add16(uint16_t* pu16Source_, uint16_t u16Val_);
uint32_t Atomic_Add32(uint32_t* pu32Source_, uint32_t u32Val_);
uint8_t Atomic_Sub8(uint8_t* pu8Source_, uint8_t u8Val_);
uint16_t Atomic_Sub16(uint16_t* pu16Source_, uint16_t u16Val_);
uint32_t Atomic_Sub32(uint32_t* pu32Source_, uint32_t u32Val_);
bool Atomic_TestAndSet(bool* pbLock);

//---------------------------------------------------------------------------
// Message/Message Queue APIs
void Message_Init(Message_t handle);
void Message_SetData(Message_t handle, void* pvData_);
void* Message_GetData(Message_t handle);
void Message_SetCode(Message_t handle, uint16_t u16Code_);
uint16_t Message_GetCode(Message_t handle);
void MessageQueue_Init(MessageQueue_t handle);
Message_t MessageQueue_Receive(MessageQueue_t handle);
Message_t MessageQueue_TimedReceive(MessageQueue_t handle, uint32_t u32TimeWaitMS_);

void MessageQueue_Send(MessageQueue_t handle, Message_t hMessage_);

uint16_t MessageQueue_GetCount(MessageQueue_t handle);

void MessagePool_Init(MessagePool_t handle);

void MessagePool_Push(MessagePool_t handle, Message_t msg);

Message_t MessagePool_Pop(MessagePool_t handle);

//---------------------------------------------------------------------------
// Mailbox APIs

void Mailbox_Init(Mailbox_t handle, void* pvBuffer_, uint16_t u16BufferSize_, uint16_t u16ElementSize_);

bool Mailbox_Send(Mailbox_t handle, void* pvData_);

bool Mailbox_SendTail(Mailbox_t handle, void* pvData_);

bool Mailbox_TimedSend(Mailbox_t handle, void* pvData_, uint32_t u32TimeoutMS_);

bool Mailbox_TimedSendTail(Mailbox_t handle, void* pvData_, uint32_t u32TimeoutMS_);

void Mailbox_Receive(Mailbox_t handle, void* pvData_);

void Mailbox_ReceiveTail(Mailbox_t handle, void* pvData_);

bool Mailbox_TimedReceive(Mailbox_t handle, void* pvData_, uint32_t u32TimeoutMS_);

bool Mailbox_TimedReceiveTail(Mailbox_t handle, void* pvData_, uint32_t u32TimeoutMS_);

uint16_t Mailbox_GetFreeSlots(Mailbox_t handle);

bool Mailbox_IsFull(Mailbox_t handle);

bool Mailbox_IsEmpty(Mailbox_t handle);

//---------------------------------------------------------------------------
// Condition Variables
void ConditionVariable_Init(ConditionVariable_t handle);

void ConditionVariable_Wait(ConditionVariable_t handle, Mutex_t hMutex_);

void ConditionVariable_Signal(ConditionVariable_t handle);

void ConditionVariable_Broadcast(ConditionVariable_t handle);

bool ConditionVariable_TimedWait(ConditionVariable_t handle, Mutex_t hMutex_, uint32_t u32WaitTimeMS_);

//---------------------------------------------------------------------------
// Reader-writer locks
void ReaderWriterLock_Init(ReaderWriterLock_t handle);

void ReaderWriterLock_AcquireReader(ReaderWriterLock_t handle);

void ReaderWriterLock_ReleaseReader(ReaderWriterLock_t handle);

void ReaderWriterLock_AcquireWriter(ReaderWriterLock_t handle);

void ReaderWriterLock_ReleaseWriter(ReaderWriterLock_t handle);

bool ReaderWriterLock_TimedAcquireWriter(ReaderWriterLock_t handle, uint32_t u32TimeoutMs_);

bool ReaderWriterLock_TimedAcquireReader(ReaderWriterLock_t handle, uint32_t u32TimeoutMs_);

void Kernel_SetDebugPrintFunction(kernel_debug_print_t pfPrintFunction_);

void Kernel_DebugPrint(const char* szString_);

#if defined(__cplusplus)
}
#endif