"HELP [" improvements

From the sound of things it’s either required or desireable for us to add the VFP/NEON instructions to the output of BASIC’s “HELP [” in order for the assembler to make it into any official OS releases. Since “HELP [” is already a bit of a mess, I’m proposing that we adopt the following new structure:

• “HELP [” simply produces a brief list of sub-options
• “HELP [ OPT” describes the various OPTions
• “HELP [ ARM” produces an alphabetical list of all the core ARM instructions, similar to how “HELP .” produces a list of all BASIC keywords
• “HELP [ FPA”, “HELP [ VFP”, and “HELP [ NEON” produce lists of the FPA/VFP/NEON instructions
• “HELP [ *instruction>” displays the syntax for a specific instruction
• “HELP [ A.” displays the syntax of all instructions starting with “A”, etc. This wildcard system would also presumably include “HELP [ .” for a massive dump of all instructions, like “HELP [” currently provides.
• We also need somewhere to stick EQUD, ALIGN and any other non-instructions. Potentially under “HELP [ ASM”? Or just list them under “HELP [”?

Implementation-wise, help text lookup is performed by BASICTrans, so developing the new help system shouldn’t require any changes to BASIC itself. A bit of work will be needed to come up with a suitable way of representing the help text (we don’t want to bombard the user with too much redundant information if they use a wildcard, and we don’t want the messages file to grow to a massive size), but overall it should be a relatively painless procedure.

Note that I’m also assuming that the help text (for the instruction mnemonics) will remain limited to just syntax information, like it is now. Describing the purpose and operation of each instruction is an entirely different kettle of fish.

Since “HELP [” is already a bit of a mess, I’m proposing that we adopt the following new structure:

The sub-divisions you suggest seem eminently suitable.

However, I would like to put forward a completely different approach. ATM you have to be in BASIC command mode to use the HELP keyword and that is not unreasonable if you are writing programs like that, as you would have done on the BBC B, and you want to check on a keyword. How may people are likely to write more than trivial programs that way now and just how likely is it that they will be using assembler at all?

Rather like TWIN, HELP is really redundant and could be removed from BASIC without much loss, but there is still a need for a quick check system that is even simpler than StrongHelp. I considered this problem not so long ago with Basalt and solved it using the command *BasaltHelp. The use is very similar to the HELP keyword, and presents results in the same way. Such a command, *BasicHelp, could be added to the BASICTrans module without compromising BASIC itself and it could be used in most contexts.

Should you wish to see how it works you could look at the alpha version of Basalt.

I know it is a bit late in the day, but when adding your new assembler mnemonics did you ever consider the approach taken by Darren Salt’s Extended BASIC assembler? This is a bit of a kludge in some respects, because it patches the BASIC assembler error handling to call routines in an external module. However, this does mean that futher developments in the extended assembler could happen without further change to BASIC itself. Just a thought.

I like Steve’s idea, I like Jeffrey’s idea. But which is better?

It’d be nice to mop up the following

1. Being able to extend BASIC’s assembler, for example John Kortink’s 6502 assembler is useful for me when you want to write more code than a BBC Master can fit in its head. I imagine some kind of service call, or similar registration scheme to allow extra assembler parsers.
2. On an ARM v5T there’s no point offering a NEON assembler, but you might want MMX. Actually that’s a variation on (1), splitting out the parsers of foreign opcodes.
3. If (1) and (2) then you’d want some way of detecting it from BASIC, that might be a SWI call, or maybe some flag bits in @% or make OPT into a function so you can read the assembler capabilities?
4. Unreadable HELP [ My vote would be that HELP [ just reports the assembler directives like OPT and EQUS and zero help on the instruction set – it’s so terse as to not help. But the wildcard lookup stuff is tempting – is that something MessageTrans (via BASICTrans) can do without needing oodles of code?

Being able to extend BASIC’s assembler, for example John Kortink’s 6502 assembler is useful for me when you want to write more code than a BBC Master can fit in its head. I imagine some kind of service call, or similar registration scheme to allow extra assembler parsers.

A service call sounds sensible to me. That way you can have easily have multiple extensions running at once.

On an ARM v5T there’s no point offering a NEON assembler, but you might want MMX. Actually that’s a variation on (1), splitting out the parsers of foreign opcodes.

This is already handled to an extent, since I had to add a switch to stop the VFP/NEON assembler being included in the Iyonix ROM due to lack of space.

If (1) and (2) then you’d want some way of detecting it from BASIC, that might be a SWI call, or maybe some flag bits in @% or make OPT into a function so you can read the assembler capabilities?

Arguably a program could do this by just setting a local error handler and attempting to compile any instructions it’s interested in. But for more complex extensions (e.g. 6502) I guess it would be more appropriate to check for the extension as a whole rather than just checking for some of the instructions it supports. In which case the program could just issue the service call and see who responds?

But the wildcard lookup stuff is tempting – is that something MessageTrans (via BASICTrans) can do without needing oodles of code?

That could work, yes. But I was thinking it would have to be done manually, in order to allow the code to work out what additional syntax text needs displaying (I’m planning to make it so that it only explains what the <reg>, <copro>, etc. operands mean if those operands were used by the instructions being described)

Also there’s the obvious mistake in my original post that ‘*’ should be being used for wildcards, not ‘.’

Actually, moving the assembler out of BASIC as a whole would be a good idea, just from the perspective of reducing code duplication. The VFP/NEON assembler relies on a 30K data table that’s currently included twice in the ROM image (for BASIC & BASIC64). I was planning on moving it to ResourceFS, but if we come up with a sensible API for supporting assembler extensions then splitting the entire assembler out into a seperate module might make the most sense.

But the wildcard lookup stuff is tempting – is that something MessageTrans (via BASICTrans) can do without needing oodles of code?

My *BasaltHelp uses MessageTrans and is about 160 bytes of code.

That could work, yes. But I was thinking it would have to be done manually, in order to allow the code to work out what additional syntax text needs displaying (I’m planning to make it so that it only explains what the , , etc. operands mean if those operands were used by the instructions being described)

I do not know the history, but I have the memory that BASICTrans preceded MessageTrans, although BT now uses MT and the Messages file is already in place in ResourcFS. BT is in some ways an unecessary intermediary step ATM, but if you are going to put in some discrimination among assemblers then it makes sense.

I do not know the history, but I have the memory that BASICTrans preceded MessageTrans

Sounds to me like BASICTrans’ days are numbered. Additional assembler parsers could simply register their resources with ResourceFS like everyone else and MessageTrans be used universally (so the help also gets compressed during ROMming).

A service call sounds sensible to me. That way you can have easily have multiple extensions running at once.

That is simpler than trying to hijack a keyword like OPT or @%, but in the spirit of BASIC it’s probably worth a skim through the keyword list to see if something sticks out – along the lines of LIBRARY.
The gamut of languages I know is pretty small, but I recall ‘require’ in perl doing the sort of thing I had in mind.
I guess the simplest example I can think of where you need to be able to query what’s installed is ‘NOP’ which translates to “MOV R0,R0” for ARM, “MOV R8,R8” for Thumb1, “NOP” for Thumb2, and opcode &EA for 6502.

Actually, moving the assembler out of BASIC as a whole would be a good idea, just from the perspective of reducing code duplication.

Presumably the service call would need some hooks back into BASIC’s workspace (like you get using CALL) to allow the variables to be looked up. “MOV R0, #fred% * 2” would need “fred% *2” evaluating.

Presumably the service call would need some hooks back into BASIC’s workspace (like you get using CALL) to allow the variables to be looked up. “MOV R0, #fred% * 2” would need “fred% *2” evaluating.

Yes. There’d probably be a few different calls required, but I have a feeling this is the kind of task where the only way to find out what’s required is to have a go at doing it.

But the wildcard lookup stuff is tempting – is that something MessageTrans (via BASICTrans) can do without needing oodles of code?

I have put together an experimental module, BasicHelp , that provides the command *BasicHelp for BASIC keywords, using the existing Messages file, and for assembler information using a file derived from the present HELP [ . This file, called ARM, is loaded separately into ResourceFS and can be specified to be another file, say NEON, before the module is loaded. Dynmically changing the file is easily possible, but I have not implemented it that way. The data in the file is not complete, so if anyone wants to change it they are welcome, and to write files for other processors.

It can be downloaded from the link above, and I would be pleased for comments.

I have put together an experimental module, BasicHelp

I have been working on this and it now provides help on separate topics with *commands starting with [ . For instance, the ARM instructions are found with [ARM keyword|wildcard. [ARM can be abbreviated to [A., as with all *commands. There is quite a lot more detail than with BASIC’s HELP, and there is provision, but no data, for NEON and VFP.

I think this goes quite a long way to satisfy Jeffrey’s original proposal, and the code could easily be incorporated into BASICTrans if needed.

I haven’t had a chance to try this yet (hopefully tonight), but it sounds like you’re on the right track. Even if it isn’t an exact match for my original proposal I suspect it’ll be good enough to replace the current HELP [ output.

could easily be incorporated into BASICTrans if needed

BASIC I hope? BASICTrans serves no purpose now MessageTrans is around.

BASIC I hope? BASICTrans serves no purpose now MessageTrans is around.

Well, it does more than just transfer information from a Messages file and you could not, now, do away with it without adding a lot more to the BASIC module. It is far simpler to alter BASICTrans, because it can be replaced easily. Replacing the BASIC module is problematic.