amforth-devel

[Amforth] inner interpreter operation.

[Macomson, W. <wis...@in...>]

I'm new to this and I'm trying to understand the amForth inner interpreter. There are a couple of clarifications in the "amforth Documentation, Release 5.1-wip,January 26, 2013" that would help a lot.

To wit:

(p. 9)	EXECUTE

Q: When is EXECUTE, um, executed? I'm not clear on what this is used for.

(p. 9)	NEXT
[ . . . ]
This last step finally jumps to the machine code pointed to by the X scratch pad register.

Q: To be clear, the machine code jumps to NEXT when it has completed.  Correct?

(p. 9)	EXIT
The code for EXIT (aka UNNEST) is the forth word EXIT in the dictionary. It reads the IP from the return stack and jumps to NEXT. The return stack pointer is incremented by 2 (1 flash cell).

Q: I think EXIT pops the top of the return stack into the IP.  That way, the second step of NEXT gets the correct value. Correct?

(p. 9)	DO_DOES
This code is the runtime part of the forth word DOES> . It pushes the current address of the MCU IP register onto the returnstack and jumps to DO_DOES. DO_DOES gets that address back, saves the current IP and sets the forth IP to the address it got from the stack. Finally it continues with NEXT.

Q.  Is this effectively a subroutine call?

Thanks for any light you can shed. 

Re: [Amforth] inner interpreter operation.

[Matthias T. <mt...@we...>]

Hi Wis,

> I'm new to this and I'm trying to understand the amForth inner
> interpreter. There are a couple of clarifications in the "amforth
> Documentation, Release 5.1-wip,January 26, 2013" that would help a
> lot.

Unfortunately I'm currently busy with other things, so please
dont hold your breath for answers. I'll come back to your questions
later. Sorry

Matthias

Re: [Amforth] inner interpreter operation.

[Michael K. <mi-...@t-...>]

Hi Wis.

Since Matthias is bussy, maybe I can help out.

Am 31.01.2013 um 21:37 schrieb Macomson, Wis:

> I'm new to this and I'm trying to understand the amForth inner  
> interpreter. There are a couple of clarifications in the "amforth  
> Documentation, Release 5.1-wip,January 26, 2013" that would help a  
> lot.
>
> To wit:
>
> (p. 9)	EXECUTE
>
> Q: When is EXECUTE, um, executed? I'm not clear on what this is  
> used for.

( xt -- ) EXECUTE

If you put an execution token xt on the stack, you may EXECUTE that.

