More documentation and minor refactoring.
authorAnselm Busse <anselm.busse@tu-berlin.de>
Tue, 26 Jan 2016 18:27:01 +0000 (19:27 +0100)
committerAnselm Busse <anselm.busse@tu-berlin.de>
Tue, 26 Jan 2016 18:27:01 +0000 (19:27 +0100)
16 files changed:
framework/include/fw_comm.h
framework/include/fw_debug.h
framework/include/fw_irq.h
framework/include/fw_limits.h
framework/include/fw_list.h
framework/include/fw_lock.h
framework/include/fw_modules.h
framework/include/fw_task.h
framework/lib/fw_comm.c
framework/lib/fw_dispatch.c [deleted file]
framework/lib/fw_irq.c
framework/lib/fw_list.c
framework/lib/fw_lock.c
framework/lib/fw_modules.c
framework/os/freebsd/fbsd_sched.c
framework/os/linux/os_lock.c

index 2e47868..e5ad0b3 100644 (file)
@@ -1,3 +1,12 @@
+/**
+ * @file fw_comm.h
+ * @author Anselm Busse
+ * @date 25 Jan 2015
+ *
+ * This file contains the interface description for the CoBaS communication
+ * subsystem.
+ */
+
 #ifndef FW_COMM_H_
 #define FW_COMM_H_
 
index 99220b4..f428635 100644 (file)
@@ -1,8 +1,8 @@
 #ifndef FW_DEBUG_H_
 #define FW_DEBUG_H_
 
-//#include <debug/fw_detect.h>
-//#include <debug/fw_break.h>
+#include <debug/fw_detect.h>
+#include <debug/fw_break.h>
 
 #define FW_DEBUG 1
 
@@ -22,4 +22,11 @@ void __fw_assert(const char *cond, const char *file, int line);
 
 #endif /* FW_DEBUG */
 
+/**
+ * Checks if a lock is locked. Note that this call is *NOT* safe!
+ *
+ * @param lock The lock to check.
+ */
+#define FW_IS_LOCKED(ptr) ((*ptr).raw_lock.slock == FW_SPINLOCK_LOCKED.slock)
+
 #endif /* FW_DEBUG_H_ */
index 1797cad..85d3687 100644 (file)
@@ -1,8 +1,10 @@
-/*
- * fw_irq.h
+/**
+ * @file fw_comm.h
+ * @author Anselm Busse
+ * @date 25 Jan 2015
  *
- *  Created on: 14.09.2015
- *      Author: abusse
+ * This file contains the interface description for the CoBaS interrupt control
+ * subsystem.
  */
 
 #ifndef _FW_IRQ_H_
 
 #include <os_irq.h>
 
+/**
+ * This type maps the generic CoBaS interrupt flags to the operating system
+ * specific ones
+ */
 #define fw_irq_flags os_irq_flags
 
+/**
+ * Disables the interrupts of the current processing element.
+ */
 inline void fw_local_irq_disable(void);
 
+/**
+ * Enables the interrupts of the current processing element.
+ */
 inline void fw_local_irq_enable(void);
 
+/**
+ * Disables the interrupts of the current processing element and safes the
+ * current interrupt flags. As this function is inlined the <code>flags</code>
+ * parameter does not have to be a pointer.
+ *
+ * @param flags The variable to write the interrupt flags to.
+ */
 inline void fw_local_irq_save(fw_irq_flags flags);
 
+/**
+ * Eneables the interupts of the current processing element and restores the
+ * interrupt flags as given.
+ *
+ * @param flags The intrrupt flags that should be restored.
+ */
 inline void fw_local_irq_restore(fw_irq_flags flags);
 
 
index 8159a28..573a8e7 100644 (file)
@@ -1,17 +1,31 @@
-/*
- * fw_limits.h
+/**
+ * @file fw_limits.h
+ * @author Anselm Busse
+ * @date 25 Jan 2015
  *
- *  Created on: 14.09.2015
- *      Author: abusse
+ * This files defines some limiting values for the CoBaS framework.
  */
-
 #ifndef _FW_LIMITS_H_
 #define _FW_LIMITS_H_
 
-#define FW_MAX_MODULE_ID 0x10
-#define FW_MAX_MODULES 16
-#define FW_MAX_MODULES_INST 32
+/**
+ * The maximum number of components
+ */
+#define FW_MAX_COMPONENT 0x20
+
+/**
+ * The highest possible component ID
+ */
+#define FW_MAX_COMPONENT_ID 0x20
 
+/**
+ * The maximum number of component instances.
+ */
+#define FW_MAX_COMPONENT_INST 128
+
+/**
+ * The maximum number of pipes.
+ */
 #define FW_MAX_PIPES 32
 
 #endif /* _FW_LIMITS_H_ */
index 1062327..87cac05 100644 (file)
@@ -1,12 +1,6 @@
 #ifndef _FW_LIST_H
 #define _FW_LIST_H
 
