OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-3.0/] [packages/] [io/] [common/] [current/] [doc/] [io.sgml] - Blame information for rev 825

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 786 skrzyp
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
I/O Package (Device Drivers)
32
 
33
34
 
35
36
Introduction
37
 
38
39
The I/O package is designed as a general purpose framework for
40
supporting device drivers. This includes all classes of
41
drivers from simple serial to networking stacks and beyond.
42
43
 
44
45
Components of the I/O package, such as device drivers, are
46
configured into the system just like all other components.
47
Additionally, end users may add their own drivers to this set.
48
49
 
50
51
While the set of drivers (and the devices they represent) may be
52
considered static, they must be accessed via an opaque
53
“handle”. Each device in the system has a unique name and
54
the cyg_io_lookup() function is used to map that
55
name onto the handle for the device. This “hiding” of the
56
device implementation allows for generic, named devices, as well as
57
more flexibility. Also, the cyg_io_lookup()
58
function provides drivers the opportunity to initialize the device
59
when usage actually starts.
60
61
 
62
63
All devices have a name. The standard provided devices use names such
64
as “/dev/console” and
65
“/dev/serial0”, where the
66
“/dev/” prefix indicates that this is
67
the name of a device.
68
69
 
70
The entire I/O package API, as well as the standard
71
set of provided drivers, is written in C. 
72
 
73
Basic functions are provided to send data to and receive data
74
from a device. The details of how this is done is left to the device [class] itself.
75
For example, writing data to a block device like a disk drive may
76
have different semantics than writing to a serial port. 
77
 
78
Additional functions are provided to manipulate the state
79
of the driver and/or the actual device. These functions
80
are, by design, quite specific to the actual driver. 
81
 
82
This driver model supports layering; in other words, a device
83
may actually be created “on top of” another device.
84
For example, the “tty” (terminal-like) devices are
85
built on top of simple serial devices. The upper layer then has
86
the flexibility to add features and functions not found at the lower
87
layers. In this case the “tty” device provides
88
for line buffering and editing not available from the simple serial
89
drivers.
90
91
 
92
Some drivers will support visibility of the layers they depend
93
upon. The “tty” driver allows information about
94
the actual serial device to be manipulated by passing get/set
95
config calls that use a serial driver “key” down
96
to the serial driver itself. 
97
 
98
99
 
100
101
102
 
103
104
<!-- <index></index> -->User API
105
 
106
107
All functions, except cyg_io_lookup()
108
require an I/O “handle”.
109
110
 
111
112
All functions return a value of the type Cyg_ErrNo. If an
113
error condition is detected, this value will be negative and the
114
absolute value indicates the actual error, as specified in
115
cyg/error/codes.h. The only other legal return
116
value will be ENOERR. All other function arguments
117
are pointers (references). This allows the drivers to pass information
118
efficiently, both into and out of the driver. The most striking
119
example of this is the “length” value passed to the read
120
and write functions. This parameter contains the desired length of
121
data on input to the function and the actual transferred length on
122
return.
123
124
 
125
126
// Lookup a device and return its handle
127
  Cyg_ErrNo cyg_io_lookup(
128
    const char *name,
129
    cyg_io_handle_t *handle )
130
131
 
132
133
This function maps a device name onto an appropriate handle. If the
134
named device is not in the system, then the error
135
-ENOENT is returned. If the device is found, then
136
the handle for the device is returned by way of the handle pointer
137
*handle.
138
139
 
140
141
// Write data to a device
142
Cyg_ErrNo cyg_io_write(
143
    cyg_io_handle_t handle,
144
    const void *buf,
145
    cyg_uint32 *len )
146
147
 
148
149
This function sends data to a device. The size of data to send is
150
contained in *len and the actual size sent will
151
be returned in the same place.
152
153
 
154
155
// Read data from a device
156
Cyg_ErrNo cyg_io_read(
157
    cyg_io_handle_t handle,
158
    void *buf,
159
    cyg_uint32 *len )
160
161
 
162
163
This function receives data from a device. The desired size of data to
164
receive is contained in *len and the actual
165
size obtained will be returned in the same place.
166
167
 
168
169
// Get the configuration of a device
170
Cyg_ErrNo cyg_io_get_config(
171
    cyg_io_handle_t handle,
172
    cyg_uint32 key,
173
    void *buf,
174
    cyg_uint32 *len )
175
176
 
177
178
This function is used to obtain run-time configuration about a
179
device. The type of information retrieved is specified by the
180
key. The data will be returned in the given
181
buffer. The value of *len should contain the
182
amount of data requested, which must be at least as large as the size
183
appropriate to the selected key. The actual size of data retrieved is
184
placed in  *len. The appropriate key values
185
differ for each driver and are all listed in the file
186
<cyg/io/config_keys.h>.
187
188
 
189
190
// Change the configuration of a device
191
Cyg_ErrNo cyg_io_set_config(
192
    cyg_io_handle_t handle,
193
    cyg_uint32 key,
194
    const void *buf,
195
    cyg_uint32 *len )
196
197
 
198
199
This function is used to manipulate or change the run-time
200
configuration of a device. The type of information is specified by the
201
key. The data will be obtained from the given
202
buffer. The value of *len should contain the
203
amount of data provided, which must match the size appropriate to the
204
selected key.  The appropriate key values differ for each driver and
205
are all listed in the file
206
<cyg/io/config_keys.h>.
207
208
 
209
210
 
211
212
213
 
214
215
Serial driver details
216
 
217
218
Two different classes of serial drivers are provided as a standard
219
part of the eCos system. These are described as “raw
220
serial” (serial) and “tty-like” (tty).
221
222
 
223
224
 
225
226
Raw Serial Driver
227
 
228
229
Use the include file <cyg/io/serialio.h> for
230
this driver.
231
232
 
233
234
The raw serial driver is capable of sending
235
and receiving blocks of raw data to a serial device. Controls are
236
provided to configure the actual hardware, but there is no manipulation
237
of the data by this driver.
238
239
 
240
241
There may be many instances of this driver in a given system,
242
one for each serial channel. Each channel corresponds to a physical
243
device and there will typically be a device module created for this
244
purpose. The device modules themselves are configurable, allowing
245
specification of the actual hardware details, as well as such details
246
as whether the channel should be buffered by the serial driver,
247
etc.
248
249
 
250
251
 
252
253
Runtime Configuration
254
 
255
256
Runtime configuration is achieved by exchanging data structures with
257
the driver via the cyg_io_set_config() and
258
cyg_io_get_config() functions.
259
260
 
261
262
typedef struct {
263
 cyg_serial_baud_rate_t baud;
264
 cyg_serial_stop_bits_t stop;
265
 cyg_serial_parity_t parity;
266
 cyg_serial_word_length_t word_length;
267
 cyg_uint32 flags;
268
} cyg_serial_info_t;
269
270
 
271
272
The field word_length contains the number of data bits per word
274
(character). This must be one of the values:
275
276
 
277
278
 CYGNUM_SERIAL_WORD_LENGTH_5
279
 CYGNUM_SERIAL_WORD_LENGTH_6
280
 CYGNUM_SERIAL_WORD_LENGTH_7
281
 CYGNUM_SERIAL_WORD_LENGTH_8
282
283
 
284
285
The field baud contains a baud rate selection.  This must be
287
one of the values:
288
289
 
290
291
 CYGNUM_SERIAL_BAUD_50
292
 CYGNUM_SERIAL_BAUD_75
293
 CYGNUM_SERIAL_BAUD_110
294
 CYGNUM_SERIAL_BAUD_134_5
295
 CYGNUM_SERIAL_BAUD_150
296
 CYGNUM_SERIAL_BAUD_200
297
 CYGNUM_SERIAL_BAUD_300
298
 CYGNUM_SERIAL_BAUD_600
299
 CYGNUM_SERIAL_BAUD_1200
300
 CYGNUM_SERIAL_BAUD_1800
301
 CYGNUM_SERIAL_BAUD_2400
302
 CYGNUM_SERIAL_BAUD_3600
303
 CYGNUM_SERIAL_BAUD_4800
304
 CYGNUM_SERIAL_BAUD_7200
305
 CYGNUM_SERIAL_BAUD_9600
306
 CYGNUM_SERIAL_BAUD_14400
307
 CYGNUM_SERIAL_BAUD_19200
308
 CYGNUM_SERIAL_BAUD_38400
309
 CYGNUM_SERIAL_BAUD_57600
310
 CYGNUM_SERIAL_BAUD_115200
311
 CYGNUM_SERIAL_BAUD_234000
312
313
 
314
The field stop contains the number of stop bits. This must be
316
one of the values:
317
 
318
319
 CYGNUM_SERIAL_STOP_1
320
 CYGNUM_SERIAL_STOP_1_5
321
 CYGNUM_SERIAL_STOP_2
322
323
 
324
325
Note
326
327
On most hardware, a selection of 1.5 stop bits is only valid
328
if the word (character) length is 5.
329
330
331
 
332
The field parity contains the parity mode.  This must be one of
334
the values: 
335
 
336
337
 CYGNUM_SERIAL_PARITY_NONE
338
 CYGNUM_SERIAL_PARITY_EVEN
339
 CYGNUM_SERIAL_PARITY_ODD
340
 CYGNUM_SERIAL_PARITY_MARK
341
 CYGNUM_SERIAL_PARITY_SPACE
342
343
 
344
The field flags is a bitmask which controls the behavior of the
346
serial device driver. It should be built from the values
347
CYG_SERIAL_FLAGS_xxx defined below:
348
349
 
350
351
#define CYG_SERIAL_FLAGS_RTSCTS 0x0001
352
353
 
354
If this bit is set then the port is placed in “hardware
355
handshake” mode. In this mode, the CTS and RTS pins control
356
when data is allowed to be sent/received at the port. This
357
bit is ignored if the hardware does not support this level of
358
handshake.
359
360
 
361
362
typedef struct {
363
  cyg_int32 rx_bufsize;
364
  cyg_int32 rx_count;
365
  cyg_int32 tx_bufsize;
366
  cyg_int32 tx_count;
367
} cyg_serial_buf_info_t;
368
369
 
370
The field rx_bufsize contains
371
the total size of the incoming data buffer. This is set to zero on
372
devices that do not support buffering (i.e. polled devices).
373
 
374
The field rx_count contains the
375
number of bytes currently occupied in the incoming data buffer.
376
This is set to zero on devices that do not support buffering (i.e. polled
377
devices).
378
 
379
The field tx_bufsize contains the
380
total size of the transmit data buffer. This is set to zero on devices
381
that do not support buffering (i.e. polled devices).
382
 
383
The field tx_count contains the
384
number of bytes currently occupied in the transmit data buffer.  This
385
is set to zero on devices that do not support buffering (i.e. polled
386
devices).
387
 
388
389
 
390
391
392
 
393
394
<!-- <index></index> -->API Details
395
 
396
397
 
398
399
cyg_io_write
400
 
401
402
cyg_io_write(handle, buf, len)
403
404
 
405
406
Send the data from buf to the device. The
407
driver maintains a buffer to hold the data. The size of the
408
intermediate buffer is configurable within the interface module. The
409
data is not modified at all while it is being buffered. On return,
410
*len contains the amount of characters actually
411
consumed .
412
 
413
414
It is possible to configure the write call to be blocking
415
(default) or non-blocking. Non-blocking mode requires both the configuration
416
option CYGOPT_IO_SERIAL_SUPPORT_NONBLOCKING
417
to be enabled, and the specific device to be set to non-blocking
418
mode for writes (see cyg_io_set_config()).
419
420
 
421
422
In blocking mode, the call will not return until there is space in the
423
buffer and the entire contents of buf have been
424
consumed.
425
426
 
427
428
In non-blocking mode, as much as possible gets consumed from
429
buf. If everything was consumed, the call
430
returns ENOERR. If only part of the
431
buf contents was consumed,
432
-EAGAIN is returned and the caller must try
433
again. On return, *len contains the number of characters actually
434
consumed .
435
 
436
437
The call can also return -EINTR if interrupted
438
via the cyg_io_get_config()/ABORT key.
439
440
 
441
442
 
443
444
445
 
446
447
cyg_io_read
448
 
449
450
cyg_io_read(handle, buf, len)
451
452
 