It is used in the interpreter: Parse input stream for a forth word  
(word means "string of ascii characters delimited by blanks", find  
that word in dictionary, get its xt on stack and then execute it.

Investigate ACCEPT and INTERPRET in the source code.



> (p. 9)	NEXT
> [ . . . ]
> This last step finally jumps to the machine code pointed to by the  
> X scratch pad register.
>
> Q: To be clear, the machine code jumps to NEXT when it has  
> completed.  Correct?

That is correct.

'Low level' forth machine code continues execution of forth on 'high  
level' that way.



> (p. 9)	EXIT
> The code for EXIT (aka UNNEST) is the forth word EXIT in the  
> dictionary. It reads the IP from the return stack and jumps to  
> NEXT. The return stack pointer is incremented by 2 (1 flash cell).
>
> Q: I think EXIT pops the top of the return stack into the IP.  That  
> way, the second step of NEXT gets the correct value. Correct?

So it is.

If stack grows 'down' an increment by 2 drops one item - on a 8Bit  
machine with a 16Bit virtual forth machine on it.


>
> (p. 9)	DO_DOES
> This code is the runtime part of the forth word DOES> . It pushes  
> the current address of the MCU IP register onto the returnstack and  
> jumps to DO_DOES. DO_DOES gets that address back, saves the current  
> IP and sets the forth IP to the address it got from the stack.  
> Finally it continues with NEXT.
>
> Q.  Is this effectively a subroutine call?

Yes. (I think so.)

It is used to define words, that create words of the same class.

For exeample VARIABLE is such a word. You may create variables that  
all work the same.

VARIABLE Y0
VARIABLE X12
VARIABLE MOON

Such words are also called "defining words".

VARIABLE defines a new forth word, that has one cell of ram to hold  
an item. When this word is executed, it puts the address of its ram  
cell on stack - that is the 'subroutine' part of it.

Michael

>
> Thanks for any light you can shed.
>
> ---------------------------------------------------------------------- 
> --------
> Everyone hates slow websites. So do we.
> Make your web apps faster with AppDynamics
> Download AppDynamics Lite for free today:
> http://p.sf.net/sfu/appdyn_d2d_jan
> _______________________________________________
> Amforth-devel mailing list for http://amforth.sf.net/
> Amf...@li...
> https://lists.sourceforge.net/lists/listinfo/amforth-devel

Re: [Amforth] inner interpreter operation.

[Macomson, W. <wis...@in...>]

Thanks, Michael.  This helps a lot.

Also thank Matthias for me when you get a chance. I don't want to clog up his email any further.

Regards,

-wis

-----Original Message-----
From: Michael Kalus [mailto:mi-...@t-...] 
Sent: Saturday, February 02, 2013 2:54 AM
To: Everything around amforth
Subject: Re: [Amforth] inner interpreter operation.

Hi Wis.

Since Matthias is bussy, maybe I can help out.

Am 31.01.2013 um 21:37 schrieb Macomson, Wis:

> I'm new to this and I'm trying to understand the amForth inner 
> interpreter. There are a couple of clarifications in the "amforth 
> Documentation, Release 5.1-wip,January 26, 2013" that would help a 
> lot.
>
> To wit:
>
> (p. 9)	EXECUTE
>
> Q: When is EXECUTE, um, executed? I'm not clear on what this is used 
> for.

( xt -- ) EXECUTE

If you put an execution token xt on the stack, you may EXECUTE that.

It is used in the interpreter: Parse input stream for a forth word (word means "string of ascii characters delimited by blanks", find that word in dictionary, get its xt on stack and then execute it.

Investigate ACCEPT and INTERPRET in the source code.



> (p. 9)	NEXT
> [ . . . ]
> This last step finally jumps to the machine code pointed to by the X 
> scratch pad register.
>
> Q: To be clear, the machine code jumps to NEXT when it has completed.  
> Correct?

That is correct.

'Low level' forth machine code continues execution of forth on 'high level' that way.



> (p. 9)	EXIT
> The code for EXIT (aka UNNEST) is the forth word EXIT in the 
> dictionary. It reads the IP from the return stack and jumps to NEXT. 
> The return stack pointer is incremented by 2 (1 flash cell).
>
> Q: I think EXIT pops the top of the return stack into the IP.  That 
> way, the second step of NEXT gets the correct value. Correct?

So it is.

If stack grows 'down' an increment by 2 drops one item - on a 8Bit machine with a 16Bit virtual forth machine on it.


>
> (p. 9)	DO_DOES
> This code is the runtime part of the forth word DOES> . It pushes the 
> current address of the MCU IP register onto the returnstack and jumps 
> to DO_DOES. DO_DOES gets that address back, saves the current IP and 
> sets the forth IP to the address it got from the stack.
> Finally it continues with NEXT.
>
> Q.  Is this effectively a subroutine call?

Yes. (I think so.)

It is used to define words, that create words of the same class.

For exeample VARIABLE is such a word. You may create variables that all work the same.

VARIABLE Y0
VARIABLE X12
VARIABLE MOON

Such words are also called "defining words".

VARIABLE defines a new forth word, that has one cell of ram to hold an item. When this word is executed, it puts the address of its ram cell on stack - that is the 'subroutine' part of it.

Michael

>
> Thanks for any light you can shed.
>
> ----------------------------------------------------------------------
> --------
> Everyone hates slow websites. So do we.
> Make your web apps faster with AppDynamics Download AppDynamics Lite 
> for free today:
> http://p.sf.net/sfu/appdyn_d2d_jan
> _______________________________________________
> Amforth-devel mailing list for http://amforth.sf.net/ 
> Amf...@li...
> https://lists.sourceforge.net/lists/listinfo/amforth-devel


------------------------------------------------------------------------------
Everyone hates slow websites. So do we.
Make your web apps faster with AppDynamics Download AppDynamics Lite for free today:
http://p.sf.net/sfu/appdyn_d2d_jan
_______________________________________________
Amforth-devel mailing list for http://amforth.sf.net/ Amf...@li...
https://lists.sourceforge.net/lists/listinfo/amforth-devel

Re: [Amforth] inner interpreter operation.

[Matthias T. <mt...@we...>]

Hi Wis,

I've got some time to work on the docs. The webpage got
a small update as well. To answer your questions (Michael
did answer most of them, but he seemed to be unsure
himself ;) I'll try to do it myself.

First you may want to read the
http://www.bradrodriguez.com/papers/moving1.htm page and there the
section about the ITC technique.
Esp the picture tells almost everything.

Most of the inner interpreter code is in the file
core/amforth-interpreter.asm.

The Forth VM (inner interpreter) consists of a few registers, that
do all the work: W, IP, X and stack pointers for
data and return stacks. These names are not related to similiar
named atmega registers!

> (p. 9)	EXECUTE
> 
> Q: When is EXECUTE, um, executed? I'm not clear on what this is used
> for.

Execute has two aspects: One is part of the inner interpreter (starting
at the DO_EXECUTE label until the ijmp instruction) and the other one
is the forth word EXECUTE (in words/execute.asm). The latter simply
fetches the Top-Of-Stack element into the W register and calls the
former.

The inner interpreter execute reads the content of the address,
the W register points to. That number is itself an address, this
time of real machine code and the final JMP [X] branches to that
code. It is expected that this code sooner or later jumps back
to the inner interpreter (to DO_NEXT) _and_ keeping the W and IP
registers intact.

> (p. 9)	NEXT [ . . . ] This last step finally jumps to the machine
> code pointed to by the X scratch pad register.

NEXT _is_ the inner interpreter (label DO_NEXT in
amforth-interpreter.asm). It reads the flash cell, IP points to,
stores that number in W and increases IP by 1 (for the next round).
Finally the above execute is done.

In addition to the generic ITC model, the amforth inner interpreter
checks for machine interrupts and handles tham if any occured. This
is another story, however.

> 
> Q: To be clear, the machine code jumps to NEXT when it has completed.
> Correct?

Yes. See above. Every assembly word in the words/ directory has
the phrase jmp_ DO_NEXT at least once. There is no RET instruction
to get back (jmp_ is a macro to optimize between jmp and rjmp,
another story).

> 
> (p. 9)	EXIT The code for EXIT (aka UNNEST) is the forth word EXIT in
> the dictionary. It reads the IP from the return stack and jumps to
> NEXT. The return stack pointer is incremented by 2 (1 flash cell).
> 
> Q: I think EXIT pops the top of the return stack into the IP.  That
> way, the second step of NEXT gets the correct value. Correct?

Yes. See code in words/exit.asm.

> 
> (p. 9)	DO_DOES This code is the runtime part of the forth word DOES>
> . It pushes the current address of the MCU IP register onto the
> returnstack and jumps to DO_DOES. DO_DOES gets that address back,
> saves the current IP and sets the forth IP to the address it got from
> the stack. Finally it continues with NEXT.
> 
> Q.  Is this effectively a subroutine call?

DOES> is a rather difficult topic. It is easy to use, but
hard to explain and the implementation in amforth is not
the most obvious one. DOES> itself is not really
a subroutine call its more like a partial redefinition of a
colon word, which is a subroutine call. In the docs I've just removed
the section for now (it was simply garbage after all). I'll rewrite it
from scratch. Expect one page text per assembly code line ;)

I think for the beginning you can savely ignore both does> and
interrupts.

HTH
Matthias

Re: [Amforth] inner interpreter operation.

[Macomson, W. <wis...@in...>]

Matthias,

Thank you for taking time to respond. It is an unexpected pleasure. Between you and Michael, I think I understand the inner interpreter well now - I've been looking at the technical document intermittently for a while.

I've been doing hardware and I'm finishing an ATXMEGAxx4U board so I'm getting back into the software.  Since I'll need a couple of assembly language Forth words for external I/O, I'm looking into the Forth guts to see how to do it.

For background, I'll be looking harder at the DOES> word - I'm glad to see that it isn't the easiest to learn. I've been studying it; perhaps now it will click with the info you and Michael shared.

BTW: the link to the "Mailing List Archive" in the FAQ (http://amforth.sourceforge.net/faq.html)
Gives "ERROR Forum not found".  Also, is the mailing list closed? I don't see how to join it.

Regards,

-wis


-----Original Message-----
From: Matthias Trute [mailto:mt...@we...] 
Sent: Wednesday, February 06, 2013 11:46 AM
To: Everything around amforth
Subject: Re: [Amforth] inner interpreter operation.

Hi Wis,

I've got some time to work on the docs. The webpage got a small update as well. To answer your questions (Michael did answer most of them, but he seemed to be unsure himself ;) I'll try to do it myself.

First you may want to read the
http://www.bradrodriguez.com/papers/moving1.htm page and there the section about the ITC technique.
Esp the picture tells almost everything.

Most of the inner interpreter code is in the file core/amforth-interpreter.asm.

The Forth VM (inner interpreter) consists of a few registers, that do all the work: W, IP, X and stack pointers for data and return stacks. These names are not related to similiar named atmega registers!

> (p. 9)	EXECUTE
> 
> Q: When is EXECUTE, um, executed? I'm not clear on what this is used 
> for.

Execute has two aspects: One is part of the inner interpreter (starting at the DO_EXECUTE label until the ijmp instruction) and the other one is the forth word EXECUTE (in words/execute.asm). The latter simply fetches the Top-Of-Stack element into the W register and calls the former.

The inner interpreter execute reads the content of the address, the W register points to. That number is itself an address, this time of real machine code and the final JMP [X] branches to that code. It is expected that this code sooner or later jumps back to the inner interpreter (to DO_NEXT) _and_ keeping the W and IP registers intact.

> (p. 9)	NEXT [ . . . ] This last step finally jumps to the machine
> code pointed to by the X scratch pad register.

NEXT _is_ the inner interpreter (label DO_NEXT in amforth-interpreter.asm). It reads the flash cell, IP points to, stores that number in W and increases IP by 1 (for the next round).
Finally the above execute is done.

In addition to the generic ITC model, the amforth inner interpreter checks for machine interrupts and handles tham if any occured. This is another story, however.

> 
> Q: To be clear, the machine code jumps to NEXT when it has completed.
> Correct?

Yes. See above. Every assembly word in the words/ directory has the phrase jmp_ DO_NEXT at least once. There is no RET instruction to get back (jmp_ is a macro to optimize between jmp and rjmp, another story).

> 
> (p. 9)	EXIT The code for EXIT (aka UNNEST) is the forth word EXIT in
> the dictionary. It reads the IP from the return stack and jumps to 
> NEXT. The return stack pointer is incremented by 2 (1 flash cell).
> 
> Q: I think EXIT pops the top of the return stack into the IP.  That 
> way, the second step of NEXT gets the correct value. Correct?

Yes. See code in words/exit.asm.

> 
> (p. 9)	DO_DOES This code is the runtime part of the forth word DOES>
> . It pushes the current address of the MCU IP register onto the 
> returnstack and jumps to DO_DOES. DO_DOES gets that address back, 
> saves the current IP and sets the forth IP to the address it got from 
> the stack. Finally it continues with NEXT.
> 
> Q.  Is this effectively a subroutine call?

DOES> is a rather difficult topic. It is easy to use, but
hard to explain and the implementation in amforth is not the most obvious one. DOES> itself is not really a subroutine call its more like a partial redefinition of a colon word, which is a subroutine call. In the docs I've just removed the section for now (it was simply garbage after all). I'll rewrite it from scratch. Expect one page text per assembly code line ;)

I think for the beginning you can savely ignore both does> and interrupts.

HTH
Matthias

------------------------------------------------------------------------------
Free Next-Gen Firewall Hardware Offer
Buy your Sophos next-gen firewall before the end March 2013 and get the hardware for free! Learn more.
http://p.sf.net/sfu/sophos-d2d-feb
_______________________________________________
Amforth-devel mailing list for http://amforth.sf.net/ Amf...@li...
https://lists.sourceforge.net/lists/listinfo/amforth-devel

Re: [Amforth] inner interpreter operation.

[Matthias T. <mt...@we...>]

Hi Wis,

> I've been doing hardware and I'm finishing an ATXMEGAxx4U board 

Keep in mind that the atXmegas are different from the atmegas
(without X). amforth currently cannot write to flash, so all
stuff that requires it does not work (e.g. the compiler). A
simple text interpreter works (somehow)

> so
> I'm getting back into the software.  Since I'll need a couple of
> assembly language Forth words for external I/O, I'm looking into the
> Forth guts to see how to do it.

You may study the drivers/1wire.asm file. It is a good example. Small
but does useful things. Most of the code is in forth, not assembly.
As it should be.

> 
> For background, I'll be looking harder at the DOES> word - I'm glad
> to see that it isn't the easiest to learn. I've been studying it;
> perhaps now it will click with the info you and Michael shared.

I've created the section for does>, and it got significantly
shorter than I announced ;) But it is still not trivial. Let
me know, what you miss.

