synth-new-target.html

ecos3.0 beta 的官方文档,html格式

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 <CODE
CLASS="FUNCTION"
>synth_auxiliary_xchgmsg</CODE
>. 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,
<CODE
CLASS="FUNCTION"
>synth_auxiliary_xchgmsg</CODE
>. This takes the following
arguments: 
    </P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><CODE
CLASS="VARNAME"
>device_id</CODE
></DT
><DD
><P
>This should be one of the identifiers returned by a previous
call to <CODE
CLASS="FUNCTION"
>synth_auxiliary_instantiate</CODE
>, specifying the
particular device which should perform some I/O.
         </P
></DD
><DT
><CODE
CLASS="VARNAME"
>request</CODE
></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
><CODE
CLASS="VARNAME"
>arg1</CODE
>, <CODE
CLASS="VARNAME"
>arg2</CODE
></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 <CODE
CLASS="VARNAME"
>arg1</CODE
>
controlling whether this mode should be enabled or disabled. Both
<CODE
CLASS="VARNAME"
>arg1</CODE
> and <CODE
CLASS="VARNAME"
>arg2</CODE
> should be signed
32-bit integers, and their values are interpreted only by the
device-specific Tcl script.
         </P
></DD
><DT
><CODE
CLASS="VARNAME"
>txdata</CODE
>, <CODE
CLASS="VARNAME"
>txlen</CODE
></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 <CODE
CLASS="VARNAME"
>arg1</CODE
>
and <CODE
CLASS="VARNAME"
>arg2</CODE
>, so those parameters have to be placed in
a suitable buffer and extracted at the other end.
<CODE
CLASS="VARNAME"
>txdata</CODE
> is an arbitrary buffer of
<CODE
CLASS="VARNAME"
>txlen</CODE
> 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
><CODE
CLASS="VARNAME"
>reply</CODE
></DT
><DD
><P
>If the host-side is expected to send a reply message then
<CODE
CLASS="VARNAME"
>reply</CODE
> 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 <CODE
CLASS="VARNAME"
>reply</CODE
> argument
should be a NULL pointer; otherwise the host-side must always send
a reply code and the <CODE
CLASS="VARNAME"
>reply</CODE
> argument must be valid.
         </P
></DD
><DT
><CODE
CLASS="VARNAME"
>rxdata</CODE
>, <CODE
CLASS="VARNAME"
>rxlen</CODE
></DT
><DD
><P
>Some operations may involve additional data coming from the host-side,
for example an incoming ethernet packet. <CODE
CLASS="VARNAME"
>rxdata</CODE
>
should be a suitably-sized buffer, and <CODE
CLASS="VARNAME"
>rxlen</CODE
> 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
<CODE
CLASS="VARNAME"
>reply</CODE
> argument was not NULL.
         </P
></DD
><DT
><CODE
CLASS="VARNAME"
>max_rxlen</CODE
></DT
><DD
><P
>If a reply to this message is expected and that reply may involve
additional data, <CODE
CLASS="VARNAME"
>max_rxlen</CODE
> limits the size of that
reply. In other words, it corresponds to the size of the
<CODE
CLASS="VARNAME"
>rxdata</CODE
> 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
<CODE
CLASS="VARNAME"
>request</CODE
>, <CODE
CLASS="VARNAME"
>txdata</CODE
> and
<CODE
CLASS="VARNAME"
>txlen</CODE
> fields (in addition to
<CODE
CLASS="VARNAME"
>device_id</CODE
> which is always required), but would not
involve <CODE
CLASS="VARNAME"
>arg1</CODE
> or <CODE
CLASS="VARNAME"
>arg2</CODE
> and no
reply would be expected. Receiving an ethernet packet would involve
<CODE
CLASS="VARNAME"
>request</CODE
>, <CODE
CLASS="VARNAME"
>rxdata</CODE
>,
<CODE
CLASS="VARNAME"
>rxlen</CODE
> and <CODE
CLASS="VARNAME"
>max_rxlen</CODE
>; in addition
<CODE
CLASS="VARNAME"
>reply</CODE
> 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 <CODE
CLASS="VARNAME"
>request</CODE
> and <CODE
CLASS="VARNAME"
>arg1</CODE
>,
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
<CODE
CLASS="FUNCTION"
>cyg_drv_interrupt_create</CODE
>, 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
<CODE
CLASS="FUNCTION"
>synth_auxiliary_xchgmsg</CODE
> 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
>