From 1374d2622be04278bc3918572c20ac694dfef0a3 Mon Sep 17 00:00:00 2001 From: Ken Sarkies Date: Mon, 11 Mar 2013 09:36:57 +1030 Subject: [PATCH] Place generic USB header and source files into the documentation tree. --- doc/usb/Doxyfile | 33 +++++ doc/usb/Doxyfile_latex | 40 ++++++ doc/usb/DoxygenLayout_usb.xml | 199 ++++++++++++++++++++++++++++++ doc/usb/header_usb.tex | 61 +++++++++ include/libopencm3/stm32/f1/usb.h | 19 +++ include/libopencm3/usb/cdc.h | 20 +++ include/libopencm3/usb/dfu.h | 20 +++ include/libopencm3/usb/doc-usb.h | 32 +++++ include/libopencm3/usb/hid.h | 20 +++ include/libopencm3/usb/usbd.h | 20 +++ include/libopencm3/usb/usbstd.h | 24 ++++ lib/usb/usb.c | 20 +++ lib/usb/usb_control.c | 21 ++++ lib/usb/usb_private.h | 21 ++++ lib/usb/usb_standard.c | 21 ++++ 15 files changed, 571 insertions(+) create mode 100644 doc/usb/Doxyfile create mode 100644 doc/usb/Doxyfile_latex create mode 100644 doc/usb/DoxygenLayout_usb.xml create mode 100644 doc/usb/header_usb.tex create mode 100644 include/libopencm3/usb/doc-usb.h diff --git a/doc/usb/Doxyfile b/doc/usb/Doxyfile new file mode 100644 index 00000000..ff48cb33 --- /dev/null +++ b/doc/usb/Doxyfile @@ -0,0 +1,33 @@ +# HTML Documentation for USB code level + +# 10 March 2013 +# (C) Ken Sarkies + +#--------------------------------------------------------------------------- +# Common Include File +#--------------------------------------------------------------------------- + +@INCLUDE = ../Doxyfile_common + +#--------------------------------------------------------------------------- +# Local settings +#--------------------------------------------------------------------------- + +WARN_LOGFILE = doxygen_usb.log + +INPUT = ../../include/libopencm3/license.dox \ + ../../include/libopencm3/usb + +INPUT += ../../lib/usb + +EXCLUDE_PATTERNS = + +LAYOUT_FILE = DoxygenLayout_usb.xml + +TAGFILES = + +GENERATE_TAGFILE = usb.tag + +ENABLE_PREPROCESSING = NO + + diff --git a/doc/usb/Doxyfile_latex b/doc/usb/Doxyfile_latex new file mode 100644 index 00000000..00392aaa --- /dev/null +++ b/doc/usb/Doxyfile_latex @@ -0,0 +1,40 @@ +# LaTeX Documentation for USB code level + +# 10 March 2013 +# (C) Ken Sarkies + +#--------------------------------------------------------------------------- +# Common Include File +#--------------------------------------------------------------------------- + +@INCLUDE = ../Doxyfile_common + +#--------------------------------------------------------------------------- +# Local settings +#--------------------------------------------------------------------------- + +WARN_LOGFILE = doxygen_usb_latex.log + +WARN_LOGFILE = doxygen_usb.log + +INPUT = ../../include/libopencm3/license.dox \ + ../../include/libopencm3/usb + +INPUT += ../../lib/usb + +EXCLUDE_PATTERNS = + +LAYOUT_FILE = DoxygenLayout_usb.xml + +TAGFILES = + +GENERATE_TAGFILE = usb.tag + +ENABLE_PREPROCESSING = NO + +GENERATE_HTML = NO + +GENERATE_LATEX = YES + +LATEX_HEADER = header_usb.tex + diff --git a/doc/usb/DoxygenLayout_usb.xml b/doc/usb/DoxygenLayout_usb.xml new file mode 100644 index 00000000..ee9718b5 --- /dev/null +++ b/doc/usb/DoxygenLayout_usb.xml @@ -0,0 +1,199 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/usb/header_usb.tex b/doc/usb/header_usb.tex new file mode 100644 index 00000000..5b902527 --- /dev/null +++ b/doc/usb/header_usb.tex @@ -0,0 +1,61 @@ +\documentclass{book} +\usepackage[a4paper,top=2.5cm,bottom=2.5cm,left=2.5cm,right=2.5cm]{geometry} +\usepackage{makeidx} +\usepackage{natbib} +\usepackage{graphicx} +\usepackage{multicol} +\usepackage{float} +\usepackage{listings} +\usepackage{color} +\usepackage{ifthen} +\usepackage[table]{xcolor} +\usepackage{textcomp} +\usepackage{alltt} +\usepackage{ifpdf} +\ifpdf +\usepackage[pdftex, + pagebackref=true, + colorlinks=true, + linkcolor=blue, + unicode + ]{hyperref} +\else +\usepackage[ps2pdf, + pagebackref=true, + colorlinks=true, + linkcolor=blue, + unicode + ]{hyperref} +\usepackage{pspicture} +\fi +\usepackage[utf8]{inputenc} +\usepackage{mathptmx} +\usepackage[scaled=.90]{helvet} +\usepackage{courier} +\usepackage{sectsty} +\usepackage{amssymb} +\usepackage[titles]{tocloft} +\usepackage{doxygen} +\lstset{language=C++,inputencoding=utf8,basicstyle=\footnotesize,breaklines=true,breakatwhitespace=true,tabsize=4,numbers=left } +\makeindex +\setcounter{tocdepth}{3} +\renewcommand{\footrulewidth}{0.4pt} +\renewcommand{\familydefault}{\sfdefault} +\hfuzz=15pt +\setlength{\emergencystretch}{15pt} +\hbadness=750 +\tolerance=750 +\begin{document} +\hypersetup{pageanchor=false,citecolor=blue} +\begin{titlepage} +\vspace*{7cm} +\begin{center} +{\Huge libopencm3: API Reference\\ Cortex M3 Generic USB}\\ +\vspace*{1cm} +{\large Generated by Doxygen 1.8.2}\\ +\vspace*{0.5cm} +{\small Thu 10 March 2013 23:26:45}\\ +\end{center} +\end{titlepage} +\pagenumbering{arabic} +\hypersetup{pageanchor=true,citecolor=blue} diff --git a/include/libopencm3/stm32/f1/usb.h b/include/libopencm3/stm32/f1/usb.h index 20e9dff3..6b9d4f43 100644 --- a/include/libopencm3/stm32/f1/usb.h +++ b/include/libopencm3/stm32/f1/usb.h @@ -1,3 +1,17 @@ +/** @defgroup adc_defines USB Defines + +@brief Defined Constants and Types for the STM32F1xx USB Module + +@ingroup STM32F1xx_defines + +@version 1.0.0 + +@author @htmlonly © @endhtmlonly 2009 Piotr Esden-Tempski + +@date 11 March 2013 + +LGPL License Terms @ref lgpl_license + */ /* * This file is part of the libopencm3 project. * @@ -17,6 +31,8 @@ * along with this library. If not, see . */ +/**@{*/ + #ifndef LIBOPENCM3_USB_H #define LIBOPENCM3_USB_H @@ -257,3 +273,6 @@ (USB_PMA_BASE + (u8 *)(USB_GET_EP_RX_ADDR(EP) * 2)) #endif + +/**@}*/ + diff --git a/include/libopencm3/usb/cdc.h b/include/libopencm3/usb/cdc.h index 5036411f..1efb36e9 100644 --- a/include/libopencm3/usb/cdc.h +++ b/include/libopencm3/usb/cdc.h @@ -1,3 +1,18 @@ +/** @defgroup usb_cdc_defines USB CDC Type Definitions + +@brief Defined Constants and Types for the USB CDC Type Definitions + +@ingroup USB_defines + +@version 1.0.0 + +@author @htmlonly © @endhtmlonly 2010 Gareth McMullin + +@date 10 March 2013 + +LGPL License Terms @ref lgpl_license +*/ + /* * This file is part of the libopencm3 project. * @@ -17,6 +32,8 @@ * along with this library. If not, see . */ +/**@{*/ + #ifndef __CDC_H #define __CDC_H @@ -125,3 +142,6 @@ struct usb_cdc_notification { } __attribute__((packed)); #endif + +/**@}*/ + diff --git a/include/libopencm3/usb/dfu.h b/include/libopencm3/usb/dfu.h index f0802063..7c8099f1 100644 --- a/include/libopencm3/usb/dfu.h +++ b/include/libopencm3/usb/dfu.h @@ -1,3 +1,18 @@ +/** @defgroup usb_dfu_defines USB DFU Type Definitions + +@brief Defined Constants and Types for the USB DFU Type Definitions + +@ingroup USB_defines + +@version 1.0.0 + +@author @htmlonly © @endhtmlonly 2010 Gareth McMullin + +@date 10 March 2013 + +LGPL License Terms @ref lgpl_license +*/ + /* * This file is part of the libopencm3 project. * @@ -17,6 +32,8 @@ * along with this library. If not, see . */ +/**@{*/ + #ifndef __DFU_H #define __DFU_H @@ -79,3 +96,6 @@ struct usb_dfu_descriptor { } __attribute__((packed)); #endif + +/**@}*/ + diff --git a/include/libopencm3/usb/doc-usb.h b/include/libopencm3/usb/doc-usb.h new file mode 100644 index 00000000..faa01b11 --- /dev/null +++ b/include/libopencm3/usb/doc-usb.h @@ -0,0 +1,32 @@ +/** @mainpage libopencm3 Generic USB + +@version 1.0.0 + +@date 10 March 2013 + +API documentation for Generic USB. + +LGPL License Terms @ref lgpl_license +*/ + +/** @defgroup USB Generic USB +Libraries for Generic USB. + +@version 1.0.0 + +@date 10 March 2013 + +LGPL License Terms @ref lgpl_license +*/ + +/** @defgroup USB_defines Generic USB Defines + +@brief Defined Constants and Types for Generic USB. + +@version 1.0.0 + +@date 10 March 2013 + +LGPL License Terms @ref lgpl_license +*/ + diff --git a/include/libopencm3/usb/hid.h b/include/libopencm3/usb/hid.h index d2f51173..31973ec5 100644 --- a/include/libopencm3/usb/hid.h +++ b/include/libopencm3/usb/hid.h @@ -1,3 +1,18 @@ +/** @defgroup usb_hid_defines USB HID Type Definitions + +@brief Defined Constants and Types for the USB HID Type Definitions + +@ingroup USB_defines + +@version 1.0.0 + +@author @htmlonly © @endhtmlonly 2010 Gareth McMullin + +@date 10 March 2013 + +LGPL License Terms @ref lgpl_license +*/ + /* * This file is part of the libopencm3 project. * @@ -17,6 +32,8 @@ * along with this library. If not, see . */ +/**@{*/ + #ifndef __HID_H #define __HID_H @@ -36,3 +53,6 @@ struct usb_hid_descriptor { } __attribute__((packed)); #endif + +/**@}*/ + diff --git a/include/libopencm3/usb/usbd.h b/include/libopencm3/usb/usbd.h index 2e5b7fbb..e81714fc 100644 --- a/include/libopencm3/usb/usbd.h +++ b/include/libopencm3/usb/usbd.h @@ -1,3 +1,18 @@ +/** @defgroup usb_driver_defines USB Drivers + +@brief Defined Constants and Types for the USB Drivers + +@ingroup USB_defines + +@version 1.0.0 + +@author @htmlonly © @endhtmlonly 2010 Gareth McMullin + +@date 10 March 2013 + +LGPL License Terms @ref lgpl_license +*/ + /* * This file is part of the libopencm3 project. * @@ -17,6 +32,8 @@ * along with this library. If not, see . */ +/**@{*/ + #ifndef __USBD_H #define __USBD_H @@ -100,3 +117,6 @@ extern void usbd_cable_connect(usbd_device *usbd_dev, u8 on); END_DECLS #endif + +/**@}*/ + diff --git a/include/libopencm3/usb/usbstd.h b/include/libopencm3/usb/usbstd.h index 79082806..9d0006f0 100644 --- a/include/libopencm3/usb/usbstd.h +++ b/include/libopencm3/usb/usbstd.h @@ -1,3 +1,22 @@ +/** @defgroup usb_type_defines USB Standard Structure Definitions + +@brief Defined Constants and Types for the USB Standard Structure Definitions + +@ingroup USB_defines + +@version 1.0.0 + +@author @htmlonly © @endhtmlonly 2010 Gareth McMullin + +@date 10 March 2013 + +A set of structure definitions for the USB control structures +defined in chapter 9 of the "Univeral Serial Bus Specification Revision 2.0" +Available from the USB Implementers Forum - http://www.usb.org/ + +LGPL License Terms @ref lgpl_license +*/ + /* * This file is part of the libopencm3 project. * @@ -17,6 +36,8 @@ * along with this library. If not, see . */ +/**@{*/ + #ifndef __USBSTD_H #define __USBSTD_H @@ -227,3 +248,6 @@ enum usb_language_id { USB_LANGID_ENGLISH_US = 0x409, }; #endif + +/**@}*/ + diff --git a/lib/usb/usb.c b/lib/usb/usb.c index 0799202a..6aa83917 100644 --- a/lib/usb/usb.c +++ b/lib/usb/usb.c @@ -1,3 +1,18 @@ +/** @defgroup usb_drivers_file Generic USB Drivers + +@ingroup USB + +@brief Generic USB Drivers + +@version 1.0.0 + +@author @htmlonly © @endhtmlonly 2010 Gareth McMullin + +@date 10 March 2013 + +LGPL License Terms @ref lgpl_license +*/ + /* * This file is part of the libopencm3 project. * @@ -17,6 +32,8 @@ * along with this library. If not, see . */ +/**@{*/ + #include #include #include "usb_private.h" @@ -150,3 +167,6 @@ void usbd_ep_nak_set(usbd_device *usbd_dev, u8 addr, u8 nak) { usbd_dev->driver->ep_nak_set(usbd_dev, addr, nak); } + +/**@}*/ + diff --git a/lib/usb/usb_control.c b/lib/usb/usb_control.c index 82843dfb..b387d4b3 100644 --- a/lib/usb/usb_control.c +++ b/lib/usb/usb_control.c @@ -1,3 +1,18 @@ +/** @defgroup usb_control_file Generic USB Control Requests + +@ingroup USB + +@brief Generic USB Control Requests + +@version 1.0.0 + +@author @htmlonly © @endhtmlonly 2010 Gareth McMullin + +@date 10 March 2013 + +LGPL License Terms @ref lgpl_license +*/ + /* * This file is part of the libopencm3 project. * @@ -17,6 +32,8 @@ * along with this library. If not, see . */ +/**@{*/ + #include #include #include "usb_private.h" @@ -151,6 +168,9 @@ static void usb_control_setup_write(usbd_device *usbd_dev, usbd_dev->control_state.state = LAST_DATA_OUT; } +/* Do not appear to belong to the API, so are omitted from docs */ +/**@}*/ + void _usbd_control_setup(usbd_device *usbd_dev, u8 ea) { struct usb_setup_data *req = &usbd_dev->control_state.req; @@ -241,3 +261,4 @@ void _usbd_control_in(usbd_device *usbd_dev, u8 ea) usbd_ep_stall_set(usbd_dev, 0, 1); } } + diff --git a/lib/usb/usb_private.h b/lib/usb/usb_private.h index 96236756..dcf14875 100644 --- a/lib/usb/usb_private.h +++ b/lib/usb/usb_private.h @@ -1,3 +1,18 @@ +/** @defgroup usb_private_defines USB Private Structures + +@brief Defined Constants and Types for the USB Private Structures + +@ingroup USB_defines + +@version 1.0.0 + +@author @htmlonly © @endhtmlonly 2010 Gareth McMullin + +@date 10 March 2013 + +LGPL License Terms @ref lgpl_license +*/ + /* * This file is part of the libopencm3 project. * @@ -17,6 +32,8 @@ * along with this library. If not, see . */ +/**@{*/ + #ifndef __USB_PRIVATE_H #define __USB_PRIVATE_H @@ -95,6 +112,9 @@ enum _usbd_transaction { USB_TRANSACTION_SETUP, }; +/* Do not appear to belong to the API, so are omitted from docs */ +/**@}*/ + void _usbd_control_in(usbd_device *usbd_dev, u8 ea); void _usbd_control_out(usbd_device *usbd_dev, u8 ea); void _usbd_control_setup(usbd_device *usbd_dev, u8 ea); @@ -135,3 +155,4 @@ struct _usbd_driver { }; #endif + diff --git a/lib/usb/usb_standard.c b/lib/usb/usb_standard.c index e14fee35..aebc4c0d 100644 --- a/lib/usb/usb_standard.c +++ b/lib/usb/usb_standard.c @@ -1,3 +1,18 @@ +/** @defgroup usb_standard_file Generic USB Standard Request Interface + +@ingroup USB + +@brief Generic USB Standard Request Interface + +@version 1.0.0 + +@author @htmlonly © @endhtmlonly 2010 Gareth McMullin + +@date 10 March 2013 + +LGPL License Terms @ref lgpl_license +*/ + /* * This file is part of the libopencm3 project. * @@ -17,6 +32,8 @@ * along with this library. If not, see . */ +/**@{*/ + #include #include #include "usb_private.h" @@ -333,6 +350,9 @@ static int usb_standard_endpoint_unstall(usbd_device *usbd_dev, return 1; } +/* Do not appear to belong to the API, so are omitted from docs */ +/**@}*/ + int _usbd_standard_request_device(usbd_device *usbd_dev, struct usb_setup_data *req, u8 **buf, u16 *len) @@ -466,3 +486,4 @@ int _usbd_standard_request(usbd_device *usbd_dev, return 0; } } +