Re: [Openocd-development] RFC: struct cleanup and more
On Wed, 2009-06-10 at 21:59 -0400, Duane Ellis wrote: > ?? >> 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. Nope, but you missed the one that I tried to make (tangentially). > How the *modules* are done - is well done, no questions asked. > > How modules are debugged, is another matter entirely. > That is my point. In terms of debugging, "static modules" would be no different than what we have today. Literally, I see "plugins" being another option that users can enable, with the default being the same code we have now. Use them or don't. I expect some users will always want to have a monolithic OpenOCD binary. That's fine, but let us have our cake too. Allowing for plug-ins should not change anything for developers, but they would reduce OpenOCD's run-time resource requirements without compromising on installed features. Users of binary packages should appreciate being able to load only those modules that they need into memory, not be forced to load them all. You don't have to debug this feature, but some of us would. --Z ___ 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 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 Tue, 2009-06-09 at 22:17 -0700, David Brownell wrote: > On Tuesday 09 June 2009, Rick Altherr wrote: > > I'm proposing that we use encapsulation and possibly ADTs to define > > clear boundaries for functionality in the code base. Rather than have > > one massive code base, I'd like to see subsystems that can be worked > > on internally with minimal effect to the users of that subsystem. > > OpenOCD has some of that and Zach has been doing a lot of work to > > refine that. > > I think we agree there. And yes, Zach's code overhauls are > good to see. > > Something else that's worth observing is that clean boundaries > might make it practical to build an OpenOCD core which doesn't > pre-link every interface, NOR, NAND, and CPU driver ... they > could be dynamically loaded modules. (CPU drivers being the > most complex.) > > Having clean boundaries there would make it easier to provide > new modules, by reducing the amount of information folk need > to master before they can plug in new code. 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. --Z ___ 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 Tuesday 09 June 2009, Rick Altherr wrote: > I'm proposing that we use encapsulation and possibly ADTs to define > clear boundaries for functionality in the code base. Rather than have > one massive code base, I'd like to see subsystems that can be worked > on internally with minimal effect to the users of that subsystem. > OpenOCD has some of that and Zach has been doing a lot of work to > refine that. I think we agree there. And yes, Zach's code overhauls are good to see. Something else that's worth observing is that clean boundaries might make it practical to build an OpenOCD core which doesn't pre-link every interface, NOR, NAND, and CPU driver ... they could be dynamically loaded modules. (CPU drivers being the most complex.) Having clean boundaries there would make it easier to provide new modules, by reducing the amount of information folk need to master before they can plug in new code. - 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
The strong vs weak typing issue is very vague and either side could be
defended for nearly every programming language as you can see from
this very discussion. See http://en.wikipedia.org/wiki/Strongly-typed_programming_language
for more examples. In the grand scheme of things, weak vs strong
has very little to do with the suitability of a language for a design
pattern or algorithm.
I'm proposing that we use encapsulation and possibly ADTs to define
clear boundaries for functionality in the code base. Rather than have
one massive code base, I'd like to see subsystems that can be worked
on internally with minimal effect to the users of that subsystem.
OpenOCD has some of that and Zach has been doing a lot of work to
refine that.
--
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 9, 2009, at 8:51 PM, David Brownell wrote:
On Tuesday 09 June 2009, Rick Altherr wrote:
although this is the first time I've ever
heard anyone apply that term to C. ...
I've commonly heard C and C++ referred to as strongly-typed.
Never *once* have I heard that usage before yours. Usually C gets
described as a weakly/loosely typed language. (This is in the
context of multiple classes and seminars that did comparative
studies of dozens of programming languages and type systems.)
The fact
that you can't declare a variable without a type is an indication of
this.
No; it just means they have types, and require declarations.
But in fact, C doesn't require, and never has required, types
for everything. I just compiled the following; no errors, and
not even any warnings unless I specify "-std=c99".
main(argc, argv)
{
argc = argv;
return 0;
}
Over time, C has integrated mechanisms that lets one's code
trigger warnings from some flavors of type abuse. But at
its core, it's still weakly typed.
Plus, having a declaration says nothing about whether that
will be "strongly" enforced, or can instead be suborned.
void * let's you work around some undesirable effects of strong-
typing, but it is a type itself.
That "work around" means "violate any type rules you want",
which is prima facie evidence that the type system is not
what's called "strong" ... either at compile time, or at
run time.
Contrast that to something like LISP or Lua ... or even TCL.
In key ways, those have stronger typing than C: they have
only a handful of data types and you can't escape them.
(That property is also a flavor of what's called "safety",
and one which lends itself to crash-free software. C is
not known for being crash-free; neither is C++.)
But on the flip side their type systems are not extensible,
so when you build abstraction layers you've got to define
your own typing conventions. Which can't be enforced at
compile time (another aspect of "safety", which would help
some other robustness characteristics), so they're weak in
those respects. Yet C provides some extension mechanisms...
:)
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. :)
That's really all I'm recommending. I've seen a dynamic- and
strongly-
typed language do very well for doing encapsulation and using ADTs to
make a very clean system architecture that allows for lots of future
extensions.
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 Tuesday 09 June 2009, Rick Altherr wrote:
> > although this is the first time I've ever
> > heard anyone apply that term to C. ...
>
> I've commonly heard C and C++ referred to as strongly-typed.
Never *once* have I heard that usage before yours. Usually C gets
described as a weakly/loosely typed language. (This is in the
context of multiple classes and seminars that did comparative
studies of dozens of programming languages and type systems.)
> The fact
> that you can't declare a variable without a type is an indication of
> this.
No; it just means they have types, and require declarations.
But in fact, C doesn't require, and never has required, types
for everything. I just compiled the following; no errors, and
not even any warnings unless I specify "-std=c99".
main(argc, argv)
{
argc = argv;
return 0;
}
Over time, C has integrated mechanisms that lets one's code
trigger warnings from some flavors of type abuse. But at
its core, it's still weakly typed.
Plus, having a declaration says nothing about whether that
will be "strongly" enforced, or can instead be suborned.
> void * let's you work around some undesirable effects of strong-
> typing, but it is a type itself.
That "work around" means "violate any type rules you want",
which is prima facie evidence that the type system is not
what's called "strong" ... either at compile time, or at
run time.
Contrast that to something like LISP or Lua ... or even TCL.
In key ways, those have stronger typing than C: they have
only a handful of data types and you can't escape them.
(That property is also a flavor of what's called "safety",
and one which lends itself to crash-free software. C is
not known for being crash-free; neither is C++.)
But on the flip side their type systems are not extensible,
so when you build abstraction layers you've got to define
your own typing conventions. Which can't be enforced at
compile time (another aspect of "safety", which would help
some other robustness characteristics), so they're weak in
those respects. Yet C provides some extension mechanisms...
:)
> > 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. :)
>
> That's really all I'm recommending. I've seen a dynamic- and strongly-
> typed language do very well for doing encapsulation and using ADTs to
> make a very clean system architecture that allows for lots of future
> extensions.
___
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 9, 2009, at 6:41 PM, David Brownell wrote: 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. That would be "very strong". "strong" just means that a variable has a designated type associated with it. "weak" on the other hand is like JavaScript where a variable has no type information attached to it. 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. "strong" typing has nothing to do with hiding machine-specific details. It's all about a variable being designated to hold a specific type of data rather than an arbitrary type. Now, void * in C lets you cast between types that would otherwise cause errors. That doesn't make it "weak", just not as "strong". 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!) I've commonly heard C and C++ referred to as strongly-typed. The fact that you can't declare a variable without a type is an indication of this. void * let's you work around some undesirable effects of strong- typing, but it is a type itself. 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.) I agree the multitude of options for casting are confusing in C++, but those actually point to the fact that C++ is strongly typed by default. The reason that dynamic_cast exists is that C++ assumes that references to variables are to a specific type (static typing) and will normally write code to access it directly as such. dynamic_cast tells C++ to instead evaluate the type at runtime (dynamic typing) so the underlying type can be changed without recompiling the calling code. 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!). I never said it was. Encapsulation can easily be done in any language regardless of strong vs weak. ADTs on the other hand build on top of encapsulation and dynamic runtime type information. They utilize encapsulation to hide the internal details of the object so that those internals can be changed by subclasses. Further, by using dynamic typing, the subclasses can be passed a reference to the ADT and convert it into their subclass so they can do special things to it. 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. I'm not a huge fan of "very strong" for typing nor of static typing. They purport to improve the stability of the code by always knowing what can be done with an object but it makes for a lot of nasty code though since non-trivial programs often need some of the features of weak-typing along with dynamic typing. I'm actually quite fond of Objective-C which is strongly-typed and very dynamic. Further, everything is allocated on the heap and passed by pointer. So objects can be cast to a generic type that means "some type of class" and then have the type information recovered by asking the object. 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. :) That's really all I'm recommending. I've seen a dynamic- and strongly- typed language do very well for doing encapsulation and using ADTs to make a very clean system architecture that allows for lots of future extensions. 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). :) -- 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 ___
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 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
On Wed, Jun 3, 2009 at 6:38 AM, Rick Altherr 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 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
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
>> 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. ___ 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
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 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
List was dropped. Sent from my iPhone On Jun 1, 2009, at 4:19 PM, David Brownell wrote: > On Monday 01 June 2009, Rick Altherr wrote: >> On May 31, 2009, at 7:41 PM, David Brownell >> 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 der
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
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
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 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 06:12 +0200, Michael Bruck wrote: > On Mon, Jun 1, 2009 at 6:00 AM, 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. ;) > > 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 K&R's section on > function declarations. Who is being dramatic now? :) --Z ___ 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
Re: [Openocd-development] RFC: struct cleanup and more
On Mon, Jun 1, 2009 at 6:00 AM, 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. ;) 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 K&R'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 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 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 Mon, Jun 1, 2009 at 5:31 AM, Zach Welch wrote: > On Mon, 2009-06-01 at 05:16 +0200, Michael Bruck wrote: >> On Mon, Jun 1, 2009 at 4:41 AM, David Brownell 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 Mon, 2009-06-01 at 05:16 +0200, Michael Bruck wrote: > On Mon, Jun 1, 2009 at 4:41 AM, David Brownell 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, 2009-06-01 at 05:14 +0200, Michael Bruck wrote:
> On Mon, Jun 1, 2009 at 4:35 AM, Zach Welch wrote:
> > On Mon, 2009-06-01 at 04:15 +0200, Michael Bruck wrote:
[snip]
> > 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 K&R 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.
By this argument, the foo_s should preferred for the same reasons: you
could use that without struct in C++ too. C is _not_ C++; in fact, C++
is even more opaque and obfuscated, so this argument holds little water.
If you like obfuscation, then use C++ -- let C be C.
> If it was for me the foo_s version would not exist, and there would be
> no duplication.
>
> You are pulling out K&R? You can't be serious!
I am pulling out the original _principles_ that created the keyword.
Both of the points that I made still hold true, even with C99.
C++ principles are not compelling, since we are discussing C code.
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, 1 Jun 2009, Michael Bruck wrote: > On Mon, Jun 1, 2009 at 4:41 AM, David Brownell 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. No argument here. Nicolas (who dislikes C++) ___ 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 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, Jun 1, 2009 at 4:35 AM, Zach Welch 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 K&R 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 K&R? 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 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 struct foo.
+- Do @b not declare a @c typedef equivalent to the structure.
+ - Always refer to pointers as struct foo *.
+- 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 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 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 K&R 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
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 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 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
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
[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
