TNeoKernel  v1.02
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
tn_cfg_default.h
Go to the documentation of this file.
1 /*******************************************************************************
2  *
3  * TNeoKernel: real-time kernel initially based on TNKernel
4  *
5  * TNKernel: copyright © 2004, 2013 Yuri Tiomkin.
6  * PIC32-specific routines: copyright © 2013, 2014 Anders Montonen.
7  * TNeoKernel: copyright © 2014 Dmitry Frank.
8  *
9  * TNeoKernel was born as a thorough review and re-implementation of
10  * TNKernel. The new kernel has well-formed code, inherited bugs are fixed
11  * as well as new features being added, and it is tested carefully with
12  * unit-tests.
13  *
14  * API is changed somewhat, so it's not 100% compatible with TNKernel,
15  * hence the new name: TNeoKernel.
16  *
17  * Permission to use, copy, modify, and distribute this software in source
18  * and binary forms and its documentation for any purpose and without fee
19  * is hereby granted, provided that the above copyright notice appear
20  * in all copies and that both that copyright notice and this permission
21  * notice appear in supporting documentation.
22  *
23  * THIS SOFTWARE IS PROVIDED BY THE DMITRY FRANK AND CONTRIBUTORS "AS IS"
24  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
26  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL DMITRY FRANK OR CONTRIBUTORS BE
27  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
28  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
29  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
30  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
31  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
32  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
33  * THE POSSIBILITY OF SUCH DAMAGE.
34  *
35  ******************************************************************************/
36 
37 /**
38  * \file
39  *
40  * TNeoKernel default configuration file, to be copied as `tn_cfg.h`.
41  *
42  * This project is intended to be built as a library, separately from main
43  * project (although nothing prevents you from bundling things together, if you
44  * want to).
45  *
46  * There are various options available which affects API and behavior of the
47  * kernel. But these options are specific for particular project, and aren't
48  * related to the kernel itself, so we need to keep them separately.
49  *
50  * To this end, file `tn.h` (the main kernel header file) includes `tn_cfg.h`,
51  * which isn't included in the repository (even more, it is added to
52  * `.hgignore` list actually). Instead, default configuration file
53  * `tn_cfg_default.h` is provided, and when you just cloned the repository, you
54  * might want to copy it as `tn_cfg.h`. Or even better, if your filesystem
55  * supports symbolic links, copy it somewhere to your main project's directory
56  * (so that you can add it to your VCS there), and create symlink to it named
57  * `tn_cfg.h` in the TNeoKernel source directory, like this:
58  *
59  * $ cd /path/to/tneokernel/src
60  * $ cp ./tn_cfg_default.h /path/to/main/project/lib_cfg/tn_cfg.h
61  * $ ln -s /path/to/main/project/lib_cfg/tn_cfg.h ./tn_cfg.h
62  *
63  * Default configuration file contains detailed comments, so you can read them
64  * and configure behavior as you like.
65  */
66 
67 #ifndef _TN_CFG_DEFAULT_H
68 #define _TN_CFG_DEFAULT_H
69 
70 
71 /*******************************************************************************
72  * USER-DEFINED OPTIONS
73  ******************************************************************************/
74 
75 /**
76  * Enables additional param checking for most of the system functions.
77  * It's surely useful for debug, but probably better to remove in release.
78  * If it is set, most of the system functions are able to return two additional
79  * codes:
80  *
81  * * `#TN_RC_WPARAM` if wrong params were given;
82  * * `#TN_RC_INVALID_OBJ` if given pointer doesn't point to a valid object.
83  * Object validity is checked by means of the special ID field of type
84  * `enum #TN_ObjId`.
85  *
86  * @see `enum #TN_ObjId`
87  */
88 #ifndef TN_CHECK_PARAM
89 # define TN_CHECK_PARAM 1
90 #endif
91 
92 /**
93  * Allows additional internal self-checking, useful to catch internal
94  * TNeoKernel bugs as well as illegal kernel usage (e.g. sleeping in the idle
95  * task callback). Produces a couple of extra instructions which usually just
96  * causes debugger to stop if something goes wrong.
97  */
98 #ifndef TN_DEBUG
99 # define TN_DEBUG 0
100 #endif
101 
102 /**
103  * Whether old TNKernel names (definitions, functions, etc) should be
104  * available. If you're porting your existing application written for
105  * TNKernel, it is definitely worth enabling. If you start new project with
106  * TNeoKernel from scratch, it's better to avoid old names.
107  */
108 #ifndef TN_OLD_TNKERNEL_NAMES
109 # define TN_OLD_TNKERNEL_NAMES 1
110 #endif
111 
112 /**
113  * Whether mutexes API should be available
114  */
115 #ifndef TN_USE_MUTEXES
116 # define TN_USE_MUTEXES 1
117 #endif
118 
119 /**
120  * Whether mutexes should allow recursive locking/unlocking
121  */
122 #ifndef TN_MUTEX_REC
123 # define TN_MUTEX_REC 1
124 #endif
125 
126 /**
127  * Whether RTOS should detect deadlocks and notify user about them
128  * via callback
129  *
130  * @see see `tn_callback_deadlock_set()`
131  */
132 #ifndef TN_MUTEX_DEADLOCK_DETECT
133 # define TN_MUTEX_DEADLOCK_DETECT 1
134 #endif
135 
136 /**
137  * Number of "tick" lists of timers, must be a power or two; minimum value:
138  * `2`; typical values: `4`, `8` or `16`.
139  *
140  * Refer to the \ref timers_implementation for details.
141  *
142  * Shortly: this value represents number of elements in the array of
143  * `struct TN_ListItem`, on 32-bit system each element takes 8 bytes.
144  *
145  * The larger value, the more memory is needed, and the faster
146  * $(TN_SYS_TIMER_LINK) ISR works. If your application has a lot of timers
147  * and/or sleeping tasks, consider incrementing this value; otherwise,
148  * default value should work for you.
149  */
150 #ifndef TN_TICK_LISTS_CNT
151 # define TN_TICK_LISTS_CNT 8
152 #endif
153 
154 
155 /**
156  * API option for `MAKE_ALIG()` macro.
157  *
158  * There is a terrible mess with `MAKE_ALIG()` macro: original TNKernel docs
159  * specify that the argument of it should be the size to align, but almost all
160  * ports, including "original" one, defined it so that it takes type, not size.
161  *
162  * But the port by AlexB implemented it differently
163  * (i.e. accordingly to the docs)
164  *
165  * When I was moving from the port by AlexB to another one, do you have any
166  * idea how much time it took me to figure out why do I have rare weird bug? :)
167  *
168  * So, available options:
169  *
170  * * `#TN_API_MAKE_ALIG_ARG__TYPE`:
171  * In this case, you should use macro like this:
172  * `TN_MAKE_ALIG(struct my_struct)`
173  * This way is used in the majority of TNKernel ports.
174  * (actually, in all ports except the one by AlexB)
175  *
176  * * `#TN_API_MAKE_ALIG_ARG__SIZE`:
177  * In this case, you should use macro like this:
178  * `TN_MAKE_ALIG(sizeof(struct my_struct))`
179  * This way is stated in TNKernel docs
180  * and used in the port for dsPIC/PIC24/PIC32 by AlexB.
181  */
182 #ifndef TN_API_MAKE_ALIG_ARG
183 # define TN_API_MAKE_ALIG_ARG TN_API_MAKE_ALIG_ARG__SIZE
184 #endif
185 
186 
187 #endif // _TN_CFG_DEFAULT_H
188 
189