Finished the documentation on the SDR module and minor bug fixed.

[pes-rpp/rpp-lib.git] / rpp / include / rpp / sdr.h

diff --git a/rpp/include/rpp/sdr.h b/rpp/include/rpp/sdr.h
index edb50c1f3d0efade62a5f3bce4701b967a604eb3..1d205c9e5d85fc74a838469aca48f8e991a63094 100644 (file)
--- a/rpp/include/rpp/sdr.h
+++ b/rpp/include/rpp/sdr.h
@@ -12,11 +12,19 @@
 #ifndef __RPP_SDR_H
 #define __RPP_SDR_H
 
+/**
+ * SDRAM start address on RPP board.
+ */
+#define RPP_SDR_ADDR_START 0x80000000U
+
+/**
+ * SDRAM end address on RPP board.
+ */
+#define RPP_SDR_ADDR_END   0x83FFFFFFU
 // Note : 0x83FFFFFF − 0x80000000 + 1 = 67108864 addresses
 //        One address per byte
 //        67108864 bytes = 65536 Kbytes = 64 Mbytes
-#define RPP_SDR_ADDR_START 0x80000000U
-#define RPP_SDR_ADDR_END   0x83FFFFFFU
+
 
 /**
  * SDR module initialization.
@@ -27,19 +35,90 @@
  */
 int8_t rpp_sdr_init();
 
-// Enable/Disable logging
+
+/**
+ * Configure SD-RAM logging.
+ *
+ * This function will enable or disable logging on application. Note that when
+ * logging is enabled a command processor task which uses the SCI for user I/O
+ * is spawned. This command processor might conflict with user application if it
+ * also uses the SCI for user I/O.
+ *
+ * @param[in] enable    Enable/Disable logging on application.
+ *
+ * @return SUCCESS if was logging successfully enabled or disabled.
+ *          FAILURE if trying to disable disabled (or enable enabled)
+ *                  logging or SDR module have not being initialized.
+ */
 int8_t rpp_sdr_setup(boolean_t enable);
 
-// How much space is available
+
+/**
+ * Query for the amount of space free on the SD-RAM.
+ *
+ * This funtion will calculate the amount of free space left (not used by logs)
+ * on the SD-RAM.
+ *
+ * @return Number of bytes free in the SD-RAM.
+ *          For 64MB SD-RAM value is between [0-67108864]
+ */
 uint32_t rpp_sdr_available();
 
-// Store something to the log, if logging is enabled
-int32_t rpp_sdr_printf(const char *format, ...);
 
-// Clears log. Will also stop the show task
+/**
+ * Store a formatted user string on the log, if logging is enabled.
+ *
+ * Implementation uses vsnprintf() from stdio.h using a fixed MAX_BUFFER_LEN
+ * bytes buffer.
+ *
+ * @param[in] format    C string that contains a format string that follows the
+ *                      same specifications as format in printf (see stdio.h's
+ *                      printf for details).
+ * @param[in] ...       (additional arguments) Depending on the format string,
+ *                      the function may expect a sequence of additional
+ *                      arguments, each containing a value to be used to replace
+ *                      a format specifier in the format string (or a pointer to
+ *                      a storage location).
+ *                      There should be at least as many of these arguments as
+ *                      the number of values specified in the format specifiers.
+ *                      Additional arguments are ignored by the function.
+ *
+ * @return The number of characters that would have been written if the buffer
+ *          had been sufficiently large, not counting the terminating null
+ *          character.
+ *          If logging is disabled, an encoding error occurs or the log file is
+ *          full a negative number is returned.
+ *          Please note that only when this returned value is non-negative and
+ *          less than the buffer size, the string has been completely written.
+ */
+int32_t rpp_sdr_printf(const char* format, ...);
+
+
+/**
+ * Clear log.
+ *
+ * This funtion will clear all the data from the log. This will also stop the
+ * show task if running.
+ *
+ * @return SUCCESS if log was cleared.
+ *          FAILURE if logging is disabled or log was already empty.
+ */
 int8_t rpp_sdr_clear();
 
-// Starts/Stops the task that sends the log to the SCI
+
+/**
+ * Start/Stop the task that sends the log to the SCI.
+ *
+ * This function will start the task that reads the log and prints it to the
+ * SCI in a similar way the 'dmesg' command work on Linux.
+ *
+ * @param[in] start     TRUE to request the log to be sent to the SCI.
+ *                      FALSE to stop the log file from being send to the SCI.
+ *
+ * @return SUCCESS if log was cleared.
+ *          FAILURE if logging is disabled or trying to stop an stopped task
+ *                  (or start an already started task).
+ */
 int8_t rpp_sdr_show(boolean_t start);