Skip to content

M
Mock Turtle
Commit 097b2099 authored by Federico Vaga's avatar Federico Vaga
Browse files
Options

rt: improve doxygen documentation 

Signed-off-by: Federico Vaga's avatarFederico Vaga <federico.vaga@cern.ch>
parent cbf7754b
Hide whitespace changes
Inline Side-by-side
Showing with 169 additions and 26 deletions
rt/mockturtle-rt-common.c
View file @ 097b2099
......@@ -26,7 +26,9 @@
#include "mockturtle-rt-common.h"
/**
* It sends a string over the debug interface
* It sends a string over the serial interface
* @param[in] p string to send
* @return number of sent characters
*/
int puts(const char *p)
{
......
rt/mockturtle-rt-common.h
View file @ 097b2099
......@@ -19,24 +19,36 @@
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#ifndef __RT_COMMON_H
#define __RT_COMMON_H
#ifndef __TRTL_RT_COMMON_H
#define __TRTL_RT_COMMON_H
/**
* @defgroup trtl-rt-common Common Utilities
* Collection of general purpose utilities.
* @{
*/
#include <stdint.h>
#include <stdio.h>
#include "hw/mockturtle_cpu_lr.h"
/* Dedicated Peripheral base */
/**
* Dedicated Peripheral base address
*/
#define CPU_DP_BASE 0x200000
/* CPU Local Registers base */
/**
* CPU Local Registers base address
*/
#define CPU_LR_BASE 0x100000
void rt_set_debug_slot(int slot);
extern void rt_set_debug_slot(int slot);
/**
* Read from the Dedicated Peripheral
* @param[in] reg register offset within the Dedicated Peripheral
* @return the value fromt the register
*/
static inline uint32_t dp_readl(uint32_t reg)
{
......@@ -46,6 +58,8 @@ static inline uint32_t dp_readl(uint32_t reg)
/**
* Write to the Dedicated Peripheral
* @param[in] value value to write
* @param[in] reg register offset within the Dedicated Peripheral
*/
static inline void dp_writel(uint32_t value, uint32_t reg)
{
......@@ -55,6 +69,8 @@ static inline void dp_writel(uint32_t value, uint32_t reg)
/**
* Read from the CPU Local Registers
* @param[in] reg register offset within the Local Registers
* @return the value fromt the register
*/
static inline uint32_t lr_readl(uint32_t reg)
{
......@@ -64,6 +80,8 @@ static inline uint32_t lr_readl(uint32_t reg)
/**
* Write to the CPU Local Registers
* @param[in] value value to write
* @param[in] reg register offset within the Local Registers
*/
static inline void lr_writel(uint32_t value, uint32_t reg)
{
......@@ -73,6 +91,7 @@ static inline void lr_writel(uint32_t value, uint32_t reg)
/**
* Set a bit in the CPU GPIO Register
* @param[in] pin GPIO pin to set
*/
static inline void gpio_set(int pin)
{
......@@ -82,6 +101,7 @@ static inline void gpio_set(int pin)
/**
* Clear a bit in the CPU GPIO Register
* @param[in] pin GPIO pin to clear
*/
static inline void gpio_clear(int pin)
{
......@@ -92,6 +112,7 @@ static inline void gpio_clear(int pin)
/**
* Wait n cycles
* fixme: use Timing Unit
* @param[in] n number of cycles to wait
*/
static inline void delay(int n)
{
......@@ -101,4 +122,6 @@ static inline void delay(int n)
asm volatile("nop");
}
/**@}*/
#endif
rt/mockturtle-rt-mqueue.h
View file @ 097b2099
......@@ -19,8 +19,14 @@
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#ifndef __RT_MQUEUE_H
#define __RT_MQUEUE_H
#ifndef __TRTL_RT_MQUEUE_H
#define __TRTL_RT_MQUEUE_H
/**
* @defgroup trtl-rt-mqueue Message Queue
* Collection of utilities to deal with the Mock Turtle Message Queues.
* @{
*/
#define REG_LR_POLL 0x100000
......@@ -57,8 +63,11 @@ struct rmq_message_addr {
/**
* It writes on a Message Queue register
* @param[in] remote if it's a remote queue set 1
* @param[val] value to write
* @param[reg] reg register offset
*/
static inline void mq_writel(int remote, uint32_t val, uint32_t reg )
static inline void mq_writel(int remote, uint32_t val, uint32_t reg)
{
if (remote)
* (volatile uint32_t *) (RMQ_BASE + reg) = val;
......@@ -69,8 +78,10 @@ static inline void mq_writel(int remote, uint32_t val, uint32_t reg )
/**
* It claims a Message Queue slot
* @param[in] remote if it's a remote queue set 1
* @param[in] slot slot number
*/
static inline void mq_claim (int remote, int slot)
static inline void mq_claim(int remote, int slot)
{
mq_writel(remote, MQ_CMD_CLAIM, MQ_OUT(slot) + MQ_SLOT_COMMAND);
}
......@@ -78,8 +89,12 @@ static inline void mq_claim (int remote, int slot)
/**
* It mark the message in the slot as Ready to send.
* After send the slot is cleared
* @param[in] remote if it's a remote queue set 1
* @param[in] slot slot number
* @param[in] count number of bytes to send
*/
static inline void mq_send( int remote, int slot, int count)
static inline void mq_send(int remote, int slot, int count)
{
mq_writel(remote, MQ_CMD_READY | count, MQ_OUT(slot) + MQ_SLOT_COMMAND);
}
......@@ -87,8 +102,10 @@ static inline void mq_send( int remote, int slot, int count)
/**
* It discard (remove) a message from the given slot
* @param[in] remote if it's a remote queue set 1
* @param[in] slot slot number
*/
static inline void mq_discard (int remote, int slot)
static inline void mq_discard(int remote, int slot)
{
mq_writel(remote, MQ_CMD_DISCARD, MQ_IN(slot));
}
......@@ -96,6 +113,8 @@ static inline void mq_discard (int remote, int slot)
/**
* It gets the output slot data field pointer
* @param[in] remote if it's a remote queue set 1
* @param[in] slot slot number
*/
static void *mq_map_out_buffer(int remote, int slot)
{
......@@ -107,6 +126,8 @@ static void *mq_map_out_buffer(int remote, int slot)
/**
* It gets the input slot data field pointer
* @param[in] remote if it's a remote queue set 1
* @param[in] slot slot number
*/
static void *mq_map_in_buffer(int remote, int slot)
{
......@@ -119,7 +140,7 @@ static void *mq_map_in_buffer(int remote, int slot)
/**
* It gets the current status of the Message Queues (both Host and Remote)
*/
static inline uint32_t mq_poll()
static inline uint32_t mq_poll(void)
{
return *(volatile uint32_t *) ( REG_LR_POLL );
}
......@@ -133,4 +154,6 @@ static inline uint32_t rmq_poll(int slot)
return *(volatile uint32_t *) ( REG_LR_POLL ) & ( 1<< (16 + slot ));
}
/**@}*/
#endif
rt/mockturtle-rt-smem.h
View file @ 097b2099
......@@ -22,9 +22,14 @@
#ifndef __WRNODE_SMEM_H
#define __WRNODE_SMEM_H
/**
* @defgroup trtl-rt-smem Shared Memory Utilities
* Collection of utilities to deal with the Mock Turtle Shared Memory.
* @{
*/
/**
* List of available access modes
* It generates the SHM address range for a given SHM operations
*/
#define SMEM_RANGE_ADD 0x10000
#define SMEM_RANGE_SUB 0x20000
......@@ -33,20 +38,43 @@
#define SMEM_RANGE_FLIP 0x50000
#define SMEM_RANGE_TEST_AND_SET 0x60000
/**
* Compiler attribute to allocate variable on the Share Memory.
* Add this to the variable declaration to put it on the Shared Memory.
*
* SMEM int x;
*/
#define SMEM volatile __attribute__((section(".smem")))
/**
* Perform an operation on a given pointer. Operation can be performed only
* on integer variables
* It performs an operations on the shared memory. What the function
* performs can be summerized as:
*
* (*p) = (*p) <operation-type> x
*
* Use this function only when the operation type that you want to use
* is not supported yet by the library directly. Otherwise,
* use the other functions.
*
* @param[in] p address on the shared memory of the first operator and store location
* @param[in] x second operation argument
* @param[in] type operation type
*/
static inline void __smem_atomic_op(volatile int *p, int x, unsigned int range)
static inline void __smem_atomic_op(volatile int *p, int x, unsigned int type)
{
*(volatile int *)(p + (range >> 2)) = x;
*(volatile int *)(p + (type >> 2)) = x;
}
/**
* Add x to the value in the shared memory pointed by p
* It performs an atomic addition:
*
* (*p) = (*p) + x
*
* @param[in] p address on the shared memory of the first operator and store location
* @param[in] x second operation argument
*/
static inline void smem_atomic_add(volatile int *p, int x)
{
......@@ -55,7 +83,12 @@ static inline void smem_atomic_add(volatile int *p, int x)
/**
* Subtract x to the value in the shared memory pointed by p
* It performs an atomic subtraction:
*
* (*p) = (*p) - x
*
* @param[in] p address on the shared memory of the first operator and store location
* @param[in] x second operation argument
*/
static inline void smem_atomic_sub(volatile int *p, int x)
{
......@@ -64,7 +97,12 @@ static inline void smem_atomic_sub(volatile int *p, int x)
/**
* Do "OR" between x and the value in the shared memory pointed by p
* It performs an atomic bitwise OR:
*
* (*p) = (*p) | x
*
* @param[in] p address on the shared memory of the first operator and store location
* @param[in] x second operation argument
*/
static inline void smem_atomic_or(volatile int *p, int x)
{
......@@ -73,7 +111,12 @@ static inline void smem_atomic_or(volatile int *p, int x)
/**
* Do "AND ~" between x and the value in the shared memory pointed by p
* It performs an atomic bitwise "AND ~":
*
* (*p) = (*p) & (~x)
*
* @param[in] p address on the shared memory of the first operator and store location
* @param[in] x second operation argument
*/
static inline void smem_atomic_and_not(volatile int *p, int x)
{
......@@ -82,17 +125,32 @@ static inline void smem_atomic_and_not(volatile int *p, int x)
/**
* Do "XOR" between x and the value in the shared memory pointed by p
* It performs an atomic bitwise XOR:
*
* (*p) = (*p) ^ x
*
* @param[in] p address on the shared memory of the first operator and store location
* @param[in] x second operation argument
*/
static inline void smem_atomic_xor(int *p, int x)
{
__smem_atomic_op(p, x, SMEM_RANGE_FLIP);
}
/**
* Do test & set in the shared memory pointed by p
* The current value is returned and the new value is setted to 1
* This allows to implement mutex
* It does a test and set in the shared memory pointed by p:
*
* val = (*p);
* if (val == 0) {
* (*p) = 1;
* }
* return val;
*
* This is useful to implement mutex
*
* @param[in] p address on the shared memory
* @return the value before the set
*/
static inline int smem_atomic_test_and_set(int *p)
{
......@@ -100,4 +158,6 @@ static inline int smem_atomic_test_and_set(int *p)
return *(volatile int *)(p + (SMEM_RANGE_TEST_AND_SET >> 2));
}
/**@}*/
#endif
rt/pp-printf.h
View file @ 097b2099
......@@ -10,6 +10,11 @@
#ifndef __PP_PRINTF_H
#define __PP_PRINTF_H
/**
* @addtogroup trtl-rt-common
* @{
*/
#include <stdarg.h>
/**
......@@ -32,21 +37,48 @@ extern int pp_vsprintf(char *buf, const char *, va_list args)
#else
/**
* It prints a string on the serial interface
* @param[in] fmt string format
* @return number of printed characters
*/
static inline int pp_printf(const char *fmt, ...)
{
return 0;
}
/**
* It fills a buffer with a string
* @param[out] s output string
* @param[in] fmt string format
* @return number of printed characters
*/
static inline int pp_sprintf(char *s, const char *fmt, ...)
{
return 0;
}
/**
* It prints a string on the serial interface
* @param[in] fmt string format
* @param[in] args list of arguments according to the string format
* @return number of printed characters
*/
static inline int pp_vprintf(const char *fmt, va_list args)
{
return 0;
}
/**
* It fills a buffer with a string
* @param[out] s output string
* @param[in] fmt string format
* @param[in] args list of arguments according to the string format
* @return number of printed characters
*/
static inline int pp_vsprintf(char *buf, const char *fmt, va_list args)
{
return 0;
......@@ -54,7 +86,10 @@ static inline int pp_vsprintf(char *buf, const char *fmt, va_list args)
#endif
/* This is what we rely on for output */
extern int puts(const char *s);
/**@}*/
#endif
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment