docs: add readme for samples by sohshri796-cell · Pull Request #37 · vedantmalkar/AstraRTOS

sohshri796-cell · 2026-07-14T13:46:29Z

Adds a README.md file to the samples directory to inform users about how to simulate the samples and, explains the modifications needed to be done for emulation in QEMU. system_init() must be commented during emulation in QEMU as it cannot emulate the hardware initialisation that only needs to be done for actual hardware.

Closes #35

mt-tass · 2026-07-14T14:41:55Z

I dont think changing the Makefile everytime for a different sample is a good idea
ideally we should have a different target for samples, something like
make sample PATH=samples/blink/blink.c
so that without editing the makefile we can build desired sample

mt-tass · 2026-07-14T14:43:59Z

+then,  
+```make flash```
+
+But to simulate in qemu, u need to modify the code a little bit,  


Suggested change

But to simulate in qemu, u need to modify the code a little bit,

But to simulate in qemu, you need to modify the code a little bit,

i think you should remove a little bit part also

mt-tass · 2026-07-14T14:46:43Z

I dont think changing the Makefile everytime for a different sample is a good idea ideally we should have a different target for samples, something like make sample PATH=samples/blink/blink.c so that without editing the makefile we can build desired sample

@vedantmalkar @Paarth-Shirsat

vedantmalkar

I would say rewrite the README with these changes and more professional wording overall

also add commands to run the samples in qemu in a section

vedantmalkar · 2026-07-14T14:41:02Z

@@ -0,0 +1,31 @@
+ # Samples


Suggested change

# Samples

# Samples

remove space

vedantmalkar · 2026-07-14T14:41:25Z

@@ -0,0 +1,31 @@
+ # Samples
+
+This directory contains sample applications demonstrating the features of this AstraRTOS. 


Suggested change

This directory contains sample applications demonstrating the features of this AstraRTOS.

This directory contains sample applications demonstrating the features of AstraRTOS.

wording

vedantmalkar · 2026-07-14T14:55:53Z

+
+To run a specific sample, open the `Makefile` in this directory and update it to point to your chosen sample instead of the default `main.c`. 
+
+For example:


Suggested change

For example:

For example to run the mutex sample:

give real example

vedantmalkar · 2026-07-14T15:00:36Z

