From eb806bc58f26d99ddc9c4a9a459224196d6e6846 Mon Sep 17 00:00:00 2001 From: Praise Tompane Date: Mon, 19 May 2025 11:45:38 +0200 Subject: [PATCH] fix: basic assembly program scaffold. add utility to assemble assembly source and link object code --- .github/workflows/assembly.yaml | 2 +- .gitignore | 63 +++++++++++++++++- .spellcheck_exceptions_dictionary.txt | 11 ++- 1_core_language/3_data_model/0_data_model.txt | 1 + .../0_structure_of_a_program.txt | 45 +++++++++++++ .../1_structure_of_a_program/empty_file | 0 .../2_naming_and_binding/empty_file | 0 .../{hello_assembly.c => 0_hello_assembly.c} | 0 ...y.asm => 0_hello_assembly_disassembly.asm} | 0 .../x86/64_bit/intel/1_basic_program.asm | 17 +++++ .../x86/64_bit/intel/hello_assembly.o | Bin 15968 -> 0 bytes assemble.sh | 20 ++++++ dissamble.sh => disassemble.sh | 0 13 files changed, 155 insertions(+), 4 deletions(-) create mode 100755 1_core_language/4_execution_model/1_structure_of_a_program/0_structure_of_a_program.txt delete mode 100644 1_core_language/4_execution_model/1_structure_of_a_program/empty_file delete mode 100644 1_core_language/4_execution_model/2_naming_and_binding/empty_file rename 4_experiments/1_core_language/x86/64_bit/intel/{hello_assembly.c => 0_hello_assembly.c} (100%) rename 4_experiments/1_core_language/x86/64_bit/intel/{hello_assembly_disassembly.asm => 0_hello_assembly_disassembly.asm} (100%) create mode 100755 4_experiments/1_core_language/x86/64_bit/intel/1_basic_program.asm delete mode 100755 4_experiments/1_core_language/x86/64_bit/intel/hello_assembly.o create mode 100755 assemble.sh rename dissamble.sh => disassemble.sh (100%) diff --git a/.github/workflows/assembly.yaml b/.github/workflows/assembly.yaml index bc8c978..46fc514 100644 --- a/.github/workflows/assembly.yaml +++ b/.github/workflows/assembly.yaml @@ -1,4 +1,4 @@ -name: language +name: assembly on: push: diff --git a/.gitignore b/.gitignore index 86d83bb..2e3de8d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,62 @@ +# Prerequisites +*.d + +# Object files +*.o +*.ko +*.obj +*.elf + +# Linker output +*.ilk +*.map +*.exp + +# Precompiled Headers +*.gch +*.pch + +# Libraries +*.lib +*.a +*.la +*.lo + +# Shared objects (inc. Windows DLLs) +*.dll +*.so +*.so.* +*.dylib + +# Executables +*.exe +*.out +*.app +*.i*86 +*.x86_64 +*.hex +*.e + +# Debug files +*.dSYM/ +*.su +*.idb +*.pdb + +# Kernel Module Compile Results +*.mod* +*.cmd +.tmp_versions/ +modules.order +Module.symvers +Mkfile.old +dkms.conf + + +# adminstration +.DS_Store + ecosystem/ -scratch_pad.language -journal +scratch_pad/ +journal/ +applications/ \ No newline at end of file diff --git a/.spellcheck_exceptions_dictionary.txt b/.spellcheck_exceptions_dictionary.txt index 4f74a15..22fbd46 100755 --- a/.spellcheck_exceptions_dictionary.txt +++ b/.spellcheck_exceptions_dictionary.txt @@ -8,12 +8,21 @@ ISA RISCV sdm rdi +asm +lxr # authors praisetompane Zelnski +rchapman -# concepts +# assembly keywords: +mov +noprefix +syscall + +# domain specific: +unistd # course codes: diff --git a/1_core_language/3_data_model/0_data_model.txt b/1_core_language/3_data_model/0_data_model.txt index 30d6974..426fd2b 100644 --- a/1_core_language/3_data_model/0_data_model.txt +++ b/1_core_language/3_data_model/0_data_model.txt @@ -6,6 +6,7 @@ def data model: - plain english: ??? - intuition: assembly's data model is the structure of the CPU's registers and main memory directly. + there is no abstraction over the basic units of the computer(i.e. CPU and Main Memory). - properties: - CPU: diff --git a/1_core_language/4_execution_model/1_structure_of_a_program/0_structure_of_a_program.txt b/1_core_language/4_execution_model/1_structure_of_a_program/0_structure_of_a_program.txt new file mode 100755 index 0000000..c271d91 --- /dev/null +++ b/1_core_language/4_execution_model/1_structure_of_a_program/0_structure_of_a_program.txt @@ -0,0 +1,45 @@ +structure of an Assembly program: + - formal: ??? + - in words: ??? + Q: Is there a formal notion/definition of an Assembly program? + + - properties: + - flow: + 1. create and expose a symbol for the linker to know where our code starts. + - the equivalent of the main in Java, C#, C, C++. + + .global _start + + 2. specify syntax variant used for this program. + + .intel_syntax noprefix + + 3. implement program + _start: + 1. register and memory manipulation with keyword such as 'mov' + # example: mov rdi, 8 #this sets the value of register rdi to 8 + + 2. request kernel to perform work such as printing to screen, properly exiting etc + syscall + + remarks: + - to get the kernel to perform some operation we: + 1. configure the state of the SPECIFIC registers to match the desired operation. this is akin to invoking a function with specific parameter/s. + # see: linux kernel system calls: + - https://blog.rchapman.org/posts/Linux_System_Call_Table_for_x86_64/ + - https://lxr.linux.no/#linux+v3.2/arch/x86/include/asm/unistd_64.h + 2. execute the system call with the 'syscall' keyword + + 4. new line at the end of program + + - examples: + - 4_experiments/1_core_language/x86/64_bit/intel/1_hello_world.asm + + - use cases: ??? + + - proof: ??? + +References: + - Advanced Computing Research Centre. 21.2. AT&T Syntax versus Intel Syntax. University of Bristol + - Low Level. 2023. Learn Assembly + diff --git a/1_core_language/4_execution_model/1_structure_of_a_program/empty_file b/1_core_language/4_execution_model/1_structure_of_a_program/empty_file deleted file mode 100644 index e69de29..0000000 diff --git a/1_core_language/4_execution_model/2_naming_and_binding/empty_file b/1_core_language/4_execution_model/2_naming_and_binding/empty_file deleted file mode 100644 index e69de29..0000000 diff --git a/4_experiments/1_core_language/x86/64_bit/intel/hello_assembly.c b/4_experiments/1_core_language/x86/64_bit/intel/0_hello_assembly.c similarity index 100% rename from 4_experiments/1_core_language/x86/64_bit/intel/hello_assembly.c rename to 4_experiments/1_core_language/x86/64_bit/intel/0_hello_assembly.c diff --git a/4_experiments/1_core_language/x86/64_bit/intel/hello_assembly_disassembly.asm b/4_experiments/1_core_language/x86/64_bit/intel/0_hello_assembly_disassembly.asm similarity index 100% rename from 4_experiments/1_core_language/x86/64_bit/intel/hello_assembly_disassembly.asm rename to 4_experiments/1_core_language/x86/64_bit/intel/0_hello_assembly_disassembly.asm diff --git a/4_experiments/1_core_language/x86/64_bit/intel/1_basic_program.asm b/4_experiments/1_core_language/x86/64_bit/intel/1_basic_program.asm new file mode 100755 index 0000000..fd3f283 --- /dev/null +++ b/4_experiments/1_core_language/x86/64_bit/intel/1_basic_program.asm @@ -0,0 +1,17 @@ +.global _start +.intel_syntax noprefix + +_start: + # This program that only starts and exits. + # Explanation: + # instruction 60 in register rax instructs the Linux kernel to exit + # see "linux kernel system calls" in 1_core_language/4_execution_model/1_structure_of_a_program/0_structure_of_a_program.txt + + # This sets 60 to register rax, indicating the system should exit + mov rax, 60 + + # This sets 0 to register rdi. I am setting here an error code of 0, to indicate no errors. + mov rdi, 0 + + # Instructs the kernel to execute a system + syscall diff --git a/4_experiments/1_core_language/x86/64_bit/intel/hello_assembly.o b/4_experiments/1_core_language/x86/64_bit/intel/hello_assembly.o deleted file mode 100755 index c815d614a94021542e62576769bee2de683dc565..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 15968 zcmeHOU2Ggz6~4P}5~p?IO_~(Pq4B6BNQ; zouzhFfl&%Hlt{@7Ae2hsg%-g>g(}1Y53W+uf}kWkMF=6QN|7rSa77D&s$R~SIp26Z ztf|xokg7S>&Ueqxcki7ucV_Q+@BK>u&_FVgP>=@okYa5ls_nSki3itg2yWJ7KFDTya1)23xdce=Y&7U zB%e{#$j732N2Q{?M}!x}K8Xi%8!TsDcXJ=4y%FJU)4Xa_6z})V3W)X|CZ1eciTLk; z%Y0heTkAS>NdAG6R&_A%WIK->%;(zkPO&=EK69+Iz4M4(Dd~s2hPhwd29K!|r^Zxr zPR+9od@gUJ52uy=h2Pxslb4@+=-mT9XuAB5y??rN=bnxh)WIB%Vc~cT3Dz+lIL1H! zud-RnO5LzuEqI1C4$RqF$7hgDt7GSO>c!{Qh_9?+Zz21A^!X2&uDTUvnv~vgv*KE1 z*DP30ku2jgmO0@Rt-SNNt=P@U?o=m+277wVL;4~8Xiz?UM45x5C(WE)wkMs6YnMk) z_U21Pd(_J2ZK`XsP%298rXN~2kUE#7E7m|CKC&dpvX>C!r`qalU9s%NrAPCNe3!^-Tv+!_h6irD+o?M`m#I4&YYWY7 za~ynCkm4;b{^(~J_AeXfmy8$xa@=_Fc7u_)X53hIw^0S}>3#)`wS|f1w!Rhq-jho$7TFO?oPjt4aR%ZH#2JV)5N9CHK%9X%191l848$4u z|7C!G?=tLszNB?mDs~~8pQSh6oedA}qb~99N=-|(noD>;;bp>464L9m+VfVe_5vaQ z#>tX+{Ip8Uq!K%uHZ)#LY)G-4f4g7$YpoXk9k719QoAMoBE@S|R-01;n_E8BeAi=* zbLx2OgC9S<+pC88-2PJ(hu_vXoZEVoJ`VM-l?~mSQ(sT^ZdyM^9b!F}I0JD8;ta$Y zh%*ppAkILXfj9$k2I35S$TEQShgffjwS>H;k)_FpV1eT%(MM(7;ttWVu5qX6c!%=d zt;mM;jr`ul0{=V9wG!)BWHBMuAWrkkBnj3Yz9RlReY3hCc$XlrA7$C@LvX|z#YI`q zh&7Rj$NMF(XJq+^4?)AQXQX53_q@c>Voy&{-@7&ce8}j9($Bo!`K5$UzXW?a@=ULv zp1v&S`%lr)Z>j!&4p=`PZMYK)UB!X*s3&@RKcVgGv$Kv>)Y82Cwxd0LIo`v{kWfCf69yB7OeY){aGs1>;GEk#cKr;>Tb2D zp@tQ#SI;#s{vH**j=%M2TZ47;zD40af&DfW>aFkIP6^Qv6vBr+`wrEZ2^p!F zCVRblddQwqJAyoeHOTSFl)`fc_F;*S*8eEkH3Wt53uNDt+@UZ|;hJGP{edL6pZW&b zQ*_<63?h9TBl}jmz9TYzynil{>su0!aRSzNCH?_XGp)tT|Ko7PLTsNKpsrfW?qGF05^#DqSsRu;gUZowSqCGfnsK36g) z^QEknH*;>OTrsWcj2bT$rt`LI=k$*H5xn@`F|BghnlOO%ji zQlz^obc+9lXj<|wMCzGo4xH{j*>Cor>N9Bxe&1(Kb)OvUB{OYwF#8Sh8hxjgd17d| zr+dg89vC>&KWdJ4_YCzDBf3K%gN*?1v-qF)7X-1qX~48|mTM{R^r%`^{H+0`tllSJ z<|-v~$|~k~55eFtMdh5LS*_SPs-#EhZ%C-S%V71^hSh!JL@K3M zW(%&BC3MR^PNC!!X?Mf4(u*b6)+dWqeY#wlw#)8p$ds)*v`@v!iK)A1u${+=7d~ZG zrj(wWEm9Lcx@F(Ab6SubVm*^~n;cu02CX9xoJB^3to@ zQ!+xPa#RU4pXv`4pMf&9U=^HkYQE%h&D1%*Ogg1l=`>giGzP;r$OkO*{Dp2UdY1dr zBHuee%wNRq#iGpkG5YYF0sLda2WsRC3+5BB@wT}z{}JH>cOy^`&n=kwdn?Sx_a;z7 zpkS2$X|n&F<{;=l=4C*%k9k?N{}%CiP6j^aZNTTGUG5|28GOv29J28#gO7P25c56? z@r3IL%NI%EITrYsR{?4HohRr&;(%W!FVESaW8Mbr5Pr1(V)o{xoKx^IZv@UuAli?f z|98mG{2qx5Ccr{Ko>=8_l>dFQaZXTw@ckg)6T$qJVpyWr|1#Oad`)-(daRWLzJ7qu zM)(&1Fk1>n2&j8V}~D)exe%ipf?ejZRkJdc`d?^#&cU?*&^*rc;EtmZ(#8Y z;D-@oFC3bY3O_F$yO*3iA4h-iT;clzeGl`m@QV`3Ei~k-Uaq9*0Z(`9@t-{EN435W F|KHotzdrx~ diff --git a/assemble.sh b/assemble.sh new file mode 100755 index 0000000..a8e2e08 --- /dev/null +++ b/assemble.sh @@ -0,0 +1,20 @@ +# +# a quick utility to: +# - assemble assembly code into object code +# - link it into executable ELF(Extensible and Linkable Format) +# example usage: +# ./assemble.sh 4_experiments/1_core_language/x86/64_bit/intel/1_hello_world.asm + +assembly_source_file=$1 +object_code_file=$assembly_source_file.o +executable_code_file=$assembly_source_file.e + +echo "Assembling code into object code and saving in file: $object_code_file" + as $assembly_source_file -o $object_code_file +echo "Done Assembling" + +echo "" + +echo "Linking object code and saving in file: $executable_code_file" + gcc -o $executable_code_file $object_code_file -nostdlib -static +echo "Done Linking" \ No newline at end of file diff --git a/dissamble.sh b/disassemble.sh similarity index 100% rename from dissamble.sh rename to disassemble.sh