Menu
▾
▴
libopencm3-devel
|
From: Weston S. <wes...@al...> - 2013-02-28 07:40:42
|
Hello, I'm working on a USB mass storage example & would like to document the APIs in a meaningful way as I go. Is there any way to get the USB documentation section added/enabled? I'm sure I could figure out the scheme, but I don't have time to spend on that aspect of the documentation + coding. If it's super easy & someone could point me to how I could learn to set it up, I could give it a try. Google + grep + prior doxygen knowledge didn't help me solve it in a reasonable amount of time. Thanks, Wes |
|
From: Ken S. <ksa...@in...> - 2013-02-28 08:21:29
|
On 28/02/13 18:08, Weston Schmidt wrote: > Hello, > > I'm working on a USB mass storage example & would like to document the > APIs in a meaningful way as I go. Is there any way to get the USB > documentation section added/enabled? I'm sure I could figure out the > scheme, but I don't have time to spend on that aspect of the > documentation + coding. Hi Weston I worked on documentation for a while last year and established a scheme of sorts, mainly focussed on getting doxygen to make a sensible hash of the job. Doxygen has trouble because there are multiple architectures to document separately in libopencm3, but with a lot of overlaps and commonality. Doing USB would be a fantastic help as I'm far from being ready to do it, but I'm not sure what guidance you need. Perhaps if you could start with the helper function descriptions, that would be the bulk of the job. I'll have a look at what else might be needed. > > If it's super easy & someone could point me to how I could learn to > set it up, I could give it a try. Google + grep + prior doxygen > knowledge didn't help me solve it in a reasonable amount of time. Unfortunately it wasn't super easy but hopefully the scheme that was set up will ease things a bit. I'll think about documenting the documentation. Keep in touch. Ken > > Thanks, > Wes > > > ------------------------------------------------------------------------------ > Everyone hates slow websites. So do we. > Make your web apps faster with AppDynamics > Download AppDynamics Lite for free today: > http://p.sf.net/sfu/appdyn_d2d_feb > > > _______________________________________________ > libopencm3-devel mailing list > lib...@li... > https://lists.sourceforge.net/lists/listinfo/libopencm3-devel |
|
From: Weston S. <wes...@al...> - 2013-02-28 09:30:54
|
Thanks Ken. Since you mentioned the overlaps, that got me thinking more about how those interacted from a doxygen point of view. I was able to enable usb documentation generation working for one chip, but not others. That is at least enough for me to get the documentation in place. Even if it doesn't generate right for a while, we can always go look at the code until we get it figured out. The location & structure of the USB code is different enough that I can't simply copy the scheme used in the 'simpler' peripherals like CRC. I'll get some APIs documented & request a push so it's easier to what is getting generated where. --Wes On Thu, Feb 28, 2013 at 12:16 AM, Ken Sarkies <ksa...@in...>wrote: > On 28/02/13 18:08, Weston Schmidt wrote: > > Hello, > > I'm working on a USB mass storage example & would like to document the > APIs in a meaningful way as I go. Is there any way to get the USB > documentation section added/enabled? I'm sure I could figure out the > scheme, but I don't have time to spend on that aspect of the documentation > + coding. > > Hi Weston > > I worked on documentation for a while last year and established a scheme > of sorts, mainly focussed on getting doxygen to make a sensible hash of the > job. Doxygen has trouble because there are multiple architectures to > document separately in libopencm3, but with a lot of overlaps and > commonality. Doing USB would be a fantastic help as I'm far from being > ready to do it, but I'm not sure what guidance you need. Perhaps if you > could start with the helper function descriptions, that would be the bulk > of the job. I'll have a look at what else might be needed. > > > If it's super easy & someone could point me to how I could learn to set it > up, I could give it a try. Google + grep + prior doxygen knowledge didn't > help me solve it in a reasonable amount of time. > > Unfortunately it wasn't super easy but hopefully the scheme that was set > up will ease things a bit. I'll think about documenting the documentation. > Keep in touch. > > Ken > > > Thanks, > Wes > > > ------------------------------------------------------------------------------ > Everyone hates slow websites. So do we. > Make your web apps faster with AppDynamics > Download AppDynamics Lite for free today:http://p.sf.net/sfu/appdyn_d2d_feb > > > > _______________________________________________ > libopencm3-devel mailing lis...@li...https://lists.sourceforge.net/lists/listinfo/libopencm3-devel > > > > > ------------------------------------------------------------------------------ > Everyone hates slow websites. So do we. > Make your web apps faster with AppDynamics > Download AppDynamics Lite for free today: > http://p.sf.net/sfu/appdyn_d2d_feb > _______________________________________________ > libopencm3-devel mailing list > lib...@li... > https://lists.sourceforge.net/lists/listinfo/libopencm3-devel > > |
|
From: Weston S. <wes...@al...> - 2013-03-02 05:12:53
|
Here is my first attempt at documenting some of the USB API. The inclusion only works for the F103 chip, but I'm hoping that it is fairly easy to fix that. https://github.com/schmidtw/libopencm3/commit/8bda85494a8ba535e2d64721223c8c8bfe366e61 I can request a pull if that would be easier. --Wes On Thu, Feb 28, 2013 at 1:28 AM, Weston Schmidt < wes...@al...> wrote: > Thanks Ken. > > Since you mentioned the overlaps, that got me thinking more about how > those interacted from a doxygen point of view. I was able to enable usb > documentation generation working for one chip, but not others. That is at > least enough for me to get the documentation in place. Even if it doesn't > generate right for a while, we can always go look at the code until we get > it figured out. The location & structure of the USB code is different > enough that I can't simply copy the scheme used in the 'simpler' > peripherals like CRC. > > I'll get some APIs documented & request a push so it's easier to what is > getting generated where. > > --Wes > > > On Thu, Feb 28, 2013 at 12:16 AM, Ken Sarkies <ksa...@in...>wrote: > >> On 28/02/13 18:08, Weston Schmidt wrote: >> >> Hello, >> >> I'm working on a USB mass storage example & would like to document the >> APIs in a meaningful way as I go. Is there any way to get the USB >> documentation section added/enabled? I'm sure I could figure out the >> scheme, but I don't have time to spend on that aspect of the documentation >> + coding. >> >> Hi Weston >> >> I worked on documentation for a while last year and established a scheme >> of sorts, mainly focussed on getting doxygen to make a sensible hash of the >> job. Doxygen has trouble because there are multiple architectures to >> document separately in libopencm3, but with a lot of overlaps and >> commonality. Doing USB would be a fantastic help as I'm far from being >> ready to do it, but I'm not sure what guidance you need. Perhaps if you >> could start with the helper function descriptions, that would be the bulk >> of the job. I'll have a look at what else might be needed. >> >> >> If it's super easy & someone could point me to how I could learn to set >> it up, I could give it a try. Google + grep + prior doxygen knowledge >> didn't help me solve it in a reasonable amount of time. >> >> Unfortunately it wasn't super easy but hopefully the scheme that was set >> up will ease things a bit. I'll think about documenting the documentation. >> Keep in touch. >> >> Ken >> >> >> Thanks, >> Wes >> >> >> ------------------------------------------------------------------------------ >> Everyone hates slow websites. So do we. >> Make your web apps faster with AppDynamics >> Download AppDynamics Lite for free today:http://p.sf.net/sfu/appdyn_d2d_feb >> >> >> >> _______________________________________________ >> libopencm3-devel mailing lis...@li...https://lists.sourceforge.net/lists/listinfo/libopencm3-devel >> >> >> >> >> ------------------------------------------------------------------------------ >> Everyone hates slow websites. So do we. >> Make your web apps faster with AppDynamics >> Download AppDynamics Lite for free today: >> http://p.sf.net/sfu/appdyn_d2d_feb >> _______________________________________________ >> libopencm3-devel mailing list >> lib...@li... >> https://lists.sourceforge.net/lists/listinfo/libopencm3-devel >> >> > |
|
From: Ken S. <ksa...@in...> - 2013-03-02 17:30:20
|
On 02/03/13 15:42, Weston Schmidt wrote: > Here is my first attempt at documenting some of the USB API. The > inclusion only works for the F103 chip, but I'm hoping that it is > fairly easy to fix that. > > https://github.com/schmidtw/libopencm3/commit/8bda85494a8ba535e2d64721223c8c8bfe366e61 > > I can request a pull if that would be easier. Had a quick look but I need to get onto them in depth in a couple of days time. It's a good start and will go a long way to providing the base documentation. The parameter descriptions are eventually linked to the headers where parameter ranges are defined. As far as linking into the whole documentation system, I can look at doing that as a separate exercise. It depends on how much USB varies between devices. Since it has a directory of its own I suspect there may be a lot of #define stuff trying to cope with differences. That makes it rather difficult for doxygen and it may be better to split files up, which can be a real headache. Last year I put in a HACKING file in the base doxygen directory just to set the scene, but it may be a bit arcane and could be improved. Best not to issue pull requests just yet. I can access your commits OK. cheers, Ken > > --Wes > > On Thu, Feb 28, 2013 at 1:28 AM, Weston Schmidt > <wes...@al... > <mailto:wes...@al...>> wrote: > > Thanks Ken. > > Since you mentioned the overlaps, that got me thinking more about > how those interacted from a doxygen point of view. I was able to > enable usb documentation generation working for one chip, but not > others. That is at least enough for me to get the documentation > in place. Even if it doesn't generate right for a while, we can > always go look at the code until we get it figured out. The > location & structure of the USB code is different enough that I > can't simply copy the scheme used in the 'simpler' peripherals > like CRC. > > I'll get some APIs documented & request a push so it's easier to > what is getting generated where. > > --Wes > > > On Thu, Feb 28, 2013 at 12:16 AM, Ken Sarkies > <ksa...@in... <mailto:ksa...@in...>> wrote: > > On 28/02/13 18:08, Weston Schmidt wrote: >> Hello, >> >> I'm working on a USB mass storage example & would like to >> document the APIs in a meaningful way as I go. Is there any >> way to get the USB documentation section added/enabled? I'm >> sure I could figure out the scheme, but I don't have time to >> spend on that aspect of the documentation + coding. > Hi Weston > > I worked on documentation for a while last year and > established a scheme of sorts, mainly focussed on getting > doxygen to make a sensible hash of the job. Doxygen has > trouble because there are multiple architectures to document > separately in libopencm3, but with a lot of overlaps and > commonality. Doing USB would be a fantastic help as I'm far > from being ready to do it, but I'm not sure what guidance you > need. Perhaps if you could start with the helper function > descriptions, that would be the bulk of the job. I'll have a > look at what else might be needed. > >> >> If it's super easy & someone could point me to how I could >> learn to set it up, I could give it a try. Google + grep + >> prior doxygen knowledge didn't help me solve it in a >> reasonable amount of time. > Unfortunately it wasn't super easy but hopefully the scheme > that was set up will ease things a bit. I'll think about > documenting the documentation. Keep in touch. > > Ken >> >> Thanks, >> Wes >> >> >> ------------------------------------------------------------------------------ >> Everyone hates slow websites. So do we. >> Make your web apps faster with AppDynamics >> Download AppDynamics Lite for free today: >> http://p.sf.net/sfu/appdyn_d2d_feb >> >> >> _______________________________________________ >> libopencm3-devel mailing list >> lib...@li... <mailto:lib...@li...> >> https://lists.sourceforge.net/lists/listinfo/libopencm3-devel > > > ------------------------------------------------------------------------------ > Everyone hates slow websites. So do we. > Make your web apps faster with AppDynamics > Download AppDynamics Lite for free today: > http://p.sf.net/sfu/appdyn_d2d_feb > _______________________________________________ > libopencm3-devel mailing list > lib...@li... > <mailto:lib...@li...> > https://lists.sourceforge.net/lists/listinfo/libopencm3-devel > > > |
|
From: Weston S. <wes...@al...> - 2013-03-03 02:14:01
|
Thanks Ken. It looks like the USB code has 2 layers - the external layer, which does all the heavy lifting across all platforms, and the device implementation layer that implements a small set of APIs that are setup at runtime/linktime. When creating a device (like a HID device) I think we should only care about the code in usb.c and usb_control.c. When creating a platform port, then you care about the other layer interface (that I haven't documented yet). I look forward to your feedback in a few days. --Wes On Sat, Mar 2, 2013 at 9:14 AM, Ken Sarkies <ksa...@in...>wrote: > On 02/03/13 15:42, Weston Schmidt wrote: > > Here is my first attempt at documenting some of the USB API. The > inclusion only works for the F103 chip, but I'm hoping that it is fairly > easy to fix that. > > > https://github.com/schmidtw/libopencm3/commit/8bda85494a8ba535e2d64721223c8c8bfe366e61 > > I can request a pull if that would be easier. > > Had a quick look but I need to get onto them in depth in a couple of days > time. It's a good start and will go a long way to providing the base > documentation. The parameter descriptions are eventually linked to the > headers where parameter ranges are defined. As far as linking into the > whole documentation system, I can look at doing that as a separate > exercise. It depends on how much USB varies between devices. Since it has a > directory of its own I suspect there may be a lot of #define stuff trying > to cope with differences. That makes it rather difficult for doxygen and it > may be better to split files up, which can be a real headache. > > Last year I put in a HACKING file in the base doxygen directory just to > set the scene, but it may be a bit arcane and could be improved. > > Best not to issue pull requests just yet. I can access your commits OK. > > cheers, Ken > > > --Wes > > On Thu, Feb 28, 2013 at 1:28 AM, Weston Schmidt < > wes...@al...> wrote: > >> Thanks Ken. >> >> Since you mentioned the overlaps, that got me thinking more about how >> those interacted from a doxygen point of view. I was able to enable usb >> documentation generation working for one chip, but not others. That is at >> least enough for me to get the documentation in place. Even if it doesn't >> generate right for a while, we can always go look at the code until we get >> it figured out. The location & structure of the USB code is different >> enough that I can't simply copy the scheme used in the 'simpler' >> peripherals like CRC. >> >> I'll get some APIs documented & request a push so it's easier to what is >> getting generated where. >> >> --Wes >> >> >> On Thu, Feb 28, 2013 at 12:16 AM, Ken Sarkies <ksa...@in...>wrote: >> >>> On 28/02/13 18:08, Weston Schmidt wrote: >>> >>> Hello, >>> >>> I'm working on a USB mass storage example & would like to document the >>> APIs in a meaningful way as I go. Is there any way to get the USB >>> documentation section added/enabled? I'm sure I could figure out the >>> scheme, but I don't have time to spend on that aspect of the documentation >>> + coding. >>> >>> Hi Weston >>> >>> I worked on documentation for a while last year and established a scheme >>> of sorts, mainly focussed on getting doxygen to make a sensible hash of the >>> job. Doxygen has trouble because there are multiple architectures to >>> document separately in libopencm3, but with a lot of overlaps and >>> commonality. Doing USB would be a fantastic help as I'm far from being >>> ready to do it, but I'm not sure what guidance you need. Perhaps if you >>> could start with the helper function descriptions, that would be the bulk >>> of the job. I'll have a look at what else might be needed. >>> >>> >>> If it's super easy & someone could point me to how I could learn to set >>> it up, I could give it a try. Google + grep + prior doxygen knowledge >>> didn't help me solve it in a reasonable amount of time. >>> >>> Unfortunately it wasn't super easy but hopefully the scheme that was >>> set up will ease things a bit. I'll think about documenting the >>> documentation. Keep in touch. >>> >>> Ken >>> >>> >>> Thanks, >>> Wes >>> >>> >>> ------------------------------------------------------------------------------ >>> Everyone hates slow websites. So do we. >>> Make your web apps faster with AppDynamics >>> Download AppDynamics Lite for free today:http://p.sf.net/sfu/appdyn_d2d_feb >>> >>> >>> >>> _______________________________________________ >>> libopencm3-devel mailing lis...@li...https://lists.sourceforge.net/lists/listinfo/libopencm3-devel >>> >>> >>> >>> >>> ------------------------------------------------------------------------------ >>> Everyone hates slow websites. So do we. >>> Make your web apps faster with AppDynamics >>> Download AppDynamics Lite for free today: >>> http://p.sf.net/sfu/appdyn_d2d_feb >>> _______________________________________________ >>> libopencm3-devel mailing list >>> lib...@li... >>> https://lists.sourceforge.net/lists/listinfo/libopencm3-devel >>> >>> >> > > > > ------------------------------------------------------------------------------ > Everyone hates slow websites. So do we. > Make your web apps faster with AppDynamics > Download AppDynamics Lite for free today: > http://p.sf.net/sfu/appdyn_d2d_feb > _______________________________________________ > libopencm3-devel mailing list > lib...@li... > https://lists.sourceforge.net/lists/listinfo/libopencm3-devel > > |
|
From: Gareth M. <ga...@bl...> - 2013-03-04 21:37:06
|
> It looks like the USB code has 2 layers - the external layer, which does > all the heavy lifting across all platforms, and the device implementation > layer that implements a small set of APIs that are setup at > runtime/linktime. When creating a device (like a HID device) I think we > should only care about the code in usb.c and usb_control.c. When creating > a platform port, then you care about the other layer interface (that I > haven't documented yet). > This is the case. Everything an application developer needs to implement a device is in usbd.h and usbstd.h. The details of the methods provided in struct _usbd_driver (usb_private.h) are needed if you intend to add support for another hardware implementation to the library. This structure is not intended to be available to application developers. Cheers, Gareth -- *Black Sphere Technologies Ltd.* Web: www.blacksphere.co.nz Mobile: +64 27 777 2182 Tel: +64 9 478 8885 Skype: gareth.mcmullin LinkedIn: http://nz.linkedin.com/in/gsmcmullin |
|
From: Ken S. <ksa...@in...> - 2013-03-05 00:43:16
Attachments:
example-usb-doc.c
example-usb-doc.h
|
On 05/03/13 07:59, Gareth McMullin wrote:
>
> It looks like the USB code has 2 layers - the external layer,
> which does all the heavy lifting across all platforms, and the
> device implementation layer that implements a small set of APIs
> that are setup at runtime/linktime. When creating a device (like
> a HID device) I think we should only care about the code in usb.c
> and usb_control.c. When creating a platform port, then you care
> about the other layer interface (that I haven't documented yet).
>
>
> This is the case. Everything an application developer needs to
> implement a device is in usbd.h and usbstd.h. The details of the
> methods provided in struct _usbd_driver (usb_private.h) are needed if
> you intend to add support for another hardware implementation to the
> library. This structure is not intended to be available to application
> developers.
Thanks Gareth, it was helpful in starting to make a bit of headway.
Weston, I'm afraid I'm on a bit of a fool's errand here, knowing zilch
about USB, so I'm proposing a documentation structure based on the files
as they appear in the USB header and source directories. There are some
device specific ones and some also in other directories which I think
we're not worrying about at the moment. These would need to be linked up
eventually but perhaps to appear under the specific device documentation.
Propose a grouping tree, separate from the device specific groups, as it
would appear in the documentation:
USB
USB_defines
CDC_class
DFU_class
HID_class
USB_driver
USB_structure_defines
USB_files
USB_control
USB_standard
USB
The names perhaps need to be refined, particularly for the source files.
Two example files are attached (may not show up in the forum) showing
the heading part and how to incorporate the helper function
documentation (source file) and definition groupings (header file). In
the latter the enums are self-documenting under doxygen. Not sure about
the structs.
I'll keep working on it over the next week. Then once everyone seems
agreeable I'll push up the top level doc files so that it all links in.
cheers, Ken
>
> Cheers,
> Gareth
>
> --
> *Black Sphere Technologies Ltd.*
>
> Web: www.blacksphere.co.nz <http://www.blacksphere.co.nz>
> Mobile: +64 27 777 2182
> Tel: +64 9 478 8885
> Skype: gareth.mcmullin
> LinkedIn: http://nz.linkedin.com/in/gsmcmullin
>
>
|
|
From: Ken S. <ksa...@in...> - 2013-03-10 23:35:07
|
Hi All I have put up a commit https://github.com/ksarkies/libopencm3/commit/usb to place the USB generic stuff into the documentation tree. Before going further I need some advice about the suitability of this. The file changes under the doc/ directory are noncontroversial and can be ignored for now. The files changes under /include/libopencm3 and /lib have had heading @defgroup blocks added, and the group inclusion brackets /**@{*/ /**@}*/ added at the top and bottom. In some of the files, functions whose names start with underscore I have taken to be internal (non-API) and so these are not included in the group. If this is incorrect please let me know. There are some struct names starting with underscore that seem to be in the API as shown in some of the examples. The titles for these files are based on a scan of the contents of the files and there may be better names to use. Please advise. There are two files under /include/libopencm3/stm32/f1 of which usb_desc.h is one with which I know not what to do (pardon the grammar). It has not been included yet in the documentation. Obviously detailed commentary is needed throughout, but this is a matter for those who know more than I and can be added later. One point that struck me is the existence of a header file in the source directory lib/usb, which I placed under the usb_defines doc group (does it really need to be amongst the source files?), and the existence of device specific files for some of the STM32F1 STM32F2 families. There are also extern'ed variables that mention device specific drivers in usbd.h. These seem to me to be best placed somewhere in device specific locations allowing the USB code to be generalized to other families (I assume this is possible with the generic code as such). Hope this makes sense. cheers, Ken |
|
From: Weston S. <wes...@al...> - 2013-03-11 05:31:55
|
Ken, what you did makes sense to me, too. I'm not sure what to make of the file usb_desc.h - or why it is located where it is. That looks like the USB chapter-9 definitions that are found in include/libopencm3/usb/usbstd.h. Piotr, your name is on the file in question (include/libopencm3/stm32/f1/usb_desc.h) - can you help us understand if it is in the right place, should be moved or is now duplicated by include/libopencm3/usb/usbstd.h? I interpreted the prefix _ to mean they are private, but need to be in a header file for a good reason. --Wes On Sun, Mar 10, 2013 at 4:34 PM, Ken Sarkies <ksa...@in...>wrote: > Hi All > > I have put up a commit https://github.com/ksarkies/libopencm3/commit/usb > to place the USB generic stuff into the documentation tree. Before going > further I need some advice about the suitability of this. > > The file changes under the doc/ directory are noncontroversial and can > be ignored for now. > > The files changes under /include/libopencm3 and /lib have had heading > @defgroup blocks added, and the group inclusion brackets /**@{*/ /**@}*/ > added at the top and bottom. In some of the files, functions whose names > start with underscore I have taken to be internal (non-API) and so these > are not included in the group. If this is incorrect please let me know. > There are some struct names starting with underscore that seem to be in > the API as shown in some of the examples. > > The titles for these files are based on a scan of the contents of the > files and there may be better names to use. Please advise. > > There are two files under /include/libopencm3/stm32/f1 of which > usb_desc.h is one with which I know not what to do (pardon the grammar). > It has not been included yet in the documentation. > > Obviously detailed commentary is needed throughout, but this is a matter > for those who know more than I and can be added later. > > One point that struck me is the existence of a header file in the source > directory lib/usb, which I placed under the usb_defines doc group (does > it really need to be amongst the source files?), and the existence of > device specific files for some of the STM32F1 STM32F2 families. There > are also extern'ed variables that mention device specific drivers in > usbd.h. These seem to me to be best placed somewhere in device specific > locations allowing the USB code to be generalized to other families (I > assume this is possible with the generic code as such). > > Hope this makes sense. > > cheers, Ken > > > ------------------------------------------------------------------------------ > Symantec Endpoint Protection 12 positioned as A LEADER in The Forrester > Wave(TM): Endpoint Security, Q1 2013 and "remains a good choice" in the > endpoint security space. For insight on selecting the right partner to > tackle endpoint security challenges, access the full report. > http://p.sf.net/sfu/symantec-dev2dev > _______________________________________________ > libopencm3-devel mailing list > lib...@li... > https://lists.sourceforge.net/lists/listinfo/libopencm3-devel > |
Thanks for helping keep SourceForge clean.
X