Writing New Devices - target

Name

Writing New Devices -- extending the synthetic target, target-side

Synopsis

#include <cyg/hal/hal_io.h>
      

int synth_auxiliary_instantiate(const char* package, const char* version, const char* device, const char* instance, const char* data);

void synth_auxiliary_xchgmsg(int device_id, int request, int arg1, int arg2, const unsigned char* txdata, int txlen, int* reply, unsigned char* rxdata, int* rxlen, int max_rxlen);

Description

In some ways writing a device driver for the synthetic target is very similar to writing one for a real target. Obviously it has to provide the standard interface for that class of device, so for example an ethernet device has to provide can_send, send, recv and similar functions. Many devices will involve interrupts, so the driver contains ISR and DSR functions and will call cyg_drv_interrupt_create, cyg_drv_interrupt_acknowledge, and related functions.

In other ways writing a device driver for the synthetic target is very different. Usually the driver will not have any direct access to the underlying hardware. In fact for some devices the I/O may not involve real hardware, instead everything is emulated by widgets on the graphical display. Therefore the driver cannot just peek and poke device registers, instead it must interact with host-side code by exchanging message. The synthetic target HAL provides a function synth_auxiliary_xchgmsg for this purpose.

Initialization of a synthetic target device driver is also very different. On real targets the device hardware already exists when the driver's initialization routine runs. On the synthetic target it is first necessary to instantiate the device inside the I/O auxiliary, by a call to synth_auxiliary_instantiate. That function performs a special message exchange with the I/O auxiliary, causing it to load a Tcl script for the desired type of device and run an instantiation procedure within that script.

Use of the I/O auxiliary is optional: if the user does not specify --io on the command line then the auxiliary will not be started and hence most I/O operations will not be possible. Device drivers should allow for this possibility, for example by just discarding any data that gets written. The HAL exports a flag synth_auxiliary_running which should be checked.

Instantiating a Device

Device instantiation should happen during the C++ prioritized static constructor phase of system initialization, before control switches to cyg_user_start and general application code. This ensures that there is a clearly defined point at which the I/O auxiliary knows that all required devices have been loaded. It can then perform various consistency checks and clean-ups, run the user's mainrc.tcl script, and make the main window visible.

For standard devices generic eCos I/O code will call the device initialization routines at the right time, iterating through the DEVTAB table in a static constructor. The same holds for network devices and file systems. For more custom devices code like the following can be used:

#include <cyg/infra/cyg_type.h>
class mydev_init {
  public:
    mydev_init() {
        …
    }
};
static mydev_init mydev_init_object CYGBLD_ATTRIB_INIT_PRI(CYG_INIT_IO);

Some care has to be taken because the object mydev_init_object will typically not be referenced by other code, and hence may get eliminated at link-time. If the code is part of an eCos package then problems can be avoided by putting the relevant file in libextras.a:

cdl_package CYGPKG_DEVS_MINE {
    …
    compile -library=libextras.a init.cxx
}

For devices inside application code the same can be achieved by linking the relevant module as a .o file rather than putting it in a .a library.

In the device initialization routine the main operation is a call to synth_auxiliary_instantiate. This takes five arguments, all of which should be strings:

package

For device drivers which are eCos packages this should be a directory path relative to the eCos repository, for example devs/eth/synth/ecosynth. This will allow the I/O auxiliary to find the various host-side support files for this package within the install tree. If the device is application-specific and not part of an eCos package then a NULL pointer can be used, causing the I/O auxiliary to search for the support files in the current directory and then in ~/.ecos/synth instead.

version

For eCos packages this argument should be the version of the package that is being used, for example current. A simple way to get this version is to use the SYNTH_MAKESTRING macro on the package name. If the device is application-specific then a NULL pointer should be used.

device

This argument specifies the type of device being instantiated, for example ethernet. More specifically the I/O auxiliary will append a .tcl suffix, giving the name of a Tcl script that will handle all I/O requests for the device. If the application requires several instances of a type of device then the script will only be loaded once, but the script will contain an instantiation procedure that will be called for each device instance.

instance

If it is possible to have multiple instances of a device then this argument identifies the particular instance, for example eth0 or eth1. Otherwise a NULL pointer can be used.

data

This argument can be used to pass additional initialization data from eCos to the host-side support. This is useful for devices where eCos configury must control certain aspects of the device, rather than host-side configury such as the target definition file, because eCos has compile-time dependencies on some or all of the relevant options. An example might be an emulated frame buffer where eCos has been statically configured for a particular screen size, orientation and depth. There is no fixed format for this string, it will be interpreted only by the device-specific host-side Tcl script. However the string length should be limited to a couple of hundred bytes to avoid possible buffer overflow problems.

