l4/pkg/l4sys/include/debugger.h

   1 #pragma once
   2 /**
   3  * \file
   4  * \brief Debugger related definitions.
   5  * \ingroup l4_api
   6  */
   7 /*
   8  * (c) 2008-2011 Adam Lackorzynski <adam@os.inf.tu-dresden.de>,
   9  *               Alexander Warg <warg@os.inf.tu-dresden.de>
  10  *     economic rights: Technische Universität Dresden (Germany)
  11  *
  12  * This file is part of TUD:OS and distributed under the terms of the
  13  * GNU General Public License 2.
  14  * Please see the COPYING-GPL-2 file for details.
  15  *
  16  * As a special exception, you may use this file as part of a free software
  17  * library without restriction.  Specifically, if other files instantiate
  18  * templates or use macros or inline functions from this file, or you compile
  19  * this file and link it with other files to produce an executable, this
  20  * file does not by itself cause the resulting executable to be covered by
  21  * the GNU General Public License.  This exception does not however
  22  * invalidate any other reasons why the executable file might be covered by
  23  * the GNU General Public License.
  24  */
  25
  26 #include <l4/sys/compiler.h>
  27 #include <l4/sys/utcb.h>
  28 #include <l4/sys/ipc.h>
  29
  30 /**
  31  * \defgroup l4_debugger_api Kernel Debugger
  32  * \ingroup api_calls_fiasco
  33  * \brief Kernel debugger related functionality.
  34  * \attention This API is subject to change!
  35  *
  36  * This is a debugging factility, any call to any function might be invalid.
  37  * Do not rely on it in any real code.
  38  *
  39  * <c>\#include <l4/sys/debugger.h></c>
  40  */
  41
  42 /**
  43  * The string name of kernel object.
  44  * \ingroup l4_debugger_api
  45  *
  46  * \param cap     Capability
  47  * \param name    Name
  48  *
  49  * This is a debugging factility, the call might be invalid.
  50  */
  51 L4_INLINE l4_msgtag_t
  52 l4_debugger_set_object_name(l4_cap_idx_t cap, const char *name) L4_NOTHROW;
  53
  54 /**
  55  * \internal
  56  */
  57 L4_INLINE l4_msgtag_t
  58 l4_debugger_set_object_name_u(l4_cap_idx_t cap, const char *name, l4_utcb_t *utcb) L4_NOTHROW;
  59
  60 /**
  61  * Get the globally unique ID of the object behind a capability.
  62  * \ingroup l4_debugger_api
  63  *
  64  * \param cap    Capability
  65  *
  66  * \return ~0UL on non-valid capability, ID otherwise
  67  *
  68  * This is a debugging factility, the call might be invalid.
  69  */
  70 L4_INLINE unsigned long
  71 l4_debugger_global_id(l4_cap_idx_t cap) L4_NOTHROW;
  72
  73 /**
  74  * \internal
  75  */
  76 L4_INLINE unsigned long
  77 l4_debugger_global_id_u(l4_cap_idx_t cap, l4_utcb_t *utcb) L4_NOTHROW;
  78
  79 /**
  80  * Get the globally unique ID of the object behind the kobject pointer.
  81  * \ingroup l4_debugger_api
  82  *
  83  * \param cap    Capability
  84  * \param kobjp  Kobject pointer
  85  *
  86  * \return ~0UL on non-valid capability or invalid kobject pointer, ID otherwise
  87  *
  88  * This is a debugging factility, the call might be invalid.
  89  */
  90 L4_INLINE unsigned long
  91 l4_debugger_kobj_to_id(l4_cap_idx_t cap, l4_addr_t kobjp) L4_NOTHROW;
  92
  93 /**
  94  * \internal
  95  */
  96 L4_INLINE unsigned long
  97 l4_debugger_kobj_to_id_u(l4_cap_idx_t cap, l4_addr_t kobjp, l4_utcb_t *utcb) L4_NOTHROW;
  98
  99 /**
 100  * \brief Query the log-id for a log type
 101  *
 102  * \param cap    Capability
 103  * \param  name  Name to query for.
 104  * \param  idx   Idx to start searching, start with 0
 105  *
 106  * \return ID, ~0U on error or no valid log name.
 107  *
 108  * This is a debugging factility, the call might be invalid.
 109  */
 110 L4_INLINE unsigned
 111 l4_debugger_query_log_typeid(l4_cap_idx_t cap, const char *name,
 112                              unsigned idx) L4_NOTHROW;
 113
 114 /**
 115  * \internal
 116  */
 117 L4_INLINE unsigned
 118 l4_debugger_query_log_typeid_u(l4_cap_idx_t cap, const char *name,
 119                                unsigned idx, l4_utcb_t *utcb) L4_NOTHROW;
 120
 121 /**
 122  * \brief Set or unset log.
 123  */
 124 L4_INLINE l4_msgtag_t
 125 l4_debugger_switch_log(l4_cap_idx_t cap, const char *name,
 126                        int on_off) L4_NOTHROW;
 127
 128 /**
 129  * \internal
 130  */
 131 L4_INLINE l4_msgtag_t
 132 l4_debugger_switch_log_u(l4_cap_idx_t cap, const char *name, int on_off,
 133                          l4_utcb_t *utcb) L4_NOTHROW;
 134
 135 enum
 136 {
 137   L4_DEBUGGER_NAME_SET_OP         = 0UL,
 138   L4_DEBUGGER_GLOBAL_ID_OP        = 1UL,
 139   L4_DEBUGGER_KOBJ_TO_ID_OP       = 2UL,
 140   L4_DEBUGGER_QUERY_LOG_TYPEID_OP = 3UL,
 141   L4_DEBUGGER_SWITCH_LOG_OP       = 4UL,
 142   L4_DEBUGGER_NAME_GET_OP         = 5UL,
 143 };
 144
 145 enum
 146 {
 147   L4_DEBUGGER_SWITCH_LOG_ON  = 1,
 148   L4_DEBUGGER_SWITCH_LOG_OFF = 0,
 149 };
 150
 151 /* IMPLEMENTATION -----------------------------------------------------------*/
 152
 153 #include <l4/sys/kernel_object.h>
 154
 155 L4_INLINE l4_msgtag_t
 156 l4_debugger_set_object_name_u(unsigned long cap,
 157                               const char *name, l4_utcb_t *utcb) L4_NOTHROW
 158 {
 159   unsigned int i;
 160   char *s = (char *)&l4_utcb_mr_u(utcb)->mr[1];
 161   l4_utcb_mr_u(utcb)->mr[0] = L4_DEBUGGER_NAME_SET_OP;
 162   for (i = 0;
 163        *name && i < (L4_UTCB_GENERIC_DATA_SIZE - 2) * sizeof(l4_umword_t) - 1;
 164        ++i, ++name, ++s)
 165     *s = *name;
 166   *s = 0;
 167   i = (i + sizeof(l4_umword_t) - 1) / sizeof(l4_umword_t);
 168   return l4_invoke_debugger(cap, l4_msgtag(0, i, 0, 0), utcb);
 169 }
 170
 171 L4_INLINE unsigned long
 172 l4_debugger_global_id_u(l4_cap_idx_t cap, l4_utcb_t *utcb) L4_NOTHROW
 173 {
 174   l4_utcb_mr_u(utcb)->mr[0] = L4_DEBUGGER_GLOBAL_ID_OP;
 175   if (l4_error_u(l4_invoke_debugger(cap, l4_msgtag(0, 1, 0, 0), utcb), utcb))
 176     return ~0UL;
 177   return l4_utcb_mr_u(utcb)->mr[0];
 178 }
 179
 180 L4_INLINE unsigned long
 181 l4_debugger_kobj_to_id_u(l4_cap_idx_t cap, l4_addr_t kobjp, l4_utcb_t *utcb) L4_NOTHROW
 182 {
 183   l4_utcb_mr_u(utcb)->mr[0] = L4_DEBUGGER_KOBJ_TO_ID_OP;
 184   l4_utcb_mr_u(utcb)->mr[1] = kobjp;
 185   if (l4_error_u(l4_invoke_debugger(cap, l4_msgtag(0, 2, 0, 0), utcb), utcb))
 186     return ~0UL;
 187   return l4_utcb_mr_u(utcb)->mr[0];
 188 }
 189
 190 L4_INLINE unsigned
 191 l4_debugger_query_log_typeid_u(l4_cap_idx_t cap, const char *name,
 192                                unsigned idx,
 193                                l4_utcb_t *utcb) L4_NOTHROW
 194 {
 195   unsigned l;
 196   l4_utcb_mr_u(utcb)->mr[0] = L4_DEBUGGER_QUERY_LOG_TYPEID_OP;
 197   l4_utcb_mr_u(utcb)->mr[1] = idx;
 198   l = __builtin_strlen(name);
 199   l = l > 31 ? 31 : l;
 200   __builtin_strncpy((char *)&l4_utcb_mr_u(utcb)->mr[2], name, 31);
 201   l = (l + 1 + sizeof(l4_umword_t) - 1) / sizeof(l4_umword_t);
 202   if (l4_error_u(l4_invoke_debugger(cap, l4_msgtag(0, 2 + l, 0, 0), utcb), utcb))
 203     return ~0U;
 204   return l4_utcb_mr_u(utcb)->mr[0];
 205 }
 206
 207 L4_INLINE l4_msgtag_t
 208 l4_debugger_switch_log_u(l4_cap_idx_t cap, const char *name, int on_off,
 209                          l4_utcb_t *utcb) L4_NOTHROW
 210 {
 211   unsigned l;
 212   l4_utcb_mr_u(utcb)->mr[0] = L4_DEBUGGER_SWITCH_LOG_OP;
 213   l4_utcb_mr_u(utcb)->mr[1] = on_off;
 214   l = __builtin_strlen(name);
 215   l = l > 31 ? 31 : l;
 216   __builtin_strncpy((char *)&l4_utcb_mr_u(utcb)->mr[2], name, 31);
 217   l = (l + 1 + sizeof(l4_umword_t) - 1) / sizeof(l4_umword_t);
 218   return l4_invoke_debugger(cap, l4_msgtag(0, 2 + l, 0, 0), utcb);
 219 }
 220
 221 L4_INLINE l4_msgtag_t
 222 l4_debugger_get_object_name_u(l4_cap_idx_t cap, unsigned id,
 223                               char *name, unsigned size,
 224                               l4_utcb_t *utcb) L4_NOTHROW
 225 {
 226   l4_msgtag_t t;
 227   l4_utcb_mr_u(utcb)->mr[0] = L4_DEBUGGER_NAME_GET_OP;
 228   l4_utcb_mr_u(utcb)->mr[1] = id;
 229   t = l4_invoke_debugger(cap, l4_msgtag(0, 2, 0, 0), utcb);
 230   __builtin_strncpy(name, (char *)&l4_utcb_mr_u(utcb)->mr[0], size);
 231   name[size - 1] = 0;
 232   return t;
 233 }
 234
 235
 236 L4_INLINE l4_msgtag_t
 237 l4_debugger_set_object_name(unsigned long cap,
 238                             const char *name) L4_NOTHROW
 239 {
 240   return l4_debugger_set_object_name_u(cap, name, l4_utcb());
 241 }
 242
 243 L4_INLINE unsigned long
 244 l4_debugger_global_id(l4_cap_idx_t cap) L4_NOTHROW
 245 {
 246   return l4_debugger_global_id_u(cap, l4_utcb());
 247 }
 248
 249 L4_INLINE unsigned long
 250 l4_debugger_kobj_to_id(l4_cap_idx_t cap, l4_addr_t kobjp) L4_NOTHROW
 251 {
 252   return l4_debugger_kobj_to_id_u(cap, kobjp, l4_utcb());
 253 }
 254
 255 L4_INLINE unsigned
 256 l4_debugger_query_log_typeid(l4_cap_idx_t cap, const char *name,
 257                              unsigned idx) L4_NOTHROW
 258 {
 259   return l4_debugger_query_log_typeid_u(cap, name, idx, l4_utcb());
 260 }
 261
 262 L4_INLINE l4_msgtag_t
 263 l4_debugger_switch_log(l4_cap_idx_t cap, const char *name,
 264                        int on_off) L4_NOTHROW
 265 {
 266   return l4_debugger_switch_log_u(cap, name, on_off, l4_utcb());
 267 }
 268
 269 L4_INLINE l4_msgtag_t
 270 l4_debugger_get_object_name(l4_cap_idx_t cap, unsigned id,
 271                             char *name, unsigned size) L4_NOTHROW
 272 {
 273   return l4_debugger_get_object_name_u(cap, id, name, size, l4_utcb());
 274 }