VirtualAcorn Support:
Podule SDK (Software Development Kit)

SDK Overview

Introduction

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.

Concepts

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.

Component construction/destruction.

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

[ ]

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

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 SDK

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.

Plugin files

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.

VirtualAcorn

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 Header Files.

VA may revise any of the Components from time to time without notice.

FEES.

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;

copy any of the Components other than as specified above;

rent, lease, grant a security interest in, or otherwise transfer rights to any of the Components; or

remove any proprietary notices or labels on or in any of the Components.

TITLE

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.

TERMINATION

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.

EXPORT CONTROLS

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.

MISCELLANEOUS

By downloading the SDK you agree to the above licence terms