gbadev.org forum archive

This is a read-only mirror of the content originally found on forum.gbadev.org (now offline), salvaged from Wayback machine copies. A new forum can be found here.

OffTopic > Need some code walkthrough advice

#156751 - simonjhall - Tue May 13, 2008 6:45 pm

We're looking to complete the development of a load of code at work at the moment and this involves the people who wrote the code doing a walkthrough of their stuff.
We've already done the walkthrough of the stuff that my boss wrote (in C++) and he did this by printing off all the code, and loads of UML and class definitions (their headers and doxy comments). This went pretty well.

I wrote the algorithms which interface with his code (as he wrote the outer logic) and my code is mainly non-branchy-ish code in tight loops. I don't think that printing off the class diagrams is appropriate (as there are no classes) and starting with the code first will be difficult. These algorithms come in three categories:
1) infrequently called stuff, written in C
2) fast code, written in high-level intrinsics, unrolled a bit and scheduled by the compiler
3) uber-13:37 ultra-pipelined and hand optimised assembly code (the bit I'm most worried about)

The people I'm doing it to have little experience with assembly so I don't want to dive in, plus all the code is out of order so stepping through the uber-1337 stuff line by line is gonna be a nightmare... However the people I'm doing this to want to go through it in order to maintain the code in case I quit. Another point of the walkthrough is that they're there to spot mistakes, so if they're not familar with the ISA I'm literally going to have to get out the manual for every instruction.

So...has anyone done this sort of thing before and would you be willing to offer advice about what worked and what didn't? I'd really appreciate any help!

PS: I went through the high-level algorithm to 3) today and all the stuff I did to make the code run the way it did...but without looking at any assembly, instead using a bit flow chart/graph thing where each node is an instruction with the description in pseudocode.
_________________
Big thanks to everyone who donated for Quake2

#156755 - Miked0801 - Tue May 13, 2008 7:17 pm

Hopefully, you got your uber leet asm code commented per line such that it reads almost like a book. That is how we maintain that sort of code. Even people like me who love to play with assembler don't appreciate page after page of code without comments. Here's my style on this:

Code:

; A function to do uber leet stuff
; It expects r0 to contain 0xdead or 0xbeef
; It returns 0xbeef or 0xdead
foo:
   ldr   r1,foo_pool      ; Get the compare values
   cmp   r0, r1,lsr 16    ; Is this 0xdead?
   mov   r0,r1            ; Either way, load in our return values
   andeq r0,0xffff        ; If it was dead, load in beef
   movne r0,r0,lsr 16     ; else shift down the dead value
   bx lr                  ; Return
foo_pool:
   dw 0xdeadbeef          ; Our compare values
 


You can read the comments as English without really needing to know what I'm doing in the assembler. So can anyone else who comes in later. I will occasionally make a larger comment area and skip a few lines of comments, but generally comment each line.

PS, unteseted written in 5 minutes assembler code may to compile :)

#156760 - simonjhall - Tue May 13, 2008 7:59 pm

Yeah luckily I commented the sh!t out of it! Uncommented assembly is just rude ;-)
Thing that's really bothering me is the pipelined nature of the code as several parts of the algorithm are all interleaved. Should I step through each part of the algorithm (ie skipping from instruction to instruction), or just plow directly through it ie follow all the threads of the algorithm as I go?
_________________
Big thanks to everyone who donated for Quake2

#156761 - silent_code - Tue May 13, 2008 8:07 pm

you could give visual cues by making the portions, that are interleved and don't belong to the currently discussed code fragment, "transparent" (some light color). that way you don't have to tear the code apart.
hope you get what i'm trying to say. ;^)

ps: don't try fancy colors for different parts of the algorithm. if you have synesthetics ("'A' is red"... at least that's true for most of them) in your company, that will probably only confuse them. even "normal" people will have problems reading the stuff. ;^)
_________________
July 5th 08: "Volumetric Shadow Demo" 1.6.0 (final) source released
June 5th 08: "Zombie NDS" WIP released!
It's all on my page, just click WWW below.

#156781 - simonjhall - Tue May 13, 2008 10:48 pm

Yeah that's not a bad idea, actually. Walking through one run of the loop and crossing instructions off couldn't hurt either...
_________________
Big thanks to everyone who donated for Quake2

#156785 - silent_code - Tue May 13, 2008 11:33 pm

ps: i don't know how that "presentation" should look like, but i was thinking of a powerpoint style ;^)
_________________
July 5th 08: "Volumetric Shadow Demo" 1.6.0 (final) source released
June 5th 08: "Zombie NDS" WIP released!
It's all on my page, just click WWW below.

#156800 - DekuTree64 - Wed May 14, 2008 12:31 am

I would try writing a plain English or pseudocode version of each algorithm being done, so you have something to point at as you step through the assembly code and try to explain all the things that are happening.

Assembly code is much easier to work with if you know what it's trying to do, and not just what it is doing.
_________________
___________
The best optimization is to do nothing at all.
Therefore a fully optimized program doesn't exist.
-Deku