1 # ====================================================================
5 # ISO environment startup/termination related configuration data
7 # ====================================================================
8 #####ECOSGPLCOPYRIGHTBEGIN####
9 ## -------------------------------------------
10 ## This file is part of eCos, the Embedded Configurable Operating System.
11 ## Copyright (C) 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.
13 ## eCos is free software; you can redistribute it and/or modify it under
14 ## the terms of the GNU General Public License as published by the Free
15 ## Software Foundation; either version 2 or (at your option) any later version.
17 ## eCos is distributed in the hope that it will be useful, but WITHOUT ANY
18 ## WARRANTY; without even the implied warranty of MERCHANTABILITY or
19 ## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
22 ## You should have received a copy of the GNU General Public License along
23 ## with eCos; if not, write to the Free Software Foundation, Inc.,
24 ## 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
26 ## As a special exception, if other files instantiate templates or use macros
27 ## or inline functions from this file, or you compile this file and link it
28 ## with other works to produce a work based on this file, this file does not
29 ## by itself cause the resulting work to be covered by the GNU General Public
30 ## License. However the source code for this file must still be made available
31 ## in accordance with section (3) of the GNU General Public License.
33 ## This exception does not invalidate any other reasons why a work based on
34 ## this file might be covered by the GNU General Public License.
36 ## Alternative licenses for eCos may be arranged by contacting Red Hat, Inc.
37 ## at http://sources.redhat.com/ecos/ecos-license/
38 ## -------------------------------------------
39 #####ECOSGPLCOPYRIGHTEND####
40 # ====================================================================
41 ######DESCRIPTIONBEGIN####
47 #####DESCRIPTIONEND####
49 # ====================================================================
51 cdl_package CYGPKG_LIBC_STARTUP {
52 display "ISO environment startup/termination"
54 This package manages the control of the
55 environment (in the general sense) that an
56 application would require for full ISO C / POSIX
57 compatibility, including a main() entry point
58 supplied with arguments and an environment
59 (as retrievable by the getenv() function).
60 It also includes at the other end of things,
61 what happens when main() returns or exit() is
63 doc ref/c-library-startup.html
64 include_dir cyg/libc/startup
66 requires CYGPKG_ISOINFRA
67 requires { CYGINT_LIBC_STARTUP_CONTEXT == 1 }
68 implements CYGINT_ISO_EXIT
69 implements CYGINT_ISO_MAIN_STARTUP
70 implements CYGINT_ISO_ENVIRON
72 compile _exit.cxx abort.cxx atexit.cxx \
73 environ.cxx exit.cxx invokemain.cxx \
74 main.cxx mainthread.cxx
76 compile -library=libextras.a cstartup.cxx
78 # ====================================================================
80 cdl_interface CYGINT_LIBC_STARTUP_EXTERNAL_INVOKE_MAIN_POSSIBLE {
81 display "main() can be invoked elsewhere"
82 description "Implementors of this interface show that they
83 allow main() to be invoked elsewhere."
88 cdl_option CYGDAT_LIBC_ARGUMENTS {
89 display "Arguments to main()"
91 default_value {"{(char *)\"\", (char *)NULL}"}
93 This option allows the setting of the arguments
94 to the main function. This only has any effect
95 when cyg_iso_c_start() is used to start the
96 ISO C compatibility. This will automatically
97 invoke main() in an ISO C compatible fashion.
98 This option is in fact used as argv, and so is
99 an n-tuple of string constants. The final
100 entry must be NULL. Conventionally if argv\[0\]
101 is supplied, it is used to inform the program
106 cdl_component CYGPKG_LIBC_STARTUP_CONTEXT {
107 display "Startup context for main()"
110 description "This component describes the options available for
111 what context main() is invoked in, such as in a thread
114 cdl_interface CYGINT_LIBC_STARTUP_CONTEXT {
115 display "Startup context implementors"
120 cdl_option CYGSEM_LIBC_STARTUP_MAIN_INITCONTEXT {
121 display "Invoked from initialization context"
122 description "With this option selected, main() will be
123 called via cyg_user_start() (unless the program
124 overrides the default cyg_user_start()). This
125 means it is run in the context of the system
126 initialization code, without the eCos kernel
127 scheduler running, and using the startup stack.
128 This means that any functions that may require
129 interactions with a running kernel will not
130 work (including libc functions, if configured
131 to be thread safe for example), so you should
132 restrict yourself to only calling fully
133 re-entrant functions from within main() in
136 default_value { 0 == CYGPKG_KERNEL && 0 ==
137 CYGINT_LIBC_STARTUP_EXTERNAL_INVOKE_MAIN_POSSIBLE }
138 implements CYGINT_LIBC_STARTUP_CONTEXT
139 implements CYGINT_LIBC_STARTUP_MAIN_NO_STACK_SIZE
142 cdl_component CYGSEM_LIBC_STARTUP_MAIN_THREAD {
143 display "Invoked as eCos thread"
144 requires CYGPKG_KERNEL
146 default_value { 0 != CYGPKG_KERNEL && 0 == \
147 CYGINT_LIBC_STARTUP_EXTERNAL_INVOKE_MAIN_POSSIBLE }
148 implements CYGINT_LIBC_STARTUP_CONTEXT
150 With this option selected, main() is invoked from an eCos
153 cdl_option CYGSEM_LIBC_MAIN_STACK_FROM_SYSTEM {
154 display "System provides stack for main()'s thread"
156 This option controls whether the stack of
157 main()'s thread is provided by the application or
158 provided by the system. When disabled, the
159 application must declare a pointer variable
160 cyg_libc_main_stack which is a pointer to an
161 appropriately aligned region of memory. The
162 application must also declare a variable of
163 type `int' called cyg_libc_main_stack_size
164 which contains the size of the stack in bytes.
165 This must be a multiple of 8."
170 cdl_option CYGNUM_LIBC_MAIN_THREAD_PRIORITY {
171 display "Priority of main()'s thread"
173 This option is used to provide the thread
174 priority which main()'s thread runs at. Be
175 sure to check that this number is appropriate
176 for the kernel scheduler chosen. Different
177 kernel schedulers impose different restrictions
178 on the usable priorities."
180 legal_values 0 to 0x7fffffff
185 cdl_option CYGSEM_LIBC_STARTUP_MAIN_OTHER {
186 display "Invoked elsewhere"
187 description "With this option selected, main() must be
188 invoked by a separate package, or by the user."
190 default_value { 0 != \
191 CYGINT_LIBC_STARTUP_EXTERNAL_INVOKE_MAIN_POSSIBLE }
192 requires CYGINT_LIBC_STARTUP_EXTERNAL_INVOKE_MAIN_POSSIBLE
193 implements CYGINT_LIBC_STARTUP_CONTEXT
197 cdl_interface CYGINT_LIBC_STARTUP_MAIN_NO_STACK_SIZE {
198 display "Don't allow main()'s stack size to be set"
199 description "This interface describes whether the stack size
200 value set in this package is supported by the
201 implementation that invokes main. If not, that
207 cdl_option CYGNUM_LIBC_MAIN_DEFAULT_STACK_SIZE {
208 display "main()'s default thread stack size"
210 legal_values 16 to 0x7fffffff
212 active_if !CYGINT_LIBC_STARTUP_MAIN_NO_STACK_SIZE
214 This option sets the size of the stack used
215 in the context that invokes main(). For example,
216 with an eCos kernel, when the cyg_iso_c_start()
217 function is used to invoke the user-supplied
218 main() function in an ISO C compatible fashion,
219 a separate thread is created to call main().
220 This option controls the size of that thread's
221 stack, which is allocated in the BSS. It
222 must be a multiple of 8. Note, a low number
223 here may be overriden by the HAL if there is
224 a minimum requirement to process interrupts
225 etc. This option cannot be set if the implementation
226 that invokes main() does not use it."
229 cdl_component CYGFUN_LIBC_ATEXIT {
230 display "Include atexit() function"
234 This option enables the use of the atexit()
235 function, and ensure that the atexit handlers
236 are invoked from within exit() as defined in
239 cdl_option CYGNUM_LIBC_ATEXIT_HANDLERS {
240 display "Number of functions atexit() supports"
242 legal_values 1 to 0x7fffffff
245 This option sets the number of functions
246 that atexit() has room for. In other words,
247 the number of separate atexit() calls that
248 can be made before calling exit() or returning
249 from main() ( in an environment controlled by
250 cyg_iso_c_start() ). For strict compliance
251 with the ISO C standard this should be at
256 cdl_option CYGSEM_LIBC_EXIT_CALLS_FFLUSH {
257 display "Make exit() call fflush()"
258 requires CYGINT_ISO_STDIO_FILEACCESS
259 default_value { 0 != CYGINT_ISO_STDIO_FILEACCESS }
261 This option will ensure that all output
262 streams are flushed when exitting using
263 exit() as prescribed by the ISO C standard."
266 cdl_option CYGSEM_LIBC_EXIT_STOPS_SYSTEM {
267 display "_exit() stops all threads"
268 requires CYGPKG_KERNEL
271 If this option is enabled then _exit(),
272 which is called from exit() which itself is
273 called on return from main(), stops the eCos
274 scheduler. For strict POSIX 1003.1
275 compatibility this would be the normal
276 behaviour. To allow the thread to simply
277 exit, without affecting other threads, simply
278 leave this option disabled. If there is no eCos
279 scheduler, then _exit() simply loops
280 irrespective of the setting of this option."
283 cdl_option CYGDAT_LIBC_DEFAULT_ENVIRONMENT {
284 display "Default environment"
286 default_value {"{ NULL }"}
288 This option allows the setting of the default
289 contents of the environment. This is in fact
290 the contents of the global environment pointer
291 char **environ defined by POSIX 1003.1. Strings
292 must be of the form NAME=VALUE, and the final
296 cdl_option CYGSEM_LIBC_INVOKE_DEFAULT_STATIC_CONSTRUCTORS {
297 display "Invoke default static constructors"
298 requires CYGSEM_HAL_STOP_CONSTRUCTORS_ON_FLAG
299 requires { CYGSEM_LIBC_STARTUP_MAIN_THREAD || \
300 (CYGSEM_LIBC_STARTUP_MAIN_OTHER && CYGPKG_POSIX_PTHREAD) }
303 This option causes the C library to call
304 static constructors with default priority
305 from within the context of the main() thread,
306 working with the co-operation of the HAL.
307 This may be needed for environments that
308 expect static constructors to be run in a
309 thread context. Note that this uses an object
310 with priority 65534. Therefore do not use
311 priority 65534 for any other static objects
312 with this option enabled."
316 # ====================================================================
318 cdl_component CYGPKG_LIBC_STARTUP_OPTIONS {
319 display "ISO environment startup/termination build options"
323 Package specific build options including control over
324 compiler flags used only in building this package,
325 and details of which tests are built."
328 cdl_option CYGPKG_LIBC_STARTUP_CFLAGS_ADD {
329 display "Additional compiler flags"
334 This option modifies the set of compiler flags for
335 building this package. These flags are used in addition
336 to the set of global flags."
339 cdl_option CYGPKG_LIBC_STARTUP_CFLAGS_REMOVE {
340 display "Suppressed compiler flags"
345 This option modifies the set of compiler flags for
346 building this package. These flags are removed from
347 the set of global flags if present."
350 cdl_option CYGPKG_LIBC_STARTUP_TESTS {
351 display "ISO environment startup/termination tests"
354 calculated { "tests/atexit" }
356 This option specifies the set of tests for this package."
361 # ====================================================================