User Tools

Site Tools


Sidebar

projects

pct0 (bonus; due 20230823)
wcp1 (due 20230823)
abc0 (due 20230830)
btt0 (due 20230830)
pct1 (bonus; due 20230830)
pct2 (due 20230830)
wcp2 (due 20230830)
mpg0 (due 20230906)
pct3 (bonus; due 20230906)
wcp3 (due 20230906)
pct4 (due 20230913)
ttb0 (due 20230913)
wcp4 (due 20230913)
pct5 (bonus; due 20230920)
ttb1 (due 20230920)
wcp5 (due 20230920)
dap0 (due 20230927)
gfo0 (due 20230927)
pct6 (due 20230927)
wcp6 (due 20230927)
cgf0 (due 20231004)
pct7 (bonus; due 20231004)
wcp7 (due 20231004)
bwp1 (bonus; due 20231018)
pct8 (due 20231018)
wcp8 (due 20231018)
yol0 (due 20231018)
bjm0 (due 20231025)
pct9 (bonus; due 20231025)
wcp9 (due 20231025)
bjm1 (due 20231101)
gfo1 (due 20231101)
pctA (due 20231101)
wcpA (due 20231101)
pctB (bonus; due 20231108)
set0 (due 20231108)
wcpB (due 20231108)
mor0 (due 20231115)
pctC (due 20231115)
wcpC (due 20231115)
bwp2 (bonus; due 20231129)
pctD (bonus; due 20231129)
wcpD (bonus; due 20231129)
gfo2 (due 20231206)
pctE (bonus; due 20231206)
wcpE (bonus; due 20231206)
EoCE (due 20231214)
haas:fall2023:discrete:projects:bdb0

Corning Community College

CSCS2330 Discrete Structures

PROJECT: Binary De-Bugging (BDB0)

OBJECTIVE

To enhance our ability to explore various algorithmic and computing realms through the exploration and cultivation of debugging and troubleshooting skills, and collaboratively authoring and documenting the project and its specifications.

GRABIT

To assist with consistency across all implementations, data files for use with this project are available on lab46 via the grabit tool. Be sure to obtain it and ensure your implementation properly works with the provided data.

lab46:~/src/SEMESTER/DESIG$ grabit DESIG PROJECT

OVERVIEW

Your task is to write a debugging tool to help in your future rleX encoding/decoding efforts. A custom-purpose binary diff tool that gives us a quicker, more helpful view into the first by of difference that exists between two given files.

Contributing to project documentation is also a core part of this project. If from reading the existing documentation or through your own exploring, you find something lacking, unclear, or outright missing, that is an opportunity to potentially contribute content.

You want the project documentation to provide you (as if coming in with no awareness of the project) with sufficient information so as to allow you to proceed. Asking questions on the discord is a great way of getting more information that you can use to add content.

EDIT

You will want to go here to edit and fill in the various sections of the document:

BACKGROUND

In the previous week, we encountered a diversity of errors while developing our codes for the RLE0 encoder and decoder. One of the most frequent errors we found ourselves struggling with was a mismatch between the bytes contained within the files processed by our programs and the sample files. As a way to debug those issues, some of us resorted to comparing the MD5SUMS hashes or the binaries with a hex editor of both files. In other words, we were dependent on other already existing tools to patch our bugs. However, these tools have one flaw they are not specified RLE debugging tools. If only we could find the perfect tool that meets our needs, or better yet, if only we could develop our own debugging tools for an improved RLE algorithm development experience. (I feel like I managed to channel my inner Matt there :P)

Therefore, this week, for bdb0 we are tasked to write a debug tool that will be used in future rleX projects. This debug tool will compare two binary files, one being the output of our encoder/decoder, and the other being some reference file.

SPECIFICATIONS

BDB0 will take two arguments, two different files that will be compared to each other:

./bdb0   FILE1.txt  sample1.txt
Argv[0]  Arg[1]     Arg[2]

These files are not necessarily RLE-specific, you could use bdb0 to compare any files together.

The main focus of this program is to help us compare binaries, displayed in hexadecimal values, similar to a hex editor, only displaying the mismatched data. Hence, the output should be the line byte of discrepancy, along with the previous and following 16 bytes and the address of those bytes

*Our task is to ask questions on Discord or in class and document our findings on this wiki page collaboratively, regarding the functionality of this project.

WIKI EDGE PAGE *For anybody interested in editing the wiki page, here is the dokuwiki user guide: https://www.dokuwiki.org/wiki:syntax#basic_text_formatting -Ash

PROGRAM

When checking to verify that one's project functions as intended, it should be borne in mind that the verify program included in the grabit does not work, so it will ultimately be up to you to check the program. Ways this may be done include using the diff and xxd commands, and testing your project with with the files included in the in sub-directory. I myself found it useful to custom-create a few files in order to ensure certain edge cases occurred, such that they may be tested for (bear in mind this project is a debugger to assist us in future projects, so leaving flaws is likely sub-optimal).

OUTPUT SPECIFICATIONS

This is an example of the output of the program:

lab46:~/src/SEMESTER/DESIG/PROJECT$ ./bdb0 example0 example1
==============================================================================================================
|000000e0 | 5325 2525 2525 2574 2525 7474 2574 7474   ||   5325 2525 2525 2574 2525 7474 2574 7474 | 000000e0|
|000000f0 | 5252 5252 5252 5245 4545 4545 4545 4545   ||   5525 1b5b 303b 353b 3337 3b34 366d 401b | 000000f0|
|00000100 | 5b30 3b31 3b33 363b 3437 6d53 1b5b 303b   ||   5b30 3b31 3b33 363b 3437 6d53 1b5b 303b | 00000100|
==============================================================================================================

