Toro Kernel: what changed

Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.

Title: ~~Toro kernel~~ Toro Kernel

Old	New		Line
1		-	~~#REDIRECT [[Toro Kernel]]~~
	1	+	A dedicated kernel for multi-threading applications
	2	+
	3	+	## Introduction
	4	+
	5	+	This wiki presents how to debug an application that is built with Toro and executes as a QEMU guest in Windows. This procedure however does not work for applications that are deployed as KVM-QEMU guests. In that case, the built-in gdbstub that is included in QEMU does not work correctly as it is unable to catch breakpoints or do step-by-step execution. To debug an application that is deployed as a KVM-QEMU guest, please follow the tutorial at <https://github.com/torokernel/torokernel/wiki/How-to-Debug-the-Kernel-and-the-Application-in-Toro>.
	6	+
	7	+	## On Windows
	8	+
	9	+	It's possible to develop Toro Kernel microservices on Windows.
	10	+
	11	+	### Building
	12	+
	13	+	- you'll need to have cross-compile linux binary utils
	14	+
	15	+
	16	+	those could be acquired from fpcup or fpcupdeluxe (https://github.com/LongDirtyAnimAlf/fpcupdeluxe/releases/download/crosslibs_v1.1/CrossLibsLinuxx64.zip)
	17	+
	18	+	- you can find a tutorial about how to get a cross-compiler in [1](https://github.com/torokernel/torokernel/wiki/How-to-get-a-Crosscompiler-of-Freepascal-for-a-Windows-host-and-Linux-target)
	19	+	- the project contain "build" utility complication as well. The utility produces an image from the resulting .elf file
	20	+
	21	+	### Running QEMU
	22	+
	23	+	- install QEmu for Windows
	24	+	- run the system specifying the built image
	25	+
	26	+	`qemu-system-x86_64 -hda HelloWorldMicroservice.img`
	27	+
	28	+	- on start qemu can complain about unknown or raw format of ".img" file.
	29	+
	30	+
	31	+	One might find the script files to build the Qemu recognizable image file formats: BuildVHDX.cmd and/or BuildVMDK.cmd
	32	+
	33	+	#### From Lazarus as Hosting Application
	34	+
	35	+	Lazarus can be configured to run QEmu as a hosting or launching application. Typically such approach is used for developing libraries, rather than virtual machines. Yet, the approach could be used for the virtual machine as well. While it works, it does introduce some difficulties when debugging is needed.
	36	+
	37	+	Open Run-\>Run Parameters... and specify QEmu as the host application.
	38	+
	39	+	On the command-line parameters specify -hda parameter, that should point to the produced image file.
	40	+
	41	+	Normally this would be an output file with .img extension.
	42	+
	43	+	\[\[Image:torokernel_run_params.png\]
	44	+
	45	+	#### From Lazarus as External Tool
	46	+
	47	+	Another approach is to launch from IDE QEmu manually as an External Tool.
	48	+
	49	+	The approach is semi-automatic, yet it's friendly with the remote debugging capabilities (which are covered below)
	50	+
	51	+	To create an external tool, click Tools-\>Configure External Tools.... (if there are some other tools configured you need to click "Add")
	52	+
	53	+	On the new dialog, the similar information regarding QEmu needs to be provided:
	54	+
	55	+	- the qemu executable
	56	+	- a parameter -hda specifying the target image file
	57	+	- additional parameters (i.e. network configuration)
	58	+
	59	+	![](/wiki-images/c/c9/Torokernel_external-tool.png)
	60	+
	61	+	Once the external tool configuration has been saved. The new section is added under "Tools" menu.
	62	+
	63	+	The execution can be invoked by either selecting the menu or assigning hot key combinations.
	64	+
	65	+	## Debugging
	66	+
	67	+	QEmu provides a built-in support for GDB remote debugging.
	68	+
	69	+	Remember, the debugging information must be enabled in the Project Options. It's recommended to use the EXTERNAL debug symbol file (-Xg) to keep the executable and the actual file image in a small size.
	70	+
	71	+	### Manual
	72	+
	73	+	- run QEmu with enabling gdb (-s) and also requesting the QEmu to halt until getting the "continue" signal from gdb (-S)
	74	+
	75	+	`qemu-system-x86_64 -s -S -hda HelloWorldMicroservice.img`
	76	+
	77	+
	78	+	The expected result is that Qemu window will halt with the message that "vga" system has not been initialized yet (and doing nothing)
	79	+
	80	+	-s - configures the default remote GDB mode for the use of TCP socket for port 1234
	81	+
	82	+	- run the debugger, and provide the previously complied binary file as its gdb target. (The file is needed to load debugging information)
	83	+
	84	+	`gdb HelloWorldMicroservice`
	85	+
	86	+	- after that run the remote target command
	87	+
	88	+	`(gdb)> target remote localhost:1234`
	89	+
	90	+
	91	+	The command makes gdb connect to the specified address. In which case this would be Qemu running locally at port 1234.
	92	+
	93	+	- setup the debugging information (i.e. breakpoints, etc)
	94	+
	95	+
	96	+	The debugging information in the compiled binary contains the information necessary to work with binary during debugging.
	97	+
	98	+	Example
	99	+
	100	+	`(gdb)> b HelloWorldMicroservice.pas:250`
	101	+
	102	+
	103	+	sets a breakpoint HelloWorldMicroservice at the line that outputs "ToroService: listening on port xxxx ..."
	104	+
	105	+	- "continue" the process.
	106	+
	107	+	`(gdb)> continue`
	108	+
	109	+	### From Lazarus IDE
	110	+
	111	+	It's possible to use Gdb with Lazarus IDE to debug remote applications.
	112	+
	113	+	The Lazarus IDE handles the debugger in 2 possible ways:
	114	+
	115	+	1. By default Lazarus attempts to launch the debugger first, and let debugger launch the debugged application.
	116	+	2. For remote debugging the remote application is expected to be launched outside of Lazarus IDE project run flow:
	117	+
	118	+	How to launch the process to be debugged for remte debugging depends on the version of Lazarus:
	119	+
	120	+	1. for the trunk version of lazarus, see the explanation in the section below on init exec.
	121	+	2. For the released (2.0.x) version of lazarus the method is explained here. This method can of course still be used in trunk.
	122	+
	123	+	In both cases, the most important thing to remember is to have
	124	+
	125	+	`-s `\
	126	+	`-S`
	127	+
	128	+	parameters added to the Qemu command line. (as described above "-s" configures the network port for GDB, while "-S" makes sure QEmu would wait for the debugger to connect)
	129	+
	130	+	The "debugger" needs to be configured as following.
	131	+
	132	+	- type should be set to (gdbserver)
	133	+	- executable should be the same as the Lazarus supplied gdb.exe.
	134	+	- Debugger_Remote_HostName should be set to "localhost" (you are running Qemu locally)
	135	+	- Debugger_Remote_Post should be set to 1234. (This is dictated by "-s" parameter passed to QEmu)
	136	+
	137	+	![](/wiki-images/1/1a/Torokernel_debugger.png)
	138	+
	139	+	#### Start Qemu As External Tool
	140	+
	141	+	Run the QEmu via configured "External Tool" (or manually). When ran you should see "Guest has not initialized the display (yet)". That means that Qemu is waiting for the debugger to connect. ![](/wiki-images/5/58/Torokernel_qemu.png)
	142	+
	143	+	IMPORTANT - make sure that "Run Parameters" don't have Host Application or Launch Application configured. If they're configured it will prevent the debugger from loading proper symbol files and will prevent the debugging.
	144	+
	145	+	Hit "Run" project (F9) in Lazarus IDE.
	146	+
	147	+	With the gdb connected to the QEmu you should see the services run as they should.
	148	+
	149	+	Lazarus IDE will allow you to set the breakpoints, inspect variables and callstack as needed.
	150	+
	151	+	In order to terminate the QEmu process one should either close QEmu window or press "Alt+Ctrl+Q". ![](/wiki-images/5/52/Toro_activedebug.png)
	152	+
	153	+	#### Using Init Exec of Remote Debugger
	154	+
	155	+	In Lazarus trunk there's an extension of gdbserver available, that allows to run QEmu automatically.
	156	+
	157	+	Two additional options were added and should be configured in the following manner:
	158	+
	159	+	- InitExec_Mode = ieRunCloseOnStop (starts QEmu and closes when the debugging is done)
	160	+	- InitExec_RemoteTarget = the command line that would open up QEmu PRIOR to the debugger trying to connect.
	161	+
	162	+	![](/wiki-images/7/70/Toro_debug2.png)
	163	+
	164	+	## See also
	165	+
	166	+	- <https://github.com/torokernel/torokernel> - source code
	167	+	- <https://torokernel.io> - the official website
	168	+	- <https://www.qemu.org/download/#windows> - QEmu Windows download
	169	+	- <https://github.com/torokernel/torokernel/wiki/How-to-Debug-the-Kernel-and-the-Application-in-Toro> - Debugging of Toro Appliances
	170	+
	171	+	---
	172	+	From the Free Pascal wiki, page "Toro Kernel", as it stood on 2021-03-14 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
	173	+	Category: Operating Systems and Platforms
	174	+	Category: Tutorials

Back to history