> 
> BTW: the link to the "Mailing List Archive" in the FAQ
> (http://amforth.sourceforge.net/faq.html) Gives "ERROR Forum not
> found".  Also, is the mailing list closed? I don't see how to join
> it.

Fixed. Thanks for telling

Matthias

Re: [Amforth] inner interpreter operation.

[Enoch <ix...@ho...>]

Helo Matthias,

Which doc output do you consider complete. The two most popular ones
fail:

make html
~~~~~~~~~

Theme error:
no theme named 'amforth' found (missing theme.conf?)

make latexpdf
~~~~~~~~~~~~~

l.1026 \includegraphics{flash-structure.*}

Regards, Enoch.

P/S above refers to r1355


Matthias Trute <mt...@we...> writes:

> Hi Wis,
>
>> I've been doing hardware and I'm finishing an ATXMEGAxx4U board 
>
> Keep in mind that the atXmegas are different from the atmegas
> (without X). amforth currently cannot write to flash, so all
> stuff that requires it does not work (e.g. the compiler). A
> simple text interpreter works (somehow)
>
>> so
>> I'm getting back into the software.  Since I'll need a couple of
>> assembly language Forth words for external I/O, I'm looking into the
>> Forth guts to see how to do it.
>
> You may study the drivers/1wire.asm file. It is a good example. Small
> but does useful things. Most of the code is in forth, not assembly.
> As it should be.
>
>> 
>> For background, I'll be looking harder at the DOES> word - I'm glad
>> to see that it isn't the easiest to learn. I've been studying it;
>> perhaps now it will click with the info you and Michael shared.
>
> I've created the section for does>, and it got significantly
> shorter than I announced ;) But it is still not trivial. Let
> me know, what you miss.
>
>> 
>> BTW: the link to the "Mailing List Archive" in the FAQ
>> (http://amforth.sourceforge.net/faq.html) Gives "ERROR Forum not
>> found".  Also, is the mailing list closed? I don't see how to join
>> it.
>
> Fixed. Thanks for telling
>
> Matthias
>
> ------------------------------------------------------------------------------
> Free Next-Gen Firewall Hardware Offer
> Buy your Sophos next-gen firewall before the end March 2013 
> and get the hardware for free! Learn more.
> http://p.sf.net/sfu/sophos-d2d-feb

Re: [Amforth] inner interpreter operation.

[Matthias T. <mt...@we...>]

Hi Enoch,

> Which doc output do you consider complete.

I'm still experimenting. The build process has
some quirks as well. In the meantime, just
enjoy the results on the webpage (some things
do not work locally)..

Matthias