Re: [Openocd-development] RFC: struct cleanup and more
On Wed, 2009-06-10 at 21:40 -0400, Duane Ellis wrote: I have developed loadable module support in the past, and it's already on The List here. If I can afford to take the time, OpenOCD will be fully decoupled from its various driver modules. Debugging these things become a *ROYAL* *P*I*T*A* Symbols don't work, etc, (ie: I've been debugging some SANE drivers, ugh, and I've done quite a bit with these). The Linux kernel shows how modules can be done well: static or dynamic. I would settle for no less here. Please - we have bigger, better fish to fry then that feature. It's definitely not until 0.3.0 or later. Cheers, Zach ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
?? on The List here. If I can afford to take the time, OpenOCD will be ?? fully decoupled from its various driver modules. duane Debugging these things become a *ROYAL* *P*I*T*A* duane Symbols don't work, etc, (ie: I've been debugging some SANE drivers, ugh, and I've done quite a duane bit with these). Zach The Linux kernel shows how modules can be done well: static or dynamic. Zach I would settle for no less here. You missed a key point. How the *modules* are done - is well done, no questions asked. How modules are debugged, is another matter entirely. That is my point. -Duane. ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
On Monday 01 June 2009, Rick Altherr wrote: C and C++ are both strongly typed I'm used to definitions of strong typing that preclude the inability to break out of the type system. C makes that trivial: cast to/from void * pointers, and you're done. That's because it was intended from the start to be a low level language, for systems programming, which doesn't hide the machine-specific details that strong typing does. It is however worth pointing out that there are dozens of definitions of what strong typing is ... although this is the first time I've ever heard anyone apply that term to C. (Since I first found a looseleaf binder of line-printer output, called The C Programming Language, in one of the libraries at Case Western. The printed/bound versions weren't very available!) C++ adds a few type frameworks to C, yes, but still doesn't have what I'd call strong typing. (Plus, all its dynamic/reinterpret/static/const cast mechanisms get confusing.) but proper use of an abstract type can greatly simplify the implementation as the efforts to simplify the target APIs has shown. We are already adopting most of the encapsulation paradigm for targets and ADTs build on that. Encapsulation != strong typing (and vice versa!). And I still stand by my observation that I've usually seen *team* approaches to strong typing fail, when they need to be built with weakly typed languages. The dynamics rarely support it as the code base evolves. However, I'm all in favor of evolving code to respect clearly defined data types, which encapsulate roles and responsibilities to support better system structures. If there's a better way to do it, I've not yet come across that answer. :) I think that a well thought out implementation of an abstract target type and interface will do wonders to the code base and maintenance. Using encapsulation will make this even better for future expansion and enhancement. All that's true, but it's still very different from strong typing (using any definition I've worked with). :) ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
On Jun 2, 2009, at 9:42 PM, Michael Bruck wrote: On Wed, Jun 3, 2009 at 6:38 AM, Rick Altherr kc8...@kc8apf.net wrote: I'm speaking in general terms, but, yes, simple accessors can definitely be a problem depending how the program is structured. I've seen many a game engine written in C++ with full encapsulation where a statistical profile shows nearly all of the time in the prolog and epilog. The actual accessor doesn't cost anything (maybe 1-2 instructions), but the setup for the stack frame kills it. A stack frame setup forces accesses to memory so even though the number of instructions is small, the impact on the performance is significant. Having the instructions sit in the icache does help in terms of instruction fetch times, but the data operations involve a read-modify-write pattern which won't sit well in many cache structures. To be entirely fair, this problem with accessors mainly shows up when there are a large number of instances of the object and the accessor is being called as part of a traversal over the instances. The typical solution is to allow direct access to the data member to avoid the stack frame setup/teardown overhead. Wouldn't you have the accessor as inlined member function in C++ (while keeping the data private)? Michael A good C++ compiler will automatically inline such functions at sufficient levels of optimization. Of course, there are limits as to what most compilers will inline and so this can really bite you. I've seen this fairly frequently on a lot of different source bases. Of course, everyone should be following the optimization creed: measure first, then optimize what is taking time. Otherwise you end up doing things like getting rid of all your accessor methods and find out it doesn't make any difference. -- Rick Altherr kc8...@kc8apf.net He said he hadn't had a byte in three days. I had a short, so I split it with him. -- Unsigned smime.p7s Description: S/MIME cryptographic signature ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
I've done a fair bit of profiling of OpenOCD and I'll scream bloody murder if I see something that offends the sensibilities of an ARM7 w/16 bit databus and 10 wait states :-) -- Øyvind Harboe Embedded software and hardware consulting services http://consulting.zylin.com ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
I'm speaking in general terms, but, yes, simple accessors can definitely be a problem depending how the program is structured. I've seen many a game engine written in C++ with full encapsulation where a statistical profile shows nearly all of the time in the prolog and epilog. The actual accessor doesn't cost anything (maybe 1-2 instructions), but the setup for the stack frame kills it. A stack frame setup forces accesses to memory so even though the number of instructions is small, the impact on the performance is significant. Having the instructions sit in the icache does help in terms of instruction fetch times, but the data operations involve a read-modify- write pattern which won't sit well in many cache structures. To be entirely fair, this problem with accessors mainly shows up when there are a large number of instances of the object and the accessor is being called as part of a traversal over the instances. The typical solution is to allow direct access to the data member to avoid the stack frame setup/teardown overhead. -- Rick Altherr kc8...@kc8apf.net He said he hadn't had a byte in three days. I had a short, so I split it with him. -- Unsigned On Jun 2, 2009, at 3:26 AM, Duane Ellis wrote: You don't want to waste a lot of time in simple accessors if they are called frequently enough Really? Sure - a few opcodes ... but in the grand scheme of things... For example the function target_write_memory() - with -O2 is exactly these instructions pushl %ebp movl%esp, %ebp movl8(%ebp), %edx popl%ebp movl(%edx), %ecx movl64(%ecx), %ecx jmp *%ecx (A) 7 instructions, operating at 1ghz. (B) if they are called frequently enough they live in the cache and are faster! (C) And because the code is more common/reused - identical 7 instruction sequences in multiple places do not cause other identical 7 instruction sequences (at another address) to leave the cache The same argument can, to a degree, be made *against* 'static inline' functions in headers. -Duane. smime.p7s Description: S/MIME cryptographic signature ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
On Wed, Jun 3, 2009 at 6:38 AM, Rick Altherr kc8...@kc8apf.net wrote: I'm speaking in general terms, but, yes, simple accessors can definitely be a problem depending how the program is structured. I've seen many a game engine written in C++ with full encapsulation where a statistical profile shows nearly all of the time in the prolog and epilog. The actual accessor doesn't cost anything (maybe 1-2 instructions), but the setup for the stack frame kills it. A stack frame setup forces accesses to memory so even though the number of instructions is small, the impact on the performance is significant. Having the instructions sit in the icache does help in terms of instruction fetch times, but the data operations involve a read-modify-write pattern which won't sit well in many cache structures. To be entirely fair, this problem with accessors mainly shows up when there are a large number of instances of the object and the accessor is being called as part of a traversal over the instances. The typical solution is to allow direct access to the data member to avoid the stack frame setup/teardown overhead. Wouldn't you have the accessor as inlined member function in C++ (while keeping the data private)? Michael ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
I'm all for removing the type redundancy, but I'd rather see the typedef stay and remove the struct name instead. It reduces typing when specifying the type and gets rid of the unnecessary separation of struct type names from other types. Sent from my iPhone On May 31, 2009, at 4:37 PM, Zach Welch z...@superlucidity.net wrote: Hi all, The following things nagged at me when I did the target_type clean-up: 1) Remove redundant structure typedefs: a) Entails the following steps (for each named struct type): i) s/^typedef struct type_s/struct type_s/ ii) s/^} type_t;/};/ iii) s/type_t/struct type_s/ iv) Fix any messes that these commands miss or make. ;) b) Eliminates what are essentially duplicated symbols: - simplifies the Doxygen documentation tremendously. - eliminates style ambiguity and forward referencing. 2) Improve the documentation for the target module files. - would be best to wait until other cleanup is done. 3) More moving and module clean-up: - I target.h needs some re-organization. - I have a jtag.h doc patch in progress. How do these changes look in the community's eyes? These were on the list of things to be considered for 0.2.0, but no one addressed them. I will post patches to clean-up and removal of jtag_tap_t in reply to this thread, to provide better foundation for concrete discussion about issue #1. While I think this would help the code and documentation a lot, I would even go further to suggest s/_s// from all struct names. Cheers, Zach ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
Is splitting jtag.h somewhere on your list? One jtag.h w/public definitions and another with definitions for drivers eyes and jtag.c only -- Øyvind Harboe Embedded software and hardware consulting services http://consulting.zylin.com ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
On Mon, 2009-06-01 at 20:56 +0200, Øyvind Harboe wrote: Is splitting jtag.h somewhere on your list? One jtag.h w/public definitions and another with definitions for drivers eyes and jtag.c only Definitely. I think flash.h deserves similar treatment too. Zach ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
List was dropped. Sent from my iPhone On Jun 1, 2009, at 4:19 PM, David Brownell davi...@pacbell.net wrote: On Monday 01 June 2009, Rick Altherr wrote: On May 31, 2009, at 7:41 PM, David Brownell davi...@pacbell.net wrote: On Sunday 31 May 2009, Michael Bruck wrote: The 'struct foo_s' syntax is code bloat that obscures the actual algorithms. 'foo_t' is shorter. Disagree about obscuring. And shorter doesn't matter here. If I see foo_t I have no idea what kind of thing it is. If I see a struct foo there's no such confusion. Ergo, foo_t has obscured. ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development If encapsulation is the goal, then you don't care about the underlying definition of foo_t unless you are the module that implements foo. It's *a* goal, not *the* only goal. And encapsulation is not a binary thing; it's a spectrum. Plus, remember that the costs of hiding can easily exceed the benefits thereof... Sure. You don't want to waste a lot of time in simple accessors if they are called frequently enough. The main benefit in encapsulation is removing the burden of doing the right thing from the caller. Since we are already moving towards accessor functions instead of direct struct access, we may as well hide the fact that it is one. It opens up our options for growth in the future. A foo_t is simply a foo and as a caller you dont need to know any more This is C, not a language that incorporates a strong notion of abstract data types. Somewhat the opposite; from the very beginning, it's tried to make some things subtly visible. The language doesn't actually do either. It offers features that allow either styles to be used. Either way, with encapsulation, knowing the underlying implementation data type isn't relevant to anyone outside that module. Since we are moving towards accessor methods, we might as well finish the encapsulation and hide the internal data type. In that case declaring it as struct everywhere exposes an implementation choice with no benefit. If foo were to ever change in type (consider a change from a pointer to a struct to an int or vice versa), you'd need to change all of the function protoypes. For encapsulation in C, the API should expose an opaque handle that the module can convert to the internal representation. A typedef that expands to a pointer to a struct hides the implementation choices from the callers and reduces the chances of doing inappropriate things to the handle. Further, the implementation can do the conversion by simply defining the underlying struct. Thus, the public for the module contains a forward struct declaration and the handle typedef while the private just adds the actual struct definition. Again, that presumes you're going after a strong notion of abstract data types. I've certainly worked in languages structured around such notions. Now, as a *designer* I really don't need extra help from C or idioms in order to achieve strong enough typing. In fact one thing I like about C (versus, say, C++ or Java; or assembler) is that it makes it easy to achieve the *right* level of information hiding, which is somewhere between all and none and varies based on the task at hand. As a member of a programming team, I've unfortunately seen more folk abuse strong typing than one who use it well. Very Strong information hiding requires a preternatural level of advance knowledge about what the interface will need to do and how it will evolve -- or a commitment to evolve the relevant interface(s) in ways that don't block other developers. That latter is very hard to achieve, at least without having everyone on the team know (wink, wink) how the interface is implemented. In short, it just works better if I don't take strong/purist stances on ADTs except as part of a well defined messaging framework (kernel/userspace, client/server, etc) where it's widely acknowledged to be a core architectural issue. - Dave C and C++ are both strongly typed and any sort of weak typing requires some layer on top of the language primitives. It is cetainly possible to go overboard with weak typing and/or encapsulation, but proper use of an abstract type can greatly simplify the implementation as the efforts to simplify the target APIs has shown. We are already adopting most of the encapsulation paradigm for targets and ADTs build on that. We may as well make our lives simpler and follow that paradigm as well since we are currently doing so half-heartedly. I recently spent 2 years defining a C API that uses encapsulation and ADTs and we've already shown that by doing so we have reduced the time to add new derived types since the infrastructure already exists. Further, users get a simpler view of the types since the only need
Re: [Openocd-development] RFC: struct cleanup and more
On Mon, 2009-06-01 at 11:12 -0700, Rick Altherr wrote: I'm all for removing the type redundancy, but I'd rather see the typedef stay and remove the struct name instead. It reduces typing when specifying the type and gets rid of the unnecessary separation of struct type names from other types. You are suggesting that we make all struct types anonymous, relying exclusively on typedefs? As far as I can tell, this simply would not work, because it would force headers to include the definition of those struct types in order to use them in any capacity. One could no longer do: struct foo; typedef struct foo foo_t; In other words, one could no longer create forward references at all, because there would be nothing to name as the type. This plan seems like it would lead us back to circular header dependencies. Cheers, Zach ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
On Jun 1, 2009, at 8:08 PM, Zach Welch wrote: On Mon, 2009-06-01 at 11:12 -0700, Rick Altherr wrote: I'm all for removing the type redundancy, but I'd rather see the typedef stay and remove the struct name instead. It reduces typing when specifying the type and gets rid of the unnecessary separation of struct type names from other types. You are suggesting that we make all struct types anonymous, relying exclusively on typedefs? As far as I can tell, this simply would not work, because it would force headers to include the definition of those struct types in order to use them in any capacity. One could no longer do: struct foo; typedef struct foo foo_t; In other words, one could no longer create forward references at all, because there would be nothing to name as the type. This plan seems like it would lead us back to circular header dependencies. Cheers, Zach Actually, I was suggesting using the typedef to be an opaque handle. The comments you grabbed were a precursor of sorts and as you correctly point out, do not allow forward declaration at all. Instead, I meant something like: struct foo; typedef struct foo * foo_t; Then, the API would use foo_t's as arguments. The fact that is a pointer to a struct is an implementation detail. To the user of the API, it's a foo regardless of how it is implemented. -- Rick Altherr kc8...@kc8apf.net He said he hadn't had a byte in three days. I had a short, so I split it with him. -- Unsigned smime.p7s Description: S/MIME cryptographic signature ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
On Mon, 2009-06-01 at 20:19 -0700, Rick Altherr wrote: On Jun 1, 2009, at 8:08 PM, Zach Welch wrote: On Mon, 2009-06-01 at 11:12 -0700, Rick Altherr wrote: I'm all for removing the type redundancy, but I'd rather see the typedef stay and remove the struct name instead. It reduces typing when specifying the type and gets rid of the unnecessary separation of struct type names from other types. You are suggesting that we make all struct types anonymous, relying exclusively on typedefs? As far as I can tell, this simply would not work, because it would force headers to include the definition of those struct types in order to use them in any capacity. One could no longer do: struct foo; typedef struct foo foo_t; In other words, one could no longer create forward references at all, because there would be nothing to name as the type. This plan seems like it would lead us back to circular header dependencies. Cheers, Zach Actually, I was suggesting using the typedef to be an opaque handle. The comments you grabbed were a precursor of sorts and as you correctly point out, do not allow forward declaration at all. Instead, I meant something like: struct foo; typedef struct foo * foo_t; Then, the API would use foo_t's as arguments. The fact that is a pointer to a struct is an implementation detail. To the user of the API, it's a foo regardless of how it is implemented. Thank goodness! We have almost arrived on the same page; I am with you on these dieas, except I would suggest '_p' for such types. :) I have some other clean up in mind that should be done before we try to tackle this stuff, but I will revise my C style guide patch with the ideas in this thread and repost them soon. Cheers, Zach ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
[Openocd-development] RFC: struct cleanup and more
Hi all, The following things nagged at me when I did the target_type clean-up: 1) Remove redundant structure typedefs: a) Entails the following steps (for each named struct type): i) s/^typedef struct type_s/struct type_s/ ii) s/^} type_t;/};/ iii) s/type_t/struct type_s/ iv) Fix any messes that these commands miss or make. ;) b) Eliminates what are essentially duplicated symbols: - simplifies the Doxygen documentation tremendously. - eliminates style ambiguity and forward referencing. 2) Improve the documentation for the target module files. - would be best to wait until other cleanup is done. 3) More moving and module clean-up: - I target.h needs some re-organization. - I have a jtag.h doc patch in progress. How do these changes look in the community's eyes? These were on the list of things to be considered for 0.2.0, but no one addressed them. I will post patches to clean-up and removal of jtag_tap_t in reply to this thread, to provide better foundation for concrete discussion about issue #1. While I think this would help the code and documentation a lot, I would even go further to suggest s/_s// from all struct names. Cheers, Zach ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
On Sunday 31 May 2009, Zach Welch wrote: 1) Remove redundant structure typedefs: a) Entails the following steps (for each named struct type): i) s/^typedef struct type_s/struct type_s/ ii) s/^} type_t;/};/ iii) s/type_t/struct type_s/ iv) Fix any messes that these commands miss or make. ;) b) Eliminates what are essentially duplicated symbols: - simplifies the Doxygen documentation tremendously. - eliminates style ambiguity and forward referencing. And makes the code *much* more approachable to anyone who's starting to pick it up ... for example, to help find/fix bugs. ... How do these changes look in the community's eyes? These were on the list of things to be considered for 0.2.0, but no one addressed them. They look good to me. This is a friendly time for such cleanup patches; they will make patches against the 0.2.0+ codebase cleaner. While I think this would help the code and documentation a lot, I would even go further to suggest s/_s// from all struct names. Most certainly. I realize there are coding conventions that promote such obfuscation, but given the least opportunity I will support non-obfuscated approaches instead. - Dave ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
On Sun, 31 May 2009, David Brownell wrote: On Sunday 31 May 2009, Zach Welch wrote: While I think this would help the code and documentation a lot, I would even go further to suggest s/_s// from all struct names. Most certainly. I realize there are coding conventions that promote such obfuscation, but given the least opportunity I will support non-obfuscated approaches instead. Agreed. If you're spelling it in full as a struct, then the _s suffix is redundant and could as well be removed. Nicolas ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
The 'struct foo_s' syntax is code bloat that obscures the actual
algorithms. 'foo_t' is shorter.
Doxygen seems to recognize the foo_s and foo_t version as one an the
same, I don't see what problem you have there. However it will just as
happily accept foo_t only, like in
typedef struct {} foo_t;
Michael
On Mon, Jun 1, 2009 at 1:37 AM, Zach Welch z...@superlucidity.net wrote:
Hi all,
The following things nagged at me when I did the target_type clean-up:
1) Remove redundant structure typedefs:
a) Entails the following steps (for each named struct type):
i) s/^typedef struct type_s/struct type_s/
ii) s/^} type_t;/};/
iii) s/type_t/struct type_s/
iv) Fix any messes that these commands miss or make. ;)
b) Eliminates what are essentially duplicated symbols:
- simplifies the Doxygen documentation tremendously.
- eliminates style ambiguity and forward referencing.
2) Improve the documentation for the target module files.
- would be best to wait until other cleanup is done.
3) More moving and module clean-up:
- I target.h needs some re-organization.
- I have a jtag.h doc patch in progress.
How do these changes look in the community's eyes? These were on the
list of things to be considered for 0.2.0, but no one addressed them.
I will post patches to clean-up and removal of jtag_tap_t in reply to
this thread, to provide better foundation for concrete discussion about
issue #1. While I think this would help the code and documentation a
lot, I would even go further to suggest s/_s// from all struct names.
Cheers,
Zach
___
Openocd-development mailing list
Openocd-development@lists.berlios.de
https://lists.berlios.de/mailman/listinfo/openocd-development
___
Openocd-development mailing list
Openocd-development@lists.berlios.de
https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
On Mon, 2009-06-01 at 04:15 +0200, Michael Bruck wrote:
The 'struct foo_s' syntax is code bloat that obscures the actual
algorithms. 'foo_t' is shorter.
I assume you prefer u32 over uint32_t, then? ;) Nevermind
I think 'struct foo' is much more clear when reading and writing code.
Doxygen seems to recognize the foo_s and foo_t version as one an the
same, I don't see what problem you have there. However it will just as
happily accept foo_t only, like in
typedef struct {} foo_t;
The problem with the documentation is the fact that there are two types
that refer to the same thing. The current scheme imposes extra effort
for new developers to realize that many blah_t types are structures, and
there is not immediate way to tell them apart without digging into
further into the documentation or code.
I think the Wikipedia page on typedefs does a good job of explaining the
reasons to avoid them in this particular case:
http://en.wikipedia.org/wiki/Typedef
Neither of the KR guidelines for using typedefs are met in this case:
1) These types do nothing to aid portability; they add no value here.
2) These types do not make a complex declaration easier to understand.
If anything, they make a simple declaration unnecessarily opaque.
Cheers,
Zach
___
Openocd-development mailing list
Openocd-development@lists.berlios.de
https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
On Sunday 31 May 2009, Michael Bruck wrote: The 'struct foo_s' syntax is code bloat that obscures the actual algorithms. 'foo_t' is shorter. Disagree about obscuring. And shorter doesn't matter here. If I see foo_t I have no idea what kind of thing it is. If I see a struct foo there's no such confusion. Ergo, foo_t has obscured. ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
On Sun, 2009-05-31 at 16:37 -0700, Zach Welch wrote:
Hi all,
The following things nagged at me when I did the target_type clean-up:
1) Remove redundant structure typedefs:
a) Entails the following steps (for each named struct type):
i) s/^typedef struct type_s/struct type_s/
ii) s/^} type_t;/};/
iii) s/type_t/struct type_s/
iv) Fix any messes that these commands miss or make. ;)
b) Eliminates what are essentially duplicated symbols:
- simplifies the Doxygen documentation tremendously.
- eliminates style ambiguity and forward referencing.
Attached is a quick attempt at a patch for the C Style Guide to add a
section for Structure Guidelines, covering the above ideas.
Cheers,
Zach
Index: doc/manual/style.txt
===
--- doc/manual/style.txt(revision 1971)
+++ doc/manual/style.txt(working copy)
@@ -66,7 +66,6 @@
- most identifiers must use lower-case letters (and digits) only.
- macros must use upper-case letters (and digits) only.
- OpenOCD identifiers should NEVER use @c MixedCaps.
-- structure names must end with the '_s' suffix.
- typedef names must end with the '_t' suffix.
- use underline characters between consecutive words in identifiers
(e.g. @c more_than_one_word).
@@ -80,6 +79,27 @@
- variables declarations may be mixed with code
- new block scopes for selection and iteration statements
+...@section stylestruct Structure Guidelines
+
+Structures should be defined using the guidelines in this section.
+
+- Declare structures like the following example:
+...@verbatim
+/**
+ * Description of the reason for needing foo.
+ */
+struct foo {
+ int bar;
+};
+...@endverbatim
+ - Always refer to this as codestruct foo/code.
+- Do @b not declare a @c typedef equivalent to the structure.
+ - Always refer to pointers as codestruct foo */code.
+- Do @b not declare a @c typedef for a pointer to the structure.
+- Structure names should be simple, without any suffix:
+ - All references to these names @a must be prefixed by @c struct,
+ - Any suffix (e.g. @c _s) appears redundant and should be removed.
+
@section stylefunc Functions
- static inline functions should be prefered over macros:
___
Openocd-development mailing list
Openocd-development@lists.berlios.de
https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
On Mon, Jun 1, 2009 at 4:35 AM, Zach Welch z...@superlucidity.net wrote:
On Mon, 2009-06-01 at 04:15 +0200, Michael Bruck wrote:
The 'struct foo_s' syntax is code bloat that obscures the actual
algorithms. 'foo_t' is shorter.
I assume you prefer u32 over uint32_t, then? ;) Nevermind
Yes I do.
I think 'struct foo' is much more clear when reading and writing code.
Doxygen seems to recognize the foo_s and foo_t version as one an the
same, I don't see what problem you have there. However it will just as
happily accept foo_t only, like in
typedef struct {} foo_t;
The problem with the documentation is the fact that there are two types
that refer to the same thing. The current scheme imposes extra effort
for new developers to realize that many blah_t types are structures, and
there is not immediate way to tell them apart without digging into
further into the documentation or code.
I think the Wikipedia page on typedefs does a good job of explaining the
reasons to avoid them in this particular case:
http://en.wikipedia.org/wiki/Typedef
Neither of the KR guidelines for using typedefs are met in this case:
1) These types do nothing to aid portability; they add no value here.
2) These types do not make a complex declaration easier to understand.
If anything, they make a simple declaration unnecessarily opaque.
Thanks, I know the purpose of typedef. In this particular case it is a
widely-used way to simulate the C++ behavior where the struct keyword
is unnecessary.
If it was for me the foo_s version would not exist, and there would be
no duplication.
You are pulling out KR? You can't be serious!
Michael
___
Openocd-development mailing list
Openocd-development@lists.berlios.de
https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
On Mon, Jun 1, 2009 at 4:41 AM, David Brownell davi...@pacbell.net wrote: On Sunday 31 May 2009, Michael Bruck wrote: The 'struct foo_s' syntax is code bloat that obscures the actual algorithms. 'foo_t' is shorter. Disagree about obscuring. And shorter doesn't matter here. If I see foo_t I have no idea what kind of thing it is. If I see a struct foo there's no such confusion. Ergo, foo_t has obscured. Yes, I read that argument on this list before. By this logic most C++ code in existence is doomed. Michael ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
On Mon, 2009-06-01 at 05:16 +0200, Michael Bruck wrote: On Mon, Jun 1, 2009 at 4:41 AM, David Brownell davi...@pacbell.net wrote: On Sunday 31 May 2009, Michael Bruck wrote: The 'struct foo_s' syntax is code bloat that obscures the actual algorithms. 'foo_t' is shorter. Disagree about obscuring. And shorter doesn't matter here. If I see foo_t I have no idea what kind of thing it is. If I see a struct foo there's no such confusion. Ergo, foo_t has obscured. Yes, I read that argument on this list before. By this logic most C++ code in existence is doomed. Doomed to a different style of code, yes. That's not subjective, it is a simple fact that derives from the very essence of each language. Cheers, Zach ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
On Mon, Jun 1, 2009 at 5:31 AM, Zach Welch z...@superlucidity.net wrote: On Mon, 2009-06-01 at 05:16 +0200, Michael Bruck wrote: On Mon, Jun 1, 2009 at 4:41 AM, David Brownell davi...@pacbell.net wrote: On Sunday 31 May 2009, Michael Bruck wrote: The 'struct foo_s' syntax is code bloat that obscures the actual algorithms. 'foo_t' is shorter. Disagree about obscuring. And shorter doesn't matter here. If I see foo_t I have no idea what kind of thing it is. If I see a struct foo there's no such confusion. Ergo, foo_t has obscured. Yes, I read that argument on this list before. By this logic most C++ code in existence is doomed. Doomed to a different style of code, yes. That's not subjective, it is a simple fact that derives from the very essence of each language. Sounds quite dramatic. I guess the essence of C is then to put redundant keywords everywhere. Your question was: How do these changes look in the community's eyes?. My answer was that they obscure the code (in my eyes). As you may have noticed from my absence on the u32 thread I am not really interested in these style debates as they cost too much of my time. I merely commented on this one because I was recently particularly annoyed when editing clusters of impenetrable gibberish like this here: /* This version of jtag_add_dr_scan() uses the check_value/mask fields */ extern void jtag_add_dr_scan_check(int num_fields, scan_field_t* fields, tap_state_t endstate); extern int interface_jtag_add_dr_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate); extern void jtag_add_plain_ir_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate); extern int interface_jtag_add_plain_ir_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate); extern void jtag_add_plain_dr_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate); extern int interface_jtag_add_plain_dr_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate); and I imagined how much worse that that would get once we mix in struct and enum. Michael ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
On Sunday 31 May 2009, Michael Bruck wrote: If I see foo_t I have no idea what kind of thing it is. If I see a struct foo there's no such confusion. Ergo, foo_t has obscured. Yes, I read that argument on this list before. By this logic most C++ code in existence is doomed. Well, it's been a few years since I've written C++ ... but I'll say that the C++ style guides I used were good about making clear if/when something was a class, so it wasn't doomed like that. In almost all cases ... the exception being smart pointers, which at this point ISTR added up to lose. On the grounds that they obfuscated too much. ;) ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
On Sunday 31 May 2009, Michael Bruck wrote: and I imagined how much worse that that would get once we mix in struct and enum. Heck, I imagined how much *better* it would be, especially if the whitespace/layout bugs got fixed. ;) ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
On Mon, Jun 1, 2009 at 6:00 AM, David Brownell davi...@pacbell.net wrote: On Sunday 31 May 2009, Michael Bruck wrote: and I imagined how much worse that that would get once we mix in struct and enum. Heck, I imagined how much *better* it would be, especially if the whitespace/layout bugs got fixed. ;) Well, I guess then go ahead and do what you have to do. Michael P.S. FYI scan_field_t is a struct, tap_state_t is an enum P.P.S. But hurry up before Zach starts quoting from KR's section on function declarations. ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] RFC: struct cleanup and more
On Sun, 2009-05-31 at 21:00 -0700, David Brownell wrote:
On Sunday 31 May 2009, Michael Bruck wrote:
and I imagined how much worse that that would get once we mix in
struct and enum.
Heck, I imagined how much *better* it would be, especially
if the whitespace/layout bugs got fixed. ;)
Amen. The unreadability of code like that quoted has little to do with
the use of struct keywords.
On a related note, I am in favor of using typedef with enum types --
just not with structs. In other words, I prefer:
typedef enum {
...
} name_t;
This difference stems from the simple fact that enum types are mostly
referenced by value; there, the code will be forced to have the full
definition of the type anyway.
In contrast, most structures are referenced by pointer, where the size
of the underlying type does not matter.
Cheers,
Zach
___
Openocd-development mailing list
Openocd-development@lists.berlios.de
https://lists.berlios.de/mailman/listinfo/openocd-development