453
454
Receive data into the buffer, buf, from the
455
device. No manipulation of the data is performed before being
456
transferred.  An interrupt driven interface module will support data
457
arriving when no read is pending by buffering the data in the serial
458
driver.  Again, this buffering is completely configurable. On return,
459
*len contains the number of characters actually
460
received.
461
 
462
463
It is possible to configure the read call to be blocking (default)
464
or  non-blocking. Non-blocking mode requires both the configuration
465
option  CYGOPT_IO_SERIAL_SUPPORT_NONBLOCKING
466
to be enabled, and the specific device to be set to non-blocking
467
mode for reads (see cyg_io_set_config()).
468
469
 
470
471
In blocking mode, the call will not return until the requested
472
amount of data has been read.
473
 
474
475
In non-blocking mode, data waiting in the device buffer is copied to
476
buf, and the call returns immediately. If there
477
was enough data in the buffer to fulfill the request,
478
ENOERR is returned.  If only part of the request
479
could be fulfilled, -EAGAIN is returned and the
480
caller must try again. On return, *len contains
481
the number of characters actually received.
482
 
483
484
The call can also return -EINTR if interrupted via
485
the cyg_io_get_config()/ABORT
486
key.
487
488
 
489
490
 
491
492
493
 
494
495
cyg_io_get_config
496
 
497
498
cyg_io_get_config(handle, key, buf, len)
499
500
 
501
This function returns current [runtime] information
502
about the device and/or driver. 
503
 
504
505
  
506
    CYG_IO_GET_CONFIG_SERIAL_INFO
507
    
508
      
509
        
510
          Buf type:
511
          
512
            cyg_serial_info_t
513
          
514
        
515
        
516
          Function:
517
          
518
            
519
              This function retrieves the current state of the driver
520
              and hardware. This information contains fields for
521
              hardware baud rate, number of stop bits, and parity
522
              mode. It also includes a set of flags that control the
523
              port, such as hardware flow control.
524
            
525
          
526
        
527
      
528
    
529
  
530
 
531
  
532
    CYG_IO_GET_CONFIG_SERIAL_BUFFER_INFO
533
    
534
       
535
         
536
           Buf type:
537
           
538
             cyg_serial_buf_info_t
539
           
540
         
541
         
542
           Function:
543
           
544
             
545
               This function retrieves the current state of the
546
               software buffers in the serial drivers. For both
547
               receive and transmit buffers it returns the total
548
               buffer size and the current number of bytes occupied in
549
               the buffer. It does not take into account any buffering
550
               such as FIFOs or holding registers that the serial
551
               device itself may have.
552
             
553
           
554
         
555
       
556
    
557
  
558
 
559
  
560
    CYG_IO_GET_CONFIG_SERIAL_OUTPUT_DRAIN
561
    
562
      
563
        
564
          Buf type:
565
          
566
            void *
567
          
568
        
569
        
570
          Function:
571
          
572
            
573
              This function waits for any buffered output to
574
              complete. This function only completes when there is no
575
              more data remaining to be sent to the device.
576
            
577
          
578
        
579
      
580
    
581
  
582
 
583
  
584
    CYG_IO_GET_CONFIG_SERIAL_OUTPUT_FLUSH
585
    
586
      
587
        
588
          Buf type:
589
          
590
            void *
591
          
592
        
593
        
594
          Function:
595
          
596
            
597
              This function discards any buffered output for the
598
              device.
599
            
600
          
601
        
602
      
603
    
604
  
605
 
606
  
607
    CYG_IO_GET_CONFIG_SERIAL_INPUT_DRAIN
608
    
609
      
610
        
611
          Buf type:
612
          
613
            void *
614
          
615
        
616
        
617
          Function:     
618
          
619
            This function discards any buffered input for the
620
            device.
621
          
622
        
623
      
624
    
625
  
626
 
627
  
628
    CYG_IO_GET_CONFIG_SERIAL_ABORT
629
    
630
      
631
        
632
          Buf type:
633
          
634
             void*
635
          
636
        
637
        
638
          Function:
639
          
640
            This function will cause any pending read or write calls on
641
            this device to return with -EABORT.
642
          
643
        
644
      
645
    
646
  
647
 
648
  
649
    CYG_IO_GET_CONFIG_SERIAL_READ_BLOCKING
650
    
651
      
652
        
653
          Buf type:
654
          
655
             cyg_uint32 (values 0 or 1)
656
          
657
        
658
        
659
          Function:
660
          
661
            This function will read back the blocking-mode
662
            setting for read calls on this device. This call is only
663
            available if the configuration option
664
            CYGOPT_IO_SERIAL_SUPPORT_NONBLOCKING is
665
            enabled.
666
          
667
        
668
      
669
    
670
  
671
 
672
  
673
    CYG_IO_GET_CONFIG_SERIAL_WRITE_BLOCKING
674
    
675
      
676
        
677
          Buf type:
678
          
679
             cyg_uint32 (values 0 or 1)
680
          
681
        
682
        
683
          Function:
684
          
685
            
686
            This function will read back the blocking-mode
687
            setting for write calls on this device. This call is only
688
            available if the configuration option
689
            CYGOPT_IO_SERIAL_SUPPORT_NONBLOCKING is enabled.
690
          
691
        
692
      
693
    
694
  
695
696
 
697
698
 
699
700
701
 
702
703
cyg_io_set_config
704
 
705
706
cyg_io_set_config(handle, key, buf,len)
707
708
 
709
This function is used to update or change runtime configuration
710
of a port. 
711
 
712
713
  
714
    CYG_IO_SET_CONFIG_SERIAL_INFO
715
    
716
      
717
        
718
          Buf type:
719
          
720
            cyg_serial_info_t
721
          
722
        
723
        
724
          Function:
725
          
726
            This function updates the information for the driver
727
            and hardware.  The information contains fields for
728
            hardware baud rate, number of stop bits, and parity
729
            mode. It also includes a set of flags that control the
730
            port, such as hardware flow control.
731
            
732
          
733
        
734
      
735
    
736
  
737
 
738
  
739
    CYG_IO_SET_CONFIG_SERIAL_READ_BLOCKING
740
    
741
      
742
        
743
          Buf type:
744
          
745
             cyg_uint32 (values 0 or 1)
746
          
747
        
748
        
749
          Function:
750
          
751
            This function will set the blocking-mode for read
752
            calls on this device. This call is only available if the
753
            configuration option CYGOPT_IO_SERIAL_SUPPORT_NONBLOCKING
754
            is enabled.
755
            
756
          
757
        
758
      
759
    
760
  
761
 
762
  
763
    CYG_IO_SET_CONFIG_SERIAL_WRITE_BLOCKING
764
    
765
      
766
        
767
          Buf type:
768
          
769
            cyg_uint32 (values 0 or 1)
770
          
771
        
772
        
773
          Function:
774
          
775
            This function will set the blocking-mode for write
776
            calls on this device. This call is only available if the
777
            configuration option CYGOPT_IO_SERIAL_SUPPORT_NONBLOCKING
778
            is enabled.
779
            
780
          
781
        
782
      
783
    
784
  
785
786
 
787
788
 
789
790
 
791
792
 
793
794
 
795
796
 
797
798
799
 
800
801
 TTY driver
802
 
803
804
Use the include file <cyg/io/ttyio.h> for
805
this driver.
806
807
 
808
809
This driver is built on top of the simple
810
serial driver and is typically used for a device that interfaces with
811
humans such as a terminal. It provides some minimal formatting of data
812
on output and allows for line-oriented editing on input.
813
814
 
815
816
 
817
818
Runtime configuration
819
 
820
821
Runtime configuration is achieved by exchanging data structures with
822
the driver via the cyg_io_set_config() and
823
cyg_io_get_config() functions.
824
825
 
826
 
827
828
typedef struct {
829
 cyg_uint32 tty_out_flags;
830
 cyg_uint32 tty_in_flags;
831
} cyg_tty_info_t;
832
833
 
834
The field tty_out_flags
835
is used to control what happens to data as it is send to the serial
836
port. It contains a bitmap comprised of the bits as defined by the
837
CYG_TTY_OUT_FLAGS_xxx values below. 
838
 
839
840
#define CYG_TTY_OUT_FLAGS_CRLF 0x0001 // Map '\n' => '\r\n' on output
841
842
 
843
If this bit is set in tty_out_flags,
844
any occurrence of the character "\n" will
845
be replaced by the sequence "\r\n" before
846
being sent to the device.
847
 
848
The field tty_in_flags
849
is used to control how data is handled as it comes from the serial
850
port. It contains a bitmap comprised of the bits as defined by the
851
CYG_TTY_IN_FLAGS_xxx values below. 
852
 
853
854
#define CYG_TTY_IN_FLAGS_CR 0x0001 // Map '\r' => '\n' on input
855
856
 
857
If this bit is set in tty_in_flags, the
858
character "\r" (“return” or “enter” on
859
most keyboards) will be mapped to "\n".
860
 
861
862
#define CYG_TTY_IN_FLAGS_CRLF 0x0002 // Map '\r\n' => '\n' on input
863
864
 
865
866
If this bit is set in tty_in_flags, the
867
character sequence "\r\n" (often sent by DOS/Windows
868
based terminals) will be mapped to "\n". 
869
 
870
871
#define CYG_TTY_IN_FLAGS_ECHO 0x0004 // Echo characters as processed
872
873
 
874
875
If this bit is set in tty_in_flags, characters
876
will be echoed back to the serial port as they are processed. 
877
 
878
879
#define CYG_TTY_IN_FLAGS_BINARY 0x0008 // No input processing
880
881
 
882
If this bit is set in tty_in_flags, the
883
input will not be manipulated in any way before being placed in
884
the user’s buffer. 
885
 
886
887
 
888
889
890
 
891
892
<!-- <index></index> -->API details
893
 
894
895
cyg_io_read(handle, buf, len)
896
897
 
898
This function is used to read data from the device. In the
899
default case, data is read until an end-of-line character ("\n"
900
or "\r") is read. Additionally, the characters are echoed
901
back to the [terminal] device. Minimal editing
902
of the input is also supported. 
903
 
904
905
When connecting to a remote target via GDB it is not possible
906
to provide console input while GDB is connected. The GDB remote
907
protocol does not support input. Users must disconnect from GDB
908
if this functionality is required.
909
910
 
911
912
cyg_io_write(handle, buf, len)
913
914
 
915
This function is used to send data to the device. In the default
916
case, the end-of-line character "\n" is replaced by the
917
sequence "\r\n". 
918
 
919
920
cyg_io_get_config(handle, key, buf, len)
921
922
 
923
This function is used to get information about the channel’s
924
configuration at runtime. 
925
 
926
927
  
928
    CYG_IO_GET_CONFIG_TTY_INFO
929
    
930
      
931
        
932
          Buf type:
933
          
934
            cyg_tty_info_t
935
          
936
        
937
        
938
          Function:
939
          
940
            This function retrieves the current state of the
941
            driver.
942
            
943
          
944
        
945
      
946
    
947
  
948
949
 
950
Serial driver keys (see above) may also be specified
951
in which case the call is passed directly to the serial
952
driver. 
953
 
954
955
cyg_io_set_config(handle, key, buf, len)
956
957
 
958
This function is used to modify the channel’s configuration
959
at runtime. 
960
 
961
 
962
963
  
964
    CYG_IO_SET_CONFIG_TTY_INFO
965
    
966
      
967
        
968
          Buf type:
969
          
970
            cyg_tty_info_t
971
          
972
        
973
        
974
          Function:     
975
          
976
            This function changes the current state of the
977
            driver.
978
          
979
        
980
      
981
    
982
  
983
984
 
985
Serial driver
986
keys (see above) may also be specified in which case the
987
call is passed directly to the serial driver. 
988
 
989
990
 
991
992
 
993
994
 
995
996
997
 
998
 
999
1000
 
1001
1002
 
1003
1004
1005
 
1006
1007
How to Write a Driver
1008
 
1009
1010
 
1011
1012
A device driver is nothing more than a
1013
named entity that supports the basic I/O functions - read, write, get
1014
config, and set config. Typically a device driver also uses and
1015
manages interrupts from the device. While the interface is generic and
1016
device driver independent, the actual driver implementation is
1017
completely up to the device driver designer. 
1018
 
