projects / apple / xnu.git / blame
| Commit | Line | Data |
|---|---|---|
| 13fec989 A |
1 | <h2>evc_wait</h2> |
| 2 | <hr> | |
| 3 | <p> | |
| 4 | <strong>System Trap</strong> - Wait for a kernel (device) signalled event. | |
| 5 | <h3>SYNOPSIS</h3> | |
| 6 | <pre> | |
| 7 | <strong>kern_return_t evc_wait</strong> | |
| 8 | <strong>(unsigned int</strong> <var>event</var><strong>);</strong> | |
| 9 | </pre> | |
| 10 | <h3>PARAMETERS</h3> | |
| 11 | <dl> | |
| 12 | <dt> <var>event</var> | |
| 13 | <dd> | |
| 14 | [in scalar] The task local event ID of the kernel event object. | |
| 15 | </dl> | |
| 16 | <h3>DESCRIPTION</h3> | |
| 17 | <p> | |
| 18 | The <strong>evc_wait</strong> function causes the invoking thread to wait until the | |
| 19 | specified kernel (device) generated <var>event</var> occurs. Device drivers | |
| 20 | (typically mapped devices intended to be supported by user space | |
| 21 | drivers) may supply an <var>event</var> service. The <var>event</var> service defines one | |
| 22 | or more <var>event</var> objects, named by task local <var>event</var> IDs. Each of these | |
| 23 | <var>event</var> objects has an associated <var>event</var> count, initially zero. Whenever | |
| 24 | the associated <var>event</var> occurs (typically a device interrupt), the <var>event</var> | |
| 25 | count is incremented. If this count is zero when <strong>evc_wait</strong> is called, | |
| 26 | the calling thread waits for the next <var>event</var> to occur. Only one thread | |
| 27 | may be waiting for the <var>event</var> to occur. If the count is non-zero when | |
| 28 | <strong>evc_wait</strong> is called, the count is simply decremented without causing | |
| 29 | the thread to wait. The <var>event</var> count guarantees that no <var>event</var>s are | |
| 30 | lost. | |
| 31 | <h3>NOTES</h3> | |
| 32 | <p> | |
| 33 | The typical use of this service is within user space device | |
| 34 | drivers. When a device interrupt occurs, the (in this case, simple) | |
| 35 | kernel device driver would place device status in a shared (with the | |
| 36 | user device driver) memory window (established by <strong>device_map</strong>) and | |
| 37 | signal the associated <var>event</var>. The user space device driver would | |
| 38 | normally be waiting with <strong>evc_wait</strong>. The user thread then wakes, | |
| 39 | processes the device status, typically interacting with the device via | |
| 40 | its shared memory window, then waits for the next interrupt. | |
| 41 | <h3>RETURN VALUES</h3> | |
| 42 | <dl> | |
| 43 | <dt> <strong>KERN_NO_SPACE</strong> | |
| 44 | <dd> | |
| 45 | There is already a thread waiting for this event. | |
| 46 | </dl> | |
| 47 | <h3>RELATED INFORMATION</h3> | |
| 48 | <p> | |
| 49 | Functions: | |
| 50 | <a href="device_map.html"><strong>device_map</strong></a>. |