A design rule for WP34s library software?



#9

The recent discussions on various software to be included in the WP34s library show that there are certain rules and limitations that need to (or at least should) be concerned. So I think it's a good idea if there was something like a standard for such software, a kind of programmer's guide. This might include the following topics and more:

  • Which registers can be used or should preferably be used? Some (most? all?) lettered registers are used for internal purposes (stack, parameters etc.), maybe there are one or two that can be used as "official" scratch registers. Or the rule recommends a range like R90-99 or R80-99 for library programs so that the user knows not to use these for his own software (as long as the library is used).
  • The same goes for flags. Since there is a vast number of available flags, the use of flag 90-99 could be recommended.
  • What about the stack? Consider the quadratic solver. X, Y and Z hold the coefficients, so do we need to preserve the higher registers on return? Should they be zeroed? Does this matter anyway?
  • What about initializing modes and handling/changing modes inside library software? For instance, software using trig functions should either use the current angular mode and, if necessary, convert angles to this mode. If modes are changed during the library call, they should be reverted to the original setting before return. The same goes for stack mode, display settings, etc.
  • What about documentation? What information is mandatory, what is optional?

I am sure this is not a complete list. ;-)

Dieter


#10

Thanks for raising this topic. There are no standards yet, but the following may form the base for a discussion here:

Quote:
  • Which registers can be used or should preferably be used? Some (most? all?) lettered registers are used for internal purposes ...