1019
That said, the reason for using a device driver is to provide
1020
access to a device from application code in as general purpose a
1021
fashion as reasonable. Most driver writers are also concerned with
1022
making this access as simple as possible while being as efficient
1023
as possible. 
1024
 
1025
Most device drivers are concerned with the movement of information,
1026
for example data bytes along a serial interface, or packets in a
1027
network. In order to make the most efficient use of system resources,
1028
interrupts are used. This will allow other application processing
1029
to take place while the data transfers are under way, with interrupts
1030
used to indicate when various events have occurred. For example,
1031
a serial port typically generates an interrupt after a character
1032
has been sent “down the wire” and the interface
1033
is ready for another. It makes sense to allow further application
1034
processing while the data is being sent since this can take quite
1035
a long time. The interrupt can be used to allow the driver to send
1036
a character as soon as the current one is complete, without any
1037
active participation by the application code. 
1038
 
1039
The main building blocks for device drivers are found in the
1040
include file: <cyg/io/devtab.h>
1041
 
1042
All device drivers in eCos are described
1043
by a device table entry, using the cyg_devtab_entry_t type.
1044
The entry should be created using the DEVTAB_ENTRY() macro,
1045
like this:
1046
 
1047
1048
DEVTAB_ENTRY(l, name, dep_name, handlers, init, lookup, priv)
1049
1050
 
1051
1052
Arguments
1053
  
1054
    l
1055
    The "C" label for this device table entry.
1056
  
1057
  
1058
    name
1059
    The "C" string name for the device.
1060
  
1061
  
1062
    dep_name
1063
    For a layered device, the "C" string name of the
1064
    device this device is built upon.
1065
  
1066
  
1067
    handlers
1068
    A pointer to the I/O function "handlers" (see below).
1069
  
1070
  
1071
    init
1072
    A function called when eCos is initialized. This
1073
    function can query the device, setup hardware, etc.
1074
  
1075
  
1076
    lookup
1077
    A function called when cyg_io_lookup() is called
1078
    for this device. 
1079
  
1080
  
1081
    priv
1082
    A placeholder for any device specific data
1083
    required by the driver.
1084
  
1085
1086
 
1087
The interface to the driver is through the handlers field.  This is a pointer to
1089
a set of functions which implement the various cyg_io_XXX()
1090
routines. This table is defined by the macro:
1091
 
1092
 
1093
1094
DEVIO_TABLE(l, write, read, select, get_config, set_config)
1095
1096
 
1097
1098
Arguments
1099
  
1100
    l
1101
    The "C" label for this table of handlers.
1102
  
1103
  
1104
    write
1105
    The function called as a result of
1106
    cyg_io_write().
1107
  
1108
  
1109
    read
1110
    The function called as a result of
1111
    cyg_io_read(). 
1112
  
1113
  
1114
    select
1115
    The function called as a result of
1116
    cyg_io_select(). 
1117
  
1118
  
1119
    get_config
1120
    The function called as a result of
1121
    cyg_io_get_config().
1122
  
1123
  
1124
    set_config
1125
    The function called as a result of
1126
    cyg_io_set_config(). 
1127
  
1128
1129
 
1130
1131
When eCos is initialized (sometimes called
1132
“boot” time), the init() function is called
1133
for all devices in the system. The init() function is
1134
allowed to return an error in which case the device will be placed
1135
“off line” and all I/O requests to that device will be
1136
considered in error.
1137
1138
 
1139
1140
The lookup() function is called whenever
1141
the cyg_io_lookup() function
1142
is called with this device name. The lookup function may cause the device
1143
to come “on line” which would then allow I/O
1144
operations to proceed. Future versions of the I/O system
1145
will allow for other states, including power saving modes,
1146
etc.
1147
1148
 
1149
1150
1151
 
1152
1153
How to Write a Serial Hardware Interface Driver
1154
 
1155
 
1156
The standard serial driver supplied with
1157
eCos is structured as a hardware independent
1158
portion and a hardware dependent interface module. To add support for
1159
a new serial port, the user should be able to use the existing
1160
hardware independent portion and just add their own interface driver which handles the details of the
1162
actual device. The user should have no need to change the hardware
1163
independent portion. 
1164
 
1165
The interfaces used by the serial driver and serial implementation
1166
modules are contained in the file <cyg/io/serial.h>
1167
1168
 
1169
1170
In the sections below we use the notation <<xx>> to
1171
mean a module specific value, referred to as “xx” below.
1172
1173
 
1174
1175
 
1176
1177
DevTab Entry
1178
 
1179
The interface module contains the devtab entry (or entries
1180
if a single module supports more than one interface). This entry
1181
should have the form: 
1182
 
1183
1184
DEVTAB_ENTRY(<<module_name>>,
1185
             <<device_name>>,
1186
             0,
1187
             &serial_devio,
1188
             <<module_init>>,
1189
             <<module_lookup>>,
1190
             &<<serial_channel>>
1191
            );
1192
1193
 
1194
1195
Arguments
1196
  
1197
    module_name
1198
    The "C" label for this devtab entry
1199
  
1200
  
1201
    device_name
1202
    The "C" string for the
1203
    device. E.g. /dev/serial0.
1204
  
1205
  
1206
    serial_devio
1207
    The table of I/O functions. This set is defined in
1208
    the hardware independent serial driver and should be used.
1209
    
1210
  
1211
  
1212
    module_init
1213
    The module initialization function.
1214
  
1215
  
1216
    module_lookup
1217
    The device lookup function. This function
1218
    typically sets up the device for actual use, turning on
1219
    interrupts, configuring the port, etc.
1220
  
1221
  
1222
    serial_channel
1223
    This table (defined below) contains the interface
1224
    between the interface module and the serial driver proper.
1225
  
1226
1227
 
1228
1229
 
1230
1231
1232
 
1233
1234
Serial Channel Structure
1235
 
1236
Each serial device must have a “serial channel”.
1237
This is a set of data which describes all operations on the device.
1238
It also contains buffers, etc., if the device is to be buffered.
1239
The serial channel is created by the macro: 
1240
 
1241
1242
SERIAL_CHANNEL_USING_INTERRUPTS(l, funs, dev_priv, baud,stop, parity, word_length,
1243
                                flags, out_buf, out_buflen, in_buf, in_buflen)
1244
1245
 
1246
1247
  Arguments
1248
  
1249
    l
1250
    The "C" label for this structure.
1251
  
1252
  
1253
    funs
1254
    The set of interface functions (see below).
1255
  
1256
  
1257
    dev_priv
1258
    A placeholder for any device specific data for
1259
    this channel.
1260
  
1261
  
1262
    baud
1263
    The initial baud rate value
1264
    (cyg_serial_baud_t).
1265
  
1266
  
1267
    stop
1268
    The initial stop bits value
1269
    (cyg_serial_stop_bits_t).
1270
  
1271
  
1272
    parity
1273
    The initial parity mode value
1274
    (cyg_serial_parity_t).
1275
  
1276
  
1277
    word_length
1278
    The initial word length value
1279
    (cyg_serial_word_length_t).
1280
  
1281
  
1282
    flags
1283
    The initial driver flags value.
1284
  
1285
  
1286
    out_buf
1287
    Pointer to the output
1288
    buffer. NULL if none required.
1289
  
1290
  
1291
    out_buflen
1292
    The length of the output buffer.
1293
  
1294
  
1295
    in_buf
1296
    pointer to the input
1297
    buffer. NULL if none required.
1298
  
1299
  
1300
    in_buflen
1301
    The length of the input buffer. 
1302
  
1303
1304
 
1305
1306
If either buffer length is zero, no buffering will take place
1307
in that direction and only polled mode functions will be used.
1308
1309
 
1310
1311
The interface from the hardware independent driver into the
1312
hardware interface module is contained in the funs table.
1313
This is defined by the macro:
1314
1315
 
1316
1317
 
1318
1319
1320
 
1321
1322
Serial Functions Structure
1323
 
1324
1325
SERIAL_FUNS(l, putc, getc, set_config, start_xmit, stop_xmit)
1326
1327
 
1328
 
1329
1330
  Arguments
1331
  
1332
    l
1333
    The "C" label for this structure.
1334
  
1335
  
1336
    putc
1337
    
1338
      bool (*putc)(serial_channel *priv, unsigned char
1339
      c)
1340
      
1341
      This function sends one character to the interface. It should
1342
      return true if the character is actually consumed. It should
1343
      return false if there is no space in the interface
1344
      
1345
    
1346
  
1347
  
1348
    getc
1349
    
1350
      unsigned char (*getc)(serial_channel *priv)
1351
      
1352
      This function fetches one character from the interface. It will
1353
      be only called in a non-interrupt driven mode, thus it should
1354
      wait for a character by polling the device until ready.
1355
      
1356
    
1357
  
1358
  
1359
    set_config
1360
    
1361
      bool (*set_config)(serial_channel
1362
      *priv,cyg_serial_info_t *config)
1363
      
1364
        This function is used to configure the port. It should return
1365
        true if the hardware is updated to match the desired
1366
        configuration. It should return false if the port cannot
1367
        support some parameter specified by the given
1368
        configuration. E.g. selecting 1.5 stop bits and 8 data bits is
1369
        invalid for most serial devices and should not be allowed.
1370
      
1371
    
1372
  
1373
  
1374
    start_xmit
1375
    void (*start_xmit)(serial_channel *priv)
1376
      
1377
        In interrupt mode, turn on the transmitter and allow for
1378
        transmit interrupts.
1379
      
1380
    
1381
  
1382
  
1383
    stop_xmit
1384
    
1385
      void (*stop_xmit)(serial_channel *priv)
1386
      In interrupt mode, turn off the transmitter.
1387
    
1388
  
1389
1390
 
1391
1392
 
1393
1394
1395
 
1396
1397
Callbacks
1398
 
1399
1400
The device interface module can execute functions in the
1401
hardware independent driver via chan->callbacks.
1402
These functions are available:
1403
1404
 
1405
1406
void (*serial_init)( serial_channel *chan )
1407
1408
 
1409
This function is used to initialize the serial channel. It
1410
is only required if the channel is being used in interrupt
1411
mode.
1412
 
1413
1414
void (*xmt_char)( serial_channel *chan )
1415
1416
 
1417
1418
This function would be called from an interrupt handler after a
1419
transmit interrupt indicating that additional characters may be
1420
sent. The upper driver will call the putc
1421
function as appropriate to send more data to the device.
1422
 
1423
1424
void (*rcv_char)( serial_channel *chan, unsigned char c )
1425
1426
 
1427
 
1428
1429
This function is used to tell the driver that a character has arrived
1430
at the interface. This function is typically called from the interrupt
1431
handler. 
1432
 
