cdc_queue.h File Reference

Header for cdc_queue.c module. More...

#include <stdbool.h>
#include "usbd_def.h"

Classes
struct	CDC_TransmitQueue_TypeDef
	Transmit queue: ring buffer filled by the application and drained by USB IN transfers. More...
struct	CDC_ReceiveQueue_TypeDef
	Receive queue: ring buffer filled by USB OUT transfers and drained by the application. More...

Macros
#define	CDC_QUEUE_MAX_PACKET_SIZE   USB_FS_MAX_PACKET_SIZE
	Maximum size, in bytes, of one USB packet handled by the queues.
#define	CDC_TRANSMIT_QUEUE_BUFFER_PACKET_NUMBER   2
	Number of packets the transmit queue buffer can hold.
#define	CDC_RECEIVE_QUEUE_BUFFER_PACKET_NUMBER   3
	Number of packets the receive queue buffer can hold.
#define	CDC_TRANSMIT_QUEUE_BUFFER_SIZE   ((uint16_t)(CDC_QUEUE_MAX_PACKET_SIZE * CDC_TRANSMIT_QUEUE_BUFFER_PACKET_NUMBER))
	Size, in bytes, of the transmit queue buffer.
#define	CDC_RECEIVE_QUEUE_BUFFER_SIZE   ((uint16_t)(CDC_QUEUE_MAX_PACKET_SIZE * CDC_RECEIVE_QUEUE_BUFFER_PACKET_NUMBER))
	Size, in bytes, of the receive queue buffer.

Functions
void	CDC_TransmitQueue_Init (CDC_TransmitQueue_TypeDef *queue)
	Initialize read and write position of the transmit queue.
int	CDC_TransmitQueue_WriteSize (CDC_TransmitQueue_TypeDef *queue)
	Get the free space available for writing into the transmit queue.
int	CDC_TransmitQueue_ReadSize (CDC_TransmitQueue_TypeDef *queue)
	Get the amount of data stored in the transmit queue.
void	CDC_TransmitQueue_Enqueue (CDC_TransmitQueue_TypeDef *queue, const uint8_t *buffer, uint32_t size)
	Copy data into the transmit queue, wrapping at the end of the buffer.
uint8_t *	CDC_TransmitQueue_ReadBlock (CDC_TransmitQueue_TypeDef *queue, uint16_t *size)
	Get a contiguous block of queued data to transmit.
void	CDC_TransmitQueue_CommitRead (CDC_TransmitQueue_TypeDef *queue)
	Release the block returned by CDC_TransmitQueue_ReadBlock().
void	CDC_ReceiveQueue_Init (CDC_ReceiveQueue_TypeDef *queue)
	Initialize read and write position of the receive queue.
int	CDC_ReceiveQueue_ReadSize (CDC_ReceiveQueue_TypeDef *queue)
	Get the amount of data available for reading from the receive queue.
int	CDC_ReceiveQueue_Dequeue (CDC_ReceiveQueue_TypeDef *queue)
	Read and remove one byte from the receive queue.
int	CDC_ReceiveQueue_Peek (CDC_ReceiveQueue_TypeDef *queue)
	Read one byte from the receive queue without removing it.
uint16_t	CDC_ReceiveQueue_Read (CDC_ReceiveQueue_TypeDef *queue, uint8_t *buffer, uint16_t size)
	Read and remove up to size bytes from the receive queue.
bool	CDC_ReceiveQueue_ReadUntil (CDC_ReceiveQueue_TypeDef *queue, uint8_t terminator, uint8_t *buffer, uint16_t size, uint16_t *fetched)
	Read and remove bytes from the receive queue up to a terminator.
uint8_t *	CDC_ReceiveQueue_ReserveBlock (CDC_ReceiveQueue_TypeDef *queue)
	Reserve space in the receive queue for an incoming packet.
void	CDC_ReceiveQueue_CommitBlock (CDC_ReceiveQueue_TypeDef *queue, uint16_t size)
	Commit bytes written to a block returned by CDC_ReceiveQueue_ReserveBlock().

Detailed Description

Header for cdc_queue.c module.

Author

makarenya

Version

V1.0.0

Date

23-December-2018

Attention

© COPYRIGHT(c) 2016 STMicroelectronics

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. Neither the name of STMicroelectronics nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Macro Definition Documentation

CDC_QUEUE_MAX_PACKET_SIZE

#define CDC_QUEUE_MAX_PACKET_SIZE   USB_FS_MAX_PACKET_SIZE

Maximum size, in bytes, of one USB packet handled by the queues.

Depends on the USB speed in use (high speed or full speed).

CDC_RECEIVE_QUEUE_BUFFER_PACKET_NUMBER

#define CDC_RECEIVE_QUEUE_BUFFER_PACKET_NUMBER   3

Number of packets the receive queue buffer can hold.

Can be overridden.

CDC_TRANSMIT_QUEUE_BUFFER_PACKET_NUMBER

#define CDC_TRANSMIT_QUEUE_BUFFER_PACKET_NUMBER   2

Number of packets the transmit queue buffer can hold.

Can be overridden.

Function Documentation

CDC_ReceiveQueue_CommitBlock()

void CDC_ReceiveQueue_CommitBlock	(	CDC_ReceiveQueue_TypeDef *	queue,
		uint16_t	size
	)

