packages/language/c/libc/startup/v2_0/cdl/startup.cdl

   1 # ====================================================================
   2 #
   3 #      startup.cdl
   4 #
   5 #      ISO environment startup/termination related configuration data
   6 #
   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.
  12 ##
  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.
  16 ##
  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
  20 ## for more details.
  21 ##
  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.
  25 ##
  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.
  32 ##
  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.
  35 ##
  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####
  42 #
  43 # Author(s):      jlarmour
  44 # Contributors:
  45 # Date:           2000-04-14
  46 #
  47 #####DESCRIPTIONEND####
  48 #
  49 # ====================================================================
  50
  51 cdl_package CYGPKG_LIBC_STARTUP {
  52     display       "ISO environment startup/termination"
  53     description   "
  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
  62             called."
  63     doc           ref/c-library-startup.html
  64     include_dir   cyg/libc/startup
  65     parent        CYGPKG_LIBC
  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
  71
  72     compile       _exit.cxx      abort.cxx      atexit.cxx     \
  73                   environ.cxx    exit.cxx       invokemain.cxx \
  74                   main.cxx       mainthread.cxx
  75
  76     compile       -library=libextras.a cstartup.cxx
  77
  78 # ====================================================================
  79
  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."
  84         flavor        bool
  85         no_define
  86     }
  87
  88     cdl_option CYGDAT_LIBC_ARGUMENTS {
  89         display       "Arguments to main()"
  90         flavor        data
  91         default_value {"{(char *)\"\", (char *)NULL}"}
  92         description   "
  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
 102             of its name."
 103     }
 104
 105
 106     cdl_component CYGPKG_LIBC_STARTUP_CONTEXT {
 107         display       "Startup context for main()"
 108         flavor        none
 109         no_define
 110         description   "This component describes the options available for
 111                        what context main() is invoked in, such as in a thread
 112                        etc."
 113
 114         cdl_interface CYGINT_LIBC_STARTUP_CONTEXT {
 115             display       "Startup context implementors"
 116             no_define
 117         }
 118
 119
 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
 134                            this case."
 135             flavor        bool
 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
 140         }
 141
 142         cdl_component CYGSEM_LIBC_STARTUP_MAIN_THREAD {
 143             display       "Invoked as eCos thread"
 144             requires      CYGPKG_KERNEL
 145             flavor        bool
 146             default_value { 0 != CYGPKG_KERNEL && 0 == \
 147                             CYGINT_LIBC_STARTUP_EXTERNAL_INVOKE_MAIN_POSSIBLE }
 148             implements    CYGINT_LIBC_STARTUP_CONTEXT
 149             description   "
 150                 With this option selected, main() is invoked from an eCos
 151                 thread."
 152
 153             cdl_option CYGSEM_LIBC_MAIN_STACK_FROM_SYSTEM {
 154                 display        "System provides stack for main()'s thread"
 155                 description    "
 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."
 166                 flavor         bool
 167                 default_value  1
 168             }
 169
 170             cdl_option CYGNUM_LIBC_MAIN_THREAD_PRIORITY {
 171                 display         "Priority of main()'s thread"
 172                 description     "
 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."
 179                 flavor          data
 180                 legal_values    0 to 0x7fffffff
 181                 default_value   10
 182             }
 183         }
 184
 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."
 189             flavor        bool
 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
 194         }
 195     }
 196
 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
 202                         option is disabled."
 203         flavor         bool
 204         no_define
 205     }
 206
 207     cdl_option CYGNUM_LIBC_MAIN_DEFAULT_STACK_SIZE {
 208         display        "main()'s default thread stack size"
 209         flavor         data
 210         legal_values   16 to 0x7fffffff
 211         default_value  8192
 212         active_if      !CYGINT_LIBC_STARTUP_MAIN_NO_STACK_SIZE
 213         description    "
 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."
 227     }
 228
 229     cdl_component CYGFUN_LIBC_ATEXIT {
 230         display        "Include atexit() function"
 231         flavor         bool
 232         default_value  1
 233         description    "
 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
 237             the ISO C standard."
 238
 239         cdl_option CYGNUM_LIBC_ATEXIT_HANDLERS {
 240             display        "Number of functions atexit() supports"
 241             flavor         data
 242             legal_values   1 to 0x7fffffff
 243             default_value  32
 244             description    "
 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
 252                 least 32."
 253         }
 254     }
 255
 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 }
 260         description    "
 261             This option will ensure that all output
 262             streams are flushed when exitting using
 263             exit() as prescribed by the ISO C standard."
 264     }
 265
 266     cdl_option CYGSEM_LIBC_EXIT_STOPS_SYSTEM {
 267         display        "_exit() stops all threads"
 268         requires       CYGPKG_KERNEL
 269         default_value  0
 270         description    "
 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."
 281     }
 282
 283     cdl_option CYGDAT_LIBC_DEFAULT_ENVIRONMENT {
 284         display       "Default environment"
 285         flavor        data
 286         default_value {"{ NULL }"}
 287         description   "
 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
 293             entry must be NULL."
 294     }
 295
 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) }
 301         default_value  0
 302         description    "
 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."
 313     }
 314
 315
 316 # ====================================================================
 317
 318     cdl_component CYGPKG_LIBC_STARTUP_OPTIONS {
 319         display       "ISO environment startup/termination build options"
 320         flavor        none
 321         no_define
 322         description   "
 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."
 326
 327
 328         cdl_option CYGPKG_LIBC_STARTUP_CFLAGS_ADD {
 329             display       "Additional compiler flags"
 330             flavor        data
 331             no_define
 332             default_value { "" }
 333             description   "
 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."
 337         }
 338
 339         cdl_option CYGPKG_LIBC_STARTUP_CFLAGS_REMOVE {
 340             display       "Suppressed compiler flags"
 341             flavor        data
 342             no_define
 343             default_value { "" }
 344             description   "
 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."
 348         }
 349
 350         cdl_option CYGPKG_LIBC_STARTUP_TESTS {
 351             display       "ISO environment startup/termination tests"
 352             flavor        data
 353             no_define
 354             calculated    { "tests/atexit" }
 355             description   "
 356                 This option specifies the set of tests for this package."
 357         }
 358     }
 359 }
 360
 361 # ====================================================================
 362 # EOF startup.cdl