Defining Procedures & Functions

Anything QL Software or Programming Related.
Post Reply
Martin_Head
Aurora
Posts: 847
Joined: Tue Dec 17, 2013 1:17 pm

Defining Procedures & Functions

Post by Martin_Head »

When defining SuperBASIC Procedures & Functions that have long names in machine code, there is a calculation to use (number of procedures or functions + number of characters + 7)/8

Doe's the number of characters include the length byte in the defined name?
If you have to use a extra byte at the end of the name to pad it out to an even address for the next DC.W. Is that counted too?
If the calculation results in a fraction, Do you round up/down/nearest whole number?

example:

dc.w myfun-*
dc.b 10,'A_LONGNAME',0

should this be worked out as:
(1+10+7)/8=2.25
(1+11+7)/8=2.375
(1+12+7)/8=2.5


martyn_hill
Aurora
Posts: 909
Joined: Sat Oct 25, 2014 9:53 am

Re: Defining Procedures & Functions

Post by martyn_hill »

Hi Martin

I have often pondered on this point, and whilst I have some ideas, I'm sure some one else here will have a more authoritative answer.

Here's my understanding:

. The PROC (or FN) Count that precedes the null-terminated list is solely used by QDOS to reserve sufficient space in the Name List (NL).
. Standard memory allocation granularity is 8-bytes
. The byte count of each new Name is already taken in to account in that standard calculation by the item 'number of procs or fns' - the NL stores (uniquely for QDOS) the text-length as a Byte, as you know.
. The pad-byte in the definition list is NOT stored in the NL, so does not need to be added.
. Round-down (we've already rounded-up to the next 8-byte allocation with the '+7'), so in your example:

(1 + 10 + 7) / 8 = 2.25 rounded-down to 2, to allocate 2 lots of 8-bytes in the NL for our 11-byte (Length + Name).

Anyone got a better understanding?


User avatar
tofro
Font of All Knowledge
Posts: 2685
Joined: Sun Feb 13, 2011 10:53 pm
Location: SW Germany

Re: Defining Procedures & Functions

Post by tofro »

Thre's an in-depth detailed explanation of what, why and how much by Simon Goodwin somewhere in the DIY TK documentation if I remember right - I don't recall atm, however, where exactly.

Tobias


ʎɐqǝ ɯoɹɟ ǝq oʇ ƃuᴉoƃ ʇou sᴉ pɹɐoqʎǝʞ ʇxǝu ʎɯ 'ɹɐǝp ɥO
martyn_hill
Aurora
Posts: 909
Joined: Sat Oct 25, 2014 9:53 am

Re: Defining Procedures & Functions

Post by martyn_hill »

Prompted by Tobias to look through the DIY TK docs, I found some clues to validate the first answer below.

Still haven't found the in-depth article Tobias refers to, but in the TASKCOM basic utiilty in Volume 'F', where the new Name is being POKEd as part of the usual BP.INIT code, the Count of procs/fns (always '1' in the case of TASKCOM) is calculated as:

NL%=LEN(name$)
...
POKE_W b,(NL%+8) DIV 8

Which is numerically the same as (number of procs/fns + total length of Names + 7) / 8 - rounded-down...

:-)


User avatar
NormanDunbar
Forum Moderator
Posts: 2251
Joined: Tue Dec 14, 2010 9:04 am
Location: Leeds, West Yorkshire, UK
Contact:

Re: Defining Procedures & Functions

Post by NormanDunbar »

It's bound to be in Pennell's QDOS Companion, but from page 98 of the book "wot I rote", https://qdosmsq.dunbar-it.co.uk/downloa ... sembly.pdf, I see this:
Now then, there is a caveat - isn’t there always? If the average length of the names of all the
procedures, or functions, is greater than 7 then the simple word for the number of procedures or
functions is changed to the value given by this calculation:

Code: Select all

(total number of characters in proc names+number of procedures+7)/8
So, the byte defining the length isn't included in the total number of bytes, only the bytes of the procedure/function names are required.

I also had a look at the code for DJToolkit, which has a number of longer names, so takes the average up over the 7 maximum, and I note that for procedures, I have the following:

Code: Select all

*--------------------------------------------------------------------*
* Procedure definition block                                              *
*--------------------------------------------------------------------*
num_procs  equ	    14
p_chars    equ	   173

def_block  dc.w    num_procs+p_chars+7/8
           dc.w    rel_heap-*
           dc.b    12,'RELEASE_HEAP'
Unfortunately, it seems I'm 2 procedures short, and about 6 characters short too - but it still works, and has done since 1993/94 with a minor update in 2013! I suspect the memory allocation granularity of 8 bytes, has saved my neck!


HTH

Cheers,
Norm.


Why do they put lightning conductors on churches?
Author of Arduino Software Internals
Author of Arduino Interrupts

No longer on Twitter, find me on https://mastodon.scot/@NormanDunbar.
martyn_hill
Aurora
Posts: 909
Joined: Sat Oct 25, 2014 9:53 am

Re: Defining Procedures & Functions

Post by martyn_hill »

Hi Norm

May interpretation is that the "byte defining the length" is in fact included - but not in the "total number of characters in proc names", but in the "number of procedures" :-)


User avatar
janbredenbeek
Super Gold Card
Posts: 629
Joined: Wed Jan 21, 2015 4:54 pm
Location: Hilversum, The Netherlands

Re: Defining Procedures & Functions

Post by janbredenbeek »

Pennell's QDOS Companion mentions that the BP.INIT vector allocates (PROCNUM+FUNCNUM)*8 bytes in both the Name Table and Name List. A NT entry is always 8 bytes, a NL entry is LEN(name)+1 bytes. As long as the average length of the names doesn't exceed 8 (including the length byte) you shouldn't worry about allocating too little space.

Jan.


User avatar
pjw
QL Wafer Drive
Posts: 1286
Joined: Fri Jul 11, 2014 8:44 am
Location: Norway
Contact:

Re: Defining Procedures & Functions

Post by pjw »

My penny's worth:

The number of names that should be specified so as to allow
bp.init/sb.inipr to reserve sufficient space for the procedures and or
functions can be calculated as followes:

Code: Select all

count  = number of procedures or functions
length = the sum of all procedure or function name lengths + 1 for each name
         (This is for the length byte. Any padding bytes are not counted)
number = the number we're after

if count = 0 then
 number = 0
else
 length = (length + 9) / 8
 if count >= length then
  number = count
 else
  number = length
 endif
endif
The calculation is done separately for procedures and functions.

This algorithm was extracted from the ..mac_proc macros in the SMSQ/E
sources, so is presumably by Tony Tebby.


Per
dont be happy. worry
- ?
Martin_Head
Aurora
Posts: 847
Joined: Tue Dec 17, 2013 1:17 pm

Re: Defining Procedures & Functions

Post by Martin_Head »

Thanks for all that. I only ask because I am always worried whether I get it wrong. As I did once, and it led me a merry dance to find it. Everything worked normally, except intermittently FLP2_


Post Reply