Commit bytes written to a block returned by CDC_ReceiveQueue_ReserveBlock().

Parameters

queue	receive queue.
size	number of bytes written into the reserved block.

CDC_ReceiveQueue_Dequeue()

int CDC_ReceiveQueue_Dequeue

(

CDC_ReceiveQueue_TypeDef *

queue

)

Read and remove one byte from the receive queue.

Parameters

queue

receive queue.

Returns

byte value (0-255), or -1 if the queue is empty.

CDC_ReceiveQueue_Init()

void CDC_ReceiveQueue_Init

(

CDC_ReceiveQueue_TypeDef *

queue

)

Initialize read and write position of the receive queue.

Parameters

queue

receive queue to initialize.

CDC_ReceiveQueue_Peek()

int CDC_ReceiveQueue_Peek

(

CDC_ReceiveQueue_TypeDef *

queue

)

Read one byte from the receive queue without removing it.

Parameters

queue

receive queue.

Returns

byte value (0-255), or -1 if the queue is empty.

CDC_ReceiveQueue_Read()

uint16_t CDC_ReceiveQueue_Read	(	CDC_ReceiveQueue_TypeDef *	queue,
		uint8_t *	buffer,
		uint16_t	size
	)

Read and remove up to size bytes from the receive queue.

Parameters

queue	receive queue.
buffer	destination buffer.
size	maximum number of bytes to read.

Returns

number of bytes copied into buffer.

CDC_ReceiveQueue_ReadSize()

int CDC_ReceiveQueue_ReadSize

(

CDC_ReceiveQueue_TypeDef *

queue

)

Get the amount of data available for reading from the receive queue.

Parameters

queue

receive queue.

Returns

number of bytes available to read.

CDC_ReceiveQueue_ReadUntil()

bool CDC_ReceiveQueue_ReadUntil	(	CDC_ReceiveQueue_TypeDef *	queue,
		uint8_t	terminator,
		uint8_t *	buffer,
		uint16_t	size,
		uint16_t *	fetched
	)

Read and remove bytes from the receive queue up to a terminator.

Note

The terminator is consumed but not copied into buffer. If the terminator is not found, up to size bytes are read and removed.

Parameters

queue	receive queue.
terminator	byte that ends the read.
buffer	destination buffer.
size	maximum number of bytes to copy into buffer.
fetched	output: number of bytes copied into buffer, excluding the terminator.

Returns

true if the terminator was found, false otherwise.

CDC_ReceiveQueue_ReserveBlock()

uint8_t * CDC_ReceiveQueue_ReserveBlock

(

CDC_ReceiveQueue_TypeDef *

queue

)

Reserve space in the receive queue for an incoming packet.

Note

Up to CDC_QUEUE_MAX_PACKET_SIZE bytes may be written to the returned pointer. Call CDC_ReceiveQueue_CommitBlock() with the number of bytes actually written.

Parameters

queue

receive queue.

Returns

pointer where the packet can be written, or NULL if there is no room.

CDC_TransmitQueue_CommitRead()

void CDC_TransmitQueue_CommitRead

(

CDC_TransmitQueue_TypeDef *

queue

)

Release the block returned by CDC_TransmitQueue_ReadBlock().

Parameters

queue

transmit queue.

CDC_TransmitQueue_Enqueue()

void CDC_TransmitQueue_Enqueue	(	CDC_TransmitQueue_TypeDef *	queue,
		const uint8_t *	buffer,
		uint32_t	size
	)

Copy data into the transmit queue, wrapping at the end of the buffer.

Note

The caller must check CDC_TransmitQueue_WriteSize() first. Writing more than the free space overwrites data not yet transmitted.

Parameters

queue	transmit queue.
buffer	data to copy.
size	number of bytes to copy.

CDC_TransmitQueue_Init()

void CDC_TransmitQueue_Init

(

CDC_TransmitQueue_TypeDef *

queue

)

Initialize read and write position of the transmit queue.

Parameters

queue

transmit queue to initialize.

CDC_TransmitQueue_ReadBlock()

uint8_t * CDC_TransmitQueue_ReadBlock	(	CDC_TransmitQueue_TypeDef *	queue,
		uint16_t *	size
	)

Get a contiguous block of queued data to transmit.

Note

The block is the biggest flat (non wrapping) block available, so it may be shorter than the total queued data when it wraps around the end of the buffer. It is meant to be sent in USB packets of at most CDC_QUEUE_MAX_PACKET_SIZE bytes. The block is reserved until CDC_TransmitQueue_CommitRead() is called.

Parameters

queue	transmit queue.
size	output: length of the returned block in bytes.

Returns

pointer to the first byte of the block.

CDC_TransmitQueue_ReadSize()

int CDC_TransmitQueue_ReadSize

(

CDC_TransmitQueue_TypeDef *

queue

)

Get the amount of data stored in the transmit queue.

Parameters

queue

transmit queue.

Returns

number of bytes waiting to be transmitted.

CDC_TransmitQueue_WriteSize()

int CDC_TransmitQueue_WriteSize

(

CDC_TransmitQueue_TypeDef *

queue

)

Get the free space available for writing into the transmit queue.

Note

One byte is always kept unused to tell a full queue from an empty one.

Parameters

queue

transmit queue.

Returns

number of bytes that can be enqueued.