Thread: [Doxygen-users] Assembly Language
Brought to you by:
dimitri
From: Relson, D. <dav...@as...> - 2007-06-04 15:53:50
|
I've got an embedded project that's mostly C but has a few assembly language files. Using "/** ... */" delimiters the C functions are easily documented. However doxygen is not too happy with the assembly code. =20 I've got a workaround (described below) and am wondering if others have better solutions ??? Regards, David My process involves creating a C skeleton from the assembly code in several steps, i.e. 1) converting all the assembly code to comments (by adding a "//" prefix to each line) 2) converting all the call opcodes to function calls (of no args) 3) converting all the labels referenced in step 2 to function declarations 4) run doxygen on the resulting code Here's a small example: ### test.asm (original assembly file) ### init: ... some assembly code call main main: ... some assembly code call func ... more assembly code return func: return ### test.asm.c (converted file) ### /** * * This function performs system initialization. * * @param <none> * * @return <none> */ //init: void init(void) { // ... some assembly code // call main main( );=20 } /** * * This function is the main program. * * @param <none> * * @return <none> */ //main: void main(void) { // ... some assembly code // call func func( );=20 // ... more assembly code // return return;=20 } /** * * This function does the work. * * @param <none> * * @return <none> */ //func: void func(void) { // return return;=20 } |
From: Kevin S. <st...@se...> - 2007-06-04 16:17:48
|
David- For my embedded ASM code, I'm using the @cond/@endcond Doxygen tags to tell Doxygen to ignore the actual assembly code. Something like this: //********************************************************************** /**=20 * @fn bool GetPLLValue(int X, int Y, int Z) *=20 * @brief Get the PLL data value for the specified device. * * This function returns ...blah blah blah *=20 * @param[in] X integer, frequency of system clock in MHz * @param[out] Y ptr to an integer, the resultant PLL count * @param[in,out] Z ptr to an integer, the scale factor * * @retval bOK boolean, TRUE if everything went well *=20 **********************************************************************/ /// @cond DOXYGEN_IGNORE_ASM GetPLLValue: . . . <insert the real assy code here> . . . /// @endcond You don't have to do a bunch of work to the ASM file to make it "look" like a C file for Doxygen. Read up on this in the manual for more details. -Kevin Stone |
From: Relson, D. <dav...@as...> - 2007-06-04 18:52:31
|
Hi Kevin, Thanks for the suggestion! Making the ASM code "look" like C lets Doxygen generate call graphs, which is highly useful for learning the structure of new code. However, since the current task is a documentation task and the graphs aren't needed, I can skip the "look like" steps. However, following your example of a function header and @cond/@endcond tags produces Doxygen output where my test file's source code page is fine, but the document page lacks the function info or other useful stuff and just says "Go to the source code of this file." Any further thoughts? Regards, David -----Original Message----- From: Kevin Stone [mailto:st...@se...]=20 Sent: Monday, June 04, 2007 12:18 PM To: Relson, David; Dox...@li... Subject: RE: [Doxygen-users] Assembly Language David- For my embedded ASM code, I'm using the @cond/@endcond Doxygen tags to tell Doxygen to ignore the actual assembly code. Something like this: //********************************************************************** /**=20 * @fn bool GetPLLValue(int X, int Y, int Z) *=20 * @brief Get the PLL data value for the specified device. * * This function returns ...blah blah blah *=20 * @param[in] X integer, frequency of system clock in MHz * @param[out] Y ptr to an integer, the resultant PLL count * @param[in,out] Z ptr to an integer, the scale factor * * @retval bOK boolean, TRUE if everything went well *=20 **********************************************************************/ /// @cond DOXYGEN_IGNORE_ASM GetPLLValue: . . . <insert the real assy code here> . . . /// @endcond You don't have to do a bunch of work to the ASM file to make it "look" like a C file for Doxygen. Read up on this in the manual for more details. -Kevin Stone |
From: Kevin S. <st...@se...> - 2007-06-04 19:41:00
|
Hi, David- The @fn and @brief tags that are in our headers end up creating the call graph and other useful function details that you're looking for. I just re-ran my stuff and found that it shows up in the XXXX.h File Reference section. There is a list of the functions (and their brief descriptions) in each asm file, and then a block of "Functional Documentation" for each function, with the description, in/out params, return values, notes, etc, and the caller graph. All of this is right after the "Go to the source code of this file" link. -Kevin -----Original Message----- From: Relson, David [mailto:dav...@as...]=20 Sent: Monday, June 04, 2007 1:49 PM To: Kevin Stone; Dox...@li... Subject: RE: [Doxygen-users] Assembly Language Hi Kevin, Thanks for the suggestion! Making the ASM code "look" like C lets Doxygen generate call graphs, which is highly useful for learning the structure of new code. However, since the current task is a documentation task and the graphs aren't needed, I can skip the "look like" steps. However, following your example of a function header and @cond/@endcond tags produces Doxygen output where my test file's source code page is fine, but the document page lacks the function info or other useful stuff and just says "Go to the source code of this file." Any further thoughts? Regards, David -----Original Message----- From: Kevin Stone [mailto:st...@se...] Sent: Monday, June 04, 2007 12:18 PM To: Relson, David; Dox...@li... Subject: RE: [Doxygen-users] Assembly Language David- For my embedded ASM code, I'm using the @cond/@endcond Doxygen tags to tell Doxygen to ignore the actual assembly code. Something like this: //********************************************************************** /** * @fn bool GetPLLValue(int X, int Y, int Z) * * @brief Get the PLL data value for the specified device. * * This function returns ...blah blah blah *=20 * @param[in] X integer, frequency of system clock in MHz * @param[out] Y ptr to an integer, the resultant PLL count * @param[in,out] Z ptr to an integer, the scale factor * * @retval bOK boolean, TRUE if everything went well * **********************************************************************/ /// @cond DOXYGEN_IGNORE_ASM GetPLLValue: . . . <insert the real assy code here> . . . /// @endcond You don't have to do a bunch of work to the ASM file to make it "look" like a C file for Doxygen. Read up on this in the manual for more details. -Kevin Stone |
From: Relson, D. <dav...@as...> - 2007-06-04 21:25:45
|
Hi Kevin, I was hoping to include doxygen tags in the asm file itself, but that no longer seems feasible. It seems that doxygen needs a C function definition/prototype before it will put the function info in the generated html documentation. As the assembler will choke on a C function declaration, this won't work. The alternate solution is an include.h file. This has the drawback of code in one file and documentation in a different file. The benefit is that this allows all the functions to be included in the doxygen output. As the benefit outweighs the drawback, so shall it be. Thanks for the tips leading to a workable solution. Regards, David -----Original Message----- From: Kevin Stone [mailto:st...@se...]=20 Sent: Monday, June 04, 2007 3:41 PM To: Relson, David; Dox...@li... Subject: RE: [Doxygen-users] Assembly Language Hi, David- The @fn and @brief tags that are in our headers end up creating the call graph and other useful function details that you're looking for. I just re-ran my stuff and found that it shows up in the XXXX.h File Reference section. There is a list of the functions (and their brief descriptions) in each asm file, and then a block of "Functional Documentation" for each function, with the description, in/out params, return values, notes, etc, and the caller graph. All of this is right after the "Go to the source code of this file" link. -Kevin |
From: Kevin S. <st...@se...> - 2007-06-04 21:36:26
|
David- Our code has a C-style .H file for each .asm file, too. Something like this: #ifndef _FUNC_TEST_H #define _FUNC_TEST_H /*********************************************************************** ** * * Module Name: FUNCTIONAL.H * * Author: <author's name> * * Version history: * * $Log: FUNCTIONAL.H $ * Revision 1.2 2005/09/28 16:00:06 EngLab-1 * Revision 1.1 2005/05/05 19:05:11 kstone * Initial revision * =20 ************************************************************************ */ extern "C" unsigned int functional_test(void); #endif=20 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D The ASM file does NOT include this file at all - it's there to be included by the various C files that need access to the functions that XXX.H provides. Note that there aren't any Doxygen tags in this file either. We put all of that over in the XXX.ASM file for the same reasons you mentioned - to keep the code and documentation close together. -----Original Message----- From: dox...@li... [mailto:dox...@li...] On Behalf Of Relson, David Sent: Monday, June 04, 2007 4:22 PM To: Dox...@li... Subject: Re: [Doxygen-users] Assembly Language Hi Kevin, I was hoping to include doxygen tags in the asm file itself, but that no longer seems feasible. It seems that doxygen needs a C function definition/prototype before it will put the function info in the generated html documentation. As the assembler will choke on a C function declaration, this won't work. The alternate solution is an include.h file. This has the drawback of code in one file and documentation in a different file. The benefit is that this allows all the functions to be included in the doxygen output. As the benefit outweighs the drawback, so shall it be. Thanks for the tips leading to a workable solution. Regards, David -----Original Message----- From: Kevin Stone [mailto:st...@se...] Sent: Monday, June 04, 2007 3:41 PM To: Relson, David; Dox...@li... Subject: RE: [Doxygen-users] Assembly Language Hi, David- The @fn and @brief tags that are in our headers end up creating the call graph and other useful function details that you're looking for. I just re-ran my stuff and found that it shows up in the XXXX.h File Reference section. There is a list of the functions (and their brief descriptions) in each asm file, and then a block of "Functional Documentation" for each function, with the description, in/out params, return values, notes, etc, and the caller graph. All of this is right after the "Go to the source code of this file" link. -Kevin ------------------------------------------------------------------------ - This SF.net email is sponsored by DB2 Express Download DB2 Express C - the FREE version of DB2 express and take control of your XML. No limits. Just data. Click to get it now. http://sourceforge.net/powerbar/db2/ _______________________________________________ Doxygen-users mailing list Dox...@li... https://lists.sourceforge.net/lists/listinfo/doxygen-users |
From: Relson, D. <dav...@as...> - 2007-06-05 12:21:50
|
For this embedded project, the startup code is (naturally) in assembler. Based on external inputs, the startup code activates one memory bank or t'other. In the first case, an assembly program is run and in the second case a C program is run. As the assembly and C programs are totally independent of one another, there's no inherent head for a header file for the assembly code. However adding one to provide a home for the needed documentation is a reasonable compromise. -----Original Message----- From: Kevin Stone [mailto:st...@se...]=20 Sent: Monday, June 04, 2007 5:36 PM To: Relson, David; Dox...@li... Subject: RE: [Doxygen-users] Assembly Language David- Our code has a C-style .H file for each .asm file, too. Something like this: #ifndef _FUNC_TEST_H #define _FUNC_TEST_H /*********************************************************************** ** * * Module Name: FUNCTIONAL.H * * Author: <author's name> * * Version history: * * $Log: FUNCTIONAL.H $ * Revision 1.2 2005/09/28 16:00:06 EngLab-1 * Revision 1.1 2005/05/05 19:05:11 kstone * Initial revision * =20 ************************************************************************ */ extern "C" unsigned int functional_test(void); #endif=20 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D The ASM file does NOT include this file at all - it's there to be included by the various C files that need access to the functions that XXX.H provides. Note that there aren't any Doxygen tags in this file either. We put all of that over in the XXX.ASM file for the same reasons you mentioned - to keep the code and documentation close together. -----Original Message----- From: dox...@li... [mailto:dox...@li...] On Behalf Of Relson, David Sent: Monday, June 04, 2007 4:22 PM To: Dox...@li... Subject: Re: [Doxygen-users] Assembly Language Hi Kevin, I was hoping to include doxygen tags in the asm file itself, but that no longer seems feasible. It seems that doxygen needs a C function definition/prototype before it will put the function info in the generated html documentation. As the assembler will choke on a C function declaration, this won't work. The alternate solution is an include.h file. This has the drawback of code in one file and documentation in a different file. The benefit is that this allows all the functions to be included in the doxygen output. As the benefit outweighs the drawback, so shall it be. Thanks for the tips leading to a workable solution. Regards, David -----Original Message----- From: Kevin Stone [mailto:st...@se...] Sent: Monday, June 04, 2007 3:41 PM To: Relson, David; Dox...@li... Subject: RE: [Doxygen-users] Assembly Language Hi, David- The @fn and @brief tags that are in our headers end up creating the call graph and other useful function details that you're looking for. I just re-ran my stuff and found that it shows up in the XXXX.h File Reference section. There is a list of the functions (and their brief descriptions) in each asm file, and then a block of "Functional Documentation" for each function, with the description, in/out params, return values, notes, etc, and the caller graph. All of this is right after the "Go to the source code of this file" link. -Kevin ------------------------------------------------------------------------ - This SF.net email is sponsored by DB2 Express Download DB2 Express C - the FREE version of DB2 express and take control of your XML. No limits. Just data. Click to get it now. http://sourceforge.net/powerbar/db2/ _______________________________________________ Doxygen-users mailing list Dox...@li... https://lists.sourceforge.net/lists/listinfo/doxygen-users |
From: Barrie D. <bar...@gm...> - 2007-06-05 09:16:18
|
I have done it once before by documenting the asm functions in a c header file. e.g. hwstuff.asm - contains normal asm with no doxygen hwstuff.h - contains all the asm function prototypes in above file commented in doxygen. I also did this as i already used a header file to export the asm symbols into the rest of my c code. The only problem with this is that if lots of code depends on the header then when u update the comments then most of the project will need to be recompiled. Regards Barrie. Relson, David wrote: >I've got an embedded project that's mostly C but has a few assembly >language files. Using "/** ... */" delimiters the C functions are >easily documented. However doxygen is not too happy with the assembly >code. > >I've got a workaround (described below) and am wondering if others have >better solutions ??? > >Regards, > >David > >My process involves creating a C skeleton from the assembly code in >several steps, i.e. > 1) converting all the assembly code to comments (by adding a "//" >prefix to each line) > 2) converting all the call opcodes to function calls (of no args) > 3) converting all the labels referenced in step 2 to function >declarations > 4) run doxygen on the resulting code > >Here's a small example: > >### test.asm (original assembly file) ### >init: > ... some assembly code > call main > >main: > ... some assembly code > call func > ... more assembly code > return > >func: > return > > >### test.asm.c (converted file) ### > >/** >* >* This function performs system initialization. >* >* @param <none> >* >* @return <none> >*/ >//init: >void init(void) >{ >// ... some assembly code >// call main > main( ); >} > >/** >* >* This function is the main program. >* >* @param <none> >* >* @return <none> >*/ >//main: >void main(void) >{ >// ... some assembly code >// call func > func( ); >// ... more assembly code >// return > return; >} > >/** >* >* This function does the work. >* >* @param <none> >* >* @return <none> >*/ >//func: >void func(void) >{ >// return > return; >} > >------------------------------------------------------------------------- >This SF.net email is sponsored by DB2 Express >Download DB2 Express C - the FREE version of DB2 express and take >control of your XML. No limits. Just data. Click to get it now. >http://sourceforge.net/powerbar/db2/ >_______________________________________________ >Doxygen-users mailing list >Dox...@li... >https://lists.sourceforge.net/lists/listinfo/doxygen-users > > > |