summaryrefslogtreecommitdiff
path: root/cesar/cl/cl.h
blob: ce7831b78f6f125259d458e3552b826d5573707b (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
#ifndef CL_CL_H_
#define CL_CL_H_

/* Cesar project {{{
 *
 * Copyright (C) 2007 Spidcom
 *
 * <<<Licence>>>
 *
 * }}} */
/**
 * \file    cl/cl.h
 * \brief   Public functions
 * \ingroup cl
 *
 */

#include "mac/common/mfs.h"
#include "mac/common/store.h"
#include "lib/utils.h"
#include "mac/sar/sar.h"
#include "common/defs/igmp.h"

/** forward declaration. */
typedef struct cl_t cl_t;
typedef struct cl_send_t cl_send_t;

/**
 * Callback use to inform the upper layer when a data had been sent over the
 * PLC.
 *
 * \param  user  the user data
 * \param  buffer  the buffer use to send the data over the PLC.
 */
typedef void
(*cl_data_send_done_cb_t) (void *user, u8 *buffer);

/**
 * Callback to provide a received data to the upper layer coming from the SAR.
 *
 * \param  user  the user data
 * \param  buffer  the buffer containing the data
 * \param  length  the data length in the buffer.
 */
typedef void
(*cl_data_recv_cb_t) (void *user, u8 *buffer, uint length);

/**
 * Provides a MME buffer to the CP.
 *
 * \param  user_data  the layer data.
 * \param  buffer  the buffer to provide.
 */
typedef void
(*cl_mme_buffer_add_cb_t) (void *user_data, u8 *buffer);

/**
 * Call back to use when the CL needs to send a MME to the upper layer.
 *
 * \param  ul_data  the upper layer data provided on the registration.
 * \param  buffer  the buffer containing the MME.
 * \param  length  the length of the MME
 */
typedef void
(*cl_mme_ul_send_done_cb_t) (void *ul_data, u8 *buffer, uint length);

/**
 * Callback definition used by the CL when the CP had processed the MME
 * in the buffer. This will return the buffer to the upper layer.
 *
 * \param  user_data  the upper layer user data
 * \param  buffer  the buffer containing the MME.
 */
typedef void
(*cl_mme_ul_recv_done_cb_t) (void *user_data, u8 *buffer);

/**
 * Use this callback to provide a received MME to the CP.
 *
 * \param  user  user data
 * \param  tei  the station's source TEI.
 * \param  buffer  the buffer containing the MME.
 * \param  length  the MME length
 * \param  mme_recv  private data for the cl_mme.
 * \param  encryption  inform if the MF has been encrypted or not when it
 * arrives from the PWL.
 */
typedef void
(*cl_mme_recv_cb_t) (void *user, uint tei, u8 *buffer,
                     uint length, bool mme_recv, bool encryption);

BEGIN_DECLS

/**
 * Init the Convergence Layer and return a pointer on the CL context.
 *
 * \param  mac_store  the mac store.
 * \param  sar  the sar context.
 * \param  mac_config  the mac config.
 * \return  the convergence layer context.
 */
cl_t *
cl_init (mac_store_t *mac_store, sar_t *sar, mac_config_t *mac_config);

/**
 * Uninit the Convergence layer context.
 *
 * \param  ctx  the convergence layer context
 */
void
cl_uninit (cl_t *ctx);

/**
 * Initialize the CL to call the Upper layer once the CP ends processing the
 * MME.
 * Used each time the CP needs to send an MME to the upper layer.
 *
 * \param  ctx  the CL context
 * \param  cb  the upper layer callback to use to send an MME.
 * \param  user  the user data to provide with the callback
 */
void
cl_mme_ul_init_send_done (cl_t *ctx, cl_mme_ul_recv_done_cb_t cb,
                          void *user);

/**
 * Init the function call when an MME is received from the SAR or the HLE.
 * The CP registers its callback to allow the CL to call it each time a MME
 * is received from the PLC or the HLE.
 *
 * \param  ctx  the CL ctx
 * \param  mme_recv_cb
 * \param  user  the user data
 */
void
cl_mme_recv_init (cl_t *ctx, cl_mme_recv_cb_t mme_recv_cb, void *user);

/**
 * Initialize the CL to send MMEs to the Upper layer considered as data.
 * Used each time the CP needs to send an MME to the upper layer.
 *
 * \param  ctx  the CL context
 * \param  cb  the upper layer callback to use to send an MME.
 * \param  user  the user data to provide with the callback
 */
void
cl_mme_init_ul_as_data (cl_t *ctx, cl_mme_ul_send_done_cb_t cb, void *user);


/**
 * Initialize the CP call back to get a buffer.
 *
 * \param  cl  the cl context
 * \param  cb  the call back function
 * \param  user_data  the user data.
 */
void
cl_mme_init_buffer_add_cb (cl_t *cl, cl_mme_buffer_add_cb_t cb,
                           void *user_data);

/**
 * Send a MME from the CP to the Upper layer or to the PWL.
 *
 * \param ctx  the cl context.
 * \param  buffer  the buffer containing the data to send.
 * \param  length  the length of the MME.
 * \param  tei  the destination tei.
 *
 * The TEI can take the following values:
 *   * MAC_TEI_BCAST
 *   * MAC_TEI_UNASSOCIATED
 *   * MAC_TEI_MIN to MAC_TEI_MAX
 *   * MAC_TEI_FOREIGN
 */
void
cl_mme_send (cl_t *ctx, u8 *buffer, uint length, uint tei);

/**
 * Callback called by the sar when a MME as been sent over the PWL.
 *
 * \param  ctx  the cl context.
 * \param  buffer  the buffer used.
 * \param  cl_data  the data provided to the SAR on the send.
 */
void
cl_mme_sar_send_done (cl_t *ctx, u8 *buffer, void *cl_data);

/**
 * Receives an MME from the SAR or the upper layer.
 * This function is called each time the SAR or the HLE has an MME to send to
 * the CP. It is used by the inline function.
 * When the MFS is NULL the MME received comes from the HLE. Otherwise the MME
 * comes from the SAR.
 *
 * \param  ctx  the cl context
 * \param  buffer  the MME buffer
 * \param  length  the MME length
 * \param  mfs  the MFS used by the reassembly process.
 * \param  encryption  if the mac frame comes from the SAR if returns the
 * state of the encryption.
 */
void
cl_mme_recv (cl_t *ctx, u8 *buffer, uint length, mfs_rx_t *mfs,
             bool encryption);

/**
 * Receives an MME from the Upper layer.
 * It will provide this MME to the Control Plane to be processed.
 *
 * \param  ctx  the cl context
 * \param  buffer  the MME buffer
 * \param  length  the MME length
 */
extern inline void
cl_mme_ul_send (cl_t *ctx, u8 *buffer, uint length)
{
    cl_mme_recv (ctx, buffer, length, NULL, false);
}

/**
 * Receives an MME from the SAR.
 * It will provide this MME to the Control Plane to be processed.
 *
 * \param  ctx  the cl context
 * \param  buffer  the MME buffer
 * \param  length  the MME length
 * \param  mfs  the MFS used by the reassembly process.
 * \param  encryption  boolean informing if the MF was encrypted or not.
 */
extern inline void
cl_mme_sar_recv (cl_t *ctx, u8 *buffer, uint length,
                 mfs_rx_t *mfs, bool encryption)
{
    cl_mme_recv (ctx, buffer, length, mfs, encryption);
}

/**
 * The CP inform the CL that the buffer containing previously a received MME can
 * be use again to store another MME if necessary.
 *
 * \param  ctx  the CL context
 * \param  buffer  the buffer gived back.
 * \param  mme_recv  the data provided on the previous callback.
 */
void
cl_mme_recv_done (cl_t *ctx, u8 *buffer, bool mme_recv);

/**
 * Initialize the callback to inform the upper layer when a data had been sent
 * over the PWL.
 *
 * \param  cl  the CL context
 * \param  cb  the callback to call once the data had been sent
 * \param  user  the user data to provide with the callback call
 */
void
cl_data_send_done_init (cl_t *cl, cl_data_send_done_cb_t cb, void *user);

/**
 * The SAR inform the CL that the data previously provided had been sent over
 * the PLC.
 *
 * \param  ctx  the CL context.
 * \param  buffer  the buffer containing the MME
 * \param  cl_data  the data provided to the SAR on the msdu add.
 */
void
cl_data_send_done (cl_t *ctx, u8 *buffer, void *cl_data);

/**
 * Send a data from the upper layer to the SAR, this data should be sent over
 * the PWL.
 *
 * \param  ctx  the CL context.
 * \param  buffer  the buffer containing the data to send
 * \param  length  the data length
 * \param  tag  the upper layer tag.
 * \param  arrival_time_ntb  arrival time ntb.
 */
void
cl_data_send (cl_t *ctx, u8 *buffer, uint length, uint tag,
              u32 arrival_time_ntb);

/**
 * Initialize the callback to receive the data from the PLC to the upper layer.
 *
 * \param  cl  the CL context
 * \param  cb  the function callback to call
 * \param  user  the user data to provide on the callback.
 */
void
cl_data_recv_init (cl_t *cl, cl_data_recv_cb_t cb, void *user);

/**
 * Called by the SAR each time it has a data to provide to the CL.
 *
 * \param  ctx  the CL context
 * \param  buffer  the buffer containing the data to send to the Upper layer.
 * \param  length  the data length in the buffer
 * \param  mfs  the mfs used to receive the data.
 */
void
cl_data_recv (cl_t *ctx, u8 *buffer, uint length, mfs_rx_t *mfs);

/**
 * Provides a buffer to the CP.
 *
 * \param  cl  the CL context
 * \param  buffer  the buffer to reassembly some data
 */
void
cl_mme_buffer_add (cl_t *cl, u8 *buffer);

/**
 * Provides a buffer to the SAR to reassembly data
 *
 * \param  cl  the CL context
 * \param  buffer  the buffer to reassembly some data
 */
void
cl_data_buffer_add (cl_t *cl, u8 *buffer);

/**
 * Update the igmp groups based on the mactotei table.
 * \param  cl  the CL context.
 */
void
cl_update_igmp_groups (cl_t *ctx);

/**
 * Get the access to the igmp data in the cl context.
 * \param  cl  the CL context.
  * \return the pointer to the igmp data.
 */
igmp_groups_t *
cl_get_igmp_groups (cl_t *cl);

END_DECLS

#endif /* CL_CL_H_ */