mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2025-01-18 12:52:44 +01:00
core: improved doxygen documentation
improved files complient to issue #950 - thread.h - flags.h - debug.h - crash.h
This commit is contained in:
Hauke Petersen
parent
b06eaeeefd
commit
7df411e7b7
@ -14,7 +14,7 @@
|
||||
* @brief Crash handling header
|
||||
*
|
||||
* Define a core_panic() function that allows to stop/reboot the system
|
||||
* when an unrecoverable problem has occured.
|
||||
* when an unrecoverable problem has occurred.
|
||||
*
|
||||
* @author Kévin Roussel <Kevin.Roussel@inria.fr>
|
||||
*/
|
||||
@ -24,18 +24,27 @@
|
||||
|
||||
#include "kernel.h"
|
||||
|
||||
/** Handle an unrecoverable error by halting or rebooting the system.
|
||||
A numeric code indicating the failure reason can be given
|
||||
as the ::crash_code parameter.
|
||||
Detailing the failure is possible using the ::message parameter.
|
||||
This function should serve a similar purpose as the panic()
|
||||
function of Unix/Linux kernels.
|
||||
|
||||
If the DEVELHELP macro is defined, the system will be halted;
|
||||
the system will be rebooted otherwise.
|
||||
|
||||
WARNING: this function NEVER returns! */
|
||||
/**
|
||||
* @brief Handle an unrecoverable error by halting or rebooting the system
|
||||
*
|
||||
* A numeric code indicating the failure reason can be given
|
||||
* as the *crash_code* parameter.
|
||||
*
|
||||
* Detailing the failure is possible using the *message* parameter.
|
||||
* This function should serve a similar purpose as the panic()
|
||||
* function of Unix/Linux kernels.
|
||||
*
|
||||
* If the DEVELHELP macro is defined, the system will be halted;
|
||||
* the system will be rebooted otherwise.
|
||||
*
|
||||
* @warning this function NEVER returns!
|
||||
*
|
||||
* @param[in] crash_code a unique code for identifying the crash reason
|
||||
* @param[in] message a human readable reason for the crash
|
||||
*
|
||||
* @return this function never returns
|
||||
* */
|
||||
NORETURN void core_panic(int crash_code, const char *message);
|
||||
|
||||
/** @} */
|
||||
#endif /* __CRASH_H */
|
||||
/** @} */
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
/*
|
||||
* Copyright (C) 2013 Freie Universität Berlin
|
||||
* Copyright (C) 2014 Freie Universität Berlin
|
||||
*
|
||||
* This file is subject to the terms and conditions of the GNU Lesser General
|
||||
* Public License. See the file LICENSE in the top level directory for more
|
||||
@ -25,6 +25,16 @@
|
||||
#include <stdio.h>
|
||||
#include "sched.h"
|
||||
|
||||
/**
|
||||
* @name Print debug information if the calling thread stack is large enough
|
||||
*
|
||||
* Use this macro the same as printf. When DEVHELP is defined inside an
|
||||
* implementation file, all usages of *DEBUG_PRINTF* will print the given
|
||||
* information to std-out. If DEVHELP is not set, all occurrences of
|
||||
* *DEBUG_PRINTF* will be ignored.
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
#if DEVELHELP
|
||||
#include "cpu-conf.h"
|
||||
#define DEBUG_PRINT(...) \
|
||||
@ -39,7 +49,21 @@
|
||||
#else
|
||||
#define DEBUG_PRINT(...) printf(__VA_ARGS__)
|
||||
#endif
|
||||
/** @} */
|
||||
|
||||
/**
|
||||
* @brief Print debug information to std-out
|
||||
*
|
||||
* If *ENABLE_DEBUG* is defined inside an implementation file, all calls to
|
||||
* *DEBUG* and *DEBUGF* will work the same as *printf* and output the given
|
||||
* information to stdout. If *ENABLE_DEBUG* is not defined, all calls to
|
||||
* *DEBUG* and *DEBUGF* will be ignored.
|
||||
*
|
||||
* In addition to just printing the given information *DEBUGF* will further
|
||||
* print extended debug information about the current thread and function.
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
#if ENABLE_DEBUG
|
||||
#include "tcb.h"
|
||||
#define DEBUG(...) DEBUG_PRINT(__VA_ARGS__)
|
||||
@ -55,6 +79,7 @@
|
||||
#define DEBUG(...)
|
||||
#define DEBUGF(...)
|
||||
#endif
|
||||
|
||||
/** @} */
|
||||
|
||||
#endif /* __DEBUG_H */
|
||||
/** @} */
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
/*
|
||||
* Copyright (C) 2013 Freie Universität Berlin
|
||||
* Copyright (C) 2014 Freie Universität Berlin
|
||||
*
|
||||
* This file is subject to the terms and conditions of the GNU Lesser General
|
||||
* Public License. See the file LICENSE in the top level directory for more
|
||||
@ -19,10 +19,16 @@
|
||||
#ifndef _FLAGS_H
|
||||
#define _FLAGS_H
|
||||
|
||||
#define CREATE_SLEEPING (1)
|
||||
#define AUTO_FREE (2)
|
||||
#define CREATE_WOUT_YIELD (4)
|
||||
#define CREATE_STACKTEST (8)
|
||||
|
||||
/**
|
||||
* @name Optional flags for controlling a threads initial state.
|
||||
* @{
|
||||
*/
|
||||
#define CREATE_SLEEPING (1) /**< set the new thread to sleeping */
|
||||
#define AUTO_FREE (2) /**< currently not implemented */
|
||||
#define CREATE_WOUT_YIELD (4) /**< do not automatically call thread_yield() after creation */
|
||||
#define CREATE_STACKTEST (8) /**< write markers into the thread's stack to measure stack
|
||||
usage (for debugging) */
|
||||
/** @} */
|
||||
|
||||
#endif /* _FLAGS_H */
|
||||
/** @} */
|
||||
#endif // _FLAGS_H
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
/*
|
||||
* Copyright (C) 2013 Freie Universität Berlin
|
||||
* Copyright (C) 2014 Freie Universität Berlin
|
||||
*
|
||||
* This file subject to the terms and conditions of the GNU Lesser General
|
||||
* Public License. See the file LICENSE in the top level directory for more
|
||||
@ -29,77 +29,122 @@
|
||||
|
||||
#define STATUS_NOT_FOUND (-1)
|
||||
|
||||
/** Minimum stack size */
|
||||
/**
|
||||
* @name Minimum stack size
|
||||
*/
|
||||
#ifndef MINIMUM_STACK_SIZE
|
||||
#define MINIMUM_STACK_SIZE (sizeof(tcb_t))
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @brief Creates a new thread.
|
||||
* @brief Creates a new thread
|
||||
*
|
||||
* @param stack Lowest address of preallocated stack space
|
||||
* @param stacksize
|
||||
* @param flags Options:
|
||||
* YIELD: force context switch.
|
||||
* CREATE_SLEEPING: set new thread to sleeping state, thread must be woken up manually.
|
||||
* CREATE_STACKTEST: initialize stack with values needed for stack overflow testing.
|
||||
* Creating a new thread is done in two steps:
|
||||
* 1. the new thread's stack is initialized depending on the platform
|
||||
* 2. the new thread is added to the scheduler to be run
|
||||
*
|
||||
* @param priority Priority of newly created thread. Lower number means higher
|
||||
* priority. 0 means highest possible priority. Lowest priority is
|
||||
* PRIORITY_IDLE-1, usually 30.
|
||||
* As RIOT is using a fixed priority scheduling algorithm, threads
|
||||
* are scheduled base on their priority. The priority is fixed for every thread
|
||||
* and specified during the threads creation by the *priority* parameter.
|
||||
*
|
||||
* @return returns <0 on error, pid of newly created task else.
|
||||
* A low value for *priority* number means the thread having a high priority
|
||||
* with 0 being the highest possible priority.
|
||||
*
|
||||
* The lowest possible priority is *PRIORITY_IDLE - 1*. The value is depending
|
||||
* on the platforms architecture, e.g. 30 in 32-bit systems, 14 in 16-bit systems.
|
||||
*
|
||||
*
|
||||
* In addition to the priority, the *flags* argument can be used to alter the
|
||||
* newly created threads behavior after creation. The following flags are available:
|
||||
* - CREATE_SLEEPING the newly created thread will be put to sleeping state and
|
||||
* must be waken up manually
|
||||
* - CREATE_WOUT_YIELD the newly created thread will not run immediately after creation
|
||||
* - CREATE_STACKTEST write markers into the thread's stack to measure the stack's memory
|
||||
* usage (for debugging and profiling purposes)
|
||||
*
|
||||
* @param[out] stack start address of the preallocated stack memory
|
||||
* @param[in] stacksize the size of the thread's stack in bytes
|
||||
* @param[in] priority priority of the new thread, lower mean higher priority
|
||||
* @param[in] flags optional flags for the creation of the new thread
|
||||
* @param[in] function pointer to the code that is executed in the new thread
|
||||
* @param[in] name a human readable descriptor for the thread
|
||||
*
|
||||
* @return value ``<0`` on error
|
||||
* @return pid of newly created task, otherwise
|
||||
*/
|
||||
int thread_create(char *stack, int stacksize, char priority, int flags, void (*function) (void), const char *name);
|
||||
int thread_create(char *stack,
|
||||
int stacksize,
|
||||
char priority,
|
||||
int flags,
|
||||
void (*function) (void),
|
||||
const char *name);
|
||||
|
||||
/**
|
||||
* @brief returns the status of a process.
|
||||
* @return STATUS_NOT_FOUND if pid is unknown
|
||||
* @brief Returns the status of a process
|
||||
*
|
||||
* @param[in] pid the PID of the thread to get the status from
|
||||
*
|
||||
* @return status of the thread
|
||||
* @return `STATUS_NOT_FOUND` if pid is unknown
|
||||
*/
|
||||
int thread_getstatus(int pid);
|
||||
|
||||
/**
|
||||
* @brief returns the name of a process.
|
||||
* @return NULL if pid is unknown
|
||||
* @brief Returns the name of a process
|
||||
*
|
||||
* @param[in] pid the PID of the thread to get the name from
|
||||
*
|
||||
* @return the threads name
|
||||
* @return `NULL` if pid is unknown
|
||||
*/
|
||||
const char *thread_getname(int pid);
|
||||
|
||||
/**
|
||||
* @brief Puts the current thread into sleep mode. Has to be woken up externally.
|
||||
* @brief Puts the current thread into sleep mode. Has to be woken up externally.
|
||||
*/
|
||||
void thread_sleep(void);
|
||||
|
||||
/**
|
||||
* @brief The current thread yields and let the scheduler run.
|
||||
* @brief The current thread yields and let the scheduler run
|
||||
*
|
||||
* The current thread will resume operation immediately if there is no other thread with the same
|
||||
* or a higher priority.
|
||||
*/
|
||||
void thread_yield(void);
|
||||
|
||||
/**
|
||||
* @brief Wakes up a sleeping thread.
|
||||
* @param pid The PID of the thread to be woken up
|
||||
* @return STATUS_NOT_FOUND if pid is unknown or not sleeping
|
||||
* @brief Wakes up a sleeping thread.
|
||||
*
|
||||
* @param[in] pid the PID of the thread to be woken up
|
||||
*
|
||||
* @return `1` on success
|
||||
* @return `STATUS_NOT_FOUND` if pid is unknown or not sleeping
|
||||
*/
|
||||
int thread_wakeup(int pid);
|
||||
|
||||
|
||||
/**
|
||||
* @brief Returns the process ID of the currently running thread.
|
||||
* @return Obviously you are not a golfer.
|
||||
* @brief Returns the process ID of the currently running thread
|
||||
*
|
||||
* @return obviously you are not a golfer.
|
||||
*/
|
||||
int thread_getpid(void);
|
||||
|
||||
/**
|
||||
* @brief Returns the process ID of the thread running before the current one.
|
||||
* @return Obviously you are not a golfer.
|
||||
* @brief Returns the process ID of the thread running before the current one
|
||||
*
|
||||
* @return obviously you are not a golfer.
|
||||
*/
|
||||
int thread_getlastpid(void);
|
||||
|
||||
/**
|
||||
* @brief Measures the stack usage of a stack.
|
||||
* @brief Measures the stack usage of a stack
|
||||
*
|
||||
* Only works if the thread was created with the flag CREATE_STACKTEST.
|
||||
*
|
||||
* @param stack The stack you want to measure. try active_thread->stack_start.
|
||||
* @return The amount of unused space of the thread's stack
|
||||
* @param[in] stack the stack you want to measure. try `active_thread->stack_start`
|
||||
*
|
||||
* @return the amount of unused space of the thread's stack
|
||||
*/
|
||||
int thread_measure_stack_free(char *stack);
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user