# HG changeset patch # User alexis # Date 2011-04-21 16:47:52 # Node ID 4fad670a419d6150d8282c6c64174e7c4f5cacf4 # Parent e0d39502407e81127d155afe41a5b46f42377238 Improved documentation for apb, uart, lcd drivers. diff --git a/LPP_drivers/Doxyfile b/LPP_drivers/Doxyfile --- a/LPP_drivers/Doxyfile +++ b/LPP_drivers/Doxyfile @@ -25,13 +25,13 @@ DOXYFILE_ENCODING = UTF-8 # The PROJECT_NAME tag is a single word (or a sequence of words surrounded # by quotes) that should identify the project. -PROJECT_NAME = "apb lcd driver" +PROJECT_NAME = "VHDL lib Drivers" # The PROJECT_NUMBER tag can be used to enter a project or revision number. # This could be handy for archiving the generated documentation or # if some version control system is used. -PROJECT_NUMBER = 0.1 +PROJECT_NUMBER = 0.4 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) # base path where the generated documentation will be put. diff --git a/LPP_drivers/libsrc/AMBA/lpp_apb_functions.h b/LPP_drivers/libsrc/AMBA/lpp_apb_functions.h --- a/LPP_drivers/libsrc/AMBA/lpp_apb_functions.h +++ b/LPP_drivers/libsrc/AMBA/lpp_apb_functions.h @@ -22,41 +22,111 @@ #ifndef LPP_APB_FUNCTIONS_H #define LPP_APB_FUNCTIONS_H -#define APB_TBL_HEAD 0x800FF000 -#define APB_BASE_ADDRS 0x80000000 -#define APB_MAX_DEVICES 256 +#define APB_TBL_HEAD 0x800FF000 /**< Start address of APB devices list on AHB2APB bridge*/ +#define APB_BASE_ADDRS 0x80000000 /**< Start address of APB bus*/ +#define APB_MAX_DEVICES 256 /**< Maximun device count on APB bus*/ #include "apb_devices_list.h" -/** @todo implemente a descriptor structure for any APB device */ + +/*! \file lpp_apb_functions.h + \brief General purpose APB functions. + + This library is written to work with AHB2APB VHDL module from Gaisler's GRLIB. It help you to find your device + on the APB bus by providing scan functions, it extract information such as device Version, IRQ value, Address mask. + You can use it to print the APB devices list on your SOC. + + \author Alexis Jeandet + \todo implemente a descriptor structure for any APB device +*/ -/** Structure representing a device descriptor register on Grlib's AHB2APB brige with plug and play feature */ +/*! \struct apbPnPreg + \brief Structure representing a device descriptor register on Grlib's AHB2APB brige with plug and play feature +*/ struct apbPnPreg { - int idReg; /**< id register composed of Vendor ID [31:24], Device ID [23:12], CT [11:10], Version [9:5], IRQ [4:0] */ - int bar; /**< Bank Address Register composed of Device's ADDRESS [31:20], MASK [14:4], TYPE [3:0] */ + int idReg; /**< \brief id register composed of Vendor ID [31:24], Device ID [23:12], CT [11:10], Version [9:5], IRQ [4:0] */ + int bar; /**< \brief Bank Address Register composed of Device's ADDRESS [31:20], MASK [14:4], TYPE [3:0] */ }; + +/*! \struct apbdevinfo + \brief Structure holding an APB device informations + + This information are extracted from the descriptor registers on Grlib's AHB2APB brige with plug and play feature +*/ struct apbdevinfo { - int vendorID; - int productID; - int version; - int irq; - int address; - int mask; + int vendorID; /**< \brief Stores the Vendor ID of the current device */ + int productID; /**< \brief Stores the Product ID of the current device */ + int version; /**< \brief Stores the Version of the current device */ + int irq; /**< \brief Stores the interrupt Number of the current device */ + int address; /**< \brief Stores the base address of the current device */ + int mask; /**< \brief Stores the address mask of the current device, it gives the address space of this device */ }; -/** This Function scans APB devices table and returns counth device according to VID and PID */ + + + +/*! \fn int* apbgetdevice(int PID,int VID,int count); + \brief Find device with given VID/PID + + This Function scans APB devices table and returns counth device according to VID and PID + + \param PID The PID of the device you whant to get. + \param VID The VID of the device you whant to get. + \param count The number of the device you whant to get. For example if you have 3 UARTS on your SOC you whant + to use UART1 so count = 2. + + \return The pointer to the device. +*/ int* apbgetdevice(int PID,int VID,int count); -/** This Function scans APB devices table and returns counth device informations according VID and PID */ + +/*! \fn void apbgetdeviceinfofromid(int PID,int VID,int count,struct apbdevinfo* devinfo); + \brief Record device informations with given VID/PID + + This Function scans APB devices table and returns counth device informations according VID and PID. + + \param PID The PID of the device you whant to get. + \param VID The VID of the device you whant to get. + \param count The number of the device you whant to get. For example if you have 3 UARTS on your SOC you whant + to use UART1 so count = 2. + \param devinfo The device information structure to be populated. +*/ void apbgetdeviceinfofromid(int PID,int VID,int count,struct apbdevinfo* devinfo); + +/*! \fn void apbgetdeviceinfofromdevptr(const struct apbPnPreg* dev,struct apbdevinfo* devinfo); + \brief Record device informations with given AHB2APB Plugn'Play register. + + This Function extract device informations from the given AHB2APB Plugn'Play register end write them in devinfo. + + \param dev AHB2APB Plugn'Play register corresponding to the device. + \param devinfo The device information structure to be populated. +*/ void apbgetdeviceinfofromdevptr(const struct apbPnPreg* dev,struct apbdevinfo* devinfo); + +/*! \fn void apbprintdeviceinfo(struct apbdevinfo devinfo); + \brief Print given device informations in stdout. + + \param devinfo The device information structure to be printed. +*/ void apbprintdeviceinfo(struct apbdevinfo devinfo); + + +/*! \fn void apbprintdeviceslist(); + \brief Print APB devices informations in stdout. + + This function list all devices on APB bus and print theirs informations. + +*/ void apbprintdeviceslist(); + + + #endif // LPP_APB_FUNCTIONS_H + diff --git a/LPP_drivers/libsrc/LCD/apb_lcd_driver.h b/LPP_drivers/libsrc/LCD/apb_lcd_driver.h --- a/LPP_drivers/libsrc/LCD/apb_lcd_driver.h +++ b/LPP_drivers/libsrc/LCD/apb_lcd_driver.h @@ -26,7 +26,14 @@ #define lcdCharCnt 80 -/** @todo implemente some shift functions */ +/*! \file apb_lcd_driver.h + \brief APB char LCD driver. + + This library is written to work with apb_lcd VHDL module from LPP's VHDlib. It help you to drive char LCD. + + \author Alexis Jeandet + \todo implemente some shift functions +*/ /*=================================================== @@ -34,30 +41,31 @@ ====================================================*/ - -/** error type used for most of lcd functions */ -typedef int lcd_err; - /** lcd error ennum for higher abstraction level when error decoding */ enum lcd_error { - lcd_error_no_error, /**< no error append while function execution */ - lcd_error_not_ready, /**< the lcd isn't available*/ - lcd_error_not_openned, /**< the device guiven to the function isn't opened*/ - lcd_error_too_long /**< the string guiven to the lcd is bigger than the lcd frame buffer memory */ + lcd_error_no_error, /**< \brief no error append while function execution */ + lcd_error_not_ready, /**< \brief the lcd isn't available*/ + lcd_error_not_openned, /**< \brief the device guiven to the function isn't opened*/ + lcd_error_too_long /**< \brief the string guiven to the lcd is bigger than the lcd frame buffer memory */ }; +typedef enum lcd_error lcd_err; -/** for each command sended to the lcd driver a time should be guiven according to the lcd datasheet */ +/** for each command sended to the lcd driver a time should be guiven according to the lcd datasheet. +Don't worry about time, the lcd VHDL module should be aware of oscillator frequency. +*/ enum lcd_CMD_time { - lcd_4us = 0x0FF, + lcd_4us = 0x0FF, lcd_100us = 0x1FF, lcd_4ms = 0x2FF, lcd_20ms = 0x3FF }; -/** list of availiable lcd commands use whith an AND mask whith cmd time */ +/** list of availiable lcd commands use whith an AND mask whith cmd time +\todo implemente more commands. +*/ enum lcd_CMD { CursorON = 0xF0E, @@ -78,10 +86,24 @@ typedef struct lcd_driver lcd_device; F U N C T I O N S ====================================================*/ -/** says if the lcd is busy */ +/*! \fn int lcdbusy(lcd_device * lcd); + \brief Say if the lcd screen is busy + + \param lcd The lcd device to test. + \return True if the lcd is busy. +*/ int lcdbusy(lcd_device * lcd); -/** Opens and returns the counth lcd found on APB bus else NULL */ + +/*! \fn lcd_device* lcdopen(int count); + \brief Return counth LCD. + + This Function scans APB devices table and returns counth LCD. + + \param count The number of the LCD you whant to get. For example if you have 3 LCD on your SOC you whant + to use LCD1 so count = 2. + \return The pointer to the device. +*/ lcd_device* lcdopen(int count); /** Sends a command to the given device, don't forget to guive the time of the cmd */ diff --git a/LPP_drivers/libsrc/UART/apb_uart_Driver.h b/LPP_drivers/libsrc/UART/apb_uart_Driver.h --- a/LPP_drivers/libsrc/UART/apb_uart_Driver.h +++ b/LPP_drivers/libsrc/UART/apb_uart_Driver.h @@ -18,39 +18,94 @@ ------------------------------------------------------------------------------- -- Author : Martin Morlot -- Mail : martin.morlot@lpp.polytechnique.fr ------------------------------------------------------------------------------*/ +-----------------------------------------------------------------------------*/ #ifndef APB_UART_DRIVER_H -#define APB_UART_DRIVER_H - - -#define BaudGenOnDuty 0 -#define DataSended 0x10 -#define NewData 0x100 - +#define APB_UART_DRIVER_H + +/*! \file apb_uart_Driver.h + \brief LPP Uart driver. + + This library is written to work with LPP_APB_UART VHDL module from LPP's FreeVHDLIB. It help you to print and get + char or strings over uart. + + \todo Continue documentation + \author Martin Morlot +*/ + + + +#define BaudGenOnDuty 0 +#define DataSended 0x10 +#define NewData 0x100 + /*=================================================== T Y P E S D E F -====================================================*/ - -struct UART_Driver -{ - int ConfigReg; - int DataWReg; - int DataRReg; -}; - -typedef struct UART_Driver UART_Device; - - +====================================================*/ + +struct UART_Driver +{ + int ConfigReg; + int DataWReg; + int DataRReg; +}; + +typedef struct UART_Driver UART_Device; + + /*=================================================== F U N C T I O N S -====================================================*/ - - -UART_Device* openUART(int count); -void uartputc(UART_Device* dev,char c); -void uartputs(UART_Device* dev,char* s); -char uartgetc(UART_Device* dev); -void uartgets(UART_Device* dev,char* s); - - -#endif +====================================================*/ + +/*! \fn UART_Device* openUART(int count); + \brief Return counth UART. + + This Function scans APB devices table and returns counth UART. + + \param count The number of the UART you whant to get. For example if you have 3 UARTS on your SOC you whant + to use UART1 so count = 2. + \return The pointer to the device. +*/ +UART_Device* openUART(int count); + +/*! \fn void uartputc(UART_Device* dev,char c); + \brief Print char over given UART. + + This Function puts the given char over the given UART. + + \param dev The UART pointer. + \param c The char you whant to print. +*/ +void uartputc(UART_Device* dev,char c); + +/*! \fn void uartputs(UART_Device* dev,char* s); + \brief Print string over given UART. + + This Function puts the given string over the given UART. + + \param dev The UART pointer. + \param s The string you whant to print. +*/ +void uartputs(UART_Device* dev,char* s); + +/*! \fn char uartgetc(UART_Device* dev); + \brief Get char from given UART. + + This Function get char from the given UART. + + \param dev The UART pointer. + \return The read char. +*/ +char uartgetc(UART_Device* dev); + +/*! \fn void uartgets(UART_Device* dev,char* s); + \brief Get string from given UART. + + This Function get string from the given UART. + + \param dev The UART pointer. + \param s The read string. +*/ +void uartgets(UART_Device* dev,char* s); + + +#endif