From joel.sherrill at oarcorp.com Tue Jan 1 16:56:50 2008 From: joel.sherrill at oarcorp.com (Joel Sherrill) Date: Tue, 01 Jan 2008 10:56:50 -0600 Subject: Happy New Year ! Message-ID: <477A70D2.10006@oarcorp.com> Hi, Last year was an interesting and busy one in the RTEMS world. I hope this year continues to be as fun for RTEMS. Remember that a lot of this activity was due to you sponsoring development through support contracts, RTEMS Application Assistance, training, and other consulting arrangements. Thanks again. --joel PS: This also puts a first message in the archives for 2008 so I can check that that works. :) From joel.sherrill at oarcorp.com Fri Jan 4 17:05:24 2008 From: joel.sherrill at oarcorp.com (Joel Sherrill) Date: Fri, 04 Jan 2008 11:05:24 -0600 Subject: January RTEMS Class in Huntsville Message-ID: <477E6754.4040408@oarcorp.com> There will be an RTEMS Open Class Jan 15-18 in Huntsville. Time is running out to get your registration in. A flyer including the registration form is at http://www.rtems.com/RTEMSClassFlyerJanuary2008.pdf Please contact Valerie Holguin (valerie DOT holguin AT oarcorp DOT com) to register or for more information. Remember that there is also a class scheduled for March in Munich. Thomas Doerfler is the contact for that. If you are interested in a session on Monday focused on the installation and setup of the RTEMS Development Environment, please let myself or Valerie know. Thanks. --joel From joel.sherrill at OARcorp.com Tue Jan 29 23:16:58 2008 From: joel.sherrill at OARcorp.com (Joel Sherrill) Date: Tue, 29 Jan 2008 17:16:58 -0600 Subject: API Additions on CVS Head Message-ID: <479FB3EA.7060907@oarcorp.com> Hi, I have committed a fairly large addition to the CVS head. It adds a number of new object id/name helper services and formally offers a number of routines which have existed but never been documented before. Here is the summary from the Wiki: * Added rtems_build_name() - build object name from characters * Added rtems_object_get_classic_name() - lookup name from id * Added rtems_object_get_name() - obtain object name as string * Added rtems_object_set_name() - set object name * rtems_object_id_api_minimum() - obtain minimum API value * rtems_object_id_api_maximum() - obtain maximum API value * rtems_object_id_api_minimum_class() - obtain minimum class value * rtems_object_id_api_maximum_class() - obtain maximum class value * rtems_object_get_api_name() - obtain API name * rtems_object_get_api_class_name() - obtain class name * rtems_object_get_class_information() - obtain class information * Renamed rtems_get_node() to rtems_object_id_get_node() * Renamed rtems_get_api() to rtems_object_id_get_api() * Renamed rtems_get_class() to rtems_object_id_get_class() * Renamed rtems_get_index() to rtems_object_id_get_index() --joel From joel.sherrill at OARcorp.com Tue Jan 29 23:21:53 2008 From: joel.sherrill at OARcorp.com (Joel Sherrill) Date: Tue, 29 Jan 2008 17:21:53 -0600 Subject: RTEMS SuperCore Doxygen Message-ID: <479FB511.2050209@oarcorp.com> Hi, Over the past couple of years, I have slowly worked on an unpaid pet project of mine -- converting the comments in the core .h files in RTEMS to Doxygen. I have completed enough of the SuperCore to the point where I think it is good enough to debut. YEAH!! It is automatically rebuilt every 6 hours and is online at http://www.rtems.org/doxygen/score/html/index.html I encourage the community to help this improve by editing .h files or financially contributing to further improvements. I really would like to see the Classic API, POSIX API, and SAPI .h files documented this way. That leaves a lot to do. --joel From joel.sherrill at OARcorp.com Wed Jan 30 15:12:59 2008 From: joel.sherrill at OARcorp.com (Joel Sherrill) Date: Wed, 30 Jan 2008 09:12:59 -0600 Subject: RTEMS SuperCore Doxygen In-Reply-To: <47A090D8.8090405@alum.mit.edu> References: <479FB511.2050209@oarcorp.com> <47A090D8.8090405@alum.mit.edu> Message-ID: <47A093FB.3030803@oarcorp.com> Robert S. Grimes wrote: > Joel Sherrill wrote: > >> Hi, >> >> Over the past couple of years, I have slowly worked >> on an unpaid pet project of mine -- converting the >> comments in the core .h files in RTEMS to Doxygen. >> >> > This is great! As a relatively new RTEMS application developer, I am > often grep'ing through header files for the real types of arguments when > the "RTEMS Applications C User's Guide" (CUG) is out-of-date. There are > a lot of these issues. A fine example of how documentation lags the > code when the two are done separately! > The documentation set for the CVS head is also updated automatically every 6 hours now and is at: http://www.rtems.org/onlinedocs/doc-current/share/rtems/html/ >> I have completed enough of the SuperCore to the >> point where I think it is good enough to debut. YEAH!! >> >> It is automatically rebuilt every 6 hours and is online at >> >> > Auto-rebuild - that's great! > If it doesn't destroy the output like it did last night when it ran the first time automatically. :-D >> http://www.rtems.org/doxygen/score/html/index.html >> >> I encourage the community to help this improve by >> editing .h files or financially contributing to >> further improvements. I really would like to see >> the Classic API, POSIX API, and SAPI .h files >> documented this way. That leaves a lot to do. >> >> > I would suggest you set up auto-rebuilding for these, as it would > encourage people to contribute, IMHO. I know that when I use Doxygen, I > document my code much better when I see the results of my efforts - I > suppose that's the "instant gratification" plague in action, I'm\ > afraid! Still, the more we can encourage others to contribute... > > The other directories I mentioned have NOT been converted to Doxygen. A few files that have been modified recently have been converted and some may have a routine here or there commented in Doxygen format -- but that's about it. Believe it or not, most of the information in the score header files was already present. It just needed to be in Doxygen format. > There are two issues that come to mind. > > 1. Potential Code Breakage > First, one potential problem with documenting in the source code is > inadvertent changes to the actual code when only documentation was the > intent. For example, as a mere user, I would be happy to help by > documenting things that I have just looked up during my work, and > spending a bit of time to contribute the appropriate comments; however, > I might be hesitant to do so because I could inadvertently break > something, and I'm not sure I'm up to validating this hasn't occurred. > If you submit a patch to Doxygen comments, part of validating them will be for me (or whomever merges it) to run Doxygen. If you break something, we will have to fix it or punt it back with comments. Under Fedora, Doxygen is easy to install since it is a regaulr RPM. So Linux users shouldn't have trouble testing any changes. > As it is, I can't actually check anything in anyway, which is probably a > Good Thing :-P ! Do you envision an alternate means for contributing > Doxygen comments? > No. Since they are in the code, I still think it has to be a CVS diff against the head. > 2. Descriptive Text > Ultimately, it would be great to include the narrative descriptions of > various facilities, such as the text in the aforementioned CUG. I would > suggest those materials be put in files other than the real header > files, to keep the latter to reasonable sizes. From my experience, > striving to keep the details out of the narrative helps to keep the > latter current. The hyperlinking Doxygen generates allows the > (relatively static) higher-level docs to link to (relatively dynamic) > details, which is tremendously useful for users and maintainers alike! > > Seems I have two major points: > > 1. This is a great idea, at least as great as the Wiki, and certainly > has huge potential to really increasing the usability (and subsequent > viability) of RTEMS! > > Thanks. It was a long time getting to the point it could be done this way. I have considered having "Joel's RTEMS Blog" -- would if be of interest? > 2. Think really hard about how to include the wider community in > this! Should changes be proposed somewhere (perhaps the mailing list, > or the Wiki) by anyone, and when appropriately reviewed, submitted by > Joel or someone? > > I had thought about posting a Wiki page with a list of files that are to be converted to Doxygen and let people sign up for some. File count for .h and .inl. cpukit/rtems - 52 cpukit/sapi - 9 cpukit/posix - 34 Since most have the raw information and just need to be formatted per Doxygen, it is more tedious than hard. I can post a "work sign up sheet" if people are willing to pitch in. This does NOT require great detailed knowledge. > Great job, as usual! > Thanks. --joel > -Bob > >> --joel >> >> _______________________________________________ >> rtems-users mailing list >> rtems-users at rtems.com >> http://rtems.rtems.org/mailman/listinfo/rtems-users >> >> >> From joel.sherrill at oarcorp.com Tue Jan 1 16:56:50 2008 From: joel.sherrill at oarcorp.com (Joel Sherrill) Date: Tue, 01 Jan 2008 10:56:50 -0600 Subject: Happy New Year ! Message-ID: <477A70D2.10006@oarcorp.com> Hi, Last year was an interesting and busy one in the RTEMS world. I hope this year continues to be as fun for RTEMS. Remember that a lot of this activity was due to you sponsoring development through support contracts, RTEMS Application Assistance, training, and other consulting arrangements. Thanks again. --joel PS: This also puts a first message in the archives for 2008 so I can check that that works. :) From joel.sherrill at oarcorp.com Fri Jan 4 17:05:24 2008 From: joel.sherrill at oarcorp.com (Joel Sherrill) Date: Fri, 04 Jan 2008 11:05:24 -0600 Subject: January RTEMS Class in Huntsville Message-ID: <477E6754.4040408@oarcorp.com> There will be an RTEMS Open Class Jan 15-18 in Huntsville. Time is running out to get your registration in. A flyer including the registration form is at http://www.rtems.com/RTEMSClassFlyerJanuary2008.pdf Please contact Valerie Holguin (valerie DOT holguin AT oarcorp DOT com) to register or for more information. Remember that there is also a class scheduled for March in Munich. Thomas Doerfler is the contact for that. If you are interested in a session on Monday focused on the installation and setup of the RTEMS Development Environment, please let myself or Valerie know. Thanks. --joel From joel.sherrill at OARcorp.com Tue Jan 29 23:16:58 2008 From: joel.sherrill at OARcorp.com (Joel Sherrill) Date: Tue, 29 Jan 2008 17:16:58 -0600 Subject: API Additions on CVS Head Message-ID: <479FB3EA.7060907@oarcorp.com> Hi, I have committed a fairly large addition to the CVS head. It adds a number of new object id/name helper services and formally offers a number of routines which have existed but never been documented before. Here is the summary from the Wiki: * Added rtems_build_name() - build object name from characters * Added rtems_object_get_classic_name() - lookup name from id * Added rtems_object_get_name() - obtain object name as string * Added rtems_object_set_name() - set object name * rtems_object_id_api_minimum() - obtain minimum API value * rtems_object_id_api_maximum() - obtain maximum API value * rtems_object_id_api_minimum_class() - obtain minimum class value * rtems_object_id_api_maximum_class() - obtain maximum class value * rtems_object_get_api_name() - obtain API name * rtems_object_get_api_class_name() - obtain class name * rtems_object_get_class_information() - obtain class information * Renamed rtems_get_node() to rtems_object_id_get_node() * Renamed rtems_get_api() to rtems_object_id_get_api() * Renamed rtems_get_class() to rtems_object_id_get_class() * Renamed rtems_get_index() to rtems_object_id_get_index() --joel From joel.sherrill at OARcorp.com Tue Jan 29 23:21:53 2008 From: joel.sherrill at OARcorp.com (Joel Sherrill) Date: Tue, 29 Jan 2008 17:21:53 -0600 Subject: RTEMS SuperCore Doxygen Message-ID: <479FB511.2050209@oarcorp.com> Hi, Over the past couple of years, I have slowly worked on an unpaid pet project of mine -- converting the comments in the core .h files in RTEMS to Doxygen. I have completed enough of the SuperCore to the point where I think it is good enough to debut. YEAH!! It is automatically rebuilt every 6 hours and is online at http://www.rtems.org/doxygen/score/html/index.html I encourage the community to help this improve by editing .h files or financially contributing to further improvements. I really would like to see the Classic API, POSIX API, and SAPI .h files documented this way. That leaves a lot to do. --joel From joel.sherrill at OARcorp.com Wed Jan 30 15:12:59 2008 From: joel.sherrill at OARcorp.com (Joel Sherrill) Date: Wed, 30 Jan 2008 09:12:59 -0600 Subject: RTEMS SuperCore Doxygen In-Reply-To: <47A090D8.8090405@alum.mit.edu> References: <479FB511.2050209@oarcorp.com> <47A090D8.8090405@alum.mit.edu> Message-ID: <47A093FB.3030803@oarcorp.com> Robert S. Grimes wrote: > Joel Sherrill wrote: > >> Hi, >> >> Over the past couple of years, I have slowly worked >> on an unpaid pet project of mine -- converting the >> comments in the core .h files in RTEMS to Doxygen. >> >> > This is great! As a relatively new RTEMS application developer, I am > often grep'ing through header files for the real types of arguments when > the "RTEMS Applications C User's Guide" (CUG) is out-of-date. There are > a lot of these issues. A fine example of how documentation lags the > code when the two are done separately! > The documentation set for the CVS head is also updated automatically every 6 hours now and is at: http://www.rtems.org/onlinedocs/doc-current/share/rtems/html/ >> I have completed enough of the SuperCore to the >> point where I think it is good enough to debut. YEAH!! >> >> It is automatically rebuilt every 6 hours and is online at >> >> > Auto-rebuild - that's great! > If it doesn't destroy the output like it did last night when it ran the first time automatically. :-D >> http://www.rtems.org/doxygen/score/html/index.html >> >> I encourage the community to help this improve by >> editing .h files or financially contributing to >> further improvements. I really would like to see >> the Classic API, POSIX API, and SAPI .h files >> documented this way. That leaves a lot to do. >> >> > I would suggest you set up auto-rebuilding for these, as it would > encourage people to contribute, IMHO. I know that when I use Doxygen, I > document my code much better when I see the results of my efforts - I > suppose that's the "instant gratification" plague in action, I'm\ > afraid! Still, the more we can encourage others to contribute... > > The other directories I mentioned have NOT been converted to Doxygen. A few files that have been modified recently have been converted and some may have a routine here or there commented in Doxygen format -- but that's about it. Believe it or not, most of the information in the score header files was already present. It just needed to be in Doxygen format. > There are two issues that come to mind. > > 1. Potential Code Breakage > First, one potential problem with documenting in the source code is > inadvertent changes to the actual code when only documentation was the > intent. For example, as a mere user, I would be happy to help by > documenting things that I have just looked up during my work, and > spending a bit of time to contribute the appropriate comments; however, > I might be hesitant to do so because I could inadvertently break > something, and I'm not sure I'm up to validating this hasn't occurred. > If you submit a patch to Doxygen comments, part of validating them will be for me (or whomever merges it) to run Doxygen. If you break something, we will have to fix it or punt it back with comments. Under Fedora, Doxygen is easy to install since it is a regaulr RPM. So Linux users shouldn't have trouble testing any changes. > As it is, I can't actually check anything in anyway, which is probably a > Good Thing :-P ! Do you envision an alternate means for contributing > Doxygen comments? > No. Since they are in the code, I still think it has to be a CVS diff against the head. > 2. Descriptive Text > Ultimately, it would be great to include the narrative descriptions of > various facilities, such as the text in the aforementioned CUG. I would > suggest those materials be put in files other than the real header > files, to keep the latter to reasonable sizes. From my experience, > striving to keep the details out of the narrative helps to keep the > latter current. The hyperlinking Doxygen generates allows the > (relatively static) higher-level docs to link to (relatively dynamic) > details, which is tremendously useful for users and maintainers alike! > > Seems I have two major points: > > 1. This is a great idea, at least as great as the Wiki, and certainly > has huge potential to really increasing the usability (and subsequent > viability) of RTEMS! > > Thanks. It was a long time getting to the point it could be done this way. I have considered having "Joel's RTEMS Blog" -- would if be of interest? > 2. Think really hard about how to include the wider community in > this! Should changes be proposed somewhere (perhaps the mailing list, > or the Wiki) by anyone, and when appropriately reviewed, submitted by > Joel or someone? > > I had thought about posting a Wiki page with a list of files that are to be converted to Doxygen and let people sign up for some. File count for .h and .inl. cpukit/rtems - 52 cpukit/sapi - 9 cpukit/posix - 34 Since most have the raw information and just need to be formatted per Doxygen, it is more tedious than hard. I can post a "work sign up sheet" if people are willing to pitch in. This does NOT require great detailed knowledge. > Great job, as usual! > Thanks. --joel > -Bob > >> --joel >> >> _______________________________________________ >> rtems-users mailing list >> rtems-users at rtems.com >> http://rtems.rtems.org/mailman/listinfo/rtems-users >> >> >> From joel.sherrill at oarcorp.com Tue Jan 1 16:56:50 2008 From: joel.sherrill at oarcorp.com (Joel Sherrill) Date: Tue, 01 Jan 2008 10:56:50 -0600 Subject: Happy New Year ! Message-ID: <477A70D2.10006@oarcorp.com> Hi, Last year was an interesting and busy one in the RTEMS world. I hope this year continues to be as fun for RTEMS. Remember that a lot of this activity was due to you sponsoring development through support contracts, RTEMS Application Assistance, training, and other consulting arrangements. Thanks again. --joel PS: This also puts a first message in the archives for 2008 so I can check that that works. :) From joel.sherrill at oarcorp.com Fri Jan 4 17:05:24 2008 From: joel.sherrill at oarcorp.com (Joel Sherrill) Date: Fri, 04 Jan 2008 11:05:24 -0600 Subject: January RTEMS Class in Huntsville Message-ID: <477E6754.4040408@oarcorp.com> There will be an RTEMS Open Class Jan 15-18 in Huntsville. Time is running out to get your registration in. A flyer including the registration form is at http://www.rtems.com/RTEMSClassFlyerJanuary2008.pdf Please contact Valerie Holguin (valerie DOT holguin AT oarcorp DOT com) to register or for more information. Remember that there is also a class scheduled for March in Munich. Thomas Doerfler is the contact for that. If you are interested in a session on Monday focused on the installation and setup of the RTEMS Development Environment, please let myself or Valerie know. Thanks. --joel From joel.sherrill at OARcorp.com Tue Jan 29 23:16:58 2008 From: joel.sherrill at OARcorp.com (Joel Sherrill) Date: Tue, 29 Jan 2008 17:16:58 -0600 Subject: API Additions on CVS Head Message-ID: <479FB3EA.7060907@oarcorp.com> Hi, I have committed a fairly large addition to the CVS head. It adds a number of new object id/name helper services and formally offers a number of routines which have existed but never been documented before. Here is the summary from the Wiki: * Added rtems_build_name() - build object name from characters * Added rtems_object_get_classic_name() - lookup name from id * Added rtems_object_get_name() - obtain object name as string * Added rtems_object_set_name() - set object name * rtems_object_id_api_minimum() - obtain minimum API value * rtems_object_id_api_maximum() - obtain maximum API value * rtems_object_id_api_minimum_class() - obtain minimum class value * rtems_object_id_api_maximum_class() - obtain maximum class value * rtems_object_get_api_name() - obtain API name * rtems_object_get_api_class_name() - obtain class name * rtems_object_get_class_information() - obtain class information * Renamed rtems_get_node() to rtems_object_id_get_node() * Renamed rtems_get_api() to rtems_object_id_get_api() * Renamed rtems_get_class() to rtems_object_id_get_class() * Renamed rtems_get_index() to rtems_object_id_get_index() --joel From joel.sherrill at OARcorp.com Tue Jan 29 23:21:53 2008 From: joel.sherrill at OARcorp.com (Joel Sherrill) Date: Tue, 29 Jan 2008 17:21:53 -0600 Subject: RTEMS SuperCore Doxygen Message-ID: <479FB511.2050209@oarcorp.com> Hi, Over the past couple of years, I have slowly worked on an unpaid pet project of mine -- converting the comments in the core .h files in RTEMS to Doxygen. I have completed enough of the SuperCore to the point where I think it is good enough to debut. YEAH!! It is automatically rebuilt every 6 hours and is online at http://www.rtems.org/doxygen/score/html/index.html I encourage the community to help this improve by editing .h files or financially contributing to further improvements. I really would like to see the Classic API, POSIX API, and SAPI .h files documented this way. That leaves a lot to do. --joel From joel.sherrill at OARcorp.com Wed Jan 30 15:12:59 2008 From: joel.sherrill at OARcorp.com (Joel Sherrill) Date: Wed, 30 Jan 2008 09:12:59 -0600 Subject: RTEMS SuperCore Doxygen In-Reply-To: <47A090D8.8090405@alum.mit.edu> References: <479FB511.2050209@oarcorp.com> <47A090D8.8090405@alum.mit.edu> Message-ID: <47A093FB.3030803@oarcorp.com> Robert S. Grimes wrote: > Joel Sherrill wrote: > >> Hi, >> >> Over the past couple of years, I have slowly worked >> on an unpaid pet project of mine -- converting the >> comments in the core .h files in RTEMS to Doxygen. >> >> > This is great! As a relatively new RTEMS application developer, I am > often grep'ing through header files for the real types of arguments when > the "RTEMS Applications C User's Guide" (CUG) is out-of-date. There are > a lot of these issues. A fine example of how documentation lags the > code when the two are done separately! > The documentation set for the CVS head is also updated automatically every 6 hours now and is at: http://www.rtems.org/onlinedocs/doc-current/share/rtems/html/ >> I have completed enough of the SuperCore to the >> point where I think it is good enough to debut. YEAH!! >> >> It is automatically rebuilt every 6 hours and is online at >> >> > Auto-rebuild - that's great! > If it doesn't destroy the output like it did last night when it ran the first time automatically. :-D >> http://www.rtems.org/doxygen/score/html/index.html >> >> I encourage the community to help this improve by >> editing .h files or financially contributing to >> further improvements. I really would like to see >> the Classic API, POSIX API, and SAPI .h files >> documented this way. That leaves a lot to do. >> >> > I would suggest you set up auto-rebuilding for these, as it would > encourage people to contribute, IMHO. I know that when I use Doxygen, I > document my code much better when I see the results of my efforts - I > suppose that's the "instant gratification" plague in action, I'm\ > afraid! Still, the more we can encourage others to contribute... > > The other directories I mentioned have NOT been converted to Doxygen. A few files that have been modified recently have been converted and some may have a routine here or there commented in Doxygen format -- but that's about it. Believe it or not, most of the information in the score header files was already present. It just needed to be in Doxygen format. > There are two issues that come to mind. > > 1. Potential Code Breakage > First, one potential problem with documenting in the source code is > inadvertent changes to the actual code when only documentation was the > intent. For example, as a mere user, I would be happy to help by > documenting things that I have just looked up during my work, and > spending a bit of time to contribute the appropriate comments; however, > I might be hesitant to do so because I could inadvertently break > something, and I'm not sure I'm up to validating this hasn't occurred. > If you submit a patch to Doxygen comments, part of validating them will be for me (or whomever merges it) to run Doxygen. If you break something, we will have to fix it or punt it back with comments. Under Fedora, Doxygen is easy to install since it is a regaulr RPM. So Linux users shouldn't have trouble testing any changes. > As it is, I can't actually check anything in anyway, which is probably a > Good Thing :-P ! Do you envision an alternate means for contributing > Doxygen comments? > No. Since they are in the code, I still think it has to be a CVS diff against the head. > 2. Descriptive Text > Ultimately, it would be great to include the narrative descriptions of > various facilities, such as the text in the aforementioned CUG. I would > suggest those materials be put in files other than the real header > files, to keep the latter to reasonable sizes. From my experience, > striving to keep the details out of the narrative helps to keep the > latter current. The hyperlinking Doxygen generates allows the > (relatively static) higher-level docs to link to (relatively dynamic) > details, which is tremendously useful for users and maintainers alike! > > Seems I have two major points: > > 1. This is a great idea, at least as great as the Wiki, and certainly > has huge potential to really increasing the usability (and subsequent > viability) of RTEMS! > > Thanks. It was a long time getting to the point it could be done this way. I have considered having "Joel's RTEMS Blog" -- would if be of interest? > 2. Think really hard about how to include the wider community in > this! Should changes be proposed somewhere (perhaps the mailing list, > or the Wiki) by anyone, and when appropriately reviewed, submitted by > Joel or someone? > > I had thought about posting a Wiki page with a list of files that are to be converted to Doxygen and let people sign up for some. File count for .h and .inl. cpukit/rtems - 52 cpukit/sapi - 9 cpukit/posix - 34 Since most have the raw information and just need to be formatted per Doxygen, it is more tedious than hard. I can post a "work sign up sheet" if people are willing to pitch in. This does NOT require great detailed knowledge. > Great job, as usual! > Thanks. --joel > -Bob > >> --joel >> >> _______________________________________________ >> rtems-users mailing list >> rtems-users at rtems.com >> http://rtems.rtems.org/mailman/listinfo/rtems-users >> >> >> From joel.sherrill at oarcorp.com Tue Jan 1 16:56:50 2008 From: joel.sherrill at oarcorp.com (Joel Sherrill) Date: Tue, 01 Jan 2008 10:56:50 -0600 Subject: Happy New Year ! Message-ID: <477A70D2.10006@oarcorp.com> Hi, Last year was an interesting and busy one in the RTEMS world. I hope this year continues to be as fun for RTEMS. Remember that a lot of this activity was due to you sponsoring development through support contracts, RTEMS Application Assistance, training, and other consulting arrangements. Thanks again. --joel PS: This also puts a first message in the archives for 2008 so I can check that that works. :) From joel.sherrill at oarcorp.com Fri Jan 4 17:05:24 2008 From: joel.sherrill at oarcorp.com (Joel Sherrill) Date: Fri, 04 Jan 2008 11:05:24 -0600 Subject: January RTEMS Class in Huntsville Message-ID: <477E6754.4040408@oarcorp.com> There will be an RTEMS Open Class Jan 15-18 in Huntsville. Time is running out to get your registration in. A flyer including the registration form is at http://www.rtems.com/RTEMSClassFlyerJanuary2008.pdf Please contact Valerie Holguin (valerie DOT holguin AT oarcorp DOT com) to register or for more information. Remember that there is also a class scheduled for March in Munich. Thomas Doerfler is the contact for that. If you are interested in a session on Monday focused on the installation and setup of the RTEMS Development Environment, please let myself or Valerie know. Thanks. --joel From joel.sherrill at OARcorp.com Tue Jan 29 23:16:58 2008 From: joel.sherrill at OARcorp.com (Joel Sherrill) Date: Tue, 29 Jan 2008 17:16:58 -0600 Subject: API Additions on CVS Head Message-ID: <479FB3EA.7060907@oarcorp.com> Hi, I have committed a fairly large addition to the CVS head. It adds a number of new object id/name helper services and formally offers a number of routines which have existed but never been documented before. Here is the summary from the Wiki: * Added rtems_build_name() - build object name from characters * Added rtems_object_get_classic_name() - lookup name from id * Added rtems_object_get_name() - obtain object name as string * Added rtems_object_set_name() - set object name * rtems_object_id_api_minimum() - obtain minimum API value * rtems_object_id_api_maximum() - obtain maximum API value * rtems_object_id_api_minimum_class() - obtain minimum class value * rtems_object_id_api_maximum_class() - obtain maximum class value * rtems_object_get_api_name() - obtain API name * rtems_object_get_api_class_name() - obtain class name * rtems_object_get_class_information() - obtain class information * Renamed rtems_get_node() to rtems_object_id_get_node() * Renamed rtems_get_api() to rtems_object_id_get_api() * Renamed rtems_get_class() to rtems_object_id_get_class() * Renamed rtems_get_index() to rtems_object_id_get_index() --joel From joel.sherrill at OARcorp.com Tue Jan 29 23:21:53 2008 From: joel.sherrill at OARcorp.com (Joel Sherrill) Date: Tue, 29 Jan 2008 17:21:53 -0600 Subject: RTEMS SuperCore Doxygen Message-ID: <479FB511.2050209@oarcorp.com> Hi, Over the past couple of years, I have slowly worked on an unpaid pet project of mine -- converting the comments in the core .h files in RTEMS to Doxygen. I have completed enough of the SuperCore to the point where I think it is good enough to debut. YEAH!! It is automatically rebuilt every 6 hours and is online at http://www.rtems.org/doxygen/score/html/index.html I encourage the community to help this improve by editing .h files or financially contributing to further improvements. I really would like to see the Classic API, POSIX API, and SAPI .h files documented this way. That leaves a lot to do. --joel From joel.sherrill at OARcorp.com Wed Jan 30 15:12:59 2008 From: joel.sherrill at OARcorp.com (Joel Sherrill) Date: Wed, 30 Jan 2008 09:12:59 -0600 Subject: RTEMS SuperCore Doxygen In-Reply-To: <47A090D8.8090405@alum.mit.edu> References: <479FB511.2050209@oarcorp.com> <47A090D8.8090405@alum.mit.edu> Message-ID: <47A093FB.3030803@oarcorp.com> Robert S. Grimes wrote: > Joel Sherrill wrote: > >> Hi, >> >> Over the past couple of years, I have slowly worked >> on an unpaid pet project of mine -- converting the >> comments in the core .h files in RTEMS to Doxygen. >> >> > This is great! As a relatively new RTEMS application developer, I am > often grep'ing through header files for the real types of arguments when > the "RTEMS Applications C User's Guide" (CUG) is out-of-date. There are > a lot of these issues. A fine example of how documentation lags the > code when the two are done separately! > The documentation set for the CVS head is also updated automatically every 6 hours now and is at: http://www.rtems.org/onlinedocs/doc-current/share/rtems/html/ >> I have completed enough of the SuperCore to the >> point where I think it is good enough to debut. YEAH!! >> >> It is automatically rebuilt every 6 hours and is online at >> >> > Auto-rebuild - that's great! > If it doesn't destroy the output like it did last night when it ran the first time automatically. :-D >> http://www.rtems.org/doxygen/score/html/index.html >> >> I encourage the community to help this improve by >> editing .h files or financially contributing to >> further improvements. I really would like to see >> the Classic API, POSIX API, and SAPI .h files >> documented this way. That leaves a lot to do. >> >> > I would suggest you set up auto-rebuilding for these, as it would > encourage people to contribute, IMHO. I know that when I use Doxygen, I > document my code much better when I see the results of my efforts - I > suppose that's the "instant gratification" plague in action, I'm\ > afraid! Still, the more we can encourage others to contribute... > > The other directories I mentioned have NOT been converted to Doxygen. A few files that have been modified recently have been converted and some may have a routine here or there commented in Doxygen format -- but that's about it. Believe it or not, most of the information in the score header files was already present. It just needed to be in Doxygen format. > There are two issues that come to mind. > > 1. Potential Code Breakage > First, one potential problem with documenting in the source code is > inadvertent changes to the actual code when only documentation was the > intent. For example, as a mere user, I would be happy to help by > documenting things that I have just looked up during my work, and > spending a bit of time to contribute the appropriate comments; however, > I might be hesitant to do so because I could inadvertently break > something, and I'm not sure I'm up to validating this hasn't occurred. > If you submit a patch to Doxygen comments, part of validating them will be for me (or whomever merges it) to run Doxygen. If you break something, we will have to fix it or punt it back with comments. Under Fedora, Doxygen is easy to install since it is a regaulr RPM. So Linux users shouldn't have trouble testing any changes. > As it is, I can't actually check anything in anyway, which is probably a > Good Thing :-P ! Do you envision an alternate means for contributing > Doxygen comments? > No. Since they are in the code, I still think it has to be a CVS diff against the head. > 2. Descriptive Text > Ultimately, it would be great to include the narrative descriptions of > various facilities, such as the text in the aforementioned CUG. I would > suggest those materials be put in files other than the real header > files, to keep the latter to reasonable sizes. From my experience, > striving to keep the details out of the narrative helps to keep the > latter current. The hyperlinking Doxygen generates allows the > (relatively static) higher-level docs to link to (relatively dynamic) > details, which is tremendously useful for users and maintainers alike! > > Seems I have two major points: > > 1. This is a great idea, at least as great as the Wiki, and certainly > has huge potential to really increasing the usability (and subsequent > viability) of RTEMS! > > Thanks. It was a long time getting to the point it could be done this way. I have considered having "Joel's RTEMS Blog" -- would if be of interest? > 2. Think really hard about how to include the wider community in > this! Should changes be proposed somewhere (perhaps the mailing list, > or the Wiki) by anyone, and when appropriately reviewed, submitted by > Joel or someone? > > I had thought about posting a Wiki page with a list of files that are to be converted to Doxygen and let people sign up for some. File count for .h and .inl. cpukit/rtems - 52 cpukit/sapi - 9 cpukit/posix - 34 Since most have the raw information and just need to be formatted per Doxygen, it is more tedious than hard. I can post a "work sign up sheet" if people are willing to pitch in. This does NOT require great detailed knowledge. > Great job, as usual! > Thanks. --joel > -Bob > >> --joel >> >> _______________________________________________ >> rtems-users mailing list >> rtems-users at rtems.com >> http://rtems.rtems.org/mailman/listinfo/rtems-users >> >> >>