PIC24 Support Libraries
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
dataXfer.h
Go to the documentation of this file.
1 /*
2  * "Copyright (c) 2008 Robert B. Reese, Bryan A. Jones, J. W. Bruce ("AUTHORS")"
3  * All rights reserved.
4  * (R. Reese, reese_AT_ece.msstate.edu, Mississippi State University)
5  * (B. A. Jones, bjones_AT_ece.msstate.edu, Mississippi State University)
6  * (J. W. Bruce, jwbruce_AT_ece.msstate.edu, Mississippi State University)
7  *
8  * Permission to use, copy, modify, and distribute this software and its
9  * documentation for any purpose, without fee, and without written agreement is
10  * hereby granted, provided that the above copyright notice, the following
11  * two paragraphs and the authors appear in all copies of this software.
12  *
13  * IN NO EVENT SHALL THE "AUTHORS" BE LIABLE TO ANY PARTY FOR
14  * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
15  * OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE "AUTHORS"
16  * HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
17  *
18  * THE "AUTHORS" SPECIFICALLY DISCLAIMS ANY WARRANTIES,
19  * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
20  * AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
21  * ON AN "AS IS" BASIS, AND THE "AUTHORS" HAS NO OBLIGATION TO
22  * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS."
23  *
24  * Please maintain this header in its entirety when copying/modifying
25  * these files.
26  *
27  *
28  */
29 
30 #ifndef __DATA_XFER_H__
31 #define __DATA_XFER_H__
32 
33 /** \file
34  * \brief Routines which implement the \ref dataXfer "uC comm protocol".
35  */
36 
37 #include "dataXferImpl.h"
38 
39 // Specify that this is C code for proper C++ linking
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
43 
44 /// Number of for loop iterations which equal a timeout for the PIC.
45 /// # loops = instructions/sec * loops/instruction * seconds
46 #define RECEIVE_TIMEOUT (FCY * 1/20 * 0.1)
47 
48 /// Send one character to the uC, escaping if necessary.
49 /// \param c Character to send.
50  void
51  outCharXfer(char c);
52 
53 
54 /// A system-dependent macro to output one character.
55 #ifndef OUT_CHAR
56  void outChar(uint8_t c);
57 #define OUT_CHAR(c) outChar(c)
58 #else
59 // Hack: a command line of -DOUT_CHAR(c)=testOutChar(c) doesn't work. Just -DOUT_CHAR then
60 // redefine it here.
61 #undef OUT_CHAR
62 #define UNIT_TESTS
63  void testOutChar(uint8_t c);
64 #define OUT_CHAR(c) testOutChar(c)
65 #endif
66 
67 /// Initialize the data transfer system. This must be called before calling
68 /// any of the data transfer functions in the library.
69  void
70  initDataXfer();
71 
72 #if defined(__PIC__) || defined(__DOXYGEN__) || defined(UNIT_TESTS)
73  /** Specify a variable to be sent or received.
74  * \param u_varIndex A value from 0-\ref NUM_XFER_VARS, unique for each var
75  * \param pv_data A pointer to the data to be sent
76  * \param u_size Size of the data in bytes; must be from 1 to 256.
77  * \param b_isWriteable True if the PC is allowed to change this
78  * variable; false otherwise. This does *NOT*
79  * restrict the PIC to read-only access to this
80  * variable.
81  * \param psz_format printf format string to use in displaying the
82  * Variable.
83  * \param psz_name Name of this variable, typically the same as used
84  * in the code
85  * \param psz_desc Description of this variable.
86  */
87  void
88  specifyVar(uint u_varIndex, volatile void* pv_data, uint u_size,
89  BOOL b_isWriteable, char* psz_format, char* psz_name,
90  char* psz_desc);
91 
92  /** For simplicity, define a macro that specifies a variable with
93  * default names.
94  * \param u_varIndex A value from 0-\ref NUM_XFER_VARS, unique for each var
95  * \param data A pointer to the data to be sent
96  * \param isWriteable True if the PC is allowed to change this
97  * variable; false otherwise. This does *NOT*
98  * restrict the PIC to read-only access to this
99  * variable.
100  * \param format printf format string to use in displaying the
101  * variable
102  * \param desc Description of this variable.
103  */
104 #define SPECIFY_VAR(u_varIndex, data, isWriteable, format, desc) \
105  specifyVar(u_varIndex, &data, sizeof(data), isWriteable, format, #data, desc)
106 #endif
107 
108 /// Send an already-specified variable; \see specifyVar.
109 /// \param u_varIndex The index of the variable to send; must be from 0 to
110 /// \ref NUM_XFER_VARS.
111  void
112  sendVar(uint u_varIndex);
113 
114 #if !defined(__PIC__) || defined(__DOXYGEN__)
115  /** Return a string with the data stored in the given variable formatted using
116  * the format string contained in the variable. Limitation: current, use of
117  * a string (%s format) will probably crash the program. <b>PC only.</b>
118  * \param u_varIndex The index of the variable to send; must be from 0 to
119  * \ref NUM_XFER_VARS.
120  * \param psz_buf Buffer large enough to contain the formatted string.
121  * \return On success, the total number of characters written is returned.
122  * This count does not include the additional null-character
123  * automatically appended at the end of the string.
124  * On failure, a negative number is returned.
125  */
126  int
127  formatVar(uint u_varIndex, char* psz_buf);
128 #endif
129 
130 
131 #if defined(__PIC__) || defined(__DOXYGEN__)
132  /** Receive a character or a variable. Any errors that occur are
133  * reported via outString. <b>uC only.</b>
134  * \param c Pointer to space for storing the received character, if
135  * a character was received (see return value).
136  * \return An index to the variable, if a variable was received, or
137  * \ref CHAR_RECEIVED_INDEX if a character was received.
138  */
139  uint
140  receiveVar(char* c);
141 
142  /** Receive a character, while transparently processing any
143  * variables sent by the PC. Variables are assigned, but
144  * this simple interface does not report these assignments
145  * to its caller. This provides a simple wrapper around \ref receiveVar,
146  * which also reports on received variables. <b>uC only.</b>
147  * \return The character received.
148  */
149  char
150  inCharXfer();
151 #endif
152 
153 
154 #ifdef __cplusplus
155 }
156 #endif
157 
158 #endif