merge default into stable for release v1.02

examples/examples_readme!!!.txt

@@ -1,6 +1,6 @@
 
 Before trying to build examples, please read the following page carefully:
-http://dfrank.bitbucket.org/tneokernel_api/html/building.html
+http://dfrank.bitbucket.org/tneokernel_api/latest/html/building.html
 
 In short, you need to copy configuration file in the tneokernel directory to
 build it.  Each example has `tn_cfg_appl.h` file, and you should either create

examples/pic32/basic/tn_pic32_example_basic.X/nbproject/configurations.xml

@@ -33,7 +33,7 @@
         <targetDevice>PIC32MX440F512H</targetDevice>
         <targetHeader></targetHeader>
         <targetPluginBoard></targetPluginBoard>
-        <platformTool>PICkit3PlatformTool</platformTool>
+        <platformTool>ICD3PlatformTool</platformTool>
         <languageToolchain>XC32</languageToolchain>
         <languageToolchainVersion>1.21</languageToolchainVersion>
         <platform>2</platform>

src/arch/pic32/tn_arch_pic32.c

@@ -75,12 +75,12 @@ extern unsigned long _gp;
 //      SP + 00 lo
 //----------------------------------------------------------------------------
 
-TN_UWord *_tn_arch_stack_start_get(
+TN_UWord *_tn_arch_stack_top_get(
       TN_UWord *stack_low_address,
       int stack_size
       )
 {
-   return stack_low_address + stack_size - 1;
+   return stack_low_address + stack_size;
 }
 
 
@@ -91,53 +91,49 @@ TN_UWord *_tn_arch_stack_start_get(
 //----------------------------------------------------------------------------
 unsigned int *_tn_arch_stack_init(
       TN_TaskBody *task_func,
-      TN_UWord *stack_start,
+      TN_UWord *stack_top,
       void *param
       )
 {
-   unsigned int *p_stk;
-
    //-- filling register's position in the stack - for debugging only
+   *(--stack_top) = 0;                          //-- ABI argument area
+   *(--stack_top) = 0;
+   *(--stack_top) = 0;
+   *(--stack_top) = 0;
+   *(--stack_top) = (unsigned int)task_func;    //-- EPC
+   *(--stack_top) = 3;                          //-- Status: EXL and IE bits are set
+   *(--stack_top) = (unsigned int)tn_task_exit; //-- ra
+   *(--stack_top) = 0x30303030L;                //-- fp
+   *(--stack_top) = (unsigned int)&_gp;         //-- gp - provided by linker
+   *(--stack_top) = 0x25252525L;                //-- t9
+   *(--stack_top) = 0x24242424L;                //-- t8
+   *(--stack_top) = 0x23232323L;                //-- s7
+   *(--stack_top) = 0x22222222L;                //-- s6
+   *(--stack_top) = 0x21212121L;                //-- s5
+   *(--stack_top) = 0x20202020L;                //-- s4
+   *(--stack_top) = 0x19191919L;                //-- s3
+   *(--stack_top) = 0x18181818L;                //-- s2
+   *(--stack_top) = 0x17171717L;                //-- s1
+   *(--stack_top) = 0x16161616L;                //-- s0
+   *(--stack_top) = 0x15151515L;                //-- t7
+   *(--stack_top) = 0x14141414L;                //-- t6
+   *(--stack_top) = 0x13131313L;                //-- t5
+   *(--stack_top) = 0x12121212L;                //-- t4
+   *(--stack_top) = 0x11111111L;                //-- t3
+   *(--stack_top) = 0x10101010L;                //-- t2
+   *(--stack_top) = 0x09090909L;                //-- t1
+   *(--stack_top) = 0x08080808L;                //-- t0
+   *(--stack_top) = 0x07070707L;                //-- a3
+   *(--stack_top) = 0x06060606L;                //-- a2
+   *(--stack_top) = 0x05050505L;                //-- a1
+   *(--stack_top) = (unsigned int)param;        //-- a0 - task's function argument
+   *(--stack_top) = 0x03030303L;                //-- v1
+   *(--stack_top) = 0x02020202L;                //-- v0
+   *(--stack_top) = 0x01010101L;                //-- at
+   *(--stack_top) = 0x33333333L;                //-- hi
+   *(--stack_top) = 0x32323232L;                //-- lo
 
-   p_stk  = (unsigned int *)stack_start;     //-- Load stack pointer
-   *p_stk-- = 0;                             //-- ABI argument area
-   *p_stk-- = 0;
-   *p_stk-- = 0;
-   *p_stk-- = 0;
-   *p_stk-- = (unsigned int)task_func;       //-- EPC
-   *p_stk-- = 3;                             //-- Status: EXL and IE bits are set
-   *p_stk-- = (unsigned int)tn_task_exit;    //-- ra
-   *p_stk-- = 0x30303030L;                   //-- fp
-   *p_stk-- = (unsigned int)&_gp;            //-- gp - provided by linker
-   *p_stk-- = 0x25252525L;                   //-- t9
-   *p_stk-- = 0x24242424L;                   //-- t8
-   *p_stk-- = 0x23232323L;                   //-- s7
-   *p_stk-- = 0x22222222L;                   //-- s6
-   *p_stk-- = 0x21212121L;                   //-- s5
-   *p_stk-- = 0x20202020L;                   //-- s4
-   *p_stk-- = 0x19191919L;                   //-- s3
-   *p_stk-- = 0x18181818L;                   //-- s2
-   *p_stk-- = 0x17171717L;                   //-- s1
-   *p_stk-- = 0x16161616L;                   //-- s0
-   *p_stk-- = 0x15151515L;                   //-- t7
-   *p_stk-- = 0x14141414L;                   //-- t6
-   *p_stk-- = 0x13131313L;                   //-- t5
-   *p_stk-- = 0x12121212L;                   //-- t4
-   *p_stk-- = 0x11111111L;                   //-- t3
-   *p_stk-- = 0x10101010L;                   //-- t2
-   *p_stk-- = 0x09090909L;                   //-- t1
-   *p_stk-- = 0x08080808L;                   //-- t0
-   *p_stk-- = 0x07070707L;                   //-- a3
-   *p_stk-- = 0x06060606L;                   //-- a2
-   *p_stk-- = 0x05050505L;                   //-- a1
-   *p_stk-- = (unsigned int)param;           //-- a0 - task's function argument
-   *p_stk-- = 0x03030303L;                   //-- v1
-   *p_stk-- = 0x02020202L;                   //-- v0
-   *p_stk-- = 0x01010101L;                   //-- at
-   *p_stk-- = 0x33333333L;                   //-- hi
-   *p_stk = 0x32323232L;                     //-- lo
-
-   return p_stk;
+   return stack_top;
 }
 
 //_____________________________________________________________________________

src/arch/pic32/tn_arch_pic32.h

@@ -207,10 +207,15 @@ typedef  unsigned int               TN_UWord;
 
 #ifdef __mips16
 #  define TN_INT_DIS_SAVE()   tn_save_status_reg = tn_arch_sr_save_int_dis()
-#  define TN_INT_RESTORE()    _TN_PIC32_INTSAVE_CHECK(); tn_arch_sr_restore(tn_save_status_reg)
+#  define TN_INT_RESTORE()    _TN_PIC32_INTSAVE_CHECK();                      \
+                              tn_arch_sr_restore(tn_save_status_reg)
 #else
-#  define TN_INT_DIS_SAVE()   __asm__ __volatile__("di %0; ehb" : "=d" (tn_save_status_reg))
-#  define TN_INT_RESTORE()    _TN_PIC32_INTSAVE_CHECK(); __builtin_mtc0(12, 0, tn_save_status_reg)
+#  define TN_INT_DIS_SAVE()   __asm__ __volatile__(                           \
+                                    "di %0; ehb"                              \
+                                    : "=d" (tn_save_status_reg)               \
+                                    )
+#  define TN_INT_RESTORE()    _TN_PIC32_INTSAVE_CHECK();                      \
+                              __builtin_mtc0(12, 0, tn_save_status_reg)
 #endif
 
 /**

src/arch/pic32/tneokernel.X/nbproject/configurations.xml

@@ -27,6 +27,7 @@
         <itemPath>../../../core/tn_list.c</itemPath>
         <itemPath>../../../core/tn_eventgrp.c</itemPath>
         <itemPath>../../../core/tn_fmem.c</itemPath>
+        <itemPath>../../../core/tn_timer.c</itemPath>
       </logicalFolder>
     </logicalFolder>
     <logicalFolder name="ExternalFiles"

src/arch/tn_arch.h

@@ -105,13 +105,22 @@ void tn_arch_sr_restore(unsigned int sr);
 
 
 /**
- * Should return start stack address, which may be either the lowest address of
- * the stack array or the highest one, depending on the architecture.
+ * Should return top of the stack, which may be either:
  *
- * @param   stack_low_address    start address of the stack array.
- * @param   stack_size           size of the stack in `int`-s, not in bytes.
+ * - `(stack_low_address - 1)`
+ * - `(stack_low_address + stack_size)`
+ *
+ * (depending on the architecture)
+ *
+ * **NOTE** that returned *top of the stack* is NOT the address which may be
+ * used for storing the new data. Instead, it is the *previous* address.
+ *
+ * @param   stack_low_address
+ *    start address of the stack array.
+ * @param   stack_size
+ *    size of the stack in `#TN_UWord`-s, not in bytes.
  */
-TN_UWord *_tn_arch_stack_start_get(
+TN_UWord *_tn_arch_stack_top_get(
       TN_UWord *stack_low_address,
       int stack_size
       );
@@ -121,16 +130,16 @@ TN_UWord *_tn_arch_stack_start_get(
  *
  * @param task_func
  *    Pointer to task body function.
- * @param stack_start
- *    Start address of the stack, returned by `_tn_arch_stack_start_get()`.
+ * @param stack_top
+ *    Top of the stack, returned by `_tn_arch_stack_top_get()`.
  * @param param
  *    User-provided parameter for task body function.
  *
  * @return current stack pointer (top of the stack)
  */
 unsigned int *_tn_arch_stack_init(
       TN_TaskBody   *task_func,
-      TN_UWord      *stack_start,
+      TN_UWord      *stack_top,
       void          *param
       );
 

src/core/tn_common.h

@@ -91,6 +91,7 @@ enum TN_ObjId {
    TN_ID_DATAQUEUE      = 0x8C8A6C89,  //!< id for data queues
    TN_ID_FSMEMORYPOOL   = 0x26B7CE8B,  //!< id for fixed memory pools
    TN_ID_MUTEX          = 0x17129E45,  //!< id for mutexes
+   TN_ID_TIMER          = 0x9A937FBC,  //!< id for timers
 };
 
 /**
@@ -172,33 +173,32 @@ typedef void (TN_TaskBody)(void *param);
  * So, function can wait or return an error. There are possible `timeout`
  * values and appropriate behavior of the function:
  *
- *    * `timeout` is set to `0`: function doesn't wait at all, no context switch is performed,
- *      `#TN_RC_TIMEOUT` is returned immediately.
- *    * `timeout` is set to `#TN_WAIT_INFINITE`: function waits until it eventually **can** perform
- *      its job. Timeout is not taken in account, so `#TN_RC_TIMEOUT`
- *      is never returned.
- *    * `timeout` is set to other value: function waits at most specified number of system ticks.
- *      Strictly speaking, it waits from `(timeout - 1)` to `timeout` ticks. So, if
- *      you specify that timeout is 1, be aware that it might actually don't
- *      wait at all: if system timer interrupt happens just while function is
- *      putting task to wait (with interrupts disabled), then ISR will be
- *      executed right after function puts task to wait. Then
- *      `tn_tick_int_processing()` will immediately remove the task from wait
- *      queue and make it runnable again.
+ * - `timeout` is set to `0`: function doesn't wait at all, no context switch
+ *   is performed, `#TN_RC_TIMEOUT` is returned immediately.
+ * - `timeout` is set to `#TN_WAIT_INFINITE`: function waits until it
+ *   eventually **can** perform its job. Timeout is not taken in account, so
+ *   `#TN_RC_TIMEOUT` is never returned.
+ * - `timeout` is set to other value: function waits at most specified number
+ *   of system ticks.  Strictly speaking, it waits from `(timeout - 1)` to
+ *   `timeout` ticks. So, if you specify that timeout is 1, be aware that it
+ *   might actually don't wait at all: if $(TN_SYS_TIMER_LINK) interrupt
+ *   happens just while function is putting task to wait (with interrupts
+ *   disabled), then ISR will be executed right after function puts task to
+ *   wait. Then `tn_tick_int_processing()` will immediately remove the task
+ *   from wait queue and make it runnable again.
  *
- *      So, to guarantee that task waits *at least* 1 system tick,
- *      you should specify timeout value of `2`.
+ *      So, to guarantee that task waits *at least* 1 system tick, you should
+ *      specify timeout value of `2`.
  *
  * **Note** also that there are other possible ways to make task runnable:
  *
- *    * if task waits because of call to `tn_task_sleep()`, it may be woken up
- *      by some other task, by means of `tn_task_wakeup()`. In this case,
- *      `tn_task_sleep()` returns `#TN_RC_OK`.  
- *    * independently of the wait reason, task may be released from wait
- *      forcibly, by means of `tn_task_release_wait()`. It this case,
- *      `#TN_RC_FORCED` is returned by the waiting function.
- *      (the usage of the `tn_task_release_wait()` function is discouraged
- *      though)
+ * - if task waits because of call to `tn_task_sleep()`, it may be woken up by
+ *   some other task, by means of `tn_task_wakeup()`. In this case,
+ *   `tn_task_sleep()` returns `#TN_RC_OK`.  
+ * - independently of the wait reason, task may be released from wait forcibly,
+ *   by means of `tn_task_release_wait()`. It this case, `#TN_RC_FORCED` is
+ *   returned by the waiting function.  (the usage of the
+ *   `tn_task_release_wait()` function is discouraged though)
  */
 typedef unsigned long TN_Timeout;
 

src/core/tn_dqueue.c

@@ -281,7 +281,7 @@ static enum TN_RCode _dqueue_job_perform(
       struct TN_DQueue *dque,
       enum _JobType job_type,
       void *p_data,
-      unsigned long timeout
+      TN_Timeout timeout
       )
 {
    TN_INTSAVE_DATA;