[v5,2/6] node: Add some documentation

Message ID 20171016051653.31014-3-aik@ozlabs.ru
State New
Headers show
Series
  • fdt: Pass the resulting device tree to QEMU + related fixes
Related show

Commit Message

Alexey Kardashevskiy Oct. 16, 2017, 5:16 a.m.
This adds some internal structure commented definitions so they won't
break things now and grep can find them.

Signed-off-by: Alexey Kardashevskiy <aik@ozlabs.ru>
---
 slof/fs/base.fs | 16 ++++++++++++++++
 slof/fs/node.fs |  2 +-
 2 files changed, 17 insertions(+), 1 deletion(-)

Comments

Segher Boessenkool Oct. 16, 2017, 6:47 a.m. | #1
Hi!

On Mon, Oct 16, 2017 at 04:16:49PM +1100, Alexey Kardashevskiy wrote:
> +\ WARNING: the wid>xxx and name>xxx definitions below are for the documentation
> +\ purposes only; NAME>LINK LINK> NAME> should be used instead; no code outside
> +\ of the engine has any business accessing flags, count, chars directly.
> +
> +\ STRUCT
> +\  cell FIELD wid>next
> +\  cell FIELD wid>names \ the head of the list of name records, points to name>next
> +\ END-STRUCT

It points to the first word in the list.  A word starts with the link
field, but that is just a detail.

> diff --git a/slof/fs/node.fs b/slof/fs/node.fs
> index 3b079e4..add5760 100644
> --- a/slof/fs/node.fs
> +++ b/slof/fs/node.fs
> @@ -23,7 +23,7 @@ STRUCT
>    cell FIELD node>peer
>    cell FIELD node>parent
>    cell FIELD node>child
> -  cell FIELD node>properties
> +  cell FIELD node>properties \ points to wid>next
>    cell FIELD node>words
>    cell FIELD node>instance-template
>    cell FIELD node>instance-size

Similarly, this is just a wid, just like the "words" field.


Segher
Alexey Kardashevskiy Oct. 16, 2017, 7:11 a.m. | #2
On 16/10/17 17:47, Segher Boessenkool wrote:
> Hi!
> 
> On Mon, Oct 16, 2017 at 04:16:49PM +1100, Alexey Kardashevskiy wrote:
>> +\ WARNING: the wid>xxx and name>xxx definitions below are for the documentation
>> +\ purposes only; NAME>LINK LINK> NAME> should be used instead; no code outside
>> +\ of the engine has any business accessing flags, count, chars directly.
>> +
>> +\ STRUCT
>> +\  cell FIELD wid>next
>> +\  cell FIELD wid>names \ the head of the list of name records, points to name>next
>> +\ END-STRUCT
> 
> It points to the first word in the list.  A word starts with the link
> field, but that is just a detail.

I'll make it:

\  cell FIELD wid>names \ points to the first word in the list (grep name>next)

I am adding this mostly for grepping sometime later.


> 
>> diff --git a/slof/fs/node.fs b/slof/fs/node.fs
>> index 3b079e4..add5760 100644
>> --- a/slof/fs/node.fs
>> +++ b/slof/fs/node.fs
>> @@ -23,7 +23,7 @@ STRUCT
>>    cell FIELD node>peer
>>    cell FIELD node>parent
>>    cell FIELD node>child
>> -  cell FIELD node>properties
>> +  cell FIELD node>properties \ points to wid>next
>>    cell FIELD node>words
>>    cell FIELD node>instance-template
>>    cell FIELD node>instance-size
> 
> Similarly, this is just a wid, just like the "words" field.
> 
> 
> Segher
>
Alexey Kardashevskiy Oct. 17, 2017, 3:33 a.m. | #3
On 16/10/17 18:11, Alexey Kardashevskiy wrote:
> On 16/10/17 17:47, Segher Boessenkool wrote:
>> Hi!
>>
>> On Mon, Oct 16, 2017 at 04:16:49PM +1100, Alexey Kardashevskiy wrote:
>>> +\ WARNING: the wid>xxx and name>xxx definitions below are for the documentation
>>> +\ purposes only; NAME>LINK LINK> NAME> should be used instead; no code outside
>>> +\ of the engine has any business accessing flags, count, chars directly.
>>> +
>>> +\ STRUCT
>>> +\  cell FIELD wid>next
>>> +\  cell FIELD wid>names \ the head of the list of name records, points to name>next
>>> +\ END-STRUCT
>>
>> It points to the first word in the list.  A word starts with the link
>> field, but that is just a detail.
> 
> I'll make it:
> 
> \  cell FIELD wid>names \ points to the first word in the list (grep name>next)
> 
> I am adding this mostly for grepping sometime later.
> 
> 
>>
>>> diff --git a/slof/fs/node.fs b/slof/fs/node.fs
>>> index 3b079e4..add5760 100644
>>> --- a/slof/fs/node.fs
>>> +++ b/slof/fs/node.fs
>>> @@ -23,7 +23,7 @@ STRUCT
>>>    cell FIELD node>peer
>>>    cell FIELD node>parent
>>>    cell FIELD node>child
>>> -  cell FIELD node>properties
>>> +  cell FIELD node>properties \ points to wid>next
>>>    cell FIELD node>words
>>>    cell FIELD node>instance-template
>>>    cell FIELD node>instance-size
>>
>> Similarly, this is just a wid, just like the "words" field.


btw what does "wid" stand for?
Segher Boessenkool Oct. 17, 2017, 9:51 a.m. | #4
On Tue, Oct 17, 2017 at 02:33:15PM +1100, Alexey Kardashevskiy wrote:
> >> Similarly, this is just a wid, just like the "words" field.
> 
> btw what does "wid" stand for?

Wordlist ID.  See the Forth standard, e.g.
http://lars.nocrew.org/dpans/dpans16.htm#16.3.1


Segher

Patch

diff --git a/slof/fs/base.fs b/slof/fs/base.fs
index edd474e..e92621f 100644
--- a/slof/fs/base.fs
+++ b/slof/fs/base.fs
@@ -13,6 +13,22 @@ 
 \ Hash for faster lookup
 #include <find-hash.fs>
 
+\ WARNING: the wid>xxx and name>xxx definitions below are for the documentation
+\ purposes only; NAME>LINK LINK> NAME> should be used instead; no code outside
+\ of the engine has any business accessing flags, count, chars directly.
+
+\ STRUCT
+\  cell FIELD wid>next
+\  cell FIELD wid>names \ the head of the list of name records, points to name>next
+\ END-STRUCT
+
+\ STRUCT
+\  cell FIELD name>next
+\  /c   FIELD name>flags
+\  /c   FIELD name>count
+\  0    FIELD name>chars
+\ END-STRUCT
+
 : >name ( xt -- nfa ) \ note: still has the "immediate" field!
    BEGIN char- dup c@ UNTIL ( @lastchar )
    dup dup aligned - cell+ char- ( @lastchar lenmodcell )
diff --git a/slof/fs/node.fs b/slof/fs/node.fs
index 3b079e4..add5760 100644
--- a/slof/fs/node.fs
+++ b/slof/fs/node.fs
@@ -23,7 +23,7 @@  STRUCT
   cell FIELD node>peer
   cell FIELD node>parent
   cell FIELD node>child
-  cell FIELD node>properties
+  cell FIELD node>properties \ points to wid>next
   cell FIELD node>words
   cell FIELD node>instance-template
   cell FIELD node>instance-size