Commit 726bc123 authored by Federico Vaga's avatar Federico Vaga

doc: fix API comments with a more typical format

Signed-off-by: Federico Vaga's avatarFederico Vaga <federico.vaga@cern.ch>
parent 2cc7927e
......@@ -31,7 +31,7 @@ const char *spec_btn_to_name(enum spec_btn_mode mode)
}
/**
* It returns a string messages corresponding to a given error code. If
* Return a string messages corresponding to a given error code. If
* it is not a libwrtd error code, it will run trtl_strerror()
* @param[in] err error code
* @return a message error
......@@ -46,7 +46,7 @@ const char *spec_strerror(unsigned int err)
/**
* It initializes the SPEC library. It must be called before doing
* Initialize the SPEC library. It must be called before doing
* anything else.
* This library is based on the libmockturtle, so internally, this function also
* run spec_init() in order to initialize the WRNC library.
......@@ -65,7 +65,7 @@ int spec_init()
/**
* It releases the resources allocated by spec_init(). It must be called when
* Release the resources allocated by spec_init(). It must be called when
* you stop to use this library. Then, you cannot use functions from this
* library.
*/
......@@ -103,7 +103,7 @@ out:
/**
* It closes a SPEC device opened with one of the following function:
* Close a SPEC device opened with one of the following function:
* spec_open_by_id()
* @param[in] dev device token
*/
......@@ -118,7 +118,7 @@ void spec_close(struct spec_node *dev)
/**
* It returns the WRNC token in order to allows users to run
* Return the WRNC token in order to allows users to run
* functions from the WRNC library
* @param[in] dev device token
* @return the WRNC token
......
......@@ -69,7 +69,7 @@ struct trtl_fw_variable svec_variables[] = {
/**
* It sends messages over the debug interface
* Send messages over the debug interface
*/
static int svec_debug_interface(void)
{
......
......@@ -21,7 +21,7 @@ const char *svec_errors[] = {
/**
* It returns a string messages corresponding to a given error code. If
* Return a string messages corresponding to a given error code. If
* it is not a libwrtd error code, it will run trtl_strerror()
* @param[in] err error code
* @return a message error
......@@ -36,7 +36,7 @@ const char *svec_strerror(unsigned int err)
/**
* It initializes the SVEC library. It must be called before doing
* Initialize the SVEC library. It must be called before doing
* anything else.
* This library is based on the libmockturtle, so internally, this function also
* run svec_init() in order to initialize the WRNC library.
......@@ -55,7 +55,7 @@ int svec_init()
/**
* It releases the resources allocated by svec_init(). It must be called when
* Release the resources allocated by svec_init(). It must be called when
* you stop to use this library. Then, you cannot use functions from this
* library.
*/
......@@ -93,7 +93,7 @@ out:
/**
* It closes a SVEC device opened with one of the following function:
* Close a SVEC device opened with one of the following function:
* svec_open_by_id()
* @param[in] dev device token
*/
......@@ -108,7 +108,7 @@ void svec_close(struct svec_node *dev)
/**
* It returns the WRNC token in order to allows users to run
* Return the WRNC token in order to allows users to run
* functions from the WRNC library
* @param[in] dev device token
* @return the WRNC token
......@@ -185,7 +185,7 @@ int svec_led_set(struct svec_node *dev, uint32_t value, enum svec_color color)
/**
* It gets the status of the SVEC program
* Get the status of the SVEC program
*/
int svec_status_get(struct svec_node *dev, struct svec_status *status)
{
......
......@@ -29,7 +29,7 @@ int pr_frm_debug(const char *fmt, ...)
uint32_t msg_seq = 0;
/**
* It makes the given message an error message
* Make the given message an error message
*/
void trtl_fw_message_error(struct trtl_fw_msg *msg, int err)
{
......@@ -264,7 +264,7 @@ static inline trtl_fw_action_t *rt_action_get(unsigned int msg_id)
}
/**
* It runs the action associated with the given identifier
* Run the action associated with the given identifier
* @param[in] type MQ type
* @param[in] idx_mq MQ index
* @param[out] msg the incoming message
......@@ -320,7 +320,7 @@ static inline int rt_action_run(enum trtl_mq_type type,
/**
* It dispatch messages coming from a given message queue.
* Dipatch messages coming from a given message queue.
* @param[in] type MQ type
* @param[in] idx_mq MQ index
* @return 0 on success. -1 on error
......@@ -375,7 +375,7 @@ out:
/**
* It builds and it sends a message over MQ.
* Build and send a message over MQ.
* The vargs will be copied into the payload message.
* @param[in] type MQ type
* @param[in] idx_mq MQ index within the declaration
......@@ -420,7 +420,7 @@ int trtl_fw_mq_send_uint32(enum trtl_mq_type type,
/**
* It builds and it sends a message over MQ.
* Build and send a message over MQ.
* The buffer will be copied into the payload message.
* Beware that, internally, it uses trtl_fw_mq_send().
* @param[in] type MQ type
......@@ -462,7 +462,7 @@ int trtl_fw_mq_send_buf(enum trtl_mq_type type,
/**
* It gets the current time from the internal TRTL timer
* Get the current time from the internal TRTL timer
* @param[out] seconds
* @param[out] cycles
*/
......@@ -474,7 +474,7 @@ void trtl_fw_time(uint32_t *seconds, uint32_t *cycles)
/**
* It validates the user application actions
* Validate the user application actions
* @param[in] app the user application
* @return 0 on success. -EINVAL on error
*/
......@@ -499,7 +499,7 @@ static inline int trtl_fw_init_action(struct trtl_fw_application *app)
/**
* It validates the FPGA
* Validate the FPGA
* @param[in] app the user application
* @return 0 on success. -EINVAL on error
*/
......@@ -537,7 +537,7 @@ static inline int trtl_fw_init_fpga(struct trtl_fw_application *app)
/**
* It initializes the RMQ and the HMQ
* Initialize the RMQ and the HMQ
* @param[in] app the user application
* @return 0 on success. -EINVAL on error
*/
......@@ -549,7 +549,7 @@ static inline int trtl_fw_init_mq(struct trtl_fw_application *app)
/**
* It validates the RMQ and the HMQ
* Validate the RMQ and the HMQ
* @param[in] app the user application
* @return 0 on success. -EINVAL on error
*/
......@@ -570,7 +570,7 @@ static inline int trtl_fw_init_variables(struct trtl_fw_application *app)
/**
* It validates the RMQ and the HMQ
* Validate the RMQ and the HMQ
* @param[in] app the user application
* @return 0 on success. -EINVAL on error
*/
......@@ -589,7 +589,7 @@ static inline int trtl_fw_init_buffers(struct trtl_fw_application *app)
/**
* It initializes the application and it does some compatibility check.
* Initialize the application and some compatibility check.
*
* - check bitstream FPGA ID if compatibile with the application.
* - purge remote message queue
......
......@@ -68,7 +68,7 @@ struct trtl_fw_buffer {
/**
* Firmware Application Descriptor.
* It provides a set of useful information used by the framework to
* Provide a set of useful information used by the framework to
* provide services to users.
*/
struct trtl_fw_application {
......@@ -103,7 +103,7 @@ struct trtl_fw_application {
extern struct trtl_fw_application app;
/**
* It returns the application descriptor
* Return the application descriptor
* @return application descriptor
*/
static inline struct trtl_fw_application *trtl_fw_application_get(void)
......
......@@ -14,7 +14,7 @@
/**
* It sends a character to the UART interface
* Send a character to the UART interface
* @param[in] c the character to sent
* @return 0 on success (for the time being it does not fail)
*/
......@@ -27,7 +27,7 @@ int putchar(int c)
/**
* It sends a string over the serial interface
* Send a string over the serial interface
* @param[in] p string to send
* @return number of sent characters
*
......@@ -48,7 +48,7 @@ int puts(const char *p)
/**
* It prints on the serial console the given message
* Print on the serial console the given message
* @param[in] msg a mock turtle message
*/
void pr_message(struct trtl_fw_msg *msg)
......
......@@ -44,7 +44,7 @@ struct trtl_fw_msg {
/**
* It prints a string on the serial interface.
* Print a string on the serial interface.
* Internally, it uses the puts() function.
* @param[in] fmt string format
* @param[in] ... argument according to the string format
......@@ -62,7 +62,7 @@ static inline int pp_printf(const char *fmt, ...)
/**
* It creates a new string according to the given format
* Create a new string according to the given format
* @param[out] s output string
* @param[in] fmt string format
* @param[in] ... argument according to the string format
......@@ -80,7 +80,7 @@ static inline int pp_sprintf(char *s, const char *fmt, ...)
/**
* It prints a string on the serial interface.
* Print a string on the serial interface.
* Internally, it uses the puts() function.
* @param[in] fmt string format
* @param[in] args list of arguments according to the string format
......@@ -97,7 +97,7 @@ static inline int pp_vprintf(const char *fmt, va_list args)
/**
* It creates a new string according to the given format
* Create a new string according to the given format
* @param[out] buf output string
* @param[in] fmt string format
* @param[in] args list of arguments according to the string format
......@@ -115,7 +115,7 @@ static inline int pp_vsprintf(char *buf, const char *fmt, va_list args)
/**
* It prints a string on the serial interface only when the support
* Print a string on the serial interface only when the support
* for error messages is enable.
*
* Kconfig ->CONFIG_MOCKTURTLE_LIBRARY_PRINT_DEBUG_ENABLE
......@@ -136,7 +136,7 @@ static inline int pr_debug(const char *fmt, ...)
#endif
/**
* It prints a string on the serial interface only when the support
* Print a string on the serial interface only when the support
* for error messages is enable.
*
* Kconfig -> CONFIG_MOCKTURTLE_LIBRARY_PRINT_ERROR_ENABLE
......@@ -246,7 +246,7 @@ static inline void gpio_clear(int pin)
/**
* It gets the GPIO status
* Get the GPIO status
* @param[in] pin GPIO pin to query
* @return the GPIO status
*/
......@@ -270,7 +270,7 @@ static inline void delay(int n)
/**
* It returns a pointer to the config ROM
* Return a pointer to the config ROM
* @return pointer to the configuration ROM
*/
static inline const struct trtl_config_rom *trtl_config_rom_get(void)
......@@ -280,7 +280,7 @@ static inline const struct trtl_config_rom *trtl_config_rom_get(void)
/**
* It waits for n milli-seconds (more or less). Be carefull to not overflow
* Wait for n milli-seconds (more or less). Be carefull to not overflow
* the 32bits with big delays (in principle you should never use big delays)
* @param[in] n number of milli-seconds to wait
*/
......@@ -293,7 +293,7 @@ static inline void mdelay(unsigned int n)
/**
* It waits for n micro-seconds (more or less). Be carefull to not overflow
* Wait for n micro-seconds (more or less). Be carefull to not overflow
* the 32bits with big delays (in principle you should never use big delays)
* @param[in] n number of micro-seconds to wait
*/
......@@ -306,7 +306,7 @@ static inline void udelay(unsigned int n)
/**
* It generates a notification signal (IRQ) to ask the HOST CPU
* Generate a notification signal (IRQ) to ask the HOST CPU
* to take some action.
* @param[in] id CPU notification identifier
*/
......@@ -317,7 +317,7 @@ static inline void trtl_notify(uint8_t id)
/**
* It generates a notification signal (IRQ) to ask the HOST CPU
* Generate a notification signal (IRQ) to ask the HOST CPU
* to take some action.
* @param[in] id CPU notification identifier
*/
......@@ -333,7 +333,7 @@ static inline void trtl_notify_user(uint8_t id)
/**
* It returns the core ID on which the firmware is running
* Return the core ID on which the firmware is running
* @return the core ID
*/
static inline uint32_t trtl_get_core_id(void)
......@@ -367,7 +367,7 @@ enum trtl_mq_type {
/**
* It gets the Message Queue base address
* Get the Message Queue base address
* @param[in] type MQ type
* @return message queue base address
*/
......@@ -378,7 +378,7 @@ static inline void *trtl_mq_base_address(enum trtl_mq_type type)
/**
* It writes on a Message Queue register
* Write on a Message Queue register
* @param[in] type MQ type to use
* @param[in] val value to write
* @param[in] reg register offset
......@@ -396,7 +396,7 @@ static inline uint32_t mq_readl(enum trtl_mq_type type, uint32_t reg)
/**
* It gets the output slot data field pointer
* Get the output slot data field pointer
* @param[in] type MQ type to use
* @param[in] slot slot number
* @return pointer to the input buffer
......@@ -411,7 +411,7 @@ static inline void *mq_map_out_buffer(enum trtl_mq_type type, int slot)
/**
* It gets the input slot data field pointer
* Get the input slot data field pointer
* @param[in] type MQ type to use
* @param[in] slot slot number
* @return pointer to the input buffer
......@@ -424,7 +424,7 @@ static inline void *mq_map_in_buffer(enum trtl_mq_type type, int slot)
/**
* It gets the output slot header field pointer
* Get the output slot header field pointer
* @param[in] type MQ type to use
* @param[in] slot slot number
* @return pointer to the output header
......@@ -439,7 +439,7 @@ static inline void *mq_map_out_header(enum trtl_mq_type type, int slot)
/**
* It gets the input slot header field pointer
* Get the input slot header field pointer
* @param[in] type MQ type to use
* @param[in] slot slot number
* @return pointer to the input header
......@@ -523,7 +523,7 @@ static inline void mq_discard(enum trtl_mq_type type, int slot)
/**
* It maps a given MQ for outcoming messages
* Map a given MQ for outcoming messages
* @param[in] type MQ type to use
* @param[in] idx_mq MQ index
* @param[out] msg where to map the message
......@@ -538,7 +538,7 @@ static inline void mq_map_out_message(enum trtl_mq_type type,
/**
* It maps a given MQ for incoming messages
* Map a given MQ for incoming messages
* @param[in] type MQ type to use
* @param[in] idx_mq MQ index
* @param[out] msg where to map the message
......@@ -552,7 +552,7 @@ static inline void mq_map_in_message(enum trtl_mq_type type,
}
/**
* It gets the current MQ input status
* Get the current MQ input status
* @param[in] type MQ type to use
* @param[in] mask bitmask to set the bit of interest
* @return message queues input status bitmask
......@@ -570,7 +570,7 @@ static inline uint32_t mq_poll_in(enum trtl_mq_type type, uint32_t mask)
}
/**
* It gets the current MQ output status
* Get the current MQ output status
* @param[in] type MQ type to use
* @param[in] mask bitmask to set the bit of interest
* @return message queues output status bitmask
......@@ -589,7 +589,7 @@ static inline uint32_t mq_poll_out(enum trtl_mq_type type, uint32_t mask)
/**
* It gets the current MQ input status
* Get the current MQ input status
* @param[in] type MQ type to use
* @param[in] mask bitmask to set the bit of interest
* @param[in] us_timeout timeout in micro-seconds
......@@ -613,7 +613,7 @@ static inline uint32_t mq_poll_in_wait(enum trtl_mq_type type, uint32_t mask,
/**
* It gets the current MQ input status
* Get the current MQ input status
* @param[in] type MQ type to use
* @param[in] mask bitmask to set the bit of interest
* @param[in] us_timeout timeout in micro-seconds
......@@ -659,7 +659,7 @@ static inline uint32_t trtl_get_runtime_cycles()
#define TRTL_SMEM_RANGE_BASE 0x00000
/**
* It generates the SHM address range for a given SHM type
* Generate the SHM address range for a given SHM type
*/
#define TRTL_SMEM_TYPE_TO_RANGE(_type) \
(TRTL_SMEM_RANGE_BASE + (_type) * TRTL_SMEM_SIZE)
......@@ -722,7 +722,7 @@ static inline uint32_t trtl_get_runtime_cycles()
/**
* It performs an operations on the shared memory. What the function
* Perform an operations on the shared memory. What the function
* performs can be summerized as:
*
* (*p) = (*p) <operation-type> x
......@@ -743,7 +743,7 @@ static inline void __smem_atomic_op(volatile int *p, int x,
/**
* It performs an
* Perform an
* @copydoc TRTL_SMEM_TYPE_ADD
*
* (*p) = (*p) + x
......@@ -758,7 +758,7 @@ static inline void smem_atomic_add(volatile int *p, int x)
/**
* It performs an
* Perform an
* @copydoc TRTL_SMEM_TYPE_SUB
*
* (*p) = (*p) - x
......@@ -773,7 +773,7 @@ static inline void smem_atomic_sub(volatile int *p, int x)
/**
* It performs an
* Perform an
* @copydoc TRTL_SMEM_TYPE_SET
*
* (*p) = (*p) | x
......@@ -788,7 +788,7 @@ static inline void smem_atomic_or(volatile int *p, int x)
/**
* It performs an
* Perform an
* @copydoc TRTL_SMEM_TYPE_CLR
*
* (*p) = (*p) & (~x)
......@@ -803,7 +803,7 @@ static inline void smem_atomic_and_not(volatile int *p, int x)
/**
* It performs an
* Perform an
* @copydoc TRTL_SMEM_TYPE_FLP
*
* (*p) = (*p) ^ x
......@@ -818,7 +818,7 @@ static inline void smem_atomic_xor(int *p, int x)
/**
* It performs an:
* Perform an:
* @copydoc TRTL_SMEM_TYPE_TST_SET
*
* val = (*p);
......
......@@ -37,12 +37,12 @@
/**
* It gives a nice pointer to the given register in the dedicated peripheral
* Give a nice pointer to the given register in the dedicated peripheral
*/
#define TRTL_ADDR_DP(_offset) ((void *)(TRTL_ADDR_DP_BASE + (_offset)))
/**
* It gives a nice pointer to the given register in the local register area
* Give a nice pointer to the given register in the local register area
*/
#define TRTL_ADDR_LR(_offset) ((void *)(TRTL_ADDR_LR_BASE + (_offset)))
......
......@@ -25,7 +25,7 @@ extern const unsigned int trtl_default_timeout_ms;
/**
* @struct trtl_dev
* It is an obfuscated structure type. This is done because the user should not
* An obfuscated structure type. This is done because the user should not
* modify it but just use it as a token to access the library API.
*/
struct trtl_dev;
......@@ -132,7 +132,7 @@ extern int trtl_cpu_is_enable(struct trtl_dev *trtl, unsigned int index,
unsigned int *enable);
/**
* It disable and re-enable the CPU to perform a restart
* Diable and re-enable the CPU to perform a restart
*/
static inline int trtl_cpu_restart(struct trtl_dev *trtl, unsigned int index)
{
......
......@@ -38,7 +38,7 @@
/**
* @enum trtl_cpu_notification
* It lists all Mock Turtle notification's code.
* List all Mock Turtle notification's code.
*/
enum trtl_cpu_notification {
TRTL_CPU_NOTIFY_APPLICATION = __TRTL_CPU_NOTIFY_APPLICATION_MAX, /**< anonymous application
......@@ -53,7 +53,7 @@ enum trtl_cpu_notification {
/**
* It enumerates the Mock Turtle message ID.
* Enumerate the Mock Turtle message ID.
* These IDs starts after the user defined ones
*/
enum trtl_msg_id {
......@@ -114,7 +114,7 @@ struct trtl_hmq_header {
#define RT_VERSION(_a, _b) (((_a & 0xFFFF) << 16) | (_b & 0xFFFF))
/**
* It describes the version running on the embedded CPU
* Describe the version running on the embedded CPU
*/
struct trtl_fw_version {
uint16_t rt_id; /**< RT application identifier */
......@@ -238,19 +238,19 @@ struct trtl_msg {
#define TRTL_CONFIG_ROM_MQ_HEADER_MASK 0x000000FF
/**
* It extracts the number of message queue entries from the sizes value
* Extract the number of message queue entries from the sizes value
* in the configuration ROM
*/
#define TRTL_CONFIG_ROM_MQ_SIZE_ENTRIES(_size) (1 << ((_size & TRTL_CONFIG_ROM_MQ_ENTRIES_MASK) >> TRTL_CONFIG_ROM_MQ_ENTRIES_SHIFT))
/**
* It extracts the maximum payload size (32bit words) from the sizes value
* Extract the maximum payload size (32bit words) from the sizes value
* in the configuration ROM
*/
#define TRTL_CONFIG_ROM_MQ_SIZE_PAYLOAD(_size) (1 << ((_size & TRTL_CONFIG_ROM_MQ_PAYLOAD_MASK) >> TRTL_CONFIG_ROM_MQ_PAYLOAD_SHIFT))
/**
* It extracts the maximum header size (32bit words) from the sizes value in
* Extract the maximum header size (32bit words) from the sizes value in
* in the configuration ROM
*/
#define TRTL_CONFIG_ROM_MQ_SIZE_HEADER(_size) (1 << ((_size & TRTL_CONFIG_ROM_MQ_HEADER_MASK) >> TRTL_CONFIG_ROM_MQ_HEADER_SHIFT))
......
......@@ -99,7 +99,7 @@ int trtl_minor_get(struct device *dev, enum trtl_dev_type type)
/**
* It releases the char device minor is use by a given device
* Release the char device minor is use by a given device
*/
void trtl_minor_put(struct device *dev)
{
......@@ -115,7 +115,7 @@ void trtl_minor_put(struct device *dev)
/**
* It returns the application ID
* Return the application ID
*/
static ssize_t application_id_show(struct device *dev,
struct device_attribute *attr,
......@@ -127,7 +127,7 @@ static ssize_t application_id_show(struct device *dev,
}
/**
* It returns the number of CPU in the FPGA
* Return the number of CPU in the FPGA
*/
static ssize_t n_cpu_show(struct device *dev,
struct device_attribute *attr,
......@@ -140,7 +140,7 @@ static ssize_t n_cpu_show(struct device *dev,
/**
* It returns the reset status of all CPUs as bitmask
* Return the reset status of all CPUs as bitmask
*/
static ssize_t reset_mask_show(struct device *dev,
struct device_attribute *attr,
......@@ -155,7 +155,7 @@ static ssize_t reset_mask_show(struct device *dev,
}
/**
* It sets the reset status of all CPUs as bitmask
* Set the reset status of all CPUs as bitmask
*/
static ssize_t reset_mask_store(struct device *dev,
struct device_attribute *attr,
......
......@@ -86,7 +86,7 @@ static ssize_t notification_history_show(struct device *dev,
{
struct trtl_cpu *cpu = to_trtl_cpu(dev);
ssize_t len;
unsigned int i; /* it must be unsigned for the circ-buffer */
unsigned int i; /* Mut be unsigned for the circ-buffer */
int idx, id;
len = 0;
......@@ -103,7 +103,7 @@ DEVICE_ATTR(notification_history, 0444,
/**
* It returns the CPU reset status
* Return the CPU reset status
*/
static ssize_t reset_show(struct device *dev,
struct device_attribute *attr,
......@@ -119,7 +119,7 @@ static ssize_t reset_show(struct device *dev,
}
/**
* It assert or de-assert the CPU reset line
* Asert or de-assert the CPU reset line
*/
static ssize_t reset_store(struct device *dev,
struct device_attribute *attr,
......@@ -158,7 +158,7 @@ const struct attribute_group *trtl_cpu_groups[] = {
/**
* It loads a given application into the CPU memory
* Load a given application into the CPU memory
*/
static int trtl_cpu_firmware_load(struct trtl_cpu *cpu, void *fw_buf,
size_t count, loff_t off)
......@@ -287,7 +287,7 @@ static int trtl_cpu_simple_open(struct inode *inode, struct file *file)
}
/**
* It writes a given firmware into a CPU
* Write a given firmware into a CPU
*/
static ssize_t trtl_cpu_write(struct file *f, const char __user *buf,
size_t count, loff_t *offp)
......@@ -320,7 +320,7 @@ out_cpy:
}
/**
* It reads the firmware from a CPU
* Read the firmware from a CPU
*/
static ssize_t trtl_cpu_read(struct file *f, char __user *buf,
size_t count, loff_t *offp)
......
......@@ -132,7 +132,7 @@ static const struct file_operations trtl_dbg_debugger_ops = {
};
/**
* It creates the debug info file
* Create the debug info file
* @trtl: the mock turtle device instance
*/
void trtl_debugfs_init(struct trtl_dev *trtl)
......@@ -169,7 +169,7 @@ void trtl_debugfs_init(struct trtl_dev *trtl)
/**
* It removes the debug info file
* Remove the debug info file
* @trtl: the mock turtle device instance
*/
void trtl_debugfs_exit(struct trtl_dev *trtl)
......
......@@ -52,7 +52,7 @@ extern struct class trtl_cdev_class;
/**
* It enumerates the IRQ sources
* Enumerate the IRQ sources
* @TRTL_IRQ_HMQ_IN: incoming messages from soft-CPUs
* @TRTL_IRQ_HMQ_OUT: outgoing messages to soft-CPUs
* @TRTL_IRQ_HMQ_CON: messages in the console
......@@ -132,7 +132,7 @@ struct trtl_hmq_slot {
/**
* It describe the status of a HMQ slot
* Decribe the status of a HMQ slot
* @dev:
* @index: instance number
* @flags: describe the status of the HMQ slot from the driver point of view
......@@ -185,7 +185,7 @@ struct trtl_hmq {
#define TRTL_HMQ_USER_FLAG_SYNC_WAIT BIT(1)
/**
* It describes the consumer of the output slot
* Describe the consumer of the output slot
* @list: to keep it in our local queue
* @hmq: reference to opened HMQ
* @lock: to protect flags, wait_id
......@@ -206,7 +206,7 @@ struct trtl_hmq_user {
/**
* It describes a single instance of a CPU of the TRTL
* Describe a single instance of a CPU of the TRTL
* @index: instance number
* @dev: device representing a single CPU
* @cbuf: debug circular buffer
......@@ -236,7 +236,7 @@ struct trtl_cpu {
#define TRTL_DEV_FLAGS_BIGENDIAN BIT(0)
/**
* It describes the generic instance of a TRTL
* Describe the generic instance of a TRTL
* @
* @dev;
* @cpu: CPU instances
......
......@@ -91,7 +91,7 @@ static int trtl_msg_seq_get(struct trtl_dev *trtl)
}
/**
* It is an opaque type. It is used to avoid mistakes when using features
* An opaque type. It is used to avoid mistakes when using features
* that requires the HMQ selection. If you do not provide this type (which is
* provided by the selection function) you will get at least a warning from
* the compiler
......@@ -265,7 +265,7 @@ void trtl_hmq_purge(struct trtl_hmq *hmq)
/**
* It gets the bit number of a HMQ within CSR HMQ registers
* Get the bit number of a HMQ within CSR HMQ registers
* Return: a bit number
*/
static inline uint32_t trtl_hmq_csr_bit(struct trtl_hmq *hmq)
......@@ -283,7 +283,7 @@ static inline uint32_t trtl_hmq_csr_bit(struct trtl_hmq *hmq)
/**
* It enables IRQ for HMQ
* Enable IRQ for HMQ
*
* Internally it locks the HMQ selection spinlock
*/
......@@ -309,7 +309,7 @@ static void trtl_hmq_irq_enable(struct trtl_hmq *hmq, unsigned int is_output)
/**
* It disables IRQ for HMQ
* Disable IRQ for HMQ
*
* Internally it locks the HMQ selection spinlock
*/
......@@ -335,7 +335,7 @@ static void trtl_hmq_irq_disable(struct trtl_hmq *hmq, unsigned int is_output)
/**
* It removes all the data from local buffers and HW slots
* Remove all the data from local buffers and HW slots
* @hmq: the HMQ to flush
*
* Do not use it in interrupt context
......@@ -390,7 +390,7 @@ static bool trtl_hmq_user_filter_one(struct trtl_hmq_user *user,
}
/**
* It clears the content of the HMQ
* Clear the content of the HMQ
*/
static ssize_t discard_all_store(struct device *dev,
struct device_attribute *attr,
......@@ -598,7 +598,7 @@ static int trtl_hmq_release(struct inode *inode, struct file *f)
/**
* It writes a single message from a buffer
* Write a single message from a buffer
* @hmq: HMQ instance destination
* @buf: source buffer
* Return: 0 on success, otherwise a negative error number
......@@ -658,7 +658,7 @@ static int trtl_hmq_write_one(struct trtl_hmq_user *user,
}
/**
* It writes message in the drive message queue. The messages will be sent on
* Write message in the drive message queue. The messages will be sent on
* IRQ signal
*/
static ssize_t trtl_hmq_write(struct file *f, const char __user *buf,
......@@ -759,7 +759,7 @@ static long trtl_hmq_ioctl(struct file *f, unsigned int cmd, unsigned long arg)
/**
* It returns a message to user space messages from an output HMQ
* Return a message to user space messages from an output HMQ
*/
static ssize_t trtl_hmq_read(struct file *f, char __user *ubuf,
size_t count, loff_t *offp)
......@@ -818,7 +818,7 @@ static ssize_t trtl_hmq_read(struct file *f, char __user *ubuf,
/**
* It filters out messages until a valid one
* Filter out messages until a valid one
* @usr: pointer to a user HMQ instance
*/
static void trtl_hmq_user_filter(struct trtl_hmq_user *usr)
......@@ -840,7 +840,7 @@ static void trtl_hmq_user_filter(struct trtl_hmq_user *usr)
}
/**
* It looks into the input and output buffer to see if the user cna take
* Look into the input and output buffer to see if the user cna take
* any action. If the user can write 'POLLOUT', if the user can read 'POLLOUT'
*/
static unsigned int trtl_hmq_poll(struct file *f, struct poll_table_struct *w)
......@@ -874,7 +874,7 @@ const struct file_operations trtl_hmq_fops = {
/**
* It extracts a message from the given HMQ
* Extract a message from the given HMQ
* @hmq: where to get the message from
* @msg: where to store the message
*
......@@ -906,7 +906,7 @@ static void trtl_message_pop(struct trtl_hmq *hmq, struct trtl_msg *msg)
/**
* It extracts a message from the given HMQ and store it in the local buffer
* Extract a message from the given HMQ and store it in the local buffer
* @hmq: where to get the message from
*
* Internally this function locks the local input buffer (spinlock)
......@@ -928,7 +928,7 @@ static void trtl_message_pop_to_buf(struct trtl_hmq *hmq)
}
/**
* It handles an incoming interrupt, messages coming from the soft-CPU
* Handle an incoming interrupt, messages coming from the soft-CPU
*/
static void trtl_irq_handler_input(struct trtl_hmq *hmq)
{
......@@ -956,7 +956,7 @@ static void trtl_irq_handler_input(struct trtl_hmq *hmq)
/**
* It gets the IRQ status for the output HMQ
* Get the IRQ status for the output HMQ
* @trtl: Mock Turtle device instance
*/
static uint64_t trtl_hmq_irq_status_in(struct trtl_dev *trtl)
......@@ -972,7 +972,7 @@ static uint64_t trtl_hmq_irq_status_in(struct trtl_dev *trtl)
/**
* It handles the HMQ interrupts incoming messages from the soft-CPU
* Handle the HMQ interrupts incoming messages from the soft-CPU
*/
irqreturn_t trtl_irq_handler_in(int irq_core_base, void *arg)
{
......@@ -1004,7 +1004,7 @@ dispatch_irq:
/**
* It writes a message to a FPGA HMQ. Note that you have to take
* Write a message to a FPGA HMQ. Note that you have to take
* the HMQ spinlock before call this function
* @hmq: where to send the message
* @msg: the message to send
......@@ -1041,7 +1041,7 @@ static void trtl_message_push(struct trtl_hmq *hmq, struct trtl_msg *msg)
/**
* It injects a message to the given HMQ from the local buffer
* Inject a message to the given HMQ from the local buffer
* @hmq: where to get the message from
*
* Internally this function locks the local output buffer (spinlock)
......@@ -1070,7 +1070,7 @@ static void trtl_message_push_from_buf(struct trtl_hmq *hmq)
/**
* It gets the IRQ status for the input HMQ
* Get the IRQ status for the input HMQ
* @trtl: Mock Turtle device instance
*/
static uint64_t trtl_hmq_irq_status_out(struct trtl_dev *trtl)
......@@ -1086,7 +1086,7 @@ static uint64_t trtl_hmq_irq_status_out(struct trtl_dev *trtl)
/**
* It handles the HMQ interrupts for outgoing messages to the soft-CPU
* Handle the HMQ interrupts for outgoing messages to the soft-CPU
*/
irqreturn_t trtl_irq_handler_out(int irq_core_base, void *arg)
{
......@@ -1146,7 +1146,7 @@ static int trtl_hmq_buf_init(struct mturtle_hmq_buffer *buf)
}
/**
* It initializes and registers a HMQ device
* Initialize and registers a HMQ device
*/
int trtl_probe_hmq(struct trtl_cpu *cpu, unsigned int hmq_idx)
{
......
......@@ -41,7 +41,7 @@ static inline void trtl_tty_flip_buffer_push(struct trtl_cpu *cpu)
/**
* trtl_tty_handler_getchar - Get Character From soft-CPU
* It retrieves a character from the soft-CPU serial interface
* Retrieve a character from the soft-CPU serial interface
* and it adds the character to the TTY buffer
* @cpu: the soft-CPU to use
*/
......
......@@ -51,7 +51,7 @@ int trtl_fw_version(struct trtl_dev *trtl,
/**
* It checks if firmware core is running and answering to messages
* Check if firmware core is running and answering to messages
* @param[in] trtl device token
* @param[in] idx_cpu CPU index
* @param[in] idx_hmq HMQ index
......@@ -86,7 +86,7 @@ int trtl_fw_ping_timeout(struct trtl_dev *trtl,
}
/**
* It checks if firmware core is running and answering to messages
* Check if firmware core is running and answering to messages
* @param[in] trtl device token
* @param[in] idx_cpu CPU index
* @param[in] idx_hmq HMQ index
......@@ -136,7 +136,7 @@ static int __trtl_fw_variable(struct trtl_dev *trtl,
}
/**
* It sends/receive a set of variables to/from the Real-Time application.
* Send/receive a set of variables to/from the Real-Time application.
*
* The 'variables' field data format is the following
*
......@@ -149,7 +149,7 @@ static int __trtl_fw_variable(struct trtl_dev *trtl,
* VAL is the associated value
*
* By setting the flag 'sync' you will send a synchronous message, otherwise
* it is asynchronous. When synchronous the 'variables' field will be
* I asynchronous. When synchronous the 'variables' field will be
* overwritten by the synchronous answer; the answer contains the read back
* values for the requested variable after the set operation. You can use
* this to verify. You can use synchronous messages to verify that you
......@@ -282,7 +282,7 @@ static int __trtl_fw_buffer(struct trtl_dev *trtl,
}
/**
* It sends/receives a set of structures within TLV records.
* Send/receives a set of structures within TLV records.
* @param[in] trtl device token
* @param[in] idx_cpu CPU index
* @param[in] idx_hmq HMQ index
......@@ -301,7 +301,7 @@ int trtl_fw_buffer_set(struct trtl_dev *trtl,
/**
* It receives a set of structures within TLV records.
* Receive a set of structures within TLV records.
* @param[in] trtl device token
* @param[in] idx_cpu CPU index
* @param[in] idx_hmq HMQ index
......@@ -321,7 +321,7 @@ int trtl_fw_buffer_get(struct trtl_dev *trtl,
/**
* It prints the message header in a human readable format
* Print the message header in a human readable format
* @param[in] msg message
*/
void trtl_print_header(struct trtl_msg *msg)
......@@ -341,7 +341,7 @@ void trtl_print_header(struct trtl_msg *msg)
/**
* It prints the payload in a human readable format according
* Print the payload in a human readable format according
* to the message type
* @param[in] msg message
*/
......@@ -400,7 +400,7 @@ void trtl_print_payload(struct trtl_msg *msg)
/**
* It prints a message in a human readable format. This function assumes
* Print a message in a human readable format. This function assumes
* that the message contains a Mock Turtle message header.
* According to the message ID the format may change
* @param[in] msg message
......
......@@ -59,7 +59,7 @@ static int trtl_sysfs_write(char *path, void *buf, size_t len);
/**
* It returns a string messages corresponding to a given error code. If
* Return a string messages corresponding to a given error code. If
* it is not a libtrtl error code, it will run strerror(3)
* @param[in] err error code. Typically 'errno' variable
* @return a message error. No need to free the string.
......@@ -73,7 +73,7 @@ const char *trtl_strerror(int err)
/**
* It initializes the TRTL library. It must be called before doing
* Initialize the TRTL library. It must be called before doing
* anything else. If you are going to load/unload TRTL devices, then
* you have to un-load (trtl_exit()) e reload (trtl_init()) the library.
* @return 0 on success, otherwise -1 and errno is appropriately set
......@@ -95,7 +95,7 @@ int trtl_init(void)
/**
* It releases the resources allocated by trtl_init(). It must be called when
* Release the resources allocated by trtl_init(). It must be called when
* you stop to use this library. Then, you cannot use functions from this
* library anymore.
*/
......@@ -106,8 +106,8 @@ void trtl_exit(void)
/**
* It returns the number of available TRTLs. This is not calculated on demand.
* It depends on library initialization.
* Return the number of available TRTLs. This is not calculated on demand.
* Depend on library initialization.
* @return the number of TRTL available
*/
uint32_t trtl_count()
......@@ -132,7 +132,7 @@ uint32_t trtl_count()
/**
* It allocates and returns the list of available TRTL devices. The user is
* Allocate and return the list of available TRTL devices. The user is
* in charge to free the allocated memory wit trtl_list_free(). The list
* contains trtl_count() + 1 elements. The last element is a NULL pointer.
* @return a list of TRTL device's names. NULL on error
......@@ -167,7 +167,7 @@ char **trtl_list()
/**
* It release the list allocated memory
* Release the list allocated memory
* @param[in] list device list to release
*/
void trtl_list_free(char **list)
......@@ -180,7 +180,7 @@ void trtl_list_free(char **list)
}
/**
* It opens a TRTL device using a string descriptor. The descriptor correspond
* Open a TRTL device using a string descriptor. The descriptor correspond
* to the main char device name of the Mock-Turtle.
* @param[in] device name of the device to open
* @return the TRTL token, NULL on error and errno is appropriately set
......@@ -270,7 +270,7 @@ out_stat:
/**
* It opens a TRTL device using its device_id. The Mock-Turtle
* Open a TRTL device using its device_id. The Mock-Turtle
* driver is based upon the platform bus infrastructure, so all trtl devices are
* identified with their platform id.
* @param[in] device_id device id of the device to use
......@@ -296,7 +296,7 @@ struct trtl_dev *trtl_open_by_id(uint32_t device_id)
/**
* It opens a TRTL device using its Logical Unit Number. The Logical Unit Number
* Open a TRTL device using its Logical Unit Number. The Logical Unit Number
* is an instance number of a particular hardware. The LUN to use is the carrier
* one, and not the mezzanine one (if any).
* The driver is not aware of LUNs but only of device-id. So, if this function does
......@@ -329,7 +329,7 @@ struct trtl_dev *trtl_open_by_lun(unsigned int lun)
/**
* It closes a TRTL device opened with one of the following functions:
* Close a TRTL device opened with one of the following functions:
* trtl_open(), wrcn_open_by_lun(), trtl_open_by_id()
* @param[in] trtl device token
*/
......@@ -458,7 +458,7 @@ static int trtl_sysfs_printf(char *path, const char *fmt, ...)
/**
* It returns the current status of the TRTL CPUs' reset line
* Return the current status of the TRTL CPUs' reset line
* @param[in] trtl device token
* @param[out] mask bit mask of the reset-lines
* @return 0 on success, -1 otherwise and errno is set appropriately
......@@ -497,7 +497,7 @@ int trtl_cpu_reset_set(struct trtl_dev *trtl, uint32_t mask)
/**
* It loads a trtl CPU firmware from a given buffer
* Load a trtl CPU firmware from a given buffer
* @param[in] trtl device token
* @param[in] index CPU index
* @param[in] code buffer containing the CPU firmware binary code
......@@ -544,7 +544,7 @@ int trtl_cpu_load_application_raw(struct trtl_dev *trtl,
/**
* It dumps a TRTL CPU firmware into a given buffer
* Dump a TRTL CPU firmware into a given buffer
* @param[in] trtl device token
* @param[in] index CPU index
* @param[out] code buffer containing the CPU firmware binary code
......@@ -585,7 +585,7 @@ int trtl_cpu_dump_application_raw(struct trtl_dev *trtl,
/**
* It loads a TRTL CPU firmware from a given file
* Load a TRTL CPU firmware from a given file
* @param[in] trtl device token
* @param[in] index CPU index
* @param[in] path path to the firmware file
......@@ -639,7 +639,7 @@ out:
/**
* It dumps a TRTL CPU firmware into a given file
* Dump a TRTL CPU firmware into a given file
* @param[in] trtl device token
* @param[in] index CPU index
* @param[in] path path to the firmware file
......@@ -674,7 +674,7 @@ int trtl_cpu_dump_application_file(struct trtl_dev *trtl,
/**
* It opens a TRTL device
* Open a TRTL device
* @param[in] wdesc device descriptor
* @return 0 on success, -1 on error and errno is set appropriately
*/
......@@ -729,7 +729,7 @@ static int trtl_smem_io(struct trtl_desc *wdesc,
}
/**
* It does a direct acces to the shared memory to read a set of cells
* Direct acces to the shared memory to read a set of cells
* @param[in] trtl device token
* @param[in] addr memory address where start the operations
* @param[out] data values read from in the shared memory. The function will
......@@ -748,7 +748,7 @@ int trtl_smem_read(struct trtl_dev *trtl, uint32_t addr, uint32_t *data,
/**
* It writes on the shared memory of the TRTL
* Write on the shared memory of the TRTL
* @param[in] trtl device to use
* @param[in] addr memory address
* @param[in, out] data values to write in the shared memory. The function will
......@@ -767,7 +767,7 @@ int trtl_smem_write(struct trtl_dev *trtl, uint32_t addr, uint32_t *data,
/**
* It enables a CPU; in other words, it clears the reset line of a CPU.
* Enable a CPU; in other words, it clears the reset line of a CPU.
* This function is a wrapper of trtl_cpu_reset_set() that allow you to safely
* enable a single CPU.
* @param[in] trtl device token
......@@ -784,7 +784,7 @@ int trtl_cpu_enable(struct trtl_dev *trtl, unsigned int index)
/**
* It disables a CPU; in other words, it sets the reset line of a CPU.
* Disable a CPU; in other words, it sets the reset line of a CPU.
* This function is a wrapper of trtl_cpu_reset_set() that allows you to safely
* disable a single CPU.
* @param[in] trtl device token
......@@ -801,7 +801,7 @@ int trtl_cpu_disable(struct trtl_dev *trtl, unsigned int index)
/**
* It checks if the CPU is enabled (or not)
* Check if the CPU is enabled (or not)
* @param[in] trtl device token
* @param[in] index CPU index
* @param[out] enable 1 if the CPU is enable
......@@ -822,7 +822,7 @@ int trtl_cpu_is_enable(struct trtl_dev *trtl, unsigned int index,
/**
* It returns the device name
* Return the device name
* @param[in] trtl device token
* @return the string representing the name of the device
*/
......@@ -835,7 +835,7 @@ char *trtl_name_get(struct trtl_dev *trtl)
/**
* It returns information about the synthesis configuration
* Return information about the synthesis configuration
* @param[in] trtl device token
* @return a pointer to a config structure
*
......@@ -850,7 +850,7 @@ const struct trtl_config_rom *trtl_config_get(struct trtl_dev *trtl)
/**
* It returns the HMQ File Descriptor
* Return the HMQ File Descriptor
* @param[in] trtl device token
* @param[in] idx_cpu CPU index
* @param[in] idx_hmq HMQ index
......@@ -866,7 +866,7 @@ int trtl_hmq_fd(struct trtl_dev *trtl,
}
/**
* It returns the HMQ File Descriptor
* Return the HMQ File Descriptor
* @param[in] trtl device token
* @param[in] idx_cpu CPU index
* @param[in] idx_hmq HMQ index
......@@ -899,7 +899,7 @@ static int trtl_msg_read(int fd, struct trtl_msg *msg, unsigned int n)
}
/**
* It reads messages from a given HMQ
* Read messages from a given HMQ
* @param[in] trtl device token
* @param[in] idx_cpu CPU index
* @param[in] idx_hmq HMQ index
......@@ -942,7 +942,7 @@ static int trtl_msg_write(int fd, struct trtl_msg *msg, unsigned int n)
return (ret / size);
}
/**
* It writes messages to a given HMQ
* Write messages to a given HMQ
* @param[in] trtl device token
* @param[in] idx_cpu CPU index
* @param[in] idx_hmq HMQ index
......@@ -968,7 +968,7 @@ int trtl_msg_async_send(struct trtl_dev *trtl,
}
/**
* It adds a new filter to the given hmq descriptor
* Add a new filter to the given hmq descriptor
* @param[in] trtl device token
* @param[in] idx_cpu CPU index
* @param[in] idx_hmq HMQ index
......@@ -985,7 +985,7 @@ int trtl_msg_sync_abort(struct trtl_dev *trtl,
}
/**
* It sends and receives a synchronous message. It is up to the user to set the
* Send and receive a synchronous message. It is up to the user to set the
* "sync_id" in the message that it would like to send.
* @param[in] trtl device token
* @param[in] idx_cpu CPU index
......@@ -1058,7 +1058,7 @@ err:
/**
* It waits for one of a set of Mock Turtle HMQ to become ready to perform I/O
* Wait for one of a set of Mock Turtle HMQ to become ready to perform I/O
* @param[in,out] trtlp specific Mock Turtle poll descriptor
* @param[in] npolls like in poll(2)
* @param[in] timeout like in poll(2)
......@@ -1106,7 +1106,7 @@ int trtl_msg_poll(struct polltrtl *trtlp,
/**
* It flushes the content of an HMQ for both input and output channel
* Flush the content of an HMQ for both input and output channel
* @param[in] trtl device token
* @param[in] idx_cpu CPU index
* @param[in] idx_hmq HMQ index
......
......@@ -15,7 +15,7 @@
/**
* It prints the help message
* Print the help message
* @param[in] name the program name
*/
static void help(char *name)
......@@ -31,7 +31,7 @@ static void help(char *name)
/**
* It shows information about a given Mock Turtle device
* Show information about a given Mock Turtle device
* @param[in] trtl Mock Turtle device instance
*/
static void trtl_list_device_info(struct trtl_dev *trtl)
......
......@@ -56,7 +56,7 @@ static void help()
/**
* It retreives a message from a given slots and it prints its content
* Retreive a message from a given slots and it prints its content
* @param[in] trtl device to use
* @param[in] hmq slot to read
*/
......
......@@ -24,7 +24,7 @@
/**
* It prints the help message
* Print the help message
* @param[in] name the program name
*/
static void help(char *name)
......@@ -41,7 +41,7 @@ static void help(char *name)
/**
* It prints the given Mock Turtle firmware version
* Print the given Mock Turtle firmware version
* @param[in] v version to print
*/
static void trtl_ping_version_print(struct trtl_fw_version *v)
......
......@@ -19,7 +19,7 @@ static const char *{{short_name}}_errors[] = {
/**
* It returns a string messages corresponding to a given error code. If
* Return a string messages corresponding to a given error code. If
* it is not a libwrtd error code, it will run trtl_strerror()
* @param[in] err error code
* @return a message error
......@@ -35,7 +35,7 @@ const char *{{short_name}}_strerror(unsigned int err)
/**
* It initializes the {{name}} library. It must be called before doing
* Initialize the {{name}} library. It must be called before doing
* anything else.
* This library is based on the libmockturtle, so internally, this function also
* run trtl_init() in order to initialize the Mock Turtle library.
......@@ -54,7 +54,7 @@ int {{short_name}}_init()
/**
* It releases the resources allocated by {{short_name}}_init(). It must be called when
* Release the resources allocated by {{short_name}}_init(). It must be called when
* you stop to use this library. Then, you cannot use functions from this
* library.
*/
......@@ -92,7 +92,7 @@ out:
/**
* It closes a {{name}} device opened with one of the following function:
* Close a {{name}} device opened with one of the following function:
* {{short_name}}_open_by_id()
* @param[in] dev device token
*/
......@@ -107,7 +107,7 @@ void {{short_name}}_close(struct {{short_name}}_node *dev)
/**
* It returns the Mock Turtle token in order to allows users to run
* Return the Mock Turtle token in order to allows users to run
* functions from the Mock Turtle library
* @param[in] dev device token
* @return the Mock Turtle token
......
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