Added assignment details as a READMEHEADmaster

1 files changed, 121 insertions, 0 deletions

diff --git a/README.html b/README.html
new file mode 100644
index 0000000..8f85d97
--- /dev/null
+++ b/README.html
@@ -0,0 +1,121 @@
+<p>For this assignment, you will be writing a memory allocation library called <strong>libmalloc.</strong> This library should provide basic heap memory management features.</p>
+<h2>Required Features</h2>
+<p>The required interface for your library is as follows,</p>
+<pre>
+void *allocate(size_t) 
+  Returns a pointer to an available region of heap memory of a specified number of bytes. 
+  If the allocation fails for some reason, return NULL instead. This function should use 
+  the sbrk syscall to grow the heap as needed, and should prioritize allocating memory 
+  from the free list if possible.
+
+  Returned pointers must be aligned to a 16 byte boundary and the allocated region must
+  be within the programs heap.
+
+  
+void release(void*)
+  Frees a region of memory allocated by the allocate function by adding it to the free 
+  list. This function should also handle coalescing contiguous memory regions on the 
+  free list at the time of release.
+
+  You may assume that the input argument is a pointer that has been returned by
+  allocate, and has not already been released.
+  
+
+typedef struct freelist_hdr freelist_hdr;
+  A struct for the header of memory regions on the free list. This type should
+  *not* be opaque externally to the library, and can be used for testing
+
+  
+freelist_hdr *list_head()
+  Returns a pointer to the head of the free list--can be used for testing
+</pre>
+<h2>Other Requirements</h2>
+<p>Beyond the required interface, there are a few constraints on how your implementation must function.</p>
+<ol style="list-style-type: decimal;">
+    <li>Do&nbsp;<strong>not&nbsp;</strong>use any heap memory management libraries, including the standard library's implementations of malloc, free, etc. You must do all memory management manually, yourself. The only memory management function you can call is sbrk</li>
+    <li>If there exists space on the free list to service an allocation, you must use that space rather than growing the heap.&nbsp;</li>
+    <li>You should include a C program which imports and tests your library in your submission. You do not need to use a unit test framework, though you may use check if you like.</li>
+    <li>Your submission should include the following,
+        <ol style="list-style-type: decimal;">
+            <li>A Makefile for building a static library, as well as the test binary</li>
+            <li>An include file for your library</li>
+        </ol>
+    </li>
+</ol>
+<h2>Hints</h2>
+<ol style="list-style-type: decimal;">
+    <li>Read Chapter 17 of the textbook. It provides near step by step instructions for this project.</li>
+    <li>You can get the initial memory address for the start of the heap by calling <code>sbrk(0)</code>.</li>
+    <li>Not being able to use heap memory within your library will feel quite limiting. You will <strong>need</strong> to make generous use of global variables to track the necessary state information.&nbsp;</li>
+    <li>C doesn't provide a mechanism for automatic module initialization. Because this library doesn't include an explicit <code>init()</code> function in its API, you will need to piggyback initialization on the first call to <code>allocate()</code>. Consider using a global variable to track whether the library has been initialized yet.</li>
+    <li>You can use subtraction on a pointer to embed headers prior to heap memory addresses. Just be careful to ensure that your library doesn't clobber these headers accidentally.&nbsp;</li>
+</ol>
+<h2>Grading Criteria</h2>
+<p>Submissions will be graded on the following criteria,</p>
+<h3>Library Correctness (30 pts)</h3>
+<table style="border-collapse: collapse; width: 100%;" border="1">
+    <tbody>
+        <tr>
+            <td style="width: 49.9772%;"><strong>Criteria</strong></td>
+            <td style="width: 49.9772%;"><strong>Points</strong></td>
+        </tr>
+        <tr>
+            <td style="width: 49.9772%;">Basic allocation and release work correctly, without account for reuse of released blocks</td>
+            <td style="width: 49.9772%;">15</td>
+        </tr>
+        <tr>
+            <td style="width: 49.9772%;">Blocks are correctly reused from the free list when possible</td>
+            <td style="width: 49.9772%;">7</td>
+        </tr>
+        <tr>
+            <td style="width: 49.9772%;">Blocks in the free list are coalesced when possible</td>
+            <td style="width: 49.9772%;">3</td>
+        </tr>
+        <tr>
+            <td style="width: 49.9772%;">Blocks in the free list are split when possible</td>
+            <td style="width: 49.9772%;">5</td>
+        </tr>
+    </tbody>
+</table>
+<h3>Testing (10 pts)</h3>
+<table style="border-collapse: collapse; width: 100%; height: 116px;" border="1">
+    <tbody>
+        <tr style="height: 29px;">
+            <td style="width: 49.9772%; height: 29px;"><strong>Criteria</strong></td>
+            <td style="width: 49.9772%; height: 29px;"><strong>Points</strong></td>
+        </tr>
+        <tr style="height: 29px;">
+            <td style="width: 49.9772%; height: 29px;">Testing code exists and runs</td>
+            <td style="width: 49.9772%; height: 29px;">2</td>
+        </tr>
+        <tr style="height: 29px;">
+            <td style="width: 49.9772%; height: 29px;">Testing code exists that leverages the list_head() function to validate the free list</td>
+            <td style="width: 49.9772%; height: 29px;">3</td>
+        </tr>
+        <tr style="height: 29px;">
+            <td style="width: 49.9772%; height: 29px;">Testing code validates allocating and releasing memory</td>
+            <td style="width: 49.9772%; height: 29px;">5</td>
+        </tr>
+    </tbody>
+</table>
+<h3>Code Quality (10 pts)</h3>
+<table style="border-collapse: collapse; width: 100%;" border="1">
+    <tbody>
+        <tr>
+            <td style="width: 49.9772%;"><strong>Criteria</strong></td>
+            <td style="width: 49.9772%;"><strong>Points</strong></td>
+        </tr>
+        <tr>
+            <td style="width: 49.9772%;">Library is well organized, non-public functions and data are declared as static</td>
+            <td style="width: 49.9772%;">3</td>
+        </tr>
+        <tr>
+            <td style="width: 49.9772%;">Code is well documented using a combination of meaningful variable and function names, and comments</td>
+            <td style="width: 49.9772%;">2</td>
+        </tr>
+        <tr>
+            <td style="width: 49.9772%;">Include file contains comments describing the behavior of each function in the interface.</td>
+            <td style="width: 49.9772%;">5</td>
+        </tr>
+    </tbody>
+</table>