ehmry/genode
ehmry/genode
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Beautify class names in 'register.h' and 'mmio.h'

Browse Source 
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.
This commit is contained in:
Martin Stein 2012-01-17 09:47:23 +01:00 committed by Norman Feske
parent e1285335ab
commit 7044b264e6
3 changed files with 137 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

182
base/include/util/mmio.h
View File

@ -28,7 +28,7 @@ namespace Genode
protected: protected:
/** /**
* Write 'value' typed to MMIO base + 'o' * Write typed 'value' to MMIO base + 'o'
*/ */
template <typename STORAGE_T> template <typename STORAGE_T>
inline void _write(off_t const o, STORAGE_T const value); 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 * 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 <off_t MMIO_OFFSET, typename STORAGE_T> template <off_t MMIO_OFFSET, typename STORAGE_T>
struct Register : public Genode::Register<STORAGE_T> struct Register : public Genode::Register<STORAGE_T>
@ -54,12 +60,12 @@ namespace Genode
/** /**
* A bitregion within a register * A bitregion within a register
* *
* \detail Subregs are read and written according to their range, * \detail Bitfields are read and written according to their range,
* so if we have a 'Subreg<2,3>' and write '0b11101' to it * so if we have a 'Bitfield<2,3>' and write '0b11101' to it
* only '0b101' (shiftet by 2 bits) is written * only '0b101' (shiftet by 2 bits) is written
*/ */
template <unsigned long BIT_SHIFT, unsigned long BIT_SIZE> template <unsigned long BIT_SHIFT, unsigned long BIT_SIZE>
struct Subreg : public Genode::Register<STORAGE_T>::template Subreg<BIT_SHIFT, BIT_SIZE> struct Bitfield : public Genode::Register<STORAGE_T>::template Bitfield<BIT_SHIFT, BIT_SIZE>
{ {
/** /**
* Back reference to containing register * Back reference to containing register
@ -71,16 +77,16 @@ namespace Genode
/** /**
* An array of successive similar items * An array of successive similar items
* *
* \detail 'STORAGE_T' width must a power of 2. The array * \detail 'STORAGE_T' width must be a power of 2. The array
* takes all subregs that are covered by an item width and * takes all bitfields that are covered by an item width and
* iterates them successive 'ITEMS' times, thus subregs out of * iterates them successive 'ITEMS' times. Thus bitfields out of
* the range of the first item are not accessible. Furthermore * the range of the first item are not accessible in any item.
* the maximum item width is the width of 'STORAGE_T'. * Furthermore the maximum item width is the width of 'STORAGE_T'.
* The array is not limited to one 'STORAGE_T' instance, * The array is not limited to one 'STORAGE_T' instance,
* it uses as much successive instances as needed. * it uses as much successive instances as needed.
*/ */
template <off_t MMIO_OFFSET, typename STORAGE_T, unsigned long ITEMS, unsigned long _ITEM_WIDTH_LOG2> template <off_t MMIO_OFFSET, typename STORAGE_T, unsigned long ITEMS, unsigned long _ITEM_WIDTH_LOG2>
struct Reg_array : public Register<MMIO_OFFSET, STORAGE_T> struct Register_array : public Register<MMIO_OFFSET, STORAGE_T>
{ {
enum { enum {
MAX_INDEX = ITEMS - 1, MAX_INDEX = ITEMS - 1,
@ -100,23 +106,25 @@ namespace Genode
/** /**
* A bitregion within a register array * A bitregion within a register array
* *
* \detail Subregs are only written and read as far as the * \detail Bitfields are only written and read as far as the
* item width reaches, i.e. assume a 'Reg_array<0,uint8_t,6,2>' * item width reaches, i.e. assume a 'Register_array<0,uint8_t,6,2>'
* that contains a 'Subreg<1,5>' and we write '0b01101' to it, then * that contains a 'Bitfield<1,5>' and we write '0b01101' to it, then
* only '0b101' is written and read in consequence * 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 <unsigned long BIT_SHIFT, unsigned long BIT_SIZE> template <unsigned long BIT_SHIFT, unsigned long BIT_SIZE>
struct Subreg : public Register<MMIO_OFFSET, STORAGE_T>::template Subreg<BIT_SHIFT, BIT_SIZE> struct Bitfield : public Register<MMIO_OFFSET, STORAGE_T>::template Bitfield<BIT_SHIFT, BIT_SIZE>
{ {
/** /**
* Back reference to containing register array * Back reference to containing register array
*/ */
typedef Reg_array<MMIO_OFFSET, STORAGE_T, ITEMS, ITEM_WIDTH_LOG2> Compound_array; typedef Register_array<MMIO_OFFSET, STORAGE_T, ITEMS, ITEM_WIDTH_LOG2> Compound_array;
}; };
/** /**
* Calculate the MMIO-relative offset 'offset' and shift 'shift' * 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' * from item 'index'
*/ */
static inline void access_dest(off_t & offset, unsigned long & shift, static inline void access_dest(off_t & offset, unsigned long & shift,
@ -154,27 +162,27 @@ namespace Genode
inline typename REGISTER::storage_t read() const; inline typename REGISTER::storage_t read() const;
/** /**
* Override the register 'REGISTER' with 'value' * Write 'value' to the register 'REGISTER'
*/ */
template <typename REGISTER> template <typename REGISTER>
inline void write(typename REGISTER::storage_t const value); 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 <typename SUBREG> template <typename BITFIELD>
inline typename SUBREG::Compound_reg::storage_t read() const; inline typename BITFIELD::Compound_reg::storage_t read() const;
/** /**
* Override the subreg 'SUBREG' with 'value' * Write value to the bitfield 'BITFIELD'
*/ */
template <typename SUBREG> template <typename BITFIELD>
inline void write(typename SUBREG::Compound_reg::storage_t const value); 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 <typename REG_ARRAY> template <typename REGISTER_ARRAY>
inline typename REG_ARRAY::storage_t read(unsigned long const index) const; 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 <typename REG_ARRAY> template <typename REGISTER_ARRAY>
inline void write(typename REG_ARRAY::storage_t const value, inline void write(typename REGISTER_ARRAY::storage_t const value,
unsigned long const index); 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 <typename ARRAY_SUBREG> template <typename ARRAY_BITFIELD>
inline typename ARRAY_SUBREG::Compound_array::storage_t read(unsigned long const index) const; 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 <typename ARRAY_SUBREG> template <typename ARRAY_BITFIELD>
inline void write(typename ARRAY_SUBREG::Compound_array::storage_t const value, long unsigned const index); 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> template <typename BITFIELD>
typename SUBREG::Compound_reg::storage_t Genode::Mmio::read() const 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; typedef typename Register::storage_t storage_t;
return SUBREG::get(_read<storage_t>(Register::OFFSET)); return BITFIELD::get(_read<storage_t>(Register::OFFSET));
} }
template <typename SUBREG> template <typename BITFIELD>
void Genode::Mmio::write(typename SUBREG::Compound_reg::storage_t const value) 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; typedef typename Register::storage_t storage_t;
storage_t new_reg = read<Register>(); storage_t new_reg = read<Register>();
SUBREG::clear(new_reg); BITFIELD::clear(new_reg);
SUBREG::set(new_reg, value); BITFIELD::set(new_reg, value);
write<Register>(new_reg); write<Register>(new_reg);
} }
@ -288,96 +296,96 @@ void Genode::Mmio::write(typename SUBREG::Compound_reg::storage_t const value)
************************************/ ************************************/
template <typename REG_ARRAY> template <typename REGISTER_ARRAY>
typename REG_ARRAY::storage_t Genode::Mmio::read(unsigned long const index) const typename REGISTER_ARRAY::storage_t Genode::Mmio::read(unsigned long const index) const
{ {
/** /**
* Handle array overflow * Handle array overflow
*/ */
if (index > REG_ARRAY::MAX_INDEX) return 0; if (index > REGISTER_ARRAY::MAX_INDEX) return 0;
off_t offset; off_t offset;
/** /**
* Optimize access if item width equals storage type width * 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); offset = REGISTER_ARRAY::OFFSET + (index << REGISTER_ARRAY::ITEM_WIDTH_LOG2);
return _read<typename REG_ARRAY::storage_t>(offset); return _read<typename REGISTER_ARRAY::storage_t>(offset);
} else { } else {
long unsigned shift; long unsigned shift;
REG_ARRAY::access_dest(offset, shift, index); REGISTER_ARRAY::access_dest(offset, shift, index);
return (_read<typename REG_ARRAY::storage_t>(offset) >> shift) & REG_ARRAY::ITEM_MASK; return (_read<typename REGISTER_ARRAY::storage_t>(offset) >> shift) & REGISTER_ARRAY::ITEM_MASK;
} }
} }
template <typename REG_ARRAY> template <typename REGISTER_ARRAY>
void Genode::Mmio::write(typename REG_ARRAY::storage_t const value, void Genode::Mmio::write(typename REGISTER_ARRAY::storage_t const value,
unsigned long const index) unsigned long const index)
{ {
/** /**
* Avoid array overflow * Avoid array overflow
*/ */
if (index > REG_ARRAY::MAX_INDEX) return; if (index > REGISTER_ARRAY::MAX_INDEX) return;
off_t offset; off_t offset;
/** /**
* Optimize access if item width equals storage type width * 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); offset = REGISTER_ARRAY::OFFSET + (index << REGISTER_ARRAY::ITEM_WIDTH_LOG2);
_write<typename REG_ARRAY::storage_t>(offset, value); _write<typename REGISTER_ARRAY::storage_t>(offset, value);
} else { } else {
long unsigned shift; long unsigned shift;
REG_ARRAY::access_dest(offset, shift, index); REGISTER_ARRAY::access_dest(offset, shift, index);
/** /**
* Insert new value into old register value * Insert new value into old register value
*/ */
typename REG_ARRAY::storage_t new_reg = _read<typename REG_ARRAY::storage_t>(offset); typename REGISTER_ARRAY::storage_t new_reg = _read<typename REGISTER_ARRAY::storage_t>(offset);
new_reg &= ~(REG_ARRAY::ITEM_MASK << shift); new_reg &= ~(REGISTER_ARRAY::ITEM_MASK << shift);
new_reg |= (value & REG_ARRAY::ITEM_MASK) << shift; new_reg |= (value & REGISTER_ARRAY::ITEM_MASK) << shift;
_write<typename REG_ARRAY::storage_t>(offset, new_reg); _write<typename REGISTER_ARRAY::storage_t>(offset, new_reg);
} }
} }
/*************************************************** /*****************************************************
** Access to subregs within register array items ** ** Access to bitfields within register array items **
***************************************************/ *****************************************************/
template <typename ARRAY_SUBREG> template <typename ARRAY_BITFIELD>
void Genode::Mmio::write(typename ARRAY_SUBREG::Compound_array::storage_t const value, void Genode::Mmio::write(typename ARRAY_BITFIELD::Compound_array::storage_t const value,
long unsigned const index) 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<Reg_array>(index); typename Register_array::storage_t new_reg = read<Register_array>(index);
ARRAY_SUBREG::clear(new_reg); ARRAY_BITFIELD::clear(new_reg);
ARRAY_SUBREG::set(new_reg, value); ARRAY_BITFIELD::set(new_reg, value);
write<Reg_array>(new_reg, index); write<Register_array>(new_reg, index);
} }
template <typename ARRAY_SUBREG> template <typename ARRAY_BITFIELD>
typename ARRAY_SUBREG::Compound_array::storage_t Genode::Mmio::read(long unsigned const index) const 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; typedef typename Array::storage_t storage_t;
return ARRAY_SUBREG::get(read<Array>(index)); return ARRAY_BITFIELD::get(read<Array>(index));
} }

