packages/services/memalloc/common/v2_0/cdl/memalloc.cdl

   1 # ====================================================================
   2 #
   3 #      memalloc.cdl
   4 #
   5 #      Dynamic memory allocator services 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-06-02
  46 #
  47 #####DESCRIPTIONEND####
  48 #
  49 # ====================================================================
  50
  51 cdl_package CYGPKG_MEMALLOC {
  52     display       "Dynamic memory allocation"
  53     description   "
  54         This package provides memory allocator infrastructure required for
  55         dynamic memory allocators, including the ISO standard malloc
  56         interface. It also contains some sample implementations."
  57     doc           ref/memalloc.html
  58     include_dir   cyg/memalloc
  59     compile       dlmalloc.cxx memfixed.cxx memvar.cxx \
  60                   sepmeta.cxx debug.c
  61
  62 # ====================================================================
  63
  64     cdl_component CYGPKG_MEMALLOC_ALLOCATORS {
  65         display       "Memory allocator implementations"
  66         flavor        none
  67         no_define
  68         description   "
  69             This component contains configuration options related to the
  70             various memory allocators available."
  71
  72         cdl_component CYGPKG_MEMALLOC_ALLOCATOR_FIXED {
  73             display       "Fixed block allocator"
  74             flavor        none
  75             no_define
  76             description   "
  77                 This component contains configuration options related to the
  78                 fixed block memory allocator."
  79
  80             cdl_option CYGSEM_MEMALLOC_ALLOCATOR_FIXED_THREADAWARE {
  81                 display        "Make thread safe"
  82                 active_if      CYGPKG_KERNEL
  83                 default_value  1
  84                 description    "
  85                     With this option enabled, this allocator will be
  86                     made thread-safe. Additionally allocation functions
  87                     are made available that allow a thread to wait
  88                     until memory is available."
  89             }
  90         }
  91
  92         cdl_component CYGPKG_MEMALLOC_ALLOCATOR_VARIABLE {
  93             display       "Simple variable block allocator"
  94             flavor        none
  95             no_define
  96             description   "
  97                 This component contains configuration options related to the
  98                 simple variable block memory allocator. This allocator is not
  99                 very fast, and in particular does not scale well with large
 100                 numbers of allocations. It is however very compact in terms of
 101                 code size and does not have very much overhead per allocation."
 102
 103             cdl_option CYGSEM_MEMALLOC_ALLOCATOR_VARIABLE_THREADAWARE {
 104                 display        "Make thread safe"
 105                 active_if      CYGPKG_KERNEL
 106                 default_value  1
 107                 description    "
 108                     With this option enabled, this allocator will be
 109                     made thread-safe. Additionally allocation functions
 110                     are added that allow a thread to wait until memory
 111                     are made available that allow a thread to wait
 112                     until memory is available."
 113             }
 114
 115             cdl_option CYGSEM_MEMALLOC_ALLOCATOR_VARIABLE_COALESCE {
 116                 display       "Coalesce memory"
 117                 default_value 1
 118                 description   "
 119                     The variable-block memory allocator can perform coalescing
 120                     of memory whenever the application code releases memory back
 121                     to the pool. This coalescing reduces the possibility of
 122                     memory fragmentation problems, but involves extra code and
 123                     processor cycles."
 124             }
 125         }
 126
 127         cdl_component CYGPKG_MEMALLOC_ALLOCATOR_DLMALLOC {
 128             display       "Doug Lea's malloc"
 129             flavor        none
 130             description   "
 131                 This component contains configuration options related to the
 132                 port of Doug Lea's memory allocator, normally known as
 133                 dlmalloc. dlmalloc has a reputation for being both fast
 134                 and space-conserving, as well as resisting fragmentation well.
 135                 It is a common choice for a general purpose allocator and
 136                 has been used in both newlib and Linux glibc."
 137
 138             cdl_option CYGDBG_MEMALLOC_ALLOCATOR_DLMALLOC_DEBUG {
 139                 display       "Debug build"
 140                 requires      CYGDBG_USE_ASSERTS
 141                 default_value { 0 != CYGDBG_USE_ASSERTS }
 142                 description   "
 143                     Doug Lea's malloc implementation has substantial amounts
 144                     of internal checking in order to verify the operation
 145                     and consistency of the allocator. However this imposes
 146                     substantial overhead on each operation. Therefore this
 147                     checking may be individually disabled."
 148             }
 149
 150             cdl_option CYGIMP_MEMALLOC_ALLOCATOR_DLMALLOC_THREADAWARE {
 151                 display       "Make thread safe"
 152                 active_if     CYGPKG_KERNEL
 153                 requires      CYGPKG_KERNEL
 154                 default_value 1
 155                 description   "
 156                     With this option enabled, this allocator will be
 157                     made thread-safe. Additionally allocation functions
 158                     are made available that allow a thread to wait
 159                     until memory is available."
 160             }
 161
 162             cdl_option CYGIMP_MEMALLOC_ALLOCATOR_DLMALLOC_SAFE_MULTIPLE {
 163                 display       "Support more than one instance"
 164                 default_value 1
 165                 description   "
 166                     Having this option disabled allows important
 167                     implementation structures to be declared as a single
 168                     static instance, allowing faster access. However this
 169                     would fail if there is more than one instance of
 170                     the dlmalloc allocator class. Therefore this option can
 171                     be enabled if multiple instances are required. Note: as
 172                     a special case, if this allocator is used as the
 173                     implementation of malloc, and it can be determined there
 174                     is more than one malloc pool, then this option will be
 175                     silently enabled."
 176             }
 177
 178            cdl_option CYGIMP_MEMALLOC_ALLOCATOR_DLMALLOC_USE_MEMCPY {
 179                 display       "Use system memmove() and memset()"
 180                 requires      CYGPKG_ISOINFRA
 181                 default_value { 0 != CYGPKG_ISOINFRA }
 182                 description   "
 183                     This may be used to control whether memset() and memmove()
 184                     are used within the implementation. The alternative is
 185                     to use some macro equivalents, which some people report
 186                     are faster in some circumstances."
 187            }
 188
 189            cdl_option CYGNUM_MEMALLOC_ALLOCATOR_DLMALLOC_ALIGNMENT {
 190                 display       "Minimum alignment of allocated blocks"
 191                 flavor        data
 192                 legal_values  3 to 10
 193                 default_value 3
 194                 description   "
 195                     This option controls the minimum alignment that the
 196                     allocated memory blocks are aligned on, specified as
 197                     2^N. Note that using large mininum alignments can lead
 198                     to excessive memory wastage."
 199            }
 200         }
 201
 202         cdl_component CYGPKG_MEMALLOC_ALLOCATOR_SEPMETA {
 203             display       "Variable block allocator with separate metadata"
 204             flavor        none
 205             no_define
 206             description   "
 207                 This component contains configuration options related to the
 208                 variable block memory allocator with separate metadata."
 209
 210             cdl_option CYGSEM_MEMALLOC_ALLOCATOR_SEPMETA_THREADAWARE {
 211                 display        "Make thread safe"
 212                 active_if      CYGPKG_KERNEL
 213                 default_value  1
 214                 description    "
 215                     With this option enabled, this allocator will be
 216                     made thread-safe. Additionally allocation functions
 217                     are made available that allow a thread to wait
 218                     until memory is available."
 219             }
 220         }
 221     }
 222
 223     cdl_option CYGFUN_MEMALLOC_KAPI {
 224         display       "Kernel C API support for memory allocation"
 225         active_if     CYGPKG_KERNEL
 226         default_value CYGFUN_KERNEL_API_C
 227         description   "
 228             This option must be enabled to provide the extensions required
 229             to support integration into the kernel C API."
 230         compile       kapi.cxx
 231     }
 232
 233     cdl_option CYGSEM_MEMALLOC_MALLOC_ZERO_RETURNS_NULL {
 234         display       "malloc(0) returns NULL"
 235         default_value 0
 236         description   "
 237             This option controls the behavior of malloc(0) ( or calloc with
 238             either argument 0 ). It is permitted by the standard to return
 239             either a NULL pointer or a unique pointer. Enabling this option
 240             forces a NULL pointer to be returned."
 241     }
 242
 243     cdl_option CYGSEM_MEMALLOC_INVOKE_OUT_OF_MEMORY {
 244         display       "Breakpoint site when running out of memory"
 245         default_value 0
 246         description   "
 247             Whenever the system runs out of memory, it invokes this function
 248             before either going to sleep waiting for memory to become
 249             available or returning failure."
 250     }
 251
 252     cdl_component CYGPKG_MEMALLOC_MALLOC_ALLOCATORS {
 253         display      "malloc() and supporting allocators"
 254         flavor        bool
 255         active_if     CYGPKG_ISOINFRA
 256         implements    CYGINT_ISO_MALLOC
 257         implements    CYGINT_ISO_MALLINFO
 258         default_value 1
 259         compile       malloc.cxx
 260         description   "
 261             This component enables support for dynamic memory
 262             allocation as supplied by the functions malloc(),
 263             free(), calloc() and realloc(). As these
 264             functions are often used, but can have quite an
 265             overhead, disabling them here can ensure they
 266             cannot even be used accidentally when static
 267             allocation is preferred. Within this component are
 268             various allocators that can be selected for use
 269             as the underlying implementation of the dynamic
 270             allocation functions."
 271
 272         make -priority 50 {
 273             heapgeninc.tcl : <PACKAGE>/src/heapgen.cpp
 274             $(CC) $(ACTUAL_CXXFLAGS) $(INCLUDE_PATH) -Wp,-MD,heapgen.tmp -E $< -o $@
 275             @sed -e '/^ *\\/d' -e "s#.*: #$@: #" heapgen.tmp > $(notdir $@).deps
 276             @rm heapgen.tmp
 277         }
 278
 279         # FIXME this should have a dependency on mlt_headers, but CDL doesn't
 280         # permit custom build rules depending on phony targets
 281         # FIXME we workaround an NT cygtclsh80 bug by cd'ing into the
 282         # correct dir and running heapgen.tcl from there rather than passing
 283         # an absolute path.
 284         make -priority 50 {
 285             heaps.cxx : heapgeninc.tcl <PACKAGE>/src/heapgen.tcl
 286             XPWD=`pwd` ; cd $(REPOSITORY)/$(PACKAGE)/src ; sh heapgen.tcl "$(PREFIX)" "$$XPWD"
 287             @cp heaps.hxx "$(PREFIX)"/include/pkgconf/heaps.hxx
 288             @chmod u+w "$(PREFIX)"/include/pkgconf/heaps.hxx
 289         }
 290
 291         make_object {
 292             heaps.o.d : heaps.cxx
 293             $(CC) $(ACTUAL_CXXFLAGS) $(INCLUDE_PATH) -Wp,-MD,heaps.tmp -c -o $(OBJECT_PREFIX)_$(notdir $(@:.o.d=.o)) $<
 294             @sed -e '/^ *\\/d' -e "s#.*: #$@: #" heaps.tmp > $@
 295             @rm heaps.tmp
 296         }
 297
 298         cdl_component CYGBLD_MEMALLOC_MALLOC_EXTERNAL_HEAP_H {
 299             display       "Use external heap definition"
 300             flavor        booldata
 301             default_value 0
 302             description   "This option allows other components in the
 303                            system to override the default system
 304                            provision of heap memory pools. This should
 305                            be set to a header which provides the equivalent
 306                            definitions to <pkgconf/heaps.hxx>."
 307         }
 308
 309         cdl_component CYGBLD_MEMALLOC_MALLOC_EXTERNAL_JOIN_H {
 310             display       "Use external implementation of joining multiple heaps"
 311             flavor        booldata
 312             default_value 0
 313             description   "The default implementation of joining multiple heaps
 314                            is fine for the case where there are multiple disjoint
 315                            memory regions of the same type. However, in a system
 316                            there might be e.g. a small amount of internal SRAM and
 317                            a large amount of external DRAM. The SRAM is faster and
 318                            the DRAM is slower. An application can implement some
 319                            heuristic to choose which pool to allocate from. This
 320                            heuristic can be highly application specific."
 321         }
 322
 323         cdl_interface CYGINT_MEMALLOC_MALLOC_ALLOCATORS {
 324             display       "malloc() allocator implementations"
 325             requires      { CYGINT_MEMALLOC_MALLOC_ALLOCATORS == 1 }
 326             no_define
 327         }
 328
 329         cdl_option CYGBLD_MEMALLOC_MALLOC_IMPLEMENTATION_HEADER {
 330             display       "malloc() implementation instantiation data"
 331             flavor        data
 332             description   "
 333                 Memory allocator implementations that are capable of being
 334                 used underneath malloc() must be instantiated. The code
 335                 to do this is set in this option. It is only intended to
 336                 be set by the implementation, not the user."
 337             # default corresponds to the default allocator
 338             default_value {"<cyg/memalloc/dlmalloc.hxx>"}
 339         }
 340
 341         cdl_option CYGIMP_MEMALLOC_MALLOC_VARIABLE_SIMPLE {
 342             display       "Simple variable block implementation"
 343             description   "This causes malloc() to use the simple
 344                            variable block allocator."
 345             default_value 0
 346             implements    CYGINT_MEMALLOC_MALLOC_ALLOCATORS
 347             requires      { CYGBLD_MEMALLOC_MALLOC_IMPLEMENTATION_HEADER == \
 348                             "<cyg/memalloc/memvar.hxx>" }
 349             requires      CYGSEM_MEMALLOC_ALLOCATOR_VARIABLE_COALESCE
 350         }
 351
 352         cdl_option CYGIMP_MEMALLOC_MALLOC_DLMALLOC {
 353             display       "Doug Lea's malloc implementation"
 354             description   "This causes malloc() to use a version of Doug Lea's
 355                            malloc (dlmalloc) as the underlying implementation."
 356             default_value 1
 357             implements    CYGINT_MEMALLOC_MALLOC_ALLOCATORS
 358             requires      { CYGBLD_MEMALLOC_MALLOC_IMPLEMENTATION_HEADER == \
 359                             "<cyg/memalloc/dlmalloc.hxx>" }
 360         }
 361     }
 362     cdl_option CYGNUM_MEMALLOC_FALLBACK_MALLOC_POOL_SIZE {
 363         display       "Size of the fallback dynamic memory pool in bytes"
 364         flavor        data
 365         legal_values  32 to 0x7fffffff
 366         default_value 16384
 367         description   "
 368             If *no* heaps are configured in your memory layout,
 369             dynamic memory allocation by
 370             malloc() and calloc() must be from a fixed-size,
 371             contiguous memory pool (note here that it is the
 372             pool that is of a fixed size, but malloc() is still
 373             able to allocate variable sized chunks of memory
 374             from it). This option is the size
 375             of that pool, in bytes. Note that not all of
 376             this is available for programs to
 377             use - some is needed for internal information
 378             about memory regions, and some may be lost to
 379             ensure that memory allocation only returns
 380             memory aligned on word (or double word)
 381             boundaries - a very common architecture
 382             constraint."
 383     }
 384 # ====================================================================
 385
 386     cdl_component CYGPKG_MEMALLOC_OPTIONS {
 387         display "Common memory allocator package build options"
 388         flavor  none
 389         no_define
 390         description   "
 391             Package specific build options including control over
 392             compiler flags used only in building this package,
 393             and details of which tests are built."
 394
 395         cdl_option CYGPKG_MEMALLOC_CFLAGS_ADD {
 396             display "Additional compiler flags"
 397             flavor  data
 398             no_define
 399             default_value { "-fno-rtti -Woverloaded-virtual" }
 400             description   "
 401                 This option modifies the set of compiler flags for
 402                 building this package. These flags are used in addition
 403                 to the set of global flags."
 404         }
 405
 406         cdl_option CYGPKG_MEMALLOC_CFLAGS_REMOVE {
 407             display "Suppressed compiler flags"
 408             flavor  data
 409             no_define
 410             default_value { "-Wno-pointer-sign" }
 411             description   "
 412                 This option modifies the set of compiler flags for
 413                 building this package. These flags are removed from
 414                 the set of global flags if present."
 415         }
 416
 417         cdl_option CYGPKG_MEMALLOC_TESTS {
 418             display "Tests"
 419             flavor  data
 420             no_define
 421             calculated { "tests/dlmalloc1 tests/dlmalloc2 tests/heaptest tests/kmemfix1 tests/kmemvar1 tests/malloc1 tests/malloc2 tests/malloc3 tests/malloc4 tests/memfix1 tests/memfix2 tests/memvar1 tests/memvar2 tests/realloc tests/sepmeta1 tests/sepmeta2" }
 422             description   "
 423                 This option specifies the set of tests for this package."
 424         }
 425     }
 426 }
 427
 428 # ====================================================================
 429 # EOF memalloc.cdl