-/*  Created on:23.07.2013
- *     Authors: Christian Rene Sechting, Daniel Roehrig
- *
- */
-
-
 #define FW_LIST_POISON1  ((void *) 0x00100100)
 #define FW_LIST_POISON2  ((void *) 0x00200200)
 
index e7325d7..eb3d57f 100644 (file)
-/*
- * fw_lock.h
+/**
+ * @file fw_lock.h
+ * @author Anselm Busse
+ * @date 25 Jan 2015
  *
- *  Created on: 29.01.2014
- *      Author: jkrieg
+ * This file contains the interface description for the CoBaS locking
+ * subsystem.
  */
 
 #ifndef FW_LOCK_H_
 #define FW_LOCK_H_
 
 #include <fw_irq.h>
+#include <os.h>
 
-
+/**
+ * Definition of a locked spinlock in CoBaS
+ */
 #define FW_SPINLOCK_LOCKED (fw_raw_spinlock_t) {1}
+/**
+ * Definition of an ulocked spinlock in CoBaS
+ */
 #define FW_SPINLOCK_UNLOCKED (fw_raw_spinlock_t) {0}
+/**
+ * Creates an unlocked spinlock with the given name.
+ */
 #define FW_SPINLOCK_CREATE(name) fw_spinlock_t name = {{0}}
 
-
+/**
+ * Definition of the content of a raw spinlock.
+ */
 typedef struct {
-       volatile unsigned int slock;
+       volatile unsigned int slock;    /**< Te lock variable */
 } fw_raw_spinlock_t;
 
+/**
+ * Definition of a spinlock in CoBaS
+ */
 typedef struct {
        fw_raw_spinlock_t raw_lock;
 } fw_spinlock_t;
 
-#define FW_IS_LOCKED(ptr) ((*ptr).raw_lock.slock == FW_SPINLOCK_LOCKED.slock)
-
-
+/**
+ * \brief Locks the given spinlock.
+ *
+ * This function locks the given spinlock and will spin until it is capable to
+ * do so.
+ *
+ * @param lock The lock to operate on.
+ */
 void fw_spinlock(fw_spinlock_t *lock);
 
+/**
+ * \brief Unlocks the given spinlock.
+ *
+ * This function unlocks the given spinlock.
+ *
+ * @param lock The lock to operate on.
+ */
 void fw_spinunlock(fw_spinlock_t *lock);
 
+/**
+ * \brief Locks the given spinlock and disables interrupts.
+ *
+ * This function locks the given spinlock and disables the interrupts. It will
+ * spin until capable to do so.
+ *
+ * @param lock The lock to operate on.
+ */
 void fw_spinlock_irq(fw_spinlock_t *lock);
 
+/**
+ * \brief Unlocks the given spinlock and enables the interrupts
+ *
+ * This function unlocks the given spinlock and enables the interrupts.
+ *
+ * @param lock The lock to operate on.
+ */
 void fw_spinunlock_irq(fw_spinlock_t *lock);
 
+/**
+ * \brief Locks the given spinlock, disables interrupts and save the interrupt
+ * state
+ *
+ * This function locks the given spinlock, disables the interrupts and safe the
+ * interrupt states. It willbspin until capable to do so.
+ *
+ * @param lock The lock to operate on.
+ */
 void fw_spinlock_irqsave(fw_spinlock_t *lock, fw_irq_flags *flags);
 
+/**
+ * \brief Unlocks the given spinlock, enables the interrupts and restores the
+ * interrupt states.
+ *
+ * This function unlocks the given spinlock, enables the interrupts and restores
+ * the interrupt states
+ *
+ * @param lock The lock to operate on.
+ * @param flags The flags to restore.
+ */
 void fw_spinunlock_irqrestore(fw_spinlock_t *lock, fw_irq_flags *flags);
 
 #endif /* FW_LOCK_H_ */
index 764cb2c..ab6d738 100644 (file)
@@ -1,3 +1,11 @@
+/**
+ * @file fw_comm.h
+ * @author Anselm Busse
+ * @date 25 Jan 2015
+ *
+ * This file contains the interface description for the CoBaS component system.
+ */
+
 #ifndef FW_MODULES_H_
 #define FW_MODULES_H_
 
