ARM-specific Functions
10.14uart.c ring buffer management functions
Within the UART device driver, ring buffers are used to hold data received by the UART, but not yet processed by the PPP software. They are also used for data waiting to be transmitted by the UART. Each ring buffer is managed through a data structure, struct ring:
/* A ring buffer abstraction */ |
|
typedef struct ring { |
|
volatile unsigned |
in; |
volatile unsigned |
out; |
volatile unsigned |
limit; |
volatile unsigned char *data; |
|
} t_ring |
|
Each ring buffer has: |
|
in |
a pointer which points to the next location at which new data will |
|
be inserted |
out |
a pointer which points to the next character to be removed from |
|
the buffer |
limit |
the size of the data array |
data |
an array of 0..(limit-1) bytes. |
When in==out, the buffer is considered empty.
When ((in + 1) % limit)==out, the buffer is considered full.
Note
If you have a limit of ten, you will be able to store only nine characters before the buffer is considered full.
The ring buffer management functions in uart.c are:
•ring_add() on page 10-19
•ring_avail() on page 10-19
•ring_new() on page 10-20
•ring_remove() on page 10-21
•ring_space() on page 10-21.
10-18 |
Copyright © 1998 and 1999 ARM Limited. All rights reserved. |
ARM DUI 0079B |
ARM-specific Functions
10.14.1 ring_add()
This function adds a character to a ring if space is available.
Syntax
static int ring_add(t_ring *pRing, int ch)
where: |
|
pRing |
is the pointer to the ring buffer structure. |
ch |
is the character to add to the ring buffer. |
Return value
Returns one of the following:
0 |
if successful. |
–1 |
if there is insufficient room. |
10.14.2 ring_avail()
This function returns the number of characters stored in a ring buffer.
Syntax
static int ring_avail(t_ring *pRing)
where:
pRing is the pointer to the ring buffer structure.
Return value
Returns the number of characters that can be read from this ring buffer.
ARM DUI 0079B |
Copyright © 1998 and 1999 ARM Limited. All rights reserved. |
10-19 |
ARM-specific Functions
10.14.3 ring_new()
This function initializes a new ring buffer.
Syntax
static void ring_new(t_ring *pRing, int limit)
where:
pRing is the pointer to the ring buffer structure to be initialized. limit is the amount of buffer space to allocate for this ring buffer.
Return value
None.
Usage
ring_new() is used to initialize a new ring buffer to hold up to limit characters. Buffer space for the ring is allocated by calling calloc().
10-20 |
Copyright © 1998 and 1999 ARM Limited. All rights reserved. |
ARM DUI 0079B |
ARM-specific Functions
10.14.4 ring_remove()
This function removes and returns a character from a ring buffer.
Syntax
static int ring_remove(t_ring *pRing)
where:
pRing is the pointer to the ring buffer structure.
Return value
Returns one of the following:
–1 if there are no characters in this ring buffer.
the removed character
if there are characters in this ring buffer.
10.14.5 ring_space()
This function returns the amount of free space in a ring buffer.
Syntax
static int ring_space(t_ring *pRing)
where:
pRing is the pointer to the ring buffer structure.
Return value
Returns the number of characters that can be added to this ring buffer.
ARM DUI 0079B |
Copyright © 1998 and 1999 ARM Limited. All rights reserved. |
10-21 |