join implementation

Makefile

@@ -142,20 +142,28 @@ UPROGS=\
 	$U/_logstress\
 	$U/_forphan\
 	$U/_dorphan\
+	$U/_join\
 
-fs.img: mkfs/mkfs README.md $(UPROGS)
-	mkfs/mkfs fs.img README.md $(UPROGS)
+TDIR = tests
+
+fs.img: mkfs/mkfs README.md $(UPROGS) $(TDIR)/file1.txt $(TDIR)/file2.txt $(TDIR)/students.txt $(TDIR)/grades.txt $(TDIR)/products.txt $(TDIR)/prices.txt $(TDIR)/Fog_Emp.txt $(TDIR)/Fog_Perf.txt $(TDIR)/MC_Item.txt $(TDIR)/MC_Price.txt $(TDIR)/empty.txt
+	cp $(TDIR)/*.txt .
+	mkfs/mkfs fs.img README.md $(UPROGS) file1.txt file2.txt students.txt grades.txt products.txt prices.txt Fog_Emp.txt Fog_Perf.txt MC_Item.txt MC_Price.txt empty.txt
 
 -include kernel/*.d user/*.d
 
 clean: 
-	rm -f *.tex *.dvi *.idx *.aux *.log *.ind *.ilg \
+	rm -f *.tex *.dvi *.idx *.aux *.log *.ind *.ilg file1.txt file2.txt students.txt grades.txt products.txt prices.txt Fog_Emp.txt Fog_Perf.txt MC_Item.txt MC_Price.txt empty.txt \
 	*/*.o */*.d */*.asm */*.sym \
 	$K/kernel fs.img \
 	mkfs/mkfs .gdbinit \
         $U/usys.S \
 	$(UPROGS)
 
+qemu-clean: check-qemu-version $K/kernel fs.img
+	$(QEMU) $(QEMUOPTS)
+	$(MAKE) clean
+
 # try to generate a unique GDB port
 GDBPORT = $(shell expr `id -u` % 5000 + 25000)
 # QEMU's gdb stub command line changed in 0.11

README.md

@@ -4,4 +4,27 @@ Fall 2025 Edition
 
 ![FogOS](docs/fogos.gif)
 
+## Documentation
 
+### Quick Links
+- [Building the Software](docs/Documentation.md#building-the-software)
+- [Running the Software](docs/Documentation.md#running-the-software)
+- [Testing the Software](docs/Documentation.md#testing-the-software)
+- [Cleaning Up](docs/Documentation.md#cleaning-up)
+- [Project Structure](docs/Documentation.md#project-structure)
+
+### Quick Start
+```bash
+# Build the project
+make
+
+# Run QEMU
+make qemu
+
+# Exit: Ctrl+A then X
+
+# Clean up
+make clean
+```
+
+For detailed documentation, see [Documentation.md](docs/Documentation.md)

docs/Documentation.md

@@ -0,0 +1,111 @@
+# Software Documentation
+
+## Building the Software
+
+### Prerequisites
+- RISC-V toolchain (riscv64-unknown-elf-gcc or riscv64-linux-gnu-gcc)
+- QEMU RISC-V emulator (version 7.2 or higher)
+- Make build system
+
+### Build Steps
+```bash
+make
+```
+This will:
+- Compile the kernel from source files in the `kernel/` directory
+- Compile user programs from the `user/` directory
+- Copy test data files from `tests/` to the root directory
+- Create the filesystem image (`fs.img`) containing all programs and data files
+
+## Running the Software
+
+### Start QEMU
+```bash
+make qemu
+```
+This launches the RISC-V emulator with the compiled kernel and filesystem.
+
+### Exit QEMU
+Press `Ctrl+A` then `X` to quit the emulator.
+
+**Important:** After exiting QEMU, run `make clean` to remove build artifacts and copied test files.
+
+### Run with automatic cleanup
+```bash
+make qemu-clean
+```
+This runs QEMU and automatically cleans build artifacts after you exit.
+
+## Testing the Software
+
+### Understanding the join command
+The `join` command merges two text files based on matching first fields (words) in each line. For each match found, it outputs a combined line in the format:
+```
+<matching_field> <rest_of_line_from_file1> <rest_of_line_from_file2>
+```
+
+### Access test data files
+Once in QEMU, the test data files are available in the filesystem:
+- `file1.txt`, `file2.txt` - Sample department data (25 lines each)
+- `MC_Item.txt`, `MC_Price.txt` - Inventory data
+- `students.txt`, `grades.txt` - Student records
+- `products.txt`, `prices.txt` - Product information
+- `Fog_Emp.txt`, `Fog_Perf.txt` - Employee data
+- `empty.txt` - Empty test file
+
+### Run join command
+
+**Basic usage (output to console):**
+```bash
+join file1.txt file2.txt
+```
+Expected output: 25 joined lines matching names from both files, displaying department info with grades.
+
+**With output file:**
+```bash
+join file1.txt file2.txt output.txt
+```
+This saves the joined results to `output.txt` while also displaying them on console.
+
+**Get help:**
+```bash
+join --help
+```
+
+**Example output format:**
+When joining students.txt and grades.txt, each matching line combines:
+- The matching first field (e.g., "001")
+- The remainder of the line from students.txt (e.g., "Alice Engineering Robotics")
+- The remainder of the line from grades.txt (e.g., "A+ Excellent Outstanding")
+
+```
+001 Alice Engineering Robotics A+ Excellent Outstanding
+002 Bob Physics Quantum B+ Good Solid
+003 Charlie Chemistry Polymers A- Very Strong
+005 Ethan Biology Genetics B Fair Average
+join completed
+...
+```
+
+The output shows 4 total matches (one for each person in both files).
+
+## Cleaning Up
+
+### Remove all build artifacts and copied test files
+```bash
+make clean
+```
+This removes:
+- Compiled object files (*.o)
+- Kernel binary and filesystem image
+- Temporary files
+- Test data files copied to root (preserves originals in `tests/`)
+- Note: `compile_flags.txt` in root is preserved
+
+## Project Structure
+
+- `kernel/` - Operating system kernel source code
+- `user/` - User-space programs and utilities
+- `tests/` - Original test data files (preserved during clean)
+- `mkfs/` - Filesystem creation utility
+- `Makefile` - Build configuration and targets

kernel/syscall.c

@@ -102,6 +102,7 @@ extern uint64 sys_link(void);
 extern uint64 sys_mkdir(void);
 extern uint64 sys_close(void);
 
+
 // An array mapping syscall numbers from syscall.h
 // to the function that handles the system call.
 static uint64 (*syscalls[])(void) = {

kernel/sysproc.c

@@ -105,3 +105,4 @@ sys_uptime(void)
   release(&tickslock);
   return xticks;
 }
+

tests/Fog_Emp.txt

@@ -0,0 +1,40 @@
+EMP001 Alice Johnson Manager Sales Northeast
+EMP002 Bob Smith Developer IT Backend
+EMP003 Carol Davis Analyst Finance Budgets
+EMP004 David Wilson Designer Marketing Creative
+EMP005 Emma Brown Support Operations Customer
+EMP006 Frank Miller Engineer IT Systems
+EMP007 Grace Lee Specialist HR Recruiting
+EMP008 Henry Chen Coordinator Marketing Events
+EMP009 Iris Taylor Administrator Finance Payroll
+EMP010 Jack Rodriguez Developer IT Frontend
+EMP011 Kate Thompson Manager Operations Supply
+EMP012 Luis Garcia Analyst Data Business
+EMP013 Maria Gonzalez Designer UX Research
+EMP014 Nathan Park Engineer Software Senior
+EMP015 Olivia White Specialist Sales Enterprise
+EMP016 Paul Kim Coordinator HR Benefits
+EMP017 Quinn Adams Administrator IT Security
+EMP018 Rachel Turner Manager Finance Treasury
+EMP019 Samuel Lee Developer Mobile Applications
+EMP020 Tara Patel Analyst Marketing Consumer
+EMP021 Ulysses Jones Engineer DevOps Cloud
+EMP022 Victoria Chang Specialist Operations Logistics
+EMP023 William Hayes Coordinator Sales Regional
+EMP024 Ximena Rivera Administrator Marketing Social
+EMP025 Yuki Tanaka Manager IT Infrastructure
+EMP026 Zachary Moore Developer Full Stack
+EMP027 Abby Foster Analyst HR Metrics
+EMP028 Blake Cooper Engineer Quality Assurance
+EMP029 Chloe Ward Specialist Finance Audit
+EMP030 Dylan Scott Coordinator IT Help
+EMP031 Elena Morales Administrator Operations Facilities
+EMP032 Felix Chen Manager Sales International
+EMP033 Gina Roberts Developer Database Systems
+EMP034 Hugo Martinez Analyst Operations Process
+EMP035 Ivy Johnson Specialist Marketing Digital
+EMP036 Jake Williams Engineer Network Security
+EMP037 Kara Davis Coordinator Finance Accounting
+EMP038 Logan Brown Administrator HR Training
+EMP039 Mia Thompson Manager Operations Quality
+EMP040 Noah Garcia Developer API Services

tests/Fog_Perf.txt

@@ -0,0 +1,30 @@
+EMP001 Excellent Rating5 Promotion Ready
+EMP003 Good Rating4 Steady Progress
+EMP005 Outstanding Rating5 Top Performer
+EMP007 Satisfactory Rating3 Meeting Goals
+EMP009 Excellent Rating5 Leadership Potential
+EMP011 Good Rating4 Strong Contributor
+EMP013 Outstanding Rating5 Innovation Leader
+EMP015 Satisfactory Rating3 Reliable Worker
+EMP017 Good Rating4 Technical Expert
+EMP019 Excellent Rating5 Rising Star
+EMP021 Outstanding Rating5 Architecture Lead
+EMP023 Satisfactory Rating3 Consistent Results
+EMP025 Excellent Rating5 Strategic Thinker
+EMP027 Good Rating4 Data Expert
+EMP029 Outstanding Rating5 Process Optimizer
+EMP031 Satisfactory Rating3 Team Player
+EMP033 Excellent Rating5 Database Guru
+EMP035 Good Rating4 Creative Marketer
+EMP037 Outstanding Rating5 Financial Wizard
+EMP039 Satisfactory Rating3 Quality Focused
+EMP002 Good Rating4 Code Quality
+EMP004 Excellent Rating5 Design Leader
+EMP006 Outstanding Rating5 System Architect
+EMP008 Satisfactory Rating3 Event Success
+EMP010 Good Rating4 Frontend Expert
+EMP012 Excellent Rating5 Analytics Pro
+EMP014 Outstanding Rating5 Senior Mentor
+EMP016 Satisfactory Rating3 Benefits Admin
+EMP018 Good Rating4 Treasury Manager
+EMP020 Excellent Rating5 Market Researcher

tests/MC_Item.txt

@@ -0,0 +1,45 @@
+SKU1001 Laptop Dell Inspiron 15
+SKU1002 Monitor Samsung 27inch 4K
+SKU1003 Keyboard Mechanical RGB Gaming
+SKU1004 Mouse Wireless Ergonomic Office
+SKU1005 Headphones Noise Cancelling Premium
+SKU1006 Webcam HD 1080p Conference
+SKU1007 Printer Laser Color Network
+SKU1008 Scanner Flatbed Document High
+SKU1009 Tablet iPad Pro 12inch
+SKU1010 Smartphone iPhone 15 Pro
+SKU1011 Smartwatch Apple Watch Series
+SKU1012 Speaker Bluetooth Portable Waterproof
+SKU1013 Charger USB-C Fast Wireless
+SKU1014 Cable HDMI 4K Premium
+SKU1015 Adapter USB Hub Multi
+SKU1016 Drive SSD External 1TB
+SKU1017 Memory RAM DDR4 32GB
+SKU1018 Graphics Card RTX 4080
+SKU1019 Processor Intel i7 13th
+SKU1020 Motherboard ASUS Gaming ATX
+SKU1021 Case PC Tower RGB
+SKU1022 Fan Cooling Liquid AIO
+SKU1023 Power Supply 850W Modular
+SKU1024 Router WiFi 6 Mesh
+SKU1025 Switch Network 24 Port
+SKU1026 Camera DSLR Canon Professional
+SKU1027 Lens Telephoto 70-200mm Canon
+SKU1028 Tripod Carbon Fiber Professional
+SKU1029 Light LED Panel Studio
+SKU1030 Microphone USB Condenser Podcast
+SKU1031 Interface Audio USB Recording
+SKU1032 Mixer Digital 8 Channel
+SKU1033 Drone Quadcopter 4K Camera
+SKU1034 Battery Drone LiPo 3S
+SKU1035 Controller Game Wireless Pro
+SKU1036 Console Gaming Latest Generation
+SKU1037 Headset Gaming Surround 7.1
+SKU1038 Chair Gaming Ergonomic Racing
+SKU1039 Desk Gaming L-Shaped Standing
+SKU1040 Monitor Arm Dual Display
+SKU1041 Lamp Desk LED Adjustable
+SKU1042 Fan Desk USB Quiet
+SKU1043 Heater Space Ceramic Safety
+SKU1044 Purifier Air HEPA Smart
+SKU1045 Humidifier Ultrasonic Cool Mist

tests/MC_Price.txt

@@ -0,0 +1,29 @@
+SKU1001 $899.99 InStock Warehouse-A
+SKU1003 $149.99 InStock Warehouse-B
+SKU1005 $299.99 LowStock Warehouse-A
+SKU1007 $449.99 InStock Warehouse-C
+SKU1009 $1099.99 OutOfStock Backorder
+SKU1011 $399.99 InStock Warehouse-A
+SKU1013 $79.99 InStock Warehouse-B
+SKU1015 $49.99 InStock Warehouse-C
+SKU1017 $189.99 LowStock Warehouse-A
+SKU1019 $329.99 InStock Warehouse-B
+SKU1021 $129.99 InStock Warehouse-C
+SKU1023 $159.99 LowStock Warehouse-A
+SKU1025 $299.99 InStock Warehouse-B
+SKU1027 $899.99 OutOfStock Backorder
+SKU1029 $199.99 InStock Warehouse-C
+SKU1031 $149.99 InStock Warehouse-A
+SKU1033 $599.99 LowStock Warehouse-B
+SKU1035 $69.99 InStock Warehouse-C
+SKU1037 $199.99 InStock Warehouse-A
+SKU1039 $399.99 LowStock Warehouse-B
+SKU1041 $89.99 InStock Warehouse-C
+SKU1043 $79.99 InStock Warehouse-A
+SKU1045 $129.99 InStock Warehouse-B
+SKU1002 $349.99 InStock Warehouse-A
+SKU1004 $59.99 InStock Warehouse-B
+SKU1006 $89.99 LowStock Warehouse-C
+SKU1008 $249.99 InStock Warehouse-A
+SKU1010 $999.99 InStock Warehouse-B
+SKU1012 $99.99 InStock Warehouse-C

tests/file1.txt

@@ -0,0 +1,25 @@
+Alice Engineering Dept Robotics
+Bob Physics Dept Quantum Studies
+Charlie Chemistry Dept Polymers
+Diana Math Dept Applied Modeling
+Ethan Biology Dept Genetics Focus
+Fiona Economics Dept Global Trade
+George Literature Dept Classics
+Hannah History Dept Ancient World
+Ian Philosophy Dept Ethics
+Julia Music Dept Composition
+Kevin Art Dept Modern Painting
+Laura CS Dept Machine Learning
+Mark Stats Dept Data Analysis
+Nina Linguistics Dept Semantics
+Oliver Sociology Dept Inequality
+Paula Psychology Dept Cognition
+Quinn Anthropology Dept Culture
+Rachel Astronomy Dept Cosmology
+Steve PoliSci Dept Governance
+Tina EnvSci Dept Climate Studies
+Uma Business Dept Marketing
+Victor Education Dept Pedagogy
+Wendy Geography Dept GIS Mapping
+Xavier Law Dept International
+Yara Medicine Dept Physiology

tests/file2.txt

@@ -0,0 +1,25 @@
+GradeA GPA3.9 HighPerformance
+GradeB GPA3.1 AveragePerformance
+GradeA GPA3.8 StrongPerformance
+GradeA GPA3.7 SolidPerformance
+GradeB GPA3.4 GoodPerformance
+GradeC GPA2.5 BelowPerformance
+GradeC GPA2.7 WeakPerformance
+GradeB GPA3.3 ConsistentWork
+GradeA GPA3.9 ExcellentWork
+GradeA GPA4.0 OutstandingWork
+GradeB GPA3.2 SatisfactoryWork
+GradeB GPA3.0 FairPerformance
+GradeA GPA3.5 StrongAnalysis
+GradeA GPA3.6 ClearThinking
+GradeB GPA3.4 GroupWorkGood
+GradeC GPA2.8 NeedsImprovement
+GradeC GPA2.6 PoorRetention
+GradeA GPA3.9 ExcellentResearch
+GradeA GPA3.8 HighAchievement
+GradeB GPA3.2 StableWork
+GradeB GPA3.0 AverageResults
+GradeA GPA3.8 GoodLearning
+GradeA GPA3.9 HighAccuracy
+GradeB GPA3.1 FairResults
+GradeB GPA3.3 SolidWork

tests/grades.txt

@@ -0,0 +1,5 @@
+001 A+ Excellent Outstanding
+002 B+ Good Solid
+003 A- Very Strong
+005 B Fair Average
+006 C Below Standard

tests/prices.txt

@@ -0,0 +1,5 @@
+P001 $999 Premium High
+P003 $599 Mid Reasonable
+P004 $299 Budget Low
+P007 $199 Clearance Sale
+P008 $149 Discount Special