[projmgr] Add device and board books to cbuild.yml (#1087)

Author: brondani

test/packs/ARM/RteTestBoard/0.1.0/ARM.RteTestBoard.pdsc

@@ -37,6 +37,8 @@
     </board>
     <board name="RteTest CM4 board" vendor="Keil" revision="Rev.C">
       <description>uVision Simulator</description>
+      <book category="overview" name="https://www.keil.arm.com/boards/" title="Development boards for application prototyping"/>
+      <book category="other" name="Documents/README.md" title="Guide" public="true"/>
       <mountedDevice    deviceIndex="0" Dvendor="ARM:82" Dname="RteTest_ARMCM4_FP"/>
       <compatibleDevice deviceIndex="0" Dvendor="ARM:82" Dname="RteTest_ARMCM4_NOFP"/>
       <algorithm name="Board/Flash/BoargAlgo1.FLM" start="0x00000000" size="0x00040000" default="1"/>

test/packs/ARM/RteTestBoard/0.1.0/Documents/README.md

@@ -0,0 +1 @@
+# Board documentation

tools/projmgr/include/ProjMgrWorker.h

@@ -211,6 +211,18 @@ struct LinkerContextItem {
   std::string script;
 };
 
+/**
+ * @brief book item containing
+ *        string name
+ *        string title
+ *        string category
+*/
+struct BookItem {
+  std::string name;
+  std::string title;
+  std::string category;
+};
+
 /**
  * @brief context type item containing
  *        list of all build types including mapped ones
@@ -273,6 +285,8 @@ struct ContextTypesItem {
  *        vector of dependent contexts
  *        map of layers descriptors from packs
  *        flag indicating the context needs a rebuild
+ *        vector of device books
+ *        vector of board books
 */
 struct ContextItem {
   CdefaultItem* cdefault = nullptr;
@@ -328,6 +342,8 @@ struct ContextItem {
   StrVec dependsOn;
   std::map<std::string, RteItem*> packLayers;
   bool needRebuild = false;
+  std::vector<BookItem> deviceBooks;
+  std::vector<BookItem> boardBooks;
 };
 
 /**

tools/projmgr/include/ProjMgrYamlParser.h

@@ -26,6 +26,7 @@ static constexpr const char* YAML_BASE = "base";
 static constexpr const char* YAML_BASE_DIR = "base-dir";
 static constexpr const char* YAML_BASE_NAME = "base-name";
 static constexpr const char* YAML_BOARD = "board";
+static constexpr const char* YAML_BOARD_BOOKS = "board-books";
 static constexpr const char* YAML_BOARD_PACK = "board-pack";
 static constexpr const char* YAML_BRANCH_PROTECTION = "branch-protection";
 static constexpr const char* YAML_BUILD = "build";
@@ -72,6 +73,7 @@ static constexpr const char* YAML_DELPATH = "del-path";
 static constexpr const char* YAML_DEPENDS_ON = "depends-on";
 static constexpr const char* YAML_DESCRIPTION = "description";
 static constexpr const char* YAML_DEVICE = "device";
+static constexpr const char* YAML_DEVICE_BOOKS = "device-books";
 static constexpr const char* YAML_DEVICE_PACK = "device-pack";
 static constexpr const char* YAML_DOWNLOAD_URL = "download-url";
 static constexpr const char* YAML_DSP = "dsp";
@@ -170,6 +172,7 @@ static constexpr const char* YAML_TARGETTYPE = "target-type";
 static constexpr const char* YAML_TARGETTYPES = "target-types";
 static constexpr const char* YAML_TRUSTZONE = "trustzone";
 static constexpr const char* YAML_CORE = "core";
+static constexpr const char* YAML_TITLE = "title";
 static constexpr const char* YAML_TYPE = "type";
 static constexpr const char* YAML_UNDEFINE = "undefine";
 static constexpr const char* YAML_UPDATE = "update";

tools/projmgr/schemas/common.schema.json

@@ -19,6 +19,21 @@
       "type": "string",
       "pattern": "^([^\\.\\+]+|[^\\.\\+]*\\.[a-zA-Z0-9_-]{1,32}(\\+[a-zA-Z0-9_-]{1,32})|[^\\.\\+]*\\+[a-zA-Z0-9_-]{1,32}(\\.[a-zA-Z0-9_-]{1,32})?)$"
     },
+    "BooksType": {
+      "type": "array",
+      "uniqueItems": true,
+      "minItems": 1,
+      "items": { "$ref": "#/definitions/BookType" }
+    },
+    "BookType": {
+      "type": "object",
+      "properties": {
+        "name":     { "type": "string" },
+        "title":    { "type": "string" },
+        "category": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
     "ArrayOfContextMapAlternativeContext": {
       "type": "array",
       "uniqueItems": true,
@@ -1058,8 +1073,10 @@
         "compiler":          { "$ref": "#/definitions/CompilerType" },
         "board":             { "$ref": "#/definitions/BoardType" },
         "board-pack":        { "$ref": "#/definitions/PackID" },
+        "board-books":       { "$ref": "#/definitions/BooksType" },
         "device":            { "$ref": "#/definitions/DeviceType" },
         "device-pack":       { "$ref": "#/definitions/PackID" },
+        "device-books":      { "$ref": "#/definitions/BooksType" },
         "processor":         { "$ref": "#/definitions/BuildProcessorType" },
         "packs":             { "$ref": "#/definitions/BuildPacksType" },
         "optimize":          { "$ref": "#/definitions/OptimizeType" },

tools/projmgr/src/ProjMgrWorker.cpp

@@ -1239,6 +1239,17 @@ bool ProjMgrWorker::ProcessDevice(ContextItem& context) {
     if (context.boardPack) {
       context.packages.insert({ context.boardPack->GetID(), context.boardPack });
       context.variables[RteConstants::AS_BPACK] = context.boardPack->GetAbsolutePackagePath();
+
+      Collection<RteItem*> books;
+      books = matchedBoard->GetChildrenByTag("book", books);
+      context.boardBooks.clear();
+      for (const auto& book : books) {
+        BookItem bookItem;
+        bookItem.name = book->GetDocFile();
+        bookItem.title = book->GetAttribute("title");
+        bookItem.category = book->GetAttribute("category");
+        context.boardBooks.push_back(bookItem);
+      }
     }
     context.targetAttributes["Bname"]    = matchedBoard->GetName();
     context.targetAttributes["Bvendor"]  = matchedBoard->GetVendorName();
@@ -1385,6 +1396,14 @@ bool ProjMgrWorker::ProcessDevice(ContextItem& context) {
   if (context.devicePack) {
     context.packages.insert({ context.devicePack->GetID(), context.devicePack });
     context.variables[RteConstants::AS_DPACK] = context.devicePack->GetAbsolutePackagePath();
+    const auto& books = matchedDevice->GetEffectiveProperties("book", deviceItem.pname);
+    context.deviceBooks.clear();
+    for (const auto& book : books) {
+      BookItem bookItem;
+      bookItem.name = book->GetDocFile();
+      bookItem.title = book->GetAttribute("title");
+      context.deviceBooks.push_back(bookItem);
+    }
   }
   GetDeviceItem(context.device, context.deviceItem);
   context.variables[RteConstants::AS_DNAME] = context.deviceItem.name;

tools/projmgr/src/ProjMgrYamlEmitter.cpp

@@ -69,6 +69,7 @@ class ProjMgrYamlCbuild : public ProjMgrYamlBase {
   void SetMiscNode(YAML::Node miscNode, const MiscItem& misc);
   void SetMiscNode(YAML::Node miscNode, const vector<MiscItem>& misc);
   void SetDefineNode(YAML::Node node, const vector<string>& vec);
+  void SetBooksNode(YAML::Node node, const std::vector<BookItem>& books, const std::string& dir);
   const bool m_ignoreRteFileMissing;
 };
 
@@ -464,11 +465,13 @@ void ProjMgrYamlCbuild::SetContextNode(YAML::Node contextNode, const ContextItem
     if (context->boardPack != nullptr) {
       SetNodeValue(contextNode[YAML_BOARD_PACK], context->boardPack->GetID());
     }
+    SetBooksNode(contextNode[YAML_BOARD_BOOKS], context->boardBooks, context->directories.cbuild);
   }
   SetNodeValue(contextNode[YAML_DEVICE], context->device);
   if (context->devicePack != nullptr) {
     SetNodeValue(contextNode[YAML_DEVICE_PACK], context->devicePack->GetID());
   }
+  SetBooksNode(contextNode[YAML_DEVICE_BOOKS], context->deviceBooks, context->directories.cbuild);
   SetProcessorNode(contextNode[YAML_PROCESSOR], context->targetAttributes);
   SetPacksNode(contextNode[YAML_PACKS], context);
   SetControlsNode(contextNode, context, context->controls.processed);
@@ -869,6 +872,16 @@ void ProjMgrYamlCbuild::SetControlsNode(YAML::Node node, const ContextItem* cont
   }
 }
 
+void ProjMgrYamlCbuild::SetBooksNode(YAML::Node node, const std::vector<BookItem>& books, const std::string& dir) {
+  for (const auto& book : books) {
+    YAML::Node bookNode;
+    SetNodeValue(bookNode[YAML_NAME], FormatPath(book.name, dir));
+    SetNodeValue(bookNode[YAML_TITLE], book.title);
+    SetNodeValue(bookNode[YAML_CATEGORY], book.category);
+    node.push_back(bookNode);
+  }
+}
+
 void ProjMgrYamlCbuild::SetProcessorNode(YAML::Node node, const map<string, string>& targetAttributes) {
   for (const auto& [rteKey, yamlKey]: RteConstants::DeviceAttributesKeys) {
     if (targetAttributes.find(rteKey) != targetAttributes.end()) {

tools/projmgr/test/data/ExternalGenerator/ref/MultiCore/core0.Debug+MultiCore.cbuild-gen.yml

@@ -8,6 +8,9 @@ build-gen:
   compiler: AC6
   device: RteTest_ARMCM0_Dual:cm0_core0
   device-pack: ARM::[email protected]
+  device-books:
+    - name: http://infocenter.arm.com/help/topic/com.arm.doc.dui0497a/index.html
+      title: Cortex-M0 Device Generic Users Guide
   processor:
     fpu: off
     core: Cortex-M0

tools/projmgr/test/data/ExternalGenerator/ref/MultiCore/core1.Debug+MultiCore.cbuild-gen.yml

@@ -8,6 +8,9 @@ build-gen:
   compiler: AC6
   device: RteTest_ARMCM0_Dual:cm0_core1
   device-pack: ARM::[email protected]
+  device-books:
+    - name: http://infocenter.arm.com/help/topic/com.arm.doc.dui0497a/index.html
+      title: Cortex-M0 Device Generic Users Guide
   processor:
     fpu: off
     core: Cortex-M0

tools/projmgr/test/data/ExternalGenerator/ref/SingleCore/single-core.Debug+Board.cbuild.yml

@@ -6,8 +6,18 @@ build:
   compiler: AC6
   board: RteTest CM4 board
   board-pack: ARM::[email protected]
+  board-books:
+    - name: https://www.keil.arm.com/boards/
+      title: Development boards for application prototyping
+      category: overview
+    - name: ${CMSIS_PACK_ROOT}/ARM/RteTestBoard/0.1.0/Documents/README.md
+      title: Guide
+      category: other
   device: RteTest_ARMCM4_FP
   device-pack: ARM::[email protected]
+  device-books:
+    - name: http://infocenter.arm.com/help/topic/com.arm.doc.dui0553a/index.html
+      title: Cortex-M4 Device Generic Users Guide
   processor:
     fpu: sp
     core: Cortex-M4