MASM documentation
Joseph M. Newcomer
MSDN, but real documentation. THe kind that gives the syntax of identifiers, for example,
or explains what options are available with the OPTIONS directive (not just a list of
them, but the actual explanations)? Or the syntax of a string, or of an initializer?
I'm reverse-engineering some of this as I am designing a course in x86 assembly code
(really! Turns out people need to *read* it), but I'd be happier if I found real
documentation somewhere.
The last time I wrote assembler it was for a device driver in MS-DOS, in 1989. But
apparently some things never go away, such as the need to know it, but nobody teaches it
any longer.
joe
Joseph M. Newcomer [MVP]
email: newc...@flounder.com
Web: http://www.flounder.com
MVP Tips: http://www.flounder.com/mvp_tips.htm
David Ching
news:g24rf5hvuo3qbgjmj...@4ax.com...
> Has anyone ever encountered the documentation for MASM. Not the useless
> garbage in the
> MSDN, but real documentation. THe kind that gives the syntax of
> identifiers, for example,
> or explains what options are available with the OPTIONS directive (not
> just a list of
> them, but the actual explanations)? Or the syntax of a string, or of an
> initializer?
>
I suggest you download MASM from your MSDN subscription because it comes
with a set of .doc files describing all kinds of stuff. But if you are
using Word 2003/2007, these ancient files are blocked by default, and I had
to edit the registry in order to get the modern Word to open them (something
about security....) Security by feature removal, yeah, that's the ticket!
:-O
-- David
Pete Delgado
"David Ching" <d...@remove-this.dcsoft.com> wrote in message
news:%23%233tf6IZ...@TK2MSFTNGP02.phx.gbl...
> I suggest you download MASM from your MSDN subscription because it comes
> with a set of .doc files describing all kinds of stuff. But if you are
> using Word 2003/2007, these ancient files are blocked by default, and I
> had to edit the registry in order to get the modern Word to open them
> (something about security....) Security by feature removal, yeah, that's
> the ticket!
Will wordpad open them???
-Pete
David Ching
news:uCgtEXJZ...@TK2MSFTNGP06.phx.gbl...
>
> Will wordpad open them???
>
The Wordpad coming with Win 7 says "Can't load files" (yes, that is 2
spaces between "load" and "files").
-- David
Geoff
The documentation for MASM from Microsoft was always rather poor IMHO,
compared to their documentation effort on the C/C++ front. The hard
copy manuals that came with MASM 5.1 and 6 were all about the tools
like ilink and dumpbin and not about MASM commands or ML itself.
Nothing existed online at the time and the help files in the MASM 6.11
package are MS-DOS help files. Most of the "help" available at the
time was in the form of sample files, IIRC. The MASM CLI was
"documented" in the "ml /h" command. I recall the /Zi switch was the
command to make MASM generate a CodeView debuggable binary.
The documentation might be improved in the MASM 8.0 package.
I encourage you to check out MASM32, a freeware development system
built around the Microsoft MASM package. http://www.masm32.com/
The masm32 package is intriguing because of it's "invoke" operator, a
tool that allows Windows API functions to be called in one line macros
and their return codes to be recovered in another line.
As for strings, I don't know any way MASM did it other than
.data
MyString db "This is a string",0
and this has obvious deficiencies with respect to Unicode. As I recall
the MASM 5/6 documentation also had sections on interfacing to BASIC
and FORTRAN code. I have not tested what would happen if you did
MyString dd "This is a string",0 instead.
I'm not sure what you mean by initializer in this context. A variable
was either initialized or not and syntax was the same:
.data
align 4
x DWORD 10 ; initialized
y DWORD ? ; uninitialized
An uninitialized point structure would be:
POINT STRUCT
x DWORD ?
y DWORD ?
POINT ENDS
All MASM versions were backward compatible with older versions so an
8.0 MASM would still be capable of generating Win16 code.
I always had the feeling that MASM was one of those tools that was
provided by Microsoft as an afterthought "Oh, you need an assembler?
Yeah, we have one, here it is. Have fun."
The MASM 8.0 package was provided as an addend to the VS 2005 package
and I don't know if the VS IDE has carnal knowledge of the CLI of MASM
but it would seem so.
AliR
AliR.
"David Ching" <d...@remove-this.dcsoft.com> wrote in message
news:eEi1WqJZ...@TK2MSFTNGP05.phx.gbl...
David Ching
news:ORgjXMLZ...@TK2MSFTNGP02.phx.gbl...
> "files"? that your problem, you are trying to open more than 1 file. :o)
>
I only specified one file (short filename too) so perhaps they have a
problem with the parser as well as their English syntax. ;)
-- David
Geoff
<newc...@flounder.com> wrote:
Found through Bing.
http://www.freebookzone.com/fetch.php?bkcls=pl_asm&bkidx=21
http://www.freebookzone.com/fetch.php?bkcls=pl_asm&bkidx=20
Click on the zip icon for an archive of .doc files.
Joseph M. Newcomer
I'm constrained to using MASM for external reasons.
name DWORD 30 DUP (1)
initializes 30 DWORDs to the value 1. I keep discovering these things by reading the MASM
listings produced by the compiler, and that triggers memories of what I used to do twenty
years ago.
I have the DDK MASM package, and its documents suck.
The command line switches are actually defined in the documentation. Nothing else of
value is defined.
MASM doesn't support Unicode, and I even have a slide that points this out; it has to be
hello DB 'H', 00h, 'E', 00h, 'L', 00h, 'L', 00h, 'O', 00h, 00h, 00h
I can see why companies are having problems finding people who can program in assembler.
When you can't learn how something works, you won't use it.
But now they're paying the price: people who need super-high-performance and want to use
the fancy MMX/XMM/etc instructions can't figure out how to use them or write them;
security companies can't get people who can reverese-engineer viruses, etc. And some of
these people need to write code that doesn't run with a C-stack or use the normal stack
while doing virus intercepts and cleanup. The number of us who used to earn our livings
writing huge systems in assembly code (250K lines) is dwindling...
I don't really believe in writing more that tiny subroutines in assembler, but what I seem
to take for granted--how to write assembly code--is apparently becoming a lost art.
Also, it turns out, compiler writers need to know how to program in machine code so they
can write code-generation components. I found someone who was writing a "compiler" for
XXXX-to-x86, where XXXX is the binary executable format for a long-dead computer (I can't
say more, such as who, but emulation is becoming a Big Deal all of a sudden, as long-lost
dusty-deck binaries are being sought out to do things like data reduction on massive
datasets (multi-GB). So opportunity is not just knocking; it is trying to break my door
down.
I thought writing a course in using MASM would be easy. It probably would be, if there
were any documentation. Right now, I have to run experiments. Sad, really. The syntax
of an identifier is apparently a Microsoft Corporate Secret.
joe
Liviu
>
> Has anyone ever encountered the documentation for MASM.
You don't mention the version. Besides the masm32 site well pointed
already, for some v6.1x links see for example..
http://doc.ddart.net/asm/Microsoft_MASM_Programmers_Guide_v6.1/
http://webster.cs.ucr.edu/AsmTools/MASM/
http://web.sau.edu/LillisKevinM/csci240/masmdocs/
Yes, I do realize the age of v6.1x (the manuals talk at length about 16b
segmentation and TSRs among others) yet surprisingly much still applies.
Liviu
Geoff
<newc...@flounder.com> wrote:
>It is surprising how horribly bad the documentation is.
I dug around my bookshelves and finally came up with the MASM book I
got with my original Windows SDK. (the big blue and white box)
Title: Microsoft Macro Assembler 5.1 Programmer's Guide
Copyright: 1987
Document number: 410610014-500-R00-0787
467 pages.
No bar code, the back has the MS Redmond address and is marked
1287 Part No. 01506
This was my only reference for it for years. You might find a copy of
it on amazon.com. The online copies I cited in my other post actually
get to the nitty gritty a bit more succinctly in the 6.11
documentation and they are more relevant today.
Mihai N.
Hmm, I just dicovered that my trust-worthy masm 5.10
(and link 5.01) that I keep carying around does not
work on Win 7 64 bit.
I need to find a newer version.
It's ok, it's only 20 years old (1988).
It it would have been some Apple stuff I would
have had to change it every 2 years :-)
--
Mihai Nita [Microsoft MVP, Visual C++]
http://www.mihai-nita.net
------------------------------------------
Replace _year_ with _ to get the real email
Mihai N.
> The syntax
> of an identifier is apparently a Microsoft Corporate Secret.
I would not expect to find this in the masm documents.
Isn't this part of the Intel assembly language spec?
All the options, and . directives (like .486, .code, .model flat),
yes, that would be the assembler.
Same for tricks like @@: to automatically generate label names.
Anyway, you might have a point with the value of someone who
knows assembly.
With at bit of luck I might be able to land some well payed job
later one, something like the Y2K boom for the Cobol guys :-D
Giovanni Dicanio
news:3kjsf5pv7sdqhc6a1...@4ax.com...
> I dug around my bookshelves and finally came up with the MASM book I
> got with my original Windows SDK. (the big blue and white box)
>
> Title: Microsoft Macro Assembler 5.1 Programmer's Guide
> Copyright: 1987
So back in the days the Windows SDK was made not only by header files but
also by paper-based documentation and books?
Giovanni
Giovanni Dicanio
news:mebsf590t5c7h1q5u...@4ax.com...
> It is surprising how horribly bad the documentation is.
> MASM doesn't support Unicode, and I even have a slide that points this
> out; it has to be
>
> hello DB 'H', 00h, 'E', 00h, 'L', 00h, 'L', 00h, 'O', 00h, 00h, 00h
>
> I can see why companies are having problems finding people who can program
> in assembler.
> When you can't learn how something works, you won't use it.
Probably when MASM was developed Unicode did not exist?
(I've never used this MASM, I don't know. I just used Devpac Assembler for
Motorola MC68000 on Commodore Amiga).
> But now they're paying the price: people who need super-high-performance
> and want to use
> the fancy MMX/XMM/etc instructions can't figure out how to use them or
> write them;
I have no idea of the assembly of the new Intel CPUs, but I read somewhere
that writing *hand-coded* optimized assembly code is hard these days (it's
not like the age of 80286 or Motorola 68000), and optimizing C++ compilers
do a better job than humans in producing optimized assembly code.
>The number of us who used to earn our livings
> writing huge systems in assembly code (250K lines) is dwindling...
Wow... Writing 250K lines of assembly code must be a titanic work (leaving
apart debugging...!).
> I don't really believe in writing more that tiny subroutines in assembler,
> but what I seem
> to take for granted--how to write assembly code--is apparently becoming a
> lost art.
As is COM programming :)
> I thought writing a course in using MASM would be easy. It probably would
> be, if there
> were any documentation. Right now, I have to run experiments.
Have fun :)
Giovanni
David Lowndes
>also by paper-based documentation and books?
Yep, a bookshelf full - something you could peruse in the reading room
and discover some useful API that you weren't aware of :)
Dave
BobF
Giovanni Dicanio
news:mebsf590t5c7h1q5u...@4ax.com...
> It is surprising how horribly bad the documentation is.
[...]
> I thought writing a course in using MASM would be easy. It probably would
> be, if there
> were any documentation. Right now, I have to run experiments.
Joe: I'm not sure if this helps, but I found the Art of Assembly Language
book freely available online:
http://webster.cs.ucr.edu/AoA/DOS/pdf/0_AoAPDF.html
And there is a chapter about MASM here:
http://webster.cs.ucr.edu/AoA/DOS/pdf/ch08.pdf
Giovanni
Joseph M. Newcomer
(did something to tear a ligament in my leg) so walking downstairs to find it...and
standing while I dug around in the old boxes...wasn't really an option. Maybe after I get
back next week (I'm off for a week of teaching tomorrow) I'll be able to go down and get
it.
joe
Joseph M. Newcomer
snow to get our listings...
joe
Tom Serface
haven't had any problems (except installing VS 2008 SP1 which won't work
with the Web Designer installed so I had to rename that folder and remove
some registry entries). I'll never get that 5 hours back it took me to
finally get programs to compile on my notebook and run on my desktop with
the same versioning. Although, to be fair, I learned a lot about manifest
and winsxs in the process.
You'd think some of the testing would have included trying a few "other"
products from the same company to ensure that they all play together well.
Tom
"David Ching" <d...@remove-this.dcsoft.com> wrote in message
news:%23%233tf6IZ...@TK2MSFTNGP02.phx.gbl...
Tom Serface
Tom
"David Ching" <d...@remove-this.dcsoft.com> wrote in message
news:%23%233tf6IZ...@TK2MSFTNGP02.phx.gbl...
Tom Serface
computer to the "reading room".
Tom
"David Lowndes" <Dav...@example.invalid> wrote in message
news:83atf51aah74l12um...@4ax.com...
Geoff
<newc...@flounder.com> wrote:
>When MASM was developed, computers barely existed. We had to walk barefoot through the
>snow to get our listings...
Up hill, both ways.
I still have my 286 machine with a Z80 ICE for cross development.
Monochrome CRT.
Giovanni Dicanio
news:ulIPi2T...@TK2MSFTNGP06.phx.gbl...
> But, I can read any documents at all now that I have Office 2007
> installed.
Tom: at least tin my experience, with Office 2007 I can't open the MASM docs
"out of the box" (the registry hack cited by David is required).
G
Joseph M. Newcomer
anything important; a couple of the links were fictional works about what assemblers might
do someway, but using the constructs in a real program causes the assembler to crash
(Microsoft wants to legitimize the use of this word by guaranteeing that no one will ever
again be able to deduce what "crash" means, by hiding all useful information).
But it got me further than I had been before. Today's problem: how to use a struct
declaration when the pointer to the structure base is in a register.
The construct
mov eax, [ecx].StructureName.field
causes the assembler to "stop working", whatever that now means. (It probably means the
code has never been tested...syntax errors should not cause programs to take internal
failures that terminate their execution...)
Anyway, I'm off the net for a week, teaching in Columbia MD all next week.
(By the way, the documentation on STRUCT is, to put it mildly, totally useless, but at
least the documentation is largely self-consistent in that regard, being almost uniformly
totally useless)
joe
Liviu
> when the pointer to the structure base is in a register.
>
> The construct
> mov eax, [ecx].StructureName.field
>
That construct works with v6.15 as documented. What version are you
using, and what's the full context, including the ml.exe command line?
Liviu
Mihai N.
> Up hill, both ways.
And carrying the PC and the CRT on the back.
:-)
Giovanni Dicanio
news:Xns9CC3F1BF...@207.46.248.16...
>>> We had to walk barefoot through the snow to get our listings...
>
>> Up hill, both ways.
>
> And carrying the PC and the CRT on the back.
> :-)
:-))
G
Joseph M. Newcomer
Source file:
title
.686
.model flat
option casemap:none
Triple struct
x dd ?
y dd ?
z dd ?
Triple ends
_TEXT segment
_fetchZ proc
$t=4
_fetchZ endp
mov eax,$t[esp]
mov eax, offset [eax].Triple.z
ret
_TEXT ends
end
========
Command line (from build log)
========
ml.exe /c /Fo"Debug\fetcher.obj" /W3 /Zi /errorReport:prompt /Ta.\fetcher.asm
>------ Build started: Project: structExample, Configuration: Debug Win32 ------
1>Assembling...
1> Assembling: .\fetcher.asm
1>MASM : fatal error A1016: Internal error
1>Project : error PRJ0019: A tool returned an error code from "Assembling..."
========
It is called by a program of the form:
#include "Triple.h" // which defines typedef struct { int x; int y; int z; } Triple;
extern "C" int fetchZ(Triple & t);
int fetchZ0(Triple & t)
{
return t.z;
}
int _tmain(int argc, _TCHAR* argv[])
{
Triple t={1, 2, 3};
int z0 = fetchZ0(t);
_tprintf(_T("z0=%d\n"), z0);
int z = fetchZ(t);
_tprintf(_T("z=%d\n"), z);
return 0;
}
This is a trivial example that is supposed to demonstrate how structures
are accessed from an assembly code program; I've run through several variations of
the syntax trying to get it to not crash (and Vista doesn't disclose what "crash" means,
eternal damnation to the paternalistic idiot who thought we should be protected from
knowing
the truth). This was the latest.
The next example will be how to access a field in a array of objects. Then we will work
backwards
to C code showing what the C compiler does, using the C++ subroutine shown above, then
discuss H2INC, etc.
The idea is to show patterns of assembly code and patterns of the C compiler; among other
things,
it helps figure out whether a compiler or an assembly programmer wrote the code.
But programs should not fail if there is a syntax error. Apparently adding the word
"offset" (left over from a previous attempt) causes the error. I removed it, and it
worked. Comes from programming on painkillers.
joe
Giovanni Dicanio
news:vpb0g5dbvhlama9bs...@4ax.com...
> MASM 9.00,
>
> Source file:
[...]
> _TEXT segment
> _fetchZ proc
>
> $t=4
> _fetchZ endp
> mov eax,$t[esp]
> mov eax, offset [eax].Triple.z
> ret
I don't understand that.
I thought you should put 'endp' after the 'ret' keyword to mark end of
procedure.
e.g
<code>
_fetchZ proc
$t=4
mov eax,$t[esp]
mov eax, offset [eax].Triple.z
ret
_fetchZ endp
</code>
Giovanni
Liviu
>[...]
> mov eax, offset [eax].Triple.z
> Apparently adding the word "offset" (left over from a previous
> attempt) causes the error. I removed it, and it worked.
FWIW v6.15 terminates with the same A1016 on the (wrong) construct
above, but has the decency to at least log the exact line number.
> But programs should not fail if there is a syntax error.
MS agrees ;-) but hasn't fixed it, yet. Looks like the root bug was
reported (and acknowledged) for more than a year now.
http://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=356393
Liviu
P.S. Giovanni is right about the misplaced 'endp' though that happens to
not matter in this case (loosely speaking, it's more about source
organization and label scoping than actual code generation).
Tom Serface
Tom
"Giovanni Dicanio" <giovanniD...@REMOVEMEgmail.com> wrote in message
news:uC1GjndZ...@TK2MSFTNGP02.phx.gbl...
Tom Serface
well be true.
Tom
"Giovanni Dicanio" <giovanniD...@REMOVEMEgmail.com> wrote in message
news:uqJGw4WZ...@TK2MSFTNGP04.phx.gbl...
Geoff
wrote:
We had to roll ours on a cart. The wheels bogged down in the snow and
I kept stepping on the cables. :)
Joseph M. Newcomer
Too bad errors that crash products can't be fixed in a timely fashion. Says something
about dedication to quality...
joe