::/ \::::::. :/___\:::::::. /| \::::::::. :| _/\:::::::::. :| _|\ \::::::::::. Mar 00-Aug 00 :::\_____\::::::::::. Issue 8 ::::::::::::::::::::::......................................................... A S S E M B L Y P R O G R A M M I N G J O U R N A L http://asmjournal.freeservers.com asmjournal@mailcity.com T A B L E O F C O N T E N T S ---------------------------------------------------------------------- Introduction...................................................mammon_ "Teaching Assembly Language Using HLA"....................Randall.Hyde "Processor Identification - Part II"..............Chris Dragan.&.Chili "The LCC Intrinsics Utility"...............................Jacob.Navia "Accessing COM Objects from Assembly"....................Ernest.Murphy "64-bit Integer/ASCII Conversion"............................X-Calibre Column: Win32 Assembly Programming "Win32 AppFatalExit Skeleton"................................Chili Column: The Unix World "System Calls in FreeBSD".........................G.Adam.Stanislav "Loadable Kernel Modules"..................................mammon_ Column: Gaming Corner "Win32 ASM Game Programming"...........................Chris.Hobbs Column: Assembly Language Snippets "SEH.INC"................................................X-Calibre "SEH.ASM"................................................X-Calibre Column: Issue Solution "BCD_Conv"...........................................Angel.Tsankov ---------------------------------------------------------------------- +++++++++++++++++++Issue Challenge++++++++++++++++++ Convert a two-digit BCD to hexadecimal ---------------------------------------------------------------------- ::/ \::::::. :/___\:::::::. /| \::::::::. :| _/\:::::::::. :| _|\ \::::::::::. :::\_____\:::::::::::..............................................INTRODUCTION by mammon_ I cannot begin to count the number of subtle and overt hints I have received that this issue is by far the most tardy APJ release to date. Quite a few projects have conspired to steal my time away, from Linux essays to disassembler coding to reverse engineering a hardware/software combo thrown together by a madman bent on carrying the technology to his grave. Enough to say, though, that the issue is finally ready for distribution. Not only that, but I actually have about four article left over --including Part II of the ASM Gaming series-- to include in APJ 9. The articles in this issue encompass a wide range of topics, from customizing the LCC compiler to programming games in asm. Randall Hyde, who I'm sure needs no introduction to assembly coders, has provided an excellent article discussing the teaching of assembly language, and how he developed HLA to assist. Chili has done a fair amount of work as well, working on everything from CPU identification and exception handling to preparing an online gaming article for ASCII publication. X-Calibre has provided two complete programming packages, one for exception handling and one for converting 64-bit integers; an introductory COM article which further demystifies COM has been provided by Ernest Murphy. The Unix camp is doubly represented this month, with an introduction to FreeBSD assembly language [using NASM, of course] and my linux article deferred from the previous issue. Capping everything off is a quick challenge and solution provided by Angel Tsankov. It has been suggested to me many times during the Time Of No Issues that I should acquire a staff for ensuring that the issues get out on time. I am open to suggestions in this area; anyone willing to volunteer their time on a regular basis is welcome to contact me. Ideally, the mag should have a staff that solicits articles [hint IRC hint], tests the code in each article, and edits the articles to enforce formatting [80 col, 3sp tab] and commenting standards. To date I've been doing the last one only, and as is readily apparent I put it off as long as possible. Another note, regarding mirrors. Translation of the APJ issues is perfectly acceptable and highly encouraged; all I request is an email giving the URL so I can link to it from the main page. I should point out that the individual articles, once removed from the context of the APJ issue, are the property of their individual authors, so contact them before 'repackaging'. Regarding formatting, I have also received a few requests to reformat APJ in HTML or another markup language to make reading and browsing easier. This I will not do, for it makes APJ less portable and causes problems copying code from the magazine to a source file. I have been working on syntax highlighting/tag files for vi and nedit; I will post these and any user-contributed translation files [e.g. APJ_to_HTML] on the main APJ website. All pleading and excuses aside, issue 8 is now put to bed, and issue 9 will be out faster than you can recite GNU's license agreement. Enjoy the mag... _m ::/ \::::::. :/___\:::::::. /| \::::::::. :| _/\:::::::::. :| _|\ \::::::::::. :::\_____\:::::::::::...........................................FEATURE.ARTICLE Teaching Assembly Language Using HLA by Randall Hyde I first began teaching assembly language programming at Cal Poly Pomona in the Winter Quarter of 1987. I quickly discovered that good pedagogical material was difficult to come by; even the textbooks available for the course left something to be desired. As a result, my students were learning very little assembly language in the ten weeks available to the course. After about two quarters, I decided to do something about the textbook problem, so I began writing a text I entitled "How to Program the IBM PC Using 8088 Assembly Language" (obviously, this was back in the days when schools still used PCs made by IBM and the main CPU you could always count on was the 8088). "How to Program..." became the epitome of a "work in progress." Each quarter I would get feedback from the students, update the text, and give it to Kinko's (and the UCR Printing and Reprographics Department) to run off copies for my students the very next quarter. The original "How to Program..." text provided a basic set of library routines to print strings, input characters and lines of text, and a few other basic functions. This allowed the students to quickly begin writing programs without having to learn about the INT instruction, DOS, or BIOS. However, I discovered that students were spending a significant time each quarter writing their own numeric conversion routines, string manipulation routines, etc. One student commented on "how much easier it was to program in 'C' than assembly language since all those conversions and string operations were built into the language." I replied that the real savings were due more to the 'C' standard library than the language itself and that a comparable library for assembly language programmers would make assembly language programming almost as easy as 'C' programming. At that moment a little light when on in my head and I sat down and wrote the first few routines of what ultimately became the "UCR Standard Library for 80x86 Assembly Language Programmers" (You can still get a copy of the UCR stdlib from webster at the URL given above). As I finished each group of routines in the standard library, I incorporated them into my courses. This reaped immediate benefits as students spent less time writing numeric conversion routines and spent more time learning assembly language. My students were getting into far more advanced topics than was possible before the advent of the UCR Stdlib. In the early 1990's, the 8088 CPU finally died off and IBM was no longer the major supplier of PCs. Not only was it time to change the title of my text, but I needed to update references to the 8088 (that were specific to that chip) and bring the text into the world of the 80386 and 80486 processors. DOS was still King and 16-bit code was still what everyone was writing, but issues of optimization and the like were a little outdated in the text. In addition to the changes reflecting the new Intel CPUs, I also incorporated the UCR Standard Library into the text since it dramatically improved the speed at which students progressed beyond the basic assembly programming skills. I entitled the new version of the text "The Art of Assembly Language Programming," an obvious knock-off of Knuth's series ("The Art of Computer Programming"). In early 1996 it became obvious to me that DOS was finally dying and I needed to modify "The Art of Assembly Language Programming" (AoA) to use Windows as the development platform. I wasn't interested in having students write Windows GUI applications in assembly language (the time spent teaching event-oriented programming would interfere with the teaching of basic machine organization and assembly language programming), but it was clear that the days of writing code that arbitrarily pokes around in memory and accesses I/O addresses directly (things that AoA taught) were nearly over. So I decided to get started on a new version of AoA that used Windows as the basic development environment with the emphasis on writing console applications. The UCR Standard Library was the single most important pedagogical tool I'd discovered that dramatically improved my students' progress. As I began work on a new version of AoA for Windows 3.1 my first task was to improve upon the UCR Standard Library to make it even easier to use, more flexible, more efficient, and more "high level." After six months of part time work I eventually gave up on the UCR Stdlib v2.0. The idea was right, unfortunately the tools at my disposal (specifically, MASM 6.11) weren't quite up to the task at hand. I was writing some really tricky macros, obviously exploiting code inside MASM that Microsoft's engineers had never run (i.e., I discovered lots of bugs). I would code in some workarounds to the defects only to have the macro package break at the next minor patch of MASM (e.g., from MASM 6.11a to MASM 6.11b). There was also a robustness issue. Although MASM's macro capabilities are quite powerful and it almost let me do everything I wanted, it was very easy to confuse the macro package and then MASM would generate some totally weird (but absolutely correct) diagnostic messages that correctly described what was going wrong in the macro but made absolutely no sense whatsoever at all to a beginning assembly language student who use using the macro to print some data to the console device. As it became clear that the UCR Stdlib v2.0 would never be robust enough for student use, I decide to take a different approach. About this time, I was talking with my Department Chair about the assembly language course. We were identifying some of the problems that students had learning assembly language. One problem, of course, was the paradigm shift - learning to solve problems using machine language rather than a high level language. The second problem we identified is that students get to apply very little of what they've learned from other courses to the assembly language class. A third problem was the primitive tools available to assembly language programmers. Energized by this discussion, I decided to see how I could solve these problems and improve the educational process. Problem one, the paradigm shift, had to be handled carefully. After all, the whole purpose of having students take an assembly language programming course in the first place is to acquaint them with the low-level operation of the machine. However, I felt it was certainly possible to redefine parts of assembly language so that would be more familiar to students. For example, one might test the carry flag after an addition to determine if an unsigned overflow has occurred using code like the following: add eax, 5 jnc NoOverflow << code to execute if overflow occurs >> NoOverflow: Although this code is fairly straight-forward, you would be surprised how many students cannot visualize this code on their own. On the other hand, if you feed them some pseudo code like: add eax, 5 if( the carry flag is set ) then << code to execute if overflow occurs >> endif those same students won't have any problems understanding this code. To take advantage of this difference in perspective, I decided to explore changing the definition of assembly language to allow the use of the "if condition then do something" paradigm rather than the "if a condition is false them skip over something" paradigm. Fundamentally, this does not change the material the student has to learn; it just presents it from a different point of view to which they're already accustomed. This certainly wasn't a gigantic leap away from assembly language as it existed in 1996. After all, MASM and other assemblers were already allowing statements like ".if" and ".endif" in the code. So I tried these statements out on a few of my students. What I discovered is that the students picked up the basic "high level" syntax very rapidly. Once they mastered the high level syntax, they were able to learn the low-level syntax (i.e., using conditional jumps) faster than ever before. What I discovered is something that Nicoderm CQ is pushing for their smoking cessation program: "learning assembly language in graduated steps (from high level to low level) is easier than going about it 'cold turkey.'" The second problem, students not being able to leverage their programming skills from other classes, is largely linked to the syntax of Intel x86 assembly language. Many skills students pick up, such as programming style, indentation, appropriate programming construct selection, etc., are useless in a typically assembly language class. Even skills like commenting and choosing good variable names are slightly different in assembly language programs. As a result, students spend considerable (unproductive) time learning the new "rules of the game" when writing assembly language programs. This directly equates to less progress over the ten week quarter. Ideally, students should be able to applying knowledge like program style, commenting style, algorithm organization, and control construct selection they learned in a C/C++ or Pascal course to their assembly language programs. If they could, they'd be "up and writing" in assembly language much faster than before. The third problem with teaching assembly language is the primitive state of the tools. While MASM provides a wonderful set of high level language control constructs, very little else about MASM supports this "brave new world" of assembly language I want to teach. For example, MASM's variable declarations leave a lot to be desired (the syntax is straight out of the 1960's). As I noted earlier, as powerful as MASM's macro facilities are, they weren't sufficient to develop a robust library package for my students. I briefly looked at TASM, but it's "ideal" mode fared little better than MASM. Likewise, while development environments for high level languages have been improving by leaps and bounds (e.g., Delphi and C++ Builder), assembly language programmers are still using the same crude command line tools popularized in the early 1970's. Codeview, which is practically useless under Windows, is the most advanced tool Microsoft provides specifically for assembly language programmers. Faced with these problems, I decided the first order of business was to create a new x86 assembly language and write a compiler for it. I decided to give this language the somewhat-less-than-original name of "the High Level Assembler," or HLA (IBM and Motorola both already have assemblers that use a variant of this name). It took three years, but the first version of HLA was ready for public consumption in September of 1999. I began using HLA in my CS 61 course (machine organization and assembly language programming) at UCR in the Fall Quarter, 1999. With no pedagogical material other than a roughly written reference guide to the language, I was expecting a complete disaster. It turns out that I was pleasantly surprised. Although the students did have major problems, the course went far more smoothly than I anticipated and we managed to cover about the same material I normally covered when using MASM. Although things were going far better than I expected, this is not to say that things were going great, or even as smoothly as I would have liked. The major problem, of course, was the lack of a textbook. The only material the students had to study from were their lecture notes. Clearly something needed to be done about this. Of course, the whole reason for spending three years writing HLA was to allow me to write a new version of AoA. So in November, 1999, I began work on the new edition of the text. By the start of the Winter Quarter in January, 2000, I had roughed together five chapters, about 50% of the material was brand new, the other 50% was cut, pasted, and updated from the older version of the text. During the quarter I rushed out two more chapters bringing the total to seven. The Winter Quarter went far more smoothly than the Fall Quarter. Student projects were much better and the progress of the class outstripped any assembly language course I'd taught prior to that point. Clearly the class was benefiting from the use of HLA. By the start of the Spring Quarter in April, 2000, I'd managed to make one proofreading pass over the first six chapters and I'd written the first draft of the eighth chapter. With a bit of luck, I will have the first draft of the text ready by the end of Summer, 2000. At that time I intend to "shop" the text around to a set of publishers so other schools can benefit from the work. Well, this has been a long-winded report of HLA's justification. You're probably wondering what HLA is and whether it is applicable to you (especially if you're a programmer rather than an educator). Fair enough, the rest of this article will discuss the HLA system and how you would use it. HLA is a technically a compiler, not an assembler. HLA v1.x converts an HLA source file into a MASM-compatible assembly language source file. This MASM file is then assembled and linked to produce a Win32 executable file. The HLA compiler automatically runs the assembler and linker, so these steps are transparent to the HLA user (other than the few extra seconds it takes to assemble and link the output file). This whole process takes only a few seconds (for example, compiling, assembling, and linking the 750-line "x2p.hla" program in the HLA examples directory only takes about two seconds on a 266 MHz Pentium II system with UW SCSI drives). I am planning to emit object code directly in version 2.0 of HLA. Until then, an HLA user will need Microsoft's MASM and linker. For those who would prefer to have HLA generate code for TASM, NASM, or some other assembler, the HLA compiler source code is available, have fun :-). HLA is a Win32 console application and it generates Win32 applications. By default, it generates console applications although it does not restrict you to writing console applications under Windows. There is absolutely no support for DOS applications. While it is possible to write Linux applications with only minor changes to HLA, the development process for Linux applications is convoluted and hardly worthwhile. HLA v2.0 will address portability across 32-bit x86 operating systems. For now, using HLA is practical only under Win32 OSes (Win 95, 98, NT, and 2000). When designing the HLA language, I chose a syntax that is very similar to common imperative high level languages like Pascal/Delphi, Ada, Modula-2, FORTRAN77, C/C++, and Java. That is not to say that HLA compiles Pascal programs, but rather, a Pascal programmer will note many similarities between Pascal and HLA (and ditto for the other languages). HLA stole many of the ideas for data declarations from the Algol based languages (Pascal, Modula-2, and Ada), it grabbed the ideas for many of its control structures from FORTRAN77, Ada, and C/C++/Java, and the structure of the HLA Standard Library is based on the C Standard Library. So regardless of which high level language you're most comfortable with in this set, you'll certainly recognize some elements of your favorite HLL in HLA. A carefully written HLA program will look almost exactly like a high level language program. Consider the following sample program: program SampleHLApgm; #include( "stdlib.hhf" ) const HelloWorld := "Hello World"; begin SampleHLApgm; stdout.put( "The classical 'Hello World' program: ", HelloWorld, nl ); end SampleHLApgm; This program does the obvious thing. Anyone with any high level language background can probably figure out everything except the purpose of "nl" (which is the newline string imported by the standard library). This certainly doesn't look like an assembly language program; there isn't even a real machine instruction in sight. Of course, this is a trivial example; nonetheless, I've managed to write reasonable HLA programs that were just over 1,000 lines of code that contained only one or two identifiable machine language instructions. If it's possible to do this, how can I get away with calling HLA an assembly language? The truth is, you can actually write a very similar looking program with MASM. Here's an example I trot out for unbelievers. This code is compilable with MASM (assuming you include the UCR Standard Library v2.0 and some additional code I've cut out for brevity: var enum colors, colors c1, c2 endvar Main proc mov ax, dseg mov ds, ax mov es, ax MemInit InitExcept EnableExcept finit try cout "Enter two colors:" cin c1, c2 cout "You entered ",c1," and ",c2,nl .if c1 == red cout "c1 was red" .endif except $Conversion cout "Conversion error occured",nl except $Overflow cout "Overflow error occured",nl endtry CleanUpEx ExitPgm ;DOS macro to quit program. Main endp As you can see, the only identifiable machine instructions here are the ones that initialize the segment registers at the beginning of the program (which is unnecessary in a Win32 environment). So let me blunt criticism from "die-hard" assembly fans right at the start: HLA doesn't open up all kinds of new programming paradigms that weren't possible before. With some really clever macros (e.g., enum, cout, and cin in the MASM code), it is quite possible to do some really amazing things. If you're wondering why you should bother with HLA if MASM is so wonderful, don't forget my comments about the robustness of these macros. Both HLA and MASM (with the UCR Standard Library v2.0) work great as long as you write perfect code and don't make any mistakes. However, if you do make mistakes, the MASM macro scheme gets ugly real quick. The "die-hard" assembly fan will probably make the observation that they would never write code like the MASM code I've presented above; they would write traditional assembly code. They want to write traditional code. They don't want this high level syntax forced upon them. Well, HLA doesn't force you to use high level control structures rather than machine instructions. You can always write the low level code if you prefer it that way. Here is the original HLA program rewritten to use familiar machine instructions: program SampleHLApgm2; #include( "stdlib.hhf" ) data dword 37, 37; TcHWpStr: dword; byte "The classical 'Hello World' program: ",0,0,0; dword 11, 11; HWstr: dword; byte "Hello World",0; begin SampleHLApgm2; lea( eax, TcHWpStr ); push( eax ); call stdout.puts; lea( eax, HWstr ); push( eax ); call stdout.puts; call stdout.newln; end SampleHLApgm2; The stdout.puts and stdout.newln procedures come from the HLA Standard Library. I will leave it up to the interested reader to translate these into Win API Write calls if this code isn't sufficiently low level to satisfy. Note that HLA strings are not simple zero terminated strings like C/C++. This explains the extra zeros and dword values in the DATA section (the dword values hold the string lengths; I offer these without further explanation, see the HLA documentation for more details on HLA's string format). One thing you've probably noticed from this second example is that HLA uses a functional notation for assembly language statements. That is, the instruction mnemonics look like function calls in a high level language and the operands look like parameters to those functions. The neat thing about this notation is that it easily allows the use of "instruction composition." Instruction composition, like functional composition, means that you get to use one instruction as the operand of another. For example, an instruction like "mov( mov( 0, eax ), ebx );" is perfectly legal in HLA. The HLA compiler will compile the innermost instruction first and then substitute the destination operand of the innermost instruction for the operand position occupied by the instruction. HLA's MOV instruction takes the generic form "MOV( source, destination );" so the former instruction translates to the following two instruction sequence: mov( 0, eax ); // intel syntax: mov eax, 0 mov( eax, ebx ); // intel syntax: mov ebx, eax By and of itself, instruction composition is somewhat interesting, but programmers striving to write readable code need to exercise caution when using instruction composition. It is real easy to write some really unreadable code if you abuse instruction composition. E.g., consider: mov( add( mov( 0, eax ), sub( ebx, ecx)), edx ), mov( i, esi )); Egads! What does this mess do? Some might consider the inclusion of instruction composition in HLA to be a fault of the language if it allows you to write such unreadable code. However, I've never felt it was the language syntax's job to enforce good programming style. If there's really a reason for writing such messy code, the compiler shouldn't prevent it. Although you can produce some truly unreadable messes with instruction composition, if you use it properly it can enhance the readability of your programs. For example, HLA lets you associate an arbitrary string with a procedure that HLA will substitute for that procedure name when the procedure call appears as an operand of another instruction. Most functions that return a value in a register specify that register name as their "returns" string (the string HLA substitutes for the procedure call). For example, the "str.eq( str1, str2)" function compares the two string operands and returns true or false in AL depending on the result of the comparison. This allows you to write code like the following: if( str.eq( str1, "Hello" )) then stdout.put( "str1 = 'Hello'" nl ); endif; HLA directly translates the IF statement into the following sequence: str.eq( str1, "Hello" ); if( al ) then stdout.put( "str1= 'Hello'" nl ); endif; (If a register name appears where a boolean expression is expected, as AL does in the IF statement above, HLA emits a TEST instruction to see if the register contains a non-zero value.) Arguably, the former version is a little more readable than the latter version. Instruction composition, when you use it in this fashion, lets you write code that "looks" a little more high level without the compiler having to generate lots of extra code (as it would if HLA supported a generalized arithmetic expression parser). Like MASM, HLA supports a wide variety of high level control structures. HLA's set is both higher level and lower level at the same time. There are two reasons HLA's control structures aren't always as powerful as MASM's. First, with the sole exception of object method invocations, I made a rule that HLA's high level control structures would not modify any general purpose registers behind the programmer's back. MASM, for example, may modify the value in EAX for certain boolean expressions it must compute. Second, remember that the primary goal of HLA is to teach assembly language; yes, it's supposed to ease the learning curve, but still the goal is to teach assembly language. It is possible to get carried away with the high level language features and then wind up with an "assembler" that lets students write their assembly language programs in a high level language. In my opinion, MASM went too far with what it allows for boolean expressions. HLA, for example, doesn't allow the use of the conjunctive and disjunctive operators ( "&&" and "||") in boolean expressions. I expect my students to generate the appropriate sequence of low level instructions themselves. In general, most HLA boolean expressions compile into two instructions: a CMP and a conditional jump. I didn't want to go any farther than this because that would allow the students to avoid learning how to write this code for themselves. Although I designed HLA as a tool to teach assembly language programming, this is also a tool that I intend to use so I included lots of goodies for advanced assembly language programmers. For example, HLA's macro facilities are more powerful than I've seen in any programming language based macro processor. One unique feature of HLA's macro preprocessor is the ability to create "context free" control structures using macros. For example, suppose that you decide that you need a new type of looping construct that HLA doesn't provide; let's say, a loop that will repeat once for each character in a string supplied as a parameter to the loop. Let's call this loop "OnceForEachChar" and decide on the following syntax: OnceForEachChar( SomeString ) << Loop Body >> endOnceForEachChar; On each iteration of this loop, the AL register will contain the corresponding character from the string specified as the OnceForEachChar operand. You can easily implement this loop using the following HLA macro: macro OnceForEachChar( SomeString ): TopOfLoop, LoopExit; pushd( -1 ); // index into string. TopOfLoop: inc( (type dword [esp] )); // Bump up index into string. #if( @IsConst( SomeString )) lea( eax, SomeString ); // Load address of string constant into EAX. #else mov( SomeString, eax ); // Get ptr to string. #endif add( [esp], eax ); // Point at next available character mov( [eax], al ); // Get the next available character cmp( al, 0 ); // See if we're at the end of the string je LoopExit; terminator endOnceForEachChar; jmp TopOfLoop; // Return to the top of the loop and repeat. LoopExit: add( 4, esp ); // Remove index into string from stack. endmacro; Anyone familiar with MASM's macro processor should be able to figure out most of this code. Note that the symbols "TopOfLoop" and "LoopExit" are local symbols to this macro. Hence, if you repeat this macro several times in the code, HLA will emit different actual labels for these symbols to the MASM output file. The "@IsConst" is an HLA compile-time function that returns true if its operand is a constant. Obtaining the address for a constant is fundamentally different than obtaining the address of a string variable (since HLA string variables are actually pointers to the string data). The most interesting feature of this macro definition is the "terminator" line. This actually defines a second macro that is active only after HLA encounters the "OnceForEachChar" macro and control returns to the first statement after the OnceForEachChar invocation. Invocation of "context free" macros always occur in pairs; that is, for every "OnceForEachChar" invocation there must be a matching "endOnceForEachChar" invocation. The following program demonstrates this macro in use, it also demonstrates that you can nest this newly created control structure in your program: program SampleHLApgm3; #include( "stdlib.hhf" ) macro OnceForEachChar( SomeString ): TopOfLoop, LoopExit; pushd( -1 ); // index into string. TopOfLoop: inc( (type dword [esp] )); #if( @IsConst( SomeString )) lea( eax, SomeString ); #else mov( SomeString, eax ); #endif add( [esp], eax ); mov( [eax], al ); cmp( al, 0 ); je LoopExit; terminator endOnceForEachChar; jmp TopOfLoop; LoopExit: add( 4, esp ); endmacro; static strVar: string := ":" nl; begin SampleHLApgm3; OnceForEachChar( "Hello" ) stdout.putc( al ); OnceForEachChar( strVar ) stdout.putc( al ); endOnceForEachChar; endOnceForEachChar; end SampleHLApgm3; This program produces the output: H: e: l: l: o: Here's the MASM code the compiler emits for the sequence above (the "strings" segment was moved for clarity): strings segment page public 'data' align 4 ?635_len dword 5 dword 5 ?635_str byte "Hello",0,0,0 strings ends pushd -1 ?634__0278_: inc dword ptr [esp+0] ;(type dword [esp]) lea eax, ?635_str add eax, [esp+0] ;[esp] mov al, [eax+0] ;[eax] cmp al, 0 je ?636__0279_ push eax call stdio_putc ;putc pushd -1 ?639__027d_: inc dword ptr [esp+0] ;(type dword [esp]) mov eax, dword ptr ?630_strVar[0] ;strVar add eax, [esp+0] ;[esp] mov al, [eax+0] ;[eax] cmp al, 0 je ?640__027e_ push eax call stdio_putc ;putc jmp ?639__027d_ ?640__027e_: add esp, 4 jmp ?634__0278_ ?636__0279_: add esp, 4 In addition to the "terminator" clause, HLA macros also support a "keyword" clause that let you bury reserved words within a context-free language construct. For example, the HLA language does not provide a SWITCH/CASE statement. This omission was intentional. Rather than build the SWITCH/CASE statement into the HLA language, I implemented the SWITCH .. CASE .. DEFAULT .. ENDCASE statement using HLA's macro facilities (as a demonstration of HLA's power). An HLA SWITCH statement takes the following form: switch( reg32 ) case( constantList1 ) << statements >> case (constantList2 ) << statements >> . . . default // This is optional << statements >> endswitch; The switch macro implements the "switch" and "endswitch" reserved words using the macro and terminator clauses in the macro declaration. It implements the "case" and "default" reserved words using the HLA "keyword" clause in a macro definition. The "keyword" clause is similar to the "terminator" clause except it doesn't force the end of the macro expansion in the invoking code. The actual code for the HLA SWITCH statement is a little too complex to present here, so I will extend the example of the OnceForEachChar macro to demonstrate how you code use the "keyword" clause in a macro. Let's suppose you wanted to add a "_break" clause to the "OnceForEachChar" loop ( I'm using "_break" with an underscore because "break" is an HLA reserved word). You could easily modify the "OnceForEachChar" macro to achieve this by using the following code: macro OnceForEachChar( SomeString ): TopOfLoop, LoopExit; pushd( -1 ); // index into string. TopOfLoop: inc( (type dword [esp] )); #if( @IsConst( SomeString )) lea( eax, SomeString ); #else mov( SomeString, eax ); #endif add( [esp], eax ); mov( [eax], al ); cmp( al, 0 ); je LoopExit; keyword _break; jmp LoopExit; terminator endOnceForEachChar; jmp TopOfLoop; LoopExit: add( 4, esp ); endmacro; The "keyword" clause defines a macro ("_break") that is active between the "OnceForEachChar" and "endOnceForEachChar" invocations. This macro simply expands to a jmp instruction that exits the loop. Note that if you have nested "OnceForEachChar" loops and you "_break" out of the innermost loop, the code only jumps out of the innermost loop, exactly as you would expect. HLA's macro facilities are part of a larger feature I refer to as the "HLA Compile-Time Language." HLA actually contains a built-in interpreter than executes while it is compiling your program. The compile-time language provides conditional compilation ( the #IF..#ELSE..#ENDIF statements in the previous example), interpreted procedure calls (macros), looping constructs (#WHILE..#ENDWHILE), a very powerful constant expression evaluator, compile-time I/O facilities (#PRINT, #ERROR, #INCLUDE, and #TEXT..#ENDTEXT), and dozens of built-in compile time functions (like the @IsConst function above). The HLA built-in string functions (not to be confused with the HLA Standard Library's string functions) are actually powerful enough to let you write a compiler for a high level language completely within HLA. I mentioned earlier that it is possible to write an expression compiler within HLA; I was serious. The HLA compile-time language will let you write a sophisticated recursive descent parser for arithmetic expressions (and other context-free language constructs, for that matter). HLA is a great tool for creating low-level Domain Specific Embedded Languages (DSELs). DSELs are mini-languages that you create on a project by project basis to help reduce development time. HLA's compile time language lets you create some very high level constructs. For example, HLA implements a very powerful string pattern matching language in the "patterns" module found in the HLA Standard Library. This module lets you write pattern matching programs that use techniques found in language like SNOBOL4 and Icon. As a final example, consider the following HLA program that translate RPN (reverse polish notation) expressions into their equivalent assembly language (HLA) statements and displays the results to the standard output: // This program translates user RPN input into an // equivalent sequence of assembly language instrs (HLA fmt). program RPNtoASM; #include( "stdlib.hhf" ); static s: string; operand: string; StartOperand: dword; macro mark; mov( esi, StartOperand ); endmacro; macro delete; mov( StartOperand, eax ); sub( eax, esi ); inc( esi ); sub( s, eax ); str.delete( s, eax, esi ); endmacro; procedure length( s:string ); returns( "eax" ); nodisplay; begin length; push( ebx ); mov( s, ebx ); mov( (type str.strRec [ebx]).length, eax ); pop( ebx ); end length; begin RPNtoASM; stdout.put( "-- RPN to assembly --" nl ); forever stdout.put( nl nl "Enter RPN sequence (empty line to quit): " ); stdin.a_gets(); mov( eax, s ); breakif( length( s ) = 0 ); while( length( s ) <> 0 ) do pat.match( s ); // Match identifiers and numeric constants mark; pat.zeroOrMoreWS(); pat.oneOrMoreCset( {'a'..'z', 'A'..'Z', '0'..'9', '_'} ); pat.a_extract( operand ); stdout.put( " pushd( ", operand, " );" nl ); strfree( operand ); delete; pat.alternate; // Handle the "+" operator. mark; pat.zeroOrMoreWS(); pat.oneChar( '+' ); stdout.put ( " pop( eax );" nl " add( eax, [esp] );" nl ); delete; pat.alternate; // Handle the '-' operator. mark; pat.zeroOrMoreWS(); pat.oneChar( '-' ); stdout.put ( " pop( eax );" nl " pop( ebx );" nl " sub( eax, ebx );" nl " push( ebx );" nl ); delete; pat.alternate; // Handle the '*' operator. mark; pat.zeroOrMoreWS(); pat.oneChar( '*' ); stdout.put ( " pop( eax );" nl " imul( eax, [esp] );" nl ); delete; pat.alternate; // handle the '/' operator. mark; pat.zeroOrMoreWS(); pat.oneChar( '/' ); stdout.put ( " pop( ebx );" nl " pop( eax );" nl " cdq(); " nl " idiv( ebx, edx:eax );" nl " push( ebx );" nl ); delete; pat.if_failure // If none of the above, it must be an error. stdout.put( nl "Illegal RPN Expression" nl ); mov( s, ebx ); mov( 0, (type str.strRec [ebx]).length ); pat.endmatch; endwhile; endfor; end RPNtoASM; Consider for a moment the code that matches an identifier or an integer constant: mark; pat.zeroOrMoreWS(); pat.oneOrMoreCset( {'a'..'z', 'A'..'Z', '0'..'9', '_'} ); pat.a_extract( operand ); stdout.put( " pushd( ", operand, " );" nl ); strfree( operand ); delete; The "mark;" invocation saves a pointer into the "s" string where the current identifier starts. The pat.ZeroOrMoreWS pattern matching function skips over zero or more whitespace characters. The pat.OneOrMoreCset pattern match function matches one or more alphanumeric and underscore characters (a crude approximation for identifiers and integer constants). The pat.a_extract function makes a copy of the string between the "mark" and the "a_extract" calls (this corresponds to the whitespace and identifier/constant). The stdout.put statement emits the HLA machine instruction that will push this operand on to the x86 stack for later computations. The remaining statements clean up allocated string storage space and delete the matched string from "s". Although the "pat.xxxxx" statements look like simple function calls, there's actually a whole lot more going on here. HLA's pattern matching facilities, like SNOBOL4 and Icon, support success, failure, and backtracking. For example, if the pat.oneOrMoreChar function fails to match at least one character from the set, control does not flow down to the pat.a_extract function. Instead, control flows to the next "pat.alternate" or "pat.if_failure" clause. Some calls to HLA pattern matching routines may even cause the program to back up in the code and reexecute previously called functions in an attempt to match a difficult pattern (i.e., the backtracking component). This article is not the place to get into the theory of pattern matching; however, these few examples should be sufficient to show you that something really special is going on here. And all these facilities were developed using the HLA compile-time language. This should give you a small indication of what is possible when using the HLA compile time language facilities. The HLA language is far too rich to describe in this short article (the *very* rough documentation for the language is nearly 300 pages long). For more information, check out the on-line documentation for HLA at http://webster.cs.ucr.edu. Someday, you'll also be able to learn about HLA via "The Art of Assembly Language Programming, HLA/Windows version." I will keep interested individuals updated on the progress of AoA at the Webster web site. HLA is totally free. It is public domain software and there are no restrictions on its use, the use of the HLA standard library, or the HLA compiler source code. Do whatever you want with it and have a lot of fun! rhyde@genovation.com http://webster.cs.ucr.edu http://www.cs.ucr.edu/docs/webster/ ::/ \::::::. :/___\:::::::. /| \::::::::. :| _/\:::::::::. :| _|\ \::::::::::. :::\_____\:::::::::::...........................................FEATURE.ARTICLE Processor Identification - Part II by Chris Dragan & Chili In the first part of this article I'll explain a lot of different ways to check for older processors by exploiting bugs, undocumented features, etc. I'll also show how to write an invalid-opcode exception handler, calculate the size of the prefetch queue and some other things. Finally, in the last part Chris shows how to determine the processor clockrate with the RDTSC instruction. Chris didn't have much free time at the moment and so couldn't contribute more, therefore I had to put this article together pretty much myself, and I hope the quality didn't go down very much -- since Chris' texts are definitely better than mine. AAD (ASCII Adjust before Division) Instruction ---------------------------------------------- This instruction allows us to distinguish between at least NEC's V-series and Intel processors. AAD, usually in preparation for a division using DIV or IDIV, works like this: AL = AH * 10 + AL AH = 0 Converting the unpacked two-digit BCD number in AX into binary. Thus being "0d5h, 0ah" the normal opcode. The difference is that while Intel's chips allow one to replace the multiplicand with any number (and by so building your own AAD instruction for various number systems), NEC always encodes it as 10 by default. So by replacing the second byte with a different number, we can then check if the operand is actually used, and if not, assume it's a NEC. mov ax, 0f0fh db 0d5h, 10h ; opcode for AAD 16 cmp al, 0ffh ; check if multiplicand was 10 or not jz _is_Intel jnz _is_NEC This should be used as another way (in addition to the one presented in the first article on this subject) to distinguish the NEC V20/V30 series from the Intel 8086/88. PUSHA Instruction ----------------- Here is another good way to differentiate NECs from Intel's 8086/88. Since V20 and V30 execute all the 80186 instructions and knowing that PUSHA executed on the 8086/88 as "JMP $+2", one can for example, after executing it, set the carry flag and then see if it was really set. clc ; ensure that CF is clear pusha ; executed on 8086/88 as JMP $+2 stc jc _is_NEC_or_186plus jnc _is_808x . . . _is_NEC_or_186plus: popa ; clean up Of course the carry flag must not already be set before performing this test. POP CS Trick ------------ I'll just show one last way of accomplishing the same. The trick is that, on a 8086/88 (non-CMOS versions, at least), the opcode "0fh" will perform a POP CS, on a 186/88 is an invalid opcode, generating an INT6 exception, while NECs and 286+ use that encoding as a prefix byte, to indicate new instructions. So, to tell NEC's V20/V30 (also V40/V50, I think) and 8086/88 apart, and knowing that with the byte string "0fh, 14h, 0c3h", the CPU will perform the following: 8086/88 V20/V30 ------- ------- pop cs set1 bl, cl adc al, 0C3h It is then easy to write a piece of code that will distinguish between them: xor al, al ; BTW: clears CF push cs db 0fh, 14h, 0c3h ; intruction(s) -- see above cmp al, 0c3h ; check if ADC was executed je _is_808x jne _is_NEC_V20plus . . . _is_NEC_V20plus: pop ax ; clean up (no POP CS available) Note that, again, the carry flag must be cleared before execution of this test. Also, just a reminder that this is to be used when you know that the processor is not a 186 or above but an older one. Word Write ---------- On the 8086/88 (+ V20/V30), when a word write is performed at offset 0ffffh in a segment, one byte will be written at that offset and the other at offset 0, while an 80186 family processor will write one byte at offset 0ffffh, and the other, one byte beyond the end of the segment (offset 10000h). So all we have to do is test if it wraps around or not: mov ax, ds:[0ffffh] ; save original bytes mov word ptr ds:[0ffffh], 0aaaah cmp byte ptr ds:[0], 0aah ; did 2nd byte wrap around? mov ds:[0ffffh], ax ; restore original bytes je _is_808x jne _is_8018x Again, note that this should only be used for the specified processors. Multi-Prefix Intructions ------------------------ The standard 8086/88 processors have a bug such that they loose multiple prefixes if an interrupt occurs, while CMOS versions do not, since this bug was fixed in the 80C86/C88 processors (NEC V20/V30 processors also do not have this bug -- allowing the following code to also be applicable to them). If we execute a string operation with a repeat prefix and also a segment override for long enough to be interrupted, then, if we are on a 8086/88 the REP prefix will be lost when the instruction is interrupted, since on return, only the last prefix will be retained. If instead, we are on a low-power consumption CMOS version, the code will successfully complete. mov cx, 0ffffh sti rep lods byte ptr es:[si] ; sure to be interrupted cli jcxz _not_standard_808x ; check if REP was completed . . . Just in case you want to use a piece of code like this without having to worry about that bug, here's how to get it work correctly every time (with interrupts enabled -- this time with MOVS): do_REP: rep movs byte ptr es:[di], es:[si] ; may be interrupted! jcxz carry_on ; if not, carry on, loop do_REP ; else, complete REP carry_on: Invalid-Opcode Exception Handler (INT6) --------------------------------------- >From the 80186 and upwards, all processors allow one to implement an invalid-opcode exception handler, which gives us a great way of telling the families of CPUs apart. All one does is, hook the INT6 interrupt vector with our own handler and see if some specific instructions trigger an INT6 or not. With our handler we trap those exceptions and then toggle a little flag, that show us the processor doesn't support that instruction. In the code below I hooked the INT6 vector by changing the IVT (Interrupt Vector Table) directly, but one can also use DOS services for that, test which processor we're running on and after that restore things back to what they were before (except registers, place some push/pop code yourself according to your needs -- by the way, Robert Collins is a god!). Anyway, the code is pretty much self-explanatory: ; Hook INT6 -- set up our own handler push 0 ; point to IVT (0000:0000) - (1 pop es ; byte saved thanks to Chris!) cli lds ax, es:[6*4] ; get original handler vector mov es:[6*4], offset INT6_handler ; then, replace it with mov es:[6*4+2], cs ; our own handler sti ; Test if processor is at least a 80186 -- Executes "SHL DX, 10"? mov cx, 1 ; set up invalid-opcode flag shl dx, 0ah jcxz unknown_CPU ; Test if processor is at least a 80286 -- Executes "SMSW DX"? smsw dx jcxz _is_80186 ; Test if processor is at least a 80386 -- Executes "MOV EDX, EDX"? mov edx, edx jcxz _is_80286 ; Test if processor is at least a 80486 -- Executes "XADD DL, DL"? xadd dl, dl jcxz _is_80386 . . . ; Restore original INT6 handler address -- for all processors type! cli mov es:[6*4], ax ; restore original INT6 offset mov es:[6*4+2], ds ; restore original INT6 segment sti . . . ; Our own INT6 handler INT6_handler: xor cx, cx ; toggle invalid-opcode flag push bp mov bp, sp add word ptr ss:[bp+2], 3 ; adjust the return address to ; after the invalid opcode (3 ; bytes for all) pop bp iret Note, that for this code: 1) should only be used if you know the processor is at least a 80186, 2) if you fiddle with the contents of AX, ES and DS and change them before restoring the original INT6 handler don't forget to first save and then restore them!, 3) of course the code in the INT6_handler should only be executed by means of an INT6! Maybe a very small extra explanation is required regarding the INT6_handler. We need to adjust the return address, since when an invalid opcode exception is issued the saved contents of CS and EIP (which are pushed onto the stack) point to the instruction that generated the exception, instead of the next one (as usually happens for other interrupts). Instruction Prefetch Queue -------------------------- 16-bit (ie. 8086s, 80186s, V30s) processors have a prefetch queue 6 bytes in size and replenish the instruction queue after having at least two bytes empty in the queue, while their 8-bit bus versions (ie. 8088s, 80188, V20s) only have a 4 byte prefetch queue and initiate the prefetch cycle when there is at least one empty byte in it. So, knowing this about their Bus Interface Unit design, it isn't difficult to write some code to distinguish between the two categories. We'll make a routine that uses self-modifying code to change the opcode at the fifth byte and then see if it was executed or not. xor cx, cx cli ; prevent against queue being emptied lea di, patch mov al, 90h ; load NOP opcode stosb ; patch fifth byte to a NOP nop nop nop nop patch: inc cx ; did the INC execute? sti jcxz _is_8bit I believe there is enough time for the prefetch queue to fill, though I have no chance to confirm it! Just in case you want to be on the safe side, here's a routine that will most certainly work: xor dx, dx cli ; prevent against queue being emptied lea di, patch+2 mov al, 90h ; load NOP opcode mov cx, 3 std rep stosb ; patch fifth byte to a NOP nop nop nop nop patch: inc dx ; did the INC execute? nop nop sti test dx, dx jz _is_8bit Again, I must stress that this code should only be used for the specified processors, since it will without a doubt fail on others. Do It The Optimized Way! ------------------------ Here is our size-optimized way of determining the processor type. It's an algorithm that uses Intel's guidelines and tests between pre-80286, 80286, 80386, 80486 without CPUID and 80486+ with CPUID support. Chris is using a similar routine in his CPU identification utility. ; Detection of pre-80286/80286/386+ processors mov ax, 7202h ; set bits 12-14 and clear bit 15 push ax popf pushf pop ax test ah, 0f0h js _is_pre286 ; bit 15 of FLAGS is set on pre-286 jz _is_80286 ; bits 12..15 of FLAGS are clear on 286 ; processor in real mode (no V86 mode ; on 286) ; ; Detection of 80386/80486(w/out CPUID)/80486+(CPUID compliant) pushfd pop eax mov edx, eax xor eax, 00240000h ; flip bits 18 (AC) and 21 (ID) push eax popfd pushfd pop eax xor eax, edx ; check if both bits didn't toggle jz _is_80386 shr eax, 19 ; check if only bit 18 toggled jz _is_80486_without_CPUID And so, we got the whole code down to a measly 46 bytes! CR0 Register - Bit 4 -------------------- The 80386 DX may be differentiated from the other models by trying to clear bit 4 (ET) in the CR0 register. It can be toggled on the 80386 DX, while it is hardwired to 1 on any of the other family models. So this gives us a good way to differentiate them, by trying to clear that bit and then see if it got forced to set or not. ; Test CR0 register -- bit 4 (ET) mov eax, cr0 mov edx, eax ; save original CR0 and al, 11101111b ; clear bit 4 mov cr0, eax mov eax, cr0 mov cr0, edx ; restore original CR0 test al, 00010000b ; check if bit 4 was forced high jz _is_a_80386DX_model jnz _is_not_a_80386DX_and_therefore_is_some_other_model Note that I'm not sure if this can safelly/trustfully be done under protected mode! Clockrate --------- Before Pentium, it was difficult to determine the processor clockrate. It typically based on sophisticated timing loops, which were often unreliable. With Pentium, Intel introduced RDTSC instruction, which returned number of clocks since the processor start. The following code illustrates how to use it. ; Determine RDTSC support (assuming that CPUID is supported) mov eax, 1 cpuid test edx, 10h ; bit 4 is set when RDTSC is supported jz _no_rdtsc ; Disable all interrupts but timer IRQ0 in al, 21h mov ah, al in al, 0A1h push ax ; Save previous values mov al, 0FEh out 21h, al mov al, 0FFh out 0A1h, al ; Assuming that timer runs at 55ms periods, get the clockrate hlt ; Wait for timer rdtsc ; Read TSC mov ebx, eax ; Save lo mov ecx, edx ; Save hi hlt ; Wait for timer rdtsc ; Read TSC sub eax, ebx ; Difference lo sbb edx, ecx ; Difference hi ; Calculate clockrate in MHz mov ecx, 54925 div ecx mov [Clockrate], eax ; Restore interrupt states pop ax out 0A1h, al mov al, ah out 21h, al The above code can be run in real mode, V86 mode or protected mode in ring0. In V86 mode it will hang Pentium and Pentium MMX processors, but on other processors it will work OK. In this code, clockrate is determined as: (T2-T1)*PIT/(D*M), where T1 and T2 are numbers of clocks returned by RDTSC, PIT is the value divided in the Programmable Interval Timer (equals 0x1234DD), D is the value by which PIT is divided (0x10000) and M is 1000000 (we want it in MHz). Is This The End? ---------------- I think this is the end as old CPUs are concerned, since a lot of techniques have already been covered here (though there are some more), but not for other processors, like AMD and IBM and whatever else Chris and I think up before the next article. Take the time to visit Chris' web page, where you can find the source for his CPU identification utility (for Netwide Assembler). His place is at: http://ams.ampr.org/cdragan/ Also, here are some other sources of information that you might want to take a look at (available somewhere on the net -- since I don't remember where I got them from): WHATCHIP.ASM (Christy Gemmell) 86BUGS.LST (Harald Feldmann/Hamarsoft) [distributed with Ralf Brown's Interrupt list] OPCODES.LST (Potemkin's Hackers Group) [distributed with Ralf Brown's Interrupt list] cpu.asm (Robert Mashlan) WHATCPU.ASM (Dave M. Walker) COMPTEST 2.60 (Norbert Juffa) Ralf Brown's Interrupt List: http://www.cs.cmu.edu/~ralf/files.html This, in addition to the ones already referenced in the first article of this series. ::/ \::::::. :/___\:::::::. /| \::::::::. :| _/\:::::::::. :| _|\ \::::::::::. :::\_____\:::::::::::...........................................FEATURE.ARTICLE The LCC Intrinsics Utility Jacob Navia Lcc-win32 is a free C compiler system. It features an IDE, a resource compiler, a linker, librarian, a windowed debugger, and other goodies. Here, I would like to describe a special feature of lcc-win32 that will be surely appreciated by the colleagues that use assembly. Lcc-win32 understands special macro definitions called intrinsics.This constructs will be seen as normal function calls by the front end of the compiler, but will be inline expanded by the back-end. You can add your own intrinsic macros to the system, allowing you to use the power and speed of assembly language within the context of a more powerful and safer high level language. I will present here two examples, to give you an idea of how this can look like. You will need the source code of lcc-win32, that can be obtained at the home page: http://ps.qss.cz/lcc or ftp://ftp.cs.virginia.edu/pub/lcc-win32 Inlining the strlen function ---------------------------- Lets assume the strlen function of the C library is just to slow for you. Instead of generating: pushl Arg call _strlen addl $4,%esp you would like to generate inline the following code: ; Inlined strlen. The input argument is in ECX and points to the ; character string orl $-1,%eax loop: inc %eax cmpb $0,(%ecx,%eax) jnz loop This function then, should be inlined by the compiler. The C interface would be: _strlen(str); The prototype must be: extern _stdcall _strlen(char *); The compiler recognizes intrinsic macros because they have an underscore as the first character of their names, they are declared _stdcall, and they appear in the intrinsics table. Functions that begin with an underscore are few, and this avoids looking up the intrinsics table for each function call, what would slow down compilation speed. You take then the file intrin.c, in the sources of lcc-win32 and modify the intrinsics table. Its declaration is in the middle of the file, and looks like this: static INTRINSICS intrinsicTable[] = { {"_fsincos",2, 0, fsincos, NULL }, {"_bswap", 1, 0, bswap, bswapArgs }, ... many declarations omitted ... {"_reduceLtb",3, 0, redCmpLtb, paddArgs }, {"_mmxDotProduct",3,0, mmxDotProd, paddArgs }, {"_emms",0, 0, emms, NULL }, {NULL, 0, 0, 0, 0 } }; You add before the last line, the following line: {"_strlen",1, 0, strlenGen, strlenArgs }, telling the system that you want an intrinsic called _strlen, that takes one argument, whose code will be generated by the function strlenGen(), and the arguments assigned to their respective registers in the function strlenArgs(). This functions should assign the registers in which you want the arguments to the inline macro, and generate the code for the body of the macro. Basically, this macros are seen as special calls by the compiler, that instead of generating a push instruction, will call your function, that should set the right fields in each node passed to it, to make later the code generator generate a move to the registers specified. Note that all intrinsics should start with an underscore to avoid conflicting with user space names. When a call to this function is detected by the compiler, you will first be called when pushing the arguments at each call site. Here is the function strlenArgs() then: static Symbol strlenArgs(Node p) { Symbol r=NULL; //The global ArgumentsIndex is zero before each call. The compiler //takes care of that. switch (ArgumentsIndex) { case 0: // First argument pushed, from right to left! if (p->x.nestedCall == 0) { Symbol w; r = SetRegister(p,intreg[ECX]); } break; } // We have seen another argument ArgumentsIndex++; // Assign the register to this expression. if (p->x.nestedCall == 0 && r) p->syms[2] = r; // Should never be more than one arguments if (ArgumentsIndex == 1) ArgumentsIndex = 0; return r; } You see that in several places we have the test: if (p->x.nestedCall == 0) This means that we should check if we have a nested call sequence within the arguments, i.e. the following C expression: strlen( SomeFunction() ); True, in the case of strlen this doesnt change anything important, the result of the function will be in EAX anyway. But suppose you defined a macro that takes two arguments, say, some special form of addition sadd(a,b). In this case we would assign the second argument (from left to right) to ECX, and the first to EAX. Consider then the case of: sadd( SomeFunction(),5); If we would just assign 5 to ECX, then the call to SomeFunction(), would destroy the contents of ECX during the call! This means that when the compiler detects a call within argument passing, all arguments WILL BE in the stack, and our code generating function should take care of popping them into the right registers before proceeding. In the case of strlen this can really hardly happen, but its important to see how this would work in the general case. Note too that the argument function should increase the global argument counter for each argument, and reset it to zero when its done. Again, this is not necessary for strlen, but for macros that take more arguments this should be done imperatively. The SetRegister function takes care of the details of assigning a register. Here is its short body: Symbol SetRegister(Node p,Symbol r) { Symbol w; w = p->kids[0]->syms[2]; if (w->x.regnode == NULL || w->x.regnode->vbl == NULL) p->kids[0]->syms[2] = r; return r; } This function tests that in the given node, the left child isn't already assigned to a register. It will assign the register only if this is not the case. Otherwise, the compiler will generate the move. We come now to the center of the routine: Generating code for the strlen utility. static Symbol strlenGen(Node p) { static int labelCount; // OK, the first thing to do is to see if we should pop our arguments. // If that is the case, pop them into the right registers. if (p->x.nestedCall) { print("\tpopl\t%%ecx\n"); } /* Here we generate the code for the strlen routine. Note that the % sign is used by the assembler of lcc-win32 to mark a register keyword, but our print() function uses it too to mark (as printf) the beginning of an argument. We must double them to get around this collision. 1) Set the counter to minus one */ print("\torl\t$-1,%%eax\n"); /* 2) We should generate the label for this instance. All labels must be unique, and the easiest way to ensure that we always generate a new label is to number them consecutively using a counter. To avoid colliding with other labels, we use a unique prefix too. */ print("_$strlen%d:\n",labelCount); /* 3) Now we generate the code for the body of the loop searching for the character zero. */ print("\tinc\t%%eax\n"); /* 4) Note the dollar before the immediate constant.*/ print("\tcmpb\t$0,(%%ecx,%%eax)\n"); /* 5) We generate the jump, incrementing our loop counter afterwards */ print("\tjnz\t_$strlen%d\n",labelCount++); /* Now we are done, the result is in eax, as it should. We finish our function. Note that no pops are needed, since the ones we did at the beginning (eventually) are just to compensate for the pushs the compiler generated. Note too that we shouldn't insert a return statement since this is a macro that shouldn't cause the current function to return! */ } We compile the compiler, and we obtain a new compiler that will recognize the macro we have just created. Compiling the compiler with itself is a good test for your new function of course. This should be done at least three times to be sure that your function is working OK. Register assignments -------------------- In general, you can use ECX, EDX, and EAX as you wish. The contents of EBX, ESI, EBP and EDI should always be saved. If you destroy them unpredictable results will surely occur. Lets write a test function for our new compiler: #include #ifdef MACRO int _stdcall _strlen(char *); #define strlen _strlen #else int strlen(char *); #endif int main(int argc, char *argv[]) { if (argc > 1) printf("Length of \"%s\" is %d\n", argv[1], strlen(argv[1])); return 0; } In the C source, we use the conditional MACRO to signify if we should use our macro, or just generate a call to the normal strlen procedure for comparison purposes. We compile this with our new compiler, and add the S parameter to see what is generating. lcc -S DMACRO tstrlen.c The assembly (that the compiler writes in tstrlen.asm) is then: _main: pushl %ebp movl %esp,%ebp pushl %edi .line 9 .line 10 cmpl $1,8(%ebp) jle _$2 .line 11 movl 12(%ebp),%edi ; Our argument gets assigned to ECX, as our strlenArgs function ; defined movl 4(%edi),%ecx ; Here is the begin of our macro body orl $-1,%eax ; This is our generated label _$strlen0: inc %eax cmpb $0,(%ecx,%eax) jnz _$strlen0 ; Our macro ends here, leaving its results in EAX pushl %eax movl 12(%ebp),%edi pushl 4(%edi) pushl $_$4 call _printf addl $12,%esp _$2: .line 12 xor %eax,%eax .line 13 popl %edi popl %ebp ret We see that there is absolutely no call overhead. The arguments are assigned to the right registers in our function strlenArgs, and the body is expanded in-line by strlenGen. Next, we link our executable: D:\lcc\src74\test>lcclnk tstrlen.obj And we run a test: D:\lcc\src74\test>tstrlen abcde The length of "abcde" is 5 D:\lcc\src74\test> Here is the strlenGen() function again for clarity. static void strlenGen(Node p) { static int labelCount; if (p->x.nestedCall) { print("\tpopl\t%%ecx\n"); } print("\torl\t$-1,%%eax\n"); print("_$strlen%d:\n",labelCount); print("\tinc\t%%eax\n"); print("\tcmpb\t$0,(%%ecx,%%eax)\n"); print("\tjnz\t_$strlen%d\n",labelCount++); } Another example: inlining the strchr function --------------------------------------------- To demonstrate a function with two arguments, we inline the strchr function. This function should return a pointer to the first occurrence of the given character in a string, or NULL, if the character doesnt appear in the string. The implementation could be like this : _strchr: movb (%eax),%dl // read a character cmpb %cl,%dl // compare it to searched for char je _strchrexit // exit if found with pointer to char as result incl %eax // move pointer to next char orb %dl,%dl // test for end of string jne strchr // if not zero continue loop xorl %eax,%eax // Not found. Zero result strchrexit : We just scan the characters looking for either zero (end of the string) or the given char. The pointer to the string will be in EAX, and the character to be searched for will be in ECX. We use EDX as a scratch register. The next step is then, to write the strchr function for assigning the arguments. Here it is : static Symbol strchrArgs(Node p) { Symbol r=NULL; switch (ArgumentsIndex) { case 0: // First argument (from right to left) char to be searched. // We put it in ECX if (p->x.nestedCall == 0) { r = SetRegister(p,intreg[ECX]); } break; case 1: // Second argument: pointer to the string. We put it in EAX if (p->x.nestedCall == 0) { r = SetRegister(p,intreg[EAX]); } break; } ArgumentsIndex++; if (p->x.nestedCall == 0) p->syms[2] = r; if (ArgumentsIndex == 2) ArgumentsIndex = 0; return r; } The next step is finally to write the generating function. Here it is; note that we need two labels: static void strchrGen(Node p) { static int labelCount; if (p->x.nestedCall) { print("\tpopl\t%%ecx\n"); } print("_$strchr%d:\n",labelCount); print("\tmovb\t(%%eax),%%dl\n"); print("\tcmpb\t%%cl,%%dl\n"); print("\tje\t_$strchr%d\n",labelCount+1); print("\tinc\t%%eax\n"); print("\torb\t%%dl,%%dl\n"); print("\tjne\t_$strchr%d\n",labelCount); print("\txorl\t%%eax,%%eax\n"); print("_$strchr%d:\n",labelCount+1); labelCount += 2; } This facility is not very common in a compiler system, and it allows you to use assembly language in the routines that are *really* needed in a software system, leaving to the compiler the tedious work of generating the assembly for you in the 90% of the code where speed is not so important after all. Another benefit is that you can't do simple mistakes when passing arguments to your assembler macros since they are understood as function calls by the compiler, and all prototype checking is done by the front end. If you attempt to use the strchr macro like this: strchr('\n",string); the compiler will issue an error. The lcc-win32 system can be downloaded free of charge from http://ps.qss.cz/lcc ::/ \::::::. :/___\:::::::. /| \::::::::. :| _/\:::::::::. :| _|\ \::::::::::. :::\_____\:::::::::::...........................................FEATURE.ARTICLE Accessing COM Objects from Assembly by Ernest Murphy Abstract -------- The COM (Component Object Model) is used by the Windows Operation system in increasing ways. For example, the shell.dll uses COM to access some of its API methods. The IShellLink and IPersistFile interfaces of the shell32.dll will be demonstrated to create a shortcut shell link. A basic understanding of COM is assumed. The code sample included is MASM specific. Introduction ------------ COM may seem complicated with its numerous details, but in use these complications disappear into simple function calls. The hardest part is understanding the data structures involved so you can define the interfaces. I apologize for all the C++ terminology used in here. While COM is implementation neutral, it borrows much terminology from C++ to define itself. In order to use the COM methods of some object, you must first instance or create that object from its coclass, then ask it to return you a pointer to it's interface. This process is performed by the API function CoCreateInstance. When you are done with the interface you call it's Release method, and COM and the coclass will take care of unloading the coclass. Assessing COM Methods --------------------- To use COM methods you need to know before hand what the interface looks like. Even if you "late bind" through an IDispatch interface, you still need to know what IDispatch looks like. An COM interface is just table of pointers to functions. Let's start with the IUnknown interface. If you were to create a component that simply exports the IUnknown interface, you have a fully functional COM object (albeit on the level of "Hello World"). IUnknown has the 3 basic methods of every interface, since all interfaces inherit from IUnknown. Keep in mind all an interface consists of is a structure of function pointers. For IUnknown, it looks like this: IUnknown STRUCT DWORD ; IUnknown methods QueryInterface IUnknown_QueryInterface ? AddRef IUnknown_AddRef ? Release IUnknown_Release ? IUnknown ENDS That's it, just 12 bytes long. It holds 3 DWORD pointers to the procedures that actually implement the methods. It is the infamous "vtable" you may have heard of. The pointers are defined as such so we can have MASM do some type checking for us when compiling our calls. Since the vtable holds the addresses of functions, or pointers, these pointers are typedefed in our interface definition as such: IUnknown_QueryInterface typedef ptr IUnknown_QueryInterfaceProto IUnknown_AddRef typedef ptr IUnknown_AddRefProto IUnknown_Release typedef ptr IUnknown_ReleaseProto Finally, we define the function prototypes as follows: IUnknown_QueryInterfaceProto typedef PROTO :DWORD, :DWORD, :DWORD IUnknown_AddRefProto typedef PROTO :DWORD IUnknown_ReleaseProto typedef PROTO :DWORD In keeping with the MASM32 practice of "loose" type checking, function parameters are just defined as DWORDs. Lots of work to set things up, but it does keeps lots of errors confined to compile time, not run time. In practice, you can wrap up your interface definitions in include files and keep them from cluttering up your source code. One rather big compilation on defining an interface: MASM cannot resolve forward references like this, so we have to define them backwards, by defining the function prototype typedefs first, and the interface table last. The sample program later on defines the interfaces this way. To actually use an interface, you need a pointer to it. The CoCreateInstance API can be used to return us this indirect pointer to an interface structure. It is one level removed from the vtable itself, and actually points to the "object" that holds the interface. (This would be clearer had I been creating the interface instead of using one. Please wait for a future article for that). The place this pointer points to in the object points to the interface structure. Thus, this pointer is generically named "ppv", for "pointer to pointer to (void)," where (void) means an unspecified type. For example, say we used CoCreateInstance and successfully got an interface pointer ppv, and wanted to see if it supports some other interface. We can call its QueryInterface method and request a new ppv to the other interface we are interested in. Such a call would look like this: mov eax, ppv ; get pointer to the object mov edx, [eax] ; and use it to find the interface structure ; and then call that method invoke (IUnknown PTR [edx]).QueryInterface, ppv, ADDR IID_SomeOtherInterface, ADDR ppv_new I hope you find this as wonderfully simple as I do. IID_SomeOtherInterface holds the GUID of the interface we desire, and ppv_new is a new pointer we can use to access it. Also note we must pass in the pointer we used, this lets the interface know which object (literally "this" object) we are using. Incidentally, in a previous APJ article on COM, there was an error in how a COM interface is invoked. THIS was left out of the COM call. The program seemed to work, because the COM invoke was invoked from the main code, not from a procedure, and did not require a return call before calling ExitProcess. Had this COM invoke been done from a procedure, a stack error crash would have resulted. Note the register must be type cast (IUnknown PTR [edx]). This lets the compiler know what structure to use to get the correct offset in the vtable for the .QueryInterface function (in this case it means an offset of zero from edx). Actually, the information contained by the interface name and function name called disappear at compile time, all that is left is a numeric offset from an as of yet value unspecified pointer. We can simplify a COM invoke further with a macro: coinvoke MACRO pInterface:REQ, Interface:REQ, Function:REQ, args:VARARG LOCAL istatement, arg ;; invokes an arbitrary COM interface ;; pInterface pointer to a specific interface instance ;; Interface the Interface's struct typedef ;; Function which function or method of the interface to perform ;; args all required arguments ;; (type, kind and count determined by the function) istatement TEXTEQU FOR arg, ; build the list of parameter arguments istatement CATSTR istatement, <, >, <&arg> ENDM mov eax, pInterface mov eax, [eax] istatement ENDM Thus, the same QueryInterface method as before can be invoked in a single line: coinvoke ppv ,IUnknown, QueryInterface, ADDR IID_SomeOtherInterface, ADDR ppnew The return parameter for every COM call is an hResult, a 4 byte return value in eax. It is used to signal success or failure. Since the most significant digit is used to indicate failure, you can test the result with a simple: .IF !SIGN? ; function passed .ELSE ; function failed .ENDIF Again, this can be simplified with some more simple macros: SUCCEEDED TEXTEQU FAILED TEXTEQU (The not ! sign must be doubled since that symbol has special meaning in MASM macros) That's about all you need to fully invoke and use interfaces from COM objects from assembly. These techniques work with any COM or activeX object. Back to the Real Word: Using IShellFile and IPersistFile from shell32.dll ------------------------------------------------------------------------- The shell32.dll provides a simple, easy way to make shell links (shortcuts). However, it uses a COM interface to provide this service. The sample below is based on the MSDN "Shell Links" section for "Internet Tools and Technologies." This may be a strange place to find documentation, but there it is. The "Shell Links" article may be found at http://msdn.microsoft.com/library/psdk/shellcc/shell/Shortcut.htm For this tutorial we will access the following members of the IShellLink and the IPersistFile interfaces. Note every interface includes a "ppi" interface parameter, this is the interface that we calling to (it is the THIS parameter). (The following interface information is a copy of information published by Microsoft) IShellLink::QueryInterface, ppi, ADDR riid, ADDR ppv * riid: The identifier of the interface requested. To get access to the * ppv: The pointer to the variable that receives the interface. Description: Checks if the object also supports the requested interface. If so, assigns the ppv pointer with the interface's pointer. IShellLink::Release, ppi Description: Decrements the reference count on the IShellLink interface. IShellLink:: SetPath, ppi, ADDR szFile * pszFile: A pointer to a text buffer containing the new path for the shell link object. Description: Defines where the file the shell link points to. IShellLink::SetIconLocation, ppi, ADDR szIconPath, iIcon * pszIconPath: A pointer to a text buffer containing the new icon path. * iIcon: An index to the icon. This index is zero based. Description: Sets which icon the shelllink will use. IPersistFile::Save, ppi, ADDR szFileName, fRemember * pszFileName: Points to a zero-terminated string containing the absolute path of the file to which the object should be saved. * fRemember: Indicates whether the pszFileName parameter is to be used as the current working file. If TRUE, pszFileName becomes the current file and the object should clear its dirty flag after the save. If FALSE, this save operation is a "Save A Copy As ..." operation. In this case, the current file is unchanged and the object should not clear its dirty flag. If pszFileName is NULL, the implementation should ignore the fRemember flag. Description: Perform a save operation for the ShellLink object, or saves the shell link are creating. IPersistFile::Release, ppi Description: Decrements the reference count on the IPersistFile interface. These interfaces contain many many more methods (see the full interface definitions in the code below), but we only need concentrate on those we will actually be using. A shell link is the MS-speak name for a shortcut icon. The information contained in a link (.lnk) file is: 1 - The file path and name of the program to shell. 2 - Where to obtain the icon to display for the shortcut (usually from the executable itself), and which icon in that file to use. We will use the first icon in the file 3 - A file path and name where the shortcut should be stored. The use of these interfaces is simple and straightforward. It goes like this: * Call CoCreateInstance CLSID_ShellLink for a IID_IShellLink interface * Queryinterface IShellLink for an IID_IPersistFile interface. * Call IShellLink.SetPath to specify where the shortcut target is * Call IShellLink.SetIconLocation to specify which icon to use * Call IPersistFile.Save to save our new shortcut .lnk file. * Call IPersistFile.Release * Call IShellLink.Release The last two steps will releases our hold on these interfaces, which will automatically lead to the dll that supplied them being unloaded. Again, the hard part in this application was finding documentation. What finally found broke the search open was using Visual Studio "Search in Files" to find "IShellLink" and " IPersistFile" in the /include area of MSVC. This lead me to various .h files, from which I hand translated the interfaces from C to MASM. Another handy tool I could have used is the command line app "FindGUID.exe," which looks through the registry for a specific interface name or coclass, or will output a list of every class and interface with their associated GUIDs. Finally, the OLEView.exe application will let you browse the registry type libraries and mine them for information. However, these tools come with MSVC and are proprietary. Take care when defining an interface. Missing vtable methods lead to strange results. Essentially COM calls, on one level, amount to "perform function (number)" calls. Leave a method out of the vtable definition and you call the wrong interface. The original IShellLink interface definition I used from a inc file I downloaded had a missing function. The calls I made generated a "SUCEEDED" hResult, but in some cases would not properly clean the stack (since my push count did not match the invoked function's pop count), thus lead to a GPF as I exited a procedure. Keep this in mind if you ever get similar "weird" results. MakeLink.asm, a demonstration of COM ------------------------------------ This program does very little, as all good tutorial programs should. When run, it creates a shortcut to itself, in the same directory. It can be amusing to run from file explorer and watch the shortcut appear. Then you can try the shortcut and watch it's creation time change. The shell link tutorial code follows. It begins with some "hack code" to get the full file name path of the executable, and also makes a string with the same path that changes the file to "Shortcut To ShellLink.lnk" These strings are passed to the shell link interface, and it is saved (or persisted in COM-speak). The CoCreateLink procedure used to actually perform the COM methods and perform this link creation has been kept as general as possible, and may have reuse possibilities in other applications. ;--------------------------------------------------------------------- ; MakeLink.asm ActiveX simple client to demonstrate basic concepts ; written & (c) copyright April 5, 2000 by Ernest Murphy ; ; contact the author at ernie@surfree.com ; ; may be reused for any educational or ; non-commercial application without further license ;--------------------------------------------------------------------- .386 .model flat, stdcall option casemap:none include \masm32\include\windows.inc include \masm32\include\user32.inc include \masm32\include\kernel32.inc include \masm32\include\ole32.inc includelib \masm32\lib\user32.lib includelib \masm32\lib\kernel32.lib includelib \masm32\lib\ole32.lib ;--------------------------------------------------------------------- CoCreateLink PROTO :DWORD, :DWORD ;--------------------------------------------------------------------- ; Interface definitions ; IUnknown Interface IUnknown_QueryInterfaceProto typedef PROTO :DWORD, :DWORD, :DWORD IUnknown_AddRefProto typedef PROTO :DWORD IUnknown_ReleaseProto typedef PROTO :DWORD IUnknown_QueryInterface typedef ptr IUnknown_QueryInterfaceProto IUnknown_AddRef typedef ptr IUnknown_AddRefProto IUnknown_Release typedef ptr IUnknown_ReleaseProto IUnknown STRUCT DWORD ; IUnknown methods QueryInterface IUnknown_QueryInterface ? AddRef IUnknown_AddRef ? Release IUnknown_Release ? IUnknown ENDS ; IShellLink Interface IShellLink_IShellLink_GetPathProto typedef PROTO :DWORD, :DWORD, :DWORD, :DWORD, :DWORD IShellLink_GetIDListProto typedef PROTO :DWORD, :DWORD IShellLink_SetIDListProto typedef PROTO :DWORD, :DWORD IShellLink_GetDescriptionProto typedef PROTO :DWORD, :DWORD, :DWORD IShellLink_SetDescriptionProto typedef PROTO :DWORD, :DWORD IShellLink_GetWorkingDirectoryProto typedef PROTO :DWORD, :DWORD, :DWORD IShellLink_SetWorkingDirectoryProto typedef PROTO :DWORD, :DWORD IShellLink_GetArgumentsProto typedef PROTO :DWORD, :DWORD, :DWORD IShellLink_SetArgumentsProto typedef PROTO :DWORD, :DWORD IShellLink_GetHotkeyProto typedef PROTO :DWORD, :DWORD IShellLink_SetHotkeyProto typedef PROTO :DWORD, :WORD IShellLink_GetShowCmdProto typedef PROTO :DWORD, :DWORD IShellLink_SetShowCmdProto typedef PROTO :DWORD, :DWORD IShellLink_GetIconLocationProto typedef PROTO :DWORD, :DWORD, :DWORD, :DWORD IShellLink_SetIconLocationProto typedef PROTO :DWORD, :DWORD, :DWORD IShellLink_SetRelativePathProto typedef PROTO :DWORD, :DWORD, :DWORD IShellLink_ResolveProto typedef PROTO :DWORD, :DWORD, :DWORD IShellLink_SetPathProto typedef PROTO :DWORD, :DWORD IShellLink_GetPath typedef ptr IShellLink_IShellLink_GetPathProto IShellLink_GetIDList typedef ptr IShellLink_GetIDListProto IShellLink_SetIDList typedef ptr IShellLink_SetIDListProto IShellLink_GetDescription typedef ptr IShellLink_GetDescriptionProto IShellLink_SetDescription typedef ptr IShellLink_SetDescriptionProto IShellLink_GetWorkingDirectory typedef ptr IShellLink_GetWorkingDirectoryProto IShellLink_SetWorkingDirectory typedef ptr IShellLink_SetWorkingDirectoryProto IShellLink_GetArguments typedef ptr IShellLink_GetArgumentsProto IShellLink_SetArguments typedef ptr IShellLink_SetArgumentsProto IShellLink_GetHotkey typedef ptr IShellLink_GetHotkeyProto IShellLink_SetHotkey typedef ptr IShellLink_SetHotkeyProto IShellLink_GetShowCmd typedef ptr IShellLink_GetShowCmdProto IShellLink_SetShowCmd typedef ptr IShellLink_SetShowCmdProto IShellLink_GetIconLocation typedef ptr IShellLink_GetIconLocationProto IShellLink_SetIconLocation typedef ptr IShellLink_SetIconLocationProto IShellLink_SetRelativePath typedef ptr IShellLink_SetRelativePathProto IShellLink_Resolve typedef ptr IShellLink_ResolveProto IShellLink_SetPath typedef ptr IShellLink_SetPathProto IShellLink STRUCT DWORD QueryInterface IUnknown_QueryInterface ? AddRef IUnknown_AddRef ? Release IUnknown_Release ? GetPath IShellLink_GetPath ? GetIDList IShellLink_GetIDList ? SetIDList IShellLink_SetIDList ? GetDescription IShellLink_GetDescription ? SetDescription IShellLink_SetDescription ? GetWorkingDirectory IShellLink_GetWorkingDirectory ? SetWorkingDirectory IShellLink_SetWorkingDirectory ? GetArguments IShellLink_GetArguments ? SetArguments IShellLink_SetArguments ? GetHotkey IShellLink_GetHotkey ? SetHotkey IShellLink_SetHotkey ? GetShowCmd IShellLink_GetShowCmd ? SetShowCmd IShellLink_SetShowCmd ? GetIconLocation IShellLink_GetIconLocation ? SetIconLocation IShellLink_SetIconLocation ? SetRelativePath IShellLink_SetRelativePath ? Resolve IShellLink_Resolve ? SetPath IShellLink_SetPath ? IShellLink ENDS ; IPersistFile Interface IPersistFile_GetClassIDProto typedef PROTO :DWORD, :DWORD IPersistFile_IsDirtyProto typedef PROTO :DWORD IPersistFile_LoadProto typedef PROTO :DWORD, :DWORD, :DWORD IPersistFile_SaveProto typedef PROTO :DWORD, :DWORD, :DWORD IPersistFile_SaveCompletedProto typedef PROTO :DWORD, :DWORD IPersistFile_GetCurFileProto typedef PROTO :DWORD, :DWORD IPersistFile_GetClassID typedef ptr IPersistFile_GetClassIDProto IPersistFile_IsDirty typedef ptr IPersistFile_IsDirtyProto IPersistFile_Load typedef ptr IPersistFile_LoadProto IPersistFile_Save typedef ptr IPersistFile_SaveProto IPersistFile_SaveCompleted typedef ptr IPersistFile_SaveCompletedProto IPersistFile_GetCurFile typedef ptr IPersistFile_GetCurFileProto IPersistFile STRUCT DWORD QueryInterface IUnknown_QueryInterface ? AddRef IUnknown_AddRef ? Release IUnknown_Release ? GetClassID IPersistFile_GetClassID ? IsDirty IPersistFile_IsDirty ? Load IPersistFile_Load ? Save IPersistFile_Save ? SaveCompleted IPersistFile_SaveCompleted ? GetCurFile IPersistFile_GetCurFile ? IPersistFile ENDS ;--------------------------------------------------------------------- coinvoke MACRO pInterface:REQ, Interface:REQ, Function:REQ, args:VARARG LOCAL istatement, arg ;; invokes an arbitrary COM interface ;; pInterface pointer to a specific interface instance ;; Interface the Interface's struct typedef ;; Function which function or method of the interface to perform ;; args all required arguments ;; (type, kind and count determined by the function) istatement TEXTEQU FOR arg, ; build the list of parameter arguments istatement CATSTR istatement, <, >, <&arg> ENDM mov eax, pInterface mov eax, [eax] istatement ENDM ; equate primitives SUCEEDED TEXTEQU FAILED TEXTEQU MakeMessage MACRO Text:REQ ; macro to display a message box ; the text to display is kept local to ; this routine for ease of use LOCAL lbl LOCAL sztext jmp lbl sztext: db Text,0 lbl: invoke MessageBox,NULL,sztext,ADDR szAppName,MB_OK ENDM ;--------------------------------------------------------------------- .data szAppName BYTE "Shell Link Maker", 0 szLinkName BYTE "Shortcut to MakeLink.lnk", 0 szBKSlash BYTE "\", 0 hInstance HINSTANCE ? Pos DWORD ? szBuffer1 BYTE MAX_PATH DUP(?) szBuffer2 BYTE MAX_PATH DUP(?) ;----------------------------------------------------------------------- .code start: ;--------------------------------------------- ; this bracketed code is just a 'quick hack' ; to replace the filename from the filepathname ; with the 'Shortcut to' title ; invoke GetModuleHandle, NULL mov hInstance, eax invoke GetModuleFileName, NULL, ADDR szBuffer1, MAX_PATH invoke lstrcpy, ADDR szBuffer2, ADDR szBuffer1 ; Find the last backslash '\' and change it to zero mov edx, OFFSET szBuffer2 mov ecx, edx .REPEAT mov al, BYTE PTR [edx] .IF al == 92 ; "\" mov ecx, edx .ENDIF inc edx .UNTIL al == 0 mov BYTE PTR [ecx+1], 0 invoke lstrcpy, ADDR szBuffer2, ADDR szLinkName ;---------------------------------------------- ; here is where we call the proc with the COM methods invoke CoInitialize, NULL MakeMessage "Let's try our Createlink." invoke CoCreateLink, ADDR szBuffer1, ADDR szBuffer2 MakeMessage "That's all folks !!!" invoke CoUninitialize invoke ExitProcess, NULL ;----------------------------------------------------------------------- CoCreateLink PROC pszPathObj:DWORD, pszPathLink:DWORD ; CreateLink - uses the shell's IShellLink and IPersistFile interfaces ; to create and store a shortcut to the specified object. ; Returns the hresult of calling the member functions of the interfaces. ; pszPathObj - address of a buffer containing the path of the object. ; pszPathLink - address of a buffer containing the path where the ; shell link is to be stored. ; adapted from MSDN article "Shell Links" ; deleted useless "description" method ; added set icon location method LOCAL pwsz :DWORD LOCAL psl :DWORD LOCAL ppsl :DWORD LOCAL ppf :DWORD LOCAL pppf :DWORD LOCAL hResult :DWORD LOCAL hHeap :DWORD .data CLSID_ShellLink GUID <0021401H, 0000H, 0000H, \ <0C0H, 00H, 00H, 00H, 00H, 00H, 00H, 046H>> IID_IShellLink GUID <00214EEH, 0000H, 0000H, \ <0C0H, 00H, 00H, 00H, 00H, 00H, 00H, 046H>> IID_IPersistFile GUID <000010BH, 0000H, 0000H, \ <0C0H, 00H, 00H, 00H, 00H, 00H, 00H, 046H>> .code ; first, get some heap for a wide buffer invoke GetProcessHeap mov hHeap, eax invoke HeapAlloc, hHeap, NULL, MAX_PATH * 2 mov pwsz, eax ; and set up some local pointers (we can't use ADDR on local vars) lea eax, psl mov ppsl, eax lea eax, ppf mov pppf, eax ; Get a pointer to the IShellLink interface. invoke CoCreateInstance, ADDR CLSID_ShellLink, NULL, CLSCTX_INPROC_SERVER, ADDR IID_IShellLink, ppsl mov hResult, eax test eax, eax .IF SUCEEDED ; Query IShellLink for the IPersistFile ; interface for saving the shortcut coinvoke psl, IShellLink, QueryInterface, ADDR IID_IPersistFile, pppf mov hResult, eax test eax, eax .IF SUCEEDED ; Set the path to the shortcut target coinvoke psl, IShellLink, SetPath, pszPathObj mov hResult, eax ; add the description. coinvoke psl, IShellLink, SetIconLocation, pszPathObj, 0 ; use first icon found mov hResult, eax ; change string to Unicode. (COM typically expects Unicode strings) invoke MultiByteToWideChar, CP_ACP, 0, pszPathLink, -1, pwsz, MAX_PATH ; Save the link by calling IPersistFile::Save coinvoke ppf, IPersistFile, Save, pwsz, TRUE mov eax, hResult ; release the IPersistFile ppf pointer coinvoke ppf, IPersistFile, Release mov hResult, eax .ENDIF ; release the IShellLink psl pointer coinvoke psl, IShellLink, Release mov hResult, eax .ENDIF ; free our heap space invoke HeapFree, hHeap, NULL, pwsz mov eax, hResult ; since we reuse this variable over and over, ; it contains the last operations result ret CoCreateLink ENDP ;----------------------------------------------------------- end start ;----------------------------------------------------------------------- Bibliography: ------------- "Inside COM, Microsoft's Component Object Model" Dale Rogerson Copyright 1997, Paperback - 376 pages CD-ROM edition Microsoft Press; ISBN: 1572313498 (THE fundamental book on understanding how COM works on a fundamental level. Uses C++ code to illustrate basic concepts as it builds simple fully functional COM object) "Automation Programmer's Reference : Using ActiveX Technology to Create Programmable Applications" (no author listed) Copyright 1997, Paperback - 450 pages Microsoft Press; ISBN: 1572315849 (This book has been available online on MSDN in the past, but it is cheap enough for those of you who prefer real books you can hold in your hand. Defines the practical interfaces and functions that the automation libraries provide you, but is more of a reference book then a "user's guide") Microsoft Developers Network http://msdn.microsoft.com "Professional Visual C++ 5 ActiveX/Com Control Programming" Sing Li and Panos Economopoulos Copyright April 1997, Paperback - 500 pages (no CD, files available online) Wrox Press Inc; ISBN: 1861000375 (Excellent description of activeX control and control site interfaces. A recent review of this book on Amazon.com stated "These guys are the type that want to rewrite the world's entire software base in assembler." Need I say more?) "sean's inconsequential homepage" http://www.eburg.com/~baxters/ Various hardcore articles on low-level COM and ATL techniques. Coded in C++ "Using COM in Assembly Language" Bill Tyler Assembly Language Journal, Apr-June 99 Mr Tyler keeps a web site at: http://thunder.prohosting.com/~asm1/ ::/ \::::::. :/___\:::::::. /| \::::::::. :| _/\:::::::::. :| _|\ \::::::::::. :::\_____\:::::::::::...........................................FEATURE.ARTICLE 64-bit Integer/ASCII Conversion by X-Calibre The following routines provide an assembly-language library for converting 64-bit integers to and from ASCII, such as would be required when preparing user-supplied data for qword arithmetic or FPU instructions. The library consists of the routines ParseRadixSigned, ParseRadixUnsigned, PrintRadixSigned, and PrintRadixUnsigned, and the macro Divide64. Wrappers for calling the routines from C code have also been provided. ParseRadix ---------- ParseRadix is a pair of routines for converting an ASCII string to a signed or unsigned 64-bit integer, using a given radix as a base. The routines take a pointer to a string and an integer radix as input, and return a 64-bit number. ;------------------------------------------------------------------------- ParseRadixUnsigned PROC ; Input: Pointer to zero-terminated string in ESI, radix in EDI ; Output: Parsed number in EDX::EAX ; Uses: EAX, EBX, ECX, EDX, ESI, EDI xor ebx, ebx ; result in EDX::EAX xor eax, eax xor edx, edx mov al, [esi] inc esi test eax, eax jz @@endOfParsing sub eax, 30h .IF eax > 9 sub eax, 7 .ENDIF mov bl, [esi] @@smallParseLoop: ; ASCII to number conversion sub ebx, 30h inc esi mul edi .IF ebx > 9 sub ebx, 7 .ENDIF add eax, ebx mov bl, [esi] jc @@carry test ebx, ebx jnz @@smallParseLoop ret @@carry: inc edx test ebx, ebx jz @@endOfParsing @@bigParseLoop: ; ASCII to number conversion mov ecx, eax mov eax, edx sub ebx, 30h inc esi mul edi xchg eax, ecx mul edi .IF ebx > 9 sub ebx, 7 .ENDIF add eax, ebx mov bl, [esi] adc edx, ecx test ebx, ebx jnz @@bigParseLoop @@endOfParsing: ret ParseRadixUnsigned ENDP ParseRadixSigned PROC ; Input: Pointer to zero-terminated string in ESI, radix in EDI ; Output: Parsed number in EDX::EAX ; Uses: EAX, EBX, ECX, EDX, ESI, EDI .code ; If string does not start with a '-', consider it positive cmp byte ptr [esi], '-' jne ParseRadixUnsigned ; Number is negative, first parse the absolute value inc esi call ParseRadixUnsigned ; Now negate the absolute value to get the negative result neg edx neg eax sbb edx, 0 ret ParseRadixSigned ENDP ;------------------------------------------------------------------------- The following is a wrapper used for calling the ParseRadix routines from C. The wrapper provides the following C functions: extern unsigned __int64 __stdcall ParseRadixUnsignedC(char *lpBuffer, unsigned int radix); extern signed __int64 __stdcall ParseRadixSignedC(char *lpBuffer, unsigned int radix); ;------------------------------------------------------------------------- .386 .Model Flat, StdCall .code include ParseRadix.asm ParseRadixUnsignedC PROC lpBuffer:PTR BYTE, radix:DWORD push esi mov esi, [lpBuffer] push edi mov edi, [radix] push ebx call ParseRadixUnsigned pop ebx pop edi pop esi ret ParseRadixUnsignedC ENDP ParseRadixSignedC PROC lpBuffer:PTR BYTE, radix:DWORD push esi mov esi, [lpBuffer] push edi mov edi, [radix] push ebx call ParseRadixSigned pop ebx pop edi pop esi ret ParseRadixSignedC ENDP END ;------------------------------------------------------------------------- Divide64 -------- Divide64 is a macro for doing 64-bit division using 32-bit integer instructions. Note that this is a 'long division' algorithm. It can easily be expanded to be able to divide any number by 32 bits. I only use it for 64 bits here to keep the CPU from getting an exception on overflow when the input is larger than ((2^32)-1)*divisor, so that printing any 64 bit number with any radix is possible. ;------------------------------------------------------------------------- Divide64 MACRO ; Input: 64 bit dividend in EBX::ECX, 32 bit divisor in ESI ; Output: 64 bit result in EBX::EAX, 32 bit remainder in EDX ; Uses: EAX, EBX, ECX, EDX, ESI ; Divide high dword by divisor. mov eax, ebx xor edx, edx div esi ; Put remainder as high dword of the original dividend. mov ebx, eax mov eax, ecx div esi ENDM ;------------------------------------------------------------------------- PrintRadix ---------- PrintRadix is a pair of routines for converting signed and unsigned 64-bit numbers to an ASCII, string, using a given radix as base. These routines take a 64-bit number and an integer radix as inpit, and return the pointer to a character buffer. ;------------------------------------------------------------------------- PrintRadixUnsigned PROC ; Input: 64 bit unsigned number in EBX::ECX, radix in ESI, pointer to output ; buffer in EDI ; Output: Zero-terminated ASCII string in output buffer, length of string in ; EAX ; Uses: EAX, EBX, ECX, EDX, ESI, EDI, EBP xor ebp, ebp ; StringLength counter ; If the high dword of the number is larger than the divisor, we ; have to do a 'long division' to prevent overflow. cmp ebx, esi jb smallDiv longDiv: Divide64 ; Convert the remainder to an ASCII char. add edx, 30h dec esp .IF edx > 39h add edx, 7 .ENDIF ; Store char on stack. inc ebp ; While result is not 0, we loop. test eax, eax mov ecx, eax mov [esp], dl jz lowDWORDIsZero cmp ebx, esi jae longDiv smallDiv: ; Set EBX::ECX to EDX::EAX for a normal 64->32 division. mov edx, ebx mov eax, ecx radixLoopSmall: div esi ; Convert the remainder to an ASCII char. add edx, 30h dec esp .IF edx > 39h add edx, 7 .ENDIF ; Store char on stack. inc ebp mov [esp], dl ; Clean out high dword for next division. xor edx, edx ; While result is not 0, we loop. test eax, eax jnz radixLoopSmall toBuffer: mov eax, ebp ; Return stringlength (not including 0-terminator) toBufferLoop: ; Copy the string from stack to the destination buffer. inc edi mov dl, [esp] inc esp dec ebp mov [edi-1], dl jnz toBufferLoop ; Zero terminate the string. mov byte ptr [edi], 0 ret lowDWORDIsZero: test ebx, ebx jnz longDiv ; We have the final string, time to copy it to the destination buffer. jmp toBuffer PrintRadixUnsigned ENDP PrintRadixSigned PROC ; Input: 64 bit signed number in EBX::ECX, radix in ESI, pointer to output ; buffer in EDI ; Output: Zero-terminated ASCII string in output buffer, length of string in ; EAX ; Uses: EAX, EBX, ECX, EDX, ESI, EDI, EBP ; If number is non-negative, use the normal PrintRadix test ebx, ebx jns PrintRadixUnsigned ; Prefix the number with a - sign mov byte ptr [edi], '-' inc edi ; Negate the 64 bit number neg ebx neg ecx sbb ebx, 0 ; Do a normal PrintRadix call PrintRadixUnsigned inc eax ret PrintRadixSigned ENDP ;------------------------------------------------------------------------- The following is a wrapper used for calling the PrintRadix routines from C. The wrapper provides the following C functions: extern unsigned int __stdcall PrintRadixUnsignedC(char *lpBuffer, unsigned __int64 number, unsigned int radix); extern unsigned int __stdcall PrintRadixSignedC(char *lpBuffer, signed __int64 number, unsigned int radix); ;------------------------------------------------------------------------- .386 .Model Flat, StdCall .code include PrintRadix.asm PrintRadixUnsignedC PROC lpBuffer:PTR BYTE, number:QWORD, radix:DWORD push ebp mov ecx, dword ptr [number] push ebx mov ebx, dword ptr [number+sizeof DWORD] push esi mov esi, [radix] push edi mov edi, [lpBuffer] call PrintRadixUnsigned pop edi pop esi pop ebx pop ebp ret PrintRadixUnsignedC ENDP PrintRadixSignedC PROC lpBuffer:PTR BYTE, number:QWORD, radix:DWORD push ebp mov ecx, dword ptr [number] push ebx mov ebx, dword ptr [number+sizeof DWORD] push esi mov esi, [radix] push edi mov edi, [lpBuffer] call PrintRadixSigned pop edi pop esi pop ebx pop ebp ret PrintRadixSignedC ENDP END ;------------------------------------------------------------------------- ::/ \::::::. :/___\:::::::. /| \::::::::. :| _/\:::::::::. :| _|\ \::::::::::. :::\_____\:::::::::::................................WIN32.ASSEMBLY.PROGRAMMING Win32 AppFatalExit Skeleton by Chili This is just a Win32 application skeleton with a small procedure that manages fatal errors, by displaying an information message box and terminating the process. I think the code is pretty much self explanatory and I commented it to some degree, so there's not much to say. To close the black window just hit ESCAPE. The only one thing that isn't that quite right is the fact that you have to code the line numbers by hand and so if you change anything above previously coded numbers, you'll have to do them again... oh well! To assemble get the MASM32 package from: http://www.pbq.com.au/home/hutch/ --8<--------------------------------------------------------------------------- ; SKELETON.ASM ; Win32 AppFatalExit Skeleton ; by Chili for APJ #8 ; August 11, 2000 ;############################################################################## ; Compiler Options ;############################################################################## title Win32 AppFatalExit Skeleton .386 .model flat, stdcall ; 32-bit memory model option casemap :none ; case sensitive ;############################################################################## ; Includes ;############################################################################## ;// Include Files include \masm32\include\windows.inc include \masm32\include\gdi32.inc include \masm32\include\user32.inc include \masm32\include\kernel32.inc include \masm32\include\comctl32.inc include \masm32\include\comdlg32.inc include \masm32\include\shell32.inc ;// Libraries includelib \masm32\lib\gdi32.lib includelib \masm32\lib\user32.lib includelib \masm32\lib\kernel32.lib includelib \masm32\lib\comctl32.lib includelib \masm32\lib\comdlg32.lib includelib \masm32\lib\shell32.lib ;############################################################################## ; Equates ;############################################################################## ;// Basic NULL equ 0 FALSE equ 0 TRUE equ 1 ;############################################################################## ; Local Prototypes ;############################################################################## ;// Main Program Procedures. WinMain PROTO :DWORD, :DWORD, :DWORD, :DWORD WndProc PROTO :DWORD, :DWORD, :DWORD, :DWORD AppFatalExit PROTO :DWORD, :DWORD ;############################################################################## ; Local Macros ;############################################################################## ;// Return a value in EAX. return MACRO arg IFNB mov eax, arg ENDIF ret ENDM ;// Memory-to-memory MOV. m2m MACRO m1:REQ, m2:REQ push m2 pop m1 ENDM ;// Memory copy. mcopy MACRO destination:REQ, source:REQ cld lea esi, source lea edi, destination mov ecx, sizeof source rep movsb ENDM ;// Insert zero terminated string into code section. szText MACRO name:REQ, text:VARARG LOCAL lbl jmp lbl name db text, 0 lbl: ENDM ;// Insert zero terminated string into .data section. dszText MACRO name:REQ, text:VARARG .data name db text, 0 .code ENDM ;// Return in EBX the ASCII size of a DWORD value dwsize MACRO value:REQ xor ebx, ebx mov eax, value .if eax == 0 inc ebx .else mov ecx, 10 .while eax > 0 xor edx, edx div ecx inc ebx .endw .endif ENDM ;############################################################################## ; Initialized Data Section ;############################################################################## .data ;############################################################################## ; Uninitialized Data Section ;############################################################################## .data? ;############################################################################## ; Constants Section ;############################################################################## .const ;############################################################################## ; Code Section ;############################################################################## .code ;============================================================================== ; Beginning of executable code ;============================================================================== start proc ;// Do some base initialization for the WinMain function and upon its ;// ending, terminate process. LOCAL hModule :DWORD ;// Get handle to current instance. invoke GetModuleHandle, NULL .IF eax == NULL dszText szGetModuleHandle_157, "GetModuleHandle, ln #157" invoke AppFatalExit, addr szGetModuleHandle_157, sizeof szGetModuleHandle_157 .ENDIF mov hModule, eax ;// Get pointer to the command-line string for the current process. invoke GetCommandLine ;// Call initial entry point for a Win32-based application. invoke WinMain, hModule, NULL, eax, SW_SHOWMAXIMIZED ;// End process and all its threads. invoke ExitProcess, eax start endp ;============================================================================== ; WinMain Function (Called by the system as the initial entry point for a ; Win32-based application) ;============================================================================== WinMain proc hInstance :DWORD, ;// handle to current instance hPrevInstance :DWORD, ;// handle to previous instance lpCmdLine :DWORD, ;// pointer to command line nCmdShow :DWORD ;// show state of window ;// Perform initialization, create and display a main window and enter a ;// message retrieval-and-dispatch loop. LOCAL wc :WNDCLASSEX LOCAL hwndMain :DWORD LOCAL msg :MSG ;// Register the window class for the main window. mov wc.cbSize, sizeof WNDCLASSEX mov wc.style, CS_OWNDC mov wc.lpfnWndProc, offset MainWndProc mov wc.cbClsExtra, 0 mov wc.cbWndExtra, 0 m2m wc.hInstance, hInstance invoke LoadIcon, NULL, IDI_APPLICATION .if eax == NULL dszText szLoadIcon_203, "LoadIcon, ln #203" invoke AppFatalExit, addr szLoadIcon_203, sizeof szLoadIcon_203 .endif mov wc.hIcon, eax invoke LoadCursor, NULL, IDC_ARROW .if eax == NULL dszText szLoadCursor_209, "LoadCursor, ln #209" invoke AppFatalExit, addr szLoadCursor_209, sizeof szLoadCursor_209 .endif mov wc.hCursor, eax invoke GetStockObject, BLACK_BRUSH .if eax == NULL dszText szGetStockObject_215, "GetStockObject, ln #215" invoke AppFatalExit, addr szGetStockObject_215, sizeof szGetStockObject_215 .endif mov wc.hbrBackground, eax mov wc.lpszMenuName, NULL dszText szClassName, "MainWndClass" mov wc.lpszClassName, offset szClassName mov wc.hIconSm, NULL invoke RegisterClassEx, addr wc .if eax == 0 dszText szRegisterClassEx_227, "RegisterClassEx, ln #227" invoke AppFatalExit, addr szRegisterClassEx_227, sizeof szRegisterClassEx_227 .endif ;// Create the main window. dszText szDisplayName, "Win32 AppFatalExit Skeleton" invoke CreateWindowEx, NULL, addr szClassName, addr szDisplayName, WS_POPUP or WS_CLIPSIBLINGS or WS_MAXIMIZE or \ WS_CLIPCHILDREN, CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, NULL, NULL, hInstance, NULL ;// If the main window cannot be created, terminate the application. .if eax == NULL dszText szCreateWindowEx_237, "CreateWindowEx, ln #237" invoke AppFatalExit, addr szCreateWindowEx_237, sizeof szCreateWindowEx_237 .endif mov hwndMain, eax ;// Show the window and paint its contents. invoke ShowWindow, hwndMain, nCmdShow invoke UpdateWindow, hwndMain .if eax == NULL dszText szUpdateWindow_255, "UpdateWindow, ln #255" invoke AppFatalExit, addr szUpdateWindow_255, sizeof szUpdateWindow_255 .endif ;// Start the message loop. .while TRUE invoke PeekMessage, addr msg, NULL, 0, 0, PM_REMOVE .if (eax != 0) .break .if msg.message == WM_QUIT invoke TranslateMessage, addr msg invoke DispatchMessage, addr msg .endif .endw ;// Return the exit code to Windows. return msg.wParam WinMain endp ;============================================================================== ; WindowProc Function (Application-defined callback function that processes ; messages sent to a window) ;============================================================================== MainWndProc proc hwnd :DWORD, ;// handle of window uMsg :DWORD, ;// message identifier wParam :DWORD, ;// first message parameter lParam :DWORD ;// second message paramater ;// Dispatch the messages that can be received. .if uMsg == WM_KEYDOWN ;// Process keyboard input by means of a key press. .if wParam == VK_ESCAPE ;// Clean up window-specific data objects. invoke PostQuitMessage, NULL return 0 .endif .elseif uMsg == WM_DESTROY ;// Clean up window-specific data objects. invoke PostQuitMessage, NULL return 0 .endif ;// Process other messages. invoke DefWindowProc, hwnd, uMsg, wParam, lParam ret MainWndProc endp ;============================================================================== ; Application Fatal Exit Procedure ;============================================================================== AppFatalExit proc lpszCaption :DWORD, ;// pointer to string to display in \ ;// caption of the message box nSize :DWORD ;// size of caption ;// Display a message box and terminate. LOCAL uExitCode :DWORD LOCAL lpBuffer :DWORD LOCAL szFatalMessage [256]:BYTE LOCAL nSizeMsg :DWORD LOCAL szFatalCaption [64]:BYTE ;// Get the calling thread's last-error code value. invoke GetLastError mov uExitCode, eax ;// Obtain error message string. invoke FormatMessage, FORMAT_MESSAGE_ALLOCATE_BUFFER or \ FORMAT_MESSAGE_FROM_SYSTEM, NULL, uExitCode, 0, addr lpBuffer, 0, NULL .if eax == NULL dwsize uExitCode mov nSizeMsg, ebx invoke GetLastError push eax dwsize eax add nSizeMsg, ebx pop eax dszText szDoubleFmt, "#%lu [& #%lu]" invoke wsprintf, addr szFatalMessage, addr szDoubleFmt, uExitCode, eax add nSizeMsg, 7 .if eax != nSizeMsg dszText szDoubleMessage, "#??? [& #???]" mcopy szFatalMessage, szDoubleMessage .endif .else mov nSizeMsg, eax dwsize uExitCode add nSizeMsg, ebx dszText szFmt, "#%lu - %s" invoke wsprintf, addr szFatalMessage, addr szFmt, uExitCode, lpBuffer add nSizeMsg, 4 .if eax != nSizeMsg dszText szMessage, "#??? - ?????" mcopy szFatalMessage, szMessage .endif invoke LocalFree, lpBuffer ;// Possible errors in LocalFree ignored .endif ;// Display the application fatal exit message box. dszText szCaptionFmt, "Fatal: %s" invoke wsprintf, addr szFatalCaption, addr szCaptionFmt, lpszCaption add nSize, 6 .if eax != nSize dszText szCaption, "Fatal: ?????, ln #???" mcopy szFatalCaption, szCaption .endif invoke MessageBox, NULL, addr szFatalMessage, addr szFatalCaption, MB_ICONHAND or MB_SYSTEMMODAL ;// End process and all its threads. invoke ExitProcess, eax AppFatalExit endp end start ---------------------------------------------------------------------------8<-- ::/ \::::::. :/___\:::::::. /| \::::::::. :| _/\:::::::::. :| _|\ \::::::::::. :::\_____\:::::::::::............................................THE.UNIX.WORLD System Calls in FreeBSD by G. Adam Stanislav Assembly language programing under Unix is highly undocumented. It is generally assumed that no one would ever want to use it because various Unix systems run on different microprocessors, so everything should be written in C for portability. Now, we know that C portability is a myth. Even C programs need to be modified when ported from one Unix to another, regardless of what processor each runs on. I was pleasantly surprised when one of FreeBSD hackers recently posted an assembly language 'Hello, World' program on the web. See http://home.ptd.net/~tms2/hello.html for what he has to say. There were two things I did not like in his example: First of all, he uses the GNU assembler with its AT&T syntax. Talk about lack of portability! Ever since I got involved in Unix programming, I switched from MASM to NASM and never looked back. NASM allows me to use the same code for Windows and Unix with only minor modifications needed wherever system calls are necessary. Everything else remains the same. I also like the fact I can use dots in the middle of a label. Secondly, he uses a separate procedure for the system call. It looks like this (in AT&T syntax): do_syscall: int $0x80 # Call kernel. ret He says a direct use of int 80h would not work. I refused to believe it. And I was right. The "problem" he is solving by using a separate procedure is the fact that int 80h is optimized for the use with C programs which make calls to functions like write() and read(). Because they make a call, an extra DWORD is pushed on the stack before invoking int 80h. His solution works, of course, but is unnecessary. All that is needed is pushing an extra DWORD before invoking int 80h. The value pushed is irrelevant. In my modification to his code, I simply pushed EAX and invoked int 80h. Then I added an extra four bytes to ESP. I already had to increase it anyway because int 80h uses C calling convention of receiving parameters on the stack and leaving them there. It worked without a hitch. I learned from his code that the value in EAX determines which system call int 80h makes. A list of these can be found in the C include file . I then decided to experiment with his code a bit further, and create something that actually does some work. A typical Unix program is a filter which reads its input from stdin, writes its output to stdout, and sends error messages to stderr. I decided to produce such a filter for this article. Because I used tabs in my source code and needed to convert them to spaces for this article, I made the filter convert tabs to spaces. Because I started writing it under Windows and finished it under Unix, I also made the filter strip any carriage returns. It would be more useful if it could accept command line parameters, so you could decide how many spaces a tab should expand to. Alas, I have no idea where to find the command line under FreeBSD. If you know, please email me at adam@whizkidtech.net. For now, the program simply assumes a tab stop is at every 8th position. The program uses ESI as a counter of where on the line it is. To calculate the number of blanks to insert, it moves ESI to EAX, negates EAX, ands it with seven, and adds 1. This works very well. Suppose you are at the beginning of the line, i.e., at the first position. So, you turn 1 into -1, i.e., 0FFFFFFFFh. And it with 7, you get 7. Increase that, and you know you need to write 8 spaces. I also used EDI as the pointer to the read/write buffer. I could have just pushed its offset (push dword buffer) every time, but pushing a register produces less code and is probably faster. I chose ESI and EDI to hold persistent values (i.e., values that need to survive the system call) because Unix system software uses the C convention of preserving these two registers (as well as EBX and EBP). In my first version I started the program with a PUSHAD and ended it a POPAD. This is certainly needed in Windows programs: An assembly language program will crash Windows if it returns to Windows with any of the four aforementioned registers modified. Then I thought that surely FreeBSD would not allow such a serious security hole in the system. I removed the PUSHAD and the POPAD, and the program worked without a hitch. The result is below. ;--------------------------------------------------------------------------- ; File: tab2sp.asm ; ; A sample assembly language program for FreeBSD. ; It converts tabs to spaces. Nothing new, expand ; already does that and with more options. ; ; But it illustrates reading from stdin, and writing ; to stdout and stderr in assembly language. ; ; 05-May-2000 ; Copyright 2000 G. Adam Stanislav ; All rights reserved ; ; http://www.whizkidtech.net/ ; http://www.redprince.net/ ; ; Assemble with nasm: ; ; nasm -f tab2sp.asm ; ld -o tab2sp tab2sp.o section .data buffer times 8 db ' ' errread db 'TAB2SP: Error reading input', 0Ah erlen equ $-errread align 4, db 0 errwrite db 'TAB2SP: Error writing output', 0Ah ewlen equ $-errwrite section .code ; ld expects every program to start with _start global _start _start: ; We use EDI and ESI to store persistent data ; because syscall will not modify them. mov edi, buffer ; EDI = address of buffer sub esi, esi ; ESI = counter ; NOTE: ; ; Because int 80h expects to be within a separate ; procedure, we need to push a fake return address ; before invoking it. It can be anything, so we ; just push EAX. .read: sub eax, eax inc al push eax ; size of "string" push edi ; address of buffer dec al push eax ; stdin = 0 push eax ; "return address" mov al, 3 ; SYS_read int 80h ; syscall add esp, byte 16 ; clean the stack after reading or eax, eax je .quit ; end of file reached js .rerror ; read error... ; Decide what to do: ; ; If the byte is a carriage return, ignore it. ; If the byte is a newline, initialize ESI = 0. ; If the byte is a tab, convert it to spaces. ; Otherwise, just write it. mov dl, [edi] cmp dl, 0Dh ; carriage return je .read cmp dl, 0Ah ; new line je .newline inc esi cmp dl, 09h ; tab jne .write ; It's a tab. Expand it. mov byte [edi], ' ' mov eax, esi neg eax and eax, 7 add esi, eax inc eax jmp short .write .newline: sub esi, esi .write: push eax ; size of "string" push edi ; address of buffer sub eax, eax inc al push eax ; stdout = 1 push eax ; "return address" mov al, 4 ; SYS_write int 80h ; system call add esp, byte 16 or eax, eax jns short .read push dword ewlen push dword errwrite jmp short .err .rerror: push dword erlen push dword errread .err: sub eax, eax mov al, 2 ; stderr = 2 push eax push eax ; "return address" add al, al ; SYS_write int 80h add esp, byte 16 .quit: sub eax, eax ; EAX = 0 push eax ; exit status inc eax ; SYS_exit push eax ; "return address" int 80h ; Program ends here. ;-------------------------------------------------------------------------- ::/ \::::::. :/___\:::::::. /| \::::::::. :| _/\:::::::::. :| _|\ \::::::::::. :::\_____\:::::::::::............................................THE.UNIX.WORLD Loadable Kernel Modules by mammon_ If there is one area in linux that is sure to attract assembly language coders, it is the coding of loadable kernel modules; after all, asm programmers aren't known for waiting around in Ring 3 space waiting for the CPU to assign their process some resources. Kernel modules are Ring 0 programs that are dynamically linked into a running kernel; they require LKM support in the kernel [ CONFIG_MODULES ]. Each kernel ships with a given number of kernel modules, as most device drivers are compiled as such; the modules are located in /lib/modules/kernel_version#. Modules are managed with the commands insmod [load module], modprobe [load module and all modules it depends on], lsmod [list loaded modules], and rmmod [unload module]; information on loaded modules can also be obtained from the /proc file system, e.g. /proc/modules. Kernel Land ----------- It need hardly be said that kernel-space programming is different from user-space progamming. For starters, simple bugs can panic the kernel, or render kernel subsystems unreliable if not actually inoperable. It is advisable, when developing kernel modules, to become well-acquainted with the "Magic SysReq Key" commands. There is no main function. Kernel modules must export the init_module and cleanup_module routines; these will be called by the kernel when the module is loaded and unloaded. The rest of the kernel module will generally consist of callback routines which are executed in response to system events [i.e. ioctl() calls, reading of /proc files, syscalls, interrupts]. The standard C libraries are also unavailable -- they are far away, in the user-space shared by all normal, well-behaved programs. The only external routines that a kernel module can call are those listed in the kernel symbol table [which can be browsed via /proc/ksyms] and the INT 80 syscalls. Some basic C-style routines are provided by the kernel, and are prototyped in $INCLUDE/linux/kernel.h: simple_strtol(const char *,char **,unsigned int); sprintf(char * buf, const char * fmt, ...); vsprintf(char *buf, const char *, va_list); get_option(char **str, int *pint); memparse(char *ptr, char **retptr); printk(const char * fmt, ...) Note that the standard kernel routines are documented in section 9 of the manual, and can be browsed with ls -1 /usr/man/man9 | cut -d. -f1 As mentioned in a previous article, the syscalls are listed in /usr/include/asm/unistd.h . Finally, accessing user-space memory is not easy. In C, there are macros provided for this -- get_user(), put_user(), copy_from_user(), copy_to_user() ... all defined in $INCLUDE/asm/uaccess.h -- and these boil down to inline assembler routines that can be accessed, somewhat awkwardly, from routines listed in the kernel symbol table [e.g. __get_user_1 and so on]. In general, it is best to leave user/kernel-space interaction to /proc and /dev files. Developing Kernel Modules ------------------------- What does all of this mean in terms of assembly language? Essentially, asm kernel modules will have the same problems as C kernel modules, with the added bonus that none of the C macros for kernel-mode programming will work. When programming kernel modules, one is more or less restricted to using the GAS assembler. NASM can be made to work, but by default it produces object files in format that the kernel module loader cannot recognize [note: RedPlait has produced a patch for NASM to fix this; in addition, it is possible to write a libBFD post-processor which will re-assemble the sections in the appropriate order]. Information on GAS invocation and syntax can be obtained from the 'as' manpage and info file, and the GAS preprocessor is documented in the 'gasp' info page. Note that the info files can be accessed randomly by appending the sequence of menu selections to the command; thus info as Machine i386 i386-Syntax would load the 'as' info section for i386 syntax details. Kernel modules are unlinked object files -- they are linked to the kernel dynamically, and so should not be run through ld. Using gcc, a kernel module can be compiled with gcc -c filename assuming that the file extension is .s or .S . Gcc will produce a .o output file which may be loaded using 'insmod' and unloaded using 'rmmod'. The compilation/test cycle for a linux kernel module is essentially gcc -c asm_module.s insmod asm_module lsmod rmmod asm_module Note that modules which cannot be initialized or unloaded will remain loaded until reboot, thus preventing another module with the same name from being loaded. In order to minimize reboots, it helps to symlink a number of 'test' filenames to the original object file, so that 'asm_module.o' would be linked to 'asm_module1.o', 'asm_module2.o', and so on. Debugging kernel modules can be quite a chore. While kernel-mode debuggers exist for linux, it is often more expedient to use primitive "printf" debugging techniques and core file analysis. In the former case, the linux kernel provides the function "printk()", which is the kernel-mode equivalent of printf(); the one notable difference is that the format string should begin with a 'priority code' indicating how syslogs should handle the message. The priority codes are: <0> Kernel Emergency <1> Kernel Alert <2> Kernel Critical Condition <3> Kernel Error <4> Kernel Warning <5> Kernel Notice <6> Kernel Info <7> Kernel Debug In addition, when a kernel module 'crashes', it writes an 'oops' file to STDERR. This is essentially a stripped-down core file giving the registers and stack state at the moment of the crash; it can be saved to a file and loaded with the ksymoops utility to make the report more coherent. One of the best tools for debugging assembly language kernel modules is gcc itself. If the module --or the problematic portion thereof-- can be written correctly in C, a GAS version can be produced by compiling the module with gcc -S filename This will produce an assembly-language version of the program, loaded with GAS preprocessor directives. This file can be cleaned up and compared against the hand-tooled assembly language version in order to judge the effects of C macros, data alignment, and sections. Hello Kernel ------------ As usual, it is best to start with the most simple module possible in order to demonstrate the absolute basics of LKM programming. Other than the use of init and cleanup functions, this module should not present any surprises: #---------------------------------------------------------------------Asm_mod.s .globl init_module .globl cleanup_module .extern printk .text .align 4 init_module: pushl $strLoad call printk popl %eax xor %eax, %eax ret cleanup_module: pushl $strUnload call printk popl %eax xorl %eax, %eax ret .section .rodata .align 32 strLoad: .ascii "<1> Asm Module Loaded!\n\0" strUnload: .ascii "<1> Asm Module Unloaded\n\0" .section .modinfo __module_lernel_version: .ascii "kernel_version=2.2.15\0" #---------------------------------------------------------------------------EOF As you can see, this program does nothing special -- it simply outputs an alert when the module is loaded or unloaded. Note the .modinfo section of the program; this is where the module specifies which kernel it was compiled for. In C, a macro determines this based on a constant in the kernel header files; in assembly, you will have to specify the kernel version by hand or with a Makefile. Also note the .rodata section -- this is where the kernel expects to find string references, and one can expect a lot of segmentation faults if the strings are placed in .data instead. Using the /proc Filesystem -------------------------- The trend in linux, as well as in other Unixes, is to provide runtime access to kernel-space data through the /proc file system. Linux system tweakers will no doubt be familiar with cat'ing /proc files to check the status of kernel variables, and echo'ing values to those files in order to change the values of such variables. The /proc filesystem is a handy mechanism for interfacing with kernel modules without the relative complexity of a device file and an ioctl() interface. Creating an entry in the /proc file system consists of the following steps: 1. Prepare a proc_dir_entry struct to describe the /proc file 2. Register the /proc file to create it 3. Unregister the /proc file when finished with it The most important component of this process is obviously the proc_dir_entry structure; it is define in $INCLUDE/linux/proc_fs.h: struct proc_dir_entry { unsigned short low_ino; //inode # of the /proc file unsigned short namelen; //length of filename const char *name; //pointer to filename string mode_t mode; //Access mode [permissions] nlink_t nlink; //# of links to the file uid_t uid; //UID of file owner gid_t gid; //GID of file owner unsigned long size; //Size of the file struct inode_operations * proc_iops; struct file_operations * proc_fops; get_info_t *get_info; //Function handling file reads struct module *owner; struct proc_dir_entry *next, *parent, *subdir; void *data; //pointer to 'user-defined' data read_proc_t *read_proc; write_proc_t *write_proc; unsigned int count; /* use count */ int deleted; /* delete flag */ kdev_t rdev; }; The last 5 members of the structure are not defined in the proc_dir_entry man page, and do not appear to be used; however, as demonstrated in the sample code, space must be reserved for them. In most cases, the majority of these structure members cal be set to NULL in order to have them filled with default values. The members that should normally be set to null include low_ino, uid, gid, size, *proc_iops, *proc_fops, *owner, *next, *parent, *subdir, and *data. This leaves the following members to be filled by the program: namelen -- length of *name string, without the terminating \0 *name -- .rodata string containing the name of the /proc file mode -- access permissions for the file nlink -- 1 for normal files, 2 for directories *getinfo -- callback routine for reads to the /proc file Note that *getinfo() is called for normal /proc file reads, e.g. `cat \proc\modules`. In order to handle more advanced operations such as writes, links, and so forth, an inodes_operations and a file_operations structure need to set up. The *getinfo() function has the following prototype: int get_info(char *buffer, char **retBuf, off_t pos, int size); where buffer is the buffer provided by the user-space program, size is the size of that buffer, pos is the current position in the file [to support multiple, sequential reads by the user-space program], and retBuf is a pointer to a buffer which can be used in place of the supplied buffer [for example, if size is too small]. When a return buffer is used, a pointer to the buffer is stored in retBuf, and the size of the buffer is returned in eax. It is important to use stack frames in all kernel-mode callbacks. The prototype for a get_info function in GAS would be .globl get_info get_info: pushl %ebp movl %esp,%ebp .... movl %eax,20(%ebp) leave ret The parameters will all be at offsets of %ebp, as the default return value [an invisible fifth parameter that is always zero] demonstrates. Registering and unregistering a proc file are fairly straightforward. The proc_register command has the prototype proc_register(proc_dir_entry *parent, proc_dir_entry *child) and always returns 0. The *parent structure must refer to a directory within the /proc tree; the global symbols proc_root and proc_sys_root refer to the directories /proc and /proc/sys, respectively. The child structure refers to the /proc entry that is being created. The proc_unregister command has the prototype proc_unregister(proc_dir_entry * parent, int inode); and returns 0 only on success. The parent node will be the same as in the proc_register call, while inode refers to the inode assigned to the /proc file being unregistered. Note that the inode of a /proc file is specified in the first member of the proc_dir_entry structure; if the inode member is 0 on /proc file registration, an inode number is dynamically assigned and stored in the inode member. Hello Proc ---------- The following program will demonstrate the use of the get_info() function; it creates a /proc file which, when read, will return a simple string in the buffer provided by the user-space program. #--------------------------------------------------------------------Asm_proc.s .globl init_module .globl cleanup_module .globl ReadAsmProcFile .globl procAsm .extern printk .extern sprintf .extern proc_root .extern proc_register .extern proc_unregister .text .align 4 init_module: pushl %ebp movl %esp,%ebp pushl $strLoad call printk popl %eax pushl $procAsm pushl $proc_root call proc_register addl $0x8, %esp xorl %eax, %eax leave ret cleanup_module: pushl %ebp movl %esp,%ebp pushl $strUnload call printk popl %eax movzwl procAsm, %eax pushl %eax pushl $proc_root call proc_unregister addl $0x8, %esp xorl %eax, %eax leave ret ReadAsmProcFile: pushl %ebp movl %esp,%ebp pushl $strRead movl 8(%ebp),%eax pushl %eax call sprintf addl $16,%esp movl %eax,20(%ebp) leave ret .section .modinfo __module_kernel_version: .ascii "kernel_version=2.2.15\0" .section .rodata .align 32 strName: .ascii "AsmModule\0" strLoad: .ascii "<1> Asm Module Loaded!\n\0" strUnload: .ascii "<1> Asm Module Unloaded\n\0" strRead: .ascii "This /proc file has nothing to say\n\0" .data .align 32 #______________________File_Permissions .equ S_IFREG, 0100000 .equ S_IRUSR, 00400 .equ S_IWUSR, 00200 .equ S_IXUSR, 00100 .equ S_IRGRP, 00040 .equ S_IWGRP, 00020 .equ S_IXGRP, 00010 .equ S_IROTH, 00004 .equ S_IWOTH, 00002 .equ S_IXOTH, 00001 #________________________________________proc_dir_entry structure procAsm: procAsm_low_ino: .short 0 procAsm_name_length: .short 9 procAsm_name: .long strName procAsm_mode: .short S_IFREG | S_IRUSR |S_IRGRP | S_IROTH procAsm_nlinks: .short 1 procAsm_owner: .short 0 procAsm_group: .short 0 procAsm_size: .long 0 procAsm_operations: .long 0 procAsm_read_proc: .long ReadAsmProcFile .zero 40 #________________________________________end proc_dir_entry #---------------------------------------------------------------------------EOF The /proc file can be read with the usual `cat /proc/AsmModule` commands. It should be noted that get_info() is executed when the file is opened; this allows different behavior to be supplied for file opens, reads, and writes. Further Reading --------------- Programming Linux kernel modules, either in assembly or in C, is a complicated and challenging field. The following online resources provide vital information on kernel module programming. "Linux Kernel Module Programming Guide", by Ori Pomerantz http://www.linuxdoc.org/LDP/lkmpg/mpg.html The 'classic' guide to LKM programming. This work is part of the Linux documentation project, and is available in most Linux distributions. Most LKM texts will assume you are familiar with the concepts presented in this one. "(nearly) Complete Linux Loadable Kernel Modules", by pragmatic / THC http://thc.pimmel.com/files/thc/LKM_HACKING.html Based on the exploratory LKM hacking essays of Phrack 50 and 52, this treatise on LKM hacking is very thorough and very informative. The text contains an introduction to LKM programming and proceeds to cover kernel modules from the security and hacking viewpoints, with plenty of source code to back up the discussion. If you read or print out only one LKM guide, this should be it. "Linux Kernel Hacker Documentation" http://jungla.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html This page contains links to a number of articles and books on Linux kernel-mode programming. ::/ \::::::. :/___\:::::::. /| \::::::::. :| _/\:::::::::. :| _|\ \::::::::::. :::\_____\:::::::::::.............................................GAMING.CORNER Win32 ASM Game Programming - Part 1 by Chris Hobbs [This series of articles was first posted at GameDev.net and is now being published here with the author's permission. Here is Chris Hobbs' introduction on this particular article: "A tutorial series on the development of a complete game, SPACE-TRIS, in pure ASM. This one covers the design document, code framework, and some Win32 ASM basics." Visit his website at http://www.fastsoftware.com. Preface, Html-to-Txt conversion and formating by Chili ] This is the article that I am sure all of you have been waiting ever so patiently for ... a complete series on the development of a game, in pure Assembly Language of all things. I know all of you are as excited about this article as I am, so I will try and keep this introduction brief. Instead of laying every single thing out to you in black and white, I will try and answer a few questions that are asked most often, and the details will appear as we progress ( I am making this up as I go you know ). What is this article about? --------------------------- This article is actually part of a seven article series on the development of a complete game, SPACE-TRIS, in 100% assembly language. We will be covering any aspect of game development that I can think of ... from design and code framework to graphics and sound. Who is this article for? ------------------------ This series is meant for anybody who wishes to learn something that they may not have known before. Since the game is a relatively simple Tetris clone it is great for the beginner. Also, given the fact that not many people are even aware that it is completely possible to write for Windows in assembly language, it is great for the more advanced developers out there too. What do I need? --------------- The only requirement is the ability to read. However, if you wish to assemble the source code, or participate in the challenge at the end of the article series, you need a copy of MASM 6.12+. You can download a package called MASM32 that will have everything that you need, and then some. Here is the link: http://www.pbq.com.au/home/hutch/. Why Assembly Language? ---------------------- Many of you are probably wondering why anybody in their right mind would write in pure assembly language. Especially in the present, when optimizing compilers are the "in" thing and everybody knows that VC++ is bug free, right? Okay I think I answered that argument ... but what about assembly language being hard to read, non-portable, and extremely difficult to learn. In the days of DOS these arguments were very valid ones. In Windows though, they are simply myths left over from the good old days of DOS. I might as well approach these one at a time. First, assembly language is hard to read. But for that matter so is C, or even VB. The readability results from the skill of the programmer and his/her thoroughness at commenting the code. This is especially true of C++. Which is easier to read: Assembly code which progress one step at a time ( e.g. move variable into a register, move a different variable into another register, multiply ), or C++ code which can go through multiple layers of Virtual Functions that were inherited? No matter what language you are in, commenting is essential ... use it and you won't have any troubles reading source code. Remember just because you know what it means doesn't mean that everybody else does also. Second, the issue of portability. Granted assembly language is not portable to other platforms. There is a way around this, which allows you to write for any x86 platform, but that is way beyond the scope of this article series. A good 80-90% of the games written are for Windows. This means that the majority of your code is specific to DirectX or the Win32 API, therefore ... you won't be porting without a huge amount of work anyway. So, if you want a truly portable game, then don't bother with writing for DirectX at all ... go get a multi-platform development library. Finally, there comes the issue of Assembly Language being extremely difficult to learn. Although there is no real way for me to prove to you that it is easy, I can offer you the basics, in a few pages, which have helped many people, who never saw a line of assembly language before, learn it. Writing Windows assembly code, especially with MASM, is very easy. It is almost like writing some C code. Give it a chance and I am certain that you won't be disappointed. Win32 ASM Basics ---------------- If you are already familiar with assembly language in the windows platform, you may want to skip this section. For those of you who aren't, this may be a bit boring, but hang with it ... this is very important stuff. For this discussion I will presume that you are at least familiar with the x86 architecture. The first thing you need to understand are the instructions. There aren't very many that you will be using often so I will simply cover the ones that we care about. MOV --- This instruction moves a value from one location to another. You can only move from a register to register, memory to register, or register to memory. You can not move from a memory location to another memory location. Example: MOV EAX, 30 MOV EBX, EAX MOV my_var1, EAX MOV DWORD PTR my_var, EAX The first example moves the value 30 into the EAX register. The second example moves the value in EAX into the EBX register. The third example moves the value of EAX into the variable my_var1. The fourth example moves the value of EAX into the ADDRESS pointed to by my_var, we need to use the DWORD specifier so that the assembler knows how much memory to move -- 1 byte ( BYTE ), 2 bytes ( WORD ), or 4 bytes ( DWORD ). ADD & SUB --------- These two instructions perform addition and subtraction. Example: ADD EAX, 30 SUB EBX, EAX The examples simply add 30 to the EAX register and then subtract that value from the EBX register. MUL & DIV --------- These two instructions perform multiplication and division. Example: MOV EAX, 10 MOV ECX, 30 MUL ECX XOR EDX, EDX MOV ECX, 10 DIV ECX The examples above first load EAX with 10 and ECX with 30. EAX is always the default multiplicand, and you get to select the other multiplier. When performing a multiplication the answer is in EAX:EDX. It only goes into EDX if the value is larger than the EAX register. When performing a divide you must first clear the EDX register that is what the XOR instruction does by performing an Exclusive OR on itself. After the divide, the answer is in EAX, with the remainder in EDX, if any exists. Of course, there are many more instructions, but those should be enough to get you started. We will probably only be using a few others, but they fairly easy to figure out once you have seen the main ones. Now we need to deal with the calling convention. We will be using the Standard Call calling convention since that is what the Win32 API uses. What this means is that we push parameters onto the stack in right to left order, but we aren't responsible for the clearing the stack afterwards. Everything will be completely transparent to you however as we will be using the pseudo-op INVOKE to make our calls. Next, there is the issue of calling Windows functions. In order to use invoke, you must have a function prototype. There is a program that comes with MASM32 which builds include files ( equivalent to header files in C ) out of the VC++ libraries. Then, you include the needed libraries in your code and you are free to make calls as you wish. You do have to build a special include file by hand for access to Win32 structures and constants. However, this too is included in the MASM32 package, and I have even put together a special one for game programmers which will be included in the source code and built upon as needed. The final thing that I need to inform you about is the high level syntax that MASM provides. These are constructs that allow you to create If-Then-Else and For loops in assembly with C-like expressions. They are easiest to show once we have some code to put in, therefore you won't see them until next time. But, they are there ... and they make life 100000 times easier than without them. That is really about all you need to know. The rest will come together as we take a look at the source code and such. So, now that we have that out of the way, we can work on designing the game and creating a code framework for it. The Design Document ------------------- Time for something a lot more fun ... designing the game. This is a process that is often neglected simply because people want to start writing code as soon as they have an idea. Although this approach can work for some people, it often does not. Or, if it does work, you end up re-coding a good portion of your game because of a simple oversight. So, we will cover exactly how to create a design document that you will be able to stick to, and will end up helping you with your game. First, you need to have an idea of what you want the game to be, and how you want the game play. In our case this is a simple Tetris clone so there isn't too much we need to cover in the way of game play and such. In many cases though, you will need to describe the game play as thoroughly as possible. This will help you see if your ideas are feasible, or if you are neglecting something. The easy part is finished, now we need to come up with as many details as we possibly can. Are we going to have a scoring system? Are we going to have load/save game options? How many levels are there? What happens at the end of a level? Is there an introductory screen? These are the kinds of questions that you should be asking yourself as you work on the design of the game. Another thing that may help you is to story board or flow chart the game on a piece of paper or your computer. This will allow you to see how the game is going to progress at each point. Once you have all of the details complete, it is time to start sketching the levels out. How do you want the screens to appear? What will the interfaces look like? This doesn't have to be precise just yet ... but it should give you a realistic idea of what the final versions will look like. I tend to break out my calculator and estimate positions at this point also. I have actually ran out of room while creating the menu screen before. This was my own fault for not calculating the largest size my text could be and it took a few hours to re-do everything. Don't make the same mistake, plan ahead. The final stage is just sort of a clean-up phase. I like to go back and make sure that everything is the way I want it to be. Take a few days break from your game beforehand. This will give you a fresh viewpoint when you come back to it later on. Often times, you will stare at the document for so long that something extraordinarily simple will be glanced over and not included in your plan -- for instance, how many points everything is worth and the maximum number of points they can get ( Not that I have ever found out halfway through the game that the player could obtain more points than the maximum score allowed for, or anything like that ). Whether you choose to use the process I have outlined, or one of your own making, it is imperative that you complete this step. I have never been one for wasted effort -- I do it right the first time if possible, and learn from my mistakes, as well as the mistakes of others. If this weren't necessary I wouldn't do it. So, do yourself a favor and complete a design document no matter how simple you think your game is. The final preparation step is something that I like to call code framework. This is where you lay out your blank source code modules and fill them with comments detailing the routines that will go into them and the basic idea behind how they operate. If you think you are perfect and have gotten every detail in your design document then you can probably skip this step. But, for those of you like me, who are cautious, then give this phase a whirl. It helps you see how all of the pieces will fit together and more importantly if something has been neglected or included that shouldn't have been. Here is an example of the framework that I am speaking about from SPACE-TRIS. You can see that nothing much goes into it ... just an overview of the module more or less. ;########################################################################### ; ABOUT SPACE-TRIS: ; ; This is the main portion of code. It has WinMain and performs all ; of the management for the game. ; ; - WinMain() ; - WndProc() ; - Main_Loop() ; - Game_Init() ; - Game_Main() ; - Game_Shutdown() ; ; ;########################################################################### ;########################################################################### ; THE COMPILER OPTIONS ;########################################################################### .386 .MODEL flat, stdcall OPTION CASEMAP :none ; case sensitive ;########################################################################### ; THE INCLUDES SECTION ;########################################################################### ;================================================== ; This is the include file for the Windows structs, ; unions, and constants ;================================================== INCLUDE Includes\Windows.inc ;================================================ ; These are the Include files for Window calls ;================================================ INCLUDE \masm32\include\comctl32.inc INCLUDE \masm32\include\comdlg32.inc INCLUDE \masm32\include\shell32.inc INCLUDE \masm32\include\user32.inc INCLUDE \masm32\include\kernel32.inc INCLUDE \masm32\include\gdi32.inc ;==================================== ; The Direct Draw include file ;==================================== INCLUDE Includes\DDraw.inc ;=============================================== ; The Lib's for those included files ;================================================ INCLUDELIB \masm32\lib\comctl32.lib INCLUDELIB \masm32\lib\comdlg32.lib INCLUDELIB \masm32\lib\shell32.lib INCLUDELIB \masm32\lib\gdi32.lib INCLUDELIB \masm32\lib\user32.lib INCLUDELIB \masm32\lib\kernel32.lib ;================================================= ; Include the file that has our prototypes ;================================================= INCLUDE Protos.inc ;########################################################################### ; LOCAL MACROS ;########################################################################### szText MACRO Name, Text:VARARG LOCAL lbl JMP lbl Name DB Text,0 lbl: ENDM m2m MACRO M1, M2 PUSH M2 POP M1 ENDM return MACRO arg MOV EAX, arg RET ENDM RGB MACRO red, green, blue XOR EAX,EAX MOV AH,blue SHL EAX,8 MOV AH,green MOV AL,red ENDM hWrite MACRO handle, buffer, size MOV EDI, handle ADD EDI, Dest_index MOV ECX, 0 MOV CX, size ADD Dest_index, ECX MOV ESI, buffer movsb ENDM hRead MACRO handle, buffer, size MOV EDI, handle ADD EDI, Spot MOV ECX, 0 MOV CX, size ADD Spot, ECX MOV ESI, buffer movsb ENDM ;############################################################################## ; Variables we want to use in other modules ;############################################################################## ;############################################################################## ; External variables ;############################################################################## ;############################################################################## ; BEGIN INITIALIZED DATA ;############################################################################## .DATA ;############################################################################## ; BEGIN CONSTANTS ;############################################################################## ;############################################################################## ; BEGIN EQUATES ;############################################################################## ;================= ;Utility Equates ;================= FALSE EQU 0 TRUE EQU 1 ;############################################################################## ; BEGIN THE CODE SECTION ;############################################################################## .CODE start: ;######################################################################## ; WinMain Function ;######################################################################## ;######################################################################## ; End of WinMain Procedure ;######################################################################## ;######################################################################## ; Main Window Callback Procedure -- WndProc ;######################################################################## ;######################################################################## ; End of Main Windows Callback Procedure ;######################################################################## ;======================================================================== ; THE GAME PROCEDURES ;======================================================================== ;######################################################################## ; Game_Init Procedure ;######################################################################## ;######################################################################## ; END Game_Init ;######################################################################## ;######################################################################## ; Game_Main Procedure ;######################################################################## ;######################################################################## ; END Game_Main ;######################################################################## ;######################################################################## ; Game_Shutdown Procedure ;######################################################################## ;######################################################################## ; END Game_Shutdown ;######################################################################## ;###################################### ; THIS IS THE END OF THE PROGRAM CODE # ;###################################### END start Well, this is the end of the first article. The good news is all of the dry boring stuff is behind us. The bad news is you won't get to see any code until I complete the next article. In the meantime I would suggest brushing up on your assembly language and maybe searching on the Internet for some references on Win32 assembly language. You can find links to a lot of Win32 ASM resources at my website: http://www.fastsoftware.com. Researching more information isn't a must ... but for those of you that still think this might be difficult, I would suggest taking the time to do so. It isn't like you will be hindered by learning more. You may find another resource that helps you learn this stuff and that is ALWAYS a good thing. In the next article we will get a skeleton version of SPACE-TRIS up and running along with coding our Direct Draw library functions. The goal is to get a bitmap up onto the screen and I think we can accomplish it next time. If everything goes as planned, you should see the work starting to pay off in a loading game screen. I know it doesn't sound like much ... but appreciate how slowly we are progressing before we get further along. Because once we have the basics down, we are going to pull out all of the stops and then you will be thankful we took the extra time to cover this stuff. So young grasshoppers, until next time ... happy coding. ::/ \::::::. :/___\:::::::. /| \::::::::. :| _/\:::::::::. :| _|\ \::::::::::. :::\_____\:::::::::::................................ASSEMBLY.LANGUAGE.SNIPPETS SEH.INC by X-Calibre ;Summary: Macros for Structured Exception Handling ;Compatibility: MASM, Win32 ;Notes: Demonstration code contained in SEH.ASM, below IFNDEF RaiseException RaiseException PROTO STDCALL dwExceptionCode:DWORD, dwExceptionFlags:DWORD , nNumberOfArguments:DWORD, lpArguments:PTR DWORD ENDIF includelib kernel32.lib TRY MACRO PUSHCONTEXT ASSUMES assume fs:nothing ; Install exception handler push @@handler push dword ptr fs:[0] mov fs:[0], esp POPCONTEXT ASSUMES ENDM CATCH MACRO exception LOCAL @@invokeHandler jmp @@removeHandler @@handler: IFNB mov eax, [esp+4] cmp dword ptr [eax], exception je @@invokeHandler mov eax, 1 ret @@invokeHandler: ENDIF ENDM ENDC MACRO PUSHCONTEXT ASSUMES assume fs:nothing ; Restore state mov esp, dword ptr fs:[0] mov esp, [esp] @@removeHandler: pop fs:[0] add esp, 4 POPCONTEXT ASSUMES ENDM FINALLY MACRO @@handler: ENDM ENDF MACRO LOCAL @@removeHandler PUSHCONTEXT ASSUMES assume fs:nothing ; Restore state cmp esp, dword ptr fs:[0] je @@removeHandler mov esp, dword ptr fs:[0] mov esp, [esp] @@removeHandler: pop fs:[0] add esp, 4 POPCONTEXT ASSUMES ENDM THROW MACRO exception INVOKE RaiseException, exception, 0, 0, NULL ENDM ; ---- flags --- EXCEPTION_INT_DIVIDE_BY_ZERO equ 0C0000094h SEH.ASM by X-Calibre ;Summary: Sample program for using SEH.INC ;Compatibility: MASM, Win32 .386 .Model Flat, StdCall include windows.inc include user32.inc include SEH.inc includelib user32.lib .code tst PROC THROW 0E0000001h ret tst ENDP start: main PROC TRY sub edx, edx mov ecx, 0 idiv ecx CATCH(EXCEPTION_INT_DIVIDE_BY_ZERO) .data exceptionMsg BYTE "Exception occured",0 .code INVOKE MessageBox, NULL, ADDR exceptionMsg, ADDR exceptionMsg, MB_OK ENDC main ENDP blah PROC TRY call tst FINALLY .data finallyMsg BYTE "In FINALLY-block",0 .code INVOKE MessageBox, NULL, ADDR finallyMsg, ADDR finallyMsg, MB_OK ENDF blah ENDP .data finishMsg BYTE "Program finished",0 .code INVOKE MessageBox, NULL, ADDR finishMsg, ADDR finishMsg, MB_OK ret end start ::/ \::::::. :/___\:::::::. /| \::::::::. :| _/\:::::::::. :| _|\ \::::::::::. :::\_____\:::::::::::...........................................ISSUE.CHALLENGE by Angel Tsankov Challenge --------- Write as short as possible program to convert a two-digit BCD to hexadecimal; that is, the decimal representation of the output must represent the hexadecimal representation of the input. Solution -------- The solution, in 14 bytes: ;Input AL = (A * 16) + B ;Output AL = (A * 10) + B 88 C4 MOV AH, AL ;AH = AL 82 E4 F0 AND AH, 0F0h ;AH = (A * 16) D0 EC SHR AH, 1 ;AH = (A * 8) 28 E0 SUB AL, AH ;AL = (A * 8) + B C0 EC 02 SHR AH, 2 ;AH = A * 2 00 E0 ADD AL, AH ;AL = (A * 10) + B Submitted by Angel Tsankov . ::/ \::::::. :/___\:::::::. /| \::::::::. :| _/\:::::::::. :| _|\ \::::::::::. :::\_____\:::::::::::.......................................................FIN