JHENSHAWJR
Posts: 2
Joined: Sun Feb 03, 2013 7:50 pm

SWI documentation/info

Sun Feb 03, 2013 7:59 pm

Sorry if this has already been mentioned, didn't see it.

Does anyone have details on all of the SWI functions availalble for the Pi RISC OS?

The Raspberry PI book just lists them without info. on their purpose or registers/operands.

Thanks, Joe

AMcS
Posts: 184
Joined: Sun Jan 06, 2013 11:23 am
Location: Dublin, Ireland

Re: SWI documentation/info

Sun Feb 03, 2013 10:11 pm

Your best bet are the PRM (Programmers' Reference Manuals), there are 5 in total and they provide the documentation on all the SWIs.

They can be downloaded from http://foundation.riscos.com/Private/manuals/

But (as I am not near my Pi at the minute) I think they are also included in the SD build downloaded when you installed RISC OS (just can't recall the Path to them at the minute...).

The PRMs will include a description of the SWI (it's name and equivalent SWI number), entry conditions (what registers have to be set and what their meanings are), exit values (if applicable) and information on if the call is re-entrant or not.

I have found them useful over the years (bought mine at a show in Guildford many moons ago from CJE... wouldn't be surprised if they still have some in stock...)

User avatar
DavidS
Posts: 3096
Joined: Thu Dec 15, 2011 6:39 am
Location: USA
Contact: Website

Re: SWI documentation/info

Mon Feb 04, 2013 2:43 am

The PRMs should be in SDFS::RICOSpi$.Documents.Books.PRMs
Of course if you renamed your SD card SDFS drive then replace RISCOSpi with the name you gave it.
26-Bit R15 to 32-bit. 16-bit addressing to 24-bit. ARM and 65xx two CPU's that continue on, and are better than ever. Assembly Language forever :) .

JHENSHAWJR
Posts: 2
Joined: Sun Feb 03, 2013 7:50 pm

Re: SWI documentation/info

Mon Feb 04, 2013 8:45 pm

Thanks for the info. AMcS and David, really appreciate it.

AMcS
Posts: 184
Joined: Sun Jan 06, 2013 11:23 am
Location: Dublin, Ireland

Re: SWI documentation/info

Mon Feb 04, 2013 9:00 pm

JHENSHAWJR wrote:Thanks for the info. AMcS and David, really appreciate it.
No problem Joe, pleased to help.

timrowledge
Posts: 1140
Joined: Mon Oct 29, 2012 8:12 pm
Location: Vancouver Island
Contact: Website

Re: SWI documentation/info

Tue Feb 05, 2013 8:01 pm

Don't forget the StrongHelp manuals; they're so easy scan through and search that a lot of the time they are much more useful than the PRMs.
For SWIs in particular it's worth getting the os335 manual and the oslib one.
See http://www.riscos.info/downloads/stronghelp/manuals/ for a loooong list.
Making Smalltalk on ARM since 1986; making your Scratch better since 2012

AMcS
Posts: 184
Joined: Sun Jan 06, 2013 11:23 am
Location: Dublin, Ireland

Re: SWI documentation/info

Wed Feb 06, 2013 9:27 pm

timrowledge wrote:Don't forget the StrongHelp manuals; they're so easy scan through and search that a lot of the time they are much more useful than the PRMs.
For SWIs in particular it's worth getting the os335 manual and the oslib one.
See http://www.riscos.info/downloads/stronghelp/manuals/ for a loooong list.
Yep good catch Tim, the StrongHelp manuals are a neat way to quickly look up this or that SWI when you need it.

The PRMs give you the "why" behind several things (so you can see the logic behind certain OS features). It's a pretty good way of understanding how Relocatable Modules are put together and how the WIMP works, how to handle interrupts etc., - that's what they're good at. But for a quick reference check or a "How do you call "OS_Byte" this or that" you can't beat the StrongHelp guides.

User avatar
DavidS
Posts: 3096
Joined: Thu Dec 15, 2011 6:39 am
Location: USA
Contact: Website

Re: SWI documentation/info

Wed Feb 06, 2013 9:57 pm

Whilst this topic is active:

What level of documentation do you think would be helpfull the RISC OS API as a whole (SWIs, *CMDs, OSByte calls. OSWord calls, modules, memory management, etc, etc)? I know that many say that what we have is not enough, or not clear. I ask this as there are now a growing number of people that are new to RISC OS using RISC OS, and some of them are programmers.

I have a project to create a new complete set of documentation for RISC OS, both for Programmers and End Users, while this project is secondary at the moment (for obvious reasons) I would like to get a sense of what would be an sufficiant level of documentation. We are accustomed to the PRMs, and other scattered documentation as well as the Strong Help manuals, though I have read that this is somewhat stifeling to new RISC OS users, and I believe that a better set of documentation is key in getting more people to use and stick with RISC OS.
26-Bit R15 to 32-bit. 16-bit addressing to 24-bit. ARM and 65xx two CPU's that continue on, and are better than ever. Assembly Language forever :) .

AMcS
Posts: 184
Joined: Sun Jan 06, 2013 11:23 am
Location: Dublin, Ireland

Re: SWI documentation/info

Wed Feb 06, 2013 10:59 pm

David the documentation, I think, should be targeted at the user. We need to know WHO is using the documentation and then aim it accordingly.

By it's nature technical documentation is terse and not necessarily best for a newcomer, so from that viewpoint the PRMs could scare the beejepers out of the novice or someone who unwarily stumbles across them.

I'd suggest it's best to start with an introductory document that would need to be light, use text and some graphics to highlight the salient points.

Don't get me wrong there's still a need for the "exhaustive" experience that is the PRMs - they are the "Bible" of RISC OS and cover every aspect of it. They additionally effectively dispenses the notion that RISC OS is not some sort of minimalist "Toy" OS, which in itself might be a useful thing.

For other things StrongHelp and maybe some short explanatory documents (documenting on programming on RISC OS and the OS itself along the lines of Burngate's introduction to RISC OS) may be what's needed.

timrowledge
Posts: 1140
Joined: Mon Oct 29, 2012 8:12 pm
Location: Vancouver Island
Contact: Website

Re: SWI documentation/info

Wed Feb 06, 2013 11:14 pm

Now I'd have to disagree with the 'exhaustive' bit when applied to the PRMs. I think they miss out almost everything actually helpful in favour of very terse, narrowly focussed documentation of individual SWIs etc.

I would love to see a good collection of explanatory documentation; stuff that explains how to do bigger things and why it is best that way. Not simply tutorials that 'leave the rest to the student' but full details. Done moderately well they can answer so many questions so much better then reference docs; done *well* they make a system come alive to new users. Yes, they're surprisingly hard to write, which is why skilled documentation staff are hard to get.

The excellent opportunity that online/soft doc provides is all the interlinking that makes it possible to take a quick look at the reference material and jump back to the explanation or vice versa. I don't know if StrongHelp is robust enough to handle a full system document but that would be a fabulous tool to have. Amongst other attributes StrongHelp is so freakin fast to jump around doc with. Much better than the PDF reader(s).
Making Smalltalk on ARM since 1986; making your Scratch better since 2012

User avatar
DavidS
Posts: 3096
Joined: Thu Dec 15, 2011 6:39 am
Location: USA
Contact: Website

Re: SWI documentation/info

Thu Feb 07, 2013 12:25 am

@AMcS:
I have to agree with timrowledge in that the PRMs are far from exaustive. Though for different reasons:
The PRMs do not have most of the changes made in over a decade. Even the online ROOL PRMs are lacking in much of what has been added and changed.

@timrowledge:
:-) Thank you for that input. I guess it is a good thing that I am writing my documentation in StrongHelp. And yes it is definitely powerfull enough to support a complete set of documentation, as I doubt that I will excede 2GB and 16 milion files for one strong help manual :-) .
26-Bit R15 to 32-bit. 16-bit addressing to 24-bit. ARM and 65xx two CPU's that continue on, and are better than ever. Assembly Language forever :) .

timrowledge
Posts: 1140
Joined: Mon Oct 29, 2012 8:12 pm
Location: Vancouver Island
Contact: Website

Re: SWI documentation/info

Thu Feb 07, 2013 3:18 am

The ideal would be to write the doc in a format that can automagically be exported as StrongHelp, PDF, or webpages. Having the doc available online would at the least make it indexable by dear old Uncle Google and therefore really easy to search. Maybe even write it on a Wiki so many can contribute, then export it to StrongHelpify it? It's only text, diagrams and links so some variety of automation must be feasible.
Making Smalltalk on ARM since 1986; making your Scratch better since 2012

AMcS
Posts: 184
Joined: Sun Jan 06, 2013 11:23 am
Location: Dublin, Ireland

Re: SWI documentation/info

Thu Feb 07, 2013 9:19 am

Lads yes the PRMs do need to be updated, however many functions haven't changed, the overall operation of the WIMP as described there hasn't changed so I'd argue that so long as the reader is aware that they can use the PRMs but need to check other sources as well.

The PRMs still have value as they also give a more in depth view of why things are as they are in RISC OS.

Call me old fashioned but I do like a book (or five) in preference to on screen text (except when I need the latest information or a quick search).

Having resources on the internet is very important though as it brings speed and universal availability to the information, so I agree with you both on the value of that.

dr_d_gee
Posts: 84
Joined: Fri Jan 04, 2013 1:30 pm

Re: SWI documentation/info

Thu Feb 07, 2013 1:58 pm

As someone used to other platforms I'd say RISC OS has a lot of technical reference documentation, but little tutorial information; what there is is largely targeted at BASIC and possibly leaves too much out.

What's needed (for C/C++ anyway, IMHO) is a RISC OS equivalent of Charles Petzold's classic "Programming Windows", which focusses on things you want to *do* and shows you how to do them.

The other problem with attracting developers to RISC OS is, quite frankly, that the development tools themselves are rather outdated. There isn't an IDE in the way in which such a thing is now understood. Compare the RISC OS tools with QtCreator for example--code completion, integrated GUI designer, integrated (extensive) documentation, both reference and tutorial--and it's free (provided you're happy to distribute programs under the GPL--otherwise a commercial license is *very* expensive).

Even other 'minority' operating systems such as Syllable and Haiku have 'modern' IDEs (even if few other applications). So I suspect attracting and keeping developers--especially those with no deep commitment to the OS--may prove difficult.

nr.
Posts: 144
Joined: Wed Oct 03, 2012 8:51 am
Location: The Fens
Contact: Website

Re: SWI documentation/info

Thu Feb 07, 2013 4:31 pm

Can I just throw in a good word here for DrWIMP as a nice IDE on RISC OS? I'm a total RISC OS novice, yet was able to put together some programs in BASIC using the WIMP with minimal learning curve. As stated elsewhere, I'm not a programmer by any stretch of the imagination, so this was doubly surprising for me.

It also means I'm absolved from any discussions about features it offers with respect to other IDEs, as I have precious little experience of them :) I used Visual Basic and Delphi very briefly about 15 years ago, and that's it really. Any other hacking around has been done using vi and gcc.

Ta,
--
nr.

User avatar
DavidS
Posts: 3096
Joined: Thu Dec 15, 2011 6:39 am
Location: USA
Contact: Website

Re: SWI documentation/info

Thu Feb 07, 2013 6:28 pm

dr_d_gee wrote:As someone used to other platforms I'd say RISC OS has a lot of technical reference documentation, but little tutorial information; what there is is largely targeted at BASIC and possibly leaves too much out.
Once you learn the api in BBC BASIC V it does not change for other languages. Though yes it would be atractive to add tutorials for other languages to attract new developers.
What's needed (for C/C++ anyway, IMHO) is a RISC OS equivalent of Charles Petzold's classic "Programming Windows", which focusses on things you want to *do* and shows you how to do them.
I had started work on a series of tutorials for new RISC OS programmers. My goal is to give pretty much equilivent tutorials for:
  • ARM Assembly.
    BBC BASIC V
    Pascal.
    Charm.
    Squeak.
    C
    and C++
This is unfortunately on hold at the momnent, while I spend most of my free time on the ROOL USB Stack and its related device support.
The other problem with attracting developers to RISC OS is, quite frankly, that the development tools themselves are rather outdated. There isn't an IDE in the way in which such a thing is now understood. Compare the RISC OS tools with QtCreator for example--code completion, integrated GUI designer, integrated (extensive) documentation, both reference and tutorial--and it's free (provided you're happy to distribute programs under the GPL--otherwise a commercial license is *very* expensive).
What is wrong with !WinED + !Zap (or simular) + GCC (or Acorn C/C++)? These tools provide a more complete, easier to use, and equaly modern development enviroment for a C programmer than those available for Linux. And because of the standard Drag and Drop paridigm for managing files, and copying text or other media between applications it is quicker to have the three applications than to use an IDE.

And for those that do not like C, just use a different compiler in the above setup.
Even other 'minority' operating systems such as Syllable and Haiku have 'modern' IDEs (even if few other applications). So I suspect attracting and keeping developers--especially those with no deep commitment to the OS--may prove difficult.
We have a better development enviroment if your goal is productivity see above. Do not improve on perfection you will just slow yourself down.
26-Bit R15 to 32-bit. 16-bit addressing to 24-bit. ARM and 65xx two CPU's that continue on, and are better than ever. Assembly Language forever :) .

dr_d_gee
Posts: 84
Joined: Fri Jan 04, 2013 1:30 pm

Re: SWI documentation/info

Fri Feb 08, 2013 2:52 pm

The other issue is that apart from using an obscure language like Charm (unknown apart from RISC OS) developing a GUI (in a readable fashion) involves using C rather than C++. Why was Vala developed? To provide an alternative to C#/Mono for developing programs for the GNOME desktop (on Linux). Why was C#/Mono being used? Because the native GNOME language was C, not C++, and C# is a lot more productive.

While !Zap and !StrongEd are good editors, they are not really as capable as SCITE (an editor for Linux--and other platforms--that can allow you to compile from within the editor, and doesn't need the compiler to support "throwback" to provide a list of error messages, clicking on one of which takes you to the relevant line). And one of the useful things about file extensions is that the editor can tell what language it is supposed to be, and adjust accordingly...

Even then, for creating GUI applications *none* of these tools is as easy to use as something like QtCreator. Or Lazarus. Or...

User avatar
DavidS
Posts: 3096
Joined: Thu Dec 15, 2011 6:39 am
Location: USA
Contact: Website

Re: SWI documentation/info

Fri Feb 08, 2013 8:26 pm

dr_d_gee wrote:The other issue is that apart from using an obscure language like Charm (unknown apart from RISC OS) developing a GUI (in a readable fashion) involves using C rather than C++. Why was Vala developed? To provide an alternative to C#/Mono for developing programs for the GNOME desktop (on Linux). Why was C#/Mono being used? Because the native GNOME language was C, not C++, and C# is a lot more productive.
And Gnome uses GTK, and a few other dynamic librarys that add an extra layer of abstraction on top of the WM itself ontop of X11. If you want to use C++ no one is stopping you from writting a __packed__ class that for each of the 4 structures and adding the methods to manipulate the the class data elements and call the SWIs.
While !Zap and !StrongEd are good editors, they are not really as capable as SCITE (an editor for Linux--and other platforms--that can allow you to compile from within the editor, and doesn't need the compiler to support "throwback" to provide a list of error messages, clicking on one of which takes you to the relevant line).
If you have the GUI front end open for your compiler, or make (or another project manager that you prefer) then it is just a matter of dropping the contents of the build file (eg make file etc) on the corosponding IconBar Icon. This is a lot easier and faster than the methods used in the cumbersome slow wasteful IDEs on Linux + x11 + WM.
And one of the useful things about file extensions is that the editor can tell what language it is supposed to be, and adjust accordingly...
!Zap has no trouble with getting file types correct, if it is /c or in the directory c. then it is C, /o or directory o. an object, /s ordirectory s. it is assembly etc. And files that have an alocated type (BASIC, Obey, etc) there is no need for filename extensions.
Even then, for creating GUI applications *none* of these tools is as easy to use as something like QtCreator. Or Lazarus. Or...
Realy, then I assume that you have never used !WinEd?
26-Bit R15 to 32-bit. 16-bit addressing to 24-bit. ARM and 65xx two CPU's that continue on, and are better than ever. Assembly Language forever :) .

AMcS
Posts: 184
Joined: Sun Jan 06, 2013 11:23 am
Location: Dublin, Ireland

Re: SWI documentation/info

Sat Feb 09, 2013 12:30 pm

dr_d_gee wrote: Even then, for creating GUI applications *none* of these tools is as easy to use as something like QtCreator. Or Lazarus. Or...
Agreed, I've worked in Delphi in the past and use Visual Studio currently and the amount of convenience these supply shouldn't be underestimated. In VS, for example, autocompletion, code snippets and pop-up context sensitive help as you type (intellisense) are a real boon. Something like that on RISC OS would make the issue of SWI documentation moot - as you typed you'd get the info you needed (and more extensive help would be a small hop away).

I'd be a very happy camper in a Lazurus/Delphi or VS type environment existed on RISC OS. That having been said RO (as a target of Application Development) is in some respects easier than say Windows (can't speak about Linux - have used it but not programmed against it) - so that means it is possible to develop on RISC OS without an IDE but I'd be much happier if there was a reasonably passable one available.

RISC OS has a chance to progress - a new IDE might be a way to accelerate that - though I don't underestimate how difficult a task producing that would be. In the meantime we'll soldier on with the current options....

microbitsuk
Posts: 33
Joined: Fri Sep 09, 2011 10:04 am
Location: Perth WA
Contact: Website

Re: SWI documentation/info

Sat Feb 09, 2013 1:05 pm


User avatar
DavidS
Posts: 3096
Joined: Thu Dec 15, 2011 6:39 am
Location: USA
Contact: Website

Re: SWI documentation/info

Sat Feb 09, 2013 1:29 pm

microbitsuk wrote:Have you looked at Sourcery Yet at http://www.reallysmall.co.uk/Pages/norm ... rcery.html
Thank you for that. That is getting darned close to being a full blown IDE, and since so many developers are stuck on that point may help attract new developers.
26-Bit R15 to 32-bit. 16-bit addressing to 24-bit. ARM and 65xx two CPU's that continue on, and are better than ever. Assembly Language forever :) .

AMcS
Posts: 184
Joined: Sun Jan 06, 2013 11:23 am
Location: Dublin, Ireland

Re: SWI documentation/info

Sat Feb 09, 2013 1:32 pm

microbitsuk wrote:Have you looked at Sourcery Yet at http://www.reallysmall.co.uk/Pages/norm ... rcery.html
Thanks very much for that Microbits, I'll give it a look.

AMcS
Posts: 184
Joined: Sun Jan 06, 2013 11:23 am
Location: Dublin, Ireland

Re: SWI documentation/info

Sat Feb 09, 2013 1:42 pm

DavidS wrote:
microbitsuk wrote:Have you looked at Sourcery Yet at http://www.reallysmall.co.uk/Pages/norm ... rcery.html
Thank you for that. That is getting darned close to being a full blown IDE, and since so many developers are stuck on that point may help attract new developers.
People are stuck on that point for good reason David, anything that makes development/debugging and testing easier is a good thing (IMHO).

To develop RISC OS we need more developers - some will come from "outside" the historical cohort so anything that "eases" their path into RISC OS so much the better. For existing RISC OS developers it would make the task of developing (particular WIMP based apps) less fraught and allow for increased productivity without placing unreasonable demands on them or their time.

As I said to Microbitsuk I'll give Sourcery a look and see if it is a solution or at least a part of the solution desired.

User avatar
DavidS
Posts: 3096
Joined: Thu Dec 15, 2011 6:39 am
Location: USA
Contact: Website

Re: SWI documentation/info

Sat Feb 09, 2013 1:54 pm

AMcS wrote:People are stuck on that point for good reason David, anything that makes development/debugging and testing easier is a good thing (IMHO).
I agree with that. That is part of why I enjoy developng on RISC OS.
To develop RISC OS we need more developers - some will come from "outside" the historical cohort so anything that "eases" their path into RISC OS so much the better. For existing RISC OS developers it would make the task of developing (particular WIMP based apps) less fraught and allow for increased productivity without placing unreasonable demands on them or their time.
Yes I understand that many of the RISC OS newcomers will be accustomed to the Linux adn Windoze syle IDEs, I have worked on both systems, using some of these IDEs for years at a time. While they are the best available option on those platforms, they slow you down as compared to the way we do things on RISC OS.

That said; RISC OS does need a IDE in the style of those in th Linux world because the New Comers are accustomed to that style of development enviroment and need a transition point. I am all for things that bring more users and developers to RISC OS so long as bloat does not follow.
As I said to Microbitsuk I'll give Sourcery a look and see if it is a solution or at least a part of the solution desired.
I have not looked at it very much yet, though it does apear to be a partial solution. I think for a complete solution someone would have to put in a week and create a coplete IDE, and then however long to extend it to the needs of RISC OS Newcomers.
26-Bit R15 to 32-bit. 16-bit addressing to 24-bit. ARM and 65xx two CPU's that continue on, and are better than ever. Assembly Language forever :) .

AMcS
Posts: 184
Joined: Sun Jan 06, 2013 11:23 am
Location: Dublin, Ireland

Re: SWI documentation/info

Sat Feb 09, 2013 2:15 pm

DavidS wrote:I have not looked at it very much yet, though it does apear to be a partial solution. I think for a complete solution someone would have to put in a week and create a coplete IDE, and then however long to extend it to the needs of RISC OS Newcomers.
I'd agree it is a partial solution, there's a lot of "fiddling" about with settings to do more complex builds and from the documentation it does seem that Sourcery would much simplify that (good !). For a competent Linux coder (say) it would flatten out some of the issues so they could concentrate on coding without wondering with switches to set in Norcroft or how to create Obey or Run files.

To describe it as a full IDE though would be fanciful (and I would think it would take a lot more than a week to "fill in the gaps").

It's not sourcery that is the issue - but the provision of the editing part of the package that gives the following:

*Auto completion
*Macros/Code snippets support (both user created and library based)
*Pop up help on command/SWI syntax (the RISC OS equivalent of intellisense in Visual Studio).
*Support for automated testing
*Single Step debugging (with variable contents display and alteration).

All the above are a big ask. Sourcery gets the inherent "ickyness" of RISC OS specific compiler settings, makes, resource files and things Linux/Windows programmers wouldn't have come across before like !Run/!Boot and the whole Obey file thing sorted out.

Given that on Pi we have a 1900x1080 panel to work on the "multiple windows" of Sourcery could work quite well - though it would probably initially disconcert a Delphi/Lazarus/VS programmer. Still it's a lot better than having to manually build files (or other such stone age practices :D )

Return to “RISCOS”

Who is online

Users browsing this forum: No registered users and 2 guests