All of them have a specific use: please see the first page about "Memory" in the manual. So I don't recommend using these nor the ones employed for statistics if you want to avoid interfering with such commands. Beyond those, feel free to chose whatever registers you like. I think it's good practice to document them in the program header.
Quote:
  • The same goes for flags.
  • No user flags but the lettered ones have a specified meaning so far. So here the door is wide open for you. Enjoy (but document)!
    Quote:
  • What about the stack? Consider the quadratic solver. X, Y and Z hold the coefficients, so do we need to preserve the higher registers on return?
  • Depends. I'd vote for some cleanup at the end of a routine. E.g. if a routine uses X, Y, and Z for input and X and Y for output, then it shall work in a 4-level stack like shown below:
    Stack level   Content at start  ... at end
    T t t
    Z input parameter 3 t
    Y input parameter 2 result (part 2)
    X input parameter 1 result (part 1)
    I leave it as an exercise to transfer this to an 8-level stack ;-) Remember the commands STOS and RCLS.
    Quote:
  • What about initializing modes and handling/changing modes inside library software? For instance, software using trig functions should either use the current angular mode and, if necessary, convert angles to this mode. If modes are changed during the library call, they should be reverted to the original setting before return. The same goes for stack mode, display settings, etc.
  • I concur. STOM and RCLM will help in hosekeeping.
    Quote:
  • What about documentation? What information is mandatory, what is optional?

  • I can't force anybody to document what (s)he does in his/her routine, but I'd welcome documenting registers and flags used as well as input and output. With the housekeeping suggested above, nothing more will be necessary IMHO.

    What do you think?

    Walter


    #11

    Quote:
    All of them have a specific use: please see the first page about "Memory" in the manual. So I don't recommend using these nor the ones employed for statistics if you want to avoid interfering with such commands.

    At least for register "J" I haven't seen any usage yet, so this should be safe as scratch register.

    Edited: 14 Aug 2011, 3:51 p.m.


    #12

    Quote:
    At least for register "J" I haven't seen any usage yet, ...

    Not my fault ;-) Please read said page again 8-)

    #13

    Quote:

    Not my fault ;-) Please read said page again 8-)


    Well dear Walter,

    I'm quite sure that register J was NOT mentioned as being used for statistical calculations in former manual versions - that's the 1st point.

    And the 2nd point is that you yourself suggest "Unless required for the purposes just mentioned, A-D,I,J and K are available as additional general purpose registers."

    So what now?

    If I'm sure to be in SSIZE4 mode (or switch to this mode) in a program, I absolutely see no reason to NOT use any of these 'upperstack' registers A-D - they can be perfectly used e.g. as a backup of the usual X-T stack.

    Waiting for your next disagreement ... ;-)


    #14

    Franz,

    Quote:
    I'm quite sure that register J was NOT mentioned as being used for statistical calculations in former manual versions - that's the 1st point.

    You're right: J wasn't mentioned this way before v1.11. Who gets the first point now? ;-)
    Quote:
    And the 2nd point is that you yourself suggest "Unless required for the purposes just mentioned, A-D,I,J and K are available as additional general purpose registers."

    So what now?

    May I quote myself? I wrote in message #2 above: I don't recommend using these nor the ones employed for statistics if you want to avoid interfering with such commands.

    So if you want to interfere feel free to use them. But don't expect me appreciating that.

    #15

    Quote:
    May I quote myself? I wrote in message #2 above: ...

    Well, I also have quoted you - with exactly the words you use in your manual.

    So do we have 2 Walters here, a 'forum Walter' and a 'manual Walter'?

    Both contradicting statements above let me almost believe this.


    #16

    IMHO both statements are not contradicting each other :-)

    (I'm willing to explain this on request, but am confident you won't need it after reading carefully.)

    #17

    The recent discussions were for code in xrom which is a very different beast to a library. Code there cannot touch the user's state and must preserve modes and stack -- xrom exists to implement commands that, to the user, appear exactly like internal ones.

    Libraries, on the other hand, are far less restricted. Basically, so long as what the function does and what resources it uses is documented I don't see a problem. Still, it would be nice to avoid using the lettered registers and flags and the statistical registers -- you as a library writer don't know what the user is doing.


    - Pauli


    #18

    I think losing the stack isn't an issue for some 'large scale' applications. If you just create a useful subroutine of sorts it should more or less look like an internal command, even if it needs additional registers to do its work.

    Stack size is very much a matter of user preference and a routine or application should only change it if absolutely necessary. The user interface of the VEC application starts with a SSIZE8 command for good reasons and a matrix program may opt for inputing the rows or columns of a matrix via the stack which makes an appropriate stack size mandatory. I don't see a way to restore the user preference because an interactive application does not have complete control all of the time.

    OTH, a library routine that needs a specific stack size to operate should make use of STOM and RCLM. The latter routines are designed to directly transfer the state from and to a register and don't interfere with the stack contents.


    #19

    I can't disagree with any of this. A library is a library and can do anything.

    However, XROM isn't a library, it must look exactly like internal commands.


    - Pauli


    Possibly Related Threads...
    Thread Author Replies Views Last Post
      HP-80 History, Design and Interesting Facts BShoring 1 438 11-30-2013, 08:50 AM
    Last Post: Xavier A. (Brazil)
      Hook-µP software by Rush Systems Lute Kamstra 5 866 11-29-2013, 01:30 AM
    Last Post: Lute Kamstra
      Library#4 Modules mass-update and New Overlays Ángel Martin 0 489 11-09-2013, 05:55 AM
    Last Post: 'Angel Martin
      [HP Prime] Constants Library Values Timothy Roche 24 2,401 11-02-2013, 04:17 PM
    Last Post: Les Koller
      [HP-Prime CAS] Vector Calculus Library CompSystems 7 1,017 10-31-2013, 12:48 PM
    Last Post: Han
      Equation Library/App for the Prime Harold A Climer 3 606 10-30-2013, 10:14 AM
    Last Post: CompSystems
      Equation Library on the PRIME Harold A Climer 0 350 10-26-2013, 10:01 AM
    Last Post: Harold A Climer
      Prime: Pedagoguery Software pop up banner Matt Kernal 1 474 10-20-2013, 01:54 AM
    Last Post: Mic
      latest prime software release? Geoff Quickfall 3 640 10-12-2013, 03:53 PM
    Last Post: Tim Wessman
      OT: Jeppesen E6B Wind-Easy Computer (Slide Rule) Eddie W. Shore 18 2,408 10-12-2013, 03:26 PM
    Last Post: George Litauszky

    Forum Jump: