From c2b752881df62c870c395bb1f6c405bca33bec37 Mon Sep 17 00:00:00 2001 From: Daniel Ramirez Date: Mon, 23 Dec 2013 13:03:25 -0600 Subject: mips/shared: added new doxygen --- c/src/lib/libbsp/mips/shared/doxygen.h | 11 ++ c/src/lib/libbsp/mips/shared/gdbstub/gdb_if.h | 33 ++++- c/src/lib/libbsp/mips/shared/gdbstub/memlimits.h | 13 ++ c/src/lib/libbsp/mips/shared/gdbstub/mips_opcode.h | 75 ++++++++--- c/src/lib/libbsp/mips/shared/irq/i8259.h | 150 +++++++++++++++------ c/src/lib/libbsp/mips/shared/liblnk/regs.h | 122 ++++++++++++----- 6 files changed, 304 insertions(+), 100 deletions(-) create mode 100644 c/src/lib/libbsp/mips/shared/doxygen.h diff --git a/c/src/lib/libbsp/mips/shared/doxygen.h b/c/src/lib/libbsp/mips/shared/doxygen.h new file mode 100644 index 0000000000..755675fc4d --- /dev/null +++ b/c/src/lib/libbsp/mips/shared/doxygen.h @@ -0,0 +1,11 @@ + /** + * @defgroup bsp_mips MIPS + * @ingroup bsp_kit + * @brief MIPS Board Support Packages + */ + + /** + * @defgroup mips_shared MIPS Shared Modules + * @ingroup bsp_mips + * @brief mips Shared Modules + */ diff --git a/c/src/lib/libbsp/mips/shared/gdbstub/gdb_if.h b/c/src/lib/libbsp/mips/shared/gdbstub/gdb_if.h index db5e711678..ba4f0eb757 100644 --- a/c/src/lib/libbsp/mips/shared/gdbstub/gdb_if.h +++ b/c/src/lib/libbsp/mips/shared/gdbstub/gdb_if.h @@ -1,3 +1,9 @@ +/** + * @file + * @ingroup mips_gdb + * @brief Definition of the interface between stub and gdb + */ + /* * gdb_if.h - definition of the interface between the stub and gdb * @@ -12,10 +18,17 @@ * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. */ +/** + * @defgroup mips_gdb GDB Interface + * @ingroup mips_shared + * @brief GDB Interface + * @{ + */ + #ifndef _GDB_IF_H #define _GDB_IF_H -/* Max number of threads in qM response */ +/** @brief Max number of threads in qM response */ #define QM_MAX_THREADS (20) struct rtems_gdb_stub_thread_info { @@ -24,8 +37,9 @@ struct rtems_gdb_stub_thread_info { char more_display[256]; }; -/* - * Prototypes +/** + * @name Prototypes + * @{ */ int parse_zbreak(const char *in, int *type, unsigned char **addr, int *len); @@ -70,9 +84,14 @@ void rtems_gdb_process_query( int thread ); -/* - * MIPS registers, numbered in the order in which gdb expects to see them. +/** @} */ + +/** + * @name MIPS registers + * @brief Numbered in the order in which gdb expects to see them. + * @{ */ + #define ZERO 0 #define AT 1 #define V0 2 @@ -157,6 +176,8 @@ void rtems_gdb_process_query( #define NUM_REGS 72 +/** @} */ + void mips_gdb_stub_install(int enableThreads) ; #define MEMOPT_READABLE 1 @@ -168,4 +189,6 @@ void mips_gdb_stub_install(int enableThreads) ; int gdbstub_add_memsegment(unsigned,unsigned,int); +/** @} */ + #endif /* _GDB_IF_H */ diff --git a/c/src/lib/libbsp/mips/shared/gdbstub/memlimits.h b/c/src/lib/libbsp/mips/shared/gdbstub/memlimits.h index 4180b9d3c0..c60ca12111 100644 --- a/c/src/lib/libbsp/mips/shared/gdbstub/memlimits.h +++ b/c/src/lib/libbsp/mips/shared/gdbstub/memlimits.h @@ -1,3 +1,9 @@ +/** + * @file + * @ingroup mips_limits + * @brief Definition of machine and system dependent address limits. + */ + /* * limits.h - definition of machine & system dependent address limits * @@ -45,6 +51,13 @@ * to have different readability and/or writeability attributes. */ +/** + * @defgroup mips_limits Address Limits + * @ingroup mips_shared + * @brief Address Limits + */ + + /* #define K0_LIMIT_FOR_READ (K0BASE+0x18000000) #define K1_LIMIT_FOR_READ (K1BASE+K1SIZE) diff --git a/c/src/lib/libbsp/mips/shared/gdbstub/mips_opcode.h b/c/src/lib/libbsp/mips/shared/gdbstub/mips_opcode.h index 59c1a06798..883b1f174b 100644 --- a/c/src/lib/libbsp/mips/shared/gdbstub/mips_opcode.h +++ b/c/src/lib/libbsp/mips/shared/gdbstub/mips_opcode.h @@ -1,4 +1,10 @@ -/*- +/** + * @file + * @ingroup + * @brief Instruction formats and opcode values for MIPS + */ + +/* * Copyright (c) 1992 The Regents of the University of California. * All rights reserved. * @@ -45,9 +51,18 @@ #ifndef _MIPS_OPCODE_H #define _MIPS_OPCODE_H -/* - * Define the instruction formats. +/** + * @defgroup mips_ops MIPS Opcodes + * @ingroup mips_shared + * @brief MIPS Instruction Formats and Opcode Values + * @{ */ + +/** + * @name Instruction formats + * @{ + */ + typedef union { unsigned word; @@ -116,9 +131,13 @@ typedef union { #endif } InstFmt; -/* - * Values for the 'op' field. +/** @} */ + +/** + * @name 'op' field values + * @{ */ + #define OP_SPECIAL 000 #define OP_REGIMM 001 #define OP_J 002 @@ -184,9 +203,11 @@ typedef union { #define OP_SDC2 076 #define OP_SD 077 -/* - * Values for the 'func' field when 'op' == OP_SPECIAL. +/** + * @name 'func' field values when 'op' == OP_SPECIAL. + * @{ */ + #define OP_SLL 000 #define OP_SRL 002 #define OP_SRA 003 @@ -247,9 +268,13 @@ typedef union { #define OP_DSRL32 076 #define OP_DSRA32 077 -/* - * Values for the 'func' field when 'op' == OP_REGIMM. +/** @} */ + +/** + * 'func' field values when 'op' == OP_REGIMM. + * @{ */ + #define OP_BLTZ 000 #define OP_BGEZ 001 #define OP_BLTZL 002 @@ -267,9 +292,13 @@ typedef union { #define OP_BLTZALL 022 #define OP_BGEZALL 023 -/* - * Values for the 'rs' field when 'op' == OP_COPz. +/** @} */ + +/** + * @name 'rs' field values when 'op' == OP_COPz. + * @{ */ + #define OP_MF 000 #define OP_DMF 001 #define OP_CF 002 @@ -278,18 +307,30 @@ typedef union { #define OP_CT 006 #define OP_BC 010 -/* - * Values for the 'rt' field when 'op' == OP_COPz and 'rt' == OP_BC. +/** @} */ + +/** + * @name 'rt' field values when 'op' == OP_COPz and 'rt' == OP_BC. + * @{ */ + #define COPz_BCF 0x00 #define COPz_BCT 0x01 #define COPz_BCFL 0x02 #define COPz_BCTL 0x03 -/* - * Instructions with specal significance to debuggers. +/** @} */ + +/** + * @name Instructions with specal significance to debuggers. + * @{ */ -#define BREAK_INSTR 0x0000000d /* instruction code for break */ -#define NOP_INSTR 0x00000000 /* instruction code for no-op */ + +#define BREAK_INSTR 0x0000000d ///< @brief instruction code for break +#define NOP_INSTR 0x00000000 ///< @brief instruction code for no-op + +/** @} */ + +/** @} */ #endif /* _MIPS_OPCODE_H */ diff --git a/c/src/lib/libbsp/mips/shared/irq/i8259.h b/c/src/lib/libbsp/mips/shared/irq/i8259.h index db4d5fa87f..0cc2594b17 100644 --- a/c/src/lib/libbsp/mips/shared/irq/i8259.h +++ b/c/src/lib/libbsp/mips/shared/irq/i8259.h @@ -1,3 +1,9 @@ +/** + * @file + * @ingroup mips_i8259_irq + * @brief Data structure and functions used to control i8259 chip. + */ + /* irq.h * * This include file describe the data structure and the functions implemented @@ -19,9 +25,18 @@ #ifndef I8259_H #define I8259_H -/* - * 8259 edge/level control definitions at VIA +/** + * @defgroup mips_i8259_irq i8259 Chip Support + * @ingroup mips_shared + * @brief i8259 Chip Support + * @{ */ + +/** + * @name 8259 edge/level control definitions at VIA + * @{ + */ + #if 1 #define ISA8259_M_ELCR 0x4d0 #define ISA8259_S_ELCR 0x4d1 @@ -44,20 +59,30 @@ #define ELCRM_INT1_LVL 0x2 #define ELCRM_INT0_LVL 0x1 -/* - * PIC's command and mask registers +/** @} */ + +/** + * @name PIC's command and mask registers + * @{ */ -#define PIC_MASTER_COMMAND_IO_PORT 0x20 /* Master PIC command register */ -#define PIC_SLAVE_COMMAND_IO_PORT 0xa0 /* Slave PIC command register */ -#define PIC_MASTER_IMR_IO_PORT 0x21 /* Master PIC Interrupt Mask Register */ -#define PIC_SLAVE_IMR_IO_PORT 0xa1 /* Slave PIC Interrupt Mask Register */ -/* - * Command for specific EOI (End Of Interrupt): Interrupt acknowledge +#define PIC_MASTER_COMMAND_IO_PORT 0x20 ///< @brief Master PIC command register */ +#define PIC_SLAVE_COMMAND_IO_PORT 0xa0 ///< @brief Slave PIC command register */ +#define PIC_MASTER_IMR_IO_PORT 0x21 ///< @brief Master PIC Interrupt Mask Register */ +#define PIC_SLAVE_IMR_IO_PORT 0xa1 ///< @brief Slave PIC Interrupt Mask Register */ + +/** @} */ + +/** + * @name Command for specific EOI (End Of Interrupt): Interrupt acknowledge + * @{ */ -#define PIC_EOSI 0x60 /* End of Specific Interrupt (EOSI) */ -#define SLAVE_PIC_EOSI 0x62 /* End of Specific Interrupt (EOSI) for cascade */ -#define PIC_EOI 0x20 /* Generic End of Interrupt (EOI) */ + +#define PIC_EOSI 0x60 ///< @brief End of Specific Interrupt (EOSI) */ +#define SLAVE_PIC_EOSI 0x62 ///< @brief End of Specific Interrupt (EOSI) for cascade */ +#define PIC_EOI 0x20 ///< @brief Generic End of Interrupt (EOI) */ + +/** @} */ #ifndef ASM @@ -69,13 +94,18 @@ extern "C" { * rtems_irq_number Definitions */ #if 0 -/* - * ISA IRQ handler related definitions + +/** + * @name ISA IRQ handler related definitions + * @{ */ + #define BSP_ISA_IRQ_NUMBER (16) #define BSP_ISA_IRQ_LOWEST_OFFSET (0) #define BSP_ISA_IRQ_MAX_OFFSET (BSP_ISA_IRQ_LOWEST_OFFSET + BSP_ISA_IRQ_NUMBER - 1) +/** @} */ + #ifndef qemu #define BSP_PCI_IRQ_NUMBER (16) #else @@ -101,29 +131,44 @@ extern "C" { #define BSP_MISC_IRQ_LOWEST_OFFSET (BSP_PROCESSOR_IRQ_MAX_OFFSET + 1) #define BSP_MISC_IRQ_MAX_OFFSET (BSP_MISC_IRQ_LOWEST_OFFSET + BSP_MISC_IRQ_NUMBER - 1) -/* - * Summary + +/** + * @name Summary + * @{ */ + #define BSP_IRQ_NUMBER (BSP_MISC_IRQ_MAX_OFFSET + 1) #define BSP_LOWEST_OFFSET (BSP_ISA_IRQ_LOWEST_OFFSET) #define BSP_MAX_OFFSET (BSP_MISC_IRQ_MAX_OFFSET) -/* - * Some ISA IRQ symbolic name definition + +/** @} */ + +/** + * @name Some ISA IRQ symbolic name definition + * @{ */ + #define BSP_ISA_PERIODIC_TIMER (0) #define BSP_ISA_KEYBOARD (1) #define BSP_ISA_UART_COM2_IRQ (3) #define BSP_ISA_UART_COM1_IRQ (4) #define BSP_ISA_RT_TIMER1 (8) #define BSP_ISA_RT_TIMER3 (10) -/* - * Some PCI IRQ symbolic name definition + +/** @} */ + +/** + * @name Some PCI IRQ symbolic name definition + * @{ */ + #define BSP_PCI_IRQ0 (BSP_PCI_IRQ_LOWEST_OFFSET) #if BSP_PCI_IRQ_NUMBER > 0 #define BSP_PCI_ISA_BRIDGE_IRQ (BSP_PCI_IRQ0) #endif +/** @} */ + #if defined(mvme2100) #define BSP_DEC21143_IRQ (BSP_PCI_IRQ_LOWEST_OFFSET + 1) #define BSP_PMC_PCMIP_TYPE1_SLOT0_IRQ (BSP_PCI_IRQ_LOWEST_OFFSET + 2) @@ -142,51 +187,68 @@ extern "C" { #define BSP_UART_COM2_IRQ BSP_ISA_UART_COM2_IRQ #endif -/* - * Some Processor execption handled as RTEMS IRQ symbolic name definition +/** + * @brief Some Processor execption handled as RTEMS IRQ symbolic name definition */ #define BSP_DECREMENTER (BSP_PROCESSOR_IRQ_LOWEST_OFFSET) #endif -/* - * Type definition for RTEMS managed interrupts +/** + * @name Type definition for RTEMS managed interrupts + * @{ */ + typedef unsigned short rtems_i8259_masks; extern volatile rtems_i8259_masks i8259s_cache; +/** @} */ + /*-------------------------------------------------------------------------+ | Function Prototypes. +--------------------------------------------------------------------------*/ /* * ------------------------ Intel 8259 (or emulation) Mngt Routines ------- */ + +/** + * @name Function Prototypes + * @{ + */ + void BSP_i8259s_init(void); -/* - * function to disable a particular irq at 8259 level. After calling - * this function, even if the device asserts the interrupt line it will - * not be propagated further to the processor +/** + * @brief function to disable a particular irq at 8259 level. * - * RETURNS: 1/0 if the interrupt was enabled/disabled originally or - * a value < 0 on error. + * After calling this function, even if the device asserts the interrupt + * line it will not be propagated further to the processor. + * + * @retval 1 the interrupt was enabled originally + * @retval 0 the interrupt was disabled originally + * @retval <0 error */ int BSP_irq_disable_at_i8259s (const rtems_irq_number irqLine); -/* - * function to enable a particular irq at 8259 level. After calling - * this function, if the device asserts the interrupt line it will - * be propagated further to the processor + +/** + * @brief function to enable a particular irq at 8259 level. + * + * After calling this function, if the device asserts the interrupt line + * it will be propagated further to the processor. */ int BSP_irq_enable_at_i8259s (const rtems_irq_number irqLine); -/* - * function to acknowledge a particular irq at 8259 level. After calling - * this function, if a device asserts an enabled interrupt line it will - * be propagated further to the processor. Mainly usefull for people - * writing raw handlers as this is automagically done for RTEMS managed + +/** + * @brief function to acknowledge a particular irq at 8259 level. + * + * After calling this function, if a device asserts an enabled interrupt + * line it will be propagated further to the processor. Mainly useful for + * people writing raw handlers as this is automagically done for RTEMS managed * handlers. */ int BSP_irq_ack_at_i8259s (const rtems_irq_number irqLine); -/* - * function to check if a particular irq is enabled at 8259 level. After calling + +/** + * @brief function to check if a particular irq is enabled at 8259 level. */ int BSP_irq_enabled_at_i8259s (const rtems_irq_number irqLine); @@ -195,6 +257,10 @@ int BSP_i8259s_int_process(void); extern void BSP_rtems_irq_mng_init(unsigned cpuId); extern void BSP_i8259s_init(void); +/** @} */ + +/** @} */ + #ifdef __cplusplus }; #endif diff --git a/c/src/lib/libbsp/mips/shared/liblnk/regs.h b/c/src/lib/libbsp/mips/shared/liblnk/regs.h index 1befa8dc79..5cc9fac745 100644 --- a/c/src/lib/libbsp/mips/shared/liblnk/regs.h +++ b/c/src/lib/libbsp/mips/shared/liblnk/regs.h @@ -1,3 +1,9 @@ +/** + * @file + * @ingroup mips_regs + * @brief Standard MIPS register names. + */ + /* * regs.S -- standard MIPS register names. * @@ -14,7 +20,18 @@ * they apply. */ -/* Standard MIPS register names: */ +/** + * @defgroup mips_regs MIPS Registers + * @ingroup mips_shared + * @brief MIPS Registers + * @{ + */ + +/** + * @name Standard MIPS register names: + * @{ + */ + #define zero $0 #define z0 $0 #define v0 $2 @@ -41,18 +58,24 @@ #define s7 $23 #define t8 $24 #define t9 $25 -#define k0 $26 /* kernel private register 0 */ -#define k1 $27 /* kernel private register 1 */ -#define gp $28 /* global data pointer */ -#define sp $29 /* stack-pointer */ -#define fp $30 /* frame-pointer */ -#define ra $31 /* return address */ -#define pc $pc /* pc, used on mips16 */ +#define k0 $26 ///< @brief kernel private register 0 */ +#define k1 $27 ///< @brief kernel private register 1 */ +#define gp $28 ///< @brief global data pointer */ +#define sp $29 ///< @brief stack-pointer */ +#define fp $30 ///< @brief frame-pointer */ +#define ra $31 ///< @brief return address */ +#define pc $pc ///< @brief pc, used on mips16 */ #define fp0 $f0 #define fp1 $f1 -/* Useful memory constants: */ +/** @} */ + +/** + * @name Useful memory constants: + * @{ + */ + #define K0BASE 0x80000000 #ifndef __mips64 #define K1BASE 0xA0000000 @@ -60,46 +83,69 @@ #define K1BASE 0xFFFFFFFFA0000000LL #endif +/** @} */ + #define PHYS_TO_K1(a) ((unsigned)(a) | K1BASE) -/* Standard Co-Processor 0 register numbers: */ -#define C0_COUNT $9 /* Count Register */ -#define C0_SR $12 /* Status Register */ -#define C0_CAUSE $13 /* last exception description */ -#define C0_EPC $14 /* Exception error address */ -#define C0_CONFIG $16 /* CPU configuration */ +/** + * @name Standard Co-Processor 0 register numbers: + * @{ + */ + +#define C0_COUNT $9 ///< @brief Count Register */ +#define C0_SR $12 ///< @brief Status Register */ +#define C0_CAUSE $13 ///< @brief last exception description */ +#define C0_EPC $14 ///< @brief Exception error address */ +#define C0_CONFIG $16 ///< @brief CPU configuration */ + +/** @} */ + +/** + * @name Standard Status Register bitmasks: + * @{ + */ + +#define SR_CU1 0x20000000 ///< @brief Mark CP1 as usable */ +#define SR_FR 0x04000000 ///< @brief Enable MIPS III FP registers */ +#define SR_BEV 0x00400000 ///< @brief Controls location of exception vectors */ +#define SR_PE 0x00100000 ///< @brief Mark soft reset (clear parity error) */ -/* Standard Status Register bitmasks: */ -#define SR_CU1 0x20000000 /* Mark CP1 as usable */ -#define SR_FR 0x04000000 /* Enable MIPS III FP registers */ -#define SR_BEV 0x00400000 /* Controls location of exception vectors */ -#define SR_PE 0x00100000 /* Mark soft reset (clear parity error) */ +#define SR_KX 0x00000080 ///< @brief Kernel extended addressing enabled */ +#define SR_SX 0x00000040 ///< @brief Supervisor extended addressing enabled */ +#define SR_UX 0x00000020 ///< @brief User extended addressing enabled */ -#define SR_KX 0x00000080 /* Kernel extended addressing enabled */ -#define SR_SX 0x00000040 /* Supervisor extended addressing enabled */ -#define SR_UX 0x00000020 /* User extended addressing enabled */ +/** @} */ -/* Standard (R4000) cache operations. Taken from "MIPS R4000 - Microprocessor User's Manual" 2nd edition: */ +/** + * @name Standard (R4000) cache operations. + * @brief Taken from "MIPS R4000 Microprocessor User's Manual" 2nd edition: + * @{ + */ -#define CACHE_I (0) /* primary instruction */ -#define CACHE_D (1) /* primary data */ -#define CACHE_SI (2) /* secondary instruction */ -#define CACHE_SD (3) /* secondary data (or combined instruction/data) */ +#define CACHE_I (0) ///< @brief primary instruction */ +#define CACHE_D (1) ///< @brief primary data */ +#define CACHE_SI (2) ///< @brief secondary instruction */ +#define CACHE_SD (3) ///< @brief secondary data (or combined instruction/data) */ -#define INDEX_INVALIDATE (0) /* also encodes WRITEBACK if CACHE_D or CACHE_SD */ +#define INDEX_INVALIDATE (0) ///< @brief also encodes WRITEBACK if CACHE_D or CACHE_SD */ #define INDEX_LOAD_TAG (1) #define INDEX_STORE_TAG (2) -#define CREATE_DIRTY_EXCLUSIVE (3) /* CACHE_D and CACHE_SD only */ +#define CREATE_DIRTY_EXCLUSIVE (3) ///< @brief CACHE_D and CACHE_SD only */ #define HIT_INVALIDATE (4) -#define CACHE_FILL (5) /* CACHE_I only */ -#define HIT_WRITEBACK_INVALIDATE (5) /* CACHE_D and CACHE_SD only */ -#define HIT_WRITEBACK (6) /* CACHE_I, CACHE_D and CACHE_SD only */ -#define HIT_SET_VIRTUAL (7) /* CACHE_SI and CACHE_SD only */ +#define CACHE_FILL (5) ///< @brief CACHE_I only */ +#define HIT_WRITEBACK_INVALIDATE (5) ///< @brief CACHE_D and CACHE_SD only */ +#define HIT_WRITEBACK (6) ///< @brief CACHE_I, CACHE_D and CACHE_SD only */ +#define HIT_SET_VIRTUAL (7) ///< @brief CACHE_SI and CACHE_SD only */ #define BUILD_CACHE_OP(o,c) (((o) << 2) | (c)) -/* Individual cache operations: */ +/** @} */ + +/** + * @name Individual cache operations: + * @{ + */ + #define INDEX_INVALIDATE_I BUILD_CACHE_OP(INDEX_INVALIDATE,CACHE_I) #define INDEX_WRITEBACK_INVALIDATE_D BUILD_CACHE_OP(INDEX_INVALIDATE,CACHE_D) #define INDEX_INVALIDATE_SI BUILD_CACHE_OP(INDEX_INVALIDATE,CACHE_SI) @@ -134,4 +180,8 @@ #define HIT_SET_VIRTUAL_SI BUILD_CACHE_OP(HIT_SET_VIRTUAL,CACHE_SI) #define HIT_SET_VIRTUAL_SD BUILD_CACHE_OP(HIT_SET_VIRTUAL,CACHE_SD) +/** @} */ + +/** @} */ + /*> EOF regs.S <*/ -- cgit v1.2.3