Changeset a5d0143 in mainline for kernel/generic/src/ipc/irq.c


Ignore:
Timestamp:
2017-09-03T19:45:52Z (7 years ago)
Author:
Jakub Jermar <jakub@…>
Branches:
lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export
Children:
30c27e9
Parents:
3422fb6
Message:

Improve comments

File:
1 edited

Legend:

Unmodified
Added
Removed

  • kernel/generic/src/ipc/irq.c

    r3422fb6 ra5d0143  
    3737 *
    3838 * This framework allows applications to subscribe to receive a notification
    39  * when interrupt is detected. The application may provide a simple 'top-half'
    40  * handler as part of its registration, which can perform simple operations
    41  * (read/write port/memory, add information to notification IPC message).
     39 * when an interrupt is detected. The application may provide a simple
     40 * 'top-half' handler as part of its registration, which can perform simple
     41 * operations (read/write port/memory, add information to notification IPC
     42 * message).
    4243 *
    4344 * The structure of a notification message is as follows:
    … …  
    5051 * - in_phone_hash: interrupt counter (may be needed to assure correct order
    5152 *                  in multithreaded drivers)
    52  *
    53  * Note on synchronization for ipc_irq_subscribe(), ipc_irq_unsubscribe(),
    54  * ipc_irq_cleanup() and IRQ handlers:
    55  *
    56  *   By always taking all of the uspace IRQ hash table lock, IRQ structure lock
    57  *   and answerbox lock, we can rule out race conditions between the
    58  *   registration functions and also the cleanup function. Thus the observer can
    59  *   either see the IRQ structure present in both the hash table and the
    60  *   answerbox list or absent in both. Views in which the IRQ structure would be
    61  *   linked in the hash table but not in the answerbox list, or vice versa, are
    62  *   not possible.
    63  *
    64  *   By always taking the hash table lock and the IRQ structure lock, we can
    65  *   rule out a scenario in which we would free up an IRQ structure, which is
    66  *   still referenced by, for example, an IRQ handler. The locking scheme forces
    67  *   us to lock the IRQ structure only after any progressing IRQs on that
    68  *   structure are finished. Because we hold the hash table lock, we prevent new
    69  *   IRQs from taking new references to the IRQ structure.
    70  *
    7153 */
    7254
    … …  
    119101        }
    120102       
    121         /* Rewrite the pseudocode addresses from physical to kernel virtual. */
     103        /* Rewrite the IRQ code addresses from physical to kernel virtual. */
    122104        for (size_t i = 0; i < cmdcount; i++) {
    123105                uintptr_t addr;
    … …  
    177159}
    178160
    179 /** Statically check the top-half pseudocode
    180  *
    181  * Check the top-half pseudocode for invalid or unsafe
    182  * constructs.
     161/** Statically check the top-half IRQ code
     162 *
     163 * Check the top-half IRQ code for invalid or unsafe constructs.
    183164 *
    184165 */
    … …  
    217198}
    218199
    219 /** Free the top-half pseudocode.
    220  *
    221  * @param code Pointer to the top-half pseudocode.
     200/** Free the top-half IRQ code.
     201 *
     202 * @param code Pointer to the top-half IRQ code.
    222203 *
    223204 */
    … …  
    232213}
    233214
    234 /** Copy the top-half pseudocode from userspace into the kernel.
    235  *
    236  * @param ucode Userspace address of the top-half pseudocode.
    237  *
    238  * @return Kernel address of the copied pseudocode.
     215/** Copy the top-half IRQ code from userspace into the kernel.
     216 *
     217 * @param ucode Userspace address of the top-half IRQ code.
     218 *
     219 * @return Kernel address of the copied IRQ code.
    239220 *
    240221 */
    … …  
    294275 * @param box     Receiving answerbox.
    295276 * @param inr     IRQ number.
    296  * @param imethod Interface and method to be associated with the
    297  *                notification.
    298  * @param ucode   Uspace pointer to top-half pseudocode.
     277 * @param imethod Interface and method to be associated with the notification.
     278 * @param ucode   Uspace pointer to top-half IRQ code.
    299279 *
    300280 * @return  IRQ capability handle.
    … …  
    342322       
    343323        /*
    344          * Enlist the IRQ structure in the uspace IRQ hash table and the
    345          * answerbox's list and make the IRQ capability valid.
     324         * Insert the IRQ structure into the uspace IRQ hash table and retype
     325         * the capability. By retyping the capability inside the critical
     326         * section, we make sure another thread cannot attempt to unregister the
     327         * IRQ before it is inserted into the hash table.
    346328         */
    347329        irq_spinlock_lock(&irq_uspace_hash_table_lock, true);
    … …  
    373355                return ENOENT;
    374356        }
     357        /* Make sure only one thread can win the race to unsubscribe. */
    375358        cap->type = CAP_TYPE_ALLOCATED;
    376359        irq_spinlock_unlock(&TASK->lock, true);
    … …  
    389372        irq_spinlock_unlock(&irq_uspace_hash_table_lock, true);
    390373       
    391         /* Free up the pseudo code and associated structures. */
     374        /* Free up the IRQ code and associated structures. */
    392375        code_free(irq->notif_cfg.code);
    393376       
    … …  
    415398}
    416399
    417 /** Apply the top-half pseudo code to find out whether to accept the IRQ or not.
     400/** Apply the top-half IRQ code to find out whether to accept the IRQ or not.
    418401 *
    419402 * @param irq IRQ structure.
    420403 *
    421  * @return IRQ_ACCEPT if the interrupt is accepted by the
    422  *         pseudocode, IRQ_DECLINE otherwise.
     404 * @return IRQ_ACCEPT if the interrupt is accepted by the IRQ code.
     405 * @return IRQ_DECLINE if the interrupt is not accepted byt the IRQ code.
    423406 *
    424407 */
Note: See TracChangeset for help on using the changeset viewer.