Changeset 7dc62af in mainline


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

Location:
kernel/generic/src/udebug
Files:
3 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)

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

    rd1c8287 r7dc62af  
    3434 * @file
    3535 * @brief       Udebug IPC message handling.
     36 *
     37 * This module handles udebug IPC messages and calls the appropriate
     38 * functions from the udebug_ops module which implement them.
    3639 */
    3740 

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

    rd1c8287 r7dc62af  
    3434 * @file
    3535 * @brief       Udebug operations.
     36 *
     37 * Udebug operations on tasks and threads are implemented here. The
     38 * functions defined here are called from the udebug_ipc module
     39 * when servicing udebug IPC messages.
    3640 */
    3741 
    … …  
    6670 * the t->lock spinlock to the t->udebug.lock mutex.
    6771 *
     72 * @param t             Pointer, need not at all be valid.
     73 * @param having_go     Required thread state.
     74 *
    6875 * Returns EOK if all went well, or an error code otherwise.
    6976 */
    … …  
    147154}
    148155
    149 
     156/** End debugging operation on a thread. */
    150157static void _thread_op_end(thread_t *t)
    151158{
    … …  
    153160}
    154161
    155 /**
    156  * \return 0 (ok, but not done yet), 1 (done) or negative error code.
     162/** Begin debugging the current task.
     163 *
     164 * Initiates a debugging session for the current task (and its threads).
     165 * When the debugging session has started a reply will be sent to the
     166 * UDEBUG_BEGIN call. This may happen immediately in this function if
     167 * all the threads in this task are stoppable at the moment and in this
     168 * case the function returns 1.
     169 *
     170 * Otherwise the function returns 0 and the reply will be sent as soon as
     171 * all the threads become stoppable (i.e. they can be considered stopped).
     172 *
     173 * @param call  The BEGIN call we are servicing.
     174 * @return      0 (OK, but not done yet), 1 (done) or negative error code.
    157175 */
    158176int udebug_begin(call_t *call)
    … …  
    206224}
    207225
     226/** Finish debugging the current task.
     227 *
     228 * Closes the debugging session for the current task.
     229 * @return Zero on success or negative error code.
     230 */
    208231int udebug_end(void)
    209232{
    … …  
    222245}
    223246
     247/** Set the event mask.
     248 *
     249 * Sets the event mask that determines which events are enabled.
     250 *
     251 * @param mask  Or combination of events that should be enabled.
     252 * @return      Zero on success or negative error code.
     253 */
    224254int udebug_set_evmask(udebug_evmask_t mask)
    225255{
    … …  
    242272}
    243273
    244 
     274/** Give thread GO.
     275 *
     276 * Upon recieving a go message, the thread is given GO. Having GO
     277 * means the thread is allowed to execute userspace code (until
     278 * a debugging event or STOP occurs, at which point the thread loses GO.
     279 *
     280 * @param t     The thread to operate on (unlocked and need not be valid).
     281 * @param call  The GO call that we are servicing.
     282 */
    245283int udebug_go(thread_t *t, call_t *call)
    246284{
    … …  
    267305}
    268306
     307/** Stop a thread (i.e. take its GO away)
     308 *
     309 * Generates a STOP event as soon as the thread becomes stoppable (i.e.
     310 * can be considered stopped).
     311 *
     312 * @param t     The thread to operate on (unlocked and need not be valid).
     313 * @param call  The GO call that we are servicing.
     314 */
    269315int udebug_stop(thread_t *t, call_t *call)
    270316{
    … …  
    316362}
    317363
     364/** Read the list of userspace threads in the current task.
     365 *
     366 * The list takes the form of a sequence of thread hashes (i.e. the pointers
     367 * to thread structures). A buffer of size @a buf_size is allocated and
     368 * a pointer to it written to @a buffer. The sequence of hashes is written
     369 * into this buffer.
     370 *
     371 * If the sequence is longer than @a buf_size bytes, only as much hashes
     372 * as can fit are copied. The number of thread hashes copied is stored
     373 * in @a n.
     374 *
     375 * The rationale for having @a buf_size is that this function is only
     376 * used for servicing the THREAD_READ message, which always specifies
     377 * a maximum size for the userspace buffer.
     378 *
     379 * @param buffer        The buffer for storing thread hashes.
     380 * @param buf_size      Buffer size in bytes.
     381 * @param n             The actual number of hashes copied will be stored here.
     382 */
    318383int udebug_thread_read(void **buffer, size_t buf_size, size_t *n)
    319384{
    … …  
    377442}
    378443
     444/** Read the arguments of a system call.
     445 *
     446 * The arguments of the system call being being executed are copied
     447 * to an allocated buffer and a pointer to it is written to @a buffer.
     448 * The size of the buffer is exactly such that it can hold the maximum number
     449 * of system-call arguments.
     450 *
     451 * Unless the thread is currently blocked in a SYSCALL_B or SYSCALL_E event,
     452 * this function will fail with an EINVAL error code.
     453 *
     454 * @param buffer        The buffer for storing thread hashes.
     455 */
    379456int udebug_args_read(thread_t *t, void **buffer)
    380457{
    … …  
    407484}
    408485
     486/** Read the memory of the debugged task.
     487 *
     488 * Reads @a n bytes from the address space of the debugged task, starting
     489 * from @a uspace_addr. The bytes are copied into an allocated buffer
     490 * and a pointer to it is written into @a buffer.
     491 *
     492 * @param uspace_addr   Address from where to start reading.
     493 * @param n             Number of bytes to read.
     494 * @param buffer        For storing a pointer to the allocated buffer.
     495 */
    409496int udebug_mem_read(unative_t uspace_addr, size_t n, void **buffer)
    410497{
Note: See TracChangeset for help on using the changeset viewer.