Jump to content
Andrew Davie

New DASM Manual

Recommended Posts

Posted (edited)

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 by Andrew Davie
  • Like 4
  • Thanks 2

Share this post


Link to post
Share on other sites

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

Share this post


Link to post
Share on other sites

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?

  • Like 1

Share this post


Link to post
Share on other sites
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.

 

 

 

Share this post


Link to post
Share on other sites

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)  :)

Share this post


Link to post
Share on other sites
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.

 

 

Share this post


Link to post
Share on other sites

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

  • Like 1

Share this post


Link to post
Share on other sites
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.

 

Share this post


Link to post
Share on other sites
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.
  • Like 1

Share this post


Link to post
Share on other sites

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 by Andrew Davie
  • Like 2

Share this post


Link to post
Share on other sites

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

Share this post


Link to post
Share on other sites
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.

 

Share this post


Link to post
Share on other sites
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.

Share this post


Link to post
Share on other sites
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.

 

Share this post


Link to post
Share on other sites
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."
 

Share this post


Link to post
Share on other sites

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. 

Share this post


Link to post
Share on other sites
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 by Andrew Davie

Share this post


Link to post
Share on other sites

  • Recently Browsing   0 members

    No registered users viewing this page.

×
×
  • Create New...