summaryrefslogtreecommitdiff
path: root/cesar/mac/sar/sar.h
blob: 6939f84b7617e986ec769342f6cd0be95bfe9d76 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
#ifndef MAC_SAR_SAR_H_
#define MAC_SAR_SAR_H_

/* Cesar project {{{
 *
 * Copyright (C) 2007 Spidcom
 *
 * <<<Licence>>>
 *
 * }}} */
/**
 * \file    mac/sar/sar.h
 * \brief   Public intefaces of the SAR.
 * \ingroup mac_sar
 *
 */

#include "mac/common/store.h"
#include "mac/pbproc/pbproc.h"
#include "mac/sar/sar_mfs_expiration_cb.h"
#include "mac/sar/sar_mf.h"

/* forward declaration */
typedef struct sar_t sar_t;

/**
 * Call back prototype to provide measure to the CE.
 * \param  data  the context of the CE RX.
 * \param  rx_params  general information on measures (date, from).
 * \param  total_pb_count  number of PB available in the frame.
 * \param  chan_data  the head of the channel data.
 * \param  chan_data_count  the count of PBs in the channel data.
 * \param  false_pb_count  number of false PBs (CRC error) inside the frame.
 * \param  ber_sum  sum of each BER of each PBs with no CRC error inside the
 * frame
 */
typedef void
(*sar_measurement_cb_t) (void *data, pbproc_rx_params_t *rx_params,
                         uint total_pb_count, pb_t *chan_data,
                         uint chan_data_count, u8 false_pb_count,
                         u32 ber_sum);

/**
 * Segmentation job done for the segmentation module, it send a data to inform
 * the upper layer that a job had been processed.
 *
 * \param  user upper layer context
 * \param  buffer the buffer which is no more used.
 * \param  user_data data provided by the upper layer on the MSDU add.
 *
 * The MFS reference is given to the CL it do not make a addref on it.
 */
typedef void
(*sar_segmentation_done_cb_t) (void *user, u8* buffer, void *user_data);

/**
 * Inform the upper layer that the buffer given in parameter is not used anymore.
 *
 * \param  user upper layer context pointer
 * \param  buffer the buffer which is no more used.
 * \param  length the length of the buffer.
 * \param  mfs  the MFS used to reassembly the packet.
 * \param  encrypted  true if the MF has been encrypted, false otherwise. This
 * is only valid for the MME, the DATA are dropped if it is not encrypted.
 *
 * The MFS reference is given to the CL it do not make a addref on it.
 */
typedef void
(*sar_reassembly_done_cb_t) (void *user, u8* buffer,
        uint length, mfs_rx_t *mfs, bool encrypted);

/**
 * Provides the beacon to the Control Plane
 *
 * \param  user user data
 * \param  beacon the beacon data
 * \param  params  the rx params at the pb reception
 */
typedef void
(*sar_beacon_cb_t) (void *user, pb_beacon_t *pb,
        pbproc_rx_beacon_params_t *params);

BEGIN_DECLS

/**
 * Initialize the SAR context.
 * \param  mac_store  the mac store
 * \param  pbproc  the PBProc context.
 * \param  ca  the Channel Access context.
 * \return  the SAR context.
 */
sar_t *
sar_init (mac_store_t *mac_store, pbproc_t *pbproc, ca_t *ca, u32 seed);

/**
 * Release all the data used in the sar.
 * \param  ctx the sar context.
 */
void
sar_uninit (sar_t *ctx);

/**
 * Initialise the SAR callback for DATA reception.
 * \param  ctx the SAR context
 * \param  user the upper layer data context.
 *
 * This should be called once the reassembly process has been done.
 */
void
sar_init_data_context (sar_t *ctx, void *user);

/**
 * Initialise the SAR callback for MME reception.
 * \param  ctx the SAR context
 * \param  user the upper layer MSG context.
 *
 * This should be called once the reassembly process has been done.
 */
void
sar_init_mme_context (sar_t *ctx, void *user);

/**
 * Initialise the SAR callback for Measure reception.
 * \param  ctx the SAR context
 * \param  user the upper layer MSG context.
 *
 * This only store the user data from the client in the SAR context. Two
 * others API are available to provide the function to call on BER measurement
 * and Channel data.
 */
