Changeset b1c21c2 in mainline


Ignore:
Timestamp:
2009-11-02T22:25:30Z (15 years ago)
Author:
Jakub Jermar <jakub@…>
Branches:
lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export
Children:
4f5dc18, 9131690, f60a0e4
Parents:
fd8bf6a
Message:

Improve comments in context.h.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • kernel/generic/include/context.h

    rfd8bf6a rb1c21c2  
    5151/** Save register context.
    5252 *
    53  * Save current register context (including stack pointers)
    54  * to context structure.
    55  *
    56  * Note that call to context_restore() will return at the same
     53 * Save the current register context (including stack pointer) to a context
     54 * structure. A subsequent call to context_restore() will return to the same
    5755 * address as the corresponding call to context_save().
    5856 *
    59  * This MUST be a macro, gcc -O0 does not inline functions even
    60  * if they are marked inline and context_save_arch must be called
    61  * from level <= that when context_restore is called.
     57 * Note that context_save_arch() must reuse the stack frame of the function
     58 * which called context_save(). We guarantee this by:
    6259 *
    63  * @param c Context structure.
     60 *   a) implementing context_save_arch() in assembly so that it does not create
     61 *      its own stack frame, and by
     62 *   b) defining context_save() as a macro because the inline keyword is just a
     63 *      hint for the compiler, not a real constraint; the application of a macro
     64 *      will definitely not create a stack frame either.
    6465 *
    65  * @return context_save() returns 1, context_restore() returns 0.
     66 * To imagine what could happen if there were some extra stack frames created
     67 * either by context_save() or context_save_arch(), we need to realize that the
     68 * sp saved in the contex_t structure points to the current stack frame as it
     69 * existed when context_save_arch() was executing. After the return from
     70 * context_save_arch() and context_save(), any extra stack frames created by
     71 * these functions will be destroyed and their contents sooner or later
     72 * overwritten by functions called next. Any attempt to restore to a context
     73 * saved like that would therefore lead to a disaster.
     74 *
     75 * @param c             Context structure.
     76 *
     77 * @return              context_save() returns 1, context_restore() returns 0.
    6678 */
    6779#define context_save(c)   context_save_arch(c)
     
    6981/** Restore register context.
    7082 *
    71  * Restore previously saved register context (including stack pointers)
    72  * from context structure.
     83 * Restore a previously saved register context (including stack pointer) from
     84 * a context structure.
    7385 *
    74  * Note that this function does not normally return.
    75  * Instead, it returns at the same address as the
    76  * corresponding call to context_save(), the only
    77  * difference being return value.
     86 * Note that this function does not normally return.  Instead, it returns to the
     87 * same address as the corresponding call to context_save(), the only difference
     88 * being return value.
    7889 *
    79  * @param c Context structure.
     90 * @param c             Context structure.
    8091 */
    8192static inline void context_restore(context_t *c)
Note: See TracChangeset for help on using the changeset viewer.