Detailed Description

TNeo default configuration file, to be copied as tn_cfg.h.

This project is intended to be built as a library, separately from main project (although nothing prevents you from bundling things together, if you want to).

There are various options available which affects API and behavior of the kernel. But these options are specific for particular project, and aren't related to the kernel itself, so we need to keep them separately.

To this end, file tn.h (the main kernel header file) includes tn_cfg.h, which isn't included in the repository (even more, it is added to .hgignore list actually). Instead, default configuration file tn_cfg_default.h is provided, and when you just cloned the repository, you might want to copy it as tn_cfg.h. Or even better, if your filesystem supports symbolic links, copy it somewhere to your main project's directory (so that you can add it to your VCS there), and create symlink to it named tn_cfg.h in the TNeo source directory, like this:

$ cd /path/to/tneo/src
$ cp ./tn_cfg_default.h /path/to/main/project/lib_cfg/tn_cfg.h
$ ln -s /path/to/main/project/lib_cfg/tn_cfg.h ./tn_cfg.h

Default configuration file contains detailed comments, so you can read them and configure behavior as you like.

Definition in file tn_cfg_default.h.

Go to the source code of this file.

Macros
#define	TN_CHECK_BUILD_CFG 1
	This option enables run-time check which ensures that build-time options for the kernel match ones for the application. More...

#define	TN_PRIORITIES_CNT TN_PRIORITIES_MAX_CNT
	Number of priorities that can be used by application, plus one for idle task (which has the lowest priority). More...

#define	TN_CHECK_PARAM 1
	Enables additional param checking for most of the system functions. More...

#define	TN_DEBUG 0
	Allows additional internal self-checking, useful to catch internal TNeo bugs as well as illegal kernel usage (e.g. More...

#define	TN_OLD_TNKERNEL_NAMES 1
	Whether old TNKernel names (definitions, functions, etc) should be available. More...

#define	TN_USE_MUTEXES 1
	Whether mutexes API should be available.

#define	TN_MUTEX_REC 1
	Whether mutexes should allow recursive locking/unlocking.

#define	TN_MUTEX_DEADLOCK_DETECT 1
	Whether RTOS should detect deadlocks and notify user about them via callback. More...

#define	TN_TICK_LISTS_CNT 8
	Takes effect if only `TN_DYNAMIC_TICK` is not set. More...

#define	TN_API_MAKE_ALIG_ARG TN_API_MAKE_ALIG_ARG__SIZE
	API option for `MAKE_ALIG()` macro. More...

#define	TN_PROFILER 0
	Whether profiler functionality should be enabled. More...

#define	TN_PROFILER_WAIT_TIME 0
	Whether profiler should store wait time for each wait reason. More...

#define	TN_INIT_INTERRUPT_STACK_SPACE 1
	Whether interrupt stack space should be initialized with `TN_FILL_STACK_VAL` on system start. More...

#define	TN_STACK_OVERFLOW_CHECK 1
	Whether software stack overflow check is enabled. More...

#define	TN_DYNAMIC_TICK 0
	Whether the kernel should use Dynamic tick scheme instead of Static tick.

#define	TN_OLD_EVENT_API 0
	Whether the old TNKernel events API compatibility mode is active. More...

#define	TN_P24_SYS_IPL 4
	Maximum system interrupt priority. More...

Macro Definition Documentation

#define TN_CHECK_BUILD_CFG 1

This option enables run-time check which ensures that build-time options for the kernel match ones for the application.

Without this check, it is possible that you change your tn_cfg.h file, and just rebuild your application without rebuilding the kernel. Then, application would assume that kernel behaves accordingly to tn_cfg.h which was included in the application, but this is actually not true: you need to rebuild the kernel for changes to take effect.

With this option turned on, if build-time configurations don't match, you will get run-time error (_TN_FATAL_ERROR()) inside tn_sys_start(), which is much more informative than weird bugs caused by configuration mismatch.

Note: turning this option on makes sense if only you use TNeo as a separate library. If you build TNeo together with the application, both the kernel and the application always use the same tn_cfg.h file, therefore this option is useless.

Attention: If this option is on, your application must include the file tn_app_check.c.

Definition at line 107 of file tn_cfg_default.h.

#define TN_PRIORITIES_CNT TN_PRIORITIES_MAX_CNT

Number of priorities that can be used by application, plus one for idle task (which has the lowest priority).

This value can't be higher than architecture-dependent value TN_PRIORITIES_MAX_CNT, which typically equals to width of int type. So, for 32-bit systems, max number of priorities is 32.

But usually, application needs much less: I can imagine at most 4-5 different priorities, plus one for the idle task.

Do note also that each possible priority level takes RAM: two pointers for linked list and one short for time slice value, so on 32-bit system it takes 10 bytes. So, with default value of 32 priorities available, it takes 320 bytes. If you set it, say, to 5, you save 270 bytes, which might be notable.

Default: TN_PRIORITIES_MAX_CNT.

Definition at line 130 of file tn_cfg_default.h.

#define TN_CHECK_PARAM 1

Enables additional param checking for most of the system functions.

It's surely useful for debug, but probably better to remove in release. If it is set, most of the system functions are able to return two additional codes:

TN_RC_WPARAM if wrong params were given;
TN_RC_INVALID_OBJ if given pointer doesn't point to a valid object. Object validity is checked by means of the special ID field of type enum TN_ObjId.

See also: enum TN_ObjId

Definition at line 147 of file tn_cfg_default.h.

#define TN_DEBUG 0

Allows additional internal self-checking, useful to catch internal TNeo bugs as well as illegal kernel usage (e.g.

sleeping in the idle task callback). Produces a couple of extra instructions which usually just causes debugger to stop if something goes wrong.

Definition at line 157 of file tn_cfg_default.h.

#define TN_OLD_TNKERNEL_NAMES 1

Whether old TNKernel names (definitions, functions, etc) should be available.

If you're porting your existing application written for TNKernel, it is definitely worth enabling. If you start new project with TNeo from scratch, it's better to avoid old names.

Definition at line 167 of file tn_cfg_default.h.

#define TN_MUTEX_DEADLOCK_DETECT 1

Whether RTOS should detect deadlocks and notify user about them via callback.

See also: see tn_callback_deadlock_set(); see TN_CBDeadlock

Definition at line 192 of file tn_cfg_default.h.

#define TN_TICK_LISTS_CNT 8

Takes effect if only TN_DYNAMIC_TICK is not set.

Number of "tick" lists of timers, must be a power or two; minimum value: 2; typical values: 4, 8 or 16.

Refer to the Implementation of static timers for details.

Shortly: this value represents number of elements in the array of struct TN_ListItem, on 32-bit system each element takes 8 bytes.

The larger value, the more memory is needed, and the faster system timer ISR works. If your application has a lot of timers and/or sleeping tasks, consider incrementing this value; otherwise, default value should work for you.

Definition at line 213 of file tn_cfg_default.h.

#define TN_API_MAKE_ALIG_ARG TN_API_MAKE_ALIG_ARG__SIZE

API option for MAKE_ALIG() macro.

There is a terrible mess with MAKE_ALIG() macro: original TNKernel docs specify that the argument of it should be the size to align, but almost all ports, including "original" one, defined it so that it takes type, not size.

But the port by AlexB implemented it differently (i.e. accordingly to the docs)

When I was moving from the port by AlexB to another one, do you have any idea how much time it took me to figure out why do I have rare weird bug? :)

