essence-os/help/Debugging.md

# Debugging

This file has not been written yet. `Notes from Discord.txt` may contain a few unorganized pointers, though.

TODO

## GDB commands

Here are various commands for GDB for inspecting kernel state. Put these in your `.gdbinit` file if you want to use them. *Please note that some of these may be out of date.*

The `ldcx` command is used to load the RIP, RSP and RBP registers from an `InterruptContext`.

	define ldcx
		set $new_rip = context->rip
		set $new_rsp = context->rsp
		set $new_rbp = context->rbp
		set $rip = $new_rip
		set $rsp = $new_rsp
		set $rbp = $new_rbp
		set $rip = $new_rip
	end

	define ldcx32
		set $new_eip = context->eip
		set $new_esp = context->esp
		set $new_ebp = context->ebp
		set $eip = $new_eip
		set $esp = $new_esp
		set $ebp = $new_ebp
		set $eip = $new_eip
	end

The `print_page_list` command follows and prints a linked list from the physical memory manager's page frame database.

	define print_page_list
		set $index = $arg0
		while $index
			set $page_frame = pmm.pageFrames[$index]
			p $index
			p $page_frame
			set $index = $page_frame.list.next
		end
	end

Here are some Python commands. `PrintKernelMMSpaceRegions` prints the memory regions in the kernel's memory space. `PrintDeviceTree` prints all devices in the kernel's device tree, including the number of open reference to each device. `PrintBootFileSystemNodes` prints all the loaded nodes in the boot filesystem ("0:/"). `PrintCachedNodes` prints all the nodes that are in cached but have no open references. This also installs hooks for the gf GDB frontend watch window for `EsRectangle` and `Array<T>`.

	py

	def EsRectangleHook(item, field):
		if field:
			if field == '[width]':  return gdb.Value(int(item['r']) - item['l'])
			if field == '[height]': return gdb.Value(int(item['b']) - item['t'])
		else:
			print('[width]')
			print('[height]')
			_gf_fields_recurse(item)

	def EsArrayHook(item, field):
		if field:
			return item['array'][int(field[1:-1])]
		else:
			print('(d_arr)',ArrayLength(item['array']))

	def ArrayLength(arrayBase):
		if int(arrayBase):
			return int(gdb.parse_and_eval('(_ArrayHeader*)' + str(int(arrayBase)) + '-1')['length'])
		return 0

	def PrintAVLKey(key, end='\n'):
		charPointer = gdb.lookup_type('char').pointer()
		nameBytes = int(key['longKeyBytes'])
		name = key['longKey'].cast(charPointer)
		print(name.string('utf-8', 'strict', nameBytes), end=end)

	def PrintNodePath(node, end='\n'):
		if isinstance(node, str):
			node = gdb.parse_and_eval(node)
		parent = node['directoryEntry']['parent']
		if int(parent):
			PrintNodePath(parent, end='/')
		key = node['directoryEntry']['item']['key']
		PrintAVLKey(key, end)

	def PrintCachedNodes():
		item = gdb.parse_and_eval('fs.cachedNodes.firstItem')
		offset = int(gdb.parse_and_eval('(uintptr_t)(&((KNode*)0)->cacheItem)-(uintptr_t)((KNode*)0)'))
		while int(item):
			node = gdb.parse_and_eval('(KNode*)' + str(int(item) - offset))
			PrintNodePath(node)
			item = item['nextItem']

	def PrintDirectoryEntryAndChildren(directoryEntry, indent=''):
		if isinstance(directoryEntry, str):
			directoryEntry = gdb.parse_and_eval(directoryEntry)
		print('"', end='')
		PrintAVLKey(directoryEntry['item']['key'], end='"')
		node = directoryEntry['node']
		recurse = None
		if int(node):
			print(', node H' + str(int(node['handles'])), end='')
			if int(directoryEntry['type']) == 0x10:
				print(', dir', end='')
				fsDirectory = node.cast(gdb.lookup_type('FSDirectory').pointer())
				recurse = fsDirectory['entries']['root']
		print('')
		if recurse:
			RecurseIntoNodeAVLTree(recurse, indent + '\t')
		
	def RecurseIntoNodeAVLTree(item, indent):
		if not int(item):
			return
		RecurseIntoNodeAVLTree(item['children'][0], indent)
		RecurseIntoNodeAVLTree(item['children'][1], indent)
		print(indent, end='')
		PrintDirectoryEntryAndChildren(item['thisItem'], indent)
		
	def PrintBootFileSystemNodes():
		PrintDirectoryEntryAndChildren('fs.bootFileSystem.rootDirectory.directoryEntry')

	def RecurseIntoDeviceTree(device, indent):
		print(indent, device['cDebugName'].string('utf-8'), device['handles'])
		childCount = ArrayLength(device['children']['array'])
		for i in range(childCount):
			RecurseIntoDeviceTree(device['children']['array'][i], indent + ' | ')

	def PrintDeviceTree():
		RecurseIntoDeviceTree(gdb.parse_and_eval('deviceTreeRoot'), '')

	def PrintMemoryRegion(region):
		print('region: ' + hex(int(region)))
		print('\tbaseAddress: ' + hex(int(region['baseAddress'])))
		print('\tsize: ' + str(4 * int(region['pageCount'])) + ' KB')
		flags = int(region['flags'])
		print('\tflags: ' + hex(flags))
		if flags & 0x200:
			print('\tnormal region')
			print('\t\tcommit: ' + str(4 * int(region['data']['normal']['commitPageCount'])) + ' KB')
		
	def RecurseIntoMMSpaceAVLTree(item):
		if not int(item):
			return
		RecurseIntoMMSpaceAVLTree(item['children'][0])
		RecurseIntoMMSpaceAVLTree(item['children'][1])
		PrintMemoryRegion(item['thisItem'])
		
	def PrintKernelMMSpaceRegions():
		RecurseIntoMMSpaceAVLTree(gdb.parse_and_eval('_kernelMMSpace.usedRegions.root'))

	gf_hooks = { 'EsRectangle': EsRectangleHook, 'Array': EsArrayHook }

	end