I misunderstood what Heater said in post #18. I thought he was saying that a wc or a wz can modify an instruction far removed from them. Now I understand that all he was saying is that his code may set or clear c and/or z long before he tests for them. That's okay. I have no problem with that. Been there, done that.
So, wc and wz act just on the instruction at hand, just as the manual states. The universe is still whole and I can breathe a sigh of relief.
Dave, my mistake here was that I didn't take the time to track down the specific code examples to which I was originally referring. Had I done so, I think a lot of confusion would have been avoided, and a lot of effort to explain things I already know could have been spared. Of course there are always others that may benefit later...
As soon as I get home and get Lodgepole fired up, I can excerpt the code in question.
Edit: I should also mention that 83 trillion operations later, my code is still running w/o a glitch. Thank goodness wc and wz don't act at a distance.
What I have noticed, is that when someone asks about something technical on a forum (anything technical / any forum), the words people use to explain how something works are "different" from the words used in the technical manuals.
For example DJNZ...
DJNZ Value, (#) Address
Instruction: Decrement value and jump to address if not zero. Try an experiment. Go show the text in blue to a non-technical friend, significant other, etc....
Then ask them to read it and tell you what it means.
They will say huh?
Then you might explain it to them. Maybe you will draw a diagram or an example to explain it.
Whatever you need to do to explain it, then that is what should be in a beginner's assembly language document, forum pages, or whatever to explain how that one instruction works.
I like looking at pictures or diagrams myself!
"Value" might be confusing. "Number" is a more common term.
"#" for that, say "We will skip that for now."
"Address", maybe "Place_Marker_Name" would be easier to understand.
Then to explain, maybe "Subtract 1 from the number and then if the number does not equal zero, then go to where the Place_Marker_Name is. Otherwise go to the next line."
Isn't the above wording more like people would use in forums to explain something?
(I'm not saying the technical manual should be worded any different. It needs to be that way to be accurate. No other way to do it except by also giving a few examples of use. I mean just to have a separate document or web page which uses more common and different words and a few examples of use. Explained the way we explain things on the forum.)
Yesterday, in a Ron Czapala thread, kuroneko did a fantastic job of illustrating a couple of PASM instructions - and it hardly required any words. That's exactly and precisely what I wished existed for every instruction, directive, condition, and effect.
I'd argue that this was simply a request/response session (works well for me, I couldn't write a proper tutorial). You'd have a hard time putting this kind of stuff into a (static) document. The most common cases could be covered but - from experience - the moment you rely on it you're out in the rain (i.e. there is no explanation for your issue).
I'm not saying you can't at least try (documenting) but I think it's hardly worth it. For any weird issue I come across I usually first do a quick-and-dirty test case, later add some comments, clean it up and file it away. Period. That's my knowledge base. Some stuff ends up here as puzzle or in [thread=84031]Phil's Tricks & Traps[/thread]. Some of it should make its way back into official documentation/errata. You're welcome to try.
bill, it may be that the folks here come from such varying backgrounds that it would be tough to make any useful generalities or to produce any universal guide. Just as soon as you simplify the terminology to suit one person, someone else will balk at the lack of precision.
When I was looking for a good "C" reference some years ago, I found all manner of thick tomes littering bookstore shelves. Yet the book that I purchased, and the only C reference I use, is a small book 1/2" thick, less than 5" wide, and about 8" high. It is perfect!
On the cover, below the title, it says "Puts All the Essential Functions and Commands At Your Fingertips" It has spoiled me. I gauge everything else by it. And practically everything else falls short. I particularly appreciate its focus on essentials.
It is odd to contemplate what a book of Prop essentials would contain. There would be no room for tutorials. No room to explain electricity or electronics. No room to elaborate on things that are common to all microprocessors. No lengthy exposition even on things specific to the Prop.
This December, when I finally have some free time, I intend to convert the Propeller Manual to a Word file and then cut out everything I consider extraneous, regroup the things I deem essential, and provide carefully crafted code snippets. If I can't reduce it to the size of my C reference, I'll eat the paper its printed on.
Such a thing couldn't be distributed - that would violate copyright laws. But I'd have the pocket reference I seek, and I'd derive perverse pleasure from the process that got me there.
--- "Value" might be confusing. "Number" is a more common term. ---
"Number" means something specific, namely a literal number. "Value" is more correct since it includes "Number" as well as any expression computable at compile-time.
--- "#" for that, say "We will skip that for now." ---
Why skip something that's fundamental to most assemblers and instruction sets, that of a literal value. This is commonly introduced as a basic concept in the initial discussion of an instruction set, then used frequently as a given in a variety of examples.
--- "Address", maybe "Place_Marker_Name" would be easier to understand. ---
Again, "Address" is a fundamental concept for any sort of assembly language programming for pretty much any instruction set. "Place_Marker_Name" is more confusing than "Address" since names in assembly language are often not place marker names. They may be constants used for calculating an effective address or used to define the size of tables or other structures.
--- Then to explain, maybe "Subtract 1 from the number and then if the number does not equal zero, then go to where the Place_Marker_Name is. Otherwise go to the next line." ---
--- Isn't the above wording more like people would use in forums to explain something? ---
No. Which number? It's a memory location whose address is provided in the destination address field of the instruction. The memory location is changed by the process involved. Again, Place_Marker_Name is not helpful. It's the source field value which is used as the address of the next instruction.
We're not talking here about a raw beginner's tutorial. The Propeller Manual is a reference manual for the Propeller. As such, it should use a generally accepted terminology for instruction sets that is fairly precise (as most terminologies are) about the meaning of things. One of the things a beginner's tutorial should do is to teach proper terminology. All other documentation should be in terms of that terminology or other generally accepted terms.
...Such a thing couldn't be distributed - that would violate copyright laws. But I'd have the pocket reference I seek, and I'd derive perverse pleasure from the process that got me there.
I've read tons of books which have parts which say "Reprinted with permission of xx", etc.
This December, when I finally have some free time, I intend to convert the Propeller Manual to a Word file and then cut out everything I consider extraneous, regroup the things I deem essential, and provide carefully crafted code snippets. If I can't reduce it to the size of my C reference, I'll eat the paper its printed on.
I'm sure that if you did this on behalf of Parallax, with Ken's permission/support/etc., he would be happy to provide you the document in an editable format.
Two books that I think would be cool would be patterned after the O'Reilly "Nutshell" and "Hacks" series... i.e. "Propeller in a Nutshell" and "Propeller Hacks". If you've ever seen books in the series, you'll understand the value. You would also probably like the book "C in a Nutshell". It's very well done.
...We're not talking here about a raw beginner's tutorial. The Propeller Manual is a reference manual for the Propeller. As such, it should use a generally accepted terminology for instruction sets that is fairly precise (as most terminologies are) about the meaning of things. One of the things a beginner's tutorial should do is to teach proper terminology. All other documentation should be in terms of that terminology or other generally accepted terms.
I knew I would get in trouble for that post!
And I agree with what you are saying. That was the way I learned. Geeze I must have read 20 books on microprocessors, digital electronics, logic circuits, programming, etc. when I was first learning this stuff.
However I've noticed a trend in recent years, and that is many people want results fast and don't want to read long manuals. Consumer electronics companies have picked up on this with their "quick start" fold outs.
My thinking is that if you can make it somewhat easy to get started and accomplish something, then that will provide the motivation to learn more.
I guess the benchmark would be how many non-technical people you could get to write a simple assembly program and get it working without their getting frustrated and giving up.
You are absolutely right. Depending on the quality of the resulting product, it's just possible Parallax would let it sally forth. Or, if everything was summarized rather than excerpted, perhaps it would not violate copyright laws. We'll see.
Fwiw, I found one of the confusing wc/wz undocumented examples I'd mentioned, and it was as Heater suspected...C & Z were previously adjusted for a later conditional branch. The absence of effects immediately before the conditional branch threw me for a loop.
Meanwhile, the absence of comments detailing that perceived trickery was simply PAR for the course.
The opcode consists of the instruction bits (–INSTR–), the “effect” status for the Z flag, C flag, result and indirect/immediate status (ZCRI), the conditional execution bits (–CON–), and the destination and source bits (–DEST- and –SRC–).
In my mind one is optaining the operand value directly from the instruction or via a level of indirection.
By the way there was a smiley at the end of my post re: the huge number of op codes. No way was I seriously suggesting it.
Just for the record... I am extremely happy with the latest Propeller Manual. I would not want any more info now as the latest version added some misconceptions and examples where necessary to remove confusion. This is a professional manual for professional people. As a professional, I do not want examples of each instruction cluttering up my manual. In fact, after initially skimming the manual, I mainly use the two page summary for almost everything I need.
The App Note (AN001??) for the counters and video definately needs improvements and a lot more detail.
Now, for the beginner, a tutorial style is what I think is required. This was discussed above. So, the wiki could be used for this.
Firstly would be the description of the use of the conditionals using c & z, and the use of WC, WZ, NR/WR. Then would follow an example of the use of each instruction, including a brief description (the manual would hold more information).
Comments
So, wc and wz act just on the instruction at hand, just as the manual states. The universe is still whole and I can breathe a sigh of relief.
As soon as I get home and get Lodgepole fired up, I can excerpt the code in question.
Edit: I should also mention that 83 trillion operations later, my code is still running w/o a glitch. Thank goodness wc and wz don't act at a distance.
For example DJNZ...
DJNZ Value, (#) Address
Instruction: Decrement value and jump to address if not zero.
Try an experiment. Go show the text in blue to a non-technical friend, significant other, etc....
Then ask them to read it and tell you what it means.
They will say huh?
Then you might explain it to them. Maybe you will draw a diagram or an example to explain it.
Whatever you need to do to explain it, then that is what should be in a beginner's assembly language document, forum pages, or whatever to explain how that one instruction works.
I like looking at pictures or diagrams myself!
"Value" might be confusing. "Number" is a more common term.
"#" for that, say "We will skip that for now."
"Address", maybe "Place_Marker_Name" would be easier to understand.
Then to explain, maybe "Subtract 1 from the number and then if the number does not equal zero, then go to where the Place_Marker_Name is. Otherwise go to the next line."
Isn't the above wording more like people would use in forums to explain something?
(I'm not saying the technical manual should be worded any different. It needs to be that way to be accurate. No other way to do it except by also giving a few examples of use. I mean just to have a separate document or web page which uses more common and different words and a few examples of use. Explained the way we explain things on the forum.)
I'd argue that this was simply a request/response session (works well for me, I couldn't write a proper tutorial). You'd have a hard time putting this kind of stuff into a (static) document. The most common cases could be covered but - from experience - the moment you rely on it you're out in the rain (i.e. there is no explanation for your issue).
I'm not saying you can't at least try (documenting) but I think it's hardly worth it. For any weird issue I come across I usually first do a quick-and-dirty test case, later add some comments, clean it up and file it away. Period. That's my knowledge base. Some stuff ends up here as puzzle or in [thread=84031]Phil's Tricks & Traps[/thread]. Some of it should make its way back into official documentation/errata. You're welcome to try.
When I was looking for a good "C" reference some years ago, I found all manner of thick tomes littering bookstore shelves. Yet the book that I purchased, and the only C reference I use, is a small book 1/2" thick, less than 5" wide, and about 8" high. It is perfect!
On the cover, below the title, it says "Puts All the Essential Functions and Commands At Your Fingertips" It has spoiled me. I gauge everything else by it. And practically everything else falls short. I particularly appreciate its focus on essentials.
It is odd to contemplate what a book of Prop essentials would contain. There would be no room for tutorials. No room to explain electricity or electronics. No room to elaborate on things that are common to all microprocessors. No lengthy exposition even on things specific to the Prop.
This December, when I finally have some free time, I intend to convert the Propeller Manual to a Word file and then cut out everything I consider extraneous, regroup the things I deem essential, and provide carefully crafted code snippets. If I can't reduce it to the size of my C reference, I'll eat the paper its printed on.
Such a thing couldn't be distributed - that would violate copyright laws. But I'd have the pocket reference I seek, and I'd derive perverse pleasure from the process that got me there.
"Number" means something specific, namely a literal number. "Value" is more correct since it includes "Number" as well as any expression computable at compile-time.
--- "#" for that, say "We will skip that for now." ---
Why skip something that's fundamental to most assemblers and instruction sets, that of a literal value. This is commonly introduced as a basic concept in the initial discussion of an instruction set, then used frequently as a given in a variety of examples.
--- "Address", maybe "Place_Marker_Name" would be easier to understand. ---
Again, "Address" is a fundamental concept for any sort of assembly language programming for pretty much any instruction set. "Place_Marker_Name" is more confusing than "Address" since names in assembly language are often not place marker names. They may be constants used for calculating an effective address or used to define the size of tables or other structures.
--- Then to explain, maybe "Subtract 1 from the number and then if the number does not equal zero, then go to where the Place_Marker_Name is. Otherwise go to the next line." ---
--- Isn't the above wording more like people would use in forums to explain something? ---
No. Which number? It's a memory location whose address is provided in the destination address field of the instruction. The memory location is changed by the process involved. Again, Place_Marker_Name is not helpful. It's the source field value which is used as the address of the next instruction.
We're not talking here about a raw beginner's tutorial. The Propeller Manual is a reference manual for the Propeller. As such, it should use a generally accepted terminology for instruction sets that is fairly precise (as most terminologies are) about the meaning of things. One of the things a beginner's tutorial should do is to teach proper terminology. All other documentation should be in terms of that terminology or other generally accepted terms.
I've read tons of books which have parts which say "Reprinted with permission of xx", etc.
So never hurts to ask!
I'm sure that if you did this on behalf of Parallax, with Ken's permission/support/etc., he would be happy to provide you the document in an editable format.
Two books that I think would be cool would be patterned after the O'Reilly "Nutshell" and "Hacks" series... i.e. "Propeller in a Nutshell" and "Propeller Hacks". If you've ever seen books in the series, you'll understand the value. You would also probably like the book "C in a Nutshell". It's very well done.
I knew I would get in trouble for that post!
And I agree with what you are saying. That was the way I learned. Geeze I must have read 20 books on microprocessors, digital electronics, logic circuits, programming, etc. when I was first learning this stuff.
However I've noticed a trend in recent years, and that is many people want results fast and don't want to read long manuals. Consumer electronics companies have picked up on this with their "quick start" fold outs.
My thinking is that if you can make it somewhat easy to get started and accomplish something, then that will provide the motivation to learn more.
I guess the benchmark would be how many non-technical people you could get to write a simple assembly program and get it working without their getting frustrated and giving up.
You are absolutely right. Depending on the quality of the resulting product, it's just possible Parallax would let it sally forth. Or, if everything was summarized rather than excerpted, perhaps it would not violate copyright laws. We'll see.
Fwiw, I found one of the confusing wc/wz undocumented examples I'd mentioned, and it was as Heater suspected...C & Z were previously adjusted for a later conditional branch. The absence of effects immediately before the conditional branch threw me for a loop.
Meanwhile, the absence of comments detailing that perceived trickery was simply PAR for the course.
Ah, you are right. Or are you? From page 349:
In my mind one is optaining the operand value directly from the instruction or via a level of indirection.
By the way there was a smiley at the end of my post re: the huge number of op codes. No way was I seriously suggesting it.
The App Note (AN001??) for the counters and video definately needs improvements and a lot more detail.
Now, for the beginner, a tutorial style is what I think is required. This was discussed above. So, the wiki could be used for this.
Firstly would be the description of the use of the conditionals using c & z, and the use of WC, WZ, NR/WR. Then would follow an example of the use of each instruction, including a brief description (the manual would hold more information).