File: /home/oboss/Users/gec/sources/PUS_Services/Large_Data_Transfer/large_data_transfer-receiver_state.ads
1 --% Compilation Unit: Large_Data_Transfer.Receiver_State
2 --
3 --% Category: Generic Package Declaration
4 --
5 --% Release: $Name: $
6 --
7 --% Version: $Revision: 1.2 $
8 --
9 --% Author: $Author: jhl $
10 --
11 --% Revision Log:
12 -- $Log: large_data_transfer-receiver_state.ads,v $
13 -- Revision 1.2 2003/10/09 11:05:29 jhl
14 -- Added Service 13 And 19
15 --
16 -- Revision 1.1.2.4 2003/10/08 15:34:59 jhl
17 -- Changed SDU Parts pacakge to store read streams instead of write streams.
18 -- Corrected Receiver State to correctly deallocate all streams after trying to add them to the SDU Parts map.
19 -- Updated TC Parsed and Reveicer State to utilize ned SDU Parts.
20 --
21 -- Revision 1.1.2.3 2003/10/08 11:54:35 gec
22 -- Responded to Post-Review comments, i.e. comments to review comments.
23 --
24 -- Revision 1.1.2.2 2003/10/03 09:47:53 jhl
25 -- Large Data Transfer post review first update
26 --
27 -- Revision 1.1.2.1 2003/10/01 11:54:43 jhl
28 -- Initial version of service 13 Event Action, and 19 Large Data Transfer.
29 --
30 -- Revision 2.0 2003/04/04 10:08:58 gec
31 -- Initial release serving as baseline for OBOSS-III project.
32 --
33 -- Revision 1.1.1.1 2003/04/04 07:19:20 gec
34 -- Imported using TkCVS
35 --
36 --
37 --
38 --% Project: OBOSS
39 --
40 --% Copyright (C) 2003 by Terma A/S
41 -- Proprietary and intellectual rights of Terma A/S, Denmark,
42 -- are involved in the subject-matter of this material and
43 -- all manufacturing, reproduction, use, disclosure, and
44 -- sales rights pertaining to such subject-matter are
45 -- expressly reserved. This material is submitted for a
46 -- specific purpose as agreed, and the recipient by
47 -- accepting this material agrees that this material will
48 -- not be used, copied, or reproduced in whole or in part
49 -- nor its contents revealed in any manner or to any person,
50 -- except to meet the purpose for which it was submitted and
51 -- subject to the terms of the agreement.
52 --
53 --% Target Dependencies:
54 -- None
55 --% Compiler Dependencies:
56 -- None
57
58
59 --~-----------------------------------------------------------------------------
60
61 with Task_Priority_Control;
62
63 -- With's for external types
64 with External_Large_Data_Transfer_Types;
65 with Large_Data_Transfer_Types;
66
67 -- With's for timeout control
68 with Timeout_Control;
69 with Ada.Real_Time;
70
71 -- With's for part data streams
72 with Source_Data_Stream;
73 with Basic_Types;
74
75 generic
76
77 --% Generic Parameter Constraints:
78 --> Parameter - Constraint
79
80 -- Priority of proteceted object encapsulating actual state changes, making
81 --+ them atomic.
82 Protected_State_Priority
83 : in Task_Priority_Control.
84 Passive_Task_Priority;
85
86 -- Timeout interval for downlink reception acknowledgement TC from receiver.
87 --+
88 Timeout_Interval_In_Milliseconds : in Positive;
89
90 -- Timeout handler called if an downlink reception acknowledgement is not
91 --+ received after all parts have been sent.
92 with procedure Receiver_Timeout_Handler
93 (Timeout : in Receiver_Timeout);
94
95 -- Priority of proteceted object encapsulating the timout control
96 Protected_Timer_Control_Priority
97 : in Task_Priority_Control.Passive_Task_Priority;
98
99 -- Priority of the actual timer task for timeout control
100 Active_Timer_Priority : in Task_Priority_Control.Active_Task_Priority;
101
102 package Large_Data_Transfer.Receiver_State is
103
104 --% Library Package:
105 -- Maintains the state of the receiving sub-service.
106 --
107 -- The Sender State is used by:
108 --
109 -- * The TC Handler:
110 --
111 -- The TC Handler uses the Receiver State for requesting actions from
112 --+ TC's forwarded to the CDH to the Large Data Transfer receiving
113 --+ sub-service.
114 --
115 --% Active Tasks:
116 --> The_Timer - Contains a timer task for timeout control
117 --% Passive Tasks:
118 --> The_State - Protected object maintaining the state of the sending
119 --+ sub-service.
120 --> The_Timer - Contains a protected object encapsulating the timout
121 --+ control
122
123
124 -- Abstract base types for TC requests:
125
126 type TC_Request_Base is abstract tagged null record;
127
128 --% Subprogram:
129 -- Abstract subprogram for forwarding a TC request to the protected state
130 --+ object
131 -- TC Verification Level performed by this subprogram: Stort of Execution,
132 --+ Progress of Execution
133 -- The other levels are performed by other subprograms
134 --% Parameter Constraints:
135 --> None
136 --% Exceptions Raised:
137 --> None
138
139 function TC_Request_State
140 (TC_Packet : in PUS.PUS_Packet; -- TC packet needed for
141 --+ TC Verification
142 TC_Request : in TC_Request_Base)
143 return Boolean is abstract;
144
145 -- Extended abstract types:
146
147 -- Request to receive parts:
148
149 -- TC Request Data
150
151 type TC_Request_Part_Data is
152 record
153 Number : Large_Data_Transfer_Types.Sequence_Number := 1;
154 Stream : Source_Data_Stream.Read_Stream; -- Shall be allocated,
155 --+ but can have size 0, i.e.
156 --+ Void.
157 end record;
158
159 -- Abstract base type for accept uplink part requests
160 type TC_Request_Accept_Part_Base is abstract new TC_Request_Base
161 with record
162 Part : TC_Request_Part_Data;
163 end record;
164
165 -- Extended types:
166
167 -- First part
168 type TC_Request_Accept_First_Uplink_Part is new TC_Request_Accept_Part_Base
169 with null record;
170
171 function TC_Request_State
172 (TC_Packet : in PUS.PUS_Packet;
173 TC_Request : in TC_Request_Accept_First_Uplink_Part)
174 return Boolean;
175
176 -- Intermediate part
177 type TC_Request_Accept_Intermediate_Uplink_Part is new
178 TC_Request_Accept_Part_Base
179 with null record;
180
181 function TC_Request_State
182 (TC_Packet : in PUS.PUS_Packet;
183 TC_Request : in TC_Request_Accept_Intermediate_Uplink_Part)
184 return Boolean;
185
186 -- Last part
187 type TC_Request_Accept_Last_Uplink_Part is new TC_Request_Accept_Part_Base
188 with null record;
189
190 function TC_Request_State
191 (TC_Packet : in PUS.PUS_Packet;
192 TC_Request : in TC_Request_Accept_Last_Uplink_Part)
193 return Boolean;
194
195 -- Repeated part
196 type TC_Request_Accept_Repeated_Part is new TC_Request_Accept_Part_Base
197 with null record;
198
199 function TC_Request_State
200 (TC_Packet : in PUS.PUS_Packet;
201 TC_Request : in TC_Request_Accept_Repeated_Part)
202 return Boolean;
203
204 -- Request to abort uplink
205 type TC_Request_Abort_Reception_Of_Uplinked_Data is new TC_Request_Base
206 with null record;
207
208 function TC_Request_State
209 (TC_Packet : in PUS.PUS_Packet;
210 TC_Request : in TC_Request_Abort_Reception_Of_Uplinked_Data)
211 return Boolean;
212
213 -- Reason codes for uplink abort report
214 --
215 -- For comments on reason codes, look in External_Large_Data_Transfer_Types
216 type Receiver_Reason_Code is
217 (Timeout_Waiting_For_Part,
218 Illegal_Command_Waiting_For_Part,
219 Illegal_Part_Sequence_Number,
220 Repeated_Part_Errorneous,
221 Receiver_Logic_Error);
222
223 --% Subprogram:
224 -- Initialization of generic package instantiation.
225 --% Parameter Constraints:
226 --> None
227 --% Exceptions Raised:
228 --> None
229
230 procedure Initialize;
231
232 private
233
234 -- Package instantiations with types and functionality.
235
236 --% Subprogram:
237 -- Unparses the receiver reason code into the external format
238 --% Parameter Constraints:
239 --> None
240 --% Exceptions Raised:
241 --> None
242
243 function Unparse_Receiver_Reason_Code
244 (Reason_Code : in Receiver_Reason_Code)
245 return External_Large_Data_Transfer_Types.Reason_Code;
246
247 --% Subprogram:
248 -- Sends a Reception Abort Report with the specified reason code
249 --% Parameter Constraints:
250 --> None
251 --% Exceptions Raised:
252 --> None
253
254 procedure Reception_Abort_Report
255 (Reason_Code : in Receiver_Reason_Code);
256
257 -- Super state type
258 -- State Description:
259 -- Idle: Receiver state is idle, waiting to receive next SDU.
260 -- Receiving: Receiver state is currently receiveng parts for an SDU.
261 --+ Timeout timer has been started, and will timeout if a part has not
262 --+ been received within a given time internval.
263 -- Receiving_Repeated: Receiver state is currently receiveng repeated parts
264 --+ for an SDU. Timeout timer has been started, and will timeout if a
265 --+ part has not been received within a given time internval.
266 type Super_State_Type is
267 (Idle,
268 Receiving,
269 Receiving_Repeated);
270
271 -- State type
272 --
273 -- One state type object, State, is declared in the protected state object.
274 --+ The discriminant of State is used to specify the superstate. Every
275 --+ state change is then a case-statement of the discriminant, changing
276 --+ the discriminant of State to reflect the state change. So we need a
277 --+ default discriminant, as State will need to change discriminant.
278
279 type State_Type(Super_State : Super_State_Type := Idle) is
280 record
281 case Super_State is
282 when Idle =>
283 First_Part : Large_Data_Transfer.Part_Range;
284
285 when Receiving =>
286 -- Specific parts, and missing parts, are managed by the
287 --+ SDU_Parts package
288 Next_Part : Large_Data_Transfer.Part_Range;
289
290 when Receiving_Repeated =>
291 -- Specific parts, and missing parts, are managed by the
292 --+ SDU_Parts package
293 Missing_Part_Count
294 : Large_Data_Transfer.Optional_Part_Range;
295 -- The actual Parts, and missing parts, are
296 --+ managed by the SDU_Parts package.
297 Last_Part : Large_Data_Transfer.Part_Range;
298
299 end case;
300 end record;
301
302 --
303 -- The actual protected state object
304 --
305
306 protected The_State is
307
308 --% Protected Specification:
309 -- Maintains the actual state of the receiving sub-service.
310 -- All calls to the Sender State is routed through to the state,
311 --+ ensuring that only one call is executed at a time. This is
312 --+ necessary due to the timeout call.
313 -- TC verification Start of Execution and Progress of Execution
314 --+ is carried out by the protected state.
315
316 -- Priority of the protected object.
317 pragma Priority (Integer(Protected_State_Priority));
318
319 --% Subprogram:
320 -- TC Request to receive part: First
321 --% Parameter Constraints:
322 --> None
323 --% Exceptions Raised:
324 --> None
325
326 procedure TC_Request_Accept_First_Uplink_Part
327 (TC_Packet : in PUS.PUS_Packet;
328 Part : in TC_Request_Part_Data;
329 Request_Success : out Boolean);
330
331 --% Subprogram:
332 -- TC Request to receive part: Intermediate
333 --% Parameter Constraints:
334 --> None
335 --% Exceptions Raised:
336 --> None
337
338 procedure TC_Request_Accept_Intermediate_Uplink_Part
339 (TC_Packet : in PUS.PUS_Packet;
340 Part : in TC_Request_Part_Data;
341 Request_Success : out Boolean);
342
343 --% Subprogram:
344 -- TC Request to receive part: Last
345 --% Parameter Constraints:
346 --> None
347 --% Exceptions Raised:
348 --> None
349
350 procedure TC_Request_Accept_Last_Uplink_Part
351 (TC_Packet : in PUS.PUS_Packet;
352 Part : in TC_Request_Part_Data;
353 Request_Success : out Boolean);
354
355 --% Subprogram:
356 -- TC Request to receive part: Repeated
357 --% Parameter Constraints:
358 --> None
359 --% Exceptions Raised:
360 --> None
361
362 procedure TC_Request_Accept_Repeated_Part
363 (TC_Packet : in PUS.PUS_Packet;
364 Part : in TC_Request_Part_Data;
365 Request_Success : out Boolean);
366
367 --% Subprogram:
368 -- TC request to abort an uplink in progress
369 --% Parameter Constraints:
370 --> None
371 --% Exceptions Raised:
372 --> None
373
374 procedure TC_Request_Abort_Reception_Of_Uplinked_Data
375 (TC_Packet : in PUS.PUS_Packet;
376 Request_Success : out Boolean);
377
378 --% Subprogram:
379 -- Internal Timeout mechanism. Called when a next part reception has
380 --+ timed out.
381 -- Parameter is the timeout time set in the timeout control when
382 --+ starting the timeout.
383 --% Parameter Constraints:
384 --> None
385 --% Exceptions Raised:
386 --> None
387
388 procedure Timeout
389 (Abs_Timeout_Time : in Ada.Real_Time.Time);
390
391 private
392
393 --
394 -- Internal state variables keeping tack of the state of the receiving
395 --+ sub-service
396 --
397
398 -- Initial state
399 State : State_Type :=
400 State_Type'
401 (Super_State => Idle,
402 First_Part => Large_Data_Transfer.First_Part_Sequence_Number);
403
404 -- Info in case of timeout handler call
405 Timeout_Info : Large_Data_Transfer.Receiver_Timeout;
406
407 -- Next timeout time
408 Next_Timeout_Time : Ada.Real_Time.Time;
409
410 --
411 -- Internal state switch procedures.
412 --
413 -- Conveinience functions wrapping common functionality
414 --
415
416 --% Subprogram:
417 -- Set super state idle
418 --% Parameter Constraints:
419 --> None
420 --% Exceptions Raised:
421 --> None
422
423 procedure Go_Idle;
424
425 end The_State;
426
427 end Large_Data_Transfer.receiver_State;
428
429 --~-----------------------------------------------------------------------------
430