@@ -44,9 +52,9 @@ typedef struct fw_component {
                __attribute__ ((__used__)) \
                __attribute__ ((__section__(".fw.modules.init"))) = fn
 
-extern const char *fw_modules_names[FW_MAX_MODULE_ID];
-extern fw_module_operations_t *fw_modules_operations[FW_MAX_MODULE_ID];
-extern void *fw_modules_private_data[FW_MAX_MODULES];
+extern const char *fw_modules_names[FW_MAX_COMPONENT_ID];
+extern fw_module_operations_t *fw_modules_operations[FW_MAX_COMPONENT_ID];
+extern void *fw_modules_private_data[FW_MAX_COMPONENT];
 
 void fw_modules_init(void);
 
index cad8a9d..fedaf0b 100644 (file)
@@ -26,7 +26,7 @@ typedef struct fw_task {
        unsigned int cpu;
        task_context_t *task_context;
        fw_pipe_pcb_t pipe_pcb[FW_MAX_PIPES];
-       void *component_pcb[FW_MAX_MODULES_INST];
+       void *component_pcb[FW_MAX_COMPONENT_INST];
 } fw_task_t;
 
 #endif /* FW_TASK_H_ */
index 6bf0d21..557e322 100644 (file)
@@ -2,7 +2,6 @@
  * @file fw_comm.c
  * @author Anselm Busse
  * @date 25 Jan 2015
- * @brief File containing CoBaS communication functions.
  *
  * CoBaS uses a publish subscribe based communication pattern. This file
  * contains all the functionality to realize that.
diff --git a/framework/lib/fw_dispatch.c b/framework/lib/fw_dispatch.c
deleted file mode 100644 (file)
index 1ca7137..0000000
+++ /dev/null
@@ -1,20 +0,0 @@
-/*FW
- * NAME: dispatch
- * INPUT: fw_dispatch_tasks
- */
-
-
-#include <fw.h>
-
-
-extern fw_task_list_t *fs_dispatch_tasks;
-
-int fw_dispatch_init(int id){
-
-}
-
-fw_module_t fw_dispatch_module = {
-               .init = fw_dispatch_init
-};
-
-
index addb1ae..3ca504a 100644 (file)
@@ -1,8 +1,9 @@
-/*
- * fw_irq.c
+/**
+ * @file fw_irq.c
+ * @author Anselm Busse
+ * @date 25 Jan 2015
  *
- *  Created on: 14.09.2015
- *      Author: abusse
+ * Control function for the interrupts of processing elements.
  */
 
 #include <fw_irq.h>
index 4816d8f..d810f99 100644 (file)
@@ -1,9 +1,5 @@
 #include "fw.h"
 
-/*
- *     ALL LIST FUNCTIONALITIES
- */
-
 void fw_tlist_init(struct fw_tlist *list)
 {
        list->head = list->tail = NULL;
index 45d2cab..b837bdb 100644 (file)
@@ -1,13 +1,13 @@
-/*
- * fw_lock.c
+/**
+ * @file fw_lock.c
+ * @author Anselm Busse
+ * @date 25 Jan 2015
  *
- *  Created on: 29.01.2014
- *      Author: jkrieg
+ * This file contains the implementations of locks in CoBaS. They are mostly
+ * wrappers around the OS specific functions.
  */
 
-#include "fw.h"
-
-
+#include <fw_lock.h>
 
 void fw_spinlock(fw_spinlock_t *lock)
 {
index ae9cef2..d1f07e6 100644 (file)
@@ -2,9 +2,9 @@
 
 
 
-const char *fw_modules_names[FW_MAX_MODULES];
-fw_module_operations_t *fw_modules_operations[FW_MAX_MODULES];
-void *fw_modules_private_data[FW_MAX_MODULES];
+const char *fw_modules_names[FW_MAX_COMPONENT];
+fw_module_operations_t *fw_modules_operations[FW_MAX_COMPONENT];
+void *fw_modules_private_data[FW_MAX_COMPONENT];
 
 unsigned int registered_modules = 0;
 
@@ -17,7 +17,7 @@ void fw_modules_init(void)
        fw_initcall_t *call;
 
 
-       for (i=0; i<FW_MAX_MODULE_ID; i++) {
+       for (i=0; i<FW_MAX_COMPONENT_ID; i++) {
                fw_modules_operations[i] = NULL;
                fw_modules_names[i] = "N/A";
        }
@@ -31,7 +31,7 @@ void fw_modules_init(void)
 
 int fw_modules_register(int uuid, const char *module_name, fw_module_operations_t *operations)
 {
-       if (!module_name || uuid > FW_MAX_MODULE_ID) {
+       if (!module_name || uuid > FW_MAX_COMPONENT_ID) {
                return -1;
        }
 
index e8e5644..bfd81fa 100644 (file)
@@ -670,7 +670,7 @@ void sched_fork_thread(struct thread *td, struct thread *child)
        ts2->fw_task->state = FW_READY;
        ts2->fw_task->cpu = ts->ts_cpu;
        /* So far module_data is uninitialized. Free will only check against Zero. */
-       for(i=0; i<=FW_MAX_MODULES; i++)
+       for(i=0; i<=FW_MAX_COMPONENT; i++)
                ts2->fw_task->module_data[i] = 0;
 
 #ifdef KTR
index aee06f2..b67c81c 100644 (file)
@@ -1,13 +1,7 @@
-/*
- * lock.c
- *
- *  Created on: 10.12.2013
- *      Author: jkrieg
- */
-
-#include "fw.h"
 
 
+#include <fw_lock.h>
+#include <os.h>
 
 void os_spinlock(fw_spinlock_t *lock)
 {