ar_kernel.h

Go to the documentation of this file.

/*
 * Copyright (c) 2007-2018 Immo Software
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * o Redistributions of source code must retain the above copyright notice, this list
 *   of conditions and the following disclaimer.
 *
 * o Redistributions in binary form must reproduce the above copyright notice, this
 *   list of conditions and the following disclaimer in the documentation and/or
 *   other materials provided with the distribution.
 *
 * o Neither the name of the copyright holder nor the names of its contributors may
 *   be used to endorse or promote products derived from this software without
 *   specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
#if !defined(_AR_KERNEL_H_)
#define _AR_KERNEL_H_

#include "ar_port.h"
#include "ar_config.h"

//------------------------------------------------------------------------------
// Constants
//------------------------------------------------------------------------------

#define AR_VERSION (0x00010300)

enum _ar_timeouts
{
    kArNoTimeout = 0,                   
    kArInfiniteTimeout = 0xffffffffUL   
};

typedef enum _ar_status {
    kArSuccess = 0,             
    kArTimeoutError,            
    kArObjectDeletedError,      
    kArQueueFullError,          
    kArQueueEmptyError,         
    kArInvalidPriorityError,    
    kArStackSizeTooSmallError,  
    kArNotFromInterruptError,   
    kArNotOwnerError,           
    kArAlreadyUnlockedError,    
    kArInvalidParameterError,   
    kArTimerNotRunningError,    
    kArTimerNoRunLoop,          
    kArOutOfMemoryError,        
    kArInvalidStateError,       
    kArAlreadyAttachedError,    
    kArRunLoopAlreadyRunningError, 
    kArRunLoopStopped,          
    kArRunLoopQueueReceived,    
} ar_status_t;

enum _ar_thread_start {
    kArStartThread = true,      
    kArSuspendThread = false    
};

typedef enum _ar_thread_state {
    kArThreadUnknown,     
    kArThreadSuspended,   
    kArThreadReady,       
    kArThreadRunning,     
    kArThreadBlocked,     
    kArThreadSleeping,    
    kArThreadDone         
} ar_thread_state_t;

enum _ar_thread_priorities
{
    kArIdleThreadPriority = 0,  
    kArMinThreadPriority = 1,   
    kArMaxThreadPriority = 255  
};

typedef enum _ar_timer_modes {
    kArOneShotTimer,      
    kArPeriodicTimer      
} ar_timer_mode_t;

//------------------------------------------------------------------------------
// Types
//------------------------------------------------------------------------------

// Forward declarations.
typedef struct _ar_thread ar_thread_t;
typedef struct _ar_channel ar_channel_t;
typedef struct _ar_queue ar_queue_t;
typedef struct _ar_timer ar_timer_t;
typedef struct _ar_runloop ar_runloop_t;
typedef struct _ar_list_node ar_list_node_t;


typedef bool (*ar_sort_predicate_t)(ar_list_node_t * a, ar_list_node_t * b);

typedef void (*ar_thread_entry_t)(void * param);

typedef void (*ar_timer_entry_t)(ar_timer_t * timer, void * param);

typedef void (*ar_runloop_function_t)(void * param);

typedef void (*ar_runloop_queue_handler_t)(ar_queue_t * queue, void * param);

typedef void (*ar_runloop_channel_handler_t)(ar_channel_t * channel, void * param);



struct _ar_list_node {
    ar_list_node_t * m_next;    
    ar_list_node_t * m_prev;    
    void * m_obj;               

    // Internal utility methods.
#if defined(__cplusplus)
    template <typename T> T * getObject() { return reinterpret_cast<T *>(m_obj); }
    void insertBefore(ar_list_node_t * node);   
#endif // __cplusplus
};

typedef struct _ar_list {
    ar_list_node_t * m_head;    
    ar_sort_predicate_t m_predicate;    

    // Internal utility methods.
#if defined(__cplusplus)
    template <typename T> T * getHead() { return m_head ? m_head->getObject<T>() : 0; }
    inline bool isEmpty() const;                
    bool contains(ar_list_node_t * item);       
    void add(ar_list_node_t * item);            
    inline void add(ar_thread_t * item);        
    inline void add(ar_timer_t * item);         
    inline void add(ar_queue_t * item);         
    void remove(ar_list_node_t * item);         
    inline void remove(ar_thread_t * item);     
    inline void remove(ar_timer_t * item);      
    inline void remove(ar_queue_t * item);      
    void check();
#endif // __cplusplus
} ar_list_t;

struct _ar_thread {
    volatile uint8_t * m_stackPointer;  
    ar_thread_port_data_t m_portData; 
    const char * m_name;        
    uint32_t * m_stackBottom;   
    uint8_t m_priority;         
    ar_thread_state_t m_state;  
    ar_thread_entry_t m_entry;  
    ar_list_node_t m_threadNode;    
#if AR_GLOBAL_OBJECT_LISTS
    ar_list_node_t m_createdNode;   
#endif // AR_GLOBAL_OBJECT_LISTS
    ar_list_node_t m_blockedNode;   
    uint32_t m_wakeupTime;          
    ar_status_t m_unblockStatus;       
    void * m_channelData;       
    ar_runloop_t * m_runLoop;   
#if AR_ENABLE_SYSTEM_LOAD
    uint16_t m_permilleCpu;     
    uint32_t m_loadAccumulator; 
#endif // AR_ENABLE_SYSTEM_LOAD
    uint32_t * m_stackTop;      
    uint32_t m_uniqueId;        

    // Internal utility methods.
#if defined(__cplusplus)
    void block(ar_list_t & blockedList, uint32_t timeout);
    void unblockWithStatus(ar_list_t & blockedList, ar_status_t unblockStatus);
#endif // __cplusplus
};

typedef struct _ar_thread_status {
    ar_thread_t * m_thread;     
    const char * m_name;        
    uint32_t m_uniqueId;        
    uint32_t m_cpu;             
    ar_thread_state_t m_state;  
    uint32_t m_maxStackUsed;    
    uint32_t m_stackSize;       
} ar_thread_status_t;

typedef struct _ar_semaphore {
    const char * m_name;            
    volatile unsigned m_count;      
    ar_list_t m_blockedList;        
#if AR_GLOBAL_OBJECT_LISTS
    ar_list_node_t m_createdNode;   
#endif // AR_GLOBAL_OBJECT_LISTS
} ar_semaphore_t;

typedef struct _ar_mutex {
    const char * m_name;            
    volatile ar_thread_t * m_owner;     
    volatile unsigned m_ownerLockCount; 
    uint8_t m_originalPriority;         
    ar_list_t m_blockedList;        
#if AR_GLOBAL_OBJECT_LISTS
    ar_list_node_t m_createdNode;   
#endif // AR_GLOBAL_OBJECT_LISTS
} ar_mutex_t;

struct _ar_channel {
    const char * m_name;            
    uint32_t m_width;               
    ar_list_t m_blockedSenders;     
    ar_list_t m_blockedReceivers;   
#if AR_GLOBAL_OBJECT_LISTS
    ar_list_node_t m_createdNode;   
#endif // AR_GLOBAL_OBJECT_LISTS
};

struct _ar_queue {
    const char * m_name;    
    uint8_t * m_elements;   
    unsigned m_elementSize; 
    unsigned m_capacity;    
    unsigned m_head;        
    unsigned m_tail;        
    unsigned m_count;       
    ar_list_t m_sendBlockedList;    
    ar_list_t m_receiveBlockedList; 
    ar_runloop_t * m_runLoop;       
    ar_list_node_t m_runLoopNode;   
    ar_runloop_queue_handler_t m_runLoopHandler;    
    void * m_runLoopHandlerParam;   
#if AR_GLOBAL_OBJECT_LISTS
    ar_list_node_t m_createdNode;   
#endif // AR_GLOBAL_OBJECT_LISTS
};

struct _ar_timer {
    const char * m_name;            
    ar_list_node_t m_activeNode;    
#if AR_GLOBAL_OBJECT_LISTS
    ar_list_node_t m_createdNode;   
#endif // AR_GLOBAL_OBJECT_LISTS
    ar_timer_entry_t m_callback;    
    void * m_param;                 
    ar_timer_mode_t m_mode;         
    bool m_isActive;            
    bool m_isRunning;           
    uint32_t m_delay;           
    uint32_t m_wakeupTime;      
    ar_runloop_t * m_runLoop;   
};

struct _ar_runloop {
    const char * m_name;                
    ar_thread_t * m_thread;             
    ar_list_t m_timers;                 
    ar_list_t m_queues;                 
    struct _ar_runloop_function_info {
        ar_runloop_function_t function; 
        void * param;                   
    } m_functions[AR_RUNLOOP_FUNCTION_QUEUE_SIZE];  
    volatile int32_t m_functionCount;   
    volatile int32_t m_functionHead;    
    volatile int32_t m_functionTail;    
    bool m_isRunning;                   
    volatile bool m_stop;               
#if AR_GLOBAL_OBJECT_LISTS
    ar_list_node_t m_createdNode;   
#endif // AR_GLOBAL_OBJECT_LISTS
};

typedef union _ar_runloop_result {
    ar_queue_t * m_queue;       
    uint32_t m_signal;          
} ar_runloop_result_t;

//------------------------------------------------------------------------------
// API
//------------------------------------------------------------------------------

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




void ar_kernel_run(void);

bool ar_kernel_is_running(void);

uint32_t ar_get_system_load(void);





ar_status_t ar_thread_create(ar_thread_t * thread, const char * name, ar_thread_entry_t entry, void * param, void * stack, unsigned stackSize, uint8_t priority, bool startImmediately);

ar_status_t ar_thread_delete(ar_thread_t * thread);

ar_status_t ar_thread_suspend(ar_thread_t * thread);

ar_status_t ar_thread_resume(ar_thread_t * thread);

ar_thread_state_t ar_thread_get_state(ar_thread_t * thread);

uint8_t ar_thread_get_priority(ar_thread_t * thread);

ar_status_t ar_thread_set_priority(ar_thread_t * thread, uint8_t newPriority);

ar_thread_t * ar_thread_get_current(void);

ar_runloop_t * ar_thread_get_runloop(ar_thread_t * thread);

void ar_thread_sleep(uint32_t milliseconds);

void ar_thread_sleep_until(uint32_t wakeup);

const char * ar_thread_get_name(ar_thread_t * thread);

uint32_t ar_thread_get_load(ar_thread_t * thread);

uint32_t ar_thread_get_stack_used(ar_thread_t * thread);

uint32_t ar_thread_get_report(ar_thread_status_t report[], uint32_t maxEntries);





ar_status_t ar_semaphore_create(ar_semaphore_t * sem, const char * name, unsigned count);

ar_status_t ar_semaphore_delete(ar_semaphore_t * sem);

ar_status_t ar_semaphore_get(ar_semaphore_t * sem, uint32_t timeout);

ar_status_t ar_semaphore_put(ar_semaphore_t * sem);

uint32_t ar_semaphore_get_count(ar_semaphore_t * sem);

const char * ar_semaphore_get_name(ar_semaphore_t * sem);





ar_status_t ar_mutex_create(ar_mutex_t * mutex, const char * name);

ar_status_t ar_mutex_delete(ar_mutex_t * mutex);

ar_status_t ar_mutex_get(ar_mutex_t * mutex, uint32_t timeout);

ar_status_t ar_mutex_put(ar_mutex_t * mutex);

bool ar_mutex_is_locked(ar_mutex_t * mutex);

ar_thread_t * ar_mutex_get_owner(ar_mutex_t * mutex);

const char * ar_mutex_get_name(ar_mutex_t * mutex);





ar_status_t ar_channel_create(ar_channel_t * channel, const char * name, uint32_t width);

ar_status_t ar_channel_delete(ar_channel_t * channel);

ar_status_t ar_channel_send(ar_channel_t * channel, const void * value, uint32_t timeout);

ar_status_t ar_channel_receive(ar_channel_t * channel, void * value, uint32_t timeout);

const char * ar_channel_get_name(ar_channel_t * channel);





ar_status_t ar_queue_create(ar_queue_t * queue, const char * name, void * storage, unsigned elementSize, unsigned capacity);

ar_status_t ar_queue_delete(ar_queue_t * queue);

ar_status_t ar_queue_send(ar_queue_t * queue, const void * element, uint32_t timeout);

ar_status_t ar_queue_receive(ar_queue_t * queue, void * element, uint32_t timeout);

bool ar_queue_is_empty(ar_queue_t * queue);

uint32_t ar_queue_get_count(ar_queue_t * queue);

const char * ar_queue_get_name(ar_queue_t * queue);





ar_status_t ar_timer_create(ar_timer_t * timer, const char * name, ar_timer_entry_t callback, void * param, ar_timer_mode_t timerMode, uint32_t delay);

ar_status_t ar_timer_delete(ar_timer_t * timer);

ar_status_t ar_timer_start(ar_timer_t * timer);

ar_status_t ar_timer_stop(ar_timer_t * timer);

bool ar_timer_is_active(ar_timer_t * timer);

ar_status_t ar_timer_set_delay(ar_timer_t * timer, uint32_t newDelay);

uint32_t ar_timer_get_delay(ar_timer_t * timer);

const char * ar_timer_get_name(ar_timer_t * timer);





ar_status_t ar_runloop_create(ar_runloop_t * runloop, const char * name);

ar_status_t ar_runloop_delete(ar_runloop_t * runloop);

ar_status_t ar_runloop_run(ar_runloop_t * runloop, uint32_t timeout, ar_runloop_result_t * object);

ar_status_t ar_runloop_stop(ar_runloop_t * runloop);

ar_status_t ar_runloop_perform(ar_runloop_t * runloop, ar_runloop_function_t function, void * param);

ar_status_t ar_runloop_signal(ar_runloop_t * runloop, uint32_t signal);

ar_status_t ar_runloop_add_timer(ar_runloop_t * runloop, ar_timer_t * timer);

ar_status_t ar_runloop_add_queue(ar_runloop_t * runloop, ar_queue_t * queue, ar_runloop_queue_handler_t callback, void * param);

ar_runloop_t * ar_runloop_get_current(void);

const char * ar_runloop_get_name(ar_runloop_t * runloop);





uint32_t ar_get_tick_count(void);

uint32_t ar_get_millisecond_count(void);

uint64_t ar_get_microseconds();

uint32_t ar_get_milliseconds_per_tick(void);

static inline uint32_t ar_ticks_to_milliseconds(uint32_t ticks) { return ticks * ar_get_milliseconds_per_tick(); }

static inline uint32_t ar_milliseconds_to_ticks(uint32_t milliseconds) { return milliseconds / ar_get_milliseconds_per_tick(); }





int8_t ar_atomic_add8(volatile int8_t * value, int8_t delta);

int16_t ar_atomic_add16(volatile int16_t * value, int16_t delta);

int32_t ar_atomic_add32(volatile int32_t * value, int32_t delta);

bool ar_atomic_cas8(volatile int8_t * value, int8_t expectedValue, int8_t newValue);

bool ar_atomic_cas16(volatile int16_t * value, int16_t expectedValue, int16_t newValue);

bool ar_atomic_cas32(volatile int32_t * value, int32_t expectedValue, int32_t newValue);


#if defined(__cplusplus)
}
#endif


#endif // _AR_KERNEL_H_
//------------------------------------------------------------------------------
// EOF
//------------------------------------------------------------------------------