New DASM Manual

[+Andrew Davie]

I've been working on a nicer manual for DASM.

Please review and contribute where you can.

 

 

Edit: Please grab from the dasm homepage!

Edited September 19, 2020 by Andrew Davie

[+Karl G]

This looks great! I'll go through it and let you know if I have any suggestions.

[+Karl G]

The manual is really good, and will be very useful! Here's a few things I noticed on one readthrough of the manual. Use these comments as you will if they are useful I don't mention intentional placeholder text/TODO items that you already know about:

 

The version string at the top of the manual is one version ahead of the latest released version. I'm guessing the manual will officially debut with the next version of DASM? Just thought I'd mention it in case it's an error, though.

 

"LSB, MSB Refers to the low significant byte and high signifciant byte of a word. The order of LSB and MSB is dependent upon the processor type."
 

It might be helpful here to use the terms "least-significant byte" and "most-significant byte" here to match the acronyms. Also, "significant" is typoed in the second usage of the word above.

 

"There may be zero or more options each separated by whitespace."

 

You might want to mention that the usage screen is displayed if no arguments are given here.

 

"-d Debug
This option is for developers."

 

I assume you mean DASM developers here, but you may want to say that explicitly to reduce confusion.

 

"The output file contains a two byte origin in little-endian order, then data until the end of the file. Any instructions which generate output (within an initialised segment) must do so with an ascending PC. Initialised segments must occur in ascending order"
 

Does PC mean program counter in this context? Also, a period is missing at the end of the last sentence.

 

"-p Number of Passes"

 

When I read this, I wondered what the default was for the max number of passes. I saw later in the document that it was 10, but you may want to mention that here, too.

 

"Certain errors will cause the assembly to abort immediately, others will wait until the current pass is other."

 

Do you mean "over" here instead of "other"?

 

"Label definitions can end with a colon, but the usage of the label must not include the colon."

 

Would using a colon just be for readability, or is there any difference in defining a label with or without a colon?

[+Andrew Davie]

1 minute ago, Karl G said:

The manual is really good, and will be very useful! Here's a few things I noticed on one readthrough of the manual. Use these comments as you will if they are useful I don't mention intentional placeholder text/TODO items that you already know about:

 

Thanks. There are lots of errors and typos. This is an early version and very rapidly cobbled together. It will improve as I attend to issues you and others point out.

1 minute ago, Karl G said:

 

The version string at the top of the manual is one version ahead of the latest released version. I'm guessing the manual will officially debut with the next version of DASM? Just thought I'd mention it in case it's an error, though.

I have not discussed with DASM maintainers if it will be included. I am assuming so. I just did a version check on my local version and used that.

 

1 minute ago, Karl G said:

 

"LSB, MSB Refers to the low significant byte and high signifciant byte of a word. The order of LSB and MSB is dependent upon the processor type."
 

It might be helpful here to use the terms "least-significant byte" and "most-significant byte" here to match the acronyms. Also, "significant" is typoed in the second usage of the word above.

Will fix all. Ta.

 

1 minute ago, Karl G said:

"There may be zero or more options each separated by whitespace."

 

You might want to mention that the usage screen is displayed if no arguments are given here.

That is not correct. There is ONE source file (required), and zero or more options.

If you enter no options, then it just assembles the source file.

I'll try and make it clearer. The source file is kind of mandatory.

 

1 minute ago, Karl G said:

"-d Debug
This option is for developers."

 

I assume you mean DASM developers here, but you may want to say that explicitly to reduce confusion.

 

I have no idea what it actually does. Hopefully we can find out.

 

1 minute ago, Karl G said:

"The output file contains a two byte origin in little-endian order, then data until the end of the file. Any instructions which generate output (within an initialised segment) must do so with an ascending PC. Initialised segments must occur in ascending order"
 

Does PC mean program counter in this context? Also, a period is missing at the end of the last sentence.

 

I need to clarify the use of PC. There are two "address counters" - the origin and the relocatable origin.  When bytes are placed in the binary, they must be assembled in increasing order. No "random access" when building a binary, basically.  That's what this is trying to say.

Will have a think about how to explain this in detail.

1 minute ago, Karl G said:

"-p Number of Passes"

 

When I read this, I wondered what the default was for the max number of passes. I saw later in the document that it was 10, but you may want to mention that here, too.

Yep, ta.

 

1 minute ago, Karl G said:

 

