1 <!-- Copyright (C) 2003 Red Hat, Inc. -->
2 <!-- This material may be distributed only subject to the terms -->
3 <!-- and conditions set forth in the Open Publication License, v1.0 -->
4 <!-- or later (the latest version is presently available at -->
5 <!-- http://www.opencontent.org/openpub/). -->
6 <!-- Distribution of the work or derivative of the work in any -->
7 <!-- standard (paper) book form is prohibited unless prior -->
8 <!-- permission is obtained from the copyright holder. -->
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="Device Driver Interface to the Kernel"
23 HREF="devapi-device-driver-interface-to-the-kernel.html"><LINK
25 TITLE="Synchronization Levels"
26 HREF="devapi-synchronization-levels.html"><LINK
28 TITLE="File System Support Infrastructure"
29 HREF="fileio.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="devapi-synchronization-levels.html"
65 >Chapter 18. Device Driver Interface to the Kernel</TD
85 NAME="DEVAPI-API">The API</H1
87 >This section details the Driver Kernel
88 Interface. Note that most of these functions are identical to Kernel C
89 API calls, and will in most configurations be wrappers for them. In
90 non-kernel configurations they will be supported directly by the HAL,
91 or by code to emulate the required behavior.</P
93 >This API is defined in the header file
96 ><cyg/hal/drv_api.h></TT
103 NAME="AEN11310">cyg_drv_isr_lock</H2
119 CLASS="PROGRAMLISTING"
120 >void cyg_drv_isr_lock()</PRE
147 > Disables delivery of interrupts, preventing all ISRs running. This
148 function maintains a counter of the number of times it is
160 NAME="AEN11333">cyg_drv_isr_unlock</H2
176 CLASS="PROGRAMLISTING"
177 >void cyg_drv_isr_unlock()</PRE
204 >Re-enables delivery of interrupts, allowing ISRs to
205 run. This function decrements the counter maintained by
208 >cyg_drv_isr_lock()</TT
209 >, and only re-allows
210 interrupts when it goes to zero. </P
220 NAME="AEN11357">cyg_drv_spinlock_init</H2
236 CLASS="PROGRAMLISTING"
237 >void cyg_drv_spinlock_init(cyg_spinlock_t *lock, cyg_bool_t locked )</PRE
251 > - pointer to spinlock to initialize</P
258 > - initial state of lock</P
276 > Initialize a spinlock. The <TT
282 argument indicates how the spinlock should be initialized:
301 NAME="AEN11386">cyg_drv_spinlock_destroy</H2
317 CLASS="PROGRAMLISTING"
318 >void cyg_drv_spinlock_destroy(cyg_spinlock_t *lock )</PRE
332 > - pointer to spinlock destroy</P
350 > Destroy a spinlock that is no longer of use. There should be no
351 CPUs attempting to claim the lock at the time this function is
352 called, otherwise the behavior is undefined.
363 NAME="AEN11410">cyg_drv_spinlock_spin</H2
379 CLASS="PROGRAMLISTING"
380 >void cyg_drv_spinlock_spin(cyg_spinlock_t *lock )</PRE
394 > - pointer to spinlock to claim</P
412 > Claim a spinlock, waiting in a busy loop until it is
413 available. Wherever this is called from, this operation
414 effectively pauses the CPU until it succeeds. This operations
415 should therefore be used sparingly, and in situations where
416 deadlocks/livelocks cannot occur. Also see
419 >cyg_drv_spinlock_spin_intsave()</TT
431 NAME="AEN11435">cyg_drv_spinlock_clear</H2
447 CLASS="PROGRAMLISTING"
448 >void cyg_drv_spinlock_clear(cyg_spinlock_t *lock )</PRE
462 > - pointer to spinlock to clear </P
480 > Clear a spinlock. This clears the spinlock and allows another
481 CPU to claim it. If there is more than one CPU waiting in
484 >cyg_drv_spinlock_spin()</TT
486 them will be allowed to proceed.
497 NAME="AEN11460">cyg_drv_spinlock_try</H2
513 CLASS="PROGRAMLISTING"
514 >cyg_bool_t cyg_drv_spinlock_try(cyg_spinlock_t *lock )</PRE
528 > - pointer to spinlock to try</P
537 > if the spinlock was claimed,
553 > Try to claim the spinlock without waiting. If the spinlock could
554 be claimed immediately then <TT
558 returned. If the spinlock is already claimed then the result is
573 NAME="AEN11488">cyg_drv_spinlock_test</H2
589 CLASS="PROGRAMLISTING"
590 >cyg_bool_t cyg_drv_spinlock_test(cyg_spinlock_t *lock )</PRE
604 > - pointer to spinlock to test</P
613 > if the spinlock is available,
629 > Inspect the state of the spinlock. If the spinlock is not locked
630 then the result is <TT
633 >. If it is locked then
634 the result will be <TT
648 NAME="AEN11516">cyg_drv_spinlock_spin_intsave</H2
664 CLASS="PROGRAMLISTING"
665 >void cyg_drv_spinlock_spin_intsave(cyg_spinlock_t *lock,
666 cyg_addrword_t *istate )</PRE
680 > - pointer to spinlock to claim</P
687 > - pointer to interrupt state save location</P
705 > This function behaves exactly like
708 >cyg_drv_spinlock_spin()</TT
709 > except that it also
710 disables interrupts before attempting to claim the lock. The
711 current interrupt enable state is saved in
717 >. Interrupts remain disabled once
718 the spinlock had been claimed and must be restored by calling
721 >cyg_drv_spinlock_clear_intsave()</TT
725 > In general, device drivers should use this function to claim and
726 release spinlocks rather than the
730 > variants, to ensure proper
731 exclusion with code running on both other CPUs and this CPU.
742 NAME="AEN11547">cyg_drv_spinlock_clear_intsave</H2
758 CLASS="PROGRAMLISTING"
759 >void cyg_drv_spinlock_clear_intsave( cyg_spinlock_t *lock,
760 cyg_addrword_t istate )</PRE
774 > - pointer to spinlock to clear </P
781 > - interrupt state to restore </P
799 > This function behaves exactly like
802 >cyg_drv_spinlock_clear()</TT
804 also restores an interrupt state saved by
807 >cyg_drv_spinlock_spin_intsave()</TT
814 > argument must have been
815 initialized by a previous call to
818 >cyg_drv_spinlock_spin_intsave()</TT
830 NAME="AEN11577">cyg_drv_dsr_lock</H2
846 CLASS="PROGRAMLISTING"
847 >void cyg_drv_dsr_lock()</PRE
874 >Disables scheduling of DSRs. This function maintains a
875 counter of the number of times it has been called. </P
885 NAME="AEN11600">cyg_drv_dsr_unlock</H2
901 CLASS="PROGRAMLISTING"
902 >void cyg_drv_dsr_unlock()</PRE
931 >Re-enables scheduling of DSRs. This function decrements
932 the counter incremented by
935 >cyg_drv_dsr_lock()</TT
936 >. DSRs are only allowed
937 to be delivered when the counter goes to zero. </P
947 NAME="AEN11625">cyg_drv_mutex_init</H2
963 CLASS="PROGRAMLISTING"
964 >void cyg_drv_mutex_init(cyg_drv_mutex *mutex)</PRE
978 > - pointer to mutex to initialize</P
996 >Initialize the mutex pointed to by the
1010 NAME="AEN11650">cyg_drv_mutex_destroy</H2
1014 CLASS="VARIABLELIST"
1026 CLASS="PROGRAMLISTING"
1027 >void cyg_drv_mutex_destroy( cyg_drv_mutex *mutex )</PRE
1041 > - pointer to mutex to destroy</P
1059 >Destroy the mutex pointed to by the
1065 > argument. The mutex should be unlocked
1066 and there should be no threads waiting to lock it when this call
1077 NAME="AEN11675">cyg_drv_mutex_lock</H2
1081 CLASS="VARIABLELIST"
1093 CLASS="PROGRAMLISTING"
1094 >cyg_bool cyg_drv_mutex_lock( cyg_drv_mutex *mutex )</PRE
1108 > - pointer to mutex to lock</P
1117 > it the thread has claimed the
1133 >Attempt to lock the mutex pointed to by the
1139 > argument. If the mutex is already
1140 locked by another thread then this thread will wait until that
1141 thread is finished. If the result from this function is
1145 > then the thread was broken out of its
1146 wait by some other thread. In this case the mutex will not have
1157 NAME="AEN11703">cyg_drv_mutex_trylock</H2
1161 CLASS="VARIABLELIST"
1174 CLASS="PROGRAMLISTING"
1175 >cyg_bool cyg_drv_mutex_trylock( cyg_drv_mutex *mutex )</PRE
1190 > - pointer to mutex to lock</P
1199 > if the mutex has been locked,
1215 >Attempt to lock the mutex pointed to by the
1221 > argument without waiting. If the
1222 mutex is already locked by some other thread then this function
1226 >. If the function can lock the
1227 mutex without waiting, then <TT
1241 NAME="AEN11733">cyg_drv_mutex_unlock</H2
1245 CLASS="VARIABLELIST"
1257 CLASS="PROGRAMLISTING"
1258 >void cyg_drv_mutex_unlock( cyg_drv_mutex *mutex )</PRE
1272 > - pointer to mutex to unlock</P
1290 >Unlock the mutex pointed to by the
1296 > argument. If there are any threads
1297 waiting to claim the lock, one of them is woken up to try and
1308 NAME="AEN11758">cyg_drv_mutex_release</H2
1312 CLASS="VARIABLELIST"
1324 CLASS="PROGRAMLISTING"
1325 >void cyg_drv_mutex_release( cyg_drv_mutex *mutex )</PRE
1337 > - pointer to mutex to release</P
1355 >Release all threads waiting on the mutex pointed to by the
1361 > argument. These threads will return
1364 >cyg_drv_mutex_lock()</TT
1369 > result and will not have claimed the
1370 mutex. This function has no effect on any thread that may have
1371 the mutex claimed. </P
1381 NAME="AEN11785">cyg_drv_cond_init</H2
1385 CLASS="VARIABLELIST"
1397 CLASS="PROGRAMLISTING"
1398 > void cyg_drv_cond_init( cyg_drv_cond *cond, cyg_drv_mutex *mutex )
1413 > - condition variable to initialize</P
1420 > - mutex to associate with this condition variable</P
1438 >Initialize the condition variable pointed to by the
1450 > argument must point to a mutex with
1451 which this condition variable is associated. A thread may only
1452 wait on this condition variable when it has already locked the
1453 associated mutex. Waiting will cause the mutex to be unlocked,
1454 and when the thread is reawakened, it will automatically claim
1455 the mutex before continuing. </P
1465 NAME="AEN11813">cyg_drv_cond_destroy</H2
1469 CLASS="VARIABLELIST"
1481 CLASS="PROGRAMLISTING"
1482 > void cyg_drv_cond_destroy( cyg_drv_cond *cond )</PRE
1496 > - condition variable to destroy</P
1514 >Destroy the condition variable pointed to by the
1530 NAME="AEN11838">cyg_drv_cond_wait</H2
1534 CLASS="VARIABLELIST"
1546 CLASS="PROGRAMLISTING"
1547 >void cyg_drv_cond_wait( cyg_drv_cond *cond )</PRE
1561 > - condition variable to wait on</P
1579 >Wait for a signal on the condition variable pointed to by
1585 > argument. The thread must have
1586 locked the associated mutex, supplied in
1589 >cyg_drv_cond_init()</TT
1590 >, before waiting on this
1591 condition variable. While the thread waits, the mutex will be
1592 unlocked, and will be re-locked before this function returns. It
1593 is possible for threads waiting on a condition variable to
1594 occasionally wake up spuriously. For this reason it is necessary
1595 to use this function in a loop that re-tests the condition each
1596 time it returns. Note that this function performs an implicit
1597 scheduler unlock/relock sequence, so that it may be used within
1601 >cyg_drv_dsr_lock()...cyg_drv_dsr_unlock()</TT
1613 NAME="AEN11865">cyg_drv_cond_signal</H2
1617 CLASS="VARIABLELIST"
1629 CLASS="PROGRAMLISTING"
1630 >void cyg_drv_cond_signal( cyg_drv_cond *cond )</PRE
1644 > - condition variable to signal</P
1662 >Signal the condition variable pointed to by the <TT
1668 argument. If there are any threads waiting on this variable at
1669 least one of them will be awakened. Note that in some
1670 configurations there may not be any difference between this
1673 >cyg_drv_cond_broadcast()</TT
1685 NAME="AEN11891">cyg_drv_cond_broadcast</H2
1689 CLASS="VARIABLELIST"
1701 CLASS="PROGRAMLISTING"
1702 >void cyg_drv_cond_broadcast( cyg_drv_cond *cond )</PRE
1716 > - condition variable to broadcast to</P
1734 >Signal the condition variable pointed to by the
1740 > argument. If there are any threads
1741 waiting on this variable they will all be awakened. </P
1751 NAME="AEN11916">cyg_drv_interrupt_create</H2
1755 CLASS="VARIABLELIST"
1767 CLASS="PROGRAMLISTING"
1768 >void cyg_drv_interrupt_create( cyg_vector_t vector,
1769 cyg_priority_t priority,
1770 cyg_addrword_t data,
1773 cyg_handle_t *handle,
1789 > - vector to attach to</P
1796 > - queuing priority</P
1810 > - interrupt service routine</P
1817 > - deferred service routine</P
1824 > - returned handle</P
1831 > - put interrupt object here</P
1849 >Create an interrupt object and returns a handle to it. The
1850 object contains information about which interrupt vector to use
1851 and the ISR and DSR that will be called after the interrupt
1852 object is attached to the vector. The interrupt object will be
1853 allocated in the memory passed in the
1859 > parameter. The interrupt object is
1860 not immediately attached; it must be attached with the
1863 >cyg_interrupt_attach()</TT
1874 NAME="AEN11954">cyg_drv_interrupt_delete</H2
1878 CLASS="VARIABLELIST"
1890 CLASS="PROGRAMLISTING"
1891 > void cyg_drv_interrupt_delete( cyg_handle_t interrupt )</PRE
1905 > - interrupt to delete</P
1923 >Detach the interrupt from the vector and free the memory
1932 >cyg_drv_interrupt_create()</TT
1944 NAME="AEN11980">cyg_drv_interrupt_attach</H2
1948 CLASS="VARIABLELIST"
1960 CLASS="PROGRAMLISTING"
1961 >void cyg_drv_interrupt_attach( cyg_handle_t interrupt )</PRE
1975 > - interrupt to attach</P
1993 >Attach the interrupt to the vector so that interrupts will
1994 be delivered to the ISR when the interrupt occurs. </P
2004 NAME="AEN12004">cyg_drv_interrupt_detach</H2
2008 CLASS="VARIABLELIST"
2020 CLASS="PROGRAMLISTING"
2021 >void cyg_drv_interrupt_detach( cyg_handle_t interrupt )</PRE
2035 > - interrupt to detach</P
2053 >Detach the interrupt from the vector so that interrupts
2054 will no longer be delivered to the ISR. </P
2064 NAME="AEN12028">cyg_drv_interrupt_mask</H2
2068 CLASS="VARIABLELIST"
2080 CLASS="PROGRAMLISTING"
2081 >void cyg_drv_interrupt_mask(cyg_vector_t vector )</PRE
2095 > - vector to mask</P
2113 >Program the interrupt controller to stop delivery of
2114 interrupts on the given vector. On architectures which implement
2115 interrupt priority levels this may also disable all lower
2116 priority interrupts. </P
2126 NAME="AEN12052">cyg_drv_interrupt_mask_intunsafe</H2
2130 CLASS="VARIABLELIST"
2142 CLASS="PROGRAMLISTING"
2143 >void cyg_drv_interrupt_mask_intunsafe(cyg_vector_t vector )</PRE
2157 > - vector to mask</P
2175 >Program the interrupt controller to stop delivery of
2176 interrupts on the given vector. On architectures which implement
2177 interrupt priority levels this may also disable all lower
2178 priority interrupts. This version differs from
2181 >cyg_drv_interrupt_mask()</TT
2183 interrupt safe. So in situations where, for example, interrupts
2184 are already known to be disabled, this may be called to avoid
2185 the extra overhead.</P
2195 NAME="AEN12077">cyg_drv_interrupt_unmask</H2
2199 CLASS="VARIABLELIST"
2211 CLASS="PROGRAMLISTING"
2212 >void cyg_drv_interrupt_unmask(cyg_vector_t vector )</PRE
2226 > - vector to unmask</P
2244 >Program the interrupt controller to re-allow delivery of
2245 interrupts on the given <TT
2260 NAME="AEN12102">cyg_drv_interrupt_unmask_intunsafe</H2
2264 CLASS="VARIABLELIST"
2276 CLASS="PROGRAMLISTING"
2277 >void cyg_drv_interrupt_unmask_intunsafe(cyg_vector_t vector )</PRE
2291 > - vector to unmask</P
2309 >Program the interrupt controller to re-allow delivery of
2310 interrupts on the given <TT
2316 version differs from
2319 >cyg_drv_interrupt_unmask()</TT
2331 NAME="AEN12128">cyg_drv_interrupt_acknowledge</H2
2335 CLASS="VARIABLELIST"
2347 CLASS="PROGRAMLISTING"
2348 >void cyg_drv_interrupt_acknowledge( cyg_vector_t vector )</PRE
2362 > - vector to acknowledge</P
2380 >Perform any processing required at the interrupt
2381 controller and in the CPU to cancel the current interrupt
2388 need to program the hardware of the device to prevent an
2389 immediate re-triggering of the interrupt. </P
2399 NAME="AEN12153">cyg_drv_interrupt_configure</H2
2403 CLASS="VARIABLELIST"
2415 CLASS="PROGRAMLISTING"
2416 >void cyg_drv_interrupt_configure( cyg_vector_t vector,
2433 > - vector to configure</P
2440 > - level or edge triggered</P
2447 > - rising/falling edge, high/low level</P
2465 >Program the interrupt controller with the characteristics
2466 of the interrupt source. The <TT
2472 argument chooses between level- or edge-triggered
2479 between high and low level for level triggered interrupts or
2480 rising and falling edges for edge triggered interrupts. This
2481 function only works with interrupt controllers that can control
2482 these parameters. </P
2492 NAME="AEN12183">cyg_drv_interrupt_level</H2
2496 CLASS="VARIABLELIST"
2508 CLASS="PROGRAMLISTING"
2509 >void cyg_drv_interrupt_level( cyg_vector_t vector,
2510 cyg_priority_t level
2525 > - vector to configure</P
2550 >Program the interrupt controller to deliver the given
2551 interrupt at the supplied priority level. This function only
2552 works with interrupt controllers that can control this
2563 NAME="AEN12209">cyg_drv_interrupt_set_cpu</H2
2567 CLASS="VARIABLELIST"
2579 CLASS="PROGRAMLISTING"
2580 >void cyg_drv_interrupt_set_cpu( cyg_vector_t vector,
2596 > - interrupt vector to route</P
2603 > - destination CPU</P
2621 > This function causes all interrupts on the given vector to be
2622 routed to the specified CPU. Subsequently, all such interrupts
2623 will be handled by that CPU. This only works if the underlying
2624 hardware is capable of performing this kind of routing. This
2625 function does nothing on a single CPU system.
2636 NAME="AEN12235">cyg_drv_interrupt_get_cpu</H2
2640 CLASS="VARIABLELIST"
2652 CLASS="PROGRAMLISTING"
2653 >cyg_cpu_t cyg_drv_interrupt_set_cpu( cyg_vector_t vector )</PRE
2667 > - interrupt vector to query</P
2673 >The CPU to which this vector is routed</P
2685 > In multi-processor systems this function returns the id of the
2686 CPU to which interrupts on the given vector are current being
2687 delivered. In single CPU systems this function returns zero.
2698 NAME="AEN12259">cyg_ISR_t</H2
2702 CLASS="VARIABLELIST"
2714 CLASS="PROGRAMLISTING"
2715 >typedef cyg_uint32 cyg_ISR_t( cyg_vector_t vector,
2731 > - vector being delivered</P
2738 > - data value supplied by client</P
2744 >Bit mask indicating whether interrupt was handled and
2745 whether the DSR should be called. </P
2751 >Interrupt Service Routine definition. A pointer to a
2752 function with this prototype is passed to
2755 >cyg_interrupt_create()</TT
2757 object is created. When an interrupt is delivered the function
2758 will be called with the vector number and the data value that
2761 >cyg_interrupt_create()</TT
2765 >The return value is a bit mask containing one or both of the
2770 CLASS="VARIABLELIST"
2773 >CYG_ISR_HANDLED</DT
2776 >indicates that the interrupt was handled by this
2777 ISR. It is a configuration option whether this will
2778 prevent further ISR being run. </P
2781 >CYG_ISR_CALL_DSR</DT
2784 >causes the DSR that was passed to
2787 >cyg_interrupt_create()</TT
2789 scheduled to be called.</P
2802 NAME="AEN12294">cyg_DSR_t</H2
2806 CLASS="VARIABLELIST"
2818 CLASS="PROGRAMLISTING"
2819 >typedef void cyg_DSR_t( cyg_vector_t vector,
2836 > - vector being delivered</P
2843 > - number of times DSR has been scheduled</P
2850 > - data value supplied by client</P
2862 >Deferred Service Routine prototype. A pointer to a
2863 function with this prototype is passed to
2866 >cyg_interrupt_create()</TT
2868 object is created. When the ISR requests the scheduling of its
2869 DSR, this function will be called at some later point. In
2881 > arguments, which will be the same as
2882 those passed to the ISR, this routine is also passed a
2888 > of the number of times the ISR has
2889 requested that this DSR be scheduled. This counter is zeroed
2890 each time the DSR actually runs, so it indicates how many
2891 interrupts have occurred since it last ran.</P
2902 SUMMARY="Footer navigation table"
2913 HREF="devapi-synchronization-levels.html"
2922 HREF="ecos-ref.html"
2941 >Synchronization Levels</TD
2947 HREF="devapi-device-driver-interface-to-the-kernel.html"
2955 >File System Support Infrastructure</TD