From 04e8c42aecedadfde56bb64ff9d3ae776754500f Mon Sep 17 00:00:00 2001 From: Lucy Date: Wed, 9 Mar 2022 16:19:57 +1100 Subject: [PATCH] Trivial: Style Signed-off-by: Lucy --- CMakeLists.txt | 2 +- libsharedringbuffer/CMakeLists.txt | 2 +- libsharedringbuffer/README.md | 45 +++++++++---------- .../shared_ringbuffer/shared_ringbuffer.h | 30 ++++++------- libsharedringbuffer/src/shared_ringbuffer.c | 5 +-- 5 files changed, 41 insertions(+), 43 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 4ca2631..2a63685 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -17,4 +17,4 @@ add_subdirectory(libvswitch) add_subdirectory(libfdtgen) add_subdirectory(libtx2bpmp) add_subdirectory(libplatsupportports) -add_subdirectory(libsharedringbuffer) \ No newline at end of file +add_subdirectory(libsharedringbuffer) diff --git a/libsharedringbuffer/CMakeLists.txt b/libsharedringbuffer/CMakeLists.txt index 411fe25..ac66176 100644 --- a/libsharedringbuffer/CMakeLists.txt +++ b/libsharedringbuffer/CMakeLists.txt @@ -1,5 +1,5 @@ # -# Copyright 2022, UNSW (ABN 57 195 873 179) +# Copyright 2022, UNSW # SPDX-License-Identifier: BSD-2-Clause # diff --git a/libsharedringbuffer/README.md b/libsharedringbuffer/README.md index 5bba91b..f308488 100644 --- a/libsharedringbuffer/README.md +++ b/libsharedringbuffer/README.md @@ -1,34 +1,34 @@ libsharedringbuffer ------------------- -This directory contains a library implementation of shared ring -buffers for the transportation of data. This is intended to be used as a +This directory contains a library implementation of shared ring +buffers for the transportation of data. This is intended to be used as a communication mechanism between system components for bulk data transfer, and was originally created as a data plane between an ethernet driver and network stack for the sDDF. This library doesn't contain any code that -interfaces with seL4. It is expected that the user will provide shared +interfaces with seL4. It is expected that the user will provide shared memory regions and notification/signalling handlers to this library. To use this library in a project you can link `shared_ringbuffer` in your target applications CMake configuration. -This libary is intended to be used by both a producer and consumer. For +This libary is intended to be used by both a producer and a consumer. For example, an ethernet driver produces data for a network stack to consume. 2 separate shared memory regions are required for each ring handle; one to store available buffers and one to store used buffers. Each ring buffer -contains a separate read index and write index. The reader only ever -increments the read index, and the writer the write index. As read and +contains a separate read index and write index. The reader only ever +increments the read index, and the writer the write index. As read and writes of a small integer are atomic, we can keep memory consistent without locks. The size of the ring buffers can be set with the cmake config option, `LIB_SHARED_RINGBUFFER_DESC_COUNT` but defaults to 512. The user must -ensure that the shared memory regions handed to the library are of -appropriate size to match this. +ensure that the shared memory regions handed to the library are of +appropriate size to match this. Use case --------- @@ -36,32 +36,31 @@ Use case This library is intended to be used with a separate shared memory region, usually allocated for DMA for a driver. The ring buffers can then contain pointers into this shared memory, indicating which buffers are in use or -available to be used by either component. +available to be used by either component. Typically, 2 shared ring buffers are required, with separate structures required on the recieve path and transmit path. Thus there are 4 regions -of shared memory required: 1 storing pointers to available RX buffers, +of shared memory required: 1 storing pointers to available RX buffers, 1 storing pointers to used RX buffers, 1 storing pointers to TX buffers, and another storing pointers to available TX buffers. -On initialisation, both the producer and consumer should allocate their +On initialisation, both the producer and consumer should allocate their own ring handles (`struct ring_handle`). These data structures simply -store pointers to the actual shared memory regions and are used to +store pointers to the actual shared memory regions and are used to interface with this library. The ring handle should then be passed into -`ring_init` along with 2 shared memory regions, an optional function -pointer to signal the other component, and either 1 or 0 to indicate +`ring_init` along with 2 shared memory regions, an optional function +pointer to signal the other component, and either 1 or 0 to indicate whether the read/write indices need to be initialised (note that only one -side of the shared memory regions needs to do this). +side of the shared memory regions needs to do this). -After initialisation, a typical use case would look like: +After initialisation, a typical use case would look like: The driver wants to add some buffer that will be read by another component -(for example, a network stack processing incoming packets). +(for example, a network stack processing incoming packets). - 1. The driver dequeues a pointer to an available buffer from the + 1. The driver dequeues a pointer to an available buffer from the available ring. - 2. Once data is inserted into the buffer (eg. via DMA), the driver + 2. Once data is inserted into the buffer (eg. via DMA), the driver then enqueues the pointer to it into the used ring. - 3. The driver can then notify the reciever. - 4. Similarly, the reciever dequeues the pointer from the used ring, + 3. The driver can then notify the reciever. + 4. Similarly, the reciever dequeues the pointer from the used ring, processes the data, and once finished, can enqueue it back into the available ring to be used once more by the driver. - diff --git a/libsharedringbuffer/include/shared_ringbuffer/shared_ringbuffer.h b/libsharedringbuffer/include/shared_ringbuffer/shared_ringbuffer.h index b8c87e8..2088698 100644 --- a/libsharedringbuffer/include/shared_ringbuffer/shared_ringbuffer.h +++ b/libsharedringbuffer/include/shared_ringbuffer/shared_ringbuffer.h @@ -1,10 +1,10 @@ /* - * Copyright 2022, UNSW (ABN 57 195 873 179) + * Copyright 2022, UNSW * * SPDX-License-Identifier: BSD-2-Clause */ -#pragma once +#pragma once #include #include @@ -46,7 +46,7 @@ typedef struct ring_handle { * @param used pointer to 'used' ring in shared memory. * @param notify function pointer used to notify the other user. * @param buffer_init 1 indicates the read and write indices in shared memory need to be initialised. - * 0 inidicates they do not. Only one side of the shared memory regions needs to do this. + * 0 inidicates they do not. Only one side of the shared memory regions needs to do this. */ void ring_init(ring_handle_t *ring, ring_buffer_t *avail, ring_buffer_t *used, notify_fn notify, int buffer_init); @@ -57,7 +57,7 @@ void ring_init(ring_handle_t *ring, ring_buffer_t *avail, ring_buffer_t *used, n * * @return true indicates the buffer is empty, false otherwise. */ -static inline int ring_empty(ring_buffer_t *ring) +static inline int ring_empty(ring_buffer_t *ring) { return !((ring->write_idx - ring->read_idx) % CONFIG_LIB_SHARED_RINGBUFFER_DESC_COUNT); } @@ -91,7 +91,7 @@ static inline void notify(ring_handle_t *ring) * @param ring Ring buffer to enqueue into. * @param buffer address into shared memory where data is stored. * @param len length of data inside the buffer above. - * @param cookie optional pointer to data required on dequeueing. + * @param cookie optional pointer to data required on dequeueing. * * @return -1 when ring is empty, 0 on success. */ @@ -118,7 +118,7 @@ static inline int enqueue(ring_buffer_t *ring, uintptr_t buffer, unsigned int le * @param ring Ring buffer to Dequeue from. * @param buffer pointer to the address of where to store buffer address. * @param len pointer to variable to store length of data dequeueing. - * @param cookie pointer optional pointer to data required on dequeueing. + * @param cookie pointer optional pointer to data required on dequeueing. * * @return -1 when ring is empty, 0 on success. */ @@ -141,16 +141,16 @@ static inline int dequeue(ring_buffer_t *ring, uintptr_t *addr, unsigned int *le /** * Enqueue an element into an available ring buffer. - * This indicates the buffer address parameter is currently available for use. + * This indicates the buffer address parameter is currently available for use. * * @param ring Ring handle to enqueue into. * @param buffer address into shared memory where data is stored. * @param len length of data inside the buffer above. - * @param cookie optional pointer to data required on dequeueing. + * @param cookie optional pointer to data required on dequeueing. * * @return -1 when ring is empty, 0 on success. */ -static inline int enqueue_avail(ring_handle_t *ring, uintptr_t addr, unsigned int len, void *cookie) +static inline int enqueue_avail(ring_handle_t *ring, uintptr_t addr, unsigned int len, void *cookie) { return enqueue(ring->avail_ring, addr, len, cookie); } @@ -162,11 +162,11 @@ static inline int enqueue_avail(ring_handle_t *ring, uintptr_t addr, unsigned in * @param ring Ring handle to enqueue into. * @param buffer address into shared memory where data is stored. * @param len length of data inside the buffer above. - * @param cookie optional pointer to data required on dequeueing. + * @param cookie optional pointer to data required on dequeueing. * * @return -1 when ring is empty, 0 on success. */ -static inline int enqueue_used(ring_handle_t *ring, uintptr_t addr, unsigned int len, void *cookie) +static inline int enqueue_used(ring_handle_t *ring, uintptr_t addr, unsigned int len, void *cookie) { return enqueue(ring->used_ring, addr, len, cookie); } @@ -177,7 +177,7 @@ static inline int enqueue_used(ring_handle_t *ring, uintptr_t addr, unsigned int * @param ring Ring handle to dequeue from. * @param buffer pointer to the address of where to store buffer address. * @param len pointer to variable to store length of data dequeueing. - * @param cookie pointer optional pointer to data required on dequeueing. + * @param cookie pointer optional pointer to data required on dequeueing. * * @return -1 when ring is empty, 0 on success. */ @@ -192,7 +192,7 @@ static inline int dequeue_avail(ring_handle_t *ring, uintptr_t *addr, unsigned i * @param ring Ring handle to dequeue from. * @param buffer pointer to the address of where to store buffer address. * @param len pointer to variable to store length of data dequeueing. - * @param cookie pointer optional pointer to data required on dequeueing. + * @param cookie pointer optional pointer to data required on dequeueing. * * @return -1 when ring is empty, 0 on success. */ @@ -204,7 +204,7 @@ static inline int dequeue_used(ring_handle_t *ring, uintptr_t *addr, unsigned in /** * Dequeue an element from a ring buffer. * This function is intended for use by the driver, to collect a pointer - * into this structure to be passed around as a cookie. + * into this structure to be passed around as a cookie. * * @param ring Ring buffer to dequeue from. * @param addr pointer to the address of where to store buffer address. @@ -230,4 +230,4 @@ static int driver_dequeue(ring_buffer_t *ring, uintptr_t *addr, unsigned int *le ring->read_idx++; return 0; -} \ No newline at end of file +} diff --git a/libsharedringbuffer/src/shared_ringbuffer.c b/libsharedringbuffer/src/shared_ringbuffer.c index 5e1f526..de3e367 100644 --- a/libsharedringbuffer/src/shared_ringbuffer.c +++ b/libsharedringbuffer/src/shared_ringbuffer.c @@ -1,6 +1,5 @@ /* - * Copyright 2022, UNSW (ABN 57 195 873 179) - * + * Copyright 2022, UNSW * SPDX-License-Identifier: BSD-2-Clause */ @@ -18,4 +17,4 @@ void ring_init(ring_handle_t *ring, ring_buffer_t *avail, ring_buffer_t *used, n ring->avail_ring->write_idx = 0; ring->avail_ring->read_idx = 0; } -} \ No newline at end of file +}