Overview ======== Control plane is centered on the *STA core* module which control execution flow. .. figure:: overview.png :scale: 25 Control plane overview Modules ------- - beacon: handle beacon reception, emission and beacon period related functions (CA schedule, change count downs). - spoc: generate data needed by the hardware to correct frequency errors. - ntb: synchronise NTB on tracked beacon. - vstate_fsm: global FSM. - msg: message dispatching, encoding and decoding. - cl_interf: interface with the convergence layer, handle MME exchanges, buffers and reassembly. - secu: encryption and security related library. - cco: - action: CCo behaviour. - bw: Bandwidth manager. - region: Regions manager. - sta: - core: handle execution flow. - event_handler: interface to the FSM. - action: STA behaviour (power-on procedure, association, driver interface...) - data: database containing STA own data, list of discovered AVLN and list of STA for each AVLN. - mgr: handle complex data manipulations. - conn: connection database. - link: link database. Mechanisms ========== Messages reception flow ----------------------- Messages arrive at the *cl_interf* interface, in the CL context. The *cl_interf* module stores the message and its parameters in its FIFO and raises the *STA core* flag corresponding to *cl_interf*. When *STA core* sees the raised flag, it calls the *cl_interf* module back to handle the message in the CP context. The message is dropped if it is not addressed to our CP or has bad fragmentation information. If the received message is a fragment, its content is copied into blocks and appended in the reassembly context of the corresponding STA. If the message is not complete, stop here. The message is then given to the *msg* dispatch function. This function will handle encrypted messages, translate message types to FSM event, and post the corresponding event in the *event_handler* module. The *event_handler* module adds the event in the events FIFO and raises the *STA core* flag corresponding to *event_handler*. Once *STA core* sees this flag, it calls the *event_handler* module to handle waiting events in its FIFO. This function will pop the event from the FIFO, send it to the *FSM*, and finally release the event. The *FSM* module will call any function associated with the transitions triggered by the posted event. Usually, those functions will be located in the *STA action* or *CCo action* modules. A function handling a message will use the *msg* module to decode the message. It can then take any required action, like posting a response, or changing internal states. Messages transmission flow -------------------------- The *msg* module provides functions to build and send messages. Theses functions will: - ask the *cl_interf* for a new buffer, - fill headers, - fill data corresponding to the requested message type, - finalise the message, - send it to *cl_interf*. If the destination STA is a hidden STA, it will automatically encapsulate the message in a ``CC_RELAY.REQ``. The message will be encapsulated in a CM_ENCRYPTED_PAYLOAD.REQ if requested. Beacons reception flow ---------------------- Beacons are directly received by the *beacon* module. It stores the beacon in its FIFO and raises the *STA core* flag corresponding to *beacon*. When *STA core* sees the raised flag, it calls the *beacon* module to handle the beacon in the CP context. The *beacon* module reads the beacon and updates the CP database with information contained in it. If the beacon corresponds to the tracked AVLN, the *beacon* module also handles change countdowns and updates the CA schedule. In every cases, it posts the ``BEACON`` event, in order to trigger other modules actions if necessary. Each time the *beacon* module receives a beacon, it resets a timer to detect an eventual missed beacon on the next beacon period. Beacons transmission flow ------------------------- A timer programmed by the *beacon* module will trigger just before the beacon period end to prepare the beacon for the next period. When this timer expires, a event is posted to the FSM which will trigger a call to the *beacon* module. Then, the *beacon* module prepares the beacon and gives it to the data plane which will sent it when appropriated according to schedule. Messages reassembly ------------------- If a fragmented message is extracted from the *cl_interf* FIFO, its fragmentation information is checked. If all is in good shape, the message is copied into a list of 512 byte blocks which is attached to the transmitting station. If the message is out of sequence, it is dropped, and the current reassembly list for this station is cleared. The *bitstream* library will handle the decoding of blocks transparently. As the CP can be reassembling many different messages, it can not keep buffer internally because they are a sparse resource. Messages fragmentation ---------------------- To send a fragmented message, the *msg* module first computes the total message size, then constructs the message using the *bitstream* library. At each end of fragment, the *bitstream* will call a *msg* callback to send the fragment and start a new one. Core execution control ---------------------- The *STA core* module control execution flow in the control plane. It tests a event bit field in order to decide what to do and sleeps when no bit is set. The modules which use the *STA core* should have its own FIFO. When a module wants to be awaken by the *STA core*, it should put its data in its own FIFO and ask *STA core* to raise its event flag. The *STA core* will awake the CP once the flag is set and will call back the module which has set it. The module must then extract one event from its FIFO, handle it, and return. If there is still events in the FIFO, it should set the event flag again. The *STA core* also implements a garbage collector timer. It triggers about every second to do background cleanup in modules. The *STA core* will call every modules interested by this event. Here are the event flags, in priority order: beacon Set when the *beacon* module receives a beacon. FSM Set when a event is posted in the FSM FIFO. cl_interf Set when a message or a fragment is received in the *cl_interf*. garbage_collector Set every second. The *STA core* also provides timers related helpers. Enhanced bitstream library -------------------------- The *bitstream* library must be updated to handle multiple buffers. To do this, a callback is registered to *bitstream* to replace its buffer with a new one. To receive a fragmented message, when this callback will be called, it should give the next block in the list. To send a fragmented message, when this callback will be called, it should send the buffer, ask for a new one, fill header and give it to the *bitstream* library. MME handles ----------- MME header structure ~~~~~~~~~~~~~~~~~~~~ This contains: - peer TEI - peer MAC address - VLAN informations - MMTYPE When a response must be sent to a received message, the MME header structure can be used as a parameter for the MME to send. Received MME handle ~~~~~~~~~~~~~~~~~~~ .. figure:: mme_rx_handle.png :scale: 25 MME RX handle When a non fragmented message is received, the buffer is directly associated with the MME handle. The header is read by *cl_interf* and the *bitstream* points to data inside payload. When a fragmented message is received, the list of blocks is referenced by the MME handle. Headers are not present in the blocks, only payload. Once the *bitstream* arrives at buffer end, a callback is called which will replace the *bitstream* buffer with a new one. Modules details =============== Beacon ------ This module handles: - beacon reception and decoding, - beacon transmission and encoding, - CA schedule update, - beacon period change countdowns, - missed beacon. The received beacons are filtered according to there NID, SNID, and beacon type. If the beacon is a discovery beacon or does not correspond to our tracked NID and SNID, it is used to update the CP database. In other cases, it is used as our beacon, schedule is updated, change countdowns are set, hybrid mode is used, discover and/or proxy beacon are send. When the beacon is not received, the schedule is programmed using permanent information, countdowns are decremented and an event is generated to signal the beacon miss. Msg --- This module handles: - message decoding and encoding, - message transmission (get a buffer from *cl_interf*, fill header, encode, send), - message dispatching (translating between MMTYPE and FSM events), - message encryption/decryption, - message encapsulation/decapsulation for relay, - message filtering according to segment encryption. Messages dispatching ~~~~~~~~~~~~~~~~~~~~ This is called by *cl_interf* when a complete message has been received. The *cl_interf* module has read the MME header yet and the *bitstream* context is ready to read the payload. If the message is a encrypted message, it is first checked for coherency, then decrypted. If the decryption is successful and information is coherent, the message is decapsulated, and encryption information is stored in the MME handle. It is then treated like any other MME. If the decryption is not successful or there is any incoherent field, it is posted in the FSM queue with a special BAD_CM_ENCRYPTED_PAYLOAD_IND event. Then, the message is filtered according to its MMTYPE and segment encryption status and posted in the FSM queue with an event corresponding to its MMTYPE. Messages decoding ~~~~~~~~~~~~~~~~~ When a module receives a message from the FSM, it should use *msg* services to decode it. Most messages will be decoded with a function call to *msg*, using a structure as parameter which will be filled by the *msg* function. Some messages, like ``CC_SET_TEI_MAP.IND`` will also need a callback function which will be called for each received station. Messages encoding and transmission ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To send a message, a module should use a *msg* function which will ask for a new buffer, fill headers, encapsulate the message in a CC_RELAY.IND if necessary, and in a CM_ENCRYPTED_PAYLOAD.IND if requested. Most messages will be encoded with a function call to *msg*, using all messages fields as function parameters. Some messages, like ``CC_SET_TEI_MAP.IND`` will require that *msg* module uses the *STA mgr* interface to fetch data to send. SECU ---- This module handles: - AES: - encryption - decryption - SHA: - SHA256 - PBKDF1 - HomeplugAV: - NPW to NMK - NMK-SL to NID - random NMK generation - PRN procedure (start new, check, gen_next) It should behave as a separate library and will therefore not take the CP context as parameter. STA data & STA mgr ------------------ The *STA data* module maintains: - the STA own data - the network list - the STA list for each network It should keeps its information private. The *STA mgr* module is responsible for complex changes to *STA data* and can access private parts. Coding guidelines ================= Contexts -------- Each function in each module will receive the complete CP context as parameter. The CP context contains all the modules contexts, as value (for public context) or as pointer (for private ones). Naming conventions ------------------ Each function or types should be prefixed with the complete module name. For example, the ``choucroute`` function in the *STA action* module will be called ``cp_sta_action_choucroute``. CP development milestones ========================= Milestone 1 ----------- The first version will be able to: - play the power-on discovery procedure, - associate, authenticate and leave an AVLN, - act as a CCo to accept joining STA, - relay MME, only used to test the relay infrastructure, - use CSMA only schedule. This does not correspond yet to a CCo0. Handled MME messages -------------------- ========================= ==== =========== MME TYPE Milestone 1 ========================= ==== =========== CC_CCO_APPOINT REQ . .. CNF . CC_BACKUP_APPOINT REQ . .. CNF . CC_HANDOVER REQ . .. CNF . CC_LINK_INFO IND . .. RSP . CC_HANDOVER_INFO IND . .. RSP . CC_DISCOVER_LIST REQ . .. CNF . .. IND . CC_LINK_NEW REQ . .. CNF . CC_LINK_MOD REQ . .. CNF . CC_LINK_SQZ REQ . .. CNF . CC_LINK_REL REQ . .. CNF . CC_DETECT_REPORT REQ . .. CNF . CC_WHO_RU REQ X .. CNF X CC_ASSOC REQ X .. CNF X CC_LEAVE REQ X .. CNF X .. IND X .. RSP X CC_SET_TEI_MAP REQ . .. IND X CC_RELAY REQ X .. IND X CC_BEACON_RELIABILITY REQ . .. CNF . CC_ALLOC_MOVE REQ . .. CNF . CC_ACCESS all . CC_DCPPC IND . .. RSP . CC_HP1_DET REQ . .. CNF . CC_BLE_UPDATE IND . CP_* all . PH_* all . NN_* all . CM_UNASSOCIATED_STA IND X CM_ENCRYPTED_PAYLOAD IND X .. RSP X CM_SET_KEY REQ X .. CNF X CM_GET_KEY REQ X .. CNF X CM_SC_JOIN REQ . .. CNF . CM_CHAN_EST IND X CM_TM_UPDATE IND X CM_AMP_MAP REQ . .. CNF . CM_BRG_INFO REQ . .. CNF . CM_CONN_NEW REQ . .. CNF . CM_CONN_REL IND . .. CNF . CM_CONN_MOD REQ . .. CNF . CM_CONN_INFO REQ . .. CNF . CM_STA_CAP all . CM_NW_INFO all . CM_GET_BEACON all . CM_HFID all . CM_MME_ERROR IND X CM_NW_STATS REQ . .. CNF . CM_LINK_STATS REQ . .. CNF . ========================= ==== ===========