This is the structure:

The middle line, called mismatch, is the focus of the program, and it should be displayed in a different color with the use of ANSI escape codes.

The program is to display 16 bytes prior to, 16 bytes of, and 16 bytes after the first byte of difference detected in the two files. If either the 16 bytes prior or 16 bytes after the mismatch are not data from the file, in other words, you've reached the end of the file and there is no more data to display, you may display it with a NULL character (0x00, '\n'). You can display it with other characters, should you prefer dots, dashes, or other characters that could represent the end of the file. However, make sure these cannot be possible reoccurrences elsewhere in the file.

Example: In this example you see a mismatch happening right on the very first bytes of the file. Since there is no previous data to fetch, this lack of data is then displayed as NULL.

The address portion is a line count in hexadecimal format.

The colors you use are up to you, but some coloring has to happen. So far it is required that three parts of the output are displayed in different colors, the addresses (on both sides), the data (both sides), and the mismatched bytes line.

Important

Your program should only print the FIRST mismatch, NOT the entire document neither every mismatched line of bytes. JUST THE FIRST ONE along the previous and next bytes. Also make sure that you deal with edge cases in your program. Your file should be able to handle mismatches at the very start of the compared files and the very end of the compared files.

VERIFICATION

When running the program with two DIFFERENT files, the program should display the line containing the first byte that is mismatched, with the leading/post 16 bytes.

When running the program with two SAME files, the program should display nothing. The normal process of using make check to check your file against the desired result won't work in this case. The verify file is that of a different year when different specifications were desired. Running it this time around will lead you to many mismatches and headaches. You can check your output against the pictures provided above as a general guideline but other than that it is essential that if you have any questions to just ask in discord instead of guessing and hoping it is what is desired. Most of the desired output is already located on the project page.

Approaches

I think there are two approaches people have taken with the display of information with this project:

or



The main thing of note here is the position of the first mismatched bit in its line. In the first implementation, bytes are displayed chronologically, with the leftmost bit always being a multiple of 16. The second implementation has the mismatched bit always in the leftmost position and never in the middle of a line. The approach you take comes down to personal preference as is with a lot of this project, since we don't have a strict verify script to check output with.

 

SUBMISSION

To be successful in this project, the following criteria (or their equivalent) must be met:

  • Project must be submit on time, by the deadline.
    • Late submissions will lose 33% credit per day, with the submission window closing on the 3rd day following the deadline.
  • All code must compile cleanly (no warnings or errors)
    • Compile with the -Wall and –std=gnu18 compiler flags
    • all requested functionality must conform to stated requirements (either on this document or in a comment banner in source code files themselves).
  • Executed programs must display in a manner similar to provided output
    • output formatted, where applicable, must match that of project requirements
  • Processing must be correct based on input given and output requested
  • Output, if applicable, must be correct based on values input
  • Code must be nicely and consistently indented
  • Code must be consistently written, to strive for readability from having a consistent style throughout
  • Code must be commented
    • Any “to be implemented” comments MUST be removed
      • these “to be implemented” comments, if still present at evaluation time, will result in points being deducted.
      • Sufficient comments explaining the point of provided logic MUST be present
  • No global variables (without instructor approval), no goto statements, no calling of main()!
  • Track/version the source code in your lab46 semester repository
  • Submit a copy of your source code to me using the submit tool (make submit on lab46 will do this) by the deadline.

Submit Tool Usage

Let's say you have completed work on the project, and are ready to submit, you would do the following (assuming you have a program called uom0.c):

lab46:~/src/SEMESTER/DESIG/PROJECT$ make submit

You should get some sort of confirmation indicating successful submission if all went according to plan. If not, check for typos and or locational mismatches.

RUBRIC

I'll be evaluating the project based on the following criteria:

78:bdb0:final tally of results (78/78)
*:bdb0:used grabit to obtain project by the Sunday prior to duedate [13/13]
*:bdb0:clean compile, no compiler messages [13/13]
*:bdb0:implementation passes verification tests [13/13]
*:bdb0:adequate modifications to code from template [13/13]
*:bdb0:program operations conform to project specifications [13/13]
*:bdb0:code tracked in lab46 semester repo [13/13]

Pertaining to the collaborative authoring of project documentation

  • each class member is to participate in the contribution of relevant information and formatting of the documentation
    • minimal member contributions consist of:
      • near the class average edits (a value of at least four productive edits)
      • near the average class content change average (a value of at least 256 bytes (absolute value of data content change))
      • near the class content contribution average (a value of at least 1kiB)
      • no adding in one commit then later removing in its entirety for the sake of satisfying edit requirements
    • adding and formatting data in an organized fashion, aiming to create an informative and readable document that anyone in the class can reference
    • content contributions will be factored into a documentation coefficient, a value multiplied against your actual project submission to influence the end result:
      • no contributions, co-efficient is 0.50
      • less than minimum contributions is 0.75
      • met minimum contribution threshold is 1.00

Additionally

  • Solutions not abiding by spirit of project will be subject to a 50% overall deduction
  • Solutions not utilizing descriptive why and how comments will be subject to a 25% overall deduction
  • Solutions not utilizing indentation to promote scope and clarity or otherwise maintaining consistency in code style and presentation will be subject to a 25% overall deduction
  • Solutions not organized and easy to read (assume a terminal at least 90 characters wide, 40 characters tall) are subject to a 25% overall deduction
haas/fall2023/discrete/projects/bdb0.txt · Last modified: 2022/09/15 11:27 by 127.0.0.1