Changeset 7dc62af in mainline for kernel/generic/src/udebug/udebug.c


Ignore:
Timestamp:
2008-09-19T19:09:06Z (16 years ago)
Author:
Jiri Svoboda <jirik.svoboda@…>
Branches:
lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export
Children:
d93a1c5a
Parents:
d1c8287
Message:

Document functions in udebug.c and udebug_ops.c

File:
1 edited

Legend:

Unmodified
Added
Removed

  • kernel/generic/src/udebug/udebug.c

    rd1c8287 r7dc62af  
    3333/**
    3434 * @file
    35  * @brief       Udebug.
     35 * @brief       Udebug hooks and data structure management.
     36 *
     37 * Udebug is an interface that makes userspace debuggers possible.
    3638 *
    3739 * Functions in this file are executed directly in each thread, which
    … …  
    6466}
    6567
     68/** Initialize udebug part of task structure.
     69 *
     70 * Called as part of task structure initialization.
     71 * @param ut    Pointer to the structure to initialize.
     72 */
    6673void udebug_task_init(udebug_task_t *ut)
    6774{
    … …  
    7380}
    7481
     82/** Initialize udebug part of thread structure.
     83 *
     84 * Called as part of thread structure initialization.
     85 * @param ut    Pointer to the structure to initialize.
     86 */
    7587void udebug_thread_initialize(udebug_thread_t *ut)
    7688{
    … …  
    90102}
    91103
     104/** Wait for a GO message.
     105 *
     106 * When a debugging event occurs in a thread or the thread is stopped,
     107 * this function is called to block the thread until a GO message
     108 * is received.
     109 *
     110 * @param wq    The wait queue used by the thread to wait for GO messages.
     111 */
    92112static void udebug_wait_for_go(waitq_t *wq)
    93113{
    … …  
    105125/** Do a preliminary check that a debugging session is in progress.
    106126 *
    107  * This only requires the THREAD->udebug.lock mutex (and not
    108  * TASK->udebug.lock mutex). For an undebugged task, this will
    109  * never block (while there could be collisions by different threads
    110  * on the TASK mutex), thus improving SMP perormance for undebugged tasks.
     127 * This only requires the THREAD->udebug.lock mutex (and not TASK->udebug.lock
     128 * mutex). For an undebugged task, this will never block (while there could be
     129 * collisions by different threads on the TASK mutex), thus improving SMP
     130 * perormance for undebugged tasks.
     131 *
     132 * @return      True if the thread was in a debugging session when the function
     133 *              checked, false otherwise.
    111134 */
    112135static bool udebug_thread_precheck(void)
    … …  
    121144}
    122145
     146/** Start of stoppable section.
     147 *
     148 * A stoppable section is a section of code where if the thread can be stoped. In other words,
     149 * if a STOP operation is issued, the thread is guaranteed not to execute
     150 * any userspace instructions until the thread is resumed.
     151 *
     152 * Having stoppable sections is better than having stopping points, since
     153 * a thread can be stopped even when it is blocked indefinitely in a system
     154 * call (whereas it would not reach any stopping point).
     155 */
    123156void udebug_stoppable_begin(void)
    124157{
    … …  
    189222}
    190223
     224/** End of a stoppable section.
     225 *
     226 * This is the point where the thread will block if it is stopped.
     227 * (As, by definition, a stopped thread must not leave its stoppable section).
     228 */
    191229void udebug_stoppable_end(void)
    192230{
    … …  
    259297}
    260298
     299/** Syscall event hook.
     300 *
     301 * Must be called before and after servicing a system call. This generates
     302 * a SYSCALL_B or SYSCALL_E event, depending on the value of @a end_variant.
     303 */
    261304void udebug_syscall_event(unative_t a1, unative_t a2, unative_t a3,
    262305    unative_t a4, unative_t a5, unative_t a6, unative_t id, unative_t rc,
    … …  
    323366}
    324367
     368/** Thread-creation event hook.
     369 *
     370 * Must be called when a new userspace thread is created in the debugged
     371 * task. Generates a THREAD_B event.
     372 *
     373 * @param t     Structure of the thread being created. Not locked, as the
     374 *              thread is not executing yet.
     375 */
    325376void udebug_thread_b_event(struct thread *t)
    326377{
    … …  
    372423}
    373424
     425/** Thread-termination event hook.
     426 *
     427 * Must be called when the current thread is terminating.
     428 * Generates a THREAD_E event.
     429 */
    374430void udebug_thread_e_event(void)
    375431{
    … …  
    418474 * Terminate task debugging session.
    419475 *
    420  * \param ta->udebug.lock must be already locked.
    421  * \return Zero on success or negative error code.
     476 * Gracefully terminates the debugging session for a task. If the debugger
     477 * is still waiting for events on some threads, it will receive a
     478 * FINISHED event for each of them.
     479 *
     480 * @param ta    Task structure. ta->udebug.lock must be already locked.
     481 * @return      Zero on success or negative error code.
    422482 */
    423483int udebug_task_cleanup(struct task *ta)
Note: See TracChangeset for help on using the changeset viewer.