On Monday 01 January 2007 12:55 pm, Pavel Machek wrote: > > Think of it as "cookies represented by integers" if you like. > > typedef int gpio_t would hurt, and would serve as a useful > documentation hint.
Yes, I agree that such needless obfuscation hurts. ;) Plus, such a typedef would disagree with Documentation/CodingStyle which says "... the rule should basically be to NEVER EVER use a typedef" (with some exceptions not matched here). > > Should it instead say that's an (obviously unchecked) error? > > Saying it is an error would be okay by me. (Or "Behaviour of these calls for > GPIOs that can't be safely accessed without sleeping is undefined."). See the appended doc patch ... better? - Dave ================= CUT HERE Index: at91/Documentation/gpio.txt =================================================================== --- at91.orig/Documentation/gpio.txt 2006-12-29 00:00:28.000000000 -0800 +++ at91/Documentation/gpio.txt 2006-12-29 15:47:18.000000000 -0800 @@ -78,7 +78,8 @@ Identifying GPIOs ----------------- GPIOs are identified by unsigned integers in the range 0..MAX_INT. That reserves "negative" numbers for other purposes like marking signals as -"not available on this board", or indicating faults. +"not available on this board", or indicating faults. Code that doesn't +touch the underlying hardware treats these integers as opaque cookies. Platforms define how they use those integers, and usually #define symbols for the GPIO lines so that board-specific setup code directly corresponds @@ -139,8 +140,8 @@ issues including wire-OR and output late The get/set calls have no error returns because "invalid GPIO" should have been reported earlier in gpio_set_direction(). However, note that not all platforms can read the value of output pins; those that can't should always -return zero. Also, these calls will be ignored for GPIOs that can't safely -be accessed wihtout sleeping (see below). +return zero. Also, using these calls for GPIOs that can't safely be accessed +without sleeping (see below) is an error. Platform-specific implementations are encouraged to optimise the two calls to access the GPIO value in cases where the GPIO number (and for @@ -239,7 +240,8 @@ options are part of the IRQ interface, e system wakeup capabilities. Non-error values returned from irq_to_gpio() would most commonly be used -with gpio_get_value(). +with gpio_get_value(), for example to initialize or update driver state +when the IRQ is edge-triggered. @@ -262,7 +264,8 @@ like the aforementioned options for inpu Hardware may support reading or writing GPIOs in gangs, but that's usually configuration dependednt: for GPIOs sharing the same bank. (GPIOs are commonly grouped in banks of 16 or 32, with a given SOC having several such -banks.) Code relying on such mechanisms will necessarily be nonportable. +banks.) Some systems can trigger IRQs from output GPIOs. Code relying on +such mechanisms will necessarily be nonportable. Dynamic definition of GPIOs is not currently supported; for example, as a side effect of configuring an add-on board with some GPIO expanders. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
