Lines Matching full:frame
30 * This file contains definitions for the NCP frame buffer class.
46 …* A frame can consist of a sequence of data bytes and/or the content of an `otMessage` or a combin…
58 …* Defines the priority of a frame. High priority frames are read before low priority frames. Withi…
64 kPriorityLow = 0, ///< Indicates low/normal priority for a frame.
65 kPriorityHigh = 1, ///< Indicates high priority for a frame.
69 …* Defines the (abstract) frame tag type. The tag is a unique value (within currently queued frames…
70 … * with a frame in the `Buffer`. Frame tags can be compared with one another using operator `==`.
76 * Defines the tag value indicating an invalid tag (e.g., when there is no frame).
82 * Defines the structure to hold a write position for an input frame (frame being written).
109 * frame is added/written to `Buffer` or when a frame is removed from `Buffer`.
112 * @param[in] aTag The tag associated with the frame which is added or removed.
113 * @param[in] aPriority The priority of frame.
120 * Initializes an NCP frame buffer.
122 … * @param[in] aBuffer A pointer to a buffer which will be used by NCP frame buffer.
129 * Clears the NCP frame buffer. All the frames are cleared/removed.
139 …* @param[in] aFrameAddedCallback Callback invoked when a new frame is successfully added to buff…
140 … * @param[in] aFrameAddedContext A pointer to arbitrary context used with frame added callback.
150 * @param[in] aFrameRemovedCallback Callback invoked when a frame is removed from buffer.
151 …* @param[in] aFrameRemovedContext A pointer to arbitrary context used with frame removed callback.
157 * Begins a new input frame (InFrame) to be added/written to the frame buffer.
159 …* If there is a previous frame being written (for which `InFrameEnd()` has not yet been called), c…
160 * `InFrameBegin()` will discard and clear the previous unfinished frame.
162 * @param[in] aPriority Priority level of the new input frame.
168 * Adds a single byte to current input frame.
170 …this method `InFrameBegin()` must be called to start and prepare a new input frame. Otherwise, this
173 …* If no buffer space is available, this method will discard and clear the current input frame and …
176 * @param[in] aByte The byte value to add to input frame.
178 * @retval OT_ERROR_NONE Successfully added given byte to the frame.
180 …* @retval OT_ERROR_INVALID_STATE `InFrameBegin()` has not been called earlier to start the frame.
186 * Adds data to the current input frame.
188 …this method `InFrameBegin()` must be called to start and prepare a new input frame. Otherwise, this
191 …* If no buffer space is available, this method will discard and clear the current input frame and …
197 * @retval OT_ERROR_NONE Successfully added new data to the frame.
199 …* @retval OT_ERROR_INVALID_STATE `InFrameBegin()` has not been called earlier to start the frame.
206 * Adds a message to the current input frame.
208 …this method `InFrameBegin()` must be called to start and prepare a new input frame. Otherwise, this
211 …* If no buffer space is available, this method will discard and clear the frame and return error s…
214 …he ownership of the passed-in message @p aMessage changes to `Buffer` ONLY when the entire frame is
215 … finished (i.e., with a successful call to `InFrameEnd()` for the current input frame), and in this
216 …* case the `otMessage` instance will be freed once the frame is removed (using `OutFrameRemove()`)…
217 …* However, if the input frame gets discarded before it is finished (e.g., running out of buffer sp…
220 * @param[in] aMessage A message to be added to current frame.
222 * @retval OT_ERROR_NONE Successfully added the message to the frame.
224 …* @retval OT_ERROR_INVALID_STATE `InFrameBegin()` has not been called earlier to start the frame.
232 * Gets the current write position in the input frame.
234 …e position is returned in @p aPosition. The saved position can later be used to overwrite the frame
235 …* content (using `InFrameOverwrite()`) or discard a portion of written frame and move the write po…
241 …* @retval OT_ERROR_INVALID_STATE `InFrameBegin()` has not been called earlier to start the frame.
247 … * Overwrites the previously written content in the current input frame at a given write position.
249 …* The write position @p aPostion must belong to the same input frame saved earlier with `InFrameGe…
250 … * Does not allow writing beyond the current end of the input frame (i.e., it can only write over
252 …* the end, this method does not change the input frame and returns error status `OT_ERROR_INVALID_…
253 * Cannot be used if the input frame has an added `otMessage` (i.e., a previous call to
261 * @retval OT_ERROR_INVALID_STATE No input frame (`InFrameBegin()` has not been called).
263 …* input frame), or the input frame has an added `otMessage`, or t…
264 * operation will go beyond the current end of the input frame.
270 * Resets the write position of input frame back to a previously saved position. Any previously
273 …* The write position @p aPosition must belong to the same input frame saved earlier with `InFrameG…
274 * Cannot be used if the input frame has an added `otMessage` (i.e., a previous call to
279 … * @retval OT_ERROR_NONE Successfully reset the write position of current input frame..
280 * @retval OT_ERROR_INVALID_STATE No input frame (`InFrameBegin()` has not been called).
281 …ROR_INVALID_ARGS The given write position is not valid (does not belong to same input frame), or
282 * the input frame has an added `otMessage`.
288 * Gets the distance (number of bytes) from a given saved position to current end of frame.
290 …* The write position @p aPosition must belong to the same input frame saved earlier with `InFrameG…
291 * Cannot be used if the input frame has an added `otMessage` (i.e., a previous call to
296 …* @returns The distance (number of bytes) from a write position to current end of frame, or zero f…
303 * Finalizes/ends the current input frame being written to the buffer.
305 …this method `InFrameBegin()` must be called to start and prepare a new input frame. Otherwise, this
308 …* If no buffer space is available, this method will discard and clear the frame and return error s…
311 * @retval OT_ERROR_NONE Successfully ended the input frame.
313 …* @retval OT_ERROR_INVALID_STATE `InFrameBegin()` has not been called earlier to start the frame.
319 … * Returns the tag assigned to last successfully written/added frame to NcpBuffer (i.e., last input
320 …* frame for which `InFrameEnd()` was called and returned success status). The tag is a unique valu…
321 …* currently queued frames) associated with a frame in the `Buffer`. The tag can be used to identif…
322 …* same frame when it is read and removed from the NcpBuffer. Tags can be compared using operator `…
324 …* @returns The tag of the last successfully written frame, or `kInvalidTag` if no frame is written…
329 … * Checks if the buffer is empty. A non-empty buffer contains at least one full frame for reading.
331 …* @retval TRUE Buffer is not empty and contains at least one full frame for re…
332 * @retval FALSE Buffer is empty and contains no frame for reading.
338 …* Begins/prepares an output frame to be read from the frame buffer if there is no current active o…
339 * frame, or resets the read offset if there is a current active output frame.
341 … buffer maintains a read offset for the current frame being read. Before reading any bytes from th…
342 * this method should be called to prepare the frame and set the read offset.
344 …* If part or even all of current frame has been read, a sub-sequent call to this method will rese…
345 …* offset back to beginning of current output frame (note that the current output frame will remain…
346 …* in case where a higher priority frame was written to buffer while reading current output frame).…
347 …* output frame will stay active as current output frame until it is explicitly removed using `OutF…
349 … * @retval OT_ERROR_NONE Successfully started/prepared a new output frame for reading.
350 * @retval OT_ERROR_NOT_FOUND No frame available in buffer for reading.
356 * Checks if the current output frame (being read) has ended.
358 …* The NCP buffer maintains a read offset for the current output frame being read. This method retu…
359 …* the read offset has reached the end of the frame and there are no more bytes available to read, …
360 * no currently active output frame.
362 …* @retval TRUE Frame has ended (no more bytes available to read from current o…
363 * there is currently no prepared/active output frame.
364 * @retval FALSE Frame still has more data to read.
370 * Reads and returns the next byte from the current output frame.
372 …* The NCP buffer maintains a read offset for the current output frame being read. This method read…
373 …* the next byte from the current frame and moves the read offset forward. If read offset is alread…
374 * current output frame, this method returns zero.
376 …* @returns The next byte from the current output frame or zero if current output frame has ended o…
383 * Reads and copies bytes from the current output frame into a given buffer.
385 …* The NCP buffer maintains a read offset for the current output frame being read. This method atte…
386 …* the given number of bytes (@p aReadLength) from the current frame and copies the bytes into the …
388 …* remaining in current frame than the requested @p aReadLength, the available bytes are read/copie…
389 * returns the number of bytes read from frame and copied into @p aDataBuffer.
400 * Removes the current or front output frame from the buffer.
402 …* If there is an active output from being read (an output frame was prepared earlier with a succes…
403 …egin()`), this method removes the current active output frame. If there is no current active frame,
404 * the front frame in the queue (the next frame which would have been read) will be removed.
406 * When a frame is removed all its associated messages will be freed.
411 * @retval OT_ERROR_NONE Successfully removed the front frame.
412 * @retval OT_ERROR_NOT_FOUND No frame available in NCP frame buffer to remove.
418 * Returns the number of bytes (length) of current or front frame in the NCP frame buffer.
420 …* If there is an active output from being read (an output frame was prepared earlier with successf…
421 …* `OutFrameBegin()`), this method returns the length of the current output frame. If there is no c…
422 …* frame, the length of the front frame in the queue (the next frame which would have been read) wi…
424 * If there is no frame in buffer, this method returns zero.
426 * @returns The number of bytes (length) of current/front frame, or zero if no frame in buffer.
432 * Returns the tag value associated to current or front frame in the NCP frame buffer.
434 …* If there is an active output from being read (an output frame was prepared earlier with successf…
435 …* `OutFrameBegin()`), this method returns the tag associated with current output frame. If there i…
436 …* active frame, the tag associated with the front frame in the queue (the next frame which would h…
439 * If there is no frame in buffer, this method returns `kInvalidTag`.
441 …* @returns The tag assigned to the current/from output frame, or `kInvalidTag` if no frame in buff…
451 …* `Buffer` internally stores a frame as a sequence of data segments. Each segment stores a portion…
452 …* frame. The data segments are stored in the main buffer `mBuffer`. `mBuffer` is utilized as a cir…
462 * Bit 15: Flag bit set to indicate that this segment defines the start of a new frame.
466 * | New Frame | Has Message | Length of segment (excluding the header) |
471 * Consider the following calls to create a frame:
480 * This frame is stored as two segments:
483 …* data bytes, and it starts a new frame, and also includes an appended message from the messa…
494 …* `Buffer` uses the `mBuffer` as a circular/ring buffer. To support two frame priorities the buffe…
497 * available buffer space is utilized efficiently between all frame types.
518 …* For an output frame (frame being read), Buffer maintains a `ReadState` along with a set of point…
521 * mReadFrameStart[priority]: Start of the current/front frame.
531 … ... | Segment 1 | Segment 2 | ... | Last Segment | ... (possible) next frame
540 …* Note that the diagram above shows the pointers for a low-priority frame (with pointers increasin…
543 …* The `ReadState` indicates the state of current output frame and its read offset (e.g., if read o…
544 …le of a segment or if it is is middle of an appended message, or if we are done with entire frame).
546 * For an input frame (frame being written), the following pointers are maintained:
548 * mWriteFrameWrite[priority]: Start of the current/next frame being written.
550 … | mWriteSegmentHead: Start of the current segment of the active input frame.
570 kReadByteAfterFrameHasEnded = 0, // Value returned by ReadByte() when frame has ended.
572 kUnknownFrameLength = 0xffff, // Value used when frame length is unknown.
575 kMaxSegments = 10, // Max number of segments allowed in a frame
578 … kSegmentHeaderNewFrameFlag = (1 << 15), // Indicates that this segment starts a new frame.
586 kReadStateNotActive, // No current prepared output frame.
587 kReadStateInSegment, // In middle of a data segment while reading current frame.
588 kReadStateInMessage, // In middle of a message while reading current frame.
589 kReadStateDone, // Current output frame is read fully.
627 BufferCallback mFrameAddedCallback; // Callback to signal when a new frame is added
629 BufferCallback mFrameRemovedCallback; // Callback to signal when a frame is removed.
632 Direction mWriteDirection; // Direction (priority) for current frame being read.
633 uint8_t *mWriteFrameStart[kNumPrios]; // Pointer to start of current frame being written.
634 …uint8_t *mWriteSegmentHead; // Pointer to start of current segment in the frame being w…
635 …uint8_t *mWriteSegmentTail; // Pointer to end of current segment in the frame being wri…
636 FrameTag mWriteFrameTag; // Tag associated with last successfully written frame.
638 Direction mReadDirection; // Direction (priority) for current frame being read.
640 uint16_t mReadFrameLength; // Length of current frame being read.
642 uint8_t *mReadFrameStart[kNumPrios]; // Pointer to start of current frame being read.
643 …uint8_t *mReadSegmentHead; // Pointer to start of current segment in the frame being rea…
644 … uint8_t *mReadSegmentTail; // Pointer to end of current segment in the frame being read.
648 …otMessageQueue mWriteFrameMessageQueue; // Message queue for the current frame bein…
650 … otMessage *mReadMessage; // Current Message in the frame being read.