void
sar_init_measure_context (sar_t *ctx, void *user);

/**
 * Initialise the SAR with the function to call to inform when the MME is
 * provided to the PB Processing layer.
 * \param  ctx the SAR context
 * \param sar_seg_done  the function to call.
 *
 * When the callback is called the MME is still not sent by the PBProc but
 * only provided to it. The PBProc has for job to sent it when it have the
 * possibility on the medium.
 */
void
sar_init_segmentation_mme_cb (sar_t *ctx,
                              sar_segmentation_done_cb_t sar_mme_seg_done);

/**
 * Initialise the SAR with the function to call to inform when the DATA is
 * provided to the PB Processing layer.
 * \param  ctx the SAR context
 * \param sar_seg_done  the function to call.
 *
 * When the callback is called the DATA is still not sent by the PBProc but
 * only provided to it. The PBProc has for job to sent it when it have the
 * possibility on the medium.
 */
void
sar_init_segmentation_data_cb (sar_t *ctx,
                               sar_segmentation_done_cb_t sar_data_seg_done);

/**
 * Initialize the callback to send the measurement contained in the PBs.
 * \param  ctx the SAR context
 * \param  sar_measurement the function to call.
 */
void
sar_init_measurement_cb (sar_t *ctx,
                         sar_measurement_cb_t sar_measurement);

/**
 * Add a buffer address to the SAR to bridge pending jobs.
 * \param  ctx the SAR context to add a buffer
 * \param  buffer_addr the buffer address to add to the SAR in order to bridge
 * the pending jobs.
 * \param  data if it is a data buffer.
 */
void
sar_buffer_add (sar_t *ctx, u8* buffer_addr, bool data);

/**
 * Add a buffer address to the SAR to bridge pending jobs.
 * \param  ctx the SAR context to add a buffer
 * \param  buffer_addr the buffer address to add to the SAR in order to bridge
 * the pending jobs.
 */
extern inline void
sar_data_buffer_add (sar_t *ctx, u8* buffer_addr)
{
    sar_buffer_add (ctx, buffer_addr, true);
}

/**
 * Add a buffer address to the SAR to bridge pending jobs.
 * \param  ctx the SAR context to add a buffer
 * \param  buffer_addr the buffer address to add to the SAR in order to bridge
 * the pending jobs.
 */
extern inline void
sar_mme_buffer_add (sar_t *ctx, u8* buffer_addr)
{
    sar_buffer_add (ctx, buffer_addr, false);
}

/**
 * Initialise the SAR to call the function on each new frame available.
 * \param  ctx the SAR context
 * \param  sar_rea_done  function to call.
 * \param  data  a boolean to indicate if it is a DATA stream or MME.
 */
void
sar_init_reassembly_ul (sar_t *ctx,
                        sar_reassembly_done_cb_t sar_rea_done,
                        bool data);

/**
 * Initialise the SAR to call the function on each new MME available.
 * \param  ctx the SAR context
 * \param  sar_mme_reassembly_done  function to call.
 */
extern inline void
sar_init_reassembly_mme_cb (sar_t *ctx,
                            sar_reassembly_done_cb_t sar_mme_reassembly_done)
{
    sar_init_reassembly_ul (ctx, sar_mme_reassembly_done, false);
}

/**
 * Initialise the SAR to call the function on each new DATA available.
 * \param  ctx the SAR context
 * \param  sar_data_reassembly_done  function to call.
 */
extern inline void
sar_init_reassembly_data_cb (sar_t *ctx,
                    sar_reassembly_done_cb_t sar_data_reassembly_done)
{
    sar_init_reassembly_ul (ctx, sar_data_reassembly_done, true);
}

/**
 * Add a received MPDU RX to be processed.
 * \param  user  user data
 * \param  rx_desc  received MPDU block descriptor
 *
 * See pbproc_rx_cb_t.
 */
void
sar_mpdu_add (void *user, pbproc_rx_desc_t *rx_desc);

/**
 * Add a Mac Frame to send by over the medium.
 * \param  ctx  sar context
 * \param  buffer  the buffer containing the Mac Frame.
 * \param  length  the length of the Mac Frame.
 * \param  mfs  the MFS to stock the PB generated
 * \param  user_data  opaque object.
 * \param  arrival_time_ntb  the arrival time of the MSDU in the station.
 *
 * user_data is an opaque object given back once the segmentation is done.
 */
