From 56df71bb1dfa9ce8847cd9ed81334f8c913c0ea1 Mon Sep 17 00:00:00 2001
From: feng-arch <feng-arch@outlook.com>
Date: Wed, 13 Nov 2024 10:35:38 +0800
Subject: [PATCH] add readme file to this project

---
 .gitignore |   5 ++
 README.md  | 192 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 195 insertions(+), 2 deletions(-)

diff --git a/.gitignore b/.gitignore
index 7a042f5..aa4e57c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -86,3 +86,8 @@ Module.symvers
 Mkfile.old
 dkms.conf
 
+lc4
+
+tests/
+
+.vscode/
\ No newline at end of file
diff --git a/README.md b/README.md
index 63498a1..40340e0 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,191 @@
-# lc4_asm_disassembling
+# LC4 Disassembler Project
+
+This project implements a disassembler for the LC4 instruction set. It reads LC4 object files, parses the instructions and data, and outputs a human-readable assembly listing.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Project Structure](#project-structure)
+- [Compilation and Execution](#compilation-and-execution)
+- [Usage](#usage)
+- [File Descriptions](#file-descriptions)
+- [Sample Output](#sample-output)
+- [LC4 Instruction Set](#lc4-instruction-set)
+- [Notes](#notes)
+
+## Overview
+
+The program mimics the PennSim loader and disassembler. It performs the following steps:
+
+1. Loads LC4 object files containing code, data, and symbols.
+2. Parses the object files and constructs a memory linked list.
+3. Disassembles the machine code into assembly instructions.
+4. Outputs the contents of the memory, including addresses, contents, labels, and assembly instructions.
+
+## Project Structure
+
+```
+./submit
+├── lc4_disassembler.c
+├── lc4_disassembler.h
+├── lc4_loader.c
+├── lc4_loader.h
+├── lc4_memory.c
+├── lc4_memory.h
+├── lc4.c
+└── Makefile
+```
+
+- `lc4.c`: The main driver of the program.
+- `lc4_memory.*`: Implements the memory linked list and related helper functions.
+- `lc4_loader.*`: Handles loading and parsing of the LC4 object files.
+- `lc4_disassembler.*`: Contains the logic for disassembling machine code into assembly instructions.
+- `Makefile`: Automates the compilation process.
+
+## Compilation and Execution
+
+### Prerequisites
+
+- GCC compiler
+- Make utility
+
+### Compilation
+
+Run the following command to compile the project:
+
+```bash
+cd ./submit
+make all
+```
+
+This will produce an executable named `lc4`.
+
+### Execution
+
+To run the disassembler, use:
+
+```bash
+./lc4 <object_file.obj>
+```
+
+Replace `<object_file.obj>` with the path to your LC4 object file.
+
+## Usage
+
+1. **Compile the program** using the provided `Makefile`.
+2. **Run the executable** with an LC4 object file as an argument.
+3. **View the output**, which displays the labels, addresses, contents, and assembly instructions.
+
+Example:
+
+```bash
+./lc4 example.obj
+```
+
+## File Descriptions
+
+### `main.c`
+
+- Initializes the memory linked list.
+- Parses command-line arguments to get the object file name.
+- Calls functions to load the object file, disassemble the instructions, print the memory contents, and clean up.
+
+### `lc4_memory.h` and `lc4_memory.c`
+
+- Defines the `row_of_memory` struct representing each memory location.
+- Implements functions to:
+  - Add nodes to the memory linked list.
+  - Search for nodes by address or opcode.
+  - Print the memory contents.
+  - Delete the memory linked list.
+
+### `lc4_loader.h` and `lc4_loader.c`
+
+- Handles opening the object file.
+- Parses the object file sections:
+  - Code (`0xCADE`), Data (`0xDADA`), and Symbol (`0xC3B7`) sections.
+- Populates the memory linked list with addresses, contents, and labels.
+
+### `lc4_disassembler.h` and `lc4_disassembler.c`
+
+- Contains the `reverse_assemble` function.
+- Disassembles machine code instructions into their assembly equivalents.
+- Supports various LC4 instructions as per the instruction set.
+
+### `Makefile`
+
+- Automates the compilation process.
+- Usage:
+  - `make all`: Compiles the project.
+  - `make clean`: Cleans up object files.
+  - `make clobber`: Cleans up object files and the executable.
+
+## Sample Output
+
+When running the program with a valid LC4 object file, the output will display the memory contents in the following format:
+
+```
+<label>              <address>            <contents>           <assembly>
+MAIN                 0000                 9420                 
+                     0001                 D540                 
+                     0002                 16A5                 ADD R3, R2, #5
+FOR_LOOP             0003                 2403                 
+                     0004                 0603                 BRzp #3
+                     0005                 4801                 
+                     0006                 14A1                 ADD R2, R2, #1
+                     0007                 CFFB                 
+END_FOR_LOOP         0008                 C81B                 
+SUB_FACTORIAL        0010                 6080                 
+                     0011                 2100                 
+                     0012                 0A02                 BRnp #2
+                     0013                 9201                 
+                     0014                 C80D                 
+END_IF1              0015                 0202                 BRp #2
+                     0016                 93FF                 
+                     0017                 C80A                 
+END_IF2              0018                 2107                 
+                     0019                 0C02                 BRnz #2
+                     001A                 93FF                 
+                     001B                 C806                 
+END_IF3              001C                 1220                 ADD R1, R0, #0
+LOOP                 001D                 2101                 
+                     001E                 0C03                 BRnz #3
+                     001F                 103F                 ADD R0, R0, #-1
+                     0020                 1248                 MUL R1, R1, R0
+                     0021                 CFFB                 
+END_SUB_FACTORIAL    0022                 7280                 
+                     0023                 C1C0                 
+END                  0024                 0000                 
+VALUES               4020                 0006                 
+                     4021                 0005                 
+                     4022                 0008                 
+                     4023                 000A                 
+                     4024                 FFFB                 TRAP xFB
+```
+
+- **Label**: Any label associated with the memory address.
+- **Address**: The memory address in hexadecimal.
+- **Contents**: The machine code at that address.
+- **Assembly**: The disassembled assembly instruction.
+
+## LC4 Instruction Set
+
+The disassembler supports the LC4 instruction set as defined in the project requirements. It handles various instruction types, including but not limited to:
+
+- Arithmetic operations (`ADD`, `SUB`, `MUL`, `DIV`)
+- Logical operations (`AND`, `OR`, `NOT`, `XOR`)
+- Branch instructions (`BR`, `BRn`, `BRz`, `BRp`, etc.)
+- Control instructions (`JSR`, `JSRR`, `TRAP`, `RTI`)
+- Shift operations (`SLL`, `SRL`, `SRA`)
+- Memory operations (`LDR`, `STR`)
+- Comparison instructions (`CMP`, `CMPU`, `CMPI`, `CMPIU`)
+
+For a detailed list of instructions and their encodings, refer to the LC4 Instruction Set documentation provided in the project.
+
+## Notes
+
+- The program assumes that the object file is well-formed and follows the LC4 object file format.
+- Error handling is minimal; invalid instructions or malformed files may lead to unexpected behavior.
+- The disassembler currently implements a subset of the instruction set for demonstration purposes. Additional instructions can be added by extending the `reverse_assemble` function.
+- Labels are handled according to the symbol sections in the object file. Each label is associated with its corresponding address in the memory linked list.
 
-1000元兼职项目
\ No newline at end of file