rpp/include/rpp/sdr.h

   1 /**
   2  * SD-RAN logging RPP API header file.
   3  *
   4  * @file sdr.h
   5  *
   6  * @copyright Copyright (C) 2013 Czech Technical University in Prague
   7  *
   8  * @author Carlos Jenkins <carlos@jenkins.co.cr>
   9  */
  10
  11
  12 #ifndef __RPP_SDR_H
  13 #define __RPP_SDR_H
  14
  15 /**
  16  * SDRAM start address on RPP board.
  17  */
  18 #define RPP_SDR_ADDR_START 0x80000000U
  19
  20 /**
  21  * SDRAM end address on RPP board.
  22  */
  23 #define RPP_SDR_ADDR_END   0x83FFFFFFU
  24 // Note : 0x83FFFFFF − 0x80000000 + 1 = 67108864 addresses
  25 //        One address per byte
  26 //        67108864 bytes = 65536 Kbytes = 64 Mbytes
  27
  28
  29 /**
  30  * SDR module initialization.
  31  * Call this method before using this module.
  32  *
  33  * @return SUCCESS if initialization successful.
  34  *          FAILURE if module already initialized.
  35  */
  36 int8_t rpp_sdr_init();
  37
  38
  39 /**
  40  * Configure SD-RAM logging.
  41  *
  42  * This function will enable or disable logging on application. Note that when
  43  * logging is enabled a command processor task which uses the SCI for user I/O
  44  * is spawned. This command processor might conflict with user application if it
  45  * also uses the SCI for user I/O.
  46  *
  47  * @param[in] enable    Enable/Disable logging on application.
  48  *
  49  * @return SUCCESS if was logging successfully enabled or disabled.
  50  *          FAILURE if trying to disable disabled (or enable enabled)
  51  *                  logging or SDR module have not being initialized.
  52  */
  53 int8_t rpp_sdr_setup(boolean_t enable);
  54
  55
  56 /**
  57  * Query for the amount of space free on the SD-RAM.
  58  *
  59  * This funtion will calculate the amount of free space left (not used by logs)
  60  * on the SD-RAM.
  61  *
  62  * @return Number of bytes free in the SD-RAM.
  63  *          For 64MB SD-RAM value is between [0-67108864]
  64  */
  65 uint32_t rpp_sdr_available();
  66
  67
  68 /**
  69  * Store a formatted user string on the log, if logging is enabled.
  70  *
  71  * Implementation uses vsnprintf() from stdio.h using a fixed MAX_BUFFER_LEN
  72  * bytes buffer.
  73  *
  74  * @param[in] format    C string that contains a format string that follows the
  75  *                      same specifications as format in printf (see stdio.h's
  76  *                      printf for details).
  77  * @param[in] ...       (additional arguments) Depending on the format string,
  78  *                      the function may expect a sequence of additional
  79  *                      arguments, each containing a value to be used to replace
  80  *                      a format specifier in the format string (or a pointer to
  81  *                      a storage location).
  82  *                      There should be at least as many of these arguments as
  83  *                      the number of values specified in the format specifiers.
  84  *                      Additional arguments are ignored by the function.
  85  *
  86  * @return The number of characters that would have been written if the buffer
  87  *          had been sufficiently large, not counting the terminating null
  88  *          character.
  89  *          If logging is disabled, an encoding error occurs or the log file is
  90  *          full a negative number is returned.
  91  *          Please note that only when this returned value is non-negative and
  92  *          less than the buffer size, the string has been completely written.
  93  */
  94 int32_t rpp_sdr_printf(const char* format, ...);
  95
  96
  97 /**
  98  * Clear log.
  99  *
 100  * This funtion will clear all the data from the log. This will also stop the
 101  * show task if running.
 102  *
 103  * @return SUCCESS if log was cleared.
 104  *          FAILURE if logging is disabled or log was already empty.
 105  */
 106 int8_t rpp_sdr_clear();
 107
 108
 109 /**
 110  * Start/Stop the task that sends the log to the SCI.
 111  *
 112  * This function will start the task that reads the log and prints it to the
 113  * SCI in a similar way the 'dmesg' command work on Linux.
 114  *
 115  * @param[in] start     TRUE to request the log to be sent to the SCI.
 116  *                      FALSE to stop the log file from being send to the SCI.
 117  *
 118  * @return SUCCESS if log was cleared.
 119  *          FAILURE if logging is disabled or trying to stop an stopped task
 120  *                  (or start an already started task).
 121  */
 122 int8_t rpp_sdr_show(boolean_t start);
 123
 124
 125 #endif /* __RPP_SDR_H */
 126