void
sar_msdu_add (sar_t *ctx, u8 *buffer, u16 length,
              mfs_tx_t *mfs, void *user_data,
              u32 arrival_time_ntb);

/**
 * Add an MFS to the SAR expiration mechanism.
 * \param  ctx  the SAR context
 * \param  mfs  the MFS to add to the SAR.
 *
 * Always called in DSR context.
 */
void
sar_mfs_add (sar_t *ctx, mfs_t *mfs);

/**
 * Put the MFS in the release state.
 * \param  ctx  the SAR context
 * \param  mfs  the MFS to remove from the SAR.
 */
void
sar_mfs_remove (sar_t *ctx, mfs_t *mfs);

/**
 * Initialise the SAR to call the function on beacon reception.
 * \param  ctx  the SAR context
 * \param  user_data
 * \param  uf_upper_layer function to call
 */
void
sar_init_beacon_cb (sar_t *sar, void *user_data, sar_beacon_cb_t uf);

/**
 * Function to receive a beacon from the medium.
 * \param  sar  the SAR context
 * \param  pb  pb containing the beacon
 * \param  params  the rx params.
 *
 * This function is called by the pbproc using a callback.
 */
void
sar_beacon_add (void *sar, pb_beacon_t *pb,
                pbproc_rx_beacon_params_t *params);

/**
 * Request the SAR to send a beacon.
 * \param  ctx  the SAR context.
 * \param  beacon  the beacon to send.
 * \param  beacon_mfs  the MFS use to send the beacon
 * \param  bto_bpsto  the address to provide to the pbproc.
 */
void
sar_beacon_send (sar_t *sar, pb_beacon_t *beacon, mfs_tx_t *beacon_mfs,
                 void *bto_bpsto);

/**
 * Remove a station from the SAR and the mac store.
 * \param  ctx  the ctx context.
 * \param  tei  the station TEI.
 *
 * Remove all the MFS from the expiration mechanism of the SAR and ends to
 * remove the station from the mac store.
 */
void
sar_sta_remove (sar_t *ctx, u8 tei);

/**
 * SAR Activate.
 * \param  ctx  the SAR context.
 * \param  activate  true to activate, false to disable.
 */
void
sar_activate (sar_t *ctx, bool activate);

/**
 * SAR clean up all the MFS in the store and the SAR.
 * \param  ctx  the SAR context.
 */
void
sar_cleanup (sar_t *ctx);

/**
 * SAR function callback to release a MFS.
 * \param  ctx  the SAR context.
 * \param  mfs  the MFS to release.
 *
 * \warn: This function should only post a message in SAR's mailbox.
 */
void
sar_mfs_cmd (sar_t *ctx, mfs_tx_t *mfs);


/**
 * Remove the MFS from Datapath layers.
 * \param  ctx the context.
 * \param  mfs  the MFS.
 *
 * It removes the MFS from the CA.
 * Request the PBProc to release all the PBs.
 * Remove the MFS from the expiration mechanism.
 * Remove the MFS from the STORE.
 *
 * \warn  the user reference must be released by the user.
 * This function should be always called with DSR locked.
 */
void
sar_mfs_free_tx (sar_t *ctx, mfs_tx_t *mfs);

/**
 * Remove the MFS from the datapath layers.
 * \param  ctx  the context.
 * \param  mfs  the MFS RX to remove.
 *
 * Remove the MFS from the expiration mechanism.
 * Remove the MFS from the STORE.
 *
 * \warn  the user reference must be released by the user.
 * This function should be always called with DSR locked.
 */
void
sar_mfs_free_rx (sar_t *ctx, mfs_rx_t *mfs);

/**
 * Callback which active the pb_stats module
 * \param  state  Value found in internal.conf file.
 */
void
sar_pb_stats_load_write_cb (u64 state);

/**
 * Callback which indicate if the module is activated
 * \return  state  if not zero then the module is loaded
 */
u8*
sar_pb_stats_load_read_cb (void);

END_DECLS

#endif /*MAC_SAR_SAR_H_*/