1433
1434
Furthermore, if the device has a FIFO it should require the hardware
1435
independent driver to provide block transfer functionality (driver CDL
1436
should include "implements
1437
CYGINT_IO_SERIAL_BLOCK_TRANSFER").  In that case, the following
1438
functions are available as well:
1439
 
1440
1441
xmt_req_reply_t (*data_xmt_req)(serial_channel *chan,
1442
                     int space,
1443
                     int* chars_avail,
1444
                     unsigned char** chars)
1445
void (*data_xmt_done)(serial_channel *chan, int chars_sent)
1446
1447
 
1448
1449
Instead of calling xmt_char() to get a single
1450
character for transmission at a time, the driver should call
1451
data_xmt_req() in a loop, requesting character
1452
blocks for transfer. Call with a space argument of how much space
1453
there is available in the FIFO.
1454
 
1455
If the call returns true, the driver can read
1456
chars_avail characters from
1457
chars and copy them into the FIFO.
1458
 
1459
If the call returns false, there are
1460
no more buffered characters and the driver should continue without
1461
filling up the FIFO.
1462
 
1463
When all data has been unloaded, the
1464
driver must call data_xmt_done().
1465
 
1466
 
1467
1468
rcv_req_reply_t (*data_rcv_req)(serial_channel *chan,
1469
                     int avail,
1470
                     int* space_avail,
1471
                     unsigned char** space)
1472
void (*data_rcv_done)(serial_channel *chan, int chars_rcvd)
1473
1474
 
1475
Instead of calling rcv_char() with a single
1476
character at a time, the driver should call
1477
data_rcv_req() in a loop, requesting space to
1478
unload the FIFO to. avail is the number of
1479
characters the driver wishes to unload.
1480
 
1481
 
1482
If the call returns true, the driver can copy
1483
space_avail characters to
1484
space. 
1485
 
1486
 
1487
If the call returns false, the input buffer is
1488
full. It is up to the driver to decide what to do in that case
1489
(callback functions for registering overflow are being planned for
1490
later versions of the serial driver).
1491
1492
 
1493
When all data has been unloaded, the driver must call
1494
data_rcv_done().
1495
 
1496
1497
 
1498
1499
 
1500
1501
 
1502
1503
1504
 
1505
1506
Serial testing with ser_filter
1507
 
1508
1509
 
1510
1511
Rationale
1512
 
1513
1514
Since some targets only have one serial connection, a serial testing harness
1515
needs to be able to share the connection with GDB
1516
(however, the test and GDB can also run on separate
1517
lines).
1518
1519
 
1520
1521
The serial filter (ser_filter)
1522
sits between the serial port and GDB and monitors
1523
the exchange of data between GDB and the target.
1524
Normally, no changes are made to the data.
1525
1526
 
1527
1528
When a test request packet is sent from the test on the target, it is
1529
intercepted by the filter.
1530
1531
 
1532
1533
The filter and target then enter a loop, exchanging protocol data between
1534
them which GDB never sees.
1535
1536
 
1537
1538
In the event of a timeout, or a crash on the target, the filter falls
1539
back into its pass-through mode. If this happens due to a crash it should be
1540
possible to start regular debugging with GDB. The
1541
filter will stay in the pass-though mode until GDB
1542
disconnects.
1543
1544
1545
 
1546
1547
1548
 
1549
1550
The Protocol
1551
 
1552
The protocol commands are prefixed with an "@"
1553
character which the serial filter is looking for. The protocol
1554
commands include:
1555
1556
 
1557
1558
  
1559
    PING
1560
    
1561
      Allows the test on the target to probe for the filter. The
1562
      filter responds with OK, while
1563
      GDB would just ignore the
1564
      command. This allows the tests to do nothing if they require the
1565
      filter and it is not present.
1566
    
1567
  
1568
  
1569
    CONFIG
1570
    
1571
      Requests a change of serial line configuration. Arguments
1572
      to the command specify baud rate, data bits, stop bits, and
1573
      parity. [This command is not fully implemented yet - there is no
1574
      attempt made to recover if the new configuration turns out to
1575
      cause loss of data.]
1576
    
1577
  
1578
  
1579
    BINARY
1580
    
1581
      Requests data to be sent from the filter to the
1582
      target. The data is checksummed, allowing errors in the transfer
1583
      to be detected.  Sub-options of this command control how the
1584
      data transfer is made:
1585
      
1586
        
1587
          NO_ECHO
1588
          
1589
            (serial driver receive test) Just send data from the
1590
            filter to the target. The test verifies the checksum and
1591
            PASS/FAIL depending on the result. 
1592
          
1593
        
1594
        
1595
          EOP_ECHO
1596
          
1597
            (serial driver half-duplex receive and send test) As
1598
            NO_ECHO but the test echoes back the
1599
            data to the filter.  The filter does a checksum on the
1600
            received data and sends the result to the target. The test
1601
            PASS/FAIL depending on the result of both checksum
1602
            verifications.
1603
          
1604
        
1605
        
1606
          DUPLEX_ECHO
1607
          
1608
            (serial driver duplex receive and send test) Smaller
1609
            packets of data are sent back and forth in a pattern that
1610
            ensures that the serial driver will be both sending and
1611
            receiving at the same time. Again, checksums are computed
1612
            and verified resulting in PASS/FAIL.
1613
            
1614
          
1615
        
1616
      
1617
    
1618
  
1619
  
1620
    TEXT
1621
    
1622
       This is a test of the text translations in the TTY layer.
1623
      Requests a transfer of text data from the target to the filter
1624
      and possibly back again. The filter treats this as a binary
1625
      transfer, while the target ma be doing translations on the
1626
      data. The target provides the filter with checksums for what it
1627
      should expect to see. This test is not implemented yet.
1628
      
1629
    
1630
  
1631
1632
 
1633
The above commands may be extended, and new commands added, as
1634
required to test (new) parts of the serial drivers in
1635
eCos.
1636
1637
 
1638
1639
 
1640
1641
1642
 
1643
1644
The Serial Tests
1645
 
1646
1647
The serial tests are built as any other eCos test. After running the
1648
make tests command, the tests can be found in
1649
install/tests/io_serial/
1650
 
1651
1652
  
1653
    serial1
1654
    A simple API test.
1655
  
1656
  
1657
    serial2
1658
    
1659
      A simple serial send test. It writes out two strings, one
1660
      raw and one encoded as a GDB
1661
      O-packet
1662
    
1663
  
1664
  
1665
    serial3 [ requires the serial filter ]
1666
    
1667
      This tests the half-duplex send and receive capabilities
1668
      of the serial driver. 
1669
    
1670
  
1671
  
1672
    serial4 [ requires the serial filter ]
1673
    
1674
      This test attempts to use a few different serial
1675
      configurations, testing the driver's configuration/setup
1676
      functionality. 
1677
    
1678
  
1679
  
1680
    serial5 [ requires the serial filter ]
1681
    
1682
      This tests the duplex send and receive capabilities of the
1683
      serial driver. 
1684
    
1685
  
1686
1687
 
1688
All tests should complete in less than 30 seconds.
1689
 
1690
1691
 
1692
1693
1694
 
1695
1696
Serial Filter Usage
1697
 
1698
Running the ser_filter program with no (or wrong) arguments results in
1699
the following output:
1700
1701
 
1702
1703
Usage: ser_filter [-t -S] TcpIPport SerialPort BaudRate
1704
or: ser_filter -n [-t -S] SerialPort BaudRate
1705
-t: Enable tracing.
1706
-S: Output data read from serial line.
1707
-c: Output data on console instead of via GDB.
1708
-n: No GDB.
1709
1710
 
1711
The normal way to use it with GDB is to start the filter:
1712
 
1713
1714
$ ser_filter -t 9000 com1 38400
1715
1716
 
1717
1718
In this case, the filter will be listening on port 9000 and connect to the
1719
target via the serial port COM1 at 38400 baud. On a UNIX
1720
host, replace "COM1" with a device such as
1721
"/dev/ttyS0".
1722
1723
 
1724
1725
The  option enables tracing which will cause the
1726
filter to describe its actions on the console.
1727
1728
 
1729
Now start GDB with one of the tests as an
1730
argument:
1731
1732
 
1733
1734
$ mips-tx39-elf-gdb -nw install/tests/io_serial/serial3
1735
1736
 
1737
Then connect to the filter:
1738
 
1739
1740
(gdb) target remote localhost:9000
1741
1742
 
1743
1744
This should result in a connection in exactly the same way as if you
1745
had connected directly to the target on the serial line.
1746
1747
 
1748
1749
(gdb) c
1750
1751
 
1752
1753
Which should result in output similar to the below:
1754
1755
 
1756
1757
Continuing.
1758
INFO: <BINARY:16:1!>
1759
PASS: <Binary test completed>
1760
INFO: <BINARY:128:1!>
1761
PASS: <Binary test completed>
1762
INFO: <BINARY:256:1!>
1763
PASS: <Binary test completed>
1764
INFO: <BINARY:1024:1!>
1765
PASS: <Binary test completed>
1766
INFO: <BINARY:512:0!>
1767
PASS: <Binary test completed>
1768
...
1769
PASS: <Binary test completed>
1770
INFO: <BINARY:16384:0!>
1771
PASS: <Binary test completed>
1772
PASS: <serial13 test OK>
1773
EXIT: <done>
1774
1775
 
1776
1777
If any of the individual tests fail the testing will terminate with a
1778
FAIL.
1779
1780
 
1781
1782
With tracing enabled, you would also see the filter's status output:
1783
1784
 
1785
1786
The PING command sent from the target to determine the
1787
presence of the filter:
1788
1789
 
1790
1791
[400 11:35:16] Dispatching command PING
1792
[400 11:35:16] Responding with status OK
1793
1794
 
1795
Each of the binary commands result in output similar to:
1796
 
1797
1798
[400 11:35:16] Dispatching command BINARY
1799
[400 11:35:16] Binary data (Size:16, Flags:1).
1800
[400 11:35:16] Sending CRC: '170231!', len: 7.
1801
[400 11:35:16] Reading 16 bytes from target.
1802
[400 11:35:16] Done. in_crc 170231, out_crc 170231.
1803
[400 11:35:16] Responding with status OK
1804
[400 11:35:16] Received DONE from target.
1805
1806
 
1807
1808
This tracing output is normally sent as O-packets to GDB
1809
 which will display the tracing text. By using the
1810
 option, the tracing text can be redirected to the
1811
console from which ser_filter was started.
1812
1813
 
1814
1815
 
1816
1817
1818
 
1819
1820
A Note on Failures
1821
 
1822
1823
A serial connection (especially when driven at a high baud rate) can garble the
1824
transmitted data because of noise from the environment. It is not the job of
1825
the serial driver to ensure data integrity - that is the job of protocols
1826
layering on top of the serial driver. 
1827
 
1828
In the current implementation the serial tests and the serial filter are
1829
not resilient to such data errors. This means that the test may crash or hang
1830
(possibly without reporting a FAIL). It also
1831
means that you should be aware of random errors - a FAIL
1832
 is not necessarily caused by a bug in the serial driver.
1833
1834
 
1835
Ideally, the serial testing infrastructure should be able to distinguish
1836
random errors from consistent errors - the former are most likely due to noise
1837
in the transfer medium, while the latter are more likely to be caused by faulty
1838
drivers. The current implementation of the infrastructure does not have this
1839
capability.
1840
 
1841
1842
 
1843
1844
1845
 
1846
1847
Debugging
1848
 
1849
If a test fails, the serial filter's output may provide some hints about
1850
what the problem is. If the option  is used when starting
1851
the filter, data received from the target is printed out:
1852
1853
 
1854
1855
[400 11:35:16] 0000 50 41 53 53 3a 3c 42 69 'PASS:<Bi'
1856
[400 11:35:16] 0008 6e 61 72 79 20 74 65 73 'nary.tes'
1857
[400 11:35:16] 0010 74 20 63 6f 6d 70 6c 65 't.comple'
1858
[400 11:35:16] 0018 74 65 64 3e 0d 0a 49 4e 'ted>..IN'
1859
[400 11:35:16] 0020 46 4f 3a 3c 42 49 4e 41 'FO:<BINA'
1860
[400 11:35:16] 0028 52 59 3a 31 32 38 3a 31 'RY:128:1'
1861
[400 11:35:16] 0030 21 3e 0d 0a 40 42 49 4e '!..@BIN'
1862
[400 11:35:16] 0038 41 52 59 3a 31 32 38 3a 'ARY:128:'
1863
[400 11:35:16] 0040 31 21 .. .. .. .. .. .. '1!'
1864
1865
 
1866
In the case of an error during a testing command the data received by the
1867
filter will be printed out, as will the data that was expected. This allows
1868
the two data sets to be compared which may give some idea of what the problem
1869
is.
1870
 
1871
1872
 
1873
1874
 
1875
1876
 
1877
1878
 
1879
1880
 
1881
1882
1883
 
1884
1885
Device Driver Interface to the Kernel
1886
 
1887
1888
This chapter describes the API that device drivers may use
1889
to interact with the kernel and HAL. It is primarily concerned with
1890
the control and management of interrupts and the synchronization of
1891
ISRs, DSRs and threads.
1892
1893
 
1894
1895
The same API will be present in configurations where the kernel
1896
is not present. In this case the functions will be supplied by code
1897
acting directly on the HAL.
1898
1899
 
1900
 
1901
1902
 
1903
1904
Interrupt Model
1905
 
1906
1907
eCos presents a three level interrupt model to
1908
device drivers. This consists of Interrupt Service Routines (ISRs) that are invoked
1910
in response to a hardware interrupt; Deferred
1911
Service Routines (DSRs) that are invoked in response to a request by
1912
an ISR; and threads that are the clients of the driver. 
1913
 
1914
1915
Hardware interrupts are delivered with minimal intervention to an
1916
ISR. The HAL decodes the hardware source of the interrupt and calls
1917
the ISR of the attached interrupt object. This ISR may manipulate the
1918
hardware but is only allowed to make a restricted set of calls on the
1919
driver API. When it returns, an ISR may request that its DSR should be
1920
scheduled to run.
1921
1922
 
1923
1924
A DSR will be run when it is safe to do so without interfering with
1925
the scheduler. Most of the time the DSR will run immediately after the
1926
ISR, but if the current thread is in the scheduler, it will be delayed
1927
until the thread is finished. A DSR is allowed to make a larger set of
1928
driver API calls, including, in particular, being able to call
1929
cyg_drv_cond_signal() to wake up waiting
1930
threads.
1931
1932
 
1933
1934
Finally, threads are able to make all API calls and in particular are
1935
allowed to wait on mutexes and condition variables. 
1936
 
1937
 
1938
1939
For a device driver to receive interrupts it must first define ISR and
1940
DSR routines as shown below, and then call
1941
cyg_drv_interrupt_create().  Using the handle
1942
returned, the driver must then call
1943
cyg_drv_interrupt_attach() to actually attach the
1944
interrupt to the hardware vector.
1945
1946
 
1947
 
1948
1949
 
1950
1951
1952
 
1953
1954
<!-- <index></index> -->Synchronization
1955
 
1956
There are three levels of synchronization supported:
1957
 
1958
1959
  
1960
    
1961
    Synchronization with ISRs. This normally means disabling
1962
    interrupts to prevent the ISR running during a critical
1963
    section. In an SMP environment, this will also require the use of
1964
    a spinlock to synchronize with ISRs, DSRs or threads running on
1965
    other CPUs.  This is implemented by the
1966
    cyg_drv_isr_lock() and
1967
    cyg_drv_isr_unlock() functions. This
1968
    mechanism should be used sparingly and for short periods only.
1969
    For finer grained synchronization, individual spinlocks are also
1970
    supplied.
1971
    
1972
  
1973
 
1974
  
1975
    
1976
    Synchronization with DSRs. This will be implemented in the kernel
1977
    by taking the scheduler lock to prevent DSRs running during
1978
    critical sections. In non-kernel configurations it will be
1979
    implemented by non-kernel code. This is implemented by the
1980
    cyg_drv_dsr_lock() and
1981
    cyg_drv_dsr_unlock() functions. As with ISR
1982
    synchronization, this mechanism should be used sparingly. Only
1983
    DSRs and threads may use this synchronization mechanism, ISRs are
1984
    not allowed to do this.
1985
    
1986
  
1987
  
1988
    
1989
    Synchronization with threads. This is implemented with mutexes
1990
    and condition variables. Only threads may lock the mutexes and
1991
    wait on the condition variables, although DSRs may signal
1992
    condition variables.
1993
    
1994
  
1995
1996
 
1997
1998
Any data that is accessed from more than one level must be protected
1999
against concurrent access. Data that is accessed by ISRs must be
2000
protected with the ISR lock, or a spinlock at all times,
2001
even in ISRs. Data that is shared between DSRs
2002
and threads should be protected with the DSR lock. Data that is only
2003
accessed by threads must be protected with mutexes.
2004
2005
 
2006
2007
 
2008
2009
2010
 
2011
2012
<!-- <index></index> -->SMP Support
2013
 
2014
2015
Some eCos targets contain support for Symmetric Multi-Processing (SMP)
2016
configurations, where more than one CPU may be present. This option
2017
has a number of ramifications for the way in which device drivers must
2018
be written if they are to be SMP-compatible.
2019
2020
 
2021
2022
Since it is possible for the ISR, DSR and thread components of a
2023
device driver to execute on different CPUs, it is important that
2024
SMP-compatible device drivers use the driver API routines correctly.
2025
2026
 
2027
2028
Synchronization between threads and DSRs continues to require that the
2029
thread-side code use cyg_drv_dsr_lock() and
2030
cyg_drv_dsr_unlock() to protect access to shared
2031
data. While it is not strictly necessary for DSR code to claim the DSR
2032
lock, since DSRs are run with it claimed already, it is good practice
2033
to do so.
2034
2035
 
2036
2037
Synchronization between ISRs and DSRs or threads requires that access
2038
to sensitive data be protected, in all places, by calls to
2039
cyg_drv_isr_lock() and
2040
cyg_drv_isr_unlock(). Disabling or masking
2041
interrupts is not adequate, since the thread or DSR may be running on
2042
a different CPU and interrupt enable/disable only work on the current
2043
CPU.
2044
2045
 
2046
2047
The ISR lock, for SMP systems, not only disables local interrupts, but
2048
also acquires a spinlock to protect against concurrent access from
2049
other CPUs. This is necessary because ISRs are not run with the
2050
scheduler lock claimed. Hence they can run in parallel with the other
2051
components of the device driver.
2052
2053
 
2054
2055
The ISR lock provided by the driver API is just a shared spinlock that
2056
is available for use by all drivers. If a driver needs to implement a
2057
finer grain of locking, it can use private spinlocks, accessed via the
2058
cyg_drv_spinlock_*() functions.
2059
2060
 
2061
2062
 
2063
2064
2065
 
2066
2067
Device Driver Models
2068
 
2069
2070
There are several ways in which device drivers
2071
may be built. The exact model chosen will depend on the properties of
2072
the device and the behavior desired. There are three basic models that
2073
may be adopted.
2074
2075
 
2076
2077
The first model is to do all device processing in the ISR.  When it is
2078
invoked the ISR programs the device hardware directly and accesses
2079
data to be transferred directly in memory. The ISR should also call
2080
cyg_drv_interrupt_acknowledge().  When it is
2081
finished it may optionally request that its DSR be invoked.  The DSR
2082
does nothing but call cyg_drv_cond_signal() to
2083
cause a thread to be woken up. Thread level code must call
2084
cyg_drv_isr_lock(), or
2085
cyg_drv_interrupt_mask() to prevent ISRs running
2086
while it manipulates shared memory.
2087
2088
 
2089
2090
The second model is to defer device processing to the DSR.  The ISR
2091
simply prevents further delivery of interrupts by either programming
2092
the device, or by calling
2093
cyg_drv_interrupt_mask().  It must then call
2094
cyg_drv_interrupt_acknowledge() to allow other
2095
interrupts to be delivered and then request that its DSR be
2096
called. When the DSR runs it does the majority of the device handling,
2097
optionally signals a condition variable to wake a thread, and finishes
2098
by calling cyg_drv_interrupt_unmask() to re-allow
2099
device interrupts. Thread level code uses
2100
cyg_drv_dsr_lock() to prevent DSRs running while
2101
it manipulates shared memory.  The eCos serial device drivers use this
2102
approach.
2103
2104
 
2105
2106
The third model is to defer device processing even further to a
2107
thread. The ISR behaves exactly as in the previous model and simply
2108
blocks and acknowledges the interrupt before request that the DSR
2109
run. The DSR itself only calls
2110
cyg_drv_cond_signal() to wake the thread. When
2111
the thread awakens it performs all device processing, and has full
2112
access to all kernel facilities while it does so. It should finish by
2113
calling cyg_drv_interrupt_unmask() to re-allow
2114
device interrupts.  The eCos ethernet device drivers are written to
2115
this model.
2116
2117
 
2118
2119
The first model is good for devices that need immediate processing and
2120
interact infrequently with thread level. The second model trades a
2121
little latency in dealing with the device for a less intrusive
2122
synchronization mechanism. The last model allows device processing to
2123
be scheduled with other threads and permits more complex device
2124
handling.
2125
2126
 
2127
2128
 
2129
2130
2131
 
2132
2133
Synchronization Levels
2134
 
2135
2136
Since it would be dangerous for an ISR or DSR to make a call
2137
that might reschedule the current thread (by trying to lock a mutex
2138
for example) all functions in this API have an associated synchronization
2139
level. These levels are:
2140
2141
 
2142
2143
  
2144
    Thread
2145
    
2146
      
2147
      This function may only be called from within threads. This is
2148
      usually the client code that makes calls into the device driver.
2149
      In a non-kernel configuration, this will be code running at the
2150
      default non-interrupt level.
2151
      
2152
    
2153
  
2154
 
2155
  
2156
    DSR
2157
    
2158
      
2159
      This function may be called by either DSR or thread code.
2160
      
2161
    
2162
  
2163
 
2164
  
2165
    ISR
2166
    
2167
      
2168
      This function may be called from ISR, DSR or thread code.
2169
      
2170
    
2171
  
2172
2173
 
2174
2175
The following table shows, for each API function, the levels
2176
at which is may be called:
2177
2178
 
2179
2180
                                  Callable from:
2181
Function                       ISR     DSR    Thread
2182
-------------------------------------------------------------------------
2183
 
2184
cyg_drv_isr_lock                X       X       X
2185
cyg_drv_isr_unlock              X       X       X
2186
cyg_drv_spinlock_init                           X
2187
cyg_drv_spinlock_destroy                        X
2188
cyg_drv_spinlock_spin           X       X       X
2189
cyg_drv_spinlock_clear          X       X       X
2190
cyg_drv_spinlock_try            X       X       X
2191
cyg_drv_spinlock_test           X       X       X
2192
cyg_drv_spinlock_spin_intsave   X       X       X
2193
cyg_drv_spinlock_clear_intsave  X       X       X
2194
cyg_drv_dsr_lock                        X       X
2195
cyg_drv_dsr_unlock                      X       X
2196
cyg_drv_mutex_init                              X
2197
cyg_drv_mutex_destroy                           X
2198
cyg_drv_mutex_lock                              X
2199
cyg_drv_mutex_trylock                           X
2200
cyg_drv_mutex_unlock                            X
2201
cyg_drv_mutex_release                           X
2202
cyg_drv_cond_init                               X
2203
cyg_drv_cond_destroy                            X
2204
cyg_drv_cond_wait                               X
2205
cyg_drv_cond_signal                     X       X
2206
cyg_drv_cond_broadcast                  X       X
2207
cyg_drv_interrupt_create                        X
2208
cyg_drv_interrupt_delete                        X
2209
cyg_drv_interrupt_attach        X       X       X
2210
cyg_drv_interrupt_detach        X       X       X
2211
cyg_drv_interrupt_mask          X       X       X
2212
cyg_drv_interrupt_unmask        X       X       X
2213
cyg_drv_interrupt_acknowledge   X       X       X
2214
cyg_drv_interrupt_configure     X       X       X
2215
cyg_drv_interrupt_level         X       X       X
2216
cyg_drv_interrupt_set_cpu       X       X       X
2217
cyg_drv_interrupt_get_cpu       X       X       X
2218
 
2219
2220
2221
 
2222
2223
2224
 
2225
2226
The API
2227
 
2228
2229
This section details the Driver Kernel
2230
Interface. Note that most of these functions are identical to Kernel C
2231
API calls, and will in most configurations be wrappers for them. In
2232
non-kernel configurations they will be supported directly by the HAL,
2233
or by code to emulate the required behavior.
2234
2235
 
2236
This API is defined in the header file
2237
<cyg/hal/drv_api.h>.
2238
2239
 
2240
2241
 
2242
2243
<!-- <index></index> -->cyg_drv_isr_lock
2244
 
2245
2246
  
2247
    Function:
2248
    
2249
      void cyg_drv_isr_lock()
2250
    
2251
  
2252
  
2253
    Arguments:
2254
    
2255
      None
2256
    
2257
  
2258
  
2259
    Result:
2260
    
2261
      None 
2262
    
2263
  
2264
  
2265
    Level:
2266
    
2267
      ISR
2268
    
2269
  
2270
  
2271
    Description:
2272
    
2273
      
2274
      Disables delivery of interrupts, preventing all ISRs running.  This
2275
      function maintains a counter of the number of times it is
2276
      called.
2277
      
2278
    
2279
  
2280
2281
2282
 
2283
2284
2285
 
2286
2287
<!-- <index></index> -->cyg_drv_isr_unlock
2288
 
2289
2290
  
2291
    Function:   
2292
    
2293
      void cyg_drv_isr_unlock()
2294
    
2295
  
2296
  
2297
    Arguments:
2298
    
2299
      None
2300
    
2301
  
2302
  
2303
    Result:     
2304
    
2305
      None 
2306
    
2307
  
2308
  
2309
    Level:      
2310
    
2311
      ISR
2312
    
2313
  
2314
  
2315
    Description:        
2316
    
2317
      Re-enables delivery of interrupts, allowing ISRs to
2318
      run. This function decrements the counter maintained by
2319
      cyg_drv_isr_lock(), and only re-allows
2320
      interrupts when it goes to zero. 
2321
    
2322
  
2323
2324
 
2325
2326
 
2327
2328
2329
 
2330
2331
<!-- <index></index> -->cyg_drv_spinlock_init
2332
 
2333
2334
  
2335
    Function:
2336
    
2337
2338
void cyg_drv_spinlock_init(cyg_spinlock_t *lock, cyg_bool_t locked )
2339
2340
    
2341
  
2342
  
2343
    Arguments:
2344
    
2345
      lock - pointer to spinlock to initialize
2346
      locked - initial state of lock
2347
    
2348
  
2349
  
2350
    Result:
2351
    
2352
      None
2353
    
2354
  
2355
  
2356
    Level:
2357
    
2358
      Thread
2359
    
2360
  
2361
  
2362
    Description:
2363
    
2364
      
2365
      Initialize a spinlock. The locked
2366
      argument indicates how the spinlock should be initialized:
2367
      TRUE for locked or FALSE
2368
      for unlocked state.
2369
      
2370
    
2371
  
2372
2373
 
2374
2375
 
2376
2377
2378
 
2379
2380
<!-- <index></index> -->cyg_drv_spinlock_destroy
2381
 
2382
2383
  
2384
    Function:
2385
    
2386
      void cyg_drv_spinlock_destroy(cyg_spinlock_t *lock )
2387
    
2388
  
2389
  
2390
    Arguments:
2391
    
2392
      lock - pointer to spinlock destroy
2393
    
2394
  
2395
  
2396
    Result:
2397
    
2398
      None
2399
    
2400
  
2401
  
2402
    Level:
2403
    
2404
      Thread
2405
    
2406
  
2407
  
2408
    Description:
2409
    
2410
      
2411
      Destroy a spinlock that is no longer of use. There should be no
2412
      CPUs attempting to claim the lock at the time this function is
2413
      called, otherwise the behavior is undefined.
2414
      
2415
    
2416
  
2417
2418
 
2419
2420
 
2421
2422
2423
 
2424
2425
<!-- <index></index> -->cyg_drv_spinlock_spin
2426
 
2427
2428
  
2429
    Function:
2430
    
2431
      void cyg_drv_spinlock_spin(cyg_spinlock_t *lock )
2432
    
2433
  
2434
  
2435
    Arguments:
2436
    
2437
      lock - pointer to spinlock to claim
2438
    
2439
  
2440
  
2441
    Result:
2442
    
2443
      None
2444
    
2445
  
2446
  
2447
    Level:
2448
    
2449
      ISR
2450
    
2451
  
2452
  
2453
    Description:
2454
    
2455
      
2456
      Claim a spinlock, waiting in a busy loop until it is
2457
      available. Wherever this is called from, this operation
2458
      effectively pauses the CPU until it succeeds. This operations
2459
      should therefore be used sparingly, and in situations where
2460
      deadlocks/livelocks cannot occur. Also see
2461
      cyg_drv_spinlock_spin_intsave().
2462
      
2463
    
2464
  
2465
2466
 
2467
2468
 
2469
2470
2471
 
2472
2473
<!-- <index></index> -->cyg_drv_spinlock_clear
2474
 
2475
2476
  
2477
    Function:
2478
    
2479
      void cyg_drv_spinlock_clear(cyg_spinlock_t *lock )
2480
    
2481
  
2482
  
2483
    Arguments:
2484
    
2485
      lock - pointer to spinlock to clear 
2486
    
2487
  
2488
  
2489
    Result:
2490
    
2491
      None
2492
    
2493
  
2494
  
2495
    Level:
2496
    
2497
      ISR
2498
    
2499
  
2500
  
2501
    Description:
2502
    
2503
      
2504
      Clear a spinlock. This clears the spinlock and allows another
2505
      CPU to claim it. If there is more than one CPU waiting in
2506
      cyg_drv_spinlock_spin() then just one of
2507
      them will be allowed to proceed.
2508
      
2509
    
2510
  
2511
2512
 
2513
2514
 
2515
2516
2517
 
2518
2519
<!-- <index></index> -->cyg_drv_spinlock_try
2520
 
2521
2522
  
2523
    Function:
2524
    
2525
      cyg_bool_t cyg_drv_spinlock_try(cyg_spinlock_t *lock )
2526
    
2527
  
2528
  
2529
    Arguments:
2530
    
2531
      lock - pointer to spinlock to try
2532
    
2533
  
2534
  
2535
    Result:
2536
    
2537
      TRUE if the spinlock was claimed,
2538
      FALSE otherwise.
2539
    
2540
  
2541
  
2542
    Level:
2543
    
2544
      ISR
2545
    
2546
  
2547
  
2548
    Description:
2549
    
2550
      
2551
      Try to claim the spinlock without waiting. If the spinlock could
2552
      be claimed immediately then TRUE is
2553
      returned. If the spinlock is already claimed then the result is
2554
      FALSE.
2555
      
2556
    
2557
  
2558
2559
 
2560
2561
 
2562
2563
2564
 
2565
2566
<!-- <index></index> -->cyg_drv_spinlock_test
2567
 
2568
2569
  
2570
    Function:
2571
    
2572
      cyg_bool_t cyg_drv_spinlock_test(cyg_spinlock_t *lock )
2573
    
2574
  
2575
  
2576
    Arguments:
2577
    
2578
      lock - pointer to spinlock to test
2579
    
2580
  
2581
  
2582
    Result:
2583
    
2584
      TRUE if the spinlock is available,
2585
      FALSE otherwise.
2586
    
2587
  
2588
  
2589
    Level:
2590
    
2591
      ISR
2592
    
2593
  
2594
  
2595
    Description:
2596
    
2597
      
2598
      Inspect the state of the spinlock. If the spinlock is not locked
2599
      then the result is TRUE. If it is locked then
2600
      the result will be FALSE.
2601
      
2602
    
2603
  
2604
2605
 
2606
2607
 
2608
2609
2610
 
2611
2612
<!-- <index></index> -->cyg_drv_spinlock_spin_intsave
2613
 
2614
2615
  
2616
    Function:
2617
    
2618
2619
void cyg_drv_spinlock_spin_intsave(cyg_spinlock_t *lock,
2620
                                   cyg_addrword_t *istate )
2621
2622
    
2623
  
2624
  
2625
    Arguments:
2626
    
2627
      lock - pointer to spinlock to claim
2628
      istate - pointer to interrupt state save location
2629
    
2630
  
2631
  
2632
    Result:
2633
    
2634
      None
2635
    
2636
  
2637
  
2638
    Level:
2639
    
2640
      ISR
2641
    
2642
  
2643
  
2644
    Description:
2645
    
2646
      
2647
      This function behaves exactly like
2648
      cyg_drv_spinlock_spin() except that it also
2649
      disables interrupts before attempting to claim the lock. The
2650
      current interrupt enable state is saved in
2651
      *istate. Interrupts remain disabled once
2652
      the spinlock had been claimed and must be restored by calling
2653
      cyg_drv_spinlock_clear_intsave().
2654
      
2655
      
2656
      In general, device drivers should use this function to claim and
2657
      release spinlocks rather than the
2658
      non-_intsave() variants, to ensure proper
2659
      exclusion with code running on both other CPUs and this CPU.
2660
      
2661
    
2662
  
2663
2664
 
2665
2666
 
2667
2668
2669
 
2670
2671
<!-- <index></index> -->cyg_drv_spinlock_clear_intsave
2672
 
2673
2674
  
2675
    Function:
2676
    
2677
2678
void cyg_drv_spinlock_clear_intsave( cyg_spinlock_t *lock,
2679
                                     cyg_addrword_t istate )
2680
2681
    
2682
  
2683
  
2684
    Arguments:
2685
    
2686
      lock - pointer to spinlock to clear 
2687
      istate - interrupt state to restore 
2688
    
2689
  
2690
  
2691
    Result:
2692
    
2693
      None
2694
    
2695
  
2696
  
2697
    Level:
2698
    
2699
      ISR
2700
    
2701
  
2702
  
2703
    Description:
2704
    
2705
      
2706
      This function behaves exactly like
2707
      cyg_drv_spinlock_clear() except that it
2708
      also restores an interrupt state saved by
2709
      cyg_drv_spinlock_spin_intsave(). The
2710
      istate argument must have been
2711
      initialized by a previous call to
2712
      cyg_drv_spinlock_spin_intsave().
2713
      
2714
    
2715
  
2716
2717
 
2718
2719
 
2720
2721
2722
 
2723
2724
<!-- <index></index> -->cyg_drv_dsr_lock
2725
 
2726
2727
  
2728
    Function:
2729
    
2730
      void cyg_drv_dsr_lock()
2731
    
2732
  
2733
  
2734
    Arguments:
2735
    
2736
      None
2737
    
2738
  
2739
  
2740
    Result:     
2741
    
2742
      None 
2743
    
2744
  
2745
  
2746
    Level:      
2747
    
2748
      DSR
2749
    
2750
  
2751
  
2752
    Description:        
2753
    
2754
      Disables scheduling of DSRs. This function maintains a
2755
      counter of the number of times it has been called. 
2756
    
2757
  
2758
2759
2760
 
2761
2762
2763
 
2764
2765
<!-- <index></index> -->cyg_drv_dsr_unlock
2766
 
2767
2768
  
2769
    Function:   
2770
    
2771
      void cyg_drv_dsr_unlock()
2772
    
2773
  
2774
  
2775
    Arguments:
2776
    
2777
      None
2778
    
2779
  
2780
  
2781
    Result:
2782
    
2783
                
2784
      None 
2785
    
2786
  
2787
  
2788
    Level:
2789
    
2790
      DSR
2791
    
2792
  
2793
  
2794
    Description:        
2795
    
2796
      Re-enables scheduling of DSRs. This function decrements
2797
      the counter incremented by
2798
      cyg_drv_dsr_lock().  DSRs are only allowed
2799
      to be delivered when the counter goes to zero. 
2800
    
2801
  
2802
2803
2804
 
2805
2806
2807
 
2808
2809
<!-- <index></index> -->cyg_drv_mutex_init
2810
 
2811
2812
  
2813
    Function:   
2814
    
2815
      void cyg_drv_mutex_init(cyg_drv_mutex_t *mutex)
2816
    
2817
  
2818
  
2819
    Arguments:
2820
    
2821
      mutex - pointer to mutex to initialize
2822
    
2823
  
2824
  
2825
    Result:     
2826
    
2827
      None 
2828
    
2829
  
2830
  
2831
    Level:      
2832
    
2833
      Thread
2834
    
2835
  
2836
  
2837
    Description:        
2838
    
2839
      Initialize the mutex pointed to by the
2840
      mutex argument. 
2841
    
2842
  
2843
2844
 
2845
2846
 
2847
2848
2849
 
2850
2851
<!-- <index></index> -->cyg_drv_mutex_destroy
2852
 
2853
2854
  
2855
    Function:   
2856
    
2857
      void cyg_drv_mutex_destroy( cyg_drv_mutex_t *mutex )
2858
    
2859
  
2860
  
2861
    Arguments:
2862
    
2863
      mutex - pointer to mutex to destroy
2864
    
2865
  
2866
  
2867
    Result:     
2868
    
2869
      None 
2870
    
2871
  
2872
  
2873
    Level:      
2874
    
2875
      Thread
2876
    
2877
  
2878
  
2879
    Description:        
2880
    
2881
      Destroy the mutex pointed to by the
2882
      mutex argument. The mutex should be unlocked
2883
      and there should be no threads waiting to lock it when this call
2884
      in made.
2885
    
2886
  
2887
2888
 
2889
2890
 
2891
2892
2893
 
2894
2895
<!-- <index></index> -->cyg_drv_mutex_lock
2896
 
2897
2898
  
2899
    Function:   
2900
    
2901
      cyg_bool cyg_drv_mutex_lock( cyg_drv_mutex_t *mutex )
2902
    
2903
  
2904
  
2905
    Arguments:
2906
    
2907
      mutex - pointer to mutex to lock
2908
    
2909
  
2910
  
2911
    Result:
2912
    
2913
      TRUE it the thread has claimed the
2914
      lock, FALSE otherwise.
2915
    
2916
  
2917
  
2918
    Level:
2919
    
2920
      Thread
2921
    
2922
  
2923
  
2924
    Description:        
2925
    
2926
      Attempt to lock the mutex pointed to by the
2927
      mutex argument.  If the mutex is already
2928
      locked by another thread then this thread will wait until that
2929
      thread is finished. If the result from this function is
2930
      FALSE then the thread was broken out of its
2931
      wait by some other thread. In this case the mutex will not have
2932
      been locked. 
2933
    
2934
  
2935
2936
 
2937
2938
 
2939
2940
2941
 
2942
2943
<!-- <index></index> -->cyg_drv_mutex_trylock
2944
 
2945
2946
  
2947
    Function:
2948
    
2949
      cyg_bool cyg_drv_mutex_trylock( cyg_drv_mutex_t *mutex )
2950
    
2951
  
2952
  
2953
    Arguments:
2954
    
2955
      mutex - pointer to mutex to lock
2956
    
2957
  
2958
  
2959
    Result:
2960
    
2961
      TRUE if the mutex has been locked,
2962
      FALSE otherwise. 
2963
    
2964
  
2965
  
2966
    Level:
2967
    
2968
      Thread
2969
    
2970
  
2971
  
2972
    Description:
2973
    
2974
      Attempt to lock the mutex pointed to by the
2975
      mutex argument without waiting. If the
2976
      mutex is already locked by some other thread then this function
2977
      returns FALSE. If the function can lock the
2978
      mutex without waiting, then TRUE is
2979
      returned. 
2980
    
2981
  
2982
2983
 
2984
2985
 
2986
2987
2988
 
2989
2990
<!-- <index></index> -->cyg_drv_mutex_unlock
2991
 
2992
2993
  
2994
    Function:   
2995
    
2996
      void cyg_drv_mutex_unlock( cyg_drv_mutex_t *mutex )
2997
    
2998
  
2999
  
3000
    Arguments:
3001
    
3002
      mutex - pointer to mutex to unlock
3003
    
3004
  
3005
  
3006
    Result:     
3007
    
3008
    None 
3009
    
3010
  
3011
  
3012
    Level:      
3013
    
3014
      Thread
3015
    
3016
  
3017
  
3018
    Description:        
3019
    
3020
      Unlock the mutex pointed to by the
3021
      mutex argument. If there are any threads
3022
      waiting to claim the lock, one of them is woken up to try and
3023
      claim it. 
3024
    
3025
  
3026
3027
 
3028
3029
 
3030
3031
3032
 
3033
3034
<!-- <index></index> -->cyg_drv_mutex_release
3035
 
3036
3037
  
3038
    Function:   
3039
    
3040
      void cyg_drv_mutex_release( cyg_drv_mutex_t *mutex )
3041
    
3042
  
3043
  
3044
    Arguments:
3045
    
3046
      mutex - pointer to mutex to release
3047
    
3048
  
3049
  
3050
    Result:     
3051
    
3052
      None 
3053
    
3054
  
3055
  
3056
    Level:      
3057
    
3058
      Thread
3059
    
3060
  
3061
  
3062
    Description:        
3063
    
3064
      Release all threads waiting on the mutex pointed to by the
3065
      mutex argument. These threads will return
3066
      from cyg_drv_mutex_lock() with a
3067
      FALSE result and will not have claimed the
3068
      mutex. This function has no effect on any thread that may have
3069
      the mutex claimed. 
3070
    
3071
  
3072
3073
 
3074
3075
 
3076
3077
3078
 
3079
3080
<!-- <index></index> -->cyg_drv_cond_init
3081
 
3082
3083
  
3084
    Function:   
3085
    
3086
       void cyg_drv_cond_init( cyg_drv_cond_t *cond, cyg_drv_mutex_t *mutex )
3087
              
3088
    
3089
  
3090
  
3091
    Arguments:
3092
    
3093
      cond - condition variable to initialize
3094
      mutex - mutex to associate with this condition variable
3095
    
3096
  
3097
  
3098
    Result:     
3099
    
3100
      None
3101
    
3102
  
3103
  
3104
    Level:      
3105
    
3106
      Thread 
3107
    
3108
  
3109
  
3110
    Description:        
3111
    
3112
      Initialize the condition variable pointed to by the
3113
      cond argument.  The
3114
      mutex argument must point to a mutex with
3115
      which this condition variable is associated. A thread may only
3116
      wait on this condition variable when it has already locked the
3117
      associated mutex. Waiting will cause the mutex to be unlocked,
3118
      and when the thread is reawakened, it will automatically claim
3119
      the mutex before continuing. 
3120
    
3121
  
3122
3123
 
3124
3125
 
3126
3127
3128
 
3129
3130
<!-- <index></index> -->cyg_drv_cond_destroy
3131
 
3132
3133
  
3134
    Function:   
3135
    
3136
       void cyg_drv_cond_destroy( cyg_drv_cond_t *cond )
3137
    
3138
  
3139
  
3140
    Arguments:
3141
    
3142
      cond - condition variable to destroy
3143
    
3144
  
3145
  
3146
    Result:     
3147
    
3148
      None 
3149
    
3150
  
3151
  
3152
    Level:      
3153
    
3154
      Thread
3155
    
3156
  
3157
  
3158
    Description:        
3159
    
3160
      Destroy the condition variable pointed to by the
3161
      cond argument. 
3162
    
3163
  
3164
3165
 
3166
3167
 
3168
3169
3170
 
3171
3172
<!-- <index></index> -->cyg_drv_cond_wait
3173
 
3174
3175
  
3176
    Function:   
3177
    
3178
      void cyg_drv_cond_wait( cyg_drv_cond_t *cond )
3179
    
3180
  
3181
  
3182
    Arguments:
3183
    
3184
      cond - condition variable to wait on
3185
    
3186
  
3187
  
3188
    Result:     
3189
    
3190
      None 
3191
    
3192
  
3193
  
3194
    Level:      
3195
    
3196
      Thread
3197
    
3198
  
3199
  
3200
    Description:        
3201
    
3202
      Wait for a signal on the condition variable pointed to by
3203
      the cond argument. The thread must have
3204
      locked the associated mutex, supplied in
3205
      cyg_drv_cond_init(), before waiting on this
3206
      condition variable. While the thread waits, the mutex will be
3207
      unlocked, and will be re-locked before this function returns. It
3208
      is possible for threads waiting on a condition variable to
3209
      occasionally wake up spuriously. For this reason it is necessary
3210
      to use this function in a loop that re-tests the condition each
3211
      time it returns. Note that this function performs an implicit
3212
      scheduler unlock/relock sequence, so that it may be used within
3213
      an explicit
3214
      cyg_drv_dsr_lock()...cyg_drv_dsr_unlock()
3215
      structure.
3216
    
3217
  
3218
3219
 
3220
3221
 
3222
3223
3224
 
3225
3226
<!-- <index></index> -->cyg_drv_cond_signal
3227
 
3228
3229
  
3230
    Function:   
3231
    
3232
      void cyg_drv_cond_signal( cyg_drv_cond_t *cond )
3233
    
3234
  
3235
  
3236
    Arguments:
3237
    
3238
      cond - condition variable to signal
3239
    
3240
  
3241
  
3242
    Result:     
3243
    
3244
      None 
3245
    
3246
  
3247
  
3248
    Level:      
3249
    
3250
      DSR
3251
    
3252
  
3253
  
3254
    Description:        
3255
    
3256
      Signal the condition variable pointed to by the cond
3257
      argument.  If there are any threads waiting on this variable at
3258
      least one of them will be awakened. Note that in some
3259
      configurations there may not be any difference between this
3260
      function and cyg_drv_cond_broadcast().
3261
      
3262
    
3263
  
3264
3265
 
3266
3267
 
3268
3269
3270
 
3271
3272
<!-- <index></index> -->cyg_drv_cond_broadcast
3273
 
3274
3275
  
3276
    Function:   
3277
    
3278
      void cyg_drv_cond_broadcast( cyg_drv_cond_t *cond )
3279
    
3280
  
3281
  
3282
    Arguments:
3283
    
3284
      cond - condition variable to broadcast to
3285
    
3286
  
3287
  
3288
    Result:     
3289
    
3290
      None 
3291
    
3292
  
3293
  
3294
    Level:      
3295
    
3296
      DSR
3297
    
3298
  
3299
  
3300
    Description:        
3301
    
3302
      Signal the condition variable pointed to by the
3303
      cond argument.  If there are any threads
3304
      waiting on this variable they will all be awakened. 
3305
    
3306
  
3307
3308
 
3309
3310
 
3311
3312
3313
 
3314
3315
<!-- <index></index> -->cyg_drv_interrupt_create
3316
 
3317
3318
  
3319
    Function:   
3320
    
3321
3322
void cyg_drv_interrupt_create( cyg_vector_t vector,
3323
                               cyg_priority_t priority,
3324
                               cyg_addrword_t data,
3325
                               cyg_ISR_t *isr,
3326
                               cyg_DSR_t *dsr,
3327
                               cyg_handle_t *handle,
3328
                               cyg_interrupt *intr
3329
                             )
3330
3331
    
3332
  
3333
  
3334
    Arguments:
3335
    
3336
      vector - vector to attach to
3337
      priority - queuing priority
3338
      data - data pointer
3339
      isr - interrupt service routine
3340
      dsr - deferred service routine
3341
      handle - returned handle
3342
      intr - put interrupt object here
3343
    
3344
  
3345
  
3346
    Result:     
3347
    
3348
      None
3349
    
3350
  
3351
  
3352
    Level:      
3353
    
3354
      Thread
3355
    
3356
  
3357
  
3358
    Description:        
3359
    
3360
      Create an interrupt object and returns a handle to it. The
3361
      object contains information about which interrupt vector to use
3362
      and the ISR and DSR that will be called after the interrupt
3363
      object is attached to the vector. The interrupt object will be
3364
      allocated in the memory passed in the
3365
      intr parameter. The interrupt object is
3366
      not immediately attached; it must be attached with the
3367
      cyg_interrupt_attach() call. 
3368
    
3369
  
3370
3371
3372
 
3373
3374
3375
 
3376
3377
<!-- <index></index> -->cyg_drv_interrupt_delete
3378
 
3379
3380
  
3381
    Function:   
3382
    
3383
       void cyg_drv_interrupt_delete( cyg_handle_t interrupt )
3384
    
3385
  
3386
  
3387
    Arguments:
3388
    
3389
      interrupt - interrupt to delete
3390
    
3391
  
3392
  
3393
    Result:     
3394
    
3395
      None 
3396
    
3397
  
3398
  
3399
    Level:      
3400
    
3401
      Thread
3402
    
3403
  
3404
  
3405
    Description:        
3406
    
3407
      Detach the interrupt from the vector and free the memory
3408
      passed in the intr argument to
3409
      cyg_drv_interrupt_create() for
3410
      reuse. 
3411
    
3412
  
3413
3414
 
3415
3416
 
3417
3418
3419
 
3420
3421
<!-- <index></index> -->cyg_drv_interrupt_attach
3422
 
3423
3424
  
3425
    Function:   
3426
    
3427
      void cyg_drv_interrupt_attach( cyg_handle_t interrupt )
3428
    
3429
  
3430
  
3431
    Arguments:
3432
    
3433
      interrupt - interrupt to attach
3434
    
3435
  
3436
  
3437
    Result:     
3438
    
3439
      None 
3440
    
3441
  
3442
  
3443
    Level:      
3444
    
3445
      ISR
3446
    
3447
  
3448
  
3449
    Description:        
3450
    
3451
      Attach the interrupt to the vector so that interrupts will
3452
      be delivered to the ISR when the interrupt occurs. 
3453
    
3454
  
3455
3456
3457
 
3458
3459
3460
 
3461
3462
<!-- <index></index> -->cyg_drv_interrupt_detach
3463
 
3464
3465
  
3466
    Function:   
3467
    
3468
      void cyg_drv_interrupt_detach( cyg_handle_t interrupt )
3469
    
3470
  
3471
  
3472
    Arguments:
3473
    
3474
      interrupt - interrupt to detach
3475
    
3476
  
3477
  
3478
    Result:     
3479
    
3480
      None 
3481
    
3482
  
3483
  
3484
    Level:      
3485
    
3486
      ISR
3487
    
3488
  
3489
  
3490
    Description:        
3491
    
3492
      Detach the interrupt from the vector so that interrupts
3493
      will no longer be delivered to the ISR. 
3494
    
3495
  
3496
3497
 
3498
3499
 
3500
3501
3502
 
3503
3504
<!-- <index></index> -->cyg_drv_interrupt_mask
3505
 
3506
3507
  
3508
    Function:   
3509
    
3510
      void cyg_drv_interrupt_mask(cyg_vector_t vector )
3511
    
3512
  
3513
  
3514
    Arguments:
3515
    
3516
      vector - vector to mask
3517
    
3518
  
3519
  
3520
    Result:     
3521
    
3522
      None 
3523
    
3524
  
3525
  
3526
    Level:      
3527
    
3528
      ISR
3529
    
3530
  
3531
  
3532
    Description:        
3533
    
3534
      Program the interrupt controller to stop delivery of
3535
      interrupts on the given vector. On architectures which implement
3536
      interrupt priority levels this may also disable all lower
3537
      priority interrupts. 
3538
    
3539
  
3540
3541
3542
 
3543
3544
3545
 
3546
3547
<!-- <index></index> -->cyg_drv_interrupt_mask_intunsafe
3548
 
3549
3550
  
3551
    Function:   
3552
    
3553
      void cyg_drv_interrupt_mask_intunsafe(cyg_vector_t vector )
3554
    
3555
  
3556
  
3557
    Arguments:
3558
    
3559
      vector - vector to mask
3560
    
3561
  
3562
  
3563
    Result:     
3564
    
3565
      None 
3566
    
3567
  
3568
  
3569
    Level:      
3570
    
3571
      ISR
3572
    
3573
  
3574
  
3575
    Description:        
3576
    
3577
      Program the interrupt controller to stop delivery of
3578
      interrupts on the given vector. On architectures which implement
3579
      interrupt priority levels this may also disable all lower
3580
      priority interrupts. This version differs from
3581
      cyg_drv_interrupt_mask() in not being
3582
      interrupt safe. So in situations where, for example, interrupts
3583
      are already known to be disabled, this may be called to avoid
3584
      the extra overhead.
3585
    
3586
  
3587
3588
3589
 
3590
3591
3592
 
3593
3594
<!-- <index></index> -->cyg_drv_interrupt_unmask
3595
 
3596
3597
  
3598
    Function:   
3599
    
3600
      void cyg_drv_interrupt_unmask(cyg_vector_t vector )
3601
    
3602
  
3603
  
3604
    Arguments:
3605
    
3606
      vector - vector to unmask
3607
    
3608
  
3609
  
3610
    Result:     
3611
    
3612
      None 
3613
    
3614
  
3615
  
3616
    Level:      
3617
    
3618
      ISR
3619
    
3620
  
3621
  
3622
    Description:        
3623
    
3624
      Program the interrupt controller to re-allow delivery of
3625
      interrupts on the given vector. 
3626
    
3627
  
3628
3629
3630
 
3631
3632
3633
 
3634
3635
<!-- <index></index> -->cyg_drv_interrupt_unmask_intunsafe
3636
 
3637
3638
  
3639
    Function:   
3640
    
3641
      void cyg_drv_interrupt_unmask_intunsafe(cyg_vector_t vector )
3642
    
3643
  
3644
  
3645
    Arguments:
3646
    
3647
      vector - vector to unmask
3648
    
3649
  
3650
  
3651
    Result:     
3652
    
3653
      None 
3654
    
3655
  
3656
  
3657
    Level:      
3658
    
3659
      ISR
3660
    
3661
  
3662
  
3663
    Description:        
3664
    
3665
      Program the interrupt controller to re-allow delivery of
3666
      interrupts on the given vector. This
3667
      version differs from
3668
      cyg_drv_interrupt_unmask() in not being
3669
      interrupt safe.
3670
    
3671
  
3672
3673
3674
 
3675
3676
3677
 
3678
3679
<!-- <index></index> -->cyg_drv_interrupt_acknowledge
3680
 
3681
3682
  
3683
    Function:   
3684
    
3685
      void cyg_drv_interrupt_acknowledge( cyg_vector_t vector )
3686
    
3687
  
3688
  
3689
    Arguments:
3690
    
3691
      vector - vector to acknowledge
3692
    
3693
  
3694
  
3695
    Result:     
3696
    
3697
      None 
3698
    
3699
  
3700
  
3701
    Level:      
3702
    
3703
      ISR
3704
    
3705
  
3706
  
3707
    Description:        
3708
    
3709
      Perform any processing required at the interrupt
3710
      controller and in the CPU to cancel the current interrupt
3711
      request on the vector. An ISR may also
3712
      need to program the hardware of the device to prevent an
3713
      immediate re-triggering of the interrupt. 
3714
    
3715
  
3716
3717
3718
 
3719
3720
3721
 
3722
3723
<!-- <index></index> -->cyg_drv_interrupt_configure
3724
 
3725
3726
  
3727
    Function:   
3728
    
3729
      
3730
void cyg_drv_interrupt_configure( cyg_vector_t vector,
3731
                                  cyg_bool_t level,
3732
                                  cyg_bool_t up
3733
                                )
3734
3735
    
3736
  
3737
  
3738
    Arguments:
3739
    
3740
      vector - vector to configure
3741
      level - level or edge triggered
3742
      up - rising/falling edge, high/low level
3743
    
3744
  
3745
  
3746
    Result:     
3747
    
3748
      None
3749
    
3750
  
3751
  
3752
    Level:      
3753
    
3754
      ISR
3755
    
3756
  
3757
  
3758
    Description:        
3759
    
3760
      Program the interrupt controller with the characteristics
3761
      of the interrupt source. The level
3762
      argument chooses between level- or edge-triggered
3763
      interrupts. The up argument chooses
3764
      between high and low level for level triggered interrupts or
3765
      rising and falling edges for edge triggered interrupts. This
3766
      function only works with interrupt controllers that can control
3767
      these parameters. 
3768
    
3769
  
3770
3771
 
3772
3773
 
3774
3775
3776
 
3777
3778
<!-- <index></index> -->cyg_drv_interrupt_level
3779
 
3780
3781
  
3782
    Function:   
3783
    
3784
3785
void cyg_drv_interrupt_level( cyg_vector_t vector,
3786
                              cyg_priority_t level
3787
                            )
3788
3789
    
3790
  
3791
  
3792
    Arguments:
3793
    
3794
      vector - vector to configure
3795
      level - level to set
3796
    
3797
  
3798
  
3799
    Result:     
3800
    
3801
      None 
3802
    
3803
  
3804
  
3805
    Level:      
3806
    
3807
      ISR
3808
    
3809
  
3810
  
3811
    Description:        
3812
    
3813
      Program the interrupt controller to deliver the given
3814
       interrupt at the supplied priority level. This function only
3815
       works with interrupt controllers that can control this
3816
       parameter.
3817
    
3818
  
3819
3820
 
3821
3822
 
3823
3824
3825
 
3826
3827
<!-- <index></index> -->cyg_drv_interrupt_set_cpu
3828
 
3829
3830
  
3831
    Function:
3832
    
3833
3834
void cyg_drv_interrupt_set_cpu( cyg_vector_t vector,
3835
                                cyg_cpu_t cpu
3836
                              )
3837
3838
    
3839
  
3840
  
3841
    Arguments:
3842
    
3843
      vector - interrupt vector to route
3844
      cpu - destination CPU
3845
    
3846
  
3847
  
3848
    Result:
3849
    
3850
      None
3851
    
3852
  
3853
  
3854
    Level:
3855
    
3856
      ISR
3857
    
3858
  
3859
  
3860
    Description:        
3861
    
3862
      
3863
      This function causes all interrupts on the given vector to be
3864
      routed to the specified CPU. Subsequently, all such interrupts
3865
      will be handled by that CPU. This only works if the underlying
3866
      hardware is capable of performing this kind of routing. This
3867
      function does nothing on a single CPU system.
3868
      
3869
    
3870
  
3871
3872
 
3873
3874
 
3875
3876
3877
 
3878
3879
<!-- <index></index> -->cyg_drv_interrupt_get_cpu
3880
 
3881
3882
  
3883
    Function:
3884
    
3885
3886
cyg_cpu_t cyg_drv_interrupt_set_cpu( cyg_vector_t vector )
3887
3888
    
3889
  
3890
  
3891
    Arguments:
3892
    
3893
      vector - interrupt vector to query
3894
    
3895
  
3896
  
3897
    Result:
3898
    
3899
      The CPU to which this vector is routed
3900
    
3901
  
3902
  
3903
    Level:
3904
    
3905
      ISR
3906
    
3907
  
3908
  
3909
    Description:        
3910
    
3911
      
3912
      In multi-processor systems this function returns the id of the
3913
      CPU to which interrupts on the given vector are current being
3914
      delivered. In single CPU systems this function returns zero.
3915
      
3916
    
3917
  
3918
3919
 
3920
3921
 
3922
3923
3924
 
3925
3926
<!-- <index></index> -->cyg_ISR_t
3927
 
3928
3929
  
3930
    Type:       
3931
    
3932
3933
typedef cyg_uint32 cyg_ISR_t( cyg_vector_t vector,
3934
                              cyg_addrword_t data
3935
                            )
3936
3937
    
3938
  
3939
  
3940
    Fields:
3941
    
3942
      vector - vector being delivered
3943
      data - data value supplied by client
3944
    
3945
  
3946
  
3947
    Result:     
3948
    
3949
      Bit mask indicating whether interrupt was handled and
3950
      whether the DSR should be called. 
3951
    
3952
  
3953
  
3954
    Description:        
3955
    
3956
      Interrupt Service Routine definition. A pointer to a
3957
      function with this prototype is passed to
3958
      cyg_interrupt_create() when an interrupt
3959
      object is created. When an interrupt is delivered the function
3960
      will be called with the vector number and the data value that
3961
      was passed to cyg_interrupt_create().
3962
      
3963
      The return value is a bit mask containing one or both of the
3964
      following bits: 
3965
      
3966
        
3967
          CYG_ISR_HANDLED       
3968
          
3969
            indicates that the interrupt was handled by this
3970
            ISR. It is a configuration option whether this will
3971
            prevent further ISR being run. 
3972
          
3973
        
3974
        
3975
          CYG_ISR_CALL_DSR      
3976
          
3977
            causes the DSR that was passed to
3978
            cyg_interrupt_create() to be
3979
            scheduled to be called.
3980
          
3981
        
3982
      
3983
    
3984
  
3985
3986
 
3987
3988
 
3989
3990
3991
 
3992
3993
<!-- <index></index> -->cyg_DSR_t
3994
 
3995
3996
  
3997
    Type:       
3998
    
3999
4000
typedef void cyg_DSR_t( cyg_vector_t vector,
4001
                        cyg_ucount32 count,
4002
                        cyg_addrword_t data
4003
                      )
4004
4005
    
4006
  
4007
  
4008
    Fields:
4009
    
4010
      vector - vector being delivered
4011
      count - number of times DSR has been scheduled
4012
      data - data value supplied by client
4013
    
4014
  
4015
  
4016
    Result:     
4017
    
4018
      None
4019
    
4020
  
4021
  
4022
    Description:        
4023
    
4024
      Deferred Service Routine prototype. A pointer to a
4025
      function with this prototype is passed to
4026
      cyg_interrupt_create() when an interrupt
4027
      object is created. When the ISR requests the scheduling of its
4028
      DSR, this function will be called at some later point. In
4029
      addition to the vector and
4030
      data arguments, which will be the same as
4031
      those passed to the ISR, this routine is also passed a
4032
      count of the number of times the ISR has
4033
      requested that this DSR be scheduled.  This counter is zeroed
4034
      each time the DSR actually runs, so it indicates how many
4035
      interrupts have occurred since it last ran.
4036
    
4037
  
4038
4039
 
4040
4041
 
4042
4043
 
4044
4045
 
4046
4047
 
4048
4049
 
4050
4051
 
4052
 
4053

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.