fix: basic assembly program structure and basic assembly program example. add utility to assemble assembly source and link object code

.github/workflows/assembly.yaml

@@ -1,4 +1,4 @@
-name: language
+name: assembly
 
 on: 
   push:

.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/

.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:
 

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:

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
+

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

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"