12
base/include/util/register.h
View File

@ -30,7 +30,7 @@ namespace Genode
* A bitregion within a register * A bitregion within a register
*/ */
template <unsigned long BIT_SHIFT, unsigned long BIT_SIZE> template <unsigned long BIT_SHIFT, unsigned long BIT_SIZE>
struct Subreg struct Bitfield
{ {
enum { enum {
SHIFT = BIT_SHIFT, SHIFT = BIT_SHIFT,
@ -46,25 +46,25 @@ namespace Genode
typedef Register<storage_t> Compound_reg; typedef Register<storage_t> 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 * into one operation
*/ */
static inline storage_t bits(storage_t const value) { return (value & MASK) << SHIFT; } 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; } 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; } 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) static inline void set(storage_t & reg, storage_t const value = ~0)
{ {

76
base/src/test/util_mmio/main.cc
View File

@ -33,7 +33,7 @@ static uint8_t mmio_mem[MMIO_SIZE];
*/ */
struct Cpu_state : Register<uint16_t> struct Cpu_state : Register<uint16_t>
{ {
struct Mode : Subreg<0,4> struct Mode : Bitfield<0,4>
{ {
enum { enum {
KERNEL = 0b1000, KERNEL = 0b1000,
@ -41,13 +41,13 @@ struct Cpu_state : Register<uint16_t>
MONITOR = 0b1010, MONITOR = 0b1010,
}; };
}; };
struct A : Subreg<6,1> { }; struct A : Bitfield<6,1> { };
struct B : Subreg<8,1> { }; struct B : Bitfield<8,1> { };
struct C : Subreg<10,1> { }; struct C : Bitfield<10,1> { };
struct Irq : Subreg<12,3> { }; struct Irq : Bitfield<12,3> { };
struct Invalid_bit : Subreg<18,1> { }; struct Invalid_bit : Bitfield<18,1> { };
struct Invalid_area : Subreg<15,4> { }; struct Invalid_area : Bitfield<15,4> { };
inline static storage_t read() { return cpu_state; } inline static storage_t read() { return cpu_state; }
@ -69,8 +69,8 @@ struct Test_mmio : public Mmio
struct Reg : Register<0x04, uint8_t> struct Reg : Register<0x04, uint8_t>
{ {
struct Bit_1 : Subreg<0,1> { }; struct Bit_1 : Bitfield<0,1> { };
struct Area : Subreg<1,3> struct Area : Bitfield<1,3>
{ {
enum { enum {
VALUE_1 = 3, VALUE_1 = 3,
@ -78,30 +78,21 @@ struct Test_mmio : public Mmio
VALUE_3 = 5, VALUE_3 = 5,
}; };
}; };
struct Bit_2 : Subreg<4,1> { }; struct Bit_2 : Bitfield<4,1> { };
struct Invalid_bit : Subreg<8,1> { }; struct Invalid_bit : Bitfield<8,1> { };
struct Invalid_area : Subreg<6,8> { }; struct Invalid_area : Bitfield<6,8> { };
struct Overlapping_area : Subreg<0,6> { }; 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 A : Bitfield<0,1> { };
struct B : Subreg<1,2> { }; struct B : Bitfield<1,2> { };
struct C : Subreg<3,1> { }; struct C : Bitfield<3,1> { };
struct D : Subreg<1,3> { }; 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 * Print out memory content hexadecimal
@ -159,9 +150,9 @@ int test_failed(unsigned test_id)
int main() int main()
{ {
/********************************** /************************************
** Genode::Mmio::Register tests ** ** 'Genode::Mmio::Register' tests **
**********************************/ ************************************/
/** /**
* Init fake MMIO * Init fake MMIO
@ -169,7 +160,7 @@ int main()
Test_mmio mmio((addr_t)&mmio_mem[0]); 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)); zero_mem(mmio_mem, sizeof(mmio_mem));
mmio.write<Test_mmio::Reg>(Test_mmio::Reg::Bit_1::bits(7) | mmio.write<Test_mmio::Reg>(Test_mmio::Reg::Bit_1::bits(7) |
@ -243,7 +234,7 @@ int main()
{ return test_failed(7); } { return test_failed(7); }
/** /**
* Test 8, read/write bitarea that overlaps other subregs * Test 8, read/write bitarea that overlaps other bitfields
*/ */
mmio.write<Test_mmio::Reg::Overlapping_area>(0b00110011); mmio.write<Test_mmio::Reg::Overlapping_area>(0b00110011);
@ -253,12 +244,12 @@ int main()
{ return test_failed(8); } { 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::storage_t state = Cpu_state::read();
Cpu_state::Mode::set(state, Cpu_state::Mode::MONITOR); Cpu_state::Mode::set(state, Cpu_state::Mode::MONITOR);
@ -282,7 +273,7 @@ int main()
{ return test_failed(9); } { return test_failed(9); }
/** /**
* Test 10, clear subregs * Test 10, clear bitfields
*/ */
Cpu_state::B::clear(state); Cpu_state::B::clear(state);
Cpu_state::Irq::clear(state); Cpu_state::Irq::clear(state);
@ -294,6 +285,11 @@ int main()
|| Cpu_state::Irq::get(state) != 0) || Cpu_state::Irq::get(state) != 0)
{ return test_failed(10); } { return test_failed(10); }
/******************************************
** 'Genode::Mmio::Register_array' tests **
******************************************/
/** /**
* Test 11, read/write register array items with array- and item overflows * Test 11, read/write register array items with array- and item overflows
*/ */
@ -314,8 +310,8 @@ int main()
{ return test_failed(11); } { return test_failed(11); }
/** /**
* Test 12, read/write subregs of register array items with array-, item- and subreg overflows * Test 12, read/write bitfields of register array items with array-, item- and bitfield overflows
* also test overlappng subregs * also test overlappng bitfields
*/ */
zero_mem(mmio_mem, sizeof(mmio_mem)); zero_mem(mmio_mem, sizeof(mmio_mem));
mmio.write<Test_mmio::Array::A>(0x1, 0); mmio.write<Test_mmio::Array::A>(0x1, 0);