X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=docs%2Fnote-on-the-op-assembler.txt;fp=docs%2Fnote-on-the-op-assembler.txt;h=8a3d14b41d79c4bf7b85ef3171f5f5996fe4b93d;hb=261f8d9198c4235bcdced4403ba391553e6bd0d1;hp=0000000000000000000000000000000000000000;hpb=ae528e6fdb8bd5c41ed9690bec03402ccbb4ecae;p=rmac diff --git a/docs/note-on-the-op-assembler.txt b/docs/note-on-the-op-assembler.txt new file mode 100644 index 0000000..8a3d14b --- /dev/null +++ b/docs/note-on-the-op-assembler.txt @@ -0,0 +1,129 @@ +A Few Notes on the New Object Processor Assembler +------------------------------------------------- + +Q: What is it? + +A: An assembler to generate object lists for the Atari Jaguar's Object + processor. + + +Q: Why is it here? + +A: To really utilize the OP properly, it needs an assembler. Otherwise, what + happens is you end up writing an assembler in your code to assemble the OP + list, and that's a real drag--something that *should* be handled by a proper + assembler. + + +Q: How do I use it? + +A: The OP assembler works similarly to the RISC assembler; to enter the OP + assembler, you put the .objproc directive in your code (N.B.: like the RISC + assembler, it only works in a TEXT or DATA section). From there, you build + the OP list how you want it and go from there. A few caveats: you will want + to put a .org directive at the top of your list, and labels that you want to + be able to address in 68xxx code (for moving from a data section to an + address where it will be executed by the OP, for example) should be created + in .68xxx mode. + + +Q: What are the opcodes? + +A: They are bitmap, scbitmap, gpuobj, branch, stop, nop, and jump. nop and jump + are psuedo-ops, they are there as a convenience to the coder. + + +Q: What are the proper forms for these opcodes? + +A: They are as follows: + + bitmap , , , , , , , + , , , + scbitmap , , , , , , + , , , , , + , , + gpuobj , (bits 14-63 of this object) + branch VC )> , + branch OPFLAG, + branch SECHALF, + stop + nop + jump + + Note that the field in bitmap and scbitmap objects consist of the + following: REFLECT, RMW, TRANS, RELEASE. They can be in any order (and + should be separated by whitespace *only*), and you can only put a maximum of + four of them in. Further note that with bitmap and scbitmap objects, all the + parameters after are optional--if they are omitted, they will + use defaults (mostly 0, but 1 is the default for pitch). Also, in the + scbitmap object, the , , and fields can be + floating point constants/expressions. can refer to any address + defined (even external!) and the linker (rln v1.6.0 or greater) will + properly fix up the address. + + +Q: What do they do? + +A: Pretty much what you expect. It's beyond the scope of this little note to + explain the Jaguar's Object Processor and how it operates, so you'll have to + seek explanations for how they work elsewhere. + + +Q: Why do I want to put a .org directive at the top of my list? + +A: You want to put a .org directive at the top of your list because otherwise + the assembler will not know where in memory the object list is supposed + go--then when you move it to its destination, the object link addresses will + all be wrong and it won't work. + + +Q: Why would I copy my object list to another memory location? + +A: Simple: because the OP destroys the list as it uses it to render the screen. + If you don't keep a fresh copy stashed away somewhere to refresh it before + the next frame is rendered, what you see on the screen will not be what you + expect, as the OP has scribbled all over it! + + +Q: Does the assembler do anything behind my back? + +A: Yes, it will emit NOPs to ensure that bitmaps and scbitmaps are on proper + memory boundaries, and fixup link addresses as necessary. This is needed + because of a quirk in how the OP works (it ORs constants on the address + lines to get the phrases it needs and if they are not zeroes, it will fail + in bizarre ways). + + +Q: Why can't I define the link addresses for all the objects? + +A: You really, *really* don't want to do this. Trust me on this one. + + +Q: How about an example of an object list? + +A: Here you go: + + objList = $10000 + bRam = $20000 +; + .68000 +objects: ; This is the label you will use to address this in 68K code + .objproc ; Engage the OP assembler + .org objList ; Tell the OP assembler where the list will execute +; + branch VC < 69, .stahp ; Branch to the STOP object if VC < 69 + branch VC > 241, .stahp ; Branch to the STOP object if VC > 241 + bitmap bRAM, 22, 70, 24, 24, 22, 4 + bitmap bRAM, 20+96+96, 70, 24, 24, 22, 4, 0, REFLECT + scbitmap tms, 20, 70, 1, 1, 8, 3.0, 3.0, 2.9999, 0, 0, TRANS + scbitmap tmsShadow, 23, 73, 1, 1, 8, 3.0, 3.0, 2.9999, 0, 3, TRANS + bitmap sbRelBM, 30, 108, 3, 3, 8, 0, 1, TRANS + bitmap txt1BM, 46, 132, 3, 3, 8, 0, 2, TRANS + bitmap txt2BM, 46, 148, 3, 3, 8, 0, 2, TRANS + bitmap txt3BM, 22, 164, 3, 3, 8, 0, 2, TRANS + jump .haha +.stahp: + stop +.haha: + jump .stahp +