From 271c2e6dc524d39f20181304bda58d6e7ad65529 Mon Sep 17 00:00:00 2001 From: darshan jain Date: Fri, 22 Mar 2024 11:36:43 +0530 Subject: [PATCH] doc: backends: Add Doxygen-style documentation for BMV2 JSONObjects 1. Class Overview: - Provides an overview of the JsonObjects class, explaining its purpose and namespace. 2. Constructor: - Documented the constructor `JsonObjects::JsonObjects()` with a brief description of its purpose and initialization of member variables. 3. Member Functions: - Each member function of the JsonObjects class is documented with detailed descriptions. - Special attention is given to functions with complex logic or multiple parameters to ensure detailed documentation. Overall, this commit enhances the understanding of the BMV2 JSON Objects class by providing a Doxygen-style documentation. --- backends/bmv2/common/JsonObjects.cpp | 169 ++++++++++++++++++++++++--- 1 file changed, 155 insertions(+), 14 deletions(-) diff --git a/backends/bmv2/common/JsonObjects.cpp b/backends/bmv2/common/JsonObjects.cpp index 08e1119fd2b..73e6df6ad3a 100644 --- a/backends/bmv2/common/JsonObjects.cpp +++ b/backends/bmv2/common/JsonObjects.cpp @@ -19,11 +19,20 @@ limitations under the License. #include "helpers.h" #include "lib/json.h" +/** + * @file JsonObjects.h + * + * @brief Declaration of the JsonObjects class. + */ namespace BMV2 { const int JSON_MAJOR_VERSION = 2; const int JSON_MINOR_VERSION = 23; +/** + * @brief Constructs a new JsonObjects instance. + * Initializes the top-level JsonObject and other member arrays. + */ JsonObjects::JsonObjects() { toplevel = new Util::JsonObject(); meta = new Util::JsonObject(); @@ -52,6 +61,11 @@ JsonObjects::JsonObjects() { field_aliases = insert_array_field(toplevel, "field_aliases"); } +/** + * @brief Retrieves the contents of a field list identified by its ID. + * @param id The ID of the field list. + * @return A pointer to the JsonArray containing the field list's elements, or nullptr if not found. + */ Util::JsonArray *JsonObjects::get_field_list_contents(unsigned id) const { for (auto e : *field_lists) { auto obj = e->to(); @@ -63,6 +77,12 @@ Util::JsonArray *JsonObjects::get_field_list_contents(unsigned id) const { return nullptr; } +/** + * @brief Finds an object in a JSON array by its name. + * @param array The JSON array to search in. + * @param name The name of the object to find. + * @return A pointer to the JsonObject with the specified name, or nullptr if not found. + */ Util::JsonObject *JsonObjects::find_object_by_name(Util::JsonArray *array, const cstring &name) { for (auto e : *array) { auto obj = e->to(); @@ -74,27 +94,45 @@ Util::JsonObject *JsonObjects::find_object_by_name(Util::JsonArray *array, const return nullptr; } -/// Insert a json array to a parent object under key 'name'. +/** + * @brief Inserts a JSON array into a parent object under a specified key. + * @param parent The parent JsonObject to insert the array into. + * @param name The key under which the array will be inserted. + * @return A pointer to the newly created JSON array. + */ Util::JsonArray *JsonObjects::insert_array_field(Util::JsonObject *parent, cstring name) { auto result = new Util::JsonArray(); parent->emplace(name, result); return result; } -/// Append a json array to a parent json array. +/** + * @brief Appends a JSON array to a parent JSON array. + * @param parent The parent JsonArray to which the array will be appended. + * @return A pointer to the newly created JSON array. + */ Util::JsonArray *JsonObjects::append_array(Util::JsonArray *parent) { auto result = new Util::JsonArray(); parent->append(result); return result; } -/// Insert a json array named 'parameters' in a parent json object. +/** + * @brief Creates a JSON array named 'parameters' in a parent JsonObject. + * @param object The parent JsonObject in which the 'parameters' array will be created. + * @return A pointer to the newly created JSON array. + */ Util::JsonArray *JsonObjects::create_parameters(Util::JsonObject *object) { return insert_array_field(object, "parameters"); } +/** + * @brief Adds program information to the top-level JsonObject. + * @param name The name of the program. + */ void JsonObjects::add_program_info(const cstring &name) { toplevel->emplace("program", name); } +///@brief Adds meta information to the JsonObject. void JsonObjects::add_meta_info() { static constexpr int version_major = JSON_MAJOR_VERSION; static constexpr int version_minor = JSON_MINOR_VERSION; @@ -106,12 +144,13 @@ void JsonObjects::add_meta_info() { } /** - * Create a header type in json. + * @brief Create a header type in json. * @param name header name * @param type header type * @param max_length maximum length for a header with varbit fields; * if 0 header does not contain varbit fields * @param fields a JsonArray for the fields in the header + * @return The ID of the newly created header type. */ unsigned JsonObjects::add_header_type(const cstring &name, Util::JsonArray *&fields, unsigned max_length) { @@ -136,6 +175,12 @@ unsigned JsonObjects::add_header_type(const cstring &name, Util::JsonArray *&fie return id; } +/** + * @brief Creates a union type in JSON. + * @param name The name of the union type. + * @param fields A JsonArray containing the headers in the union type. + * @return The ID of the newly created union type. + */ unsigned JsonObjects::add_union_type(const cstring &name, Util::JsonArray *&fields) { std::string sname(name, name.size()); auto it = union_type_id.find(sname); @@ -155,7 +200,11 @@ unsigned JsonObjects::add_union_type(const cstring &name, Util::JsonArray *&fiel return id; } -/// Create a header type with empty field list. +/** + * @brief Creates a header type in JSON with an empty field list. + * @param name The name of the header type. + * @return The ID of the newly created header type. + */ unsigned JsonObjects::add_header_type(const cstring &name) { std::string sname(name, name.size()); auto header_type_id_it = header_type_id.find(sname); @@ -173,8 +222,11 @@ unsigned JsonObjects::add_header_type(const cstring &name) { return id; } -/// Create a set of fields to an existing header type. -/// The header type is decribed by the name. +/** + * @brief Adds a set of fields to an existing header type. + * @param name The name of the header type. + * @param field The JsonArray containing the fields to add. + */ void JsonObjects::add_header_field(const cstring &name, Util::JsonArray *&field) { CHECK_NULL(field); Util::JsonObject *headerType = find_object_by_name(header_types, name); @@ -183,7 +235,12 @@ void JsonObjects::add_header_field(const cstring &name, Util::JsonArray *&field) fields->append(field); } -/// Create a header instance in json. +/** + * @brief Creates a header instance in JSON. + * @param type The type of the header. + * @param name The name of the header instance. + * @return The ID of the newly created header instance. + */ unsigned JsonObjects::add_header(const cstring &type, const cstring &name) { auto header = new Util::JsonObject(); unsigned id = BMV2::nextId("headers"); @@ -197,7 +254,13 @@ unsigned JsonObjects::add_header(const cstring &type, const cstring &name) { return id; } -/// Create a header_union instance in json. +/** + * @brief Creates a header union instance in JSON. + * @param type The type of the header union. + * @param headers A JsonArray containing the header IDs in the union. + * @param name The name of the header union instance. + * @return The ID of the newly created header union instance. + */ unsigned JsonObjects::add_union(const cstring &type, Util::JsonArray *&headers, const cstring &name) { auto u = new Util::JsonObject(); @@ -212,6 +275,12 @@ unsigned JsonObjects::add_union(const cstring &type, Util::JsonArray *&headers, return id; } +/** + * @brief Creates a metadata header instance in JSON. + * @param type The type of the metadata. + * @param name The name of the metadata header instance. + * @return The ID of the newly created metadata header instance. + */ unsigned JsonObjects::add_metadata(const cstring &type, const cstring &name) { auto header = new Util::JsonObject(); unsigned id = BMV2::nextId("headers"); @@ -225,6 +294,13 @@ unsigned JsonObjects::add_metadata(const cstring &type, const cstring &name) { return id; } +/** + * @brief Adds a header stack to the JSON representation. + * @param type The type of the headers in the stack. + * @param name The name of the header stack. + * @param size The size of the header stack. + * @param ids The vector of header IDs in the stack. + */ void JsonObjects::add_header_stack(const cstring &type, const cstring &name, const unsigned size, const std::vector &ids) { auto stack = new Util::JsonObject(); @@ -241,6 +317,13 @@ void JsonObjects::add_header_stack(const cstring &type, const cstring &name, con header_stacks->append(stack); } +/** + * @brief Adds a header union stack to the JSON representation. + * @param type The type of the header unions in the stack. + * @param name The name of the header union stack. + * @param size The size of the header union stack. + * @param ids The vector of header union IDs in the stack. + */ void JsonObjects::add_header_union_stack(const cstring &type, const cstring &name, const unsigned size, const std::vector &ids) { auto stack = new Util::JsonObject(); @@ -257,15 +340,23 @@ void JsonObjects::add_header_union_stack(const cstring &type, const cstring &nam header_union_stacks->append(stack); } -/// Add an error to json. +/** + * @brief Adds an error to the JSON representation. + * @param name The name of the error. + * @param type The type of the error. + */ void JsonObjects::add_error(const cstring &name, const unsigned type) { auto arr = append_array(errors); arr->append(name); arr->append(type); } -/// Add a single enum entry to json. -/// A enum entry is identified with { enum_name, entry_name, entry_value } +/** + * @brief Adds a single enum entry to the JSON representation. + * @param enum_name The name of the enum. + * @param entry_name The name of the enum entry. + * @param entry_value The value of the enum entry. + */ void JsonObjects::add_enum(const cstring &enum_name, const cstring &entry_name, const unsigned entry_value) { // look up enum in json by name @@ -290,6 +381,11 @@ void JsonObjects::add_enum(const cstring &enum_name, const cstring &entry_name, } } +/** + * @brief Adds a parser to the JSON representation. + * @param name The name of the parser. + * @return The ID of the newly created parser. + */ unsigned JsonObjects::add_parser(const cstring &name) { auto parser = new Util::JsonObject(); unsigned id = BMV2::nextId("parser"); @@ -304,8 +400,12 @@ unsigned JsonObjects::add_parser(const cstring &name) { return id; } -/// insert parser state into a parser identified by parser_id -/// return the id of the parser state +/** + * @brief Adds a parser state to an existing parser in the JSON representation. + * @param parser_id The ID of the parser. + * @param state_name The name of the parser state. + * @return The ID of the newly created parser state. + */ unsigned JsonObjects::add_parser_state(const unsigned parser_id, const cstring &state_name) { if (map_parser.find(parser_id) == map_parser.end()) BUG("parser %1% not found.", parser_id); auto parser = map_parser[parser_id]; @@ -326,6 +426,11 @@ unsigned JsonObjects::add_parser_state(const unsigned parser_id, const cstring & return state_id; } +/** + * @brief Adds a parser transition to an existing parser state in the JSON representation. + * @param state_id The ID of the parser state. + * @param transition The transition to add. + */ void JsonObjects::add_parser_transition(const unsigned state_id, Util::IJson *transition) { if (map_parser_state.find(state_id) == map_parser_state.end()) BUG("parser state %1% not found.", state_id); @@ -337,6 +442,11 @@ void JsonObjects::add_parser_transition(const unsigned state_id, Util::IJson *tr transitions->append(trans); } +/** + * @brief Adds a parser operation to an existing parser state in the JSON representation. + * @param state_id The ID of the parser state. + * @param op The operation to add. + */ void JsonObjects::add_parser_op(const unsigned state_id, Util::IJson *op) { if (map_parser_state.find(state_id) == map_parser_state.end()) BUG("parser state %1% not found.", state_id); @@ -346,6 +456,11 @@ void JsonObjects::add_parser_op(const unsigned state_id, Util::IJson *op) { statements->append(op); } +/** + * @brief Adds a parser transition key to an existing parser state in the JSON representation. + * @param state_id The ID of the parser state. + * @param newKey The new transition key to add. + */ void JsonObjects::add_parser_transition_key(const unsigned state_id, Util::IJson *newKey) { if (map_parser_state.find(state_id) != map_parser_state.end()) { auto state = map_parser_state[state_id]; @@ -358,6 +473,12 @@ void JsonObjects::add_parser_transition_key(const unsigned state_id, Util::IJson } } +/** + * @brief Adds a parse vset to the JSON representation. + * @param name The name of the parse vset. + * @param bitwidth The compressed bit width of the parse vset. + * @param size The maximum size of the parse vset. + */ void JsonObjects::add_parse_vset(const cstring &name, const unsigned bitwidth, const big_int &size) { auto parse_vset = new Util::JsonObject(); @@ -369,6 +490,13 @@ void JsonObjects::add_parse_vset(const cstring &name, const unsigned bitwidth, parse_vsets->append(parse_vset); } +/** + * @brief Adds an action to the JSON representation. + * @param name The name of the action. + * @param params The runtime data parameters of the action. + * @param body The primitives body of the action. + * @return The ID of the newly created action. + */ unsigned JsonObjects::add_action(const cstring &name, Util::JsonArray *¶ms, Util::JsonArray *&body) { CHECK_NULL(params); @@ -383,6 +511,13 @@ unsigned JsonObjects::add_action(const cstring &name, Util::JsonArray *¶ms, return id; } +/** + * @brief Adds an extern attribute to the JSON representation. + * @param name The name of the attribute. + * @param type The type of the attribute. + * @param value The value of the attribute. + * @param attributes The attributes array to add the new attribute to. + */ void JsonObjects::add_extern_attribute(const cstring &name, const cstring &type, const cstring &value, Util::JsonArray *attributes) { auto attr = new Util::JsonObject(); @@ -392,6 +527,12 @@ void JsonObjects::add_extern_attribute(const cstring &name, const cstring &type, attributes->append(attr); } +/** + * @brief Adds an extern instance to the JSON representation. + * @param name The name of the extern instance. + * @param type The type of the extern instance. + * @param attributes The attributes array of the extern instance. + */ void JsonObjects::add_extern(const cstring &name, const cstring &type, Util::JsonArray *attributes) { auto extn = new Util::JsonObject();