TNeo  BETA v1.08-11-g97e5a6d
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_NULL   ((void *)0)
 NULL pointer definition.
 
#define TN_BOOL   int
 boolean type definition
 
#define TN_TRUE   (1 == 1)
 true value definition for type TN_BOOL
 
#define TN_FALSE   (1 == 0)
 false value definition for type TN_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...
 
#define _TN_UNUSED(x)   (void)(x)
 Suppresses "unused" compiler warning for some particular symbol.
 
#define _TN_FATAL_ERROR(error_msg)   _TN_FATAL_ERRORF(error_msg, NULL)
 

Typedefs

typedef void() TN_TaskBody(void *param)
 Prototype for task body function.
 
typedef unsigned long TN_TickCnt
 Type for system tick count, it is used by the kernel to represent absolute tick count value as well as relative timeouts. More...
 

Enumerations

enum  TN_ObjId {
  TN_ID_NONE = (int)0x0, TN_ID_TASK = (int)0x47ABCF69, TN_ID_SEMAPHORE = (int)0x6FA173EB, TN_ID_EVENTGRP = (int)0x5E224F25,
  TN_ID_DATAQUEUE = (int)0x0C8A6C89, TN_ID_FSMEMORYPOOL = (int)0x26B7CE8B, TN_ID_MUTEX = (int)0x17129E45, TN_ID_TIMER = (int)0x1A937FBC,
  TN_ID_EXCHANGE = (int)0x32b7c072, TN_ID_EXCHANGE_LINK = (int)0x24d36f35
}
 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

◆ TN_MAKE_ALIG_SIZE

#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 231 of file tn_common.h.

◆ TN_MAKE_ALIG

#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 255 of file tn_common.h.

Typedef Documentation

◆ TN_TickCnt

typedef unsigned long TN_TickCnt

Type for system tick count, it is used by the kernel to represent absolute tick count value as well as relative timeouts.

When it is used as a timeout value, it represents the 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 188 of file tn_common.h.

Enumeration Type Documentation

◆ TN_ObjId

enum TN_ObjId

Magic number for object validity verification.

Enumerator
TN_ID_NONE 

id for invalid object

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

TN_ID_TIMER 

id for timers

TN_ID_EXCHANGE 

id for exchange objects

TN_ID_EXCHANGE_LINK 

id for exchange link

Definition at line 65 of file tn_common.h.

◆ TN_RCode

enum TN_RCode

Result code returned by kernel services.

Enumerator
TN_RC_OK 

Successful operation.

TN_RC_TIMEOUT 

Timeout (consult TN_TickCnt for details).

See also
TN_TickCnt
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 81 of file tn_common.h.