login
Search
Hello linux-kernel, Intro: This is a header with hardware definitions for ASIC3 chip, contributed by HP/Compaq. It is provided as-is, as a vendor-originated header. --------- ipaq-asic3.h: Hardware definitions for ASIC3 chip, found in ~12 handheld devices from HP/Compaq and HTC. Signed-off-by: Paul Sokolovsky <pmiscml@gmail.com> include/asm-arm/hardware/ipaq-asic3.h | 609 +++++++++++++++++++++++++++++++++ 1 files changed, 609 insertions(+), 0 deletions(-) diff --git a/include/asm-arm/hardware/ipaq-asic3.h b/include/asm-arm/hardware/ipaq-asic3.h new file mode 100644 index 0000000..789bb16 --- /dev/null +++ b/include/asm-arm/hardware/ipaq-asic3.h @@ -0,0 +1,609 @@ +/* + * + * Definitions for the HTC ASIC3 chip found in several handheld devices + * + * Copyright 2001 Compaq Computer Corporation. + * + * Use consistent with the GNU GPL is permitted, + * provided that this copyright notice is + * preserved in its entirety in all copies and derived works. + * + * COMPAQ COMPUTER CORPORATION MAKES NO WARRANTIES, EXPRESSED OR IMPLIED, + * AS TO THE USEFULNESS OR CORRECTNESS OF THIS CODE OR ITS + * FITNESS FOR ANY PARTICULAR PURPOSE. + * + * Author: Andrew Christian + * + */ + +#ifndef IPAQ_ASIC3_H +#define IPAQ_ASIC3_H + +/****************************************************/ +/* IPAQ, ASIC #3, replaces ASIC #1 */ + +#define IPAQ_ASIC3(_b,s,x,y) \ + (*((volatile s *) (_b + _IPAQ_ASIC3_ ## x ## _Base + (_IPAQ_ASIC3_ ## x ## _ ## y)))) +#define IPAQ_ASIC3_N(_b,s,x,y,z) \ + (*((volatile s *) (_b + _IPAQ_ASIC3_ ## x ## _ ## y ## _Base + (_IPAQ_ASIC3_ ## x ## _ ## z)))) + +#define IPAQ_ASIC3_GPIO(_b,s,x,y) \ + (*((volatile s *) (_b + _IPAQ_ASIC3_GPIO_ ## x ## _Base + (_IPAQ_ASIC3_GPIO_ ## y)))) + +#define IPAQ_ASIC3_OFFSET(x,y) (_IPAQ_ASIC3_ ## x ## _Base + _IPAQ_ASIC3_ ## x ## _ ## y) +#define IPAQ_ASIC3_GPIO_OFFSET(x,y) (_IPAQ_ASIC3_GPIO_ ## x ## _Base + _IPAQ_ASIC3_GPIO_ ## y) + + +/* All offsets below are specified with ...
Oh my eyes. What are these doing? The volatiles are a worry - volatile is said to be basically-always-wrong in-kernel, although we've never managed to document why, and i386 cheerfully uses it in readb() and friends. Perhaps if you can describe presisely what's going on here, alternatives might be suggested. -
This doesn't appear to be self consistent or GPL compatible. Any binary will be a derivative work and will not contain the copyright notice. Alan -
Hello Alan,
Well, this is one of those hard questions... Fortunately,
people who worked on this and were Compaq employees are reachable, so
I contacted Jamie Hicks, who is one of the authors of iPaq ports,
regarding solution for this. Jamie, would it be possible to leave
Compaq and other copyright notices, and Compaq disclaimer intact,
(or GPL2 wording, or verbose wording, whatever you see fit)
--
Best regards,
Paul mailto:pmiscml@gmail.com
-
The intent of the vague wording was to have the copyright notice and Compaq disclaimer of warranties preserved in the source code, not in binaries, but it is definitely ambiguous. As I understand it, copyright law says the copyright notices need to be preserved in source code, so that part of the statement is redundant, and GPL has its own warrantee disclaimer, so I think the standard wording is just fine. I approve changing to the more standard GPL wording used in the kernel sources in order to make this acceptable into the kernel.org tree. Jamey Hicks -
[well, can be turned into a patch] Here are some 'volatile' comments from Linus, extracted from several emails in at least 2 threads. If this is close to useful, we can add it to Documentation/. =============================================================== ***** "volatile" considered useless and evil: Just Say NO! ***** Do not use the C-language "volatile" keyword (extracted from lkml emails from Linus) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ I refuse to apply this part. If the memory barriers are right, then the "volatile" doesn't matter. And if the memory barriers aren't right, then "volatile" doesn't help. Using "volatile" in data structures is basically _always_ a bug. The only acceptable uses for "volatile" are: - in _code_, i.e., for things like the definition of "readb()" etc, where we use it to force a particular access. - with inline asms - on "jiffies", for stupid legacy reasons Basically, a volatile on a data structure can NEVER be right. If it makes a difference, it's a sign of improper locking. And the reason I refuse to apply that part of the patch is that anybody who even _thinks_ that they make a difference is horribly and utterly confused, and doesn't understand locking. If the memory barriers aren't sufficient, the volatiles are useless. If the memory barriers _are_ sufficient, the volatiles are useless. See? They're useless. The only thing they do is - potentially make the compiler generate worse code for no reason (the "no reason" being that if there aren't any barriers in between, the compiler _should_ merge accesses) - make some people _believe_ that that compiler does something "right". The first point doesn't much matter. The second point matters a LOT. Anybody who thinks "volatile" matters is WRONG. As such, a "volatile" is anti-documentation - it makes people think that something is true that is NOT true. In other words, volatile on data structures is ...
Since 'volatile' has two different semantics depending on the context in which it is used, this warning should be appended to include the fact that it is legitimate to use for inline assembly. -
I think it hasn't two semantics, it's like arguing that char has two semantics. Volatile does one thing - prohibits C compiler from optimizing accesses to the variable. Either with (volatile *) casts and with volatile var; Linus is right in that volatile != direct access to the hardware and direct sync between all CPUs. Yes, most uses in high level code are probably bugs. OTOH, there are other uses where optimizing must be prohibited. It doesn't matter which form is used, in fact volatile type name; name is equivalent to: type name; *(volatile type *)&name; At least as long as "volatile" keyword is concerned. -- Krzysztof Halasa -
What the meaning of an "access" to a volatile memory-mapped I/O port or a variable that can be asynchronously interrupted is implementation-defined. You're only citing qualified versions of objects. In an asm construct, if all your input operands are modified and specified as output operands as well, volatile must be added so that the entire construct is not optimized away. Additionally, it must be added if your construct modifies memory that is neither listed in inputs nor outputs to the construct so that it is known to have at least one side-effect. Then, the compiler cannot delete your construct if it is reachable because it may produce such side-effects. Thus, the warning that was proposed for addition to CodingStyle should be modified to explicitly state that the use of 'volatile' for asm constructs is perfectly legitimate and its use as a type qualifier for objects in code is inappropriate. David -
It's already there, isn't it? <quote from original:> The only acceptable uses for "volatile" are: - in _code_, i.e., for things like the definition of "readb()" etc, where we use it to force a particular access. - with inline asms - on "jiffies", for stupid legacy reasons </quote> or are you saying that you want to subject/header/title modified also? --- ~Randy *** Remember to use Documentation/SubmitChecklist when testing your code *** -
I wasn't aware that you were considering the inclusion of Linus' entire email in the document. There exists a point where CodingStyle becomes so large that people choose not to read it in its entirety, so I was expecting only an addition that would explicit document the acceptable and unacceptable uses of 'volatile' in kernel code with perhaps a link to his email. -
but I wouldn't put it into CodingStyle. -- ~Randy *** Remember to use Documentation/SubmitChecklist when testing your code *** -
No, David means that "asm volatile (...)" is meaningful and OK to use.
J
-
Ok, I mistook that. -- Krzysztof Halasa -
In a driver? Highly unlikey it is OK. In a filesystem? Even more unlikely it is OK to use. The set of circumstances where 'volatile' is acceptable is very limited. You will see it used properly in the definitions of writel(), for example. But most drivers using 'volatile' are likely bugs. Jeff -
I thought it was OK in readl(), writel(), etc... (and in asm), -- ~Randy *** Remember to use Documentation/SubmitChecklist when testing your code *** -
Not sure how to interpret your top-posted response :) It is normal in the definition of writel(), in arch code, but inappropriate in drivers when they _use_ writel(). If I may generalize, arch code generally knows what it's doing, when it uses volatile. OTOH, driver authors that use volatile generally do /not/ know what they are doing. Jeff -
It's probably worth noting that "asm volatile (...)" doesn't mean what
many people think it means: specifically, it *does not* prevent the asm
from being reordered with respect to the surrounding code. It may not
even prevent it from being reordered with respect to other asm
volatiles. *All* it means is that the asm code will be emitted even if
the compiler doesn't think its results will be used. Note that an
"asm()" with no outputs is implicitly "asm volatile()" - on the grounds
that it would be otherwise useless as far as gcc can tell.
If you need to guarantee ordering of asm statements, you must do it
explicitly, with either a "memory" clobber, or some finer-grain
serialization variable (like the _proxy_pda stuff). It would be useful
if you could tell gcc "I'm passing this variable to the asm for
serialization purposes, but there's no need to generate any explicit
references to it", but as far as I know there's no support for that.
J
-
The doc. should just be talking about "volatile" in C mostly. Any asm volatile comments are "extra". -- ~Randy *** Remember to use Documentation/SubmitChecklist when testing your code *** -
Ok, so let's take your second paragraph and my email of an hour ago: In an asm construct, if all your input operands are modified and specified as output operands as well, volatile must be added so that the entire construct is not optimized away. Additionally, it must be added if your construct modifies memory that is neither listed in inputs nor outputs to the construct so that it is known to have at least one side-effect. Then, the compiler cannot delete your construct if it is reachable because it may produce such side-effects. and add it to any proposed change to CodingStyle that suggests against the 'volatile' keyword since there exists a distinct difference in behavior between using the keyword as a type qualifier for an object and as a qualifier for an asm construct. David -
Hm. Is "asm volatile" necessary if you have a "memory" clobber? Would
Yeah, they're completely different. They're not even analogous, really,
which was my point. People confer more meaning to "asm volatile" than
it actually has, because of the analogy with volatile variables/types.
They would have been better off with something like "asm static", which
isn't much more meaningful, but at least it doesn't mislead the reader
into thinking it has anything to do with the other volatile.
But yes, seems like a worthwhile thing to point out. Or just point to
the gcc manual, which is pretty clear about all this stuff.
J
-
No, because the first requirement for 'volatile' in my paragraph above is restricted to clobbering specific hard registers and an operand cannot describe a hard register for a member when that register appears in the clobber list. If an input operand is modified (i.e. not "accessed", rather "modified" inclusive of the case where the previous value is the same as the original value) then it must also be specified as an output operand. Now if all such output operands are to specify that the input operands were "modified", 'volatile' is required to ensure the side-effects are preserved or, otherwise, gcc is free optimize the entire asm construct You're point about reordering "asm volatile" constructs differs depending on -mvolatile-asm-stop or -mno-volatile-asm-stop, however. David -
Erm, that seems to be ia64 specific, and I have no idea what adding a
"stop bit" implies. Can you set even or odd parity too?
J
-
It is analogous with a sequence point for ia64. But, as you mentioned, it is ia64 specific so your comment about "asm volatile" constructs not being reordered is always appropriate outside of ia64 specific code but may not apply to ia64 if we ever compiled with -mvolatile-asm-stop. If we do not compile with that option, the behavior is unspecified. I don't think we'll be adding -mvolatile-asm-stop support any time soon so your warning certainly is appropriate for all code at this time. David -
Sounds like it's referring to micro-architectural reordering, which is
distinct from compiler reordering. In other words, even if you
specified "-mvolatile-asm-stop" I would assume that the compiler could
still reorder the asm statements. Am I right, or should I read more
into the manual description than it actually says?
J
-
The ia64 architecture does not include any interlocks for asm constructs and allow them to be executed in parallel without stop bits (although it should emit a diagnostic message from gcc, although that is not a constraint that was introduced in C99). Adding -mvolatile-asm-stops will add these stop bits for any asm volatile construct that does not already have them so that gcc is aware that it is unsafe to execute such constructs in parallel. [ This is a tangent because we currently don't have -mvolatile-asm-stop support and it's ia64-specific. If they ever request such support, then this will simply alter your warning about reordering asm volatile constructs to exclude the ia64 case. ] David -
Well, the document is really about "volatile" in C, not in gcc asm extensions. --- ~Randy *** Remember to use Documentation/SubmitChecklist when testing your code *** -
Yes, definitely. Say Documentation/volatile-usage.txt -- this raw version could be touched a little bit, to have sections that clearly explain (1) how volatile makes the compiler generate trashy code, (2) why volatile doesn't even do what people _think_ it does, considering code is executed out-of-order by _hardware_ these days and not due to compilers like was the case 20 years back, (3) and so volatile ends up _hiding_ bugs from people and thus should be consigned to the trash can of history, (4) _except_ for _really special_ usage cases like reading IO mapped as memory. -
Hi Satyam, If you would like to organize it like that, I'd be happy to turn it over to you. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From: Randy Dunlap <randy.dunlap@oracle.com> Add information on the problems with the C-language "volatile" keyword and why it should not be used (most of the time). Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> --- Documentation/volatile-usage.txt | 129 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) --- /dev/null +++ linux-2.6.21-git10/Documentation/volatile-usage.txt @@ -0,0 +1,129 @@ +***** "volatile" considered useless and evil: Just Say NO! ***** + +Do not use the C-language "volatile" keyword +(extracted from lkml emails from Linus) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +[Comment about a patch:] + +> Also made all the relevant mce_log fields volatile for further safety. + +I refuse to apply this part. + +If the memory barriers are right, then the "volatile" doesn't matter. + +And if the memory barriers aren't right, then "volatile" doesn't help. + +Using "volatile" in data structures is basically _always_ a bug. + +The only acceptable uses for "volatile" are: + + - in _code_, i.e., for things like the definition of "readb()" etc, where we + use it to force a particular access. + - with inline asms + - on "jiffies", for stupid legacy reasons + +Basically, a volatile on a data structure can NEVER be right. If it makes +a difference, it's a sign of improper locking. + +And the reason I refuse to apply that part of the patch is that anybody +who even _thinks_ that they make a difference is horribly and utterly +confused, and doesn't understand locking. + +So please _never_ use them like this. + + +> mce_log is fully lockless - it deals with machine checks which act like NMIs. +> That is it's problem. +> +> In theory the memory barriers should be sufficient, the volatiles are +> just an additional safety net to ...
Again, please change this sweeping introduction to explicitly state that Linus' emails were a criticism of using 'volatile' for objects (he refers to them as "data structures") and can be appropriate for asm constructs. -
You haven't replied to my other emails... "volatile" used on a gcc asm extension is different, granted. It's not even a C-language "volatile" keyword AFAICT, so it doesn't apply in this context. Anyway, how is this slightly modified title? +***** "volatile" considered useless and evil: Just Say NO! ***** + +Do not use the C-language "volatile" keyword on kernel data +(extracted from lkml emails from Linus) --- ~Randy *** Remember to use Documentation/SubmitChecklist when testing your code *** -
Using 'volatile' for an asm construct certainly is a keyword; in fact, C99 It's still ambiguous. A much more explicit title that nobody could argue with would be "do not use the 'volatile' keyword as a type qualifier for an object." David -
OK, I can accept that. --- ~Randy *** Remember to use Documentation/SubmitChecklist when testing your code *** -
Except when you do. The kernel uses the C volatile in various places itself for specific good reasons (and some for historical bad ones) Perhaps a closer summary would be Do Not Use Volatile ------------------- 1. volatile is not a locking mechanism Volatile does not define sufficiently sane or strong semantics for locking. The kernel has proper locking mechanisms which also act as compiler fetch/store barriers and where neccessary hardware barriers for SMP systems. The kernel knows about all the corner cases, you probably don't. 2. volatile is not needed for mmio space I/O memory access are done via readb/writeb and friends. They deal with volatility themselves so you don't have to. They may nor may not use volatile internally to their implementation, but that is none of your business. 3. volatile is not atomic Using volatile does not guarantee atomic behaviour. This often requires special instructions or code sequences too. We have atomic_t and the atomic_* operators for this. 4. volatile is not a store or read barrier Using volatile is not always sufficient to order accesses on SMP or to ensure things execute in the order expected. Instead the kernel provides a set of barrier operations which have clearly defined semantics on all systems. Make use of rmb, wmb, barrier, smp_wmb etc instead When Might You Need volatile ? ------------------------------ When you are implementing the locking primitives on a new platform. When you are implementing the I/O and atomic prmitives on a new platform. Also in inline gcc assembler where "volatile" is used for subtly different purposes. Possibly very special cases we haven't thought about yet. However if you find one remember the need for portability and ask whether it should be using volatile or there is a gap in the existing hardware abstraction. -
Is there a good reason for using volatile in atomic/locking primitives? AFAIKS there is not. -- SUSE Labs, Novell Inc. -
Depends on the platform. If you are writing a new architecture then who knows what you will need to get the barriers right - you may want to use volatile, you may want to use asm. -
What is determined to be an "access" (read or modify) to an object such as a locking primitive that is type-qualified with the keyword 'volatile' is implementation defined. You cannot guarantee that the value in such an object would agree with the evaluation thus far as specified by the semantics of the code even at sequence points because such an object can be modified without knowledge to the implementation. The only thing you _can_ guarantee at these sequence points is that their previous accesses are complete and later accesses, as specified by the semantics of the code, have not yet occurred. This does not exclude the possibility that they were modified without knowledge to the implementation. In this case, the actual and abstract semantics of the text may not agree. Thus, any reliance on type-qualifying an object that represents an atomic or locking primitive on the keyword 'volatile' is misplaced. David -
arch/foo is generally implementation specific code. -
That's true, but what qualifies as an "access" to an object that is type qualified with the 'volatile' keyword is _implementation_ defined, meaning the behavior is defined by the compiler and not this new architecture you're proposing 'volatile' is appropriate for. That's pure C99. -
On Wed, 9 May 2007 11:41:27 -0700 (PDT) arch/foo almost always supports a single compiler too - gcc. We simply don't support anything else. We use gcc inlines and features extensively. And who cares about such fine detail of C99, did they fix the struct copy bug in ANSI C even ? [1] Alan [1] ANSI C says access to the padding fields of a struct is undefined. ANSI C also says that struct assignment is a memcpy. Therefore struct assignment in ANSI C is a violation of ANSI C... At this point its a lot simpler not to care about other compilers pet insanities or areas of the spec like volatile that are vaguer and less credible than the output of the US congress. -
Ok, so your "acceptable use clause" of your addition should include that fact. That the volatile type qualifier is legitimate when developing a new architecture and the only implementation you support for compilation of such text has a one-to-one correspondence between actual and abstract Padding bytes are unspecified, not undefined. I doubt ANSI C says padding bytes are undefined because then any implementation that pads members of a struct object would not be strictly conforming. David -
Um, I've picked up the tinycc baton (in my copious free time) and am slowly trying to get it to build a bootable linux kernel. There's a ways to go, and I really have no idea what I'm doing, but I have help and even made a release recently (which is already significantly out of date, largely thanks to David Wheeler): http://landley.net/code/tinycc/ Admittedly, a lot of this involves implementing gcc extensions, but gratuitous use of them when there's a perfectly good c99 way of doing it isn't necessarily a plus. Fabrice got it as far as tccboot before QEMU ate his life, we've improved a bit since then, and there's presumably a finite amount of work left to be done... Rob -
I like Jonathan's article http://lwn.net/Articles/233479/ a lot. It puts as much emphasis on the DOs as on the DON'Ts, which I find helpful. -- Stefan Richter -=====-=-=== -=-= -=--= http://arcgraph.de/sr/ -
Yep. I expect to drop my patch in favor of Jon's writeup. --- ~Randy *** Remember to use Documentation/SubmitChecklist when testing your code *** -
Yeah, that article was both comprehensive and to-the-point indeed. I was trying my hand at re-organizing your original mail, but Jon's version is nicer. -
I just took a shot at turning this into something more like a normal document: http://lwn.net/Articles/233479/ Comments welcome. If people think it suits the need I'll happily make a version which moves from the LWN style to Documentation/ and send it in. Thanks, jon Jonathan Corbet / LWN.net / corbet@lwn.net -
I think the "jiffies variable is special" part misses the
"for stupid legacy reasons" explanation.
According to the other volatile rules one should use
something like that:
extern unsigned long __jiffies;
static inline unsigned long read_ulong(unsigned long *addr)
{
return *(volatile unsigned long *)addr;
}
static inline unsigned long get_jiffies(void)
{
return read_ulong(&__jiffies);
}
But of course changing all references to jiffies in the kernel would
be insane, thus jiffies is special "for stupid legacy reasons".
Right?
Johannes
-
Right. jiffies comes with no locking protection by default (and adding one today in a patch that is not invasive / disruptive could be difficult). If it had a spinlock or something for itself then the above discussion would have been void, everybody would've just grabbed the lock before accessing jiffies, and the spinlock implementation would have done the Right Thing by itself (using barriers, obviously, and so "volatile" would've been unnecessary even then). Anyway, as things stand, jiffies comes without locks for itself. But using a volatile "access cast" to read jiffies whenever you might need it is _still_ not what I would personally prefer. IMO, it's *much* better to use something like barrier() if / where you're sitting in a tight loop comparing jiffies to whatever (a timeout expiry for example). So, if you _really_ need / want to do something of this sort, I'd much rather see: while (time_before(jiffies, expiry)) barrier(); in code instead of: while (time_before((*(volatile unsigned long *)&jiffies), expiry)) ; But of course, while (time_before(jiffies, expiry)) cpu_relax(); would be better still. A last word from Linus himself here would be obviously best, but I'm not so sure it makes sense to allow the "volatile" type qualifier _even_ for the jiffies case. -
| Greg KH | Og dreams of kernels |
| Jens Axboe | [PATCH 31/33] Fusion: sg chaining support |
| Arnd Bergmann | Re: finding your own dead "CONFIG_" variables |
| Mark Brown | [PATCH 2/2] Subject: natsemi: Allow users to disable workaround for DspCfg reset |
| Tony Breeds | [LGUEST] Look in object dir for .config |
git: | |
| Brian Downing |