[spiflash] Update internal stringdocs to Doxygen format.
Signed-off-by: Miguel Osorio <miguelosorio@google.com>
diff --git a/sw/host/spiflash/ftdi_spi_interface.cc b/sw/host/spiflash/ftdi_spi_interface.cc
index 7c9b44d..f3c4d11 100644
--- a/sw/host/spiflash/ftdi_spi_interface.cc
+++ b/sw/host/spiflash/ftdi_spi_interface.cc
@@ -24,19 +24,22 @@
namespace spiflash {
namespace {
+/** FTDI MPSSE GPIO Mappings */
enum FtdiGpioMapping {
- // SRST_N reset.
+ /** SRST_N reset. */
kGpioJtagSrstN = GPIOL1,
- // JTAG SPI_N select signal.
+ /** JTAG SPI_N select signal. */
kGpioJtagSpiN = GPIOL2,
- // Bootstrap pin.
+ /** Bootstrap pin. */
kBootstrapH = GPIOL3,
};
-// Resets the target to go back to boot_rom. Assumes boot_rom will enter
-// bootstrap mode.
+/**
+ * Resets the target to go back to boot_rom. Assumes boot_rom will enter
+ * bootstrap mode.
+ */
void ResetTarget(struct mpsse_context *ctx) {
// Set bootstrap pin high
PinHigh(ctx, kBootstrapH);
@@ -54,8 +57,10 @@
}
} // namespace
-// Wrapper struct used to hide mpsse_context since incomplete C struct
-// declarations don't play in forward declarations.
+/**
+ * Wrapper struct used to hide mpsse_context since incomplete C struct
+ * declarations don't play in forward declarations.
+ */
struct MpsseHandle {
struct mpsse_context *ctx;
diff --git a/sw/host/spiflash/spiflash.cc b/sw/host/spiflash/spiflash.cc
index 284759b..54cea65 100644
--- a/sw/host/spiflash/spiflash.cc
+++ b/sw/host/spiflash/spiflash.cc
@@ -33,23 +33,25 @@
Verilator Options:
[--verilator=filehandle] Enables Verilator mode with SPI filehandle.)R";
-// SPI flash configuration options.
+/** SPI flash configuration options. */
struct SpiFlashOpts {
- // Input file in binary format.
+ /** Input file in binary format. */
std::string input;
- // Target SPI device handle.
+ /** Target SPI device handle. */
std::string target;
- // Set to true to target Verilator environment.
+ /** Set to true to target Verilator environment. */
bool verilator = false;
- // FTDI configuration options.
+ /** FTDI configuration options. */
FtdiSpiInterface::Options ftdi_options;
};
-// Get |filename| contents and store them in |contents|. Using std::string for
-// |filename| because underlying open file call requires a C string.
+/**
+ * Get `filename` contents and store them in `contents`. Using std::string for
+ * `filename` because underlying open file call requires a C string.
+ */
bool GetFileContents(const std::string &filename, std::string *contents) {
assert(contents);
std::ifstream file_stream(filename, std::ios::in | std::ios::binary);
@@ -65,15 +67,20 @@
return true;
}
-// Prints help menu.
+/** Print help menu. */
static void PrintUsage(int argc, char *argv[]) {
assert(argc >= 1);
std::cerr << argv[0] << kUsageString << std::endl;
}
-// Extracts the vendor and product ID from `device_id` and stores the values
-// in `options`. Returns true on success.
-// This function may throw exceptions.
+/*
+ * Extract the vendor and product ID from `device_id` and store the values
+ * in `options`.
+ *
+ * This function may throw exceptions.
+ *
+ * @return true on success.
+ */
bool ParseDeviceID(const std::string &device_id, SpiFlashOpts *options) {
size_t token_pos = device_id.find(':');
if (token_pos == std::string::npos) {
@@ -94,7 +101,9 @@
return true;
}
-// Parse command line arguments and store results in |options|.
+/*
+ * Parse command line arguments and store results in `options`.
+ */
bool ParseArgs(int argc, char **argv, SpiFlashOpts *options) {
assert(options);
const struct option long_options[] = {
diff --git a/sw/host/spiflash/updater.cc b/sw/host/spiflash/updater.cc
index 1d07590..1a7f93f 100644
--- a/sw/host/spiflash/updater.cc
+++ b/sw/host/spiflash/updater.cc
@@ -4,18 +4,22 @@
#include "sw/host/spiflash/updater.h"
-#include <assert.h>
-
#include <algorithm>
+#include <assert.h>
namespace opentitan {
namespace spiflash {
namespace {
-// Populates frame |f| with |frame_number|, |code_offset|, and frame data
-// starting at |code_offset| from |code| buffer. Calculates SHA256 hash of
-// frame payload and it stores it in the frame header. Returns the number of
-// bytes loaded into the frame.
+/**
+ * Populate target frame `f`.
+ *
+ * Populates frame `f` with `frame_number`, `code_offset`, and frame data
+ * starting at `code_offset` from `code` buffer. Calculates SHA256 hash of
+ * frame payload and it stores it in the frame header.
+ *
+ * @return the number of bytes loaded into the frame.
+ */
uint32_t Populate(uint32_t frame_number, uint32_t code_offset,
const std::string &code, Frame *f) {
assert(f);
@@ -34,7 +38,9 @@
return copy_size;
}
-// Calculate hash for frame |f| and store it in the frame header hash field.
+/**
+ * Calculate hash for frame `f` and store it in the frame header hash field.
+ */
void HashFrame(Frame *f) {
SHA256_CTX sha256;
SHA256_Init(&sha256);
diff --git a/sw/host/spiflash/verilator_spi_interface.cc b/sw/host/spiflash/verilator_spi_interface.cc
index 6954d64..5cd9e6a 100644
--- a/sw/host/spiflash/verilator_spi_interface.cc
+++ b/sw/host/spiflash/verilator_spi_interface.cc
@@ -18,11 +18,11 @@
namespace spiflash {
namespace {
-// Required delay to synchronize transactions with simulation environment.
// TODO: If transmission is not successful, adapt this by an argument.
+/** Required delay to synchronize transactions with simulation environment. */
constexpr int kWriteReadDelay = 20000000;
-// Configure |fd| as a serial port with baud rate 9600.
+/** Configure `fd` as a serial port with baud rate 9600. */
bool SetTermOpts(int fd) {
struct termios options;
if (tcgetattr(fd, &options) != 0) {
@@ -42,9 +42,11 @@
return true;
}
-// Returns file handle on success, or nullopt on failure. This function
-// configures de file handle to behave as a serial port with baud rate 9600,
-// which is the baud rate supported by Verilator.
+/**
+ * Returns file handle on success, or -1 on failure. This function
+ * configures de file handle to behave as a serial port with baud rate 9600,
+ * which is the baud rate supported by Verilator.
+ */
int OpenDevice(const std::string &filename) {
int fd = open(filename.c_str(), O_RDWR | O_NOCTTY | O_NONBLOCK | O_CLOEXEC);
if (fd < 0) {
@@ -58,8 +60,10 @@
return fd;
}
-// Reads |size| bytes into |rx| buffer from |fd|. Returns the number of bytes
-// read.
+/**
+ * Reads `size` bytes into `rx` buffer from `fd`. Returns the number of bytes
+ * read.
+ */
size_t ReadBytes(int fd, uint8_t *rx, size_t size) {
size_t bytes_read = 0;
while (bytes_read != size) {