+For example:
+```makefile
+# In your Makefile, swap the source file:
+C_SOURCES = samples/your_chosen_sample.c ..... #and the rest of the files


Suggested change

C_SOURCES = samples/your_chosen_sample.c ..... #and the rest of the files

C_SOURCES = samples/mutex_basic/main.c ...

vedantmalkar · 2026-07-14T15:08:04Z

+For running them on hardware use:  
+``` make ```  
+then,  
+```make flash```


remove then, and keep both make and make flash under same set of backticks, commands under eachother

vedantmalkar · 2026-07-14T15:09:01Z

+then,  
+```make flash```
+
+But to simulate in qemu, u need to modify the code a little bit,  


Suggested change

But to simulate in qemu, u need to modify the code a little bit,

But to simulate in qemu, you need to modify the code a little bit,

vedantmalkar · 2026-07-14T15:12:31Z

+ system_init() performs hardware initialization (such as clock configuration) that is something thats done on a real STM32 hardware.  
+ QEMU does not fully emulate the hardware, so the initialization code may wait indefinitely for hardware-ready flags that never become set. Commenting out this call allows the program to continue running under QEMU.


could be written better and more in depth

vedantmalkar · 2026-07-14T15:17:34Z

I dont think changing the Makefile everytime for a different sample is a good idea ideally we should have a different target for samples, something like make sample PATH=samples/blink/blink.c so that without editing the makefile we can build desired sample

yeah this seems like a good idea, worth implementing

vedantmalkar · 2026-07-14T15:19:10Z

+
+---
+
+To run a specific sample, open the `Makefile` in this directory and update it to point to your chosen sample instead of the default `main.c`. 


Suggested change

To run a specific sample, open the `Makefile` in this directory and update it to point to your chosen sample instead of the default `main.c`.

To run a specific sample, replace the entry point in the top level `Makefile` from `app/main.c` to the sample you want

wording

vedantmalkar · 2026-07-14T15:23:23Z

@sohshri796-cell commit structure looks great, address the reviews and word the readme better

vedantmalkar · 2026-07-14T17:44:42Z

+system_init() is responsible for configuring critical low-level subsystems, primarily the Reset and Clock Control (RCC) unit. This involves enabling internal/external oscillators (HSI/HSE), configuring the Phase-Locked Loops (PLL), and switching the system clock source.
+Because QEMU focuses on CPU instruction emulation rather than register-accurate peripheral simulation, it does not fully simulate the RCC state transitions. Consequently, these hardware-ready flags are never set within the emulator, causing the program to trap itself in an infinite loop before the RTOS kernel or scheduler can boot.


Suggested change

system_init() is responsible for configuring critical low-level subsystems, primarily the Reset and Clock Control (RCC) unit. This involves enabling internal/external oscillators (HSI/HSE), configuring the Phase-Locked Loops (PLL), and switching the system clock source.

Because QEMU focuses on CPU instruction emulation rather than register-accurate peripheral simulation, it does not fully simulate the RCC state transitions. Consequently, these hardware-ready flags are never set within the emulator, causing the program to trap itself in an infinite loop before the RTOS kernel or scheduler can boot.

`system_init()` is responsible for configuring critical low-level subsystems, primarily the Reset and Clock Control (RCC) unit. This involves enabling internal/external oscillators (HSI/HSE), configuring the Phase-Locked Loops (PLL), and switching the system clock source.

Because QEMU focuses on CPU instruction emulation rather than register-accurate peripheral simulation, it does not fully simulate the RCC state transitions. Consequently, these hardware-ready flags are never set within the emulator, causing the program to trap itself in an infinite loop before the RTOS kernel or scheduler can boot.

vedantmalkar · 2026-07-14T17:46:17Z

add a section telling for the make qemu command

mt-tass · 2026-07-15T16:24:27Z

dont add a new commit, we always group the changes for a single file or feature into one commit

…how to simulate the samples and, explains the modifications needed to be done for emulation in QEMU. system_init() must be commented during emulation in QEMU as it cannot emulate the hardware initialisation that only needs to be done for actual hardware. Closes vedantmalkar#35 Signed-off-by: Sohshri <sohshri796@gmail.com>

mt-tass · 2026-07-16T16:44:52Z

also your commit doesnt have a title ?

mt-tass reviewed Jul 14, 2026

View reviewed changes

vedantmalkar reviewed Jul 14, 2026

View reviewed changes

sohshri796-cell force-pushed the docs/samples-readme branch from 254dfb5 to 9bca499 Compare July 14, 2026 16:23

vedantmalkar reviewed Jul 14, 2026

View reviewed changes

sohshri796-cell force-pushed the docs/samples-readme branch from 9bca499 to 15ef8fd Compare July 15, 2026 12:04

vedantmalkar reviewed Jul 15, 2026

View reviewed changes

Comment thread samples/README.md Outdated

sohshri796-cell force-pushed the docs/samples-readme branch from 26c8051 to 50d8463 Compare July 16, 2026 15:55

mt-tass suggested changes Jul 16, 2026

View reviewed changes

	But to simulate in qemu, u need to modify the code a little bit,
	But to simulate in qemu, you need to modify the code a little bit,

		@@ -0,0 +1,31 @@
		# Samples

		This directory contains sample applications demonstrating the features of this AstraRTOS.


		To run a specific sample, open the `Makefile` in this directory and update it to point to your chosen sample instead of the default `main.c`.

		For example:

	C_SOURCES = samples/your_chosen_sample.c ..... #and the rest of the files
	C_SOURCES = samples/mutex_basic/main.c ...

		system_init() performs hardware initialization (such as clock configuration) that is something thats done on a real STM32 hardware.
		QEMU does not fully emulate the hardware, so the initialization code may wait indefinitely for hardware-ready flags that never become set. Commenting out this call allows the program to continue running under QEMU.

	To run a specific sample, open the `Makefile` in this directory and update it to point to your chosen sample instead of the default `main.c`.
	To run a specific sample, replace the entry point in the top level `Makefile` from `app/main.c` to the sample you want

		system_init() is responsible for configuring critical low-level subsystems, primarily the Reset and Clock Control (RCC) unit. This involves enabling internal/external oscillators (HSI/HSE), configuring the Phase-Locked Loops (PLL), and switching the system clock source.
		Because QEMU focuses on CPU instruction emulation rather than register-accurate peripheral simulation, it does not fully simulate the RCC state transitions. Consequently, these hardware-ready flags are never set within the emulator, causing the program to trap itself in an infinite loop before the RTOS kernel or scheduler can boot. No newline at end of file

Conversation

sohshri796-cell commented Jul 14, 2026

Uh oh!

mt-tass commented Jul 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mt-tass commented Jul 14, 2026

Uh oh!

vedantmalkar left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vedantmalkar commented Jul 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vedantmalkar commented Jul 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vedantmalkar commented Jul 14, 2026

Uh oh!

Uh oh!

mt-tass commented Jul 15, 2026

Uh oh!

mt-tass commented Jul 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants