Common Mistakes and Good techniques

[Galandros]

Well I would like to see a good post with common mistakes and good techniques for assembly.

-------------------------------------------------------------------------------------------------

Common mistakes:

Compiler issues: (here: assembler working and syntax issues)
General:
- miss include file in the compiler folder or include in the source code
- include file is not compatible for your compiler (links: spasm and tasm)
- wrong usage in command line (in case you use it)
- duplicate define and label
wrong instructions typing: (most common)
- Watch out for b_call/bcall macro...
- sub a,8 instead of sub 8 (I got it wrong many times)
- Doing a ld a,(port) in place of a in a,(port), or similar. (e.g. out)
- making ex hl,de instead of ex de,hl (note: some assemblers may work with ex hl,de)

- in APPS don't forget to set .org to $4000 in every page
- in APPS code/data can pass from one page to another...
- in APPS self modifying code does not work. Take a look at routines you may use...

- Extra or missing directives (an #endif without an #ifdef, etc)
- Mistaking .DB for .DW or .DS
- Single-quotes inside text strings (ex: "Don't do this!"). Note some assemblers allow this
- Order of operations or parenthesis errors (assemblers evaluate from left to right without giving priority to any operator)
- Mistakenly typing a colon instead of a semi-colon, or vice-versa. (Depending on the font, this isn't just tricky, it's physically hard to see)

TASM specific:
- miss TASM80.TAB
SPASM specific:
- to the b_call macro work you have to comment this line in case you have it in your include: ;.addinstr B_CALL * EF 3 NOP 1
- make sure you have the latest version (link)

ASM coding itself (wrong instructions, bad registers and instructions use)
- load data from an address in A, not in the other 1-bit registers... (e.g. ld e,(data) such instruction don't exist)
- in port access don't forget to retrieve/pass values (and correct values) from ports

- calling routines that don't preserve registers or destroys them unintentionally (common bug)
- pushes without popes (there are exceptions in advanced uses)
- pushes and don't pop before a ret (also exist a very nice advanced use)
- jump somewhere after push confuses the stack usage... better double check
- mess the "TI-OS"'s RAM or shell safe rams
- forget to disable interrupts when using shadow registers or stack pointer
- Unintentionally altering IY OR SP while interrupts are active

- Sprite routine you are using doesn't clip (symptoms: sprite passes from an part of the screen to another and/or you destroy TI-OS RAM)
- forget/confuse inputs for a routine (like ionputsprite and iongetpixel, look at the register used to y input)

VERY STUPID things and miscellaneous
- do not use use your own calculator for general testing purposes! You can search and use one of many emulators around. (See Emulators here)
. links: pindurti : pindurti documentation) : wabbitemu
tips: use pindurti for debugging because the debugger is stable and wabbitemu for screenshooting because of the GUI.
Even if you can't ROM dump your calculator use the TI emulator in their SDK page. (download here)
. experiment rom8x to dump your rom

Nspire compatibility:
- if you use unsupported instructions, your program will crash on a nspire emulating the TI-84 SE. So or you replace them or warn in the readme.
- see bellow or in the instruction set what instructions are marked as unsupported or undocumented
- ASM in 28 days has some mistakes:
. Day 13 - Vector table routine instead of LD HL,HL it is ADD HL,HL .(think before seeing)
. check this link

-------------------------------------------------------------------------------------------------

Good techniques and programming practises (source code and asm optimizations and techniques)
Source code:
- think before programming, make your pseudo code, variables and such even in a quite simple program.
- Keeping an Instruction Sheet Summary readily available.
- always good to maintain your source code "clean" and shining (related to next)
- Documenting routines for INputs, OUTputs, DESTROYED registers. Always a good investment on large projects.
- Commenting not on what an instruction does, but why it's doing it.
- Rigorous use of comments.
- Meaningful label names that you can remember.
- Not backing up frequently. (i.e.: saving to removable media, ftp servers, mail inbox, or other fail-safes)

Code optimization:
- Overuse of IX and IY when other faster, "cheaper" registers are available for use
- Consistent use of the registers for certain situations (HL for addresses, IX & IY for table indexing, B and BC for loops and counters; for example)
- even if you have a very used routine that is less than 4 bytes, don't use a call and ret to use it. Use as a macro instead! (another mistake by me) Because call is 3 bytes plus the ret 1 bytes means you are wasting speed and space.

Others:
- Searching some useful and optimized routines
- Search forums and others resources before doing some reusable code
- Visiting forums for new ideas!

-------------------------------------------------------------------------------------------------

Debugging tips and habits:
- leave risky optimizations to later part of development (note it to note forget)
- while you are a beginner debug on emulator frequently the new code so you know that the older code is not buggy
- even being good it does not hurt debugging time to time. Catching errors early is good
- don't forget to watch what happened to your variables in RAM
- if you cannot find how it crash then: (and you are getting desperate)
. - try to pinpoint the place where the error occurs by exiting the program in different places then see what is up in that part (sometimes this is not possible)
. - debug little parts of code (sometimes this is not viable)
- if you want to stop the emulator without breakpoints and altering registers use this macro: #define STOP jp $ . . . .tip: use step over in the debugger to continue
- sometimes is better to leave the computer for some time and when you come back the error seams now clear
debugging macros:
#define STOP jp $ ;stops the CPU in this command execution. DON'T USE ON A REAL CALCULATOR
(more useful to come!)

-------------------------------------------------------------------------------------------------

Also I would like to provide good but as simple as possible source codes to others to learn.

Links:
Related topics to this topic:
Other good programming practises in WikiTI
WikiTI (large documentation of TI-OS)
TI documentation (search in TI SDK)

Numerous routines:
ticalc source codes and routines
see Ion's source code (download Ion here)
WikiTI routines
Detached Solutions Forum Useful Routines
UnitedTI Forum Useful Routines
Revsoft Forum Useful Routines (some interesting finds)
Maxcoderz Useful Routines
Cemetech Useful Routines
z80 bits Routines (math and others)

Optimization:
Little tricks: http://www.junemann.nl/maxcoderz/viewtopic.php?f=5&t=675
Looping: http://map.tni.nl/articles/fast_loops.php

Sample programs:
Revsoft example of a shooter: star.asm (Spencer is always giving it)

Techniques:
- design a good data arrange (there is no right formula so just adequate it to your game after think long)
Simple tilemap: http://www.unitedti.org/index.php?showtopic=8189
Animated sprites: http://www.unitedti.org/index.php?showtopic=7622
- physics (idea of velocity, acceleration and vectors implementation)
- hit detection hint (for every object have a wide value and if need a height value then check for x, x+w, y, y+h "hits" the position of player) (eg: here)
General: List of Maxcoderz programming topics
Dwedit tilemaper + help: http://www.junemann.nl/maxcoderz/viewtopic.php?p=901
jim_e tilemapper: http://www.revsoft.org/phpBB2/viewtopic.php?t=34
[Z80-asm] Advise about tilemapping: http://www.junemann.nl/maxcoderz/viewtopic...?f=5&t=2538
Small Smoothscrolling tilemap:
http://www.revsoft.org/phpBB2/viewtopic.php?t=614
http://www.junemann.nl/maxcoderz/viewtopic...?f=5&t=2305
tilemap: http://www.revsoft.org/phpBB2/viewtopic.php?t=820
[TI ASM/pseudo] General algorithms http://www.junemann.nl/maxcoderz/viewtopic...?f=5&t=2405
Generic game engine: http://www.revsoft.org/phpBB2/viewtopic.php?t=824
Special events: http://www.junemann.nl/maxcoderz/viewtopic.php?t=887
AI movement: http://www.gamedev.net/reference/articles/article2003.asp
Search for algorithms and techniques in the following sites:
General: Wikipedia
Game's techniques: http://www.gamedev.net/

See in ASM in 28 days:
- TASM error messages (may help to solve errors given by the assembler)
- some interesting techniques in: DAY 14. Procedures

Finally, you can see programming ideas:
UnitedTI
Revsoft
Maxcoderz
Omnimaga

-------------------------------------------------------------------------------------------------
TO DO:
- This is getting big so at this rate I will make more "chapters", they are already sorted in some logic like mistyping instructions are together and the source code practises too. (not yet)
- dare to suggest some documentation or forum posts to the asm routines above.

REQUESTS:
- if you disagree with something and would like to change a issue to another place or something picky and/or small PM me instead of replying, please.
-------------------------------------------------------------------------------------------------
Contributions:
- DigiTan
- darkstone knight

All the asm programmer scene thanks!
-------------------------------------------------------------------------------------------------
Conclusion: before you start programming z80 assembly the first time, take a look and enjoy from tips of more practised programmers.
Also some general tips serve to basically any language.
-------------------------------------------------------------------------------------------------

Ok I can't push more for now. Try to reply only when absolutely necessary.
I want this bright and help others after me. If I read something like this before could help me.

"Some" mistakes I shared were mine ^^ I noticed that some were pretty bad during classes or while walking... I am programming 70% of the time awaken. :P

PS: I searched and I think there isn't a topic like this in UnitedTI at least.
EDIT: 16/01/09 verification
- moved things a little and corrected others;
- waiting feedback before I add emulator and debugging stuff;
- made a backup.
EDIT: 1/2/09 news
- added debugging tips
- lots of links and more links
- taken out of topic old edits history
- Made another backup
EDIT: 28/2/09
- nspire compatibility
- some more links ^^
EDIT: some times
- minor stuff
EDIT: 20/4/09
- more errors added
- all links filled
- debugging macros
useful for links...

[darkstone knight]

thats pretty cool

another "common" mistake:

you can only load data from an adress in A, not in the other 1-bit registers...

it hapened to me MANY TIMES (like 3 times each project..........)

[DigiTan]

This topic was a really good idea. We haven't had one close to it in ages. It may even become...pin worthy!

Common mistakes:

Here's stuff I've caught myself or colleagues doing at one time or another. Sometimes, it's inexperience. Other times, it's just a bad typing finger day. Excluding optimizations...

Assembler Issues: (General pitfalls)
- Extra or missing directives (an #endif without an #ifdef, etc)
- Mistaking .DB for .DW or .DS
- Unintentionally altering IY while interrupts are active
- Overuse of IX and IX when other faster, "cheaper" registers are available for use
- Doing a ld a,(port) in place of a in a,(port), or similar.
- Single-quotes inside text strings (ex: "Don't do this!"). Note some assemblers allow this
- Order of operations or parenthesis errors
- Mistakenly typing a colon instead of a semi-colon, or vice-versa. (Depending on the font, this isn't just tricky, it's physically hard to see.)
- Not backing up frequently. (ie: saving to removable media, ftp servers, mail inbox, or other fail-safes)

Good techniques

- Keeping an Instruction Sheet Summary readily available.
- Documenting routines for INputs, OUTputs, DESTROYED registers. Always a good investment on large projects.
- Commenting not on what an instruction does, but why it's doing it
- Rigorous use of comments.
- Consistent use of the registers for certain situations (HL for addresses, IX & IY for table indexing, B and BC for loops and counters; for example)
- Meaningful label names that you can remember
- Visiting forums for new ideas!

Overall, I'm big fan of thorough commenting and documentation. And it doesn't matter which language it is. Even for an expert, being able to retrace your own footsteps will save a lot of wandering in routines you don't visit often.

[simplethinker]

I know you want this to just be for listing the mistakes/techniques, but could you elaborate on the "- ASMin 28 days has some mistakes. I will try to share them..." part, as I'm using it right now.

[magicdanw]

I don't remember any crippling 28 days mistakes. The only big one I recall was that the sprite routines listed the incorrect inputs, or didn't work, or something. Just keeps you on your toes!

[Galandros]

Good to see your (very) positive comments. Good contribution DigiTan ;)

The idea appeared because I started programming and because asm has many issues where you can get wrong and I have being discovering slowly my mistakes, if you could share something, we all benefit.
Like I said if I read this before programming I roughly skipped 1 hour of free time debugging.

I will try to maintain the first post updated and I will see now which errors the version of ASM in 28 days has. I remember well one in vector table routine. At least in my copy of the tutorial it is wrong and the version in .chm and .html.
Also contributors gain their credit.

[Madskillz]

This is a great contribution, has a lot of potential to be something really important for all the beginners! Keep updating it, I will try and dig up some mistakes.

[Brazucs]

[Galandros]

You can see in the EDIT history what I have being doing...
I started using SPASM so one more.
I even added some apps mistakes! But this time weren't mine.

And thanks for pinning. This will certainly help others.

In some days I will stay out of here until next year. And I would be glad if I see new contributions. :ninja:

[Galandros]

Fresh new idea that came during holidays:

Debugging tips and habits:
- while you are a beginner debug on emulator frequently the new code
- even being good it does not hurt debugging time to time

- if you cannot find how it crash then: (and you are getting desperate)
. - try to pinpoint the place where the error occurs by exiting the program in different places then see what is up in that part (sometimes this is not possible)
EDIT: - if you want to stop the emulator without break points use this: #define STOP jp $ (just posting, discuss utility)

- sometimes is better to leave the computer for some time and when you come back the error seams now clear.

Someone has something to add or a better suggestion before I edit the first post?

[Galandros]

[Iambian]

Debugging stuff, eh?

I like to have a macro definition in some of my apps that read as follows:

[Galandros]

[Galandros]

What do you think of when you are debugging and miss the problem use this code to find out faulty usage of SP or IY?
;in the start:
ld (savesp),sp
;before quiting:
ld sp,(savesp)
savesp:
.dw 0
;before quiting
ld iy,flags ;flags=89F0h
If using this code doesn't crash means that you used bad SP or IY... I can do the macros later.
This can be useful or is simpler to use the debugger options in emulator?

Also updates to the topic!

[Galandros]

*updated*

About nspire compatibility: are all "undocumented" and "unsupported" instructions not featured in the emulation layer?
And making the list of them: sll (shift left logic), use of ixh, ixl, iyh and iyl registers in instruction like ld, add, etc.
There is other things to mind? I think there is the usb emulation... ports? not sure.
Maybe I should search hackspire, but I am in my laziness moment right now.

And don't forget my reply right above this one.

[FloppusMaximus]

I don't have an Nspire myself (probably a rant best saved for another time.) From what I've read, though, I would guess that you're correct and it does not emulate any of the undocumented Z80 instructions (or undocumented aliases such as ED4C.) (TI's Flash Debugger never has, either; it wouldn't surprise me if the Nspire's 84+ emulator uses the same Z80 emulation code.)

