Programming Lessons

1. Have a descriptive, consistent naming convention.
2. If you write the same code three times, turn it into a function/macro. I have never regretted this.
3. Keep functions to half a page. Modularity is good! Fuction calls aren't that expensive anymore.
4. Have and use debugging functions! They will save you hours of work. Read my page on debugging, and debug.h.
5. Optimization: http://www.leto.net/docs/C-optimization.html
6. Debugging: http://www.csd.uwo.ca/%7ejamie/.Refs/misc_debug.html

My Software Bugs

• Compilation
  • Incorrectly compiled program. Used 'make' instead of 'make boot'.
  • Wasn't actually compiling what I needed. My "make" didn't create a new output file "clientr" -- I was using an old, stale copy.
  • Included a header multiple times. To avoid, use:
    #ifndef MYFILE_H
    #define MYFILE_H
    // header file contents
    #endif
  • Didn't restore code previously commented out. I forgot to put important code back in that I had commented out for testing.
• Dereferenced uninitialized pointer
  • It had some garbage value, got garbage results.
• Segmentation faults
  • printf: used %s instead of %d. Arrgh.
  • Printed s->parent->num_free in a debugging statement. Didn't check if s->parent existed (I assumed it did), and crashed.
• C language
  • Used = instead of == in an assert statement. It was always true.
  • Order of oprations error: *myIntPointer++ is not (*myIntPointer)++. Don't trust order of operations, use ()
• Confusion about...
  • Function argument
    • Passed the wrong parameter as the size of a table. I passed the size of the cache (bytes), not the number of entries in the table. Huge table = failed malloc calls. Comment functions well.
  • Variable names
    • Unknowingly declared two global variables with similar names (xv and vx), and mixed them up. Physics told me to use vx as the velocity in the x direction, computer science told me to use the other.
  • Offset: relative or absolute?
    • I used += (relative offset) instead of = (absolute offset) when computing the new position.
  • Big and little endian issues, network and host byte order confusion.
    • Main fix: keep everything in network order, and convert it to host order when reading it. Do NOT change it in-place, or you'll get confused about what order it is in. Read my article on big/little endian issues, and read the man pages for htons and htonl.
• Error messages
  • 'bind: address in use' errors when opening TCP connection.
    • TCP connections must wait for a 120 second timeout before resuing a port. Easy fix: Change the port number. Another fix: use SO_REUSEADDR in setsockopt call.
• GDB debugging
  • Attach to running process: use gdb filename pid
  • Calling functions: call function(arg1, arg2). I've seen it work on Linux, but not on certain flavors of Unix.
• Interrupts
  • Didn't disable interrupts when performing processing. As a result, got interrupted within processing.
  • Use locks with multiple threads!
• Screen output
  • Wasn't looking high enough on output in terminal window, and didn't start at the beginning. Solution? Type an "L", get an invalid command. Then press ENTER many times, so you get a "clear" screen. Now run program. Look for that blank area -- that's where you start.
  • Had too many debugging statements -- getitng screenfuls of detailed garbage. Separated debug statements into two parts (DEBUG and DEBUG_2), could print out each part individually: if (DEBUG) then ... , if (DEBUG_2) then ... . Very useful.

Hardware Bugs

• Faulty hardware! Arrgh.
  • Faulty wire. Some wires had really loose connections, others had internal disconnections. Test both ends of the pins you are connecting - don't assume the wire is good.
  • Faulty SRAM chips and faulty FPGA. We examined the data going in and out of the SRAM and it didn't match. Certain pins were always 0. Replacing the chips took 5 minutes (socket connections), but discovering they were bad took hours.
    
• Hardware bit order confusion (similar to big-little endian problems, but with bits)
  • We had our input switches backwards, with the least significant bit on the left.
  • My solution? Turn the board around. Upside-down binary is backwards binary =)