Diff: hal.h

Revision:

8:5879e83f632a

Parent:

1:d3b7bde3995c

--- a/hal.h	Thu Feb 25 21:28:23 2016 +0000
+++ b/hal.h	Mon Apr 02 12:04:59 2018 +0000
@@ -7,77 +7,145 @@
  *
  * Contributors:
  *    IBM Zurich Research Lab - initial API, implementation and documentation
- *******************************************************************************/
+ * /////////////////////////////////////////////////////////////////////////////
+ *
+ * Used by Giorgos Tsapparellas for Internet of Things (IoT) smart monitoring
+ * device for agriculture using LoRaWAN technology.
+ * 
+ * Date of issued copy: 25 January 2018
+ *
+ * Modifications: 
+ * - No external modifications of the existing "AS IT IS" software.
+ * - Added some external comments for meeting good principles of 
+ *   source code re-usability.   
+ ******************************************************************************/
 
 #ifndef _hal_hpp_
 #define _hal_hpp_
 
-/*
- * initialize hardware (IO, SPI, TIMER, IRQ).
- */
+/* 
+ * hal_init function of type void.
+ *
+ * Initializes hardware (IO, SPI, TIMER, IRQ).
+ *
+ * Input parameters: None
+ *
+ */ 
 void hal_init (void);
 
-/*
- * drive radio NSS pin (0=low, 1=high).
- */
+/* 
+ * hal_pin_nss function of type void.
+ *
+ * Drives radio NSS pin (0=low, 1=high).
+ *
+ * Input parameters: unsigned int val
+ *
+ */ 
 void hal_pin_nss (u1_t val);
 
-/*
- * drive radio RX/TX pins (0=rx, 1=tx).
- */
+/* 
+ * hal_pin_rxtx function of type void.
+ *
+ * Drives radio RX/TX pins (0=rx, 1=tx).
+ *
+ * Input parameters: unsigned int val
+ *
+ */ 
 void hal_pin_rxtx (u1_t val);
 
-/*
- * control radio RST pin (0=low, 1=high, 2=floating)
- */
+/* 
+ * hal_pin_rst function of type void.
+ *
+ * Controls radio RST pin (0=low, 1=high, 2=floating).
+ *
+ * Input parameters: unsigned int val
+ *
+ */ 
 void hal_pin_rst (u1_t val);
 
-/*
- * perform 8-bit SPI transaction with radio.
+/* 
+ * hal_spi function of type unsigned integer.
+ *
+ * Performs 8-bit SPI transaction with radio.
  *   - write given byte 'outval'
- *   - read byte and return value
- */
+ *   - read byte
+ *
+ * Input parameters: unsigned int outval
+ * Return: value
+ *
+ */ 
 u1_t hal_spi (u1_t outval);
 
-/*
- * disable all CPU interrupts.
+/* 
+ * hal_disableIRQs function of type void.
+ *
+ * Disables all CPU interrupts.
  *   - might be invoked nested 
  *   - will be followed by matching call to hal_enableIRQs()
- */
+ *
+ * Input parameters: None
+ *
+ */ 
 void hal_disableIRQs (void);
 
-/*
- * enable CPU interrupts.
- */
+/* 
+ * hal_enableIRQs function of type void.
+ *
+ * Enables CPU interrupts.
+ *
+ * Input parameters: None
+ *
+ */ 
 void hal_enableIRQs (void);
 
-/*
- * put system and CPU in low-power mode, sleep until interrupt.
- */
+/* 
+ * hal_sleep function of type void.
+ *
+ * Puts system and CPU in low-power mode, sleep until interrupt.
+ *
+ * Input parameters: None
+ *
+ */ 
 void hal_sleep (void);
 
-/*
- * return 32-bit system time in ticks.
- */
+/* 
+ * hal_ticks function of type unsigned interger.
+ *
+ * Input parameters: None
+ * Return: 32-bit system time in ticks.
+ */ 
 u4_t hal_ticks (void);
 
-/*
- * busy-wait until specified timestamp (in ticks) is reached.
- */
+/* 
+ * hal_waitUntil function of type void.
+ *
+ * Busy-wait until specified timestamp (in ticks) is reached.
+ *
+ * Input parameters: unsigned int time
+ */ 
 void hal_waitUntil (u4_t time);
 
-/*
- * check and rewind timer for target time.
- *   - return 1 if target time is close
- *   - otherwise rewind timer for target time or full period and return 0
- */
+/* 
+ * hal_checkTimer function of type unsigned char.
+ *
+ * Checks and rewinds timer for target time.
+ *
+ * Input parameters: unsigned int targettime
+ * Return: - 1 if target time is close
+ *         - otherwise rewind timer for target time or full period and return 0 
+ */ 
 u1_t hal_checkTimer (u4_t targettime);
 
-/*
- * perform fatal failure action.
+/* 
+ * hal_failed function of type void.
+ *
+ * Performs fatal failure action.
  *   - called by assertions
  *   - action could be HALT or reboot
- */
+ *
+ * Input parameters: None
+ *
+ */ 
 void hal_failed (void);
 
 #endif // _hal_hpp_