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