xc7frames2bit: add comments to new utility functions

Signed-off-by: Tomasz Michalak <tmichalak@antmicro.com>

lib/include/prjxray/xilinx/xc7series/frames.h

@@ -12,18 +12,29 @@
 namespace prjxray {
 namespace xilinx {
 namespace xc7series {
+
+// Contains frame information which is used for the generation
+// of the configuration package that is used in bitstream generation.
 class Frames {
        public:
 	typedef std::vector<uint32_t> FrameData;
 	typedef std::map<FrameAddress, FrameData> Frames2Data;
 
+	// Reads the contents of the frames file and populates
+	// the Frames container.
 	int readFrames(const std::string& frm_file_str);
+
+	// Adds empty frames that are present in the tilegrid of a specific part
+	// but are missing in the current frames container.
 	void addMissingFrames(const absl::optional<Part>& part);
+
+	// Returns the map with frame addresses and corresponding data
 	Frames2Data& getFrames();
 
        private:
 	Frames2Data frames_data_;
 
+	// Updates the ECC information in the frame.
 	void updateECC(FrameData& data);
 	uint32_t calculateECC(const FrameData& data);
 };

lib/include/prjxray/xilinx/xc7series/utils.h

@@ -14,14 +14,31 @@ using PacketData = std::vector<uint32_t>;
 using BitstreamHeader = std::vector<uint8_t>;
 using ConfigurationPackage = std::vector<std::unique_ptr<ConfigurationPacket>>;
 
+// Returns the payload for a type 2 packet.
+// Type 2 packets can have the payload length of more than the 11 bits available
+// for type 1 packets.
 PacketData createType2ConfigurationPacketData(const Frames::Frames2Data& frames,
                                               absl::optional<Part>& part);
+
+// Creates the complete configuration package that is
+// then used by the bitstream writer to generate the bitstream file. The package
+// forms a sequence suitable for xilinx 7-series devices. The programming
+// sequence is taken from
+// https://www.kc8apf.net/2018/05/unpacking-xilinx-7-series-bitstreams-part-2/
 void createConfigurationPackage(ConfigurationPackage& out_packets,
                                 const PacketData& packet_data,
                                 absl::optional<Part>& part);
+
+// Creates a Xilinx bit header which is mostly a
+// Tag-Length-Value(TLV) format documented here:
+// http://www.fpga-faq.com/FAQ_Pages/0026_Tell_me_about_bit_files.htm
 BitstreamHeader createBitistreamHeader(const std::string& part_name,
                                        const std::string& frames_file_name,
                                        const std::string& generator_name);
+
+// Writies out the complete bitstream for a 7-series
+// Xilinx FPGA based on the Configuration Package which holds the complete
+// programming sequence.
 int writeBitstream(const ConfigurationPackage& packets,
                    const std::string& part_name,
                    const std::string& frames_file,

lib/xilinx/xc7series/utils.cc

@@ -42,8 +42,6 @@ PacketData createType2ConfigurationPacketData(const Frames::Frames2Data& frames,
 void createConfigurationPackage(ConfigurationPackage& out_packets,
                                 const PacketData& packet_data,
                                 absl::optional<Part>& part) {
-	// The programming sequence is taken from
-	// https://www.kc8apf.net/2018/05/unpacking-xilinx-7-series-bitstreams-part-2/
 	// Initialization sequence
 	out_packets.emplace_back(new NopPacket());
 	out_packets.emplace_back(new ConfigurationPacketWithPayload<1>(
@@ -169,7 +167,6 @@ void createConfigurationPackage(ConfigurationPackage& out_packets,
 	}
 }
 
-// Xilinx BIT header
 BitstreamHeader createBitstreamHeader(const std::string& part_name,
                                       const std::string& frames_file_name,
                                       const std::string& generator_name) {