summaryrefslogtreecommitdiff
path: root/ecos/packages/hal/synth/arch/current/doc/synth-new-target.html
blob: 3cde39f0bec828e5d3014d4171ea6873f5ed2888 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
<!-- Copyright (C) 2002 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 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 Synthetic Target</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="AEN524"
></A
><H2
>Name</H2
>Writing New Devices&nbsp;--&nbsp;extending the synthetic target, target-side</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN527"><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN528"><P
></P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include &lt;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 &lt;cyg/infra/cyg_type.h&gt;
class mydev_init {
  public:
    mydev_init() {
        &#8230;
    }
};
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 {
    &#8230;
    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="hal-synth-arch.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"
>&nbsp;</TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Writing New Devices - host</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>