NetBurner 3.1
StreamUpdate.h
1 /*NB_REVISION*/
2 
3 /*NB_COPYRIGHT*/
4 
5 #ifndef _NB_STREAM_UP_H
6 #define _NB_STREAM_UP_H
7 
8 #define STREAM_UP_OK (1)
9 #define STREAM_UP_FAIL (0)
10 
11 #include <basictypes.h>
12 
13 /*Stream Update code */
14 /*Module: Stream Update
15 The functions supplied in this module are intended to be used in conjunction
16 with FTP server and client implementations. Functions are provided to access
17 the user parameter storage area of the flash memory, and to update the
18 application code in flash memory.
19 
20 
21 See the example application at
22  nburn\examples\ftpd_code_update
23 */
24 
25 /*Functions:*/
26 /*Group:Stream Update of User Parameter Flash Data.*/
27 /*Send User Parameter Flash data as a binary output stream.*/
28 /*
29 This function sends the User Parameter Flash data to the specified fd
30 output stream as a binary record.
31 
32 Parameters:
33  int fd The socket file descriptor to send the data to
34 
35 Returns:
36  STREAM_UP_OK The system was able to send the data
37  STREAM_UP_FAIL The system failed to send the data
38 
39 
40 See Also:
41  int SendUserFlashToStreamAsS19(int fd);
42  int ReadBinaryUserFlashFromStream(int fd);
43  int ReadS19UserFlashFromStream(int fd);
44 
45 
46 */
47 int SendUserFlashToStreamAsBinary(int fd);
48 
49 /*Send User Parameter Flash data as a S19 ASCII record to an output stream.*/
50 /*
51 This function sends the User Parameter Flash data to the specified fd
52 output stream as a S19 text record.
53 
54 Parameters:
55  int fd The socket file descriptor to send the data to.
56 
57 Returns:
58  STREAM_UP_OK The system was able to send the data
59  STREAM_UP_FAIL The system failed to send the data
60 
61 
62 See Also:
63  int SendUserFlashToStreamAsBinary(int fd);
64  int ReadBinaryUserFlashFromStream(int fd);
65  int ReadS19UserFlashFromStream(int fd);
66 
67 */
68 int SendUserFlashToStreamAsS19(int fd);
69 
70 /*Read User Parameter Flash data from a S19 ASCII input stream.*/
71 /*
72 This function reads ASCII S19 records from the specified fd input stream
73 and programs the data in the User Parameter Flash area.
74 
75 Parameters:
76  int fd The socket file descriptor to read data from
77 
78 Returns:
79  STREAM_UP_OK The system was able to read the data and update flash
80  STREAM_UP_FAIL The system failed to read or update
81 
82 
83 See Also:
84  int SendUserFlashToStreamAsS19(int fd);
85  int SendUserFlashToStreamAsBinary(int fd);
86  int ReadBinaryUserFlashFromStream(int fd);
87 
88 */
89 int ReadS19UserFlashFromStream(int fd);
90 
91 /*Read User Parameter Flash data from a binary input stream.*/
92 /*
93 This function reads binary data from the specified input stream and
94 programs the data into the User Parameter Flash area.
95 
96 Parameters:
97  int fd The socket file descriptor to read data from
98 
99 Returns:
100  STREAM_UP_OK The system was able to read the data and update flash
101  STREAM_UP_FAIL The system failed to read or update
102 
103 See Also:
104  int SendUserFlashToStreamAsS19(int fd);
105  int SendUserFlashToStreamAsBinary(int fd);
106  int ReadS19UserFlashFromStream(int fd);
107 
108 */
109 int ReadBinaryUserFlashFromStream(int fd);
110 
111 /*Functions:*/
112 /*Group:Stream Update of Application Code.*/
113 /*Read a new application in _APP.S19 format from an ASCII input stream.*/
114 /*
115 This function reads ASCII S19 records from a _APP.s19 format application file
116 and reprograms the Flash memory with the new application. The Flash memory will
117 not be modified unless the entire application is received without error.
118 
119 Since applications are run from RAM, the board must be rebooted before the new
120 application code becomes active. One way to accomplish a reboot is to use
121 the function: void ForceReboot(). Items you need to clean up or close before
122 causing a reboot is dependent on your particular application, but at a minimum
123 you should clean up and close any FTP client or server sessions before calling
124 ForceReboot(). An example using this function is provided in the ftpd_code_update
125 example.
126 
127 
128 Parameters:
129  int fd The socket file descriptor to read data from
130 
131 Returns:
132  STREAM_UP_OK The system was able to read the data and update the Flash
133  STREAM_UP_FAIL The system failed to read or update Flash
134 */
135 int ReadS19ApplicationCodeFromStream(int fd);
136 
137 int SendApplicationCodeAsS19(int fd);
138 
139 int ReadBinaryApplicationCodeFromStream(int fd);
140 
141 // Exposed to allow custom updates to be used
142 int ProcessS3(const char *cp, uint32_t base_Addr, puint8_t CopyTo, uint32_t &cur_pos, uint32_t maxlen);
143 
144 // A Structure to hold the data from a update before actually committing to flash.
145 struct TwoPartUpdateStruct
146 {
147  uint8_t S0Record[24];
148  puint8_t pBlob;
149  uint32_t address;
150  uint32_t pgm_size;
151  int Result;
152  TwoPartUpdateStruct()
153  {
154  pBlob = 0;
155  Result = STREAM_UP_FAIL;
156  };
157 };
158 
159 // Populate the structure with allocated binary buffer to program into flash.
160 // return STREAM_UP_OK and sets structure result to STREAM_UP_OK if successful.
161 int ReadTwoPartAppUdate(int fd, TwoPartUpdateStruct &us);
162 
163 // Take a successfully read stream update and programs the flash
164 // return STREAM_UP_FAIL on update fail, and forces device reboot on success.
165 // also frees malloced data
166 int DoTwoPartAppUpdate(TwoPartUpdateStruct &us);
167 
168 // Cleans up stored malloced data if you want to abort an update.
169 void AbortTwoPartAppUpdate(TwoPartUpdateStruct &us);
170 
171 #endif