ASF function user manual ?

Go To Last Post
13 posts / 0 new
Author
Message
#1
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

I am starting using ASF. And i have simple question. Where is usable documentation to using functions. Example: I want to choose clock source for clockout in SAME70. In pmc.h (there are two different files with this name :D ) i find function:

void pmc_pck_set_source(uint32_t ul_id, uint32_t ul_source);

how can i find macros that can be used as "inputs" for that function ?

Thanks
Michal 

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

I just typed "pmc_pck_set_source" into Google. It said:

 

http://asf.atmel.com/docs/latest...

 

(actually I knew it would)

 

To be honest that page is actually for SAM3 not SAME70 though I imagine it is the same for most chips (which is kind of the point of ASF). The key thing is it gets you to the ASF documentation site. If you click on "API" at the left it takes you to a searchable index for all modules and all devices. If I filter on "power management" and "SAM70" I get this:

 

 

Oh this is rich! If you click through the top link there you get to:

 

 

The stupid web page design means that the link to the Quick Start Guide fro SAME70 is presumably "off the edge of the page" and inaccessible. Well done Atmel!

Last Edited: Thu. Jun 29, 2017 - 08:30 AM
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

As Cliff says, all the ASF documentation is online.

 

They abandoned PDFs some years ago - although there may still be some old ones kicking around the interwebs...

 

Top Tips:

  1. How to properly post source code - see: https://www.avrfreaks.net/comment... - also how to properly include images/pictures
  2. "Garbage" characters on a serial terminal are (almost?) invariably due to wrong baud rate - see: https://learn.sparkfun.com/tutorials/serial-communication
  3. Wrong baud rate is usually due to not running at the speed you thought; check by blinking a LED to see if you get the speed you expected
  4. Difference between a crystal, and a crystal oscillatorhttps://www.avrfreaks.net/comment...
  5. When your question is resolved, mark the solution: https://www.avrfreaks.net/comment...
  6. Beginner's "Getting Started" tips: https://www.avrfreaks.net/comment...
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

Thanks for your help. I've found this "documentation". But it does not contain any relevant information. It looks like "copied" header file. If i want to use ASF library functions, i have to find information which macros can serve as input for these functions. 

for example:
void pmc_pck_set_source(uint32_t ul_id, uint32_t ul_source);

first argument can be:
PMC_PCK_0
PMC_PCK_1
PMC_PCK_2
PMC_PCK_3
PMC_PCK_4
PMC_PCK_5
PMC_PCK_6

and second argument can be:
PMC_PCK_CSS_SLOW_CLK
PMC_PCK_CSS_MAIN_CLK
PMC_PCK_CSS_PLLA_CLK
PMC_PCK_CSS_UPLL_CLK
PMC_PCK_CSS_MCK

for example like:
pmc_pck_set_source(PMC_PCK_0,PMC_PCK_CSS_MCK);

And my question is: Where is the documentation containing these "lists of usable parameters" ? 

Thanks
Michal

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

gripennn wrote:
It looks like "copied" header file.
It's Doxygen generated from the headers. In theory that makes the entire library "self documenting". If done correctly then there should be enough in all the .h/.c that goes into this doc package to fully describe the use of the code.

The "best bits" in the whole of ASF are those "Quick Start Guides". Usually they go beyond simply describing the functions in turn and show the sequence that the APIs are actually used in.

 

Sadly though this is just one of the many reasons that ASF is a "bit crap". The documentation is atrocious and it can be difficult to see how to use the APIs.

 

The best bet is probably to use Studio and get it to create example ASF projects for the module you want to use and see how the APIs are sequenced in that.

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

clawson wrote:
The best bet is probably to use Studio and get it to create example ASF projects for the module you want to use and see how the APIs are sequenced in that.

+99

 

Top Tips:

  1. How to properly post source code - see: https://www.avrfreaks.net/comment... - also how to properly include images/pictures
  2. "Garbage" characters on a serial terminal are (almost?) invariably due to wrong baud rate - see: https://learn.sparkfun.com/tutorials/serial-communication
  3. Wrong baud rate is usually due to not running at the speed you thought; check by blinking a LED to see if you get the speed you expected
  4. Difference between a crystal, and a crystal oscillatorhttps://www.avrfreaks.net/comment...
  5. When your question is resolved, mark the solution: https://www.avrfreaks.net/comment...
  6. Beginner's "Getting Started" tips: https://www.avrfreaks.net/comment...
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

