diff --git a/scripts/icestorm/Makefile b/scripts/icestorm/Makefile
index 7ead63c..7a3ece3 100644
--- a/scripts/icestorm/Makefile
+++ b/scripts/icestorm/Makefile
@@ -2,6 +2,9 @@ TOOLCHAIN_PREFIX = riscv32-unknown-elf-
 
 all: example.bin
 
+## -------------------
+## firmware generation
+
 firmware.elf: firmware.S firmware.c firmware.lds
 	$(TOOLCHAIN_PREFIX)gcc -march=rv32i -Os -ffreestanding -nostdlib -o $@ firmware.S firmware.c \
 			--std=gnu99 -Wl,-Bstatic,-T,firmware.lds,-Map,firmware.map,--strip-debug -lgcc
@@ -14,6 +17,9 @@ firmware.bin: firmware.elf
 firmware.hex: firmware.bin
 	python3 ../../firmware/makehex.py $< 128 > $@
 
+## ------------------------------
+## main flow: synth/p&r/bitstream
+
 synth.json: example.v ../../picorv32.v firmware.hex
 	yosys -v3 -l synth.log -p 'synth_ice40 -top top -json $@; write_verilog -attr2comment synth.v' $(filter %.v, $^)
 
@@ -23,6 +29,9 @@ example.asc: synth.json example.pcf
 example.bin: example.asc
 	icepack $< $@
 
+## -----------------
+## icarus simulation
+
 example_tb.vvp: example.v example_tb.v ../../picorv32.v firmware.hex
 	iverilog -o $@ -s testbench $(filter %.v, $^)
 	chmod -x $@
@@ -33,6 +42,9 @@ example_sim: example_tb.vvp
 example_sim_vcd: example_tb.vvp
 	vvp -N $< +vcd
 
+## ---------------------
+## post-synth simulation
+
 synth_tb.vvp: example_tb.v synth.json
 	iverilog -o $@ -s testbench synth.v example_tb.v `yosys-config --datdir/ice40/cells_sim.v`
 	chmod -x $@
@@ -43,6 +55,9 @@ synth_sim: synth_tb.vvp
 synth_sim_vcd: synth_tb.vvp
 	vvp -N $< +vcd
 
+## ---------------------
+## post-route simulation
+
 route.v: example.asc example.pcf
 	icebox_vlog -L -n top -sp example.pcf $< > $@
 
@@ -56,6 +71,9 @@ route_sim: route_tb.vvp
 route_sim_vcd: route_tb.vvp
 	vvp -N $< +vcd
 
+## ---------------------
+## miscellaneous targets
+
 prog_sram: example.bin
 	iceprog -S $<
 
@@ -65,6 +83,9 @@ timing: example.asc example.pcf
 view: example.vcd
 	gtkwave $< example.gtkw
 
+## ------
+## el fin
+
 clean:
 	rm -f firmware.elf firmware.map firmware.bin firmware.hex
 	rm -f synth.log synth.v synth.json route.v example.asc example.bin