So, available options:

TN_API_MAKE_ALIG_ARG__TYPE: 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)
TN_API_MAKE_ALIG_ARG__SIZE: 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 245 of file tn_cfg_default.h.

#define TN_PROFILER 0

Whether profiler functionality should be enabled.

Enabling this option adds overhead to context switching and increases the size of TN_Task structure by about 20 bytes.

See also: TN_PROFILER_WAIT_TIME; tn_task_profiler_timing_get(); struct TN_TaskTiming

Definition at line 259 of file tn_cfg_default.h.

#define TN_PROFILER_WAIT_TIME 0

Whether profiler should store wait time for each wait reason.

Enabling this option bumps the size of TN_Task structure by more than 100 bytes, see struct TN_TaskTiming.

Relevant if only TN_PROFILER is non-zero.

Definition at line 270 of file tn_cfg_default.h.

#define TN_INIT_INTERRUPT_STACK_SPACE 1

Whether interrupt stack space should be initialized with TN_FILL_STACK_VAL on system start.

It is useful to disable this option if you don't want to allocate separate array for interrupt stack, but use initialization stack for it.

Definition at line 280 of file tn_cfg_default.h.

#define TN_STACK_OVERFLOW_CHECK 1

Whether software stack overflow check is enabled.

Enabling this option adds small overhead to context switching and system tick processing (tn_tick_int_processing()), it also reduces the payload of task stacks by just one word (TN_UWord) for each stack.

When stack overflow happens, the kernel calls user-provided callback (see tn_callback_stack_overflow_set()); if this callback is undefined, the kernel calls _TN_FATAL_ERROR().

This option is on by default for all architectures except PIC24/dsPIC, since this architecture has hardware stack pointer limit, unlike the others.

Attention: It is not an absolute guarantee that the kernel will detect any stack overflow. The kernel tries to detect stack overflow by checking the latest address of stack, which should have special value TN_FILL_STACK_VAL.; So stack overflow is detected if only the overflow caused this value to corrupt, which isn't always the case.; More, the check is performed only at context switch and timer tick processing, which may be too late.

Nevertheless, from my personal experience, it helps to catch stack overflow bugs a lot.

Definition at line 324 of file tn_cfg_default.h.

#define TN_OLD_EVENT_API 0

Whether the old TNKernel events API compatibility mode is active.

Warning: Use it if only you're porting your existing TNKernel project on TNeo. Otherwise, usage of this option is strongly discouraged.

Actually, events are the most incompatible thing between TNeo and TNKernel (for some details, refer to the section Events API is changed almost completely)

This option is quite useful when you're porting your existing TNKernel app to TNeo. When it is non-zero, old events symbols are available and behave just like they do in TNKernel.

The full list of what becomes available:

Event group attributes:
- TN_EVENT_ATTR_SINGLE
- TN_EVENT_ATTR_MULTI
- TN_EVENT_ATTR_CLR
Functions:
- tn_event_create()
- tn_event_delete()
- tn_event_wait()
- tn_event_wait_polling()
- tn_event_iwait()
- tn_event_set()
- tn_event_iset()
- tn_event_clear()
- tn_event_iclear()

Definition at line 370 of file tn_cfg_default.h.

#define TN_P24_SYS_IPL 4

Maximum system interrupt priority.

For details on system interrupts on PIC24/dsPIC, refer to the section PIC24/dsPIC interrupts.

Should be >= 1 and <= 6. Default: 4.

Definition at line 389 of file tn_cfg_default.h.

Detailed Description

Macros

Macro Definition Documentation