"Certain errors will cause the assembly to abort immediately, others will wait until the current pass is other."

 

Do you mean "over" here instead of "other"?

Yep, ta.

 

1 minute ago, Karl G said:

 

"Label definitions can end with a colon, but the usage of the label must not include the colon."

 

Would using a colon just be for readability, or is there any difference in defining a label with or without a colon?

Just for readability, I think. Personally I hate it and would remove it from the assembler. But it appears to be much-loved.

 

Thanks for the feedback.

 

 

 

[+splendidnut]

I just read thru it real quick.  Good start.

 

Do you plan on including an "intro" section?  Going over the basics of a sample assembly file.... Something where first time users can learn the most important things like: labels MUST be the first thing on a line (no whitespace allowed) and everything else REQUIRES whitespace to precede it on a line.   (One of the features I hate) 

[+Andrew Davie]

3 minutes ago, splendidnut said:

I just read thru it real quick.  Good start.

 

Do you plan on including an "intro" section?  Going over the basics of a sample assembly file.... Something where first time users can learn the most important things like: labels MUST be the first thing on a line (no whitespace allowed) and everything else REQUIRES whitespace to precede it on a line.   (One of the features I hate) 

 

It's not a book on how to program in assembly, so no.

 

Having said that, I'm pretty sure it mentions labels must be first on a line.

"Label definitions start at the beginning of a line and are encoded in ASCII; they must start with a letter or @ or _, and can include letters, numbers, and some symbols." in the chapter "Symbols and Labels"

 

Also,

"There must be whitespace before a directive. Thus, directives must not appear in the first column of any line."

Chapter "Directives"

 

I'm rapidly changing stuff, though I believe the above are in the version you were reviewing.

 

Thanks for the feedback.

 

 

[+splendidnut]

Ok... I guess I just missed it then.  Thanks for the quick response.

[explorer]

A changes page will be useful, with added, modified, removed and deprecated features from the previous document version.

[+Andrew Davie]

Just now, explorer said:

A changes page will be useful, with added, modified, removed and deprecated features from the previous document version.

Great idea. Will do.

 

[+SpiceWare]

40 minutes ago, Karl G said:

Would using a colon just be for readability, or is there any difference in defining a label with or without a colon?

 

Not just readability, if you search your source for

• label you'll be taken to everywhere the label is used
• label: you'll be taken to just 1 location, where the label is defined. This can be very useful at times.

[+Andrew Davie]

Update. I've incorporated the suggestions made above.

You can easily review changes via the "Change Log" on the page after the title page.

 

 

Edit: Please grab from the dasm homepage

 

Edited September 19, 2020 by Andrew Davie

[+Andrew Davie]

The manual is now a part of the "official" distribution, and can be retrieved from the DASM homepage...
https://dasm-assembler.github.io/

 

[alex_79]

There are a couple of errors regarding the 2600 in chapter 8:

The console is from 1977, and the 6507 has 13 address lines so it can address 8k of memory

[+Andrew Davie]

1 hour ago, alex_79 said:

There are a couple of errors regarding the 2600 in chapter 8:

The console is from 1977, and the 6507 has 13 address lines so it can address 8k of memory

TY. Now fixed. I also changed the memory size description to SI units, which I expect will be unpopular.

 

[Thomas Jentzsch]

10 hours ago, Andrew Davie said:

I also changed the memory size description to SI units, which I expect will be unpopular.

Nothing wrong with being precise. Especially in a document.

[+SpiceWare]

18 hours ago, Andrew Davie said:

TY. Now fixed. I also changed the memory size description to SI units, which I expect will be unpopular.

 

the for reads strangely to me.

 

Quote

Historically, disk drive manufacturers for this change in usage from the traditional use of "kilobyte", as they wanted to make their drives seem bigger than they were, so they divided capacity by 1000 instead of 1024 when listing drive size.

 

[+Andrew Davie]

31 minutes ago, SpiceWare said:

 

the for reads strangely to me.

 

 

TY, yes. I have rewritten it but did not publish straight away, as I'm a bit wary of doing too many updates. It came about because I was having a bitch about drive manufacturers using /1000 instead of /1024 when mentioning their drive size in megabytes. The upshot was, the drives seemed much bigger when you talked in K (1000) rather than K (1024). I hated them for it, still do. But I figured it didn't belong in a dasm manual. Here's the rewrite, which will be there next update.

