LeafLabs Garden » Topic: Discussion on the Wiring API and the new style Includes for libmaple

LeafLabs Garden » Topic: Discussion on the Wiring API and the new style Includes for libmaple http://forums.leaflabs.com/topic.php?id=2016 A place to share, learn, and grow... en-US Fri, 22 Jan 2016 00:05:20 +0000 http://bbpress.org/?v=1.0.2 <![CDATA[Search]]> q http://forums.leaflabs.com/search.php modkit on "Discussion on the Wiring API and the new style Includes for libmaple" http://forums.leaflabs.com/topic.php?id=2016&page=3#post-21239 Fri, 23 Nov 2012 01:40:04 +0000 modkit 21239@http://forums.leaflabs.com/ Thanks @siy, @gbulmer, and @mbolivar for a wonderful discussion! Sorry we're coming to this late but we hope to continue this focus on "pins as objects" over <a href="http://forums.leaflabs.com/topic.php?id=9685">here</a> gbulmer on "Discussion on the Wiring API and the new style Includes for libmaple" http://forums.leaflabs.com/topic.php?id=2016&page=3#post-12024 Thu, 26 Jul 2012 07:28:40 +0000 gbulmer 12024@http://forums.leaflabs.com/ mbolivar - (you were up late! I hope you're well.) Okay so this is validating the pin number: <pre><code>void digitalWrite(uint8 pin, uint8 val) { if (pin >= BOARD_NR_GPIO_PINS) { return; } gpio_write_bit(PIN_MAP[pin].gpio_device, PIN_MAP[pin].gpio_bit, val); }</code></pre> It silently does nothing when the pin number isn't valid. So, I think I understand that example, but I think the use case for my experimental class was different; I had hoped to eventually identify errors at compile time. My aim was to check validity of all Pin instances at construction. The overriding goal of the experiments were to keep digitalWrite and digitalRead minimal so that inline would be comparable to a function call in size, and as quick as practical. Also, I was assuming that if there was a good template-based solution, the error would be raised at compile time. The approach for this experimental class was weaker. So something like this (assuming the LeafLabs error handler which throbs led13 for assertion failure): <pre><code>//... #define GPIOA_VALID_PINS (0x0000E7FF) // valid GPIOA pins for Maple #define GPIOB_VALID_PINS (0x0000FFFB) // valid GPIOB pins for Maple #define GPIOC_VALID_PINS (0x0000E7FF) // valid GPIOC pins for Maple #define GPIOD_VALID_PINS (0x00000004) // valid GPIOD pins for Maple #define ASSERT_VALID_PIN(t) if (!(t)) pin_assert_failure("Pin::Pin failure", __LINE__) // ... class Pin { public: volatile uint32_t* const bitbandaddress; Pin(volatile void* addr, uint8_t bit): bitbandaddress(bb_perip(addr, bit)) { if (addr == GPIOA) { ASSERT_VALID_PIN((0x1<<bit) & GPIOA_VALID_PINS); } else if (addr == GPIOB) { ASSERT_VALID_PIN((0x1<<bit) & GPIOB_VALID_PINS); } else if (addr == GPIOC) { ASSERT_VALID_PIN((0x1<<bit) & GPIOC_VALID_PINS); } else if (addr == GPIOD) { ASSERT_VALID_PIN((0x1<<bit) & GPIOC_VALID_PINS); } else { ASSERT_VALID_PIN(false); } } private: Pin(): bitbandaddress((volatile uint32_t*)0xFFFFFFFF) {} // cheap and nasty: force an exception };</code></pre> In retrospect, a solution more like Maples digitalWrite might have been: <pre><code>inline volatile uint32_t* safebb(volatile void* addr, uint8_t bit) { if (addr == GPIOA && ((0x1<<bit) & GPIOA_VALID_PINS)) { return bb_perip(addr, bit); } else if (addr == GPIOB && ((0x1<<bit) & GPIOB_VALID_PINS)) { return bb_perip(addr, bit); } else if (addr == GPIOC && ((0x1<<bit) & GPIOC_VALID_PINS)) { return bb_perip(addr, bit); } else if (addr == GPIOD && ((0x1<<bit) & GPIOC_VALID_PINS)) { return bb_perip(addr, bit); } return bb_perip(GPIOD, 0); // harmless pin } // ... Pin(volatile void* addr, uint8_t bit): bitbandaddress(safebb(addr, bit)) {}</code></pre> So, at construction, the pin is either initialised correctly, or it is set to a harmless digital I/O address, e.g. <code>bb_perip(GPIOD, 0);</code>. That bitband address would be whatever digital I/O address would work silently in my digitalWrite and digitalRead. That would give some of the behaviour of Maple's digitalWrite. I prefer the 'proper' error in my old code :-) mbolivar on "Discussion on the Wiring API and the new style Includes for libmaple" http://forums.leaflabs.com/topic.php?id=2016&page=3#post-12015 Thu, 26 Jul 2012 00:32:11 +0000 mbolivar 12015@http://forums.leaflabs.com/ <blockquote> Why? I can imagine == and !=, but what's the example or use case for "pin <= BOARD_NR_GPIO_PINS"? </blockquote> well, here's <code>pin >= BOARD_NR_GPIO_PINS</code>: <a href="https://github.com/leaflabs/libmaple/blob/9a081c2d523252370ebcd100de1f3c57759ebcf5/wirish/wirish_digital.cpp#L49" rel="nofollow">https://github.com/leaflabs/libmaple/blob/9a081c2d523252370ebcd100de1f3c57759ebcf5/wirish/wirish_digital.cpp#L49</a> gbulmer on "Discussion on the Wiring API and the new style Includes for libmaple" http://forums.leaflabs.com/topic.php?id=2016&page=3#post-12006 Wed, 25 Jul 2012 20:05:26 +0000 gbulmer 12006@http://forums.leaflabs.com/ mbolivar <blockquote>One concern that you may have already considered: what happens when people try to treat a Pin as if it were a number? </blockquote> That seems quite exotic to me, but show me the example or use case where people do that now, and I might be able to propose a solution. I think I did have a function which mapped the bit band address to a pin number. It was used in pinMode instead of the for loop. But I thought it was muddying the simplicity of the approach, and this way pinMode is very simple and somewhat 'fail-safe'. <blockquote>Sounds like to get that to work properly, we'd need to override the arithmetic operators to look up the pin's number via PIN_MAP and do the right thing with it </blockquote> That seems like a pile of work, and maybe premature optimisation. Show the example and use cases, and we might come up with good proposals. My 'knee-jerk' reaction, without understanding enough about the actual use case, is to provide a way to map bitband addresses to useful numbers, and maybe an appropriate constant. <blockquote>The same thing would apply to comparisons (I can see someone typing pin <= BOARD_NR_GPIO_PINS, e.g.). </blockquote> Why? I can imagine <code>==</code> and <code>!=</code>, but what's the example or use case for "pin <= BOARD_NR_GPIO_PINS"? mbolivar on "Discussion on the Wiring API and the new style Includes for libmaple" http://forums.leaflabs.com/topic.php?id=2016&page=3#post-12005 Wed, 25 Jul 2012 19:58:10 +0000 mbolivar 12005@http://forums.leaflabs.com/ Interesting. One concern that you may have already considered: what happens when people try to treat a Pin as if it were a number? Sounds like to get that to work properly, we'd need to override the arithmetic operators to look up the pin's number via PIN_MAP and do the right thing with it, with the attendant error message concerns. The same thing would apply to comparisons (I can see someone typing <code>pin <= BOARD_NR_GPIO_PINS</code>, e.g.). gbulmer on "Discussion on the Wiring API and the new style Includes for libmaple" http://forums.leaflabs.com/topic.php?id=2016&page=3#post-12004 Wed, 25 Jul 2012 19:16:51 +0000 gbulmer 12004@http://forums.leaflabs.com/ mbolivar <blockquote>Out of curiosity, did you also try separate inline and "standard" versions ... </blockquote> No. I was experimenting, and I wanted it simple and 'lite', so only one version. Also, because my digitalRead and digitalWrite were intended to be simple and very compact, ideally smaller than a call of digitalRead and digitalWrite on <code>int</code>, non-inline versions made no sense to me (IIRC compiling with debug and using GDB works properly) <blockquote>... plus use of __builtin_constant_p() to determine which to use (as tried by Arduino)? </blockquote> Definitely not. IMHO part of the attraction of the Arduino library is most of it is readable. That looks unnecessarily complex. A lot of beginners just declare things like <code>int led = 13;</code> which I think fails the <code>__builtin_constant_p()</code> test. So the extra complexity only helps a more experienced developer, but a newbie would have to wade through quite subtle and sophisticated code to understand how it works. I'd rather encourage folks to look at the MCU reference manual (e.g. RM0008) than the C++ specification :-) My plan was to have a new type which would easily discriminate between the two variations of digitalRead/digitalWrite/pinMode. It was also intended to be simpler and more efficient anyway, so faffing around with integer pin numbers was minimised. Here's a rough cut early version which I've reconstituted; it didn't even use templates. I think digitalRead/digitalWrite are faster and smaller than the standard digitalRead/digitalWrite, but less safe in this version. One objective was to make the type no bigger than the default <code>int</code> pin number, so indiscriminate use of Pin is no worse than int. <pre><code>inline volatile uint32_t* pin_to_bitband(int pin_numb) { // luxury? // should validate pin number return bb_perip(PIN_MAP[pin_numb].gpio_device, PIN_MAP[pin_numb].gpio_bit); } class Pin { public: volatile uint32_t* const bitbandaddress; // Construct pin from port address and bit number Pin(volatile void* addr, uint8_t bit): bitbandaddress(bb_perip(addr, bit)) {} private: Pin(): bitbandaddress((volatile uint32_t*)0xFFFFFFFF) {} // cheap and nasty: force an exception }; inline void digitalWrite(Pin p, uint32_t value) { *(p.bitbandaddress) = value; } inline uint32_t digitalRead(Pin p) { return *(p.bitbandaddress+MAGIC_CONSTANT); } void pinMode(Pin p, WiringPinMode mode) { /* quick and dirty: find pin in PIN_MAP, then call pinMode(int,...) */ for (int i=0; i<BOARD_NR_GPIO_PINS; i++) { if (p.bitbandaddress == pin_to_bitband(i)) { pinMode(i, mode); break; } } /* proper: use the bitband address to derive control register addresses */ } const Pin D0(GPIOA, 3); // ... const Pin D5(GPIOB, 6); // ... const Pin D13(GPIOA, 5); // -- blink -- Pin led = D13; void setup() { pinMode(led, OUTPUT); } void loop() { digitalWrite(led, HIGH); delay(1000); digitalWrite(led, LOW); delay(1000); }</code></pre> It doesn't do pinMode 'properly'. It searches for a matching bitband address in PIN_MAP, and used the existing pinMode. It should calculate the control registers from the bit band address, and hence be more direct, and not dependant on PIN_MAP. Edit { I think an inline Pin digitalWrite or digitalRead could be the same number of instructions as the call of the standard int digitalWrite or digitalRead, and hence always smaller because the body of a 'standard' digitalWrite and digitalRead isn't needed. I also think a sequence of inline-calls might be fewer instructions than a sequence of standard calls because the compiler could optimise better. Hopefully we can agree that: <pre><code>inline void digitalWrite(Pin p, uint32_t value) { *(p.bitbandaddress) = value; } inline uint32_t digitalRead(Pin p) { return *(p.bitbandaddress+MAGIC_CONSTANT); }</code></pre> isn't too sophisticated C/C++ ? So someone trying to understand this is best directed to ARM Cortex-M3 documentation, and the MCU Reference Manual :-) } End-Edit The next step was to use templating so that the Pin instances were proper compile time constants. That might have made the inline digitalRead and digitalWrite smaller and quicker by removing the load-bitband-address-from-RAM, because the bitband address would be a comple-time constant. I didn't complete that templated variation because, at the time, some of the error messages I accidentally triggered were so opaque I felt people would be left flummoxed; the error messages mentioned templates, which I felt was too off-putting for non-C++ programmers. Maybe I should have tried more variations to try to make the errors easier? Edit: Trimmed the Pin class to bare essentials; I hope it's clearer. Also, I realise e.g. <code>inline void digitalWrite(Pin p, uint32_t value) ...</code> etc. could be <code>inline void digitalWrite(Pin& p, uint32_t value)</code>, but I didn't do that experiment. I don't think C programmers would normally use references, so this way is a useful test. (WARNING: I may have made errors reconstituting this) mbolivar on "Discussion on the Wiring API and the new style Includes for libmaple" http://forums.leaflabs.com/topic.php?id=2016&page=2#post-12003 Wed, 25 Jul 2012 16:06:59 +0000 mbolivar 12003@http://forums.leaflabs.com/ <blockquote> IIRC, I only added new versions of digitalRead, digitalWrite and pinMode, and a few constructors. It used a class to differentiate existing calls (which take a pin number) from the calls of the new functions (which take a Pin). All the pins were pre-declared, e.g. D13. My main goal was to make digitalRead/digitalWrite fast with minimal change to the API. </blockquote> Out of curiosity, did you also try separate inline and "standard" versions plus use of <code>__builtin_constant_p()</code> to determine which to use (<a href="http://arduino.cc/pipermail/developers_arduino.cc/2011-February/004340.html">as tried by Arduino</a>)? If so, what turned you off about it? siy on "Discussion on the Wiring API and the new style Includes for libmaple" http://forums.leaflabs.com/topic.php?id=2016&page=2#post-11994 Wed, 25 Jul 2012 09:02:08 +0000 siy 11994@http://forums.leaflabs.com/ @gbulmer, I completely agree, that at the time when C++ started gaining popularity, everyone tried to put every 'pet' idea into language. And definitely not every idea was simple enough to implement. But things like 'finally' clause were very easy to implement and would save a lot of time and efforts for users. Yes, I know about RAI and destructors, but while working with low level OS resources such as handles or OS-allocated memory regions 'pure' approach results to countless tiny classes which do nothing (beside making code harder to read). In contract 'pure' dynamic_cast<> was included into standard, despite significant efforts necessary to implement RTTI and its doubtful usability in real life. Must admit that I'm assessing C++ as a system programming language while standard is targeted toward application programming, hence different 'weights' for different features and their usefulness in real life. gbulmer on "Discussion on the Wiring API and the new style Includes for libmaple" http://forums.leaflabs.com/topic.php?id=2016&page=2#post-11989 Wed, 25 Jul 2012 07:45:14 +0000 gbulmer 11989@http://forums.leaflabs.com/ mbolivar - The experiment I'm describing was very simple. IIRC, I only added new versions of digitalRead, digitalWrite and pinMode, and a few constructors. It used a class to differentiate existing calls (which take a pin number) from the calls of the new functions (which take a Pin). All the pins were pre-declared, e.g. <code>D13</code>. My main goal was to make digitalRead/digitalWrite fast with minimal change to the API. BTW - I have also spoken to Bjarne Stroustrup. A chum, Mark, who taught friends and myself C++, probably had the first C++ compiler in Europe, and Bjarne cut him the tape. He was the UK representative to ISO for C++ for several years. I tried to help him by reading and discussing some of the proposed changes to C++. After reading them, I would have been obsessed with trying to keep the language coherent and 'pure' too. People complain about C++ complexity, but IMHO it could have been much, much more complicated if some of the proposals were accepted (NB: complex != complicated). At that time, people were trying to put every 'pet' idea they had into a programming language. I am looking back to before Java, SmallTalk was one of the important Object Orientated (OO) programming languages, and OO was the 'next big thing'. C++ clearly had support, industry attention and momentum, so it was likely to be used. Hence C++ standardisation became a 'magnet' for those people with 'pet' ideas for OO, and a target vehicle for implementing everything, including 'the kitchen sink':-) Stroustrup was probably bombarded with proposals and criticisms of C++ every waking hour for years. He likely heard most ideas, in some variation, several times each week. Further, he was one of the implementers, so the proposals weren't just intellectually interesting; he would likely end up having to implement them. I know that changes the way I listen to ideas. When designing any large, complex, software system, the hard part is not gathering 'wants', that is easy, everyone contributes those. The hard part is weeding out from the enormous volume of 'wants' the very few critical requirements, and focusing on the right ones well enough to build them adequately. Every new independent idea has a combinatorial impact on complexity, so we want to keep the core of systems simple and coherent (to keep it buildable, testable and flexible enough to evolve). As a more recent example, have a look at the volume of Java ideas, or look at VPRI's fonc mailing list. IMHO, Stroustrup did well to focus on a few key areas, move forward, and keep moving forward. I think it may be helpful for people to view conversations with him from this perspective. mbolivar on "Discussion on the Wiring API and the new style Includes for libmaple" http://forums.leaflabs.com/topic.php?id=2016&page=2#post-11949 Mon, 23 Jul 2012 17:50:09 +0000 mbolivar 11949@http://forums.leaflabs.com/ siy: I think you're probably right that many people avoid C++ for the "sharp tool" reason. I don't think I'm one of them, but I'm also not interested in having a fight about C versus C++. These two things are true: libmaple proper is in C, and the Wiring layer is in C++. Neither of those facts is going to change any time in the foreseeable future. I'm a bad C++ programmer, so there's good reason for me to avoid using C++ features in the code I write. However, as I've said, if you can make a good argument for using a particular C++ feature in the Wiring layer that's not currently in use, I'm happy to listen. It looks like you and gbulmer are off to a good start; I look forward to seeing what you come up with. siy on "Discussion on the Wiring API and the new style Includes for libmaple" http://forums.leaflabs.com/topic.php?id=2016&page=2#post-11947 Mon, 23 Jul 2012 17:25:59 +0000 siy 11947@http://forums.leaflabs.com/ @mbolivar, I think that many peoples trying to avoid C++ just because it really a "sharp tool" and any mistake may lead to not just "shot itself in the foot" but also "amputate legs, hands and head in the same time". To use it effectively one need to have very good understanding how every line of code will be handled by compiler. And C++ in many cases unnecessarily makes things complex even in cases which are very simple by nature but do not fit into "academic style" proposed by Stroustrup. Many years ago I had discussion with him in regard to some aspects of the C++ which were related to "real world" low level and system programming, but during that discussion I quickly realized that the main goal is "purity" rather than practical usability. At present choice of languages usable for embedded programming is quite limited, so we ought to use tools we have. With some reasonable restrictions and careful use C++ is way better than pure C (although still far from perfect). Since embedded programming by its nature (limited resources, lack of full-featured underlying OS and so forth) requires careful use of programming language and establishes some restrictions, difference between C and C++ in this regard is not so big. But, as I've mentioned above, C++ is way better and more powerful language. So, I see no reasons to limit itself and avoid C++. mbolivar on "Discussion on the Wiring API and the new style Includes for libmaple" http://forums.leaflabs.com/topic.php?id=2016&page=2#post-11943 Mon, 23 Jul 2012 14:33:54 +0000 mbolivar 11943@http://forums.leaflabs.com/ Wow, this discussion is really going somewhere. Great. Regarding the pros and cons of a template-based pin approach, I'm not qualified to comment, as I generally avoid using C++ features not available in C as much as I can. I remain very receptive to specific proposals with the kind of concrete analysis that gbulmer and siy have begun performing. Because of my inexperience, I will say right away that proposals which don't come with patches are not likely to be adopted, as I don't feel capable of coming up with a good implementation myself. I really don't like doing API design in isolation, and I totally agree that anything LeafLabs comes up with unilaterally is all but certain to have serious shortcomings that user feedback can easily correct. Case in point: <blockquote> A small comment; I think device, peripheral or registers are more memorable than c_dev </blockquote> Yes, I'm uncomfortable with the name as well, which is why I've been keeping this feature a little quiet. I chose c_dev to try to evoke intuition from c_str, but it does have all the flaws you've outlined. Thankfully, these have never been part of a release, so there's still time to come up with something better. I like "device" best of the names you've suggested; it makes it easier to point to documentation about libmaple's device model. We could additionally add a "registers" method, that did nothing more than return <code>this->device()->regs</code>. That would provide the standard escape hatch without any additional stuff wrapped around it which you desire. Thoughts? feurig on "Discussion on the Wiring API and the new style Includes for libmaple" http://forums.leaflabs.com/topic.php?id=2016&page=2#post-11923 Sun, 22 Jul 2012 21:54:46 +0000 feurig 11923@http://forums.leaflabs.com/ Well said. gbulmer on "Discussion on the Wiring API and the new style Includes for libmaple" http://forums.leaflabs.com/topic.php?id=2016&page=2#post-11922 Sun, 22 Jul 2012 21:52:17 +0000 gbulmer 11922@http://forums.leaflabs.com/ feurig - I did my experiments (using template classes) for a couple of reasons: 1. When I have dipped under the Arduino digitalRead/digitalWrite API (to get reasonable performance on a couple of projects), changes to the Arduino library broke my code, 2. the performance of some library calls, e.g. digitalWrite & digitalRead, on Maple are so poor, compared to the underlying hardware, that it is frustrating; problems that I feel I should be able to solve easily require special solutions. I've ended up coding ARM-specific solutions, which I later felt should have been portable. Edit: so I have wanted a 'standard' "escape hatch", to get at the hardware, and have NOT wanted much else wrapped around it. So, I don't completely agree that it isn't broken. It might not be broken for a lot of uses, but we do get quite a regular stream of people moving to Maple, and posting on the forum because they want a lot more performance than Arduino. So I feel more folks than me would appreciate performance improvements. A solution I was experimenting with was intended to be almost invisible. Things like digitalWrite(13, HIGH), worked the same as always, but digitalWrite(D13, HIGH) had much better performace. The easiest way to get that effect (that I can think of) is using classes for pins. Some folks assume the 'right way' is to drag in all the syntax of classes just because they have encapsulated something in a class. I don't feel that is essential, or even desirable in some cases. I do agree with the sentiment there is no benefit in moving to a new API which is either so complex it is unusable by the majority of folks (and I include error messages as part of this complexity), or users feel it is so opaque that it becomes magic, because that has defeated the purpose of improving it for me. (My base-reference for improvements is Wiring and not libmaple or Wirish.) I think it is extremely hard to get things right, and the Wiring/Arduino API is remarkably good. I do think the best way to get something better is to try it with real problems, with real people, and not expect to get it right first time, no matter how 'smart' we think we are. I think (but maybe wrong) that an evolutionary approach implies the improved interface needs to appear to be close to the old API. feurig on "Discussion on the Wiring API and the new style Includes for libmaple" http://forums.leaflabs.com/topic.php?id=2016&page=2#post-11920 Sun, 22 Jul 2012 21:02:18 +0000 feurig 11920@http://forums.leaflabs.com/ One of the joys of libmaple/wiring is that the details are kept out of the way, but you are allowed to just bypass them when when it makes sense. Most of what is proposed here (outside of pinMode(42, INPUT_PULLUP) which is just common sense) is way too complicated. As mbolivar and gbulmer already said. Keep it simple, keep it approachable. These things are not just for beginners. As an experienced programmer I don't want to pay attention to more detail than I have to; which is why I have started with wiring for most of my professional projects and why I am working with libmaple instead of the multitude of other stm code bases. I think you are WAY over-thinking this. . Classing pins is just freaking out there. Feel free to write me off as an stdio loving, c programming geezer . Problem is that even if it isn't elegant or technically interesting it ain't broken. . tl;dr omg @_@ NOOOOOOOO!!!!!!!!!