[OpenSPARC-T2-SAM] / obp / obp / fm / lib / stringar.fth

\ ========== Copyright Header Begin ==========================================
\ 
\ Hypervisor Software File: stringar.fth
\ 
\ Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved.
\ 
\  - Do no alter or remove copyright notices
\ 
\  - Redistribution and use of this software in source and binary forms, with 
\    or without modification, are permitted provided that the following 
\    conditions are met: 
\ 
\  - Redistribution of source code must retain the above copyright notice, 
\    this list of conditions and the following disclaimer.
\ 
\  - Redistribution in binary form must reproduce the above copyright notice,
\    this list of conditions and the following disclaimer in the
\    documentation and/or other materials provided with the distribution. 
\ 
\    Neither the name of Sun Microsystems, Inc. or the names of contributors 
\ may be used to endorse or promote products derived from this software 
\ without specific prior written permission. 
\ 
\     This software is provided "AS IS," without a warranty of any kind. 
\ ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, 
\ INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A 
\ PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN 
\ MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR 
\ ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR 
\ DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN 
\ OR ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR 
\ FOR DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE 
\ DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, 
\ ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF 
\ SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
\ 
\ You acknowledge that this software is not designed, licensed or
\ intended for use in the design, construction, operation or maintenance of
\ any nuclear facility. 
\ 
\ ========== Copyright Header End ============================================
id: @(#)stringar.fth 2.7 03/03/21 14:31:39
purpose: 
copyright: Copyright 1990-2003 Sun Microsystems, Inc.  All Rights Reserved
copyright: Use is subject to license terms.
\ Copyright 1985-1990 Bradley Forthware

\ String-array
\ Creates an array of strings.
\ Used in the form:
\ string-array name
\   ," This is the first string in the table"
\   ," this is the second one"
\   ," and this is the third"
\ end-string-array
\
\ name is later executed as:
\
\ name ( index -- addr )
\   index is a number between 0 and one less than the number of strings in
\   the array.  addr is the address of the corresponding packed string.
\   if index is less than 0 or greater than or equal to the number of
\   strings in the array, name aborts with the message:
\        String array index out of range

headers

\  This implementation runs fast, but at some cost in code space;
\  we reduced that cost by using w-words for the offset entries,
\  instead of cell-sized words as in the original implementation.
\  (The cost was not too bad when cell-size was /l, but with the
\   growth of cell-size to /x, it got downright wasteful!)
\
\  After the strings, a table is constructed, indexed to the strings.
\  Each entry in the table is the offset, in bytes, from the start
\  of the Parameter Field to the indexed string.
\
\  The first w-word of the PF contains the number of strings.
\
\  The second w-word of the PF contains the offset from the start
\  of the PF to the table.  The indexed string is found by indexing
\  into the table for the offset, then adding the offset to the PFA.

: string-array  \ name ( -- )
   create
   0 w,    \  The number of strings
   0 w,    \  The starting offset of the pointer table
   does>					( index pfa )
   2dup w@					( index pfa index #strings )
   0 swap within  0= abort" String array index out of range"   ( index pfa )
   tuck  dup wa1+ w@ +				( pfa index table-address )
   swap wa+ w@ +				( string-address )
;

\  After the strings are all created (using  ,"  as shown above), run
\  this to construct the pointer table and fill in the number of strings.
: end-string-array ( -- )
   0 here 		( #strings string-end-addr )
   lastacf >body	( #strings string-end-addr pfa )

   \  Remember PFA for use as the base address
   tuck                 ( #strings pfa string-end-addr pfa )

   \ Offset to table-addr goes into 2nd w-word of PF
   2dup -		( #strings pfa string-end-addr pfa table-offset )
   swap wa1+		( #strings pfa string-end-addr table-offset 2nd-w-word )
   tuck w!		( #strings pfa string-end-addr 2nd-w-word )

   \  Construct the table of offset-pointers
   wa1+			( #strings pfa string-end-addr first-string-addr )
   begin		( #strings pfa string-end-addr this-string-addr )
      3dup >		( .... pfa more? )
   while
      \ Store string offset in table
			( #strings pfa string-end-addr this-string-addr pfa )
      2dup - nip w,	( #strings pfa string-end-addr this-string-addr )
      \ Increment #strings
      2swap swap 1+ swap 2swap		( #strings' ... )
      \ Find next string address
      +str		( #strings' pfa string-end-addr next-string-addr )
   repeat		( #strings pfa string-end-addr last-string-addr pfa )
   \ We counted the number of strings; now store
   3drop w!		( #strings pfa )
;

\  It's highly unlikely -- but no longer impossible -- for a string-array 
\  to overflow the capacity of a w-word (it'd have to exceed 64K!), so we
\  really ought to check.  We'd rather not incur any cost of space in the
\  final ROM image, so we'll make the test transient.

\  Mini-forth loads this file as transient.
\  We probably should, some day, revisit the prohibition against
\  " Nested transient's" (as well as that dubious apostrophe),
\  but in the meantime, we'll do an unpretty point-solution...

transient? 0= dup if    transient   then
\  Leave copy of "not-already-transient" flag on compile-time stack

overload: end-string-array ( -- )
   here lastacf >body -
   h# 1.0000 < if
      end-string-array
   else
      where ." Can't accommodate such a large string-array!" cr
      (compile-time-error)
   then
;

\  Copy of "not-already-transient" flag is on compile-time stack
if    resident     then


headerless

\  Size-of-a-string-array.
\  Return the number of strings in the string-array whose CFA is given.
\  If we ever change the data-structure again, we need only change this
\  routine, and the callers will all remain in sync.
\
: /string-array ( acf -- index )
   >body w@
;

\  Example of usage of the above:

\  \  Print out an entire string-array, under control of the  exit?  utility.
\  : .string-array ( acf -- )
\     dup /string-array 0 do i over execute ". cr exit? ?leave loop drop
\  ;

headers
Commit	Line	Data
920dae64 AT	1	\ ========== Copyright Header Begin ==========================================
	2	\
	3	\ Hypervisor Software File: stringar.fth
	4	\
	5	\ Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved.
	6	\
	7	\ - Do no alter or remove copyright notices
	8	\
	9	\ - Redistribution and use of this software in source and binary forms, with
	10	\ or without modification, are permitted provided that the following
	11	\ conditions are met:
	12	\
	13	\ - Redistribution of source code must retain the above copyright notice,
	14	\ this list of conditions and the following disclaimer.
	15	\
	16	\ - Redistribution in binary form must reproduce the above copyright notice,
	17	\ this list of conditions and the following disclaimer in the
	18	\ documentation and/or other materials provided with the distribution.
	19	\
	20	\ Neither the name of Sun Microsystems, Inc. or the names of contributors
	21	\ may be used to endorse or promote products derived from this software
	22	\ without specific prior written permission.
	23	\
	24	\ This software is provided "AS IS," without a warranty of any kind.
	25	\ ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES,
	26	\ INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A
	27	\ PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN
	28	\ MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR
	29	\ ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
	30	\ DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN
	31	\ OR ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR
	32	\ FOR DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE
	33	\ DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY,
	34	\ ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF
	35	\ SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
	36	\
	37	\ You acknowledge that this software is not designed, licensed or
	38	\ intended for use in the design, construction, operation or maintenance of
	39	\ any nuclear facility.
	40	\
	41	\ ========== Copyright Header End ============================================
	42	id: @(#)stringar.fth 2.7 03/03/21 14:31:39
	43	purpose:
	44	copyright: Copyright 1990-2003 Sun Microsystems, Inc. All Rights Reserved
	45	copyright: Use is subject to license terms.
	46	\ Copyright 1985-1990 Bradley Forthware
	47
	48	\ String-array
	49	\ Creates an array of strings.
	50	\ Used in the form:
	51	\ string-array name
	52	\ ," This is the first string in the table"
	53	\ ," this is the second one"
	54	\ ," and this is the third"
	55	\ end-string-array
	56	\
	57	\ name is later executed as:
	58	\
	59	\ name ( index -- addr )
	60	\ index is a number between 0 and one less than the number of strings in
	61	\ the array. addr is the address of the corresponding packed string.
	62	\ if index is less than 0 or greater than or equal to the number of
	63	\ strings in the array, name aborts with the message:
	64	\ String array index out of range
65
66	headers
67
68	\ This implementation runs fast, but at some cost in code space;
69	\ we reduced that cost by using w-words for the offset entries,
70	\ instead of cell-sized words as in the original implementation.
71	\ (The cost was not too bad when cell-size was /l, but with the
72	\ growth of cell-size to /x, it got downright wasteful!)
73	\
74	\ After the strings, a table is constructed, indexed to the strings.
75	\ Each entry in the table is the offset, in bytes, from the start
76	\ of the Parameter Field to the indexed string.
77	\
78	\ The first w-word of the PF contains the number of strings.
79	\
80	\ The second w-word of the PF contains the offset from the start
81	\ of the PF to the table. The indexed string is found by indexing
82	\ into the table for the offset, then adding the offset to the PFA.
83
84	: string-array \ name ( -- )
85	create
86	0 w, \ The number of strings
87	0 w, \ The starting offset of the pointer table
88	does> ( index pfa )
89	2dup w@ ( index pfa index #strings )
90	0 swap within 0= abort" String array index out of range" ( index pfa )
91	tuck dup wa1+ w@ + ( pfa index table-address )
92	swap wa+ w@ + ( string-address )
93	;
94
95	\ After the strings are all created (using ," as shown above), run
96	\ this to construct the pointer table and fill in the number of strings.
97	: end-string-array ( -- )
98	0 here ( #strings string-end-addr )
99	lastacf >body ( #strings string-end-addr pfa )
100
101	\ Remember PFA for use as the base address
102	tuck ( #strings pfa string-end-addr pfa )
103
104	\ Offset to table-addr goes into 2nd w-word of PF
105	2dup - ( #strings pfa string-end-addr pfa table-offset )
106	swap wa1+ ( #strings pfa string-end-addr table-offset 2nd-w-word )
107	tuck w! ( #strings pfa string-end-addr 2nd-w-word )
108
109	\ Construct the table of offset-pointers
110	wa1+ ( #strings pfa string-end-addr first-string-addr )
111	begin ( #strings pfa string-end-addr this-string-addr )
112	3dup > ( .... pfa more? )
113	while
114	\ Store string offset in table
115	( #strings pfa string-end-addr this-string-addr pfa )
116	2dup - nip w, ( #strings pfa string-end-addr this-string-addr )
117	\ Increment #strings
118	2swap swap 1+ swap 2swap ( #strings' ... )
119	\ Find next string address
120	+str ( #strings' pfa string-end-addr next-string-addr )
121	repeat ( #strings pfa string-end-addr last-string-addr pfa )
122	\ We counted the number of strings; now store
123	3drop w! ( #strings pfa )
124	;
125
126	\ It's highly unlikely -- but no longer impossible -- for a string-array
127	\ to overflow the capacity of a w-word (it'd have to exceed 64K!), so we
128	\ really ought to check. We'd rather not incur any cost of space in the
129	\ final ROM image, so we'll make the test transient.
130
131	\ Mini-forth loads this file as transient.
132	\ We probably should, some day, revisit the prohibition against
133	\ " Nested transient's" (as well as that dubious apostrophe),
134	\ but in the meantime, we'll do an unpretty point-solution...
135
136	transient? 0= dup if transient then
137	\ Leave copy of "not-already-transient" flag on compile-time stack
138
139	overload: end-string-array ( -- )
140	here lastacf >body -
141	h# 1.0000 < if
142	end-string-array
143	else
144	where ." Can't accommodate such a large string-array!" cr
145	(compile-time-error)
146	then
147	;
148
149	\ Copy of "not-already-transient" flag is on compile-time stack
150	if resident then
151
152
153	headerless
154
155	\ Size-of-a-string-array.
156	\ Return the number of strings in the string-array whose CFA is given.
157	\ If we ever change the data-structure again, we need only change this
158	\ routine, and the callers will all remain in sync.
159	\
160	: /string-array ( acf -- index )
161	>body w@
162	;
163
164	\ Example of usage of the above:
165
166	\ \ Print out an entire string-array, under control of the exit? utility.
167	\ : .string-array ( acf -- )
168	\ dup /string-array 0 do i over execute ". cr exit? ?leave loop drop
169	\ ;
170
171	headers
172