Programmers Reference - The Device Cookbook (1)
The Device Cookbook
A introduction to writing a device for the ConSys System./H3>
The intention of this cook book is to give a introduction to the task of writing a device class for the ConSys System. This is not a cookbook for writing Windows NT device drivers.
Contents:
Overview
Using the CSimpleDevice
Using the CParameterDevice
Using the CDevice
Overview:
The device class is used as a abstraction layer in the ConSys System kernel. The parameters that the devices exposes is the values of the parameters listed in the database. There is two basic device types, that are different in concept. The first type of device, is the real device. This device manipulates one ore more device drivers, that is, the device manipulates hardware. An example is the CG64Device class. The other kind of device is a virtual device. A virtual device does not control hardware directly. The virtual device either controls hardware through real devices, or the virtual device is used to provide information not directly related to physical properties. The most important virtual device is the CKernelDevice.
The complexity of the device classes may vary a great deal, but
the interface that they exposes to the rest of the kernel is very
simple. For creating simple device classes, the device class CSimpleDevice
is provided. This class is made for handling real devices. Below
is a description on haw to make a device class.
Using the CSimpleDevice.
This is the simplest way of creating a real device class. The CSimpleDevice class provides a number of virtual methods that must be overwritten to implement the device.
The
constructor.
First of all the constructor for the new class must be written. Initialization of internal parameters that do not need environmental information, can be made here. After the constructor is called, the AssertValid method must succeed.
CMyDevice::CMyDevice() { // Do simple initialization here }
The
dialog setup method.
When simple destruction and construction of the device is implemented create a configuration dialog. A instance of this dialog is returned by the CDevice::GetConfigDialog. If the device has need for special configuration information, or setup, overwrite this method and return a instance to the configuration dialog. It is the callers responsibility to delete the instance.
The
creation method.
The virtual method Create must now be overwritten. This method is the real initialization of the device class. This method will be called right after the constructor. The Create method has two arguments. The first argument is the entry for this device in the registry. This reference can be used to get additional information for configuration of the device. The second parameter is the CConSysEnviroment class for the kernel. This parameter will be assigned to the environment variable.
virtual void Create(CRegistryKey &aDeviceEntry, const UINT aDeviceNo) { // TODO: add extra initialization here // Call the base class Create CSimpleDevice::Create(aDeviceEntry, aDeviceNo); }
The Create method must initialize the device driver, and verify
that everything works as it should. When the Create function returns,
the status parameter for the device must be valid. The Create
method must also used the environment to access the database for
conversion factors.
The
array operator.
The array operator is the responsability of the writer. This method must provide the status of the parameters when called. The NULL address must return the status of the device. It is the responsibility of the device to cash the data for multiple requests.
const CConSysData* operator CSimpleDevice::[](CAddress* address) const { // TODO: return the requested data }
It is important to remember that this method will be called by
many different threads, some of them the same time. The write
must synchronize the access by using critical sections, or events.
The
PollDriver method.
To synchronize the device with the hardware, the PollDriver method must be implemented. This method will be called of a thread initialized at the return of the Create method of the CSimpleDevice. When the PollDriver method returns, the device assumes that the data has changed, and the data servers is notified. After notification the PollDriver method is called immediately.
void CSimpleDevice::PollDriver() { // TODO: insert code for accessing the hardware }
The write of the PollDriver method must be aware that data server
may access the cashed data while this function is running, and
appropriate synchronization must be done.
The
returnd data.
If the data returned from the array operator is of a new kind,
it is necessary to write special data server to handle this.
Using the CParameterDevice.
This device is more advanced than the CSimpleDevice. It does not contain a PollDriver method, and the user has to implement a separate thread for handling device driver IO.
Instead of signaling all data servers when data has changed, the
parameter device has a method for doing this. All data servers
attached to the device is grouped in logical groups. The data
servers in each group is signaled at the same time. Depending
on the device, the optimal grouping of the data servers may differ.
The parameter device is designed to handle CParameterAddress's,
and the grouping of the data servers is dependent on the mapping
of the CParameterAddress
to a single integer. To modify the behavior of the mapping , modify
the AddressHash method.
Using the CDevice.
When using the CDevice
directly, the programmer is responsible for notifying the data
servers. The class must also handle the driver polling, and all
other aspects of writing the device class.
References:
Last Modified 11 January 2019