"Historically, disk drive manufacturers were responsible for this change in meaning of the "kilobyte", as they divided capacity by 1000 instead of 1024 when listing drive size. This not only made their drives seem bigger, it created an ambiguity when discussing computer and disk memory size. The adoption of the new SI units for computer memory size removed the ambiguity."
 

[Thomas Jentzsch]

Originally the difference was not that large. A 500 MB HDD was ~4.9% smaller than a 500 MiB HDD. But an 1 TB SDD is already ~10% smaller than a 1 TiB SDD would be. And that gap will increase more and more. 

[+Andrew Davie]

11 minutes ago, Thomas Jentzsch said:

Originally the difference was not that large. A 500 MB HDD was ~4.9% smaller than a 500 MiB HDD. But an 1 TB SDD is already ~10% smaller than a 1 TiB SDD would be. And that gap will increase more and more. 

I just remember being outraged when I formatted a newly purchased 120MB hard drive, only to find something less than 110MB free, give or take.

 

Actually, 120MB according to the manufacturer was 120*1000*1000 bytes (Mega being 10^6).

So in my terms, divide by 1024 and again... gives just over 114 "MB" I expected.  In terms of 120, losing almost 6MB seemed... cheating.

I was most upset with the drive manufacturers for many years, not only for that "cheating" but later on for forcing KiB on us

Edit: update in calculations and trying to make the point that you lost even more space with formatting.

 

According to https://www.tweakandtrick.com/2013/07/lost-storage-space.html

a 2TB drive "loses" more than 185GB (!!)

 

Edited September 8, 2020 by Andrew Davie

[Thomas Jentzsch]

Back to topic.  

 

Maybe we should add some more description for the files created. While IMO the listing file is pretty straightforward, the symbol file IMO needs some more doc. E.g. local labels (inside subroutines and macros) are prefixed with a counter which should be explained. Also the usual '(R )' can also contain a 2nd flag 'S' which should be documented. Though I haven't seen that one yet.

 

Also it should be explained that symbols without flags are superfluous.

Edited January 17, 2021 by Thomas Jentzsch

[+Andrew Davie]

48 minutes ago, Thomas Jentzsch said:

Back to topic.  

 

Maybe we should add some more description for the files created. While IMO the listing file is pretty straightforward, the symbol file IMO needs some more doc. E.g. local labels (inside subroutines and macros) are prefixed with a counter which should be explained. Also the usual '(R )' can also contain a 2nd flag 'S' which should be documented. Though I haven't seen that one yet.

 

Also it should be explained that symbols without flags are superfluous.

 

Of course anyone is welcome to make these changes - but if you don't have the knowledge/tools to do the changes, just write 'em up and I'll be happy to add them to the manual and get the PDF done.

[Thomas Jentzsch]

Sure. I am trying to understand this completely to get this fixed for Stella first. 

[Thomas Jentzsch]

The current manual is missing an example for DV and EQM. Here is one from Robot City:

CHANCE  EQM ((255*..+100/2)/100)

RandomDirs
    DV      CHANCE 0, 5, 15, 35    ; game 1
    DV      CHANCE 0, 4, 12, 28
    DV      CHANCE 0, 3,  9, 21
    DV      CHANCE 0, 2,  6, 14
    DV      CHANCE 0, 1,  3,  7    ; game 5

This creates 20 bytes using the expressing defined by CHANCE. For game 1 the bytes created are 0, 12, 38, 89 (which are about 0, 5, 15 and 35% of 255). 

 

Another example: 

PAL_VAL     EQM     (..*PAL_ROWS + NTSC_ROWS/2)/NTSC_ROWS

This converts NTSC scanlines into PAL scanlines. 

 

BTW: Both examples are rounding, not truncating the results.

Edited April 12, 2021 by Thomas Jentzsch

[Thomas Jentzsch]

"nnn$ Local label, much like ‘.name’, except that defining a non-local label has the effect that SUBROUTINE has on‘.name’."

 

IMO this should be worded/explained better, maybe with an example. AFAIK code can be like this:

name$
  some code
Label
  some code
name$

So "Label" starts a new local label scope.

[+Pat Brady]

Is this an ongoing project?

 

IFCONST and IFNCONST always evaluate immediately. That is unusual compared to other directives which may not evaluate until a later pass. The behavior makes complete sense when you think it through, but I suggest mentioning it in the manual.