1// vi:set ft=cpp: -*- Mode: C++ -*- 2/** 3 * \file 4 * The debugger interface specifies common debugging related definitions. 5 */ 6/* 7 * (c) 2010-2011 Adam Lackorzynski <adam@os.inf.tu-dresden.de>, 8 * Alexander Warg <warg@os.inf.tu-dresden.de> 9 * economic rights: Technische Universität Dresden (Germany) 10 * 11 * This file is part of TUD:OS and distributed under the terms of the 12 * GNU General Public License 2. 13 * Please see the COPYING-GPL-2 file for details. 14 * 15 * As a special exception, you may use this file as part of a free software 16 * library without restriction. Specifically, if other files instantiate 17 * templates or use macros or inline functions from this file, or you compile 18 * this file and link it with other files to produce an executable, this 19 * file does not by itself cause the resulting executable to be covered by 20 * the GNU General Public License. This exception does not however 21 * invalidate any other reasons why the executable file might be covered by 22 * the GNU General Public License. 23 */ 24#pragma once 25 26#include <l4/sys/debugger.h> 27#include <l4/sys/kobject> 28 29namespace L4 { 30 31/** 32 * C++ kernel debugger API. 33 * 34 * \attention This API is subject to change! Do not rely on it in production 35 * code. 36 * 37 * This API is to be used for debugging exclusively. 38 * 39 * This is the API for accessing kernel-debugger functionality from user-level 40 * programs. Specifically, it provides functionality to enrich the kernel 41 * debugger with insights into the program. The purpose is to facilitate 42 * debugging with the kernel debugger. For instance, a developer might choose 43 * to name the threads of her program so that she can find them in the kernel 44 * debugger thread list. 45 * 46 * This API interacts with a kernel object that interfaces with the kernel 47 * debugger, the jdb-kernel object. The jdb-kernel object is fix and only 48 * available when the kernel debugger is built into the microkernel. The 49 * developer needs to pass the capability through to her program. 50 * 51 * \includefile{l4/sys/debugger} 52 */ 53class Debugger : public Kobject_t<Debugger, Kobject, L4_PROTO_DEBUGGER> 54{ 55public: 56 enum 57 { 58 Switch_log_on = L4_DEBUGGER_SWITCH_LOG_ON, 59 Switch_log_off = L4_DEBUGGER_SWITCH_LOG_OFF, 60 }; 61 62 /** 63 * \copybrief l4_debugger_set_object_name() 64 * 65 * \param name Name 66 * \param utcb The UTCB to use for the operation. 67 * 68 * \return System call return tag. 69 */ 70 l4_msgtag_t set_object_name(const char *name, 71 l4_utcb_t *utcb = l4_utcb()) noexcept 72 { return l4_debugger_set_object_name_u(cap(), name, utcb); } 73 74 /** 75 * \copybrief l4_debugger_global_id() 76 * 77 * \param utcb The UTCB to use for the operation. 78 * 79 * \retval ~0UL The capability is invalid. 80 * \retval >=0 The global debugger id. 81 */ 82 unsigned long global_id(l4_utcb_t *utcb = l4_utcb()) noexcept 83 { return l4_debugger_global_id_u(cap(), utcb); } 84 85 /** 86 * \copybrief l4_debugger_kobj_to_id() 87 * 88 * \param kobjp Kobject pointer 89 * \param utcb The UTCB to use for the operation. 90 * 91 * \retval ~0UL The capability or the Kobject pointer are invalid. 92 * \retval >=0 The globally unique id. 93 */ 94 unsigned long kobj_to_id(l4_addr_t kobjp, 95 l4_utcb_t *utcb = l4_utcb()) noexcept 96 { return l4_debugger_kobj_to_id_u(cap(), kobjp, utcb); } 97 98 /** 99 * \copybrief l4_debugger_query_log_typeid() 100 * 101 * \param name Name to query for. 102 * \param idx Idx to start searching, start with 0 103 * \param utcb The UTCB to use for the operation. 104 * 105 * \retval >=0 Id 106 * \retval <0 Error 107 */ 108 long query_log_typeid(const char *name, unsigned idx, 109 l4_utcb_t *utcb = l4_utcb()) noexcept 110 { return l4_debugger_query_log_typeid_u(cap(), name, idx, utcb); } 111 112 /** 113 * \copybrief l4_debugger_query_log_name() 114 * 115 * \param idx ID to query. 116 * \param[out] name Buffer to copy name to. The buffer must be 117 * allocated by the caller. 118 * \param namelen Buffer length of name. 119 * \param[out] shortname Buffer to copy `shortname` to. The buffer must 120 * be allocated by the caller. 121 * \param shortnamelen Buffer length of `shortname`. 122 * \param utcb The UTCB to use for the operation. 123 * 124 * \retval 0 Success 125 * \retval <0 Error 126 */ 127 long query_log_name(unsigned idx, 128 char *name, unsigned namelen, 129 char *shortname, unsigned shortnamelen, 130 l4_utcb_t *utcb = l4_utcb()) noexcept 131 { 132 return l4_debugger_query_log_name_u(cap(), idx, name, namelen, 133 shortname, shortnamelen, utcb); 134 } 135 136 /** 137 * \copybrief l4_debugger_switch_log() 138 * \param name Name of the log type. 139 * \param on_off 1: turn log on, 0: turn log off 140 * \param utcb The UTCB to use for the operation. 141 * 142 * \return Syscall return tag 143 */ 144 l4_msgtag_t switch_log(const char *name, unsigned on_off, 145 l4_utcb_t *utcb = l4_utcb()) noexcept 146 { return l4_debugger_switch_log_u(cap(), name, on_off, utcb); } 147 148 /** 149 * Get name of object with Id `id`. 150 * 151 * \param id Id of the object whose name is asked. 152 * \param[out] name Buffer to copy the name into. The buffer must be 153 * allocated by the caller. 154 * \param size Length of the `name` buffer. 155 * \param utcb The UTCB to use for the operation. 156 * 157 * \return Syscall return tag 158 */ 159 l4_msgtag_t get_object_name(unsigned id, char *name, unsigned size, 160 l4_utcb_t *utcb = l4_utcb()) noexcept 161 { return l4_debugger_get_object_name_u(cap(), id, name, size, utcb); } 162}; 163} 164