Typical usage would look like:

    if (!synth_auxiliary_running) {
      return;
    }
    id = synth_auxiliary_instantiate("devs/eth/synth/ecosynth",
             SYNTH_MAKESTRING(CYGPKG_DEVS_ETH_ECOSYNTH),
             "ethernet",
             "eth0",
             (const char*) 0);

The return value will be a device identifier which can be used for subsequent calls to synth_auxiliary_xchgmsg. If the device could not be instantiated then -1 will be returned. It is the responsibility of the host-side software to issue suitable diagnostics explaining what went wrong, so normally the target-side code should fail silently.

Once the desired device has been instantiated, often it will be necessary to do some additional initialization by a message exchange. For example an ethernet device might need information from the host-side about the MAC address, the interrupt vector, and whether or not multicasting is supported.

Communicating with a Device

Once a device has been instantiated it is possible to perform I/O by sending messages to the appropriate Tcl script running inside the auxiliary, and optionally getting back replies. I/O operations are always initiated by the eCos target-side, it is not possible for the host-side software to initiate data transfers. However the host-side can raise interrupts, and the interrupt handler inside the target can then exchange one or more messages with the host.

There is a single function to perform I/O operations, synth_auxiliary_xchgmsg. This takes the following arguments:

device_id

This should be one of the identifiers returned by a previous call to synth_auxiliary_instantiate, specifying the particular device which should perform some I/O.

request

Request are just signed 32-bit integers that identify the particular I/O operation being requested. There is no fixed set of codes, instead each type of device can define its own.

arg1, arg2

For some requests it is convenient to pass one or two additional parameters alongside the request code. For example an ethernet device could define a multicast-all request, with arg1 controlling whether this mode should be enabled or disabled. Both arg1 and arg2 should be signed 32-bit integers, and their values are interpreted only by the device-specific Tcl script.

txdata, txlen

Some I/O operations may involve sending additional data, for example an ethernet packet. Alternatively a control operation may require many more parameters than can easily be encoded in arg1 and arg2, so those parameters have to be placed in a suitable buffer and extracted at the other end. txdata is an arbitrary buffer of txlen bytes that should be sent to the host-side. There is no specific upper bound on the number of bytes that can be sent, but usually it is a good idea to allocate the transmit buffer statically and keep transfers down to at most several kilobytes.

reply

If the host-side is expected to send a reply message then reply should be a pointer to an integer variable and will be updated with a reply code, a simple 32-bit integer. The synthetic target HAL code assumes that the host-side and target-side agree on the protocol being used: if the host-side will not send a reply to this message then the reply argument should be a NULL pointer; otherwise the host-side must always send a reply code and the reply argument must be valid.

rxdata, rxlen

Some operations may involve additional data coming from the host-side, for example an incoming ethernet packet. rxdata should be a suitably-sized buffer, and rxlen a pointer to an integer variable that will end up containing the number of bytes that were actually received. These arguments will only be used if the host-side is expected to send a reply and hence the reply argument was not NULL.

max_rxlen

If a reply to this message is expected and that reply may involve additional data, max_rxlen limits the size of that reply. In other words, it corresponds to the size of the rxdata buffer.

Most I/O operations involve only some of the arguments. For example transmitting an ethernet packet would use the request, txdata and txlen fields (in addition to device_id which is always required), but would not involve arg1 or arg2 and no reply would be expected. Receiving an ethernet packet would involve request, rxdata, rxlen and max_rxlen; in addition reply is needed to get any reply from the host-side at all, and could be used to indicate whether or not any more packets are buffered up. A control operation such as enabling multicast mode would involve request and arg1, but none of the remaining arguments.

Interrupt Handling

Interrupt handling in the synthetic target is much the same as on a real target. An interrupt object is created using cyg_drv_interrupt_create, attached, and unmasked. The emulated device - in other words the Tcl script running inside the I/O auxiliary - can raise an interrupt. Subject to interrupts being disabled and the appropriate vector being masked, the system will invoke the specified ISR function. The synthetic target HAL implementation does have some limitations: there is no support for nested interrupts, interrupt priorities, or a separate interrupt stack. Supporting those might be appropriate when targetting a simulator that attempts to model real hardware accurately, but not for the simple emulation provided by the synthetic target.

Of course the actual implementation of the ISR and DSR functions will be rather different for a synthetic target device driver. For real hardware the device driver will interact with the device by reading and writing device registers, managing DMA engines, and the like. A synthetic target driver will instead call synth_auxiliary_xchgmsg to perform the I/O operations.

There is one other significant difference between interrupt handling on the synthetic target and on real hardware. Usually the eCos code will know which interrupt vectors are used for which devices. That information is fixed when the target hardware is designed. With the synthetic target interrupt vectors are assigned to devices on the host side, either via the target definition file or dynamically when the device is instantiated. Therefore the initialization code for a target-side device driver will need to request interrupt vector information from the host-side, via a message exchange. Such interrupt vectors will be in the range 1 to 31 inclusive, with interrupt 0 being reserved for the real-time clock.