Writing New Devices - target

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:

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:

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.