#ifndef CL_CL_H_ #define CL_CL_H_ /* Cesar project {{{ * * Copyright (C) 2007 Spidcom * * <<>> * * }}} */ /** * \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_ */