diff options
Diffstat (limited to 'utils/regtools/include')
-rw-r--r-- | utils/regtools/include/soc_desc.hpp | 384 | ||||
-rw-r--r-- | utils/regtools/include/soc_desc_v1.hpp | 230 |
2 files changed, 614 insertions, 0 deletions
diff --git a/utils/regtools/include/soc_desc.hpp b/utils/regtools/include/soc_desc.hpp new file mode 100644 index 0000000000..66f2e3b6e1 --- /dev/null +++ b/utils/regtools/include/soc_desc.hpp @@ -0,0 +1,384 @@ +/*************************************************************************** + * __________ __ ___. + * Open \______ \ ____ ____ | | _\_ |__ _______ ___ + * Source | _// _ \_/ ___\| |/ /| __ \ / _ \ \/ / + * Jukebox | | ( <_> ) \___| < | \_\ ( <_> > < < + * Firmware |____|_ /\____/ \___ >__|_ \|___ /\____/__/\_ \ + * \/ \/ \/ \/ \/ + * $Id$ + * + * Copyright (C) 2014 by Amaury Pouly + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License + * as published by the Free Software Foundation; either version 2 + * of the License, or (at your option) any later version. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ****************************************************************************/ +#ifndef __SOC_DESC__ +#define __SOC_DESC__ + +#include <stdint.h> +#include <vector> +#include <list> +#include <string> +#include <map> + +namespace soc_desc +{ + +const size_t MAJOR_VERSION = 2; +const size_t MINOR_VERSION = 0; +const size_t REVISION_VERSION = 0; + +/** Typedef for SoC types: word, address and flags */ +typedef uint32_t soc_addr_t; +typedef uint32_t soc_word_t; +typedef int soc_id_t; + +/** Error class */ +class error_t +{ +public: + enum level_t + { + INFO, + WARNING, + FATAL + }; + error_t(level_t lvl, const std::string& loc, const std::string& msg) + :m_level(lvl), m_loc(loc), m_msg(msg) {} + level_t level() const { return m_level; } + std::string location() const { return m_loc; } + std::string message() const { return m_msg; } +protected: + level_t m_level; + std::string m_loc, m_msg; +}; + +/** Error context to log errors */ +class error_context_t +{ +public: + void add(const error_t& err) { m_list.push_back(err); } + size_t count() const { return m_list.size(); } + error_t get(size_t i) const { return m_list[i]; } +protected: + std::vector< error_t > m_list; +}; + +/** + * Bare representation of the format + */ + +/** Enumerated value (aka named value), represents a special value for a field */ +struct enum_t +{ + soc_id_t id; /** ID (must be unique among field enums) */ + std::string name; /** Name (must be unique among field enums) */ + std::string desc; /** Optional description of the meaning of this value */ + soc_word_t value; /** Value of the field */ +}; + +/** Register field information */ +struct field_t +{ + soc_id_t id; /** ID (must be unique among register fields) */ + std::string name; /** Name (must be unique among register fields) */ + std::string desc; /** Optional description of the field */ + size_t pos; /** Position of the least significant bit */ + size_t width; /** Width of the field in bits */ + std::vector< enum_t > enum_; /** List of special values */ + + /** Returns the bit mask of the field within the register */ + soc_word_t bitmask() const + { + // WARNING beware of the case where width is 32 + if(width == 32) + return 0xffffffff; + else + return ((1 << width) - 1) << pos; + } + + /** Extract field value from register value */ + soc_word_t extract(soc_word_t reg_val) const + { + return (reg_val & bitmask()) >> pos; + } + + /** Replace the field value in a register value */ + soc_word_t replace(soc_word_t reg_val, soc_word_t field_val) const + { + return (reg_val & ~bitmask()) | ((field_val << pos) & bitmask()); + } + + /** Return field value index, or -1 if none */ + int find_value(soc_word_t v) const + { + for(size_t i = 0; i < enum_.size(); i++) + if(enum_[i].value == v) + return i; + return -1; + } +}; + +/** Register information */ +struct register_t +{ + size_t width; /** Size in bits */ + std::vector< field_t > field; /** List of fields */ +}; + +/** Node address range information */ +struct range_t +{ + enum type_t + { + STRIDE, /** Addresses are given by a base address and a stride */ + FORMULA /** Addresses are given by a formula */ + }; + + type_t type; /** Range type */ + size_t first; /** First index in the range */ + size_t count; /** Number of indexes in the range */ + soc_word_t base; /** Base address (for STRIDE) */ + soc_word_t stride; /** Stride value (for STRIDE) */ + std::string formula; /** Formula (for FORMULA) */ + std::string variable; /** Formula variable name (for FORMULA) */ +}; + +/** Node instance information */ +struct instance_t +{ + enum type_t + { + SINGLE, /** There is a single instance at a specified address */ + RANGE /** There are multiple addresses forming a range */ + }; + + soc_id_t id; /** ID (must be unique among node instances) */ + std::string name; /** Name (must be unique among node instances) */ + std::string title; /** Optional instance human name */ + std::string desc; /** Optional description of the instance */ + type_t type; /** Instance type */ + soc_word_t addr; /** Address (for SINGLE) */ + range_t range; /** Range (for RANGE) */ +}; + +/** Node information */ +struct node_t +{ + soc_id_t id; /** ID (must be unique among nodes) */ + std::string name; /** Name (must be unique for the among nodes) */ + std::string title; /** Optional node human name */ + std::string desc; /** Optional description of the node */ + std::vector< register_t> register_; /** Optional register */ + std::vector< instance_t> instance; /** List of instances */ + std::vector< node_t > node; /** List of sub-nodes */ +}; + +/** System-on-chip information */ +struct soc_t +{ + std::string name; /** Codename of the SoC */ + std::string title; /** Human name of the SoC */ + std::string desc; /** Optional description of the SoC */ + std::string isa; /** Instruction Set Assembly */ + std::string version; /** Description version */ + std::vector< std::string > author; /** List of authors of the description */ + std::vector< node_t > node; /** List of nodes */ +}; + +/** Parse a SoC description from a XML file, put it into <soc>. */ +bool parse_xml(const std::string& filename, soc_t& soc, error_context_t& error_ctx); +/** Write a SoC description to a XML file, overwriting it. A file can contain + * multiple Soc descriptions */ +bool produce_xml(const std::string& filename, const soc_t& soc, error_context_t& error_ctx); +/** Formula parser: try to parse and evaluate a formula with some variables */ +bool evaluate_formula(const std::string& formula, + const std::map< std::string, soc_word_t>& var, soc_word_t& result, + const std::string& loc, error_context_t& error_ctx); + +/** + * Convenience API to manipulate the format + * + * The idea is that *_ref_t objects are stable pointers: they stay valid even + * when the underlying soc changes. In particular: + * - modifying any structure data (except id fields) preserves all references + * - removing a structure invalidates all references pointing to this structure + * and its children + * - adding any structure preserves all references + * These references can be used to get pointers to the actual data + * of the representation when it needs to be read or write. + */ + +class soc_ref_t; +class node_ref_t; +class register_ref_t; +class field_ref_t; +class node_inst_t; + +/** SoC reference */ +class soc_ref_t +{ + soc_t *m_soc; /* pointer to the soc */ +public: + /** Builds an invalid reference */ + soc_ref_t(); + /** Builds a reference to a soc */ + soc_ref_t(soc_t *soc); + /** Checks whether this reference is valid */ + bool valid() const; + /** Returns a pointer to the soc */ + soc_t *get() const; + /** Returns a reference to the root node */ + node_ref_t root() const; + /** Returns a reference to the root node instance */ + node_inst_t root_inst() const; + /** Compare this reference to another */ + bool operator==(const soc_ref_t& r) const; + inline bool operator!=(const soc_ref_t& r) const { return !operator==(r); } +}; + +/** SoC node reference + * NOTE: the root soc node is presented as a node with empty path */ +class node_ref_t +{ + friend class soc_ref_t; + friend class node_inst_t; + soc_ref_t m_soc; /* reference to the soc */ + std::vector< soc_id_t > m_path; /* path from the root */ + + node_ref_t(soc_ref_t soc); + node_ref_t(soc_ref_t soc, const std::vector< soc_id_t >& path); +public: + /** Builds an invalid reference */ + node_ref_t(); + /** Check whether this reference is valid */ + bool valid() const; + /** Check whether this reference is the root node */ + bool is_root() const; + /** Returns a pointer to the node, or 0 if invalid or root */ + node_t *get() const; + /** Returns a reference to the soc */ + soc_ref_t soc() const; + /** Returns a reference to the parent node */ + node_ref_t parent() const; + /** Returns a reference to the register (which may be on a parent node) */ + register_ref_t reg() const; + /** Returns a list of references to the sub-nodes */ + std::vector< node_ref_t > children() const; + /** Returns a reference to a specific child */ + node_ref_t child(const std::string& name) const; + /** Returns the path of the node, as the list of node names from the root */ + std::vector< std::string > path() const; + /** Returns the name of the node */ + std::string name() const; + /** Compare this reference to another */ + bool operator==(const node_ref_t& r) const; + inline bool operator!=(const node_ref_t& r) const { return !operator==(r); } +}; + +/** SoC register reference */ +class register_ref_t +{ + friend class node_ref_t; + node_ref_t m_node; /* reference to the node owning the register */ + + register_ref_t(node_ref_t node); +public: + /** Builds an invalid reference */ + register_ref_t(); + /** Check whether this reference is valid/exists */ + bool valid() const; + /** Returns a pointer to the register, or 0 */ + register_t *get() const; + /** Returns a reference to the node containing the register */ + node_ref_t node() const; + /** Returns a list of references to the fields of the register */ + std::vector< field_ref_t > fields() const; + /** Returns a reference to a particular field */ + field_ref_t field(const std::string& name) const; + /** Compare this reference to another */ + bool operator==(const register_ref_t& r) const; + inline bool operator!=(const register_ref_t& r) const { return !operator==(r); } +}; + +/** SoC register field reference */ +class field_ref_t +{ + friend class register_ref_t; + register_ref_t m_reg; /* reference to the register */ + soc_id_t m_id; /* field name */ + + field_ref_t(register_ref_t reg, soc_id_t id); +public: + /** Builds an invalid reference */ + field_ref_t(); + /** Check whether this reference is valid/exists */ + bool valid() const; + /** Returns a pointer to the field, or 0 */ + field_t *get() const; + /** Returns a reference to the register containing the field */ + register_ref_t reg() const; + /** Compare this reference to another */ + bool operator==(const field_ref_t& r) const; + inline bool operator!=(const field_ref_t& r) const { return !operator==(r); } +}; + +/** SoC node instance + * NOTE: the root soc node is presented as a node with a single instance at 0 */ +class node_inst_t +{ + friend class node_ref_t; + friend class soc_ref_t; + node_ref_t m_node; /* reference to the node */ + std::vector< soc_id_t > m_id_path; /* list of instance IDs */ + std::vector< size_t > m_index_path; /* list of instance indexes */ + + node_inst_t(soc_ref_t soc); + node_inst_t(node_ref_t soc, const std::vector< soc_id_t >& path, + const std::vector< size_t >& indexes); +public: + /** Builds an invalid reference */ + node_inst_t(); + /** Check whether this instance is valid/exists */ + bool valid() const; + /** Returns a reference to the soc */ + soc_ref_t soc() const; + /** Returns a reference to the node */ + node_ref_t node() const; + /** Check whether this reference is the root node instance */ + bool is_root() const; + /** Returns a reference to the parent instance */ + node_inst_t parent() const; + /** Returns a pointer to the instance of the node, or 0 */ + instance_t *get() const; + /** Returns the address of this instance */ + soc_addr_t addr() const; + /** Returns an instance to a child of this node's instance. If the subnode + * instance is a range, the returned reference is invalid */ + node_inst_t child(const std::string& name) const; + /** Returns an instance to a child of this node's instance with a range index. + * If the subnode is not not a range or if the index is out of bounds, + * the returned reference is invalid */ + node_inst_t child(const std::string& name, size_t index) const; + /** Returns a list of all instances of subnodes of this node's instance */ + std::vector< node_inst_t > children() const; + /** Returns the name of the instance */ + std::string name() const; + /** Checks whether this instance is indexed */ + bool is_indexed() const; + /** Returns the index of the instance */ + size_t index() const; + /** Compare this reference to another */ + bool operator==(const node_inst_t& r) const; + inline bool operator!=(const node_inst_t& r) const { return !operator==(r); } +}; + +} // soc_desc + +#endif /* __SOC_DESC__ */ diff --git a/utils/regtools/include/soc_desc_v1.hpp b/utils/regtools/include/soc_desc_v1.hpp new file mode 100644 index 0000000000..33368e88d4 --- /dev/null +++ b/utils/regtools/include/soc_desc_v1.hpp @@ -0,0 +1,230 @@ +/*************************************************************************** + * __________ __ ___. + * Open \______ \ ____ ____ | | _\_ |__ _______ ___ + * Source | _// _ \_/ ___\| |/ /| __ \ / _ \ \/ / + * Jukebox | | ( <_> ) \___| < | \_\ ( <_> > < < + * Firmware |____|_ /\____/ \___ >__|_ \|___ /\____/__/\_ \ + * \/ \/ \/ \/ \/ + * $Id$ + * + * Copyright (C) 2012 by Amaury Pouly + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License + * as published by the Free Software Foundation; either version 2 + * of the License, or (at your option) any later version. + * + * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY + * KIND, either express or implied. + * + ****************************************************************************/ +#ifndef __SOC_DESC_V1__ +#define __SOC_DESC_V1__ + +#include <stdint.h> +#include <vector> +#include <list> +#include <string> +#include <map> + +/** + * These data structures represent the SoC register in a convenient way. + * The basic structure is the following: + * - each SoC has several devices + * - each device has a generic name, a list of {name,address} and several registers + * - each register has a generic name, a list of {name,address}, flags, + * several fields + * - each field has a name, a first and last bit position, can apply either + * to all addresses of a register or be specific to one only and has several values + * - each field value has a name and a value + * + * All addresses, values and names are relative to the parents. For example a field + * value BV_LCDIF_CTRL_WORD_LENGTH_18_BIT is represented has: + * - device LCDIF, register CTRL, field WORD_LENGTH, value 16_BIT + * The address of CTRL is related to the address of LCDIF, the value of 16_BIT + * ignores the position of the WORD_LENGTH field in the register. + */ + +namespace soc_desc_v1 +{ + +const size_t MAJOR_VERSION = 1; +const size_t MINOR_VERSION = 4; +const size_t REVISION_VERSION = 1; + +/** + * Typedef for SoC types: word, address and flags */ +typedef uint32_t soc_addr_t; +typedef uint32_t soc_word_t; +typedef uint32_t soc_reg_flags_t; + +/** SoC error gravity level */ +enum soc_error_level_t +{ + SOC_ERROR_WARNING, + SOC_ERROR_FATAL, +}; + +/** SoC description error */ +struct soc_error_t +{ + soc_error_level_t level; /// level (warning, fatal, ...) + std::string location; /// human description of the location + std::string message; /// message +}; + +/** SoC register generic formula */ +enum soc_reg_formula_type_t +{ + REG_FORMULA_NONE, /// register has no generic formula + REG_FORMULA_STRING, /// register has a generic formula represented by a string +}; + +/** <soc_reg_t>.<flags> values */ +const soc_reg_flags_t REG_HAS_SCT = 1 << 0; /// register SCT variants + +/** SoC register field named value */ +struct soc_reg_field_value_t +{ + std::string name; /// name of the value + soc_word_t value; /// numeric value + std::string desc; /// human description + + std::vector< soc_error_t > errors(bool recursive); +}; + +/** SoC register field */ +struct soc_reg_field_t +{ + std::string name; /// name of the field + std::string desc; /// human description + unsigned first_bit, last_bit; /// bit range of the field + + soc_reg_field_t():first_bit(0), last_bit(31) {} + + /** Return field bitmask in register */ + soc_word_t bitmask() const + { + // WARNING beware of the case where first_bit=0 and last_bit=31 + if(first_bit == 0 && last_bit == 31) + return 0xffffffff; + else + return ((1 << (last_bit - first_bit + 1)) - 1) << first_bit; + } + + /** Extract field value from register value */ + soc_word_t extract(soc_word_t reg_val) const + { + return (reg_val & bitmask()) >> first_bit; + } + + /** Replace the field value in a register value */ + soc_word_t replace(soc_word_t reg_val, soc_word_t field_val) const + { + return (reg_val & ~bitmask()) | ((field_val << first_bit) & bitmask()); + } + + bool is_reserved() const + { + return name.substr(0, 4) == "RSVD" || name.substr(0, 5) == "RSRVD"; + } + + /** Return field value index, or -1 if none */ + int find_value(soc_word_t v) const + { + for(size_t i = 0; i < value.size(); i++) + if(value[i].value == v) + return i; + return -1; + } + + std::vector< soc_reg_field_value_t > value; + + std::vector< soc_error_t > errors(bool recursive); +}; + +/** SoC register address */ +struct soc_reg_addr_t +{ + std::string name; /// actual register name + soc_addr_t addr; /// actual register address (relative to device) + + std::vector< soc_error_t > errors(bool recursive); +}; + +/** SoC register formula */ +struct soc_reg_formula_t +{ + enum soc_reg_formula_type_t type; + std::string string; /// for STRING + + std::vector< soc_error_t > errors(bool recursive); +}; + +/** SoC register */ +struct soc_reg_t +{ + std::string name; /// generic name (for multi registers) or actual name + std::string desc; /// human description + std::vector< soc_reg_addr_t > addr; /// instances of the registers + soc_reg_formula_t formula; /// formula for the instance addresses + soc_reg_flags_t flags; /// ORed value + + std::vector< soc_reg_field_t > field; + + std::vector< soc_error_t > errors(bool recursive); +}; + +/** Soc device address */ +struct soc_dev_addr_t +{ + std::string name; /// actual device name + soc_addr_t addr; + + std::vector< soc_error_t > errors(bool recursive); +}; + +/** SoC device */ +struct soc_dev_t +{ + std::string name; /// generic name (of multi devices) or actual name + std::string long_name; /// human friendly name + std::string desc; /// human description + std::string version; /// description version + std::vector< soc_dev_addr_t > addr; + + std::vector< soc_reg_t > reg; + + std::vector< soc_error_t > errors(bool recursive); +}; + +/** SoC */ +struct soc_t +{ + std::string name; /// codename (rockbox) + std::string desc; /// SoC name + + std::vector< soc_dev_t > dev; + + std::vector< soc_error_t > errors(bool recursive); +}; + +/** Parse a SoC description from a XML file, append it to <soc>. */ +bool parse_xml(const std::string& filename, soc_t& soc); +/** Write a SoC description to a XML file, overwriting it. A file can contain + * multiple Soc descriptions */ +bool produce_xml(const std::string& filename, const soc_t& soc); +/** Normalise a soc description by reordering elemnts so that: + * - devices are sorted by first name + * - registers are sorted by first address + * - fields are sorted by last bit + * - values are sorted by value */ +void normalize(soc_t& soc); +/** Formula parser: try to parse and evaluate a formula with some variables */ +bool evaluate_formula(const std::string& formula, + const std::map< std::string, soc_word_t>& var, soc_word_t& result, + std::string& error); + +} // soc_desc_v1 + +#endif /* __SOC_DESC_V1__ */
\ No newline at end of file |