Podule SDK (Software Development Kit)
The VirtualAcorn SDK has been designed to allow the user to build plugins ("software podules") for use with RISC OS. A number of these plugins are included with VirtualAcorn products. For example the Internet podule, HostFS, power management etc. This SDK includes three sample plugins that show how the system operates. You will need to be familiar with C++ and with developing under the Windows environment.
In addition you will need to have the skills required to code RISC OS modules. Any plugin needs to be able to communicate with RISC OS, typically using a Relocatable Module running on RISC OS, and to communicate with Windows. For example to pass information between the two different operating systems. If you do not have these skills then this SDK is not suitable.
This SDK is supplied as is, VirtualAcorn do not offer any warranty, support or any guarantees of any kind.
The VirtualAcorn products are built around three central concepts: Interfaces, Components and Models.
A typical VirtualAcorn can run one Model at a time. The model contains all the components that comprise a particular machine including processors, busses, keyboards, display etc. Many of these components are specified in a user editable model configuration file. Others are added by the emulator shell so it can control, or be controlled, by the model.
Components typically encapsulate a feature of the machine such as a processor or bus. They are constructed and connected to other components in a well defined order. Each component may export a number of interfaces to which other components may connect. Thus a well connected model can be built.
Interfaces are collections of functions and sometimes data. E.g. the physical bus exports and interface to allow the processor to read/write from the bus and also exports an interface to allow devices to insert themselves on the bus.
Many of these API's are exposed in the SDK for use by plugins.
The emulator will start and certain UI components will register global components, visible in all models.
The model builder will read all model files and create an associated component for each
[ ] entry. This behaviour may change in future but for now all components should perform minimal initialisation in the C++ constructor.
The user will select which model to use.
The Init() method for each global component is called.
The Init() method for each model component is called. Typically models will create structures and possibly add other dynamically created components to the model. These will in turn have their Init() method called. Components should also export any public interfaces at this time.
The Connect() method for each global component is called.
The Connect() method for each model component is called. Components should query public interfaces of other components using FindInterface() and register themselves with those interfaces as appropriate (e.g. bus devices register themselves with the physical bus).
The Reset() method for all components is called. Components should reset their internal state The PostReset() method for all components is called. Components can set state in other components. The Start() method is called. background threads can be started here but events are preferred. Run() is called on the first processor found.
At this point the model is running.
Deconstruction is pretty much the reverse of this using Stop(), Disconnect(), Cleanup() and the standard destructor.
The current SDK provides three features:
- A set of interface headers
- A set of C++ classes encapsulating some of the most commonly used interfaces
- A plugin library against which all plugins must link.
For the time being, most plugins should stick to using the C++ classes as they make it quite clear how the interfaces should be used. The classes add very little overhead to the plugin api.
There are currently three example plugins. An FPA10 coprocessor, a simple podule and a quite complex podule. They demonstrate most of the features of the plugin interface.
Special points to note
All plugins need to be compiled using fastcall rather than cdecl. You should link against retail versions of MFC if you use MFC.
Each plugin should go in its own folder in the Plugins folder. The generated dll should have the same name as the plugin folder. The plugin component can be added to the model file as [component] followed by any parameters.
VIRTUAL ACORN SDK END USER LICENSE AGREEMENT
(EXCEPT FOR REDISTRIBUTABLE ELEMENTS, REDISTRIBUTION NOT PERMITTED)
GRANT. Subject to the provisions contained herein,
Virtual Acorn ("VA") hereby grants to you a non-exclusive license to
use the components ("Components") that comprise the Virtual Acorn
SDK. You may not redistribute any of the Components except for those Components
listed as Redistributable Elements in the "redist.txt" file included
in the Virtual Acorn SDK. Your redistribution of the Redistributable Elements
is subject to the following restrictions and any supplemental restrictions in
the "redist.txt" file for that Component: (i) you may reproduce and
redistribute the Redistributable Elements in object code form only (if the
applicable Redistributable Element is software), and only when incorporated
into your software product which adds substantial and primary functionality to
the Redistributable Elements, and (ii) you may not permit further
redistribution of the Redistributable Elements by your end users.
USE OF COMPONENTS:
Source Code: You may copy and use internally the source
code ("Source Code") included in the Virtual Acorn SDK. You may not
redistribute the Source Code unless (i) the Source Code is listed as a
Redistributable Element, and (ii) you first compile the Source Code and
distribute only the compiled code.
Object Code and Graphics Files: You may copy and use
internally the object code ("Object Code") and graphics files
("Graphics Files") included in the Virtual Acorn SDK. You may not
redistribute the Object Code or the Graphics Files unless the applicable item
is listed as a Redistributable Element.
Documentation: You may use internally the
documentation ("Documentation") included in the Virtual Acorn SDK,
but your right to copy the Documentation is limited by copyright law. Making
unauthorized copies, adaptations, or compilation works is prohibited and
constitutes a punishable violation of the law.
Application Program Interfaces: You may use internally
the application programming interfaces ("APIs") included in the
Virtual Acorn SDK to create and then distribute software programs. You may not
modify or redistribute the APIs.
Header Files: You may copy and use internally the
header files ("Header Files") included in the Virtual Acorn SDK
solely to create and distribute programs to interface with the APIs (with
respect to the Header Files) or Virtual Acorn products. You may not modify the
VA may revise any of the Components from time to time without notice.
There is no license fee for the licenses granted herein.
DISCLAIMER OF WARRANTY. Each of the Components is
provided on an "AS IS" basis, without warranty of any kind, including
without limitation the warranties of merchantability, fitness for a particular
purpose and non-infringement. The entire risk as to the quality and performance
of the Components is borne by you. Should the Components prove defective or
inaccurate, as the case may be, you and not VA or its suppliers assume the
entire cost of any service and repair. This disclaimer of warranty constitutes
an essential part of the agreement. SOME JURISDICTIONS DO NOT ALLOW EXCLUSIONS
OF AN IMPLIED WARRANTY, SO THIS DISCLAIMER MAY NOT APPLY TO YOU AND YOU MAY
HAVE OTHER LEGAL RIGHTS THAT VARY BY JURISDICTION.
LIMITATIONS. You may not:
permit other individuals to use the Components except under the terms listed above;
modify, translate, reverse engineer, decompile, disassemble (except to the extent
applicable laws specifically prohibit such restriction), or create derivative
works (except as provided otherwise herein) based on the Components;
any of the Components other than as specified above;
lease, grant a security interest in, or otherwise transfer rights to any of the
any proprietary notices or labels on or in any of the Components.
Title, ownership rights, and intellectual property rights in all of the Components shall remain in VA and/or its
suppliers. The Components are protected by the copyright laws of the United
Kingdom and international copyright treaties. Title and related rights in the
content accessed through the Components is the property of the applicable
content owner and may be protected by applicable law. This license gives you no
rights to such content. This license does not grant you any right to any
enhancement or update to, or support or telephone assistance with respect to,
any of the Components.
The license will terminate automatically if
you fail to comply with the limitations described herein. Upon termination of
this License you agree to destroy all copies of the Components.
You may not download or otherwise
export or reexport the Components or any underlying information or technology
except in full compliance with all United States and other applicable laws and
regulations. None of the Components or underlying information or technology may
be downloaded or otherwise exported or reexported (i) into (or to a national or
resident of) Cuba, Iraq, Libya, Sudan, North Korea, Iran, Syria or any other
country to which the U.S. has embargoed goods; or (ii) to anyone on the U.S.
Treasury Department's list of Specially Designated Nationals or the U.S.
Commerce Department's Table of Denial Orders. By downloading or using the
Components, you are agreeing to the foregoing and you are representing and
warranting that you are not located in, under the control of, or a national or
resident of any such country or on any such list.
LIMITATION OF LIABILITY. UNDER NO CIRCUMSTANCES
AND UNDER NO LEGAL THEORY, TORT, CONTRACT, OR OTHERWISE, SHALL VA OR ITS
SUPPLIERS OR RESELLERS BE LIABLE TO YOU OR ANY OTHER PERSON FOR ANY INDIRECT,
SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING,
WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER
FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER COMMERCIAL DAMAGES OR LOSSES. IN
NO EVENT WILL VA BE LIABLE FOR ANY DAMAGES, EVEN IF VA SHALL HAVE BEEN INFORMED
OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY. THIS
LIMITATION OF LIABILITY SHALL NOT APPLY TO LIABILITY FOR DEATH OR PERSONAL
INJURY TO THE EXTENT APPLICABLE LAW PROHIBITS SUCH LIMITATION. FURTHERMORE,
SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL OR
CONSEQUENTIAL DAMAGES, SO THIS LIMITATION AND EXCLUSION MAY NOT APPLY TO YOU.
HIGH RISK ACTIVITIES
The Components are not fault-tolerant and are not designed, manufactured or intended for use or resale
as on-line control equipment in hazardous environments requiring fail-safe
performance, such as in the operation of nuclear facilities, aircraft
navigation or communication systems, air traffic control, direct life support
machines, or weapons systems, in which the failure of the Components could lead
directly to death, personal injury, or severe physical or environmental damage
("High Risk Activities"). VA and its suppliers specifically disclaim
any express or implied warranty of fitness for High Risk Activities.
This Agreement represents the complete agreement concerning this license and may amended only by a writing
executed by both parties. This license is personal to you and you agree not to
assign your rights in herein, and any attempted assignment by you shall be null
and void. If any provision of this Agreement is held to be unenforceable, such
provision shall be reformed only to the extent necessary to make it
enforceable. This Agreement shall be governed by English law (except for
conflict of law provisions).
By downloading the SDK you agree to the above licence terms