--- /dev/null
+<!-- Copyright (C) 2003 Red Hat, Inc. -->
+<!-- This material may be distributed only subject to the terms -->
+<!-- and conditions set forth in the Open Publication License, v1.0 -->
+<!-- or later (the latest version is presently available at -->
+<!-- http://www.opencontent.org/openpub/). -->
+<!-- Distribution of the work or derivative of the work in any -->
+<!-- standard (paper) book form is prohibited unless prior -->
+<!-- permission is obtained from the copyright holder. -->
+<HTML
+><HEAD
+><TITLE
+>Writing New Devices - target</TITLE
+><meta name="MSSmartTagsPreventParsing" content="TRUE">
+<META
+NAME="GENERATOR"
+CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
+"><LINK
+REL="HOME"
+TITLE="eCos Reference Manual"
+HREF="ecos-ref.html"><LINK
+REL="UP"
+TITLE="eCos Synthetic Target"
+HREF="hal-synth-arch.html"><LINK
+REL="PREVIOUS"
+TITLE="System Calls"
+HREF="synth-syscalls.html"><LINK
+REL="NEXT"
+TITLE="Writing New Devices - host"
+HREF="synth-new-host.html"></HEAD
+><BODY
+CLASS="REFENTRY"
+BGCOLOR="#FFFFFF"
+TEXT="#000000"
+LINK="#0000FF"
+VLINK="#840084"
+ALINK="#0000FF"
+><DIV
+CLASS="NAVHEADER"
+><TABLE
+SUMMARY="Header navigation table"
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TH
+COLSPAN="3"
+ALIGN="center"
+>eCos Reference Manual</TH
+></TR
+><TR
+><TD
+WIDTH="10%"
+ALIGN="left"
+VALIGN="bottom"
+><A
+HREF="synth-syscalls.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="80%"
+ALIGN="center"
+VALIGN="bottom"
+></TD
+><TD
+WIDTH="10%"
+ALIGN="right"
+VALIGN="bottom"
+><A
+HREF="synth-new-host.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+></TABLE
+><HR
+ALIGN="LEFT"
+WIDTH="100%"></DIV
+><H1
+><A
+NAME="SYNTH-NEW-TARGET">Writing New Devices - target</H1
+><DIV
+CLASS="REFNAMEDIV"
+><A
+NAME="AEN18180"
+></A
+><H2
+>Name</H2
+>Writing New Devices -- extending the synthetic target, target-side</DIV
+><DIV
+CLASS="REFSYNOPSISDIV"
+><A
+NAME="AEN18183"><H2
+>Synopsis</H2
+><DIV
+CLASS="FUNCSYNOPSIS"
+><A
+NAME="AEN18184"><P
+></P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="FUNCSYNOPSISINFO"
+>#include <cyg/hal/hal_io.h>
+ </PRE
+></TD
+></TR
+></TABLE
+><P
+><CODE
+><CODE
+CLASS="FUNCDEF"
+>int synth_auxiliary_instantiate</CODE
+>(const char* package, const char* version, const char* device, const char* instance, const char* data);</CODE
+></P
+><P
+><CODE
+><CODE
+CLASS="FUNCDEF"
+>void synth_auxiliary_xchgmsg</CODE
+>(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);</CODE
+></P
+><P
+></P
+></DIV
+></DIV
+><DIV
+CLASS="REFSECT1"
+><A
+NAME="SYNTH-NEW-TARGET-DESCRIPTION"
+></A
+><H2
+>Description</H2
+><P
+>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 <TT
+CLASS="FUNCTION"
+>can_send</TT
+>,
+<TT
+CLASS="FUNCTION"
+>send</TT
+>, <TT
+CLASS="FUNCTION"
+>recv</TT
+> and similar
+functions. Many devices will involve interrupts, so the driver
+contains ISR and DSR functions and will call
+<TT
+CLASS="FUNCTION"
+>cyg_drv_interrupt_create</TT
+>,
+<TT
+CLASS="FUNCTION"
+>cyg_drv_interrupt_acknowledge</TT
+>, and related
+functions.
+ </P
+><P
+>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
+<TT
+CLASS="FUNCTION"
+>synth_auxiliary_xchgmsg</TT
+> for this purpose.
+ </P
+><P
+>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 <TT
+CLASS="FUNCTION"
+>synth_auxiliary_instantiate</TT
+>. 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.
+ </P
+><P
+>Use of the I/O auxiliary is optional: if the user does not specify
+<TT
+CLASS="OPTION"
+>--io</TT
+> 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
+<TT
+CLASS="VARNAME"
+>synth_auxiliary_running</TT
+> which should be checked.
+ </P
+></DIV
+><DIV
+CLASS="REFSECT1"
+><A
+NAME="SYNTH-NEW-TARGET-INSTANTIATE"
+></A
+><H2
+>Instantiating a Device</H2
+><P
+>Device instantiation should happen during the C++ prioritized static
+constructor phase of system initialization, before control switches to
+<TT
+CLASS="FUNCTION"
+>cyg_user_start</TT
+> 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
+<TT
+CLASS="FILENAME"
+>mainrc.tcl</TT
+> script, and make the main window
+visible.
+ </P
+><P
+>For standard devices generic eCos I/O code will call the device
+initialization routines at the right time, iterating through the
+<TT
+CLASS="VARNAME"
+>DEVTAB</TT
+> 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:
+ </P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>#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);</PRE
+></TD
+></TR
+></TABLE
+><P
+>Some care has to be taken because the object
+<TT
+CLASS="VARNAME"
+>mydev_init_object</TT
+> 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 <TT
+CLASS="FILENAME"
+>libextras.a</TT
+>:
+ </P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>cdl_package CYGPKG_DEVS_MINE {
+ …
+ compile -library=libextras.a init.cxx
+}</PRE
+></TD
+></TR
+></TABLE
+><P
+>For devices inside application code the same can be achieved by
+linking the relevant module as a <TT
+CLASS="FILENAME"
+>.o</TT
+> file rather
+than putting it in a <TT
+CLASS="FILENAME"
+>.a</TT
+> library.
+ </P
+><P
+>In the device initialization routine the main operation is a call to
+<TT
+CLASS="FUNCTION"
+>synth_auxiliary_instantiate</TT
+>. This takes five
+arguments, all of which should be strings:
+ </P
+><P
+></P
+><DIV
+CLASS="VARIABLELIST"
+><DL
+><DT
+><TT
+CLASS="VARNAME"
+>package</TT
+></DT
+><DD
+><P
+>For device drivers which are eCos packages this should be a directory
+path relative to the eCos repository, for example
+<TT
+CLASS="LITERAL"
+>devs/eth/synth/ecosynth</TT
+>. 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 <TT
+CLASS="FILENAME"
+>~/.ecos/synth</TT
+>
+instead.
+ </P
+></DD
+><DT
+><TT
+CLASS="VARNAME"
+>version</TT
+></DT
+><DD
+><P
+>For eCos packages this argument should be the version of the package
+that is being used, for example <TT
+CLASS="LITERAL"
+>current</TT
+>. A simple
+way to get this version is to use the
+<TT
+CLASS="FUNCTION"
+>SYNTH_MAKESTRING</TT
+> macro on the package name.
+If the device is application-specific then a NULL pointer should be
+used.
+ </P
+></DD
+><DT
+><TT
+CLASS="VARNAME"
+>device</TT
+></DT
+><DD
+><P
+>This argument specifies the type of device being instantiated, for
+example <TT
+CLASS="LITERAL"
+>ethernet</TT
+>. More specifically the I/O
+auxiliary will append a <TT
+CLASS="FILENAME"
+>.tcl</TT
+> 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.
+ </P
+></DD
+><DT
+><TT
+CLASS="VARNAME"
+>instance</TT
+></DT
+><DD
+><P
+>If it is possible to have multiple instances of a device then this
+argument identifies the particular instance, for example
+<TT
+CLASS="LITERAL"
+>eth0</TT
+> or <TT
+CLASS="LITERAL"
+>eth1</TT
+>. Otherwise a NULL
+pointer can be used.
+ </P
+></DD
+><DT
+><TT
+CLASS="VARNAME"
+>data</TT
+></DT
+><DD
+><P
+>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.
+ </P
+></DD
+></DL
+></DIV
+><P
+>Typical usage would look like:
+ </P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+> if (!synth_auxiliary_running) {
+ return;
+ }
+ id = synth_auxiliary_instantiate("devs/eth/synth/ecosynth",
+ SYNTH_MAKESTRING(CYGPKG_DEVS_ETH_ECOSYNTH),
+ "ethernet",
+ "eth0",
+ (const char*) 0);</PRE
+></TD
+></TR
+></TABLE
+><P
+>The return value will be a device identifier which can be used for
+subsequent calls to <TT
+CLASS="FUNCTION"
+>synth_auxiliary_xchgmsg</TT
+>. If
+the device could not be instantiated then <TT
+CLASS="LITERAL"
+>-1</TT
+> 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.
+ </P
+><P
+>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 <A
+HREF="synth-new-target.html#SYNTH-NEW-TARGET-INTERRUPTS"
+>interrupt vector</A
+>, and
+whether or not multicasting is supported.
+ </P
+></DIV
+><DIV
+CLASS="REFSECT1"
+><A
+NAME="SYNTH-NEW-TARGET-XCHGMSG"
+></A
+><H2
+>Communicating with a Device</H2
+><P
+>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.
+ </P
+><P
+>There is a single function to perform I/O operations,
+<TT
+CLASS="FUNCTION"
+>synth_auxiliary_xchgmsg</TT
+>. This takes the following
+arguments:
+ </P
+><P
+></P
+><DIV
+CLASS="VARIABLELIST"
+><DL
+><DT
+><TT
+CLASS="VARNAME"
+>device_id</TT
+></DT
+><DD
+><P
+>This should be one of the identifiers returned by a previous
+call to <TT
+CLASS="FUNCTION"
+>synth_auxiliary_instantiate</TT
+>, specifying the
+particular device which should perform some I/O.
+ </P
+></DD
+><DT
+><TT
+CLASS="VARNAME"
+>request</TT
+></DT
+><DD
+><P
+>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.
+ </P
+></DD
+><DT
+><TT
+CLASS="VARNAME"
+>arg1</TT
+>, <TT
+CLASS="VARNAME"
+>arg2</TT
+></DT
+><DD
+><P
+>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 <TT
+CLASS="VARNAME"
+>arg1</TT
+>
+controlling whether this mode should be enabled or disabled. Both
+<TT
+CLASS="VARNAME"
+>arg1</TT
+> and <TT
+CLASS="VARNAME"
+>arg2</TT
+> should be signed
+32-bit integers, and their values are interpreted only by the
+device-specific Tcl script.
+ </P
+></DD
+><DT
+><TT
+CLASS="VARNAME"
+>txdata</TT
+>, <TT
+CLASS="VARNAME"
+>txlen</TT
+></DT
+><DD
+><P
+>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 <TT
+CLASS="VARNAME"
+>arg1</TT
+>
+and <TT
+CLASS="VARNAME"
+>arg2</TT
+>, so those parameters have to be placed in
+a suitable buffer and extracted at the other end.
+<TT
+CLASS="VARNAME"
+>txdata</TT
+> is an arbitrary buffer of
+<TT
+CLASS="VARNAME"
+>txlen</TT
+> 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.
+ </P
+></DD
+><DT
+><TT
+CLASS="VARNAME"
+>reply</TT
+></DT
+><DD
+><P
+>If the host-side is expected to send a reply message then
+<TT
+CLASS="VARNAME"
+>reply</TT
+> 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 <TT
+CLASS="VARNAME"
+>reply</TT
+> argument
+should be a NULL pointer; otherwise the host-side must always send
+a reply code and the <TT
+CLASS="VARNAME"
+>reply</TT
+> argument must be valid.
+ </P
+></DD
+><DT
+><TT
+CLASS="VARNAME"
+>rxdata</TT
+>, <TT
+CLASS="VARNAME"
+>rxlen</TT
+></DT
+><DD
+><P
+>Some operations may involve additional data coming from the host-side,
+for example an incoming ethernet packet. <TT
+CLASS="VARNAME"
+>rxdata</TT
+>
+should be a suitably-sized buffer, and <TT
+CLASS="VARNAME"
+>rxlen</TT
+> 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
+<TT
+CLASS="VARNAME"
+>reply</TT
+> argument was not NULL.
+ </P
+></DD
+><DT
+><TT
+CLASS="VARNAME"
+>max_rxlen</TT
+></DT
+><DD
+><P
+>If a reply to this message is expected and that reply may involve
+additional data, <TT
+CLASS="VARNAME"
+>max_rxlen</TT
+> limits the size of that
+reply. In other words, it corresponds to the size of the
+<TT
+CLASS="VARNAME"
+>rxdata</TT
+> buffer.
+ </P
+></DD
+></DL
+></DIV
+><P
+>Most I/O operations involve only some of the arguments. For example
+transmitting an ethernet packet would use the
+<TT
+CLASS="VARNAME"
+>request</TT
+>, <TT
+CLASS="VARNAME"
+>txdata</TT
+> and
+<TT
+CLASS="VARNAME"
+>txlen</TT
+> fields (in addition to
+<TT
+CLASS="VARNAME"
+>device_id</TT
+> which is always required), but would not
+involve <TT
+CLASS="VARNAME"
+>arg1</TT
+> or <TT
+CLASS="VARNAME"
+>arg2</TT
+> and no
+reply would be expected. Receiving an ethernet packet would involve
+<TT
+CLASS="VARNAME"
+>request</TT
+>, <TT
+CLASS="VARNAME"
+>rxdata</TT
+>,
+<TT
+CLASS="VARNAME"
+>rxlen</TT
+> and <TT
+CLASS="VARNAME"
+>max_rxlen</TT
+>; in addition
+<TT
+CLASS="VARNAME"
+>reply</TT
+> 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 <TT
+CLASS="VARNAME"
+>request</TT
+> and <TT
+CLASS="VARNAME"
+>arg1</TT
+>,
+but none of the remaining arguments.
+ </P
+></DIV
+><DIV
+CLASS="REFSECT1"
+><A
+NAME="SYNTH-NEW-TARGET-INTERRUPTS"
+></A
+><H2
+>Interrupt Handling</H2
+><P
+>Interrupt handling in the synthetic target is much the same as on a
+real target. An interrupt object is created using
+<TT
+CLASS="FUNCTION"
+>cyg_drv_interrupt_create</TT
+>, 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.
+ </P
+><P
+>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
+<TT
+CLASS="FUNCTION"
+>synth_auxiliary_xchgmsg</TT
+> to perform the I/O
+operations.
+ </P
+><P
+>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.
+ </P
+></DIV
+><DIV
+CLASS="NAVFOOTER"
+><HR
+ALIGN="LEFT"
+WIDTH="100%"><TABLE
+SUMMARY="Footer navigation table"
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+><A
+HREF="synth-syscalls.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="ecos-ref.html"
+ACCESSKEY="H"
+>Home</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+><A
+HREF="synth-new-host.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+>System Calls</TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="hal-synth-arch.html"
+ACCESSKEY="U"
+>Up</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+>Writing New Devices - host</TD
+></TR
+></TABLE
+></DIV
+></BODY
+></HTML
+>
\ No newline at end of file
projects / karo-tx-redboot.git / blobdiff