From f0b03ddfb291bd09742d506d7740b370162a29b5 Mon Sep 17 00:00:00 2001
From: Schnappy <ABelliqueux@users.noreply.github.com>
Date: Sat, 10 Jul 2021 12:41:26 +0200
Subject: [PATCH] Created Embedding binary data in your psx executable
 (markdown)

---
 ...ding-binary-data-in-your-psx-executable.md | 55 +++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 Embedding-binary-data-in-your-psx-executable.md

diff --git a/Embedding-binary-data-in-your-psx-executable.md b/Embedding-binary-data-in-your-psx-executable.md
new file mode 100644
index 0000000..690bb11
--- /dev/null
+++ b/Embedding-binary-data-in-your-psx-executable.md
@@ -0,0 +1,55 @@
+## Embedding binary data in a ps-exe
+
+So, if you don't know it yet, the fun in PSX development is to be able to upload your exes on real hardware with a USB/Serial cable.
+This means that the data you'll use in your program ( graphics, sounds, etc.) will have to be embedded in your exe in a binary form, 
+as you won't be able to stream them from the serial port. 
+
+*Well technically you could load them in memory before uploading your exe or stream them from a cd, but let's keep things simple for now.*
+
+With our setup, this is quite easy !
+
+  1. In `common.mk` , add the lines :
+  
+  ```mk
+# convert TIM file to bin
+%.o: %.tim
+    $(PREFIX)-objcopy -I binary --set-section-alignment .data=4 --rename-section .data=.rodata,alloc,load,readonly,data,contents -O elf32-tradlittlemips -B mips $< $@
+
+# convert VAG files to bin
+%.o: %.vag
+    $(PREFIX)-objcopy -I binary --set-section-alignment .data=4 --rename-section .data=.rodata,alloc,load,readonly,data,contents -O elf32-tradlittlemips -B mips $< $@
+```
+
+If you pay attention, you can see that's the same command, but for different file types. TIM files are bitmap images and VAG is the sound format used in this example.
+Each time you'll want to add a file type, duplicate and change `%.vag` to `%.filetype`
+
+Then, in your project folder, copy the makefile from the cube example :
+
+```bash
+mkdir new_project && cd new_project
+cp ../cube/Makefile ../
+```
+
+All you have to do now is add the files you wish to embed to the SRCS variable, without forgetting the \ :
+
+```bash
+SRCS = main.c \
+../common/crt0/crt0.s \
+file_to_embed.ext \
+```
+
+  2. So this part takes care of converting our data to binary. Now to access them from your program, use this in your sources :
+```c
+extern ulong _binary_filename_extension_start[]; 
+extern ulong _binary_filename_extension_end[];
+extern ulong _binary_bowsht_tim_length[];
+```
+
+The filename variable must begin with `_binary_` followed by the full path of your file, with . and / replaced by _ (underscore), and end with `_start[];` or `_end[];` or `_length[];` [source](https://discord.com/channels/642647820683444236/663664210525290507/780866265077383189)
+
+`_start` and `_end` are pointers, while `_length` is a constant.
+
+If you want to go up one level in the folder hierarchy, you can use four underscores : `____`.
+This is because `/../` are characters that will be replaced with `_`.
+
+That's it! When you'll type `make` next time, it should convert your files to .o, then include them in your ps-exe.