PIC24 Support Libraries: esos/include/esos

00001 /*
00002  * "Copyright (c) 2008 Robert B. Reese, Bryan A. Jones, J. W. Bruce ("AUTHORS")"
00003  * All rights reserved.
00004  * (R. Reese, reese_AT_ece.msstate.edu, Mississippi State University)
00005  * (B. A. Jones, bjones_AT_ece.msstate.edu, Mississippi State University)
00006  * (J. W. Bruce, jwbruce_AT_ece.msstate.edu, Mississippi State University)
00007  *
00008  * Permission to use, copy, modify, and distribute this software and its
00009  * documentation for any purpose, without fee, and without written agreement is
00010  * hereby granted, provided that the above copyright notice, the following
00011  * two paragraphs and the authors appear in all copies of this software.
00012  *
00013  * IN NO EVENT SHALL THE "AUTHORS" BE LIABLE TO ANY PARTY FOR
00014  * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
00015  * OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE "AUTHORS"
00016  * HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00017  *
00018  * THE "AUTHORS" SPECIFICALLY DISCLAIMS ANY WARRANTIES,
00019  * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
00020  * AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
00021  * ON AN "AS IS" BASIS, AND THE "AUTHORS" HAS NO OBLIGATION TO
00022  * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS."
00023  *
00024  * Please maintain this header in its entirety when copying/modifying
00025  * these files.
00026  *
00027  *
00028  */
00029 
00030 
00043 #ifndef         ESOS_COMM_H
00044 #define ESOS_COMM_H
00045 
00046 /* I N C L U D E S **********************************************************/
00047 #include    "esos.h"
00048 
00049 /* P R O T O T Y P E S ******************************************************/
00050 void __esos_InitCommSystem(void);
00051 uint8 __esos_u8_GetMSBHexCharFromUint8(uint8 u8_x);
00052 uint8 __esos_u8_GetLSBHexCharFromUint8(uint8 u8_x);
00053 ESOS_CHILD_TASK( __esos_OutChar, uint8 u8_c);
00054 ESOS_CHILD_TASK( __esos_OutUint8AsHexString, uint8 u8_x);
00055 ESOS_CHILD_TASK( __esos_OutUint32AsHexString, uint32 u32_x);
00056 ESOS_CHILD_TASK( __esos_OutCharBuffer, uint8* pu8_out, uint8 u8_len);
00057 ESOS_CHILD_TASK( __esos_getBuffer, uint8* pau8_buff, uint8 u8_size);
00058 ESOS_CHILD_TASK( __esos_getString, char* pau8_buff);
00059 ESOS_CHILD_TASK( __esos_OutString, char* psz_out );
00060 void __esos_unsafe_PutUint8(uint8 u8_c);
00061 void __esos_unsafe_PutString(char* psz_in);
00062 uint8 __esos_unsafe_GetUint8(void);
00063 
00064 /* D E F I N E S ************************************************************/
00065 #define ESOS_COMM_SYS_USB                   0x80
00066 #define ESOS_COMM_SYS_SERIAL            0x00
00067 #define ESOS_COMM_SYS_SERIAL_REV        (ESOS_COMM_SYS_SERIAL + 0x01)
00068 // size of buffer to catch data incoming to PIC (based on USB terminology)
00069 #define ESOS_SERIAL_OUT_EP_SIZE    64
00070 // size of buffer to hold data leaving the PIC (based on USB terminology)
00071 #define ESOS_SERIAL_IN_EP_SIZE     64
00072 
00073 /***
00074  *** A few defines to help make data transfer easier
00075  ***/
00076 #define   __ESOS_COMM_TXFIFO_PREP()                     \
00077   u16_tmp = __st_TxBuffer.u16_Head;                     \
00078   u16_tmp++;                                            \
00079   if (u16_tmp == ESOS_SERIAL_IN_EP_SIZE) u16_tmp = 0
00080 
00081 #define   __ESOS_COMM_WRITE_TXFIFO( u8_out )            \
00082     __st_TxBuffer.pau8_Data[u16_tmp] = (u8_out);        \
00083     __st_TxBuffer.u16_Head = u16_tmp
00084 
00085 
00086 
00087 /* M A C R O S ************************************************************/
00088 
00089 /*
00090  * Evaluates to the number of bytes in the ESOS "in" communications buffer
00091  *
00092  * \param pstTask A pointer to the ESOS task control structure specific to this task.
00093  *
00094  * \hideinitializer
00095  */
00096 
00097 /*
00098 * Evaluates to the number of bytes in the ESOS "in" communications buffer
00099 *
00100 * \param pfnTaskFcn pointer to task function
00101 * \retval NULLPTR   if no more tasks can execute at this time (scheduler is full)
00102 * \retval pstTask   pointer to the scheduled task's structure
00103 *
00104 * \hideinitializer
00105 */
00106 
00112 #define GET_ESOS_COMM_IN_DATA_LEN()   ((__st_RxBuffer.u16_Head>=__st_RxBuffer.u16_Tail)?(__st_RxBuffer.u16_Head-__st_RxBuffer.u16_Tail):(__st_RxBuffer.u16_Length-__st_RxBuffer.u16_Tail+__st_RxBuffer.u16_Head))
00113 
00124 #define IS_ESOS_COMM_GOT_EXACTLY_DATA_BYTES(x)          (GET_ESOS_COMM_IN_DATA_LEN() == x)
00125 
00136 #define IS_ESOS_COMM_GOT_AT_LEAST_DATA_BYTES(x)         (GET_ESOS_COMM_IN_DATA_LEN() >= x)
00137 
00147 #define FLUSH_ESOS_COMM_IN_DATA()                                                 (__st_RxBuffer.u16_Head = __st_RxBuffer.u16_Tail)
00148 
00158 #define IS_ESOS_COMM_GOT_IN_DATA()                                              (__st_RxBuffer.u16_Head != __st_RxBuffer.u16_Tail)
00159 
00160 // should use PEEK... It is unsafe since IRQs can occur at anytime....
00178 #define PEEK_ESOS_COMM_IN_DATA(x)                                     ( __st_RxBuffer.pau8_Data[((__st_RxBuffer.u16_Tail+1+x)% ESOS_SERIAL_OUT_EP_SIZE)] )
00179 
00196 #define PEEK_ESOS_COMM_IN_LATEST_DATA()             ( __st_RxBuffer.pau8_Data[__st_RxBuffer.u16_Head] )
00197 
00207 #define IS_ESOS_COMM_READY_OUT_DATA()                                                   (__st_TxBuffer.u16_Head != __st_TxBuffer.u16_Tail)
00208 
00209 // communications commands used by ESOS tasks
00216 #define   ESOS_TASK_WAIT_ON_AVAILABLE_IN_COMM()                                                \
00217             ESOS_TASK_WAIT_WHILE( __esos_IsSystemFlagSet( __ESOS_SYS_COMM_RX_IS_BUSY ) );      \
00218             __esos_SetSystemFlag( __ESOS_SYS_COMM_RX_IS_BUSY )
00219 
00227 #define   ESOS_TASK_WAIT_ON_AVAILABLE_OUT_COMM()                                                \
00228             ESOS_TASK_WAIT_WHILE( __esos_IsSystemFlagSet( __ESOS_SYS_COMM_TX_IS_BUSY ) );       \
00229             __esos_SetSystemFlag( __ESOS_SYS_COMM_TX_IS_BUSY )
00230 
00240 #define   ESOS_TASK_SIGNAL_BUSY_IN_COMM()     __esos_SetSystemFlag( __ESOS_SYS_COMM_RX_IS_BUSY )
00241 
00252 #define   ESOS_TASK_SIGNAL_BUSY_OUT_COMM()    __esos_SetSystemFlag( __ESOS_SYS_COMM_TX_IS_BUSY )
00253 
00254 
00262 #define   ESOS_TASK_SIGNAL_AVAILABLE_IN_COMM()         __esos_ClearSystemFlag( __ESOS_SYS_COMM_RX_IS_BUSY )
00263 
00270 #define   ESOS_TASK_SIGNAL_AVAILABLE_OUT_COMM()         __esos_ClearSystemFlag( __ESOS_SYS_COMM_TX_IS_BUSY )
00271 
00281 #define   ESOS_TASK_RELEASE_IN_COMM()     ESOS_TASK_SIGNAL_AVAILABLE_IN_COMM()
00282 
00291 #define   ESOS_TASK_RELEASE_OUT_COMM()    ESOS_TASK_SIGNAL_AVAILABLE_OUT_COMM()
00292 
00293 
00294 // **************** spawn child tasks to do getting and putting to comm streams ***********************
00308 #define   ESOS_TASK_WAIT_ON_GET_UINT8( u8_in )                                    \
00309             ESOS_TASK_SPAWN_AND_WAIT( (ESOS_TASK_HANDLE)&__stChildTaskRx, __esos_getBuffer, &(u8_in), 1 )
00310 
00325 #define   ESOS_TASK_WAIT_ON_GET_U8BUFFER( pau8_in, u8_size)                                                \
00326             ESOS_TASK_SPAWN_AND_WAIT( (ESOS_TASK_HANDLE) &__stChildTaskRx, __esos_getBuffer, (pau8_in), (u8_size) )
00327 
00346 #define   ESOS_TASK_WAIT_ON_GET_STRING( pau8_in )                                                \
00347             ESOS_TASK_SPAWN_AND_WAIT( (ESOS_TASK_HANDLE)&__stChildTaskRx, __esos_getString, (pau8_in) )
00348 
00357 #define   ESOS_TASK_WAIT_ON_SEND_UINT8( u8_out)         \
00358             ESOS_TASK_SPAWN_AND_WAIT( (ESOS_TASK_HANDLE) &__stChildTaskTx, __esos_OutChar, (u8_out) )
00359 
00369 #define   ESOS_TASK_WAIT_ON_SEND_UINT8_AS_HEX_STRING( u8_out)         \
00370             ESOS_TASK_SPAWN_AND_WAIT( (ESOS_TASK_HANDLE)&__stChildTaskTx, __esos_OutUint8AsHexString, (u8_out) )
00371 
00381 #define   ESOS_TASK_WAIT_ON_SEND_UINT32_AS_HEX_STRING( u32_out)         \
00382             ESOS_TASK_SPAWN_AND_WAIT( (ESOS_TASK_HANDLE)&__stChildTaskTx, __esos_OutUint32AsHexString, (u32_out) )
00383 
00392 #define   ESOS_TASK_WAIT_ON_SEND_STRING( psz_out)         \
00393             ESOS_TASK_SPAWN_AND_WAIT( (ESOS_TASK_HANDLE)&__stChildTaskTx, __esos_OutString, (psz_out) )
00394 
00404 #define   ESOS_TASK_WAIT_ON_SEND_U8BUFFER( pau8_out, u8_size)         \
00405             ESOS_TASK_SPAWN_AND_WAIT( (ESOS_TASK_HANDLE)&__stChildTaskTx, __esos_OutCharBuffer, (pau8_out), (u8_size) )
00406 
00407 
00408 /* S T R U C T U R E S ******************************************************/
00409 
00416 typedef struct _ESOS_COMM_BUFF_DSC {
00417   volatile uint8*       pau8_Data;
00418   int16                 u16_Head;
00419   int16                 u16_Tail;
00420   uint16                u16_Length;
00421 } ESOS_COMM_BUFF_DSC;
00422 
00423 /* E X T E R N S ************************************************************/
00424 extern volatile uint8                 __esos_comm_tx_buff[ESOS_SERIAL_IN_EP_SIZE];
00425 extern volatile uint8                 __esos_comm_rx_buff[ESOS_SERIAL_OUT_EP_SIZE];
00426 extern volatile ESOS_COMM_BUFF_DSC    __st_TxBuffer, __st_RxBuffer;
00427 extern volatile struct stTask         __stChildTaskTx, __stChildTaskRx;
00428 
00429 /* P U B L I C  P R O T O T Y P E S *****************************************/
00435 uint8 esos_GetCommSystemVersion(void);
00436 
00442 uint8 esos_GetCommSystemMaxOutDataLen(void);
00443 
00449 uint8 esos_GetCommSystemMaxInDataLen(void);
00450 
00451 void  __esos_InitCommSystem(void);
00452 
00453 /* prototypes of the unsafe comm functions provided by ESOS */
00454 void __esos_unsafe_PutUint8(uint8 u8_c);
00455 void __esos_unsafe_PutString(char* psz_in);
00456 uint8 __esos_unsafe_GetUint8(void);
00457 
00458 /* prototypes of external functions provided by hardware */
00459 void __esos_hw_signal_start_tx(void);
00460 void __esos_hw_signal_stop_tx(void);
00461 void  __esos_hw_InitCommSystem(void);
00462 
00465 #endif          // ESOS_COMM_H
esos/include/esos_comm.h
