From 7044b264e606f92503652836f46440f70f449c50 Mon Sep 17 00:00:00 2001 From: Martin Stein Date: Tue, 17 Jan 2012 09:47:23 +0100 Subject: [PATCH] Beautify class names in 'register.h' and 'mmio.h' Replace 'Reg_array' in 'Genode::Mmio' by 'Register_array' and 'Subreg' in 'Genode::Register', 'Genode::Mmio::Register'and 'Genode::Mmio::Register_array' by 'Bitfield'. Update and beautify comments in the according headers and test programs. --- base/include/util/mmio.h | 182 +++++++++++++++++--------------- base/include/util/register.h | 12 +-- base/src/test/util_mmio/main.cc | 76 +++++++------ 3 files changed, 137 insertions(+), 133 deletions(-) diff --git a/base/include/util/mmio.h b/base/include/util/mmio.h index 221dc357f..472b90010 100644 --- a/base/include/util/mmio.h +++ b/base/include/util/mmio.h @@ -28,7 +28,7 @@ namespace Genode protected: /** - * Write 'value' typed to MMIO base + 'o' + * Write typed 'value' to MMIO base + 'o' */ template inline void _write(off_t const o, STORAGE_T const value); @@ -45,6 +45,12 @@ namespace Genode /** * A POD-like region at offset 'MMIO_OFFSET' within a MMIO region + * + * \detail The register can contain multiple bitfields. Bitfields + * that are partially out of the register range are read and + * written also partially. Bitfields that are completely out + * of the register range are read as '0' and trying to + * overwrite them has no effect */ template struct Register : public Genode::Register @@ -54,12 +60,12 @@ namespace Genode /** * A bitregion within a register * - * \detail Subregs are read and written according to their range, - * so if we have a 'Subreg<2,3>' and write '0b11101' to it + * \detail Bitfields are read and written according to their range, + * so if we have a 'Bitfield<2,3>' and write '0b11101' to it * only '0b101' (shiftet by 2 bits) is written */ template - struct Subreg : public Genode::Register::template Subreg + struct Bitfield : public Genode::Register::template Bitfield { /** * Back reference to containing register @@ -71,16 +77,16 @@ namespace Genode /** * An array of successive similar items * - * \detail 'STORAGE_T' width must a power of 2. The array - * takes all subregs that are covered by an item width and - * iterates them successive 'ITEMS' times, thus subregs out of - * the range of the first item are not accessible. Furthermore - * the maximum item width is the width of 'STORAGE_T'. + * \detail 'STORAGE_T' width must be a power of 2. The array + * takes all bitfields that are covered by an item width and + * iterates them successive 'ITEMS' times. Thus bitfields out of + * the range of the first item are not accessible in any item. + * Furthermore the maximum item width is the width of 'STORAGE_T'. * The array is not limited to one 'STORAGE_T' instance, * it uses as much successive instances as needed. */ template - struct Reg_array : public Register + struct Register_array : public Register { enum { MAX_INDEX = ITEMS - 1, @@ -100,23 +106,25 @@ namespace Genode /** * A bitregion within a register array * - * \detail Subregs are only written and read as far as the - * item width reaches, i.e. assume a 'Reg_array<0,uint8_t,6,2>' - * that contains a 'Subreg<1,5>' and we write '0b01101' to it, then - * only '0b101' is written and read in consequence + * \detail Bitfields are only written and read as far as the + * item width reaches, i.e. assume a 'Register_array<0,uint8_t,6,2>' + * that contains a 'Bitfield<1,5>' and we write '0b01101' to it, then + * only '0b101' is written and read in consequence. Bitfields that are + * completely out of the item range ar read as '0' and trying to overwrite + * them has no effect. */ template - struct Subreg : public Register::template Subreg + struct Bitfield : public Register::template Bitfield { /** * Back reference to containing register array */ - typedef Reg_array Compound_array; + typedef Register_array Compound_array; }; /** * Calculate the MMIO-relative offset 'offset' and shift 'shift' - * within the according 'storage_t' instance to access this subreg + * within the according 'storage_t' instance to access this bitfield * from item 'index' */ static inline void access_dest(off_t & offset, unsigned long & shift, @@ -154,27 +162,27 @@ namespace Genode inline typename REGISTER::storage_t read() const; /** - * Override the register 'REGISTER' with 'value' + * Write 'value' to the register 'REGISTER' */ template inline void write(typename REGISTER::storage_t const value); - /**************************************** - ** Access to subregs within registers ** - ****************************************/ + /****************************************** + ** Access to bitfields within registers ** + ******************************************/ /** - * Read the subreg 'SUBREG' + * Read the bitfield 'BITFIELD' */ - template - inline typename SUBREG::Compound_reg::storage_t read() const; + template + inline typename BITFIELD::Compound_reg::storage_t read() const; /** - * Override the subreg 'SUBREG' with 'value' + * Write value to the bitfield 'BITFIELD' */ - template - inline void write(typename SUBREG::Compound_reg::storage_t const value); + template + inline void write(typename BITFIELD::Compound_reg::storage_t const value); /******************************* @@ -182,34 +190,34 @@ namespace Genode *******************************/ /** - * Read the whole item 'index' of the array 'REG_ARRAY' + * Read the whole item 'index' of the array 'REGISTER_ARRAY' */ - template - inline typename REG_ARRAY::storage_t read(unsigned long const index) const; + template + inline typename REGISTER_ARRAY::storage_t read(unsigned long const index) const; /** - * Override item 'index' of the array 'REG_ARRAY' with 'value' + * Write 'value' to item 'index' of the array 'REGISTER_ARRAY' */ - template - inline void write(typename REG_ARRAY::storage_t const value, + template + inline void write(typename REGISTER_ARRAY::storage_t const value, unsigned long const index); - /*************************************************** - ** Access to subregs within register array items ** - ***************************************************/ + /***************************************************** + ** Access to bitfields within register array items ** + *****************************************************/ /** - * Read the subreg 'ARRAY_SUBREG' of item 'index' of the compound reg array + * Read the bitfield 'ARRAY_BITFIELD' of item 'index' of the compound reg array */ - template - inline typename ARRAY_SUBREG::Compound_array::storage_t read(unsigned long const index) const; + template + inline typename ARRAY_BITFIELD::Compound_array::storage_t read(unsigned long const index) const; /** - * Override subreg 'ARRAY_SUBREG' of item 'index' of the compound reg array with 'value' + * Write 'value' to bitfield 'ARRAY_BITFIELD' of item 'index' of the compound reg array */ - template - inline void write(typename ARRAY_SUBREG::Compound_array::storage_t const value, long unsigned const index); + template + inline void write(typename ARRAY_BITFIELD::Compound_array::storage_t const value, long unsigned const index); }; } @@ -254,30 +262,30 @@ void Genode::Mmio::write(typename REGISTER::storage_t const value) } -/**************************************** - ** Access to subregs within registers ** - ****************************************/ +/****************************************** + ** Access to bitfields within registers ** + ******************************************/ -template -typename SUBREG::Compound_reg::storage_t Genode::Mmio::read() const +template +typename BITFIELD::Compound_reg::storage_t Genode::Mmio::read() const { - typedef typename SUBREG::Compound_reg Register; + typedef typename BITFIELD::Compound_reg Register; typedef typename Register::storage_t storage_t; - return SUBREG::get(_read(Register::OFFSET)); + return BITFIELD::get(_read(Register::OFFSET)); } -template -void Genode::Mmio::write(typename SUBREG::Compound_reg::storage_t const value) +template +void Genode::Mmio::write(typename BITFIELD::Compound_reg::storage_t const value) { - typedef typename SUBREG::Compound_reg Register; + typedef typename BITFIELD::Compound_reg Register; typedef typename Register::storage_t storage_t; storage_t new_reg = read(); - SUBREG::clear(new_reg); - SUBREG::set(new_reg, value); + BITFIELD::clear(new_reg); + BITFIELD::set(new_reg, value); write(new_reg); } @@ -288,96 +296,96 @@ void Genode::Mmio::write(typename SUBREG::Compound_reg::storage_t const value) ************************************/ -template -typename REG_ARRAY::storage_t Genode::Mmio::read(unsigned long const index) const +template +typename REGISTER_ARRAY::storage_t Genode::Mmio::read(unsigned long const index) const { /** * Handle array overflow */ - if (index > REG_ARRAY::MAX_INDEX) return 0; + if (index > REGISTER_ARRAY::MAX_INDEX) return 0; off_t offset; /** * Optimize access if item width equals storage type width */ - if (REG_ARRAY::ITEM_IS_REG) { + if (REGISTER_ARRAY::ITEM_IS_REG) { - offset = REG_ARRAY::OFFSET + (index << REG_ARRAY::ITEM_WIDTH_LOG2); - return _read(offset); + offset = REGISTER_ARRAY::OFFSET + (index << REGISTER_ARRAY::ITEM_WIDTH_LOG2); + return _read(offset); } else { long unsigned shift; - REG_ARRAY::access_dest(offset, shift, index); - return (_read(offset) >> shift) & REG_ARRAY::ITEM_MASK; + REGISTER_ARRAY::access_dest(offset, shift, index); + return (_read(offset) >> shift) & REGISTER_ARRAY::ITEM_MASK; } } -template -void Genode::Mmio::write(typename REG_ARRAY::storage_t const value, +template +void Genode::Mmio::write(typename REGISTER_ARRAY::storage_t const value, unsigned long const index) { /** * Avoid array overflow */ - if (index > REG_ARRAY::MAX_INDEX) return; + if (index > REGISTER_ARRAY::MAX_INDEX) return; off_t offset; /** * Optimize access if item width equals storage type width */ - if (REG_ARRAY::ITEM_IS_REG) { + if (REGISTER_ARRAY::ITEM_IS_REG) { - offset = REG_ARRAY::OFFSET + (index << REG_ARRAY::ITEM_WIDTH_LOG2); - _write(offset, value); + offset = REGISTER_ARRAY::OFFSET + (index << REGISTER_ARRAY::ITEM_WIDTH_LOG2); + _write(offset, value); } else { long unsigned shift; - REG_ARRAY::access_dest(offset, shift, index); + REGISTER_ARRAY::access_dest(offset, shift, index); /** * Insert new value into old register value */ - typename REG_ARRAY::storage_t new_reg = _read(offset); - new_reg &= ~(REG_ARRAY::ITEM_MASK << shift); - new_reg |= (value & REG_ARRAY::ITEM_MASK) << shift; + typename REGISTER_ARRAY::storage_t new_reg = _read(offset); + new_reg &= ~(REGISTER_ARRAY::ITEM_MASK << shift); + new_reg |= (value & REGISTER_ARRAY::ITEM_MASK) << shift; - _write(offset, new_reg); + _write(offset, new_reg); } } -/*************************************************** - ** Access to subregs within register array items ** - ***************************************************/ +/***************************************************** + ** Access to bitfields within register array items ** + *****************************************************/ -template -void Genode::Mmio::write(typename ARRAY_SUBREG::Compound_array::storage_t const value, +template +void Genode::Mmio::write(typename ARRAY_BITFIELD::Compound_array::storage_t const value, long unsigned const index) { - typedef typename ARRAY_SUBREG::Compound_array Reg_array; + typedef typename ARRAY_BITFIELD::Compound_array Register_array; - typename Reg_array::storage_t new_reg = read(index); - ARRAY_SUBREG::clear(new_reg); - ARRAY_SUBREG::set(new_reg, value); + typename Register_array::storage_t new_reg = read(index); + ARRAY_BITFIELD::clear(new_reg); + ARRAY_BITFIELD::set(new_reg, value); - write(new_reg, index); + write(new_reg, index); } -template -typename ARRAY_SUBREG::Compound_array::storage_t Genode::Mmio::read(long unsigned const index) const +template +typename ARRAY_BITFIELD::Compound_array::storage_t Genode::Mmio::read(long unsigned const index) const { - typedef typename ARRAY_SUBREG::Compound_array Array; + typedef typename ARRAY_BITFIELD::Compound_array Array; typedef typename Array::storage_t storage_t; - return ARRAY_SUBREG::get(read(index)); + return ARRAY_BITFIELD::get(read(index)); } diff --git a/base/include/util/register.h b/base/include/util/register.h index ea17d2541..7edfffcfe 100644 --- a/base/include/util/register.h +++ b/base/include/util/register.h @@ -30,7 +30,7 @@ namespace Genode * A bitregion within a register */ template - struct Subreg + struct Bitfield { enum { SHIFT = BIT_SHIFT, @@ -46,25 +46,25 @@ namespace Genode typedef Register Compound_reg; /** - * Get a register value with this subreg set to 'value' and the rest left zero + * Get a register value with this bitfield set to 'value' and the rest left zero * - * \detail Useful to combine successive access to multiple subregs + * \detail Useful to combine successive access to multiple bitfields * into one operation */ static inline storage_t bits(storage_t const value) { return (value & MASK) << SHIFT; } /** - * Get value of this subreg from 'reg' + * Get value of this bitfield from 'reg' */ static inline storage_t get(storage_t const reg) { return (reg >> SHIFT) & MASK; } /** - * Get registervalue 'reg' with this subreg set to zero + * Get registervalue 'reg' with this bitfield set to zero */ static inline void clear(storage_t & reg) { reg &= CLEAR_MASK; } /** - * Get registervalue 'reg' with this subreg set to 'value' + * Get registervalue 'reg' with this bitfield set to 'value' */ static inline void set(storage_t & reg, storage_t const value = ~0) { diff --git a/base/src/test/util_mmio/main.cc b/base/src/test/util_mmio/main.cc index 8b54d39b7..aa75e1f93 100644 --- a/base/src/test/util_mmio/main.cc +++ b/base/src/test/util_mmio/main.cc @@ -33,7 +33,7 @@ static uint8_t mmio_mem[MMIO_SIZE]; */ struct Cpu_state : Register { - struct Mode : Subreg<0,4> + struct Mode : Bitfield<0,4> { enum { KERNEL = 0b1000, @@ -41,13 +41,13 @@ struct Cpu_state : Register MONITOR = 0b1010, }; }; - struct A : Subreg<6,1> { }; - struct B : Subreg<8,1> { }; - struct C : Subreg<10,1> { }; - struct Irq : Subreg<12,3> { }; + struct A : Bitfield<6,1> { }; + struct B : Bitfield<8,1> { }; + struct C : Bitfield<10,1> { }; + struct Irq : Bitfield<12,3> { }; - struct Invalid_bit : Subreg<18,1> { }; - struct Invalid_area : Subreg<15,4> { }; + struct Invalid_bit : Bitfield<18,1> { }; + struct Invalid_area : Bitfield<15,4> { }; inline static storage_t read() { return cpu_state; } @@ -69,8 +69,8 @@ struct Test_mmio : public Mmio struct Reg : Register<0x04, uint8_t> { - struct Bit_1 : Subreg<0,1> { }; - struct Area : Subreg<1,3> + struct Bit_1 : Bitfield<0,1> { }; + struct Area : Bitfield<1,3> { enum { VALUE_1 = 3, @@ -78,30 +78,21 @@ struct Test_mmio : public Mmio VALUE_3 = 5, }; }; - struct Bit_2 : Subreg<4,1> { }; - struct Invalid_bit : Subreg<8,1> { }; - struct Invalid_area : Subreg<6,8> { }; - struct Overlapping_area : Subreg<0,6> { }; + struct Bit_2 : Bitfield<4,1> { }; + struct Invalid_bit : Bitfield<8,1> { }; + struct Invalid_area : Bitfield<6,8> { }; + struct Overlapping_area : Bitfield<0,6> { }; }; - struct Array : Reg_array<0x2, uint16_t, 10, 2> + struct Array : Register_array<0x2, uint16_t, 10, 2> { - struct A : Subreg<0,1> { }; - struct B : Subreg<1,2> { }; - struct C : Subreg<3,1> { }; - struct D : Subreg<1,3> { }; + struct A : Bitfield<0,1> { }; + struct B : Bitfield<1,2> { }; + struct C : Bitfield<3,1> { }; + struct D : Bitfield<1,3> { }; }; }; -/* little endian LSB --> MSB */ -/* big endian MSB <-- LSB */ -/* address 0x0 0x1 0x2 0x3 0x4 0x5 0x6 0x7 0x8 */ -/* bits 0 4 8 12 16 20 24 28 32 36 40 44 48 52 56 60 64 */ -/* bit ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| */ -/* 4bit | | | | |R0 |R1 |R2 |R3 |R4 |R5 |-- |-- | | | | | */ -/* 8bit (byte)| | | | | | | | | */ -/* 16bit | |Int0 |Int1 | | */ -/* 32bit | | | */ -/* 64bit | | */ + /** * Print out memory content hexadecimal @@ -159,9 +150,9 @@ int test_failed(unsigned test_id) int main() { - /********************************** - ** Genode::Mmio::Register tests ** - **********************************/ + /************************************ + ** 'Genode::Mmio::Register' tests ** + ************************************/ /** * Init fake MMIO @@ -169,7 +160,7 @@ int main() Test_mmio mmio((addr_t)&mmio_mem[0]); /** - * Test 1, read/write whole reg, use 'Subreg::bits' with overflowing values + * Test 1, read/write whole reg, use 'Bitfield::bits' with overflowing values */ zero_mem(mmio_mem, sizeof(mmio_mem)); mmio.write(Test_mmio::Reg::Bit_1::bits(7) | @@ -243,7 +234,7 @@ int main() { return test_failed(7); } /** - * Test 8, read/write bitarea that overlaps other subregs + * Test 8, read/write bitarea that overlaps other bitfields */ mmio.write(0b00110011); @@ -253,12 +244,12 @@ int main() { return test_failed(8); } - /**************************** - ** Genode::Register tests ** - ****************************/ + /****************************** + ** 'Genode::Register' tests ** + ******************************/ /** - * Test 9, read/write subregs appropriately, overflowing and out of range + * Test 9, read/write bitfields appropriately, overflowing and out of range */ Cpu_state::storage_t state = Cpu_state::read(); Cpu_state::Mode::set(state, Cpu_state::Mode::MONITOR); @@ -282,7 +273,7 @@ int main() { return test_failed(9); } /** - * Test 10, clear subregs + * Test 10, clear bitfields */ Cpu_state::B::clear(state); Cpu_state::Irq::clear(state); @@ -294,6 +285,11 @@ int main() || Cpu_state::Irq::get(state) != 0) { return test_failed(10); } + + /****************************************** + ** 'Genode::Mmio::Register_array' tests ** + ******************************************/ + /** * Test 11, read/write register array items with array- and item overflows */ @@ -314,8 +310,8 @@ int main() { return test_failed(11); } /** - * Test 12, read/write subregs of register array items with array-, item- and subreg overflows - * also test overlappng subregs + * Test 12, read/write bitfields of register array items with array-, item- and bitfield overflows + * also test overlappng bitfields */ zero_mem(mmio_mem, sizeof(mmio_mem)); mmio.write(0x1, 0);