The undocumented instructions:
- inc/dec/ld/add/adc/sub/sbc/and/xor/or/cp instructions involving ixh/ixl/iyh/iyl
- slia anything
- rlc/rrc/rl/rr/sla/sra/slia/srl/res/set with load, eg. DDCB0000
- in (c)
- out (c),0

Undocumented aliases:
- bit n,(ix/iy+m) (e.g. DDCB0040)
- neg (e.g. ED4C)
- retn (e.g. ED5D)
- im 0 (ED4E, ED66, ED6E)
- im 1 (ED76)
- im 2 (ED7E)
- I'm just guessing here, but the Nspire might also choke on double prefixes (FDDD23 = inc ix) or other useless prefixes (DD04 = inc b).

As I understand it, the Nspire doesn't emulate the 84+ USB hardware at all; it uses its own magic opcodes instead.

Anyway, as far as "good techniques" go, at this time I would recommend avoiding undocumented instructions in most 83+ assembly programs, for the benefit of those poor souls who are stuck with Nspires. It's fine to use undocumented instructions on the 73, 82, 83, 85, and 86, though -- some recent versions do not support all of the Z80's quirks, such as the WZ register, but I believe all of them support the full instruction set.

(P.S. Oh, God! I just had a terrifying idea: what if TI were to make a special French edition of the Nspire which emulates the TI-82 STATS instead of the 84+? The horror...)

[darkstone knight]

dont forget autocopy instuctions

http://dragonfire.unitedti.org/asmin28/ref/z80is.html

[FloppusMaximus]

Er, do you mean

[darkstone knight]

uhuuu... no

[Galandros]

Ok. I will add soon the nspire compatibility and better instruction set of the z80 I found in OTBP that calcmaniac told me in IRC. Finding it was hard, but it was on my hard drive.
I have been seeing Revsoft and Maxcoderz foruns so new links will appear.

Also I feel like understanding and doing an tutorial to access multi pages APPS. It is a common question that I hope to get rid of. :P

This reply acts kind of a to do note so I won't forget... xD

VERY LATE EDIT: why not make a more general apps tutorial/guide. It is intended to be quick to shows and explains a bit about multi pages, header, alocating problems, etc..