haydenw-uk/badgering-about-assembly
GitHub: haydenw-uk/badgering-about-assembly
Stars: 1 | Forks: 0
# Badgering About Assembly
[](https://en.wikipedia.org/wiki/X86-64)
[](https://www.linux.org/)
[](https://en.wikipedia.org/wiki/64-bit_computing)
[](#license)
## Overview
**Badgering About Assembly** is a command-line inventory management system developed as coursework for Oxford Brookes University (2025). The application demonstrates low-level systems programming by implementing a complete CRUD (Create, Read, Update, Delete) system entirely in x86-64 assembly language.
The system manages two entity types:
- **Badger Records** - Zoo animals with physical attributes, birth data, and staff assignments
- **Staff Member Records** - Personnel with department info, salary tracking, and contact details
### Key Highlights
- **1,150+ lines** of hand-written x86-64 assembly
- **Zero high-level language dependencies** - pure assembly implementation
- **Manual memory management** with fixed-size record arrays
- **Dynamic field calculations** (age, salary progression, custom metrics)
- **Complete CRUD operations** with array compaction on deletion
## Table of Contents
- [Technical Architecture](#technical-architecture)
- [Features](#features)
- [Data Structures](#data-structures)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Usage](#usage)
- [Technical Implementation Details](#technical-implementation-details)
- [Project Structure](#project-structure)
- [Build Instructions](#build-instructions)
- [Skills Demonstrated](#skills-demonstrated)
- [License](#license)
- [Author](#author)
## Technical Architecture
### Technology Stack
| Component | Technology |
|-----------|------------|
| **Language** | x86-64 Assembly (NASM Syntax) |
| **Assembler** | NASM (Netwide Assembler) |
| **Linker** | GCC (GNU Compiler Collection) |
| **Platform** | GNU/Linux (Kernel 3.2.0+) |
| **Binary Format** | ELF 64-bit LSB Executable |
| **I/O Library** | Custom joey_lib_io library |
### System Requirements
- **Processor**: x86-64 compatible (Intel/AMD 64-bit)
- **Operating System**: Linux (Ubuntu 20.04+ recommended)
- **Memory**: Minimum 128KB (for data structures allocation)
### Memory Layout
┌─────────────────────────────────────────────────────────────┐
│ SECTION .DATA │
│ - Menu strings and UI text │
│ - Field labels and prompts │
│ - Error/success messages │
│ - Record counters (num_current_badger_records, etc.) │
├─────────────────────────────────────────────────────────────┤
│ SECTION .BSS │
│ - badger_array: 51,500 bytes (500 records × 103 bytes) │
│ - staff_member_array: 22,200 bytes (100 records × 222 bytes│
│ - current_month: 1 byte │
│ - current_year: 2 bytes │
├─────────────────────────────────────────────────────────────┤
│ SECTION .TEXT │
│ - All executable functions │
│ - Main program loop │
│ - CRUD operation implementations │
└─────────────────────────────────────────────────────────────┘
## Features
### Core Functionality
| Feature | Description |
|---------|-------------|
| **Add Records** | Create new badger or staff member entries with full data validation |
| **Display All** | Iterate and display all records with formatted output |
| **Search by ID** | Linear search with custom string comparison algorithm |
| **Delete by ID** | Remove records with automatic array compaction |
### Calculated Fields
The system automatically computes derived values at display time:
#### Badger Metrics
- **Age Calculation**: `Current Year - Birth Year` (adjusted for birth month)
- **Stripiness Index**: `Mass (kg) × Number of Stripes`
#### Staff Metrics
- **Years of Service**: `Current Year - Year Joined`
- **Current Salary**: `Starting Salary + (£300 × Years of Service)`
### User Interface
=== ZOO SYSTEM ADMIN PANEL ===
1. Add Staff
2. Add Badger
3. Delete Staff
4. Delete Badger
5. Display All Staff
6. Display All Badgers
7. Search Badger
8. Search Staff
9. Exit
Your Choice: _
## Data Structures
### Badger Record Structure (103 bytes)
| Field | Offset | Size | Type | Description |
|-------|--------|------|------|-------------|
| `id` | 0 | 8 bytes | String | Format: `bXXXXXX` (e.g., b123456) |
| `name` | 8 | 65 bytes | String | Badger name (max 64 chars + null) |
| `home_sett` | 73 | 16 bytes | String | Dwelling location |
| `mass_in_kg` | 89 | 1 byte | Unsigned Int | Weight in kg (0-255) |
| `num_stripes` | 90 | 1 byte | Unsigned Int | Stripe count (0-255) |
| `sex` | 91 | 1 byte | Char | 'M' or 'F' |
| `birth_month` | 92 | 1 byte | Unsigned Int | Month (1-12) |
| `birth_year` | 93 | 2 bytes | Unsigned Int | Year (e.g., 2020) |
| `assigned_staff_id` | 95 | 8 bytes | String | Staff ID reference |
### Staff Member Record Structure (222 bytes)
| Field | Offset | Size | Type | Description |
|-------|--------|------|------|-------------|
| `surname` | 0 | 65 bytes | String | Last name (max 64 chars + null) |
| `firstname` | 65 | 65 bytes | String | First name (max 64 chars + null) |
| `staff_id` | 130 | 9 bytes | String | Format: `pXXXXXXX` (e.g., p1234567) |
| `department` | 139 | 12 bytes | String | e.g., "Park Keeper" |
| `starting_salary` | 151 | 4 bytes | Unsigned Int | Annual salary in GBP |
| `year_joining` | 155 | 2 bytes | Unsigned Int | Year joined |
| `email_address` | 157 | 65 bytes | String | Contact email |
### Array Capacity
Badger Array: 500 records × 103 bytes = 51,500 bytes (≈50 KB)
Staff Array: 100 records × 222 bytes = 22,200 bytes (≈22 KB)
─────────────────────────────────────────────────────────────────
Total Data: = 73,700 bytes (≈72 KB)
## Prerequisites
Before building this project, ensure you have the following installed:
### Required Software
# Check if NASM is installed
nasm --version
# Expected: NASM version 2.14+
# Check if GCC is installed
gcc --version
# Expected: gcc 9.4.0+ (Ubuntu/Debian)
# Check system architecture
uname -m
# Expected: x86_64
### Installing Dependencies
#### Ubuntu/Debian
sudo apt update
sudo apt install nasm gcc build-essential
#### Fedora/RHEL
sudo dnf install nasm gcc
#### Arch Linux
sudo pacman -S nasm gcc
## Installation
### Step 1: Clone the Repository
git clone https://github.com/haydenw-uk/badgering-about-assembly.git
cd badgering-about-assembly
### Step 2: Obtain the I/O Library
This project requires the `joey_lib_io_v9_release.asm` library file.
Place the library file in a known location and update the include path in `mainprogram.asm`:
; Line 4 of mainprogram.asm - update this path
%include "/path/to/your/joey_lib_io_v9_release.asm"
### Step 3: Build the Project
# Assemble the source file
nasm -f elf64 mainprogram.asm -o mainprogram.o
# Link with GCC to create executable
gcc -no-pie -o mainprogram mainprogram.o
# Make executable (if needed)
chmod +x mainprogram
### Step 4: Run the Application
./mainprogram
## Usage
### Initial Setup
When the program starts, you'll be prompted to enter the current date:
[SYSTEM] Enter current month (as 1-12 e.g. jan = 1): 2
[SYSTEM] Enter current year (e.g. 2024): 2025
[SYSTEM] Date set. Welcome ...
This date is used for calculating badger ages and staff years of service.
### Adding a Staff Member
1. Select option `1` from the main menu
2. Enter each field when prompted:
--- ADD A NEW STAFF MEMBER (ENSURE EACH FIELD IS CORRECTLY FILLED-IN!) ---
Surname: Williams
Firstname: Hayden
Staff ID (pXXXXXXX where X = number): p1234567
Affiliated department: Park Keeper
Starting annual salary (GBP): 28000
Year joined: 2023
Email address: h.williams@zoo.org
[SUCCESS] Staff Member was added successfully!
### Adding a Badger
1. Select option `2` from the main menu
2. Enter badger details:
--- ADD A NEW BADGER (ENSURE EACH FIELD IS CORRECTLY FILLED-IN!) ---
Badger ID (bXXXXXX where X = number): b000001
Name: Boris
Home Sett: Woodland A
Mass (nearest rounded kg): 12
Number of stripes: 7
Sex (M/F): M
Birth month (as 1-12 e.g. jan = 1): 5
Birth year (e.g. 2024): 2022
Assigned Staff ID (pXXXXXXX where X = number): p1234567
[SUCCESS] Badger was added successfully!
### Viewing Records
- **Option 5**: Display all staff members with calculated salaries
- **Option 6**: Display all badgers with calculated age and stripiness
### Searching Records
- **Option 7**: Search for a specific badger by ID
- **Option 8**: Search for a specific staff member by ID
### Deleting Records
- **Option 3**: Delete a staff member by ID
- **Option 4**: Delete a badger by ID
[DELETE] Welcome to delete. Enter the ID corresponding to the record you wish to delete:
Badger ID (bXXXXXX where X = number): b000001
[SUCCESS] Deletion of record completed successfully.
## Technical Implementation Details
### Register Conventions
The program follows System V AMD64 ABI calling conventions:
| Register | Usage |
|----------|-------|
| `rax` | Return value, arithmetic operations |
| `rdi` | First function argument |
| `rsi` | Second function argument |
| `rdx` | Third function argument |
| `r12-r15` | Callee-saved, used for persistent data |
| `rbp` | Stack frame base pointer |
| `rsp` | Stack pointer |
### Memory Addressing Strategy
Records are accessed using calculated offsets:
; Calculate address of nth record
movzx rax, byte [num_current_badger_records] ; Get count
imul rax, size_badger_record ; Multiply by record size
lea r12, [badger_array + rax] ; Load effective address
; Access specific field within record
lea rdi, [r12 + offset_badger_name] ; Address of name field
### String Comparison Algorithm
Custom string comparison for ID searches:
compare_strings:
; rdi = string1, rsi = string2
; Returns 0 if equal, non-zero if different
.loop:
mov al, [rdi] ; Load char from string1
mov bl, [rsi] ; Load char from string2
cmp al, bl ; Compare characters
jne .not_equal ; Jump if different
test al, al ; Check for null terminator
jz .equal ; If null, strings are equal
inc rdi ; Next char in string1
inc rsi ; Next char in string2
jmp .loop
### Array Compaction on Deletion
When a record is deleted, subsequent records are shifted to maintain contiguity:
.shift_loop:
lea rsi, [r12 + size_badger_record] ; Source: next record
mov rdi, r12 ; Dest: current position
mov rcx, size_badger_record ; Bytes to copy
rep movsb ; Copy record
add r12, size_badger_record ; Move to next position
dec rcx ; Decrement counter
jmp .shift_loop
### Stack Frame Management
Every function properly manages its stack frame:
function_name:
push rbp ; Save old base pointer
mov rbp, rsp ; Establish new frame
sub rsp, 32 ; Allocate local variables
push r12 ; Save callee-saved registers
push r13
; ... function body ...
pop r13 ; Restore registers
pop r12
add rsp, 32 ; Deallocate locals
pop rbp ; Restore old frame
ret
## Project Structure
badgering-about-assembly/
│
├── mainprogram.asm # Main assembly source file (1,150+ lines)
│ ├── section .data # Constant strings and initialized data
│ ├── section .bss # Uninitialized data (arrays, counters)
│ └── section .text # Executable code
│ ├── main # Entry point and menu loop
│ ├── add_a_new_staff_record
│ ├── add_a_new_badger_record
│ ├── display_staff_member_record
│ ├── display_all_staff_member_records
│ ├── display_badger_record
│ ├── display_all_badger_records
│ ├── search_staff_member_by_id
│ ├── search_badger_by_id
│ ├── delete_staff_member_by_id
│ ├── delete_badger_by_id
│ └── compare_strings
│
├── mainprogram.o # Compiled object file
├── mainprogram # Final executable
├── README.md # This documentation
└── .git/ # Version control
## Build Instructions
### Quick Build
# One-liner build command
nasm -f elf64 mainprogram.asm -o mainprogram.o && gcc -no-pie -o mainprogram mainprogram.o
### Debug Build
# Build with debug symbols
nasm -f elf64 -g -F dwarf mainprogram.asm -o mainprogram.o
gcc -no-pie -g -o mainprogram mainprogram.o
# Debug with GDB
gdb ./mainprogram
### Common GDB Commands for Debugging
(gdb) break main # Set breakpoint at main
(gdb) run # Start execution
(gdb) info registers # View all registers
(gdb) x/10x $rsp # Examine stack
(gdb) x/s &badger_array # View badger array
(gdb) stepi # Single instruction step
### Troubleshooting
| Issue | Solution |
|-------|----------|
| `nasm: command not found` | Install NASM: `sudo apt install nasm` |
| `undefined reference to 'main'` | Ensure `global main` is declared |
| Segmentation fault | Check stack alignment (16-byte boundary for calls) |
| Library not found | Update `%include` path in source file |
## Skills Demonstrated
This project demonstrates proficiency in:
### Low-Level Programming
- x86-64 assembly language and instruction set
- Manual memory management without garbage collection
- Direct hardware register manipulation
- Understanding of CPU architecture and data flow
### Systems Programming
- Linux system calls and binary formats (ELF)
- ABI compliance (System V AMD64)
- Stack frame management and calling conventions
- Proper register preservation across function calls
### Data Structures & Algorithms
- Fixed-size array implementation with manual indexing
- Linear search with custom string comparison
- Array compaction algorithm for deletion
- Record offset calculation for field access
### Software Engineering
- Modular function design in assembly
- Comprehensive inline documentation
- Incremental development with version control (Git)
- Defensive programming (bounds checking, validation)
### Problem Solving
- Converting high-level CRUD concepts to machine code
- Manual byte-level data structure design
- Arithmetic operations for dynamic calculations
- Control flow implementation without high-level constructs
## Limitations
- **No Persistence**: Data is stored in memory only and lost on exit
- **No Update Operation**: Records cannot be edited after creation
- **Linear Search**: O(n) search complexity
- **Fixed Capacity**: Maximum 500 badgers and 100 staff members
- **Platform Specific**: Linux x86-64 only
## Future Enhancements
Potential improvements for extended development:
- [ ] File I/O for persistent data storage
- [ ] Update/edit functionality for existing records
- [ ] Binary search with sorted arrays
- [ ] Input validation and sanitization
- [ ] Cross-platform support (Windows, macOS)
## License
## This project was developed as part of my Malware academic coursework for a module at Oxford Brookes University.
## Author
**Hayden Williams**
Oxford Brookes University, 2025
Demonstrating that even complex software systems can be built from the ground up in assembly language.
标签：安全报告生成