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
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!
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...
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
It looks like "copied" header file.
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.
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
Thanks. Simple C comments before each function would help much (like in STM32 libraries). Going back to register based approach...
Michal
Simple C comments before each function would help much
Err ... that is exactly where Doxygen gets its text from!!
(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!
i have to find information which macros can serve as input for these functions
It's all hyperlinked
EDIT: again, exactly as ST do.
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
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.
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
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"
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 !)