Toro Kernel: what changed

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

Old	New		Line
1	1		A dedicated kernel for multi-threading applications
2	2
3	3		## Introduction
4	4
5	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	6
7	7		## On Windows
8	8
9	9		It's possible to develop Toro Kernel microservices on Windows.
10	10
11	11		### Building
12	12
13	13		- you'll need to have cross-compile linux binary utils
14	14
15	15
16	16		those could be acquired from fpcup or fpcupdeluxe (https://github.com/LongDirtyAnimAlf/fpcupdeluxe/releases/download/crosslibs_v1.1/CrossLibsLinuxx64.zip)
17	17
18	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	19		- the project contain "build" utility complication as well. The utility produces an image from the resulting .elf file
20	20
21	21		### Running QEMU
22	22
23	23		- install QEmu for Windows
24	24		- run the system specifying the built image
25	25
26		-	~~`qemu-system-x86_64 -hda HelloWorldMicroservice.img`~~
	26	+	```text
	27	+	qemu-system-x86_64 -hda HelloWorldMicroservice.img
	28	+	```
27	29
28	30		- on start qemu can complain about unknown or raw format of ".img" file.
29	31
30	32
31	33		One might find the script files to build the Qemu recognizable image file formats: BuildVHDX.cmd and/or BuildVMDK.cmd
32	34
33	35		#### From Lazarus as Hosting Application
34	36
35	37		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	38
37	39		Open Run-\>Run Parameters... and specify QEmu as the host application.
38	40
39	41		On the command-line parameters specify -hda parameter, that should point to the produced image file.
40	42
41	43		Normally this would be an output file with .img extension.
42	44
43	45		\[\[Image:torokernel_run_params.png\]
44	46
45	47		#### From Lazarus as External Tool
46	48
47	49		Another approach is to launch from IDE QEmu manually as an External Tool.
48	50
49	51		The approach is semi-automatic, yet it's friendly with the remote debugging capabilities (which are covered below)
50	52
51	53		To create an external tool, click Tools-\>Configure External Tools.... (if there are some other tools configured you need to click "Add")
52	54
53	55		On the new dialog, the similar information regarding QEmu needs to be provided:
54	56
55	57		- the qemu executable
56	58		- a parameter -hda specifying the target image file
57	59		- additional parameters (i.e. network configuration)
58	60
59	61		![](/wiki-images/c/c9/Torokernel_external-tool.png)
60	62
61	63		Once the external tool configuration has been saved. The new section is added under "Tools" menu.
62	64
63	65		The execution can be invoked by either selecting the menu or assigning hot key combinations.
64	66
65	67		## Debugging
66	68
67	69		QEmu provides a built-in support for GDB remote debugging.
68	70
69	71		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	72
71	73		### Manual
72	74
73	75		- run QEmu with enabling gdb (-s) and also requesting the QEmu to halt until getting the "continue" signal from gdb (-S)
74	76
75		-	~~`qemu-system-x86_64 -s -S -hda HelloWorldMicroservice.img`~~
	77	+	```text
	78	+	qemu-system-x86_64 -s -S -hda HelloWorldMicroservice.img
	79	+	```
76	80
77	81
78	82		The expected result is that Qemu window will halt with the message that "vga" system has not been initialized yet (and doing nothing)
79	83
80	84		-s - configures the default remote GDB mode for the use of TCP socket for port 1234
81	85
82	86		- run the debugger, and provide the previously complied binary file as its gdb target. (The file is needed to load debugging information)
83	87
84		-	~~`gdb HelloWorldMicroservice`~~
	88	+	```text
	89	+	gdb HelloWorldMicroservice
	90	+	```
85	91
86	92		- after that run the remote target command
87	93
88		-	~~`(gdb)> target remote localhost:1234`~~
	94	+	```text
	95	+	(gdb)> target remote localhost:1234
	96	+	```
89	97
90	98
91	99		The command makes gdb connect to the specified address. In which case this would be Qemu running locally at port 1234.
92	100
93	101		- setup the debugging information (i.e. breakpoints, etc)
94	102
95	103
96	104		The debugging information in the compiled binary contains the information necessary to work with binary during debugging.
97	105
98	106		Example
99	107
100		-	~~`(gdb)> b HelloWorldMicroservice.pas:250`~~
	108	+	```text
	109	+	(gdb)> b HelloWorldMicroservice.pas:250
	110	+	```
101	111
102	112
103	113		sets a breakpoint HelloWorldMicroservice at the line that outputs "ToroService: listening on port xxxx ..."
104	114
105	115		- "continue" the process.
106	116
107		-	~~`(gdb)> continue`~~
	117	+	```text
	118	+	(gdb)> continue
	119	+	```
108	120
109	121		### From Lazarus IDE
110	122
111	123		It's possible to use Gdb with Lazarus IDE to debug remote applications.
112	124
113	125		The Lazarus IDE handles the debugger in 2 possible ways:
114	126
115	127		1. By default Lazarus attempts to launch the debugger first, and let debugger launch the debugged application.
116	128		2. For remote debugging the remote application is expected to be launched outside of Lazarus IDE project run flow:
117	129
118	130		How to launch the process to be debugged for remte debugging depends on the version of Lazarus:
119	131
120	132		1. for the trunk version of lazarus, see the explanation in the section below on init exec.
121	133		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	134
123	135		In both cases, the most important thing to remember is to have
124	136
125		-	~~`-s `\~~
126		-	~~`-S`~~
	137	+	```text
	138	+	-s
	139	+	-S
	140	+	```
127	141
128	142		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	143
130	144		The "debugger" needs to be configured as following.
131	145
132	146		- type should be set to (gdbserver)
133	147		- executable should be the same as the Lazarus supplied gdb.exe.
134	148		- Debugger_Remote_HostName should be set to "localhost" (you are running Qemu locally)
135	149		- Debugger_Remote_Post should be set to 1234. (This is dictated by "-s" parameter passed to QEmu)
136	150
137	151		![](/wiki-images/1/1a/Torokernel_debugger.png)
138	152
139	153		#### Start Qemu As External Tool
140	154
141	155		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	156
143	157		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	158
145	159		Hit "Run" project (F9) in Lazarus IDE.
146	160
147	161		With the gdb connected to the QEmu you should see the services run as they should.
148	162
149	163		Lazarus IDE will allow you to set the breakpoints, inspect variables and callstack as needed.
150	164
151	165		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	166
153	167		#### Using Init Exec of Remote Debugger
154	168
155	169		In Lazarus trunk there's an extension of gdbserver available, that allows to run QEmu automatically.
156	170
157	171		Two additional options were added and should be configured in the following manner:
158	172
159	173		- InitExec_Mode = ieRunCloseOnStop (starts QEmu and closes when the debugging is done)
160	174		- InitExec_RemoteTarget = the command line that would open up QEmu PRIOR to the debugger trying to connect.
161	175
162	176		![](/wiki-images/7/70/Toro_debug2.png)
163	177
164	178		## See also
165	179
166	180		- <https://github.com/torokernel/torokernel> - source code
167	181		- <https://torokernel.io> - the official website
168	182		- <https://www.qemu.org/download/#windows> - QEmu Windows download
169	183		- <https://github.com/torokernel/torokernel/wiki/How-to-Debug-the-Kernel-and-the-Application-in-Toro> - Debugging of Toro Appliances
170	184
171	185		---
172	186		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	187		Category: Operating Systems and Platforms
174	188		Category: Tutorials

Back to history