michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doxygen: Cleanup arch.h comments

Browse source 
Change-Id: I0c5743ab2db3cb1bc584ced4fa9d91c84da971b8
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
Anas Nashif 2015-07-15 17:10:25 -04:00
commit 629dfc26c9
1 changed files with 82 additions and 51 deletions
Download patch file Download diff file Expand all files Collapse all files

115
include/arch/x86/arch.h
View file

@ -1,5 +1,3 @@
/* arch.h - IA-32 specific nanokernel interface header */
/*
* Copyright (c) 2010-2014 Wind River Systems, Inc.
*
@ -31,9 +29,10 @@
*/
/*
DESCRIPTION
This header contains the IA-32 specific nanokernel interface. It is included
by the generic nanokernel interface header (nanokernel.h)
* @file
* @brief IA-32 specific nanokernel interface header
* This header contains the IA-32 specific nanokernel interface. It is included
* by the generic nanokernel interface header (nanokernel.h)
*/
#ifndef _ARCH_IFACE_H
@ -48,7 +47,7 @@ by the generic nanokernel interface header (nanokernel.h)
#define OCTET_TO_SIZEOFUNIT(X) (X)
#define SIZEOFUNIT_TO_OCTET(X) (X)
/*
/**
* Macro used internally by NANO_CPU_INT_REGISTER and NANO_CPU_INT_REGISTER_ASM.
* Not meant to be used explicitly by BSP, driver or application code.
*/
@ -59,7 +58,7 @@ by the generic nanokernel interface header (nanokernel.h)
/* interrupt/exception/error related definitions */
#define _INT_STUB_SIZE 0x2b
/*
/**
* Performance optimization
*
* Macro PERF_OPT is defined if project is compiled with option other than
@ -74,7 +73,7 @@ by the generic nanokernel interface header (nanokernel.h)
#define _INT_STUB_ALIGN 1
#endif
/*
/**
* Floating point register set alignment.
*
* If support for SSEx extensions is enabled a 16 byte boundary is required,
@ -100,13 +99,15 @@ by the generic nanokernel interface header (nanokernel.h)
typedef unsigned char __aligned(_INT_STUB_ALIGN) NANO_INT_STUB[_INT_STUB_SIZE];
typedef struct s_isrList {
void *fnc; /* Address of ISR/stub */
unsigned int vec; /* Vector number associated with ISR/stub */
unsigned int dpl; /* Privilege level associated with ISR/stub */
/** Address of ISR/stub */
void *fnc;
/** Vector number associated with ISR/stub */
unsigned int vec;
/** Privilege level associated with ISR/stub */
unsigned int dpl;
} ISR_LIST;
/**
*
* @brief Connect a routine to an interrupt vector
*
* This macro "connects" the specified routine, <r>, to the specified interrupt
@ -121,6 +122,9 @@ typedef struct s_isrList {
* The <d> argument specifies the privilege level for the interrupt-gate
* descriptor; (hardware) interrupts and exceptions should specify a level of 0,
* whereas handlers for user-mode software generated interrupts should specify 3.
* @param r Routine to be connected
* @param v Interrupt Vector
* @param d Descriptor Privilege Level
*
* @return N/A
*
@ -130,22 +134,30 @@ typedef struct s_isrList {
ISR_LIST __attribute__((section(".intList"))) MK_ISR_NAME(r) = {&r, v, d}
/*
* @brief Declare a dynamic interrupt stub
*
* Macro to declare a dynamic interrupt stub. Using the macro places the stub
* in the .intStubSection which is located in the image according to the kernel
* configuration.
* @param s Stub to be declared
*/
#define NANO_CPU_INT_STUB_DECL(s) \
#define NANO_CPU_INT_STUB_DECL(s) \
_NODATA_SECTION(.intStubSect) NANO_INT_STUB(s)
/**
*
* @brief Connect a routine to interrupt number
*
* For the device <device> associates IRQ number <irq> with priority
* <priority> with the interrupt routine <isr>, that receives parameter
* <parameter>
*
* @param device Device
* @param iqr IRQ number
* @param priority IRQ Priority
* @param isr Interrupt Service Routine
* @param parameter ISR parameter
*
* @return N/A
*
*/
@ -161,6 +173,8 @@ typedef struct s_isrList {
*
* For the given device do the neccessary configuration steps.
* For x86 platform configure APIC and mark interrupt vector allocated
* @param device Device
* @param irq IRQ
*
* @return N/A
*
@ -172,7 +186,8 @@ typedef struct s_isrList {
} while(0)
/*
/**
* @brief Nanokernel Exception Stack Frame
* A pointer to an "exception stack frame" (ESF) is passed as an argument
* to exception handlers registered via nanoCpuExcConnect(). When an exception
* occurs while PL=0, then only the EIP, CS, and EFLAGS are pushed onto the stack.
@ -195,8 +210,8 @@ typedef struct s_isrList {
*/
typedef struct nanoEsf {
unsigned int cr2; /* putting cr2 here allows discarding it and pEsf in
* one instruction */
/** putting cr2 here allows discarding it and pEsf in one instruction */
unsigned int cr2;
#ifdef CONFIG_GDB_INFO
unsigned int ebp;
unsigned int ebx;
@ -215,6 +230,7 @@ typedef struct nanoEsf {
} NANO_ESF;
/*
* @brief Nanokernel "interrupt stack frame" (ISF)
* An "interrupt stack frame" (ISF) as constructed by the processor
* and the interrupt wrapper function _IntExit(). When an interrupt
* occurs while PL=0, only the EIP, CS, and EFLAGS are pushed onto the stack.
@ -250,12 +266,18 @@ typedef struct nanoIsf {
* and _SysFatalErrorHandler().
*/
#define _NANO_ERR_SPURIOUS_INT (0) /* Unhandled exception/interrupt */
#define _NANO_ERR_PAGE_FAULT (1) /* Page fault */
#define _NANO_ERR_GEN_PROT_FAULT (2) /* General protection fault */
#define _NANO_ERR_INVALID_TASK_EXIT (3) /* Invalid task exit */
#define _NANO_ERR_STACK_CHK_FAIL (4) /* Stack corruption detected */
#define _NANO_ERR_ALLOCATION_FAIL (5) /* Kernel Allocation Failure */
/** Unhandled exception/interrupt */
#define _NANO_ERR_SPURIOUS_INT (0)
/** Page fault */
#define _NANO_ERR_PAGE_FAULT (1)
/** General protection fault */
#define _NANO_ERR_GEN_PROT_FAULT (2)
/** Invalid task exit */
#define _NANO_ERR_INVALID_TASK_EXIT (3)
/** Stack corruption detected */
#define _NANO_ERR_STACK_CHK_FAIL (4)
/** Kernel Allocation Failure */
#define _NANO_ERR_ALLOCATION_FAIL (5)
#ifndef _ASMLANGUAGE
@ -275,7 +297,6 @@ void _int_latency_stop(void);
#endif
/**
*
* @brief Disable all interrupts on the CPU (inline)
*
* This routine disables interrupts. It can be called from either interrupt,
@ -347,23 +368,23 @@ static inline __attribute__((always_inline))
}
#endif /* CONFIG_NO_ISRS */
/* interrupt/exception/error related definitions */
/** interrupt/exception/error related definitions */
typedef void (*NANO_EOI_GET_FUNC) (void *);
/*
/**
* The NANO_SOFT_IRQ macro must be used as the value for the <irq> parameter
* to irq_connect() when connecting to a software generated interrupt.
*/
#define NANO_SOFT_IRQ ((unsigned int) (-1))
#ifdef CONFIG_FP_SHARING
/* Definitions for the 'options' parameter to the fiber_fiber_start() API */
#define USE_FP 0x10 /* context uses floating point unit */
/** context uses floating point unit */
#define USE_FP 0x10
#ifdef CONFIG_SSE
#define USE_SSE 0x20 /* context uses SSEx instructions */
/** context uses SSEx instructions */
#define USE_SSE 0x20
#endif /* CONFIG_SSE */
#endif /* CONFIG_FP_SHARING */
@ -381,28 +402,36 @@ extern int irq_connect(unsigned int irq,
void (*routine)(void *parameter),
void *parameter);
/*
* irq_enable() : enable a specific IRQ
* irq_disable() : disable a specific IRQ
* irq_lock() : lock out all interrupts
* irq_unlock() : unlock all interrupts
/**
* @brief Enable a specific IRQ
* @param irq IRQ
*/
extern void irq_enable(unsigned int irq);
/**
* @brief Disable a specific IRQ
* @param irq IRQ
*/
extern void irq_disable(unsigned int irq);
#ifndef CONFIG_NO_ISRS
/**
* @brief Lock out all interrupts
*/
extern int irq_lock(void);
/**
* @brief Unlock all interrupts
*/
extern void irq_unlock(int key);
#endif /* CONFIG_NO_ISRS */
#ifdef CONFIG_FP_SHARING
/*
/**
* @brief Enable floating point hardware resources sharing
* Dynamically enable/disable the capability of a context to share floating
* point hardware resources. The same "floating point" options accepted by
* fiber_fiber_start() are accepted by these APIs (i.e. USE_FP and USE_SSE).
*/
extern void fiber_float_enable(nano_context_id_t ctx, unsigned int options);
extern void task_float_enable(nano_context_id_t ctx, unsigned int options);
extern void fiber_float_disable(nano_context_id_t ctx);
@ -415,22 +444,24 @@ extern void task_float_disable(nano_context_id_t ctx);
extern void nano_cpu_idle(void);
#endif
/* Nanokernel provided routine to report any detected fatal error. */
/** Nanokernel provided routine to report any detected fatal error. */
extern FUNC_NORETURN void _NanoFatalErrorHandler(unsigned int reason,
const NANO_ESF *pEsf);
/* User provided routine to handle any detected fatal error post reporting. */
/** User provided routine to handle any detected fatal error post reporting. */
extern FUNC_NORETURN void _SysFatalErrorHandler(unsigned int reason,
const NANO_ESF *pEsf);
/* Dummy ESF for fatal errors that would otherwise not have an ESF */
/** Dummy ESF for fatal errors that would otherwise not have an ESF */
extern const NANO_ESF _default_esf;
/*
* @brief Configure an interrupt vector of the specified priority
*
* BSP provided routine which kernel invokes to configure an interrupt vector
* of the specified priority; the BSP allocates an interrupt vector, programs
* hardware to route interrupt requests on the specified irq to that vector,
* and returns the vector number along with its associated BOI/EOI information
*
*/
extern int _SysIntVecAlloc(unsigned int irq,
unsigned int priority,
NANO_EOI_GET_FUNC *boiRtn,