packages/infra/v2_0/cdl/debug.cdl

   1 # ====================================================================
   2 #
   3 #      debug.cdl
   4 #
   5 #      Infrastructure debugging 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):      jskov
  44 # Original data:  bartv,hmt
  45 # Contributors:
  46 # Date:           1999-07-02
  47 #
  48 #####DESCRIPTIONEND####
  49 #
  50 # ====================================================================
  51
  52 # If global debugging is enabled then by default all assertions
  53 # are enabled. Tracing is not enabled by default because it
  54 # involves excessive overheads, for example on some targets
  55 # it requires sending a string down a serial line for every
  56 # function call. Both assertions and tracing are controlled
  57 # by the following lines.
  58
  59 cdl_component CYGDBG_USE_ASSERTS {
  60     display       "Use asserts"
  61     default_value 1
  62     requires      { 1 == CYGINT_INFRA_DEBUG_TRACE_IMPL }
  63     description   "
  64         If this option is defined, asserts in the code are tested.
  65         Assert functions (CYG_ASSERT()) are defined in
  66         'include/cyg/infra/cyg_ass.h' within the 'install' tree.
  67         If it is not defined, these result in no additional
  68         object code and no checking of the asserted conditions."
  69
  70     script        assert.cdl
  71 }
  72
  73 cdl_component CYGDBG_USE_TRACING {
  74     display       "Use tracing"
  75     default_value 0
  76     requires      { 1 == CYGINT_INFRA_DEBUG_TRACE_IMPL }
  77     description   "
  78         If this option is defined, tracing operations
  79         result in output or logging, depending on other options.
  80         This may have adverse effects on performance, if the time
  81         taken to output message overwhelms the available CPU
  82         power or output bandwidth.
  83         Trace functions (CYG_TRACE()) are defined in
  84         'include/cyg/infra/cyg_trac.h' within the 'install' tree.
  85         If it is not defined, these result in no additional
  86         object code and no trace information."
  87
  88
  89     # The eCos system uses two types of tracing mechanisms. The most common
  90     # type traces events, for example an event could be logged whenever
  91     # an interrupt occurs or whenever a context switch takes place. The
  92     # second type of tracing mechanism records every function entry and
  93     # exit. It is possible to disable this second type of tracing while
  94     # leaving the main tracing facility enabled.
  95     cdl_option CYGDBG_INFRA_DEBUG_FUNCTION_REPORTS {
  96         display       "Trace function reports"
  97         default_value 1
  98         description   "
  99             This option allows individual control of
 100             function entry/exit tracing, independent of
 101             more general tracing output.
 102             This may be useful to remove clutter from a
 103             trace log."
 104     }
 105
 106     cdl_option CYGDBG_INFRA_DEBUG_TRACE_MESSAGE {
 107         display       "Use trace text"
 108         default_value 1
 109         description   "
 110             All trace calls within eCos contain a text message
 111             which should give some information about the circumstances.
 112             These text messages will end up being embedded in the
 113             application image and hence there is a significant penalty
 114             in terms of image size.
 115             It is possible to suppress the use of these messages by
 116             disabling this option.
 117             This results in smaller code size, but there is less
 118             human-readable information available in the trace output,
 119             possibly only filenames and line numbers."
 120     }
 121 }
 122
 123 cdl_interface CYGINT_INFRA_DEBUG_TRACE_IMPL {
 124     display "Trace output implementations"
 125 }
 126
 127 cdl_option CYGDBG_INFRA_DEBUG_TRACE_ASSERT_NULL {
 128     display       "Null output"
 129     default_value 0
 130     implements    CYGINT_INFRA_DEBUG_TRACE_IMPL
 131     description   "
 132         A null output module which is useful when
 133         debugging interactively; the output routines
 134         can be breakpointed rather than have them actually
 135         'print' something."
 136 }
 137 cdl_option CYGDBG_INFRA_DEBUG_TRACE_ASSERT_SIMPLE {
 138     display          "Simple output"
 139     default_value 0
 140     implements    CYGINT_INFRA_DEBUG_TRACE_IMPL
 141     description   "
 142         An output module which produces simple output
 143         from tracing and assertion events."
 144 }
 145 cdl_option CYGDBG_INFRA_DEBUG_TRACE_ASSERT_FANCY {
 146     display       "Fancy output"
 147     default_value 0
 148     implements    CYGINT_INFRA_DEBUG_TRACE_IMPL
 149     description "
 150         An output module which produces fancy output
 151         from tracing and assertion events."
 152 }
 153 cdl_component CYGDBG_INFRA_DEBUG_TRACE_ASSERT_BUFFER {
 154     display       "Buffered tracing"
 155     default_value 1
 156     implements    CYGINT_INFRA_DEBUG_TRACE_IMPL
 157     description   "
 158         An output module which buffers output
 159         from tracing and assertion events. The stored
 160         messages are output when an assert fires, or
 161         CYG_TRACE_PRINT() (defined in <cyg/infra/cyg_trac.h>)
 162         is called.
 163         Of course, there will only be stored messages
 164         if tracing per se (CYGDBG_USE_TRACING)
 165         is enabled above."
 166
 167     cdl_option CYGDBG_INFRA_DEBUG_TRACE_BUFFER_SIZE {
 168         display       "Trace buffer size"
 169         flavor        data
 170         active_if     CYGDBG_USE_TRACING
 171         default_value 32
 172         legal_values  5 to 65535
 173         description   "
 174             The size of the trace buffer. This counts the number
 175             of trace records stored. When the buffer fills it
 176             either wraps, stops recording, or generates output."
 177     }
 178     # FIXME: The below options should be mutually exclusive.
 179     cdl_option CYGDBG_INFRA_DEBUG_TRACE_BUFFER_WRAP {
 180         display       "Wrap trace buffer when full"
 181         active_if     CYGDBG_USE_TRACING
 182         default_value 1
 183         #          type             radio
 184         description   "
 185             When the trace buffer has filled with records it
 186             starts again at the beginning. Hence only the last
 187             CYGDBG_INFRA_DEBUG_TRACE_BUFFER_SIZE messages will
 188             be recorded."
 189     }
 190     cdl_option CYGDBG_INFRA_DEBUG_TRACE_BUFFER_HALT {
 191         display       "Halt trace buffer when full"
 192         active_if     CYGDBG_USE_TRACING
 193         default_value 0
 194         #          type             radio
 195         description   "
 196             When the trace buffer has filled with records it
 197             stops recording. Hence only the first
 198             CYGDBG_INFRA_DEBUG_TRACE_BUFFER_SIZE messages will
 199             be recorded."
 200     }
 201     cdl_option CYGDBG_INFRA_DEBUG_TRACE_BUFFER_PRINT {
 202         display       "Print trace buffer when full"
 203         active_if     CYGDBG_USE_TRACING
 204         default_value 0
 205         #          type             radio
 206         description   "
 207             When the trace buffer has filled with records it
 208             prints the contents of the buffer. The buffer is then
 209             emptied and the system continues."
 210     }
 211     cdl_option CYGDBG_INFRA_DEBUG_TRACE_BUFFER_PRINT_ON_ASSERT {
 212         display       "Print trace buffer on assert fail"
 213         active_if     CYGDBG_USE_TRACING
 214         default_value 1
 215         description   "
 216             When an assertion fails the trace buffer will be
 217             printed to the default diagnostic device."
 218     }
 219 }
 220
 221 cdl_option CYGDBG_INFRA_DEBUG_FUNCTION_PSEUDOMACRO {
 222     display       "Use function names"
 223     default_value 1
 224     description   "
 225         All trace and assert calls within eCos contain a
 226         reference to the builtin macro '__PRETTY_FUNCTION__',
 227         which evaluates to a string containing
 228         the name of the current function.
 229         This is useful when reading a trace log.
 230         It is possible to suppress the use of the function name
 231         by disabling this option.
 232         This results in smaller code size, but there is less
 233         human-readable information available in the trace output,
 234         possibly only filenames and line numbers."
 235 }