Thanks. Simple C comments before each function would help much (like in STM32 libraries). Going back to register based approach...

Michal

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

gripennn wrote:
Simple C comments before each function would help much

Err ... that is exactly where Doxygen gets its text from!!

 

Quote:
(like in STM32 libraries)

Yes - exactly like the STM32 libraries - they also just have Doxygen documentation gathered from the source comments!

 

In that respect, they are exactly the same!

Top Tips:

  1. How to properly post source code - see: https://www.avrfreaks.net/comment... - also how to properly include images/pictures
  2. "Garbage" characters on a serial terminal are (almost?) invariably due to wrong baud rate - see: https://learn.sparkfun.com/tutorials/serial-communication
  3. Wrong baud rate is usually due to not running at the speed you thought; check by blinking a LED to see if you get the speed you expected
  4. Difference between a crystal, and a crystal oscillatorhttps://www.avrfreaks.net/comment...
  5. When your question is resolved, mark the solution: https://www.avrfreaks.net/comment...
  6. Beginner's "Getting Started" tips: https://www.avrfreaks.net/comment...
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

gripennn wrote:
i have to find information which macros can serve as input for these functions

It's all hyperlinked

 

EDIT: again, exactly as ST do.

Top Tips:

  1. How to properly post source code - see: https://www.avrfreaks.net/comment... - also how to properly include images/pictures
  2. "Garbage" characters on a serial terminal are (almost?) invariably due to wrong baud rate - see: https://learn.sparkfun.com/tutorials/serial-communication
  3. Wrong baud rate is usually due to not running at the speed you thought; check by blinking a LED to see if you get the speed you expected
  4. Difference between a crystal, and a crystal oscillatorhttps://www.avrfreaks.net/comment...
  5. When your question is resolved, mark the solution: https://www.avrfreaks.net/comment...
  6. Beginner's "Getting Started" tips: https://www.avrfreaks.net/comment...
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

ST libraries looks like this:
 

/**
  * @brief  Configures the External Low Speed oscillator (LSE) drive capability.
  * @param  RCC_LSEDrive: specifies the new state of the LSE drive capability.
  *          This parameter can be one of the following values:
  *            @arg RCC_LSEDrive_Low: LSE oscillator low drive capability.
  *            @arg RCC_LSEDrive_MediumLow: LSE oscillator medium low drive capability.
  *            @arg RCC_LSEDrive_MediumHigh: LSE oscillator medium high drive capability.
  *            @arg RCC_LSEDrive_High: LSE oscillator high drive capability.
  * @retval None
  */
void RCC_LSEDriveConfig(uint32_t RCC_LSEDrive)
{
  /* Check the parameters */
  assert_param(IS_RCC_LSE_DRIVE(RCC_LSEDrive));
  
  /* Clear LSEDRV[1:0] bits */
  RCC->BDCR &= ~(RCC_BDCR_LSEDRV);

  /* Set the LSE Drive */
  RCC->BDCR |= RCC_LSEDrive;
}

In comments you can see list of allowed arguments. But in ASF i cant find anything like this.
How i can get which of these macros should i use in function void pmc_pck_set_source(uint32_t ul_id, uint32_t ul_source) ?
Is it this group:

PMC_MCKR_CSS_SLOW_CLK, PMC_MCKR_CSS_MAIN_CLK, PMC_MCKR_CSS_PLLA_CLK,...
or this group:
PMC_PCK_CSS_SLOW_CLK, PMC_PCK_CSS_MAIN_CLK, PMC_PCK_CSS_PLLA_CLK,...
or this... ?
PMC_PCR_GCLKCSS_SLOW_CLK, PMC_PCR_GCLKCSS_MAIN_CLK, PMC_PCR_GCLKCSS_PLLA_CLK, ...

Yes i can go to definition of function, looks in which registers it writes and then choose. But it is very slow approach an what about first argument ? Only guide is name of argument "ul_id". I have to list thru file and hope that i found something what looks like "correct one". And when i find suspicious macro, how can make sure, that is realy correct one ? 

May be i am overlooking something.
Best regards
Michal Dudka

 

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

I'm also a newcomer to ASF, and share the sentiments expressed here that the documentation is crap. It's quite amazing that Atmel/Microchip lets ASF users be exposed to this. It's like having a tiny bit of help from the documentation, but the bulk of the work is to do detective work drilling down into the source code itself, sometimes an almost bottomless drilling into header files that include headder files, and macros that nest other macros etc.

 

Extremely bad done Atmel. And this is the same company that produced the, IMO, excellent data sheets for the different 8-bit AVR controllers. What went wrong??

 

I too have, after 24 hours of ASF torture, decided to go "bare metal" while learning the basics of the SAM controllers. Maybe, just maybe, after that I might return to ASF. Right now it looks like I won't.

 

As has been pointed out above, the deficiency is not in the technique used to write and generate documentation (DoxyGen), but in the actual text written.

 

A few years back I played around with (then) Luminary Stellaris ARM chips (since then bought up by Texas Instruments). Compared to ASF their documentation of the support libraries where excellent.

As of January 15, 2018, Site fix-up work has begun! Now do your part and report any bugs or deficiencies here

No guarantees, but if we don't report problems they won't get much of  a chance to be fixed! Details/discussions at link given just above.

 

"Some questions have no answers."[C Baird] "There comes a point where the spoon-feeding has to stop and the independent thinking has to start." [C Lawson] "There are always ways to disagree, without being disagreeable."[E Weddington] "Words represent concepts. Use the wrong words, communicate the wrong concept." [J Morin] "Persistence only goes so far if you set yourself up for failure." [Kartman]

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

gripennn wrote:
ST libraries looks like this:

 

Which is no different from ASF:

 

/**
 * \brief Set the source oscillator for the specified programmable clock.
 *
 * \param ul_id Peripheral ID.
 * \param ul_source Source selection value.
 */
void pmc_pck_set_source(uint32_t ul_id, uint32_t ul_source)
{
	PMC->PMC_PCK[ul_id] =
			(PMC->PMC_PCK[ul_id] & ~PMC_PCK_CSS_Msk) | ul_source;
	while ((PMC->PMC_SCER & (PMC_SCER_PCK0 << ul_id))
			&& !(PMC->PMC_SR & (PMC_SR_PCKRDY0 << ul_id)));
}

 

 

EDIT: Personally, I think the ST documentation is also rubbish; I'm not holding it up as a good example - just saying that it's certainly no better than ASF!

 

At least with ASF, as Cliff mentioned, you do get the Quick Start guides.

 

 

The trouble I find with all this doxygen-generated "documentation" is that it just gives a very "close-in" view - there never seems to be any "overview" as to how stuff should be structured, etc.

 

(that may not be the fault of doxygen itself - but is certainly a fault with, I think, every usage I've seen)

 

EDIT 2: typos

Top Tips:

  1. How to properly post source code - see: https://www.avrfreaks.net/comment... - also how to properly include images/pictures
  2. "Garbage" characters on a serial terminal are (almost?) invariably due to wrong baud rate - see: https://learn.sparkfun.com/tutorials/serial-communication
  3. Wrong baud rate is usually due to not running at the speed you thought; check by blinking a LED to see if you get the speed you expected
  4. Difference between a crystal, and a crystal oscillatorhttps://www.avrfreaks.net/comment...
  5. When your question is resolved, mark the solution: https://www.avrfreaks.net/comment...
  6. Beginner's "Getting Started" tips: https://www.avrfreaks.net/comment...
Last Edited: Thu. Jun 29, 2017 - 12:47 PM
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 1

awneil wrote:
The trouble I find with all this doxygen-generated "documentation" is that it just gives a very "close-in" view - there never seems to be any "overview"
In our work all source is heavily commented with Doxygen for the "nuts and bolts" but for every module we also have separate doc\modname.md in MarkDown that also feeds into the Doxygen process and produces "system diagrams" and more verbose documentation about where the "black box" fits into the overall picture.

 

Apart from the "Quick Start Guides" Atmel ASF seems to lack such a concept. Perhaps it IS the case that they are relying on you using the same ASF projects you can get generated in Studio to aid the understanding.

 

I've spent most of the 30 years of my professional career moaning at people about the lack of documentation - it seems that software engineering and document authoring are not skills shared by most engineers :-(

 

(OTOH most people moan about me about TL;DR !)