TNeoKernel  v1.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Macros | Typedefs | Enumerations
tn_common.h File Reference

Detailed Description

Definitions used through the whole kernel.

Definition in file tn_common.h.

Go to the source code of this file.

Macros

#define TN_API_MAKE_ALIG_ARG__TYPE   1
 In this case, you should use macro like this: TN_MAKE_ALIG(struct my_struct). More...
 
#define TN_API_MAKE_ALIG_ARG__SIZE   2
 In this case, you should use macro like this: TN_MAKE_ALIG(sizeof(struct my_struct)). More...
 
#define NULL   ((void *)0)
 NULL pointer definition.
 
#define BOOL   int
 boolean type definition
 
#define TRUE   (1 == 1)
 true value definition for type BOOL
 
#define FALSE   (1 == 0)
 false value definition for type BOOL
 
#define TN_MAKE_ALIG_SIZE(a)   (((a) + (sizeof(TN_UWord) - 1)) & (~(sizeof(TN_UWord) - 1)))
 Macro for making a number a multiple of sizeof(TN_UWord), should be used with fixed memory block pool. More...
 
#define TN_MAKE_ALIG(a)   TN_MAKE_ALIG_SIZE(a)
 The same as TN_MAKE_ALIG_SIZE but its behavior depends on the option TN_API_MAKE_ALIG_ARG More...
 

Typedefs

typedef void( TN_TaskBody )(void *param)
 Prototype for task body function.
 
typedef unsigned long TN_Timeout
 The value representing maximum number of system ticks to wait. More...
 

Enumerations

enum  TN_ObjId {
  TN_ID_TASK = 0x47ABCF69, TN_ID_SEMAPHORE = 0x6FA173EB, TN_ID_EVENTGRP = 0x5E224F25, TN_ID_DATAQUEUE = 0x8C8A6C89,
  TN_ID_FSMEMORYPOOL = 0x26B7CE8B, TN_ID_MUTEX = 0x17129E45
}
 Magic number for object validity verification. More...
 
enum  TN_RCode {
  TN_RC_OK = 0, TN_RC_TIMEOUT = -1, TN_RC_OVERFLOW = -2, TN_RC_WCONTEXT = -3,
  TN_RC_WSTATE = -4, TN_RC_WPARAM = -5, TN_RC_ILLEGAL_USE = -6, TN_RC_INVALID_OBJ = -7,
  TN_RC_DELETED = -8, TN_RC_FORCED = -9, TN_RC_INTERNAL = -10
}
 Result code returned by kernel services. More...
 

Macro Definition Documentation

#define TN_API_MAKE_ALIG_ARG__TYPE   1

In this case, you should use macro like this: TN_MAKE_ALIG(struct my_struct).

This way is used in the majority of TNKernel ports. (actually, in all ports except the one by AlexB)

Definition at line 56 of file tn_common.h.

#define TN_API_MAKE_ALIG_ARG__SIZE   2

In this case, you should use macro like this: TN_MAKE_ALIG(sizeof(struct my_struct)).

This way is stated in TNKernel docs and used in the port for dsPIC/PIC24/PIC32 by AlexB.

Definition at line 63 of file tn_common.h.

#define TN_MAKE_ALIG_SIZE (   a)    (((a) + (sizeof(TN_UWord) - 1)) & (~(sizeof(TN_UWord) - 1)))

Macro for making a number a multiple of sizeof(TN_UWord), should be used with fixed memory block pool.

See tn_fmem_create() for usage example.

Definition at line 239 of file tn_common.h.

#define TN_MAKE_ALIG (   a)    TN_MAKE_ALIG_SIZE(a)

The same as TN_MAKE_ALIG_SIZE but its behavior depends on the option TN_API_MAKE_ALIG_ARG

Attention
it is recommended to use TN_MAKE_ALIG_SIZE macro instead of this one, in order to avoid confusion caused by various TNKernel ports: refer to the section Macro MAKE_ALIG() for details.

Definition at line 263 of file tn_common.h.

Typedef Documentation

typedef unsigned long TN_Timeout

The value representing maximum number of system ticks to wait.

Assume user called some system function, and it can't perform its job immediately (say, it needs to lock mutex but it is already locked, etc).

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.

    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:

Definition at line 203 of file tn_common.h.

Enumeration Type Documentation

enum TN_ObjId

Magic number for object validity verification.

Enumerator
TN_ID_TASK 

id for tasks

TN_ID_SEMAPHORE 

id for semaphores

TN_ID_EVENTGRP 

id for event groups

TN_ID_DATAQUEUE 

id for data queues

TN_ID_FSMEMORYPOOL 

id for fixed memory pools

TN_ID_MUTEX 

id for mutexes

Definition at line 87 of file tn_common.h.

enum TN_RCode

Result code returned by kernel services.

Enumerator
TN_RC_OK 

Successful operation.

TN_RC_TIMEOUT 

Timeout (consult TN_Timeout for details).

See also
TN_Timeout
TN_RC_OVERFLOW 

This code is returned in the following cases:

  • Trying to increment semaphore count more than its max count;
  • Trying to return extra memory block to fixed memory pool.
    See also
    tn_sem.h
    tn_fmem.h
TN_RC_WCONTEXT 

Wrong context error: returned if function is called from non-acceptable context.

Required context suggested for every function by badges:

  • attr_call_task.png
    - function can be called from task;
  • attr_call_int.png
    - function can be called from ISR.
See also
tn_sys_context_get()
enum TN_Context
TN_RC_WSTATE 

Wrong task state error: requested operation requires different task state.

TN_RC_WPARAM 

This code is returned by most of the kernel functions when wrong params were given to function.

This error code can be returned if only build-time option TN_CHECK_PARAM is non-zero

See also
TN_CHECK_PARAM
TN_RC_ILLEGAL_USE 

Illegal usage.

Returned in the following cases:

  • task tries to unlock or delete the mutex that is locked by different task,
  • task tries to lock mutex with priority ceiling whose priority is lower than task's priority
    See also
    tn_mutex.h
TN_RC_INVALID_OBJ 

Returned when user tries to perform some operation on invalid object (mutex, semaphore, etc).

Object validity is checked by comparing special id_... field value with the value from enum TN_ObjId

See also
TN_CHECK_PARAM
TN_RC_DELETED 

Object for whose event task was waiting is deleted.

TN_RC_FORCED 

Task was released from waiting forcibly because some other task called tn_task_release_wait()

TN_RC_INTERNAL 

Internal kernel error, should never be returned by kernel services.

If it is returned, it's a bug in the kernel.

Definition at line 99 of file tn_common.h.