So the "thing", of the last post, was porting of https://github.com/ericwazhung/grbl-abstracted such that grbl can now be more-easily ported to a variety of architectures.

Now (actually, months-ago) functioning and configurable for either a PIC32 or the original AVR (while remaining Byte-For-Byte identical to the original!). If you're curious, check out the "diff" at that page.

----------

Today, as a move toward porting #sdramThingZero - 133MS/s 32-bit Logic Analyzer to its next architecture (originally AVR, now PIC32, and, again, with all intention of making it completely "architecture-agnostic" (where did I get that phrase stuck in my head...? It doesn't seem quite right...)... as a means to that end, I've begun the first completely new version of my first go-to 'commonThing,' 'bithandling,' since its origins about a decade ago.

----------

I've jumped from v0.99 to v1.99, because, frankly, it's darn-near entirely different, and darn-near a complete rewrite, with new function/macro-names and more standardization...

E.G. a big one that should make it a million times more intuitive:

all argument-lists are now arranged such that the variable to be modified is listed *first*.

Apparently, I was pretty much completely arbitrary about that in the previous versions... and, despite having made *TONS* of use of it over the years, that was always a big trip-up...

e.g. writeMasked2(variable, mask, value) rather'n... oh jeeze, what was that order again?

E.G.2. a big one that might make it a million times less intuitive:

'bithandling' has been stripped of most of its GPIO-related stuff, that stuff has now been moved to 'gpio_port' (that's a "more intuitive")... but in-so-doing I also changed quite a few macro-names... e.g. whereas previously all the port-related macro-names were *very closely* related to the associated 'bithandling' names (e.g. setpinPORT() ~ setbit()) now they're NOT AT ALL similar. E.G. setpinPORT -> gpioPORT_ohJeezeI'veAlreadyForgotten.

gpioPORT_makeOutputPinHigh(), or, rather, gpioPORT_outputOneToPin(), I think.

So, where *reading* the code is downright self-explanatory, *writing* the code seems to result in lots of reference to gpio_port.h

That, maybe, is more a result of just not yet being familiar with it...

It was pretty bad, before, as well... e.g. there was setinPORT() and setPORTin()... one would set a pin on a port to an input, the other would set the entire port to inputs (all bits).

These *ideas* came about mostly as a result of prepping these macros for grbl-abstracted, and, to a much lesser-extent, much of it was implemented there... and I'm pretty content with most of the changes, but there's reason I went to 1.99, rather than 2.00, as I'm obviously not 100% on a few things. (But, surely, it was *WAY* too large a change to go from merely 0.99 -> 1.00)

So, having written the whole blasted thing with those crazy-long function-names ala how you're supposed to choose a difficult-to-crack, but allegedly-easy-to-remember password:

https://xkcd.com/936/... well, anyways, you're *supposed* to be able to remember those things... but these things are a bit more wonky... Did I choose "correct" or "right", "One" or "High" this time 'round...? Yahknow?

...I find I might just write a whole new set of wrapper-macros or otherwise rename 'em back to the old names I've somewhat arbitrarily-memorized, but with a "2" at the end so I know that the version-2 macro-names *always* have the arguments listed with the *variable first* (or *PORT*).

We'll see.

Maybe I'll write a shell-script to automatically change e.g. setinPORT2() to gpioPORT_configurePinAsInput() for whenever I might decide to distribute something, just so it's easier for me to write/remember, while also being easier for newbs to digest. It's a thought.

--------------

Other additions:

Because bithandling is pretty much the first thing to go into any of my projects, regardless of the architecture, it handles a few architecture-related-things, like making it possible to easily add architecture-specific code to other 'commonThings' *when necessary*... Which, of course, is *highly* necessary for 'gpio_port'... So far, there's gpio_port_avr.h and gpio_port_pic32.h... So, there's a #include in gpio_port.h that looks, quite literally, like:

#include CONCAT_HEADER(gpio_port_,__MCU_ARCH__)

which equates, hopefully obviously, to (when compiled for an AVR):

#include "gpio_port_avr.h"

This method, again, was largely developed for grbl-abstracted, and now finally moved to commonCode.

And... a sorta late-in-the-game realization that I'll probably make use of in the near-future...

Part of the point of gpio_port's functionality is that it makes darn-near everything one can do with a GPIO port/pin available as its own macro... SUCH THAT, A) it's easy to read, B) it compiles (via optimizer) as, usually, the bare-minimum instructions that'd be required to accomplish the goal (no switch-statements to look up which pin is on which port, or which functionality to perform, etc.)...

BUT: again, that can lead to a bit of confusion with the naming... because there are a *lot* of names.

And, even worse, it means that *all those things* have to be reimplemented each time a new architecture is added (if you want full architecture-...-independent support for whatever code makes use of it). That's a lot of work.

SO... it occurred to me...

There are A LOT of things that *can* be handled quite-simply, by making use of each other... E.G.

configurePinAsAnOutput()

configureAllPinsAsOutputs()

configureMaskedPinsAsOutputs()

ALL of these could be handled, simply, by different "calls" to configureMaskedPinsAsOutputs()

The question, then, is... Is it reliable to think that most architectures' optimizers would be smart enough to recognize the most-optimal optimization of all those masked-cases...?

I know for a fact AVR's optimizer (at -Os) has been known to recognize e.g.

PORTA |= (1<<7)

as nothing more than an sbi() instruction

Pretty awesome, really... as it could much more easily have done a read-modify-write as the code was written. (Props to that optimizer team!)

BUT: at, e.g., -O1, I think it should be pretty much guaranteed to use the read-modify-write, as-written... which I don't see a use for, and would really bog things down in some other, more sophisticated, cases. And... are other architectures' optimizers as smart as avr-gcc's? Further, e.g. xc32-gcc, the free license, doesn't allow -Os, so would generate some pretty bloated code that, likely, wouldn't be any better as macros than function-calls. Maybe worse.

So, then, How could I reduce the "entry barrier" for new architectures...?

How's about e.g. using configureMaskedPinsAsOutputs() for *all* cases *except* when that case is explicitly-defined in the architecture-specific file e.g. gpio_port_pic32.h.

Then, it's likely, the majority of stuff could easily be implemented at an early-stage (and functional, really) with only a few explicitly-architecture-specific macros... And, the remainder could be manually "optimized" whenever one sees fit...

And... That's where it gets a little less "optimal"... Some architectures would be quite happy with writeMasked style stuff... PIC32 has _SET and _CLR registers for every PORT register... writeMasked could easily be implemented with two register-writes, no read-modify-write necessary. That is *just as* efficient for all the cases shown. But, e.g. on an AVR, where *three* bits are to be written, it would *definitely* require a read-modify-write, and probably some bit-shifts. (and, again, when optimization is turned off, it'd result in the same, even if only one bit was toggled and an sbi() *could've* replaced it

I've already, long-since, optimized *most* of those macros for AVR, and *many* for PIC32... but when a new architecture is added... would it be better to use writeMasked() as default for all cases, or is another method more general-purpose-optimal... (and... maybe... it'd be worth it to just implement writeMasked as a function-call in those cases...?)

So, that's where I'm at, at the moment.

And... admittedly... some amount of pondering whether having *all those macros* is such a great idea, at all... Yeah... I think it's better'n e.g. writing PORT |= (1<<7) everywhere, ain't no question whether that's architecture-specific. ("Wait, do I write LAT on this architecture, or PORT? Can I read it back for an R-M-W?") Yeah... these help... a lot.

And, again, when hand-optimized ONCE, in the associated gpio_port_<mcu>.h file, they generally result in the lowest instruction-count possible... which is generally *FAR* fewer than a function-call. So that's also quite handy. (Kinda the point, really).

...........

I guess, at some point, one might wonder whether *so much* effort should be placed on GPIOs at all, when darn-near everything these days *could* be handled by peripherals... right?

Not sure... E.G. I once implemented a UART on a device whose only serial-peripheral was synchronous, via an example from the manufacturer. Admittedly a great hack that they came up with a way to use a synchronous serial peripheral to implement asynchronous communication. And, frankly, I was pretty proud to have accomplished the same, from their example.

But, as I recall I think it was almost as much CPU-load (if not more?) than bit-banging the blasted thing. Nevermind being something that really only applies to a handful of parts, even from the same line of controllers, as it made use of a whole bunch of features available only to that style of synchronous serial peripheral, and other available features on that specific device (Again, a "Great Hack" worthy of admiration, and a great learning-experience). But, that guy was half-duplex, and bitbanging a UART in full-duplex while running other software, without even having interrupts isn't really *that* difficult for a RISC processor running at even a lowly 4MHz to handle.

Write that gpio-based software *once* (commonCode's 'polled_uar' and 'polled_uat'), and implement as many UARTs as you need on GPIOs on nearly any architecture... Not *ideal* in most-cases, (especially where a dedicated UART exists) but certainly easy to get a project started, when it's already been written, and easier to throw a debug-port on a device whose uart-peripherals are already in use, or otherwise not-yet-understood.

It's like anything, a tool, with pros-and-cons. Definitely not a one-size-fits-all, but handy to have at the right time. And, using 'bithandling' (and now 'gpio_port'), once set up *once* for your architecture, it doesn't care any more about your architecture-specifics than how to toggle a pin in the same way you'd blink an LED, the same way you'd bit-bang 32-bit SPI on an 8-bit architecture, interface with an SD-card, or SDRAM, or handle something as complex as timing acceleration of stepper-motors ala grbl on a processor most people would consider under-spec'd (props to its creator, definitely some wizardry in making that possible!). It would, however, be a bit more of a stretch to use these macros for, e.g., the bitbanged-implementations of USB on e.g. an AVR, where every clock-cycle counts and most of the *surrounding* code has to be written in assembly, so couldn't be ported to another architecture by merely abstracting the I/O routines. This "abstracted-gpio" method, despite intending to be *as fast as* direct register-writes and/or the associated-assembly, definitely has its limitations.

But, as it stands, *most* of those PIC32 I/O routines have already been "added to the bank," as-of grbl-abstracted, and several other projects. So, the current project, porting of #sdramThingZero - 133MS/s 32-bit Logic Analyzer from its current early-experiments on the AVR-host is little more than a matter of "transferring between accounts" (e.g moving the associated code from grbl-abstracted into commonCode's new 'gpio_port')...

Well, that... and soldering up a TQFP breakout-board, figuring out pinouts, etc. WEEE!

---------

Oh, and I've been meaning to throw in there that...

Another *big* part of the older versions of 'bithandling' (0.xx) and now 'gpio_port' is the fact that all port-related macros make use of *only* references to the associated "PORT" register.

That's kinda a big deal...

E.G. on AVR you have:

• PORTA
  • 1's written to *output* bits in this register cause the pin to go high
  • 1's written to *input* bits in this register cause the pin's internal pull-up resistor to be activated
  • 0's written to *output* bits in this register cause the pin to go low
  • 0's written to *input* bits in this register cause the pin's internal pull-up resistors to be disabled
• PINA
  • Read-Only (right?)
  • Reads from this register give you the binary-value measured at the pin, regardless of whether it's an input or an output
    
• DDRA
  • 1's written to this register cause the pin to be an *output*
  • 0's written to this register cause the pin to be an *input*

WHEREAS: E.G. on a PIC32 you have an *entirely* different scenario:

(And this list is a bit simplified)

• TRISA
  • 1's written to this register cause the pin to be an input
  • 0's written to this register cause the pin to be an output
  • (Essentially the opposite of AVR's DDRA)
• LATA
  • 1's written to *output* bits in this register cause the pin to go high
  • 0's written to the *output* bits in this register cause the pin to go low
  • ***READS from LATA reads the value stored in the data (output) latch
  • (SIMILAR to AVR's PORTA, but *only* for output-bits)
• PORTA
  • WRITEs to this register act identical to writes to LATA
  • READs from this register act identical to reads from the AVR's PINA
• ODCA
  • ODC registers allow setting an output to open-drain
  • The equivalent could be accomplished on an AVR, roughly, by using two back-to-back register-writes:
    • For Low output: writing '0' to the bit in PORTA and '1' to DDRA
    • For Open-Drain output: writing '0' to DDRA (leave PORTA at '0')
• CNPUA = pull-ups (CNPDA = pull-downs)
  • 1's written to *output* bits in this register cause the pin's internal pull-up/down resistors to be enabled
  • 0's written to *output* bits in this register cause the pin's internal pull-up/down resistors to be disabled
  • (CNPUA is pretty much equivalent to an AVR's PORTA register *FOR BITS THAT ARE INPUTS*)
• (_SET/_CLR/_INV registers)
  • (Every port-related register above, (and even more not listed!) has associated REGISTER_SET, REGISTER_CLR, and REGISTER_INV registers which can be written with individual bits set to 1 to change the register-value without affecting other bits. Cool! No such luck on AVRs, but they do have sbi() and cbi(), so it's close).
    

OK, so why all this info...?

Well, there are a few things that are supported by both architectures (and I don't pretend to know enough about the myriad of architectures out there to claim these options exist on *all* architectures, but are probably pretty common)...

So, let's look at the AVR again... It basically has *four* GPIO pin-states, controlled by its registers:

• Output '1'
• Output '0'
• [Input] pulled-up
• [Input] Hi-Z

The PIC32 can implement all these, as well... (and more, e.g. [Input] pulled-down)

But, doing-so on *both* architectures, requires writing to a myriad of different registers. And, Not Only do those registers have different names on different architectures, not only do they have different *functionality*, but setting some of those configurations on *one* architecture might require multiple registers to be written, plausibly even with read-modify-writes, while setting that same configuration on another architecture might only require writing one register.

So, obviously, setting up different pin-configurations on these different architectures requires not only different *code*, but *also* different register-names.

BUT:

The cool thing about these architectures (and maybe this is true amongst most?) is that these registers are all located *relative* to each other, within the devices' memory-maps.

E.G. On the AVR (for *all* AVRs? I've only worked with a dozen or so varieties):

• PORTx is located at address (a)
• DDRx is located at address (a-1)
• PINx is located at address (a-2)

On the PIC32 (for *all* PIC32s? At least the MX-series...?)

• PORTx is located at (a)
• LATx at (a+0x10)
• CNPU at (a+0x30)
• TRIS at (a-0x10)
• and so on...
• Then, each _CLR/_SET/_INV register has its own offset relative to those
  • PORTx_CLR at (a+0x4)
  • PORTx_SET at (a+0x8)
  • PORTx_INV at (a+0xC)
  • LATx_CLR at (a+0x10+0x04)
  • and so on...

SO... This knowledge makes pinoutting *perty-durn-easy* while *still* being architecture-unspecific...

Every GPIO pin, on both architectures (and probably most?), can be uniquely-referenced by its PORT-register and its bit-number...

Thus, e.g.

#define LED_BIT   3
#define LED_PORT  PORTA

...are the only two things yah-needs-ta-list for any LED pin attached to any port on (any?) both architectures (this happens to correspond to pin PA3, on an AVR, or RPA3 on a PIC32).

The remainder can be accomplished by nothing more than the macros in 'gpio_port'.

So, say you want to set the LED-pin as an output and turn it on (active-high):

gpioPORT_configurePinAsOutput(LED_PORT, LED_PIN);
gpioPORT_outputOneToPin(LED_PORT, LED_PIN);

But, again, for an AVR that would require, otherwise, keeping track of LED_BIT, LED_PORT, and LED_DDR.

For a PIC32 that would require, otherwise, keeping track of LED_BIT, LED_LAT, and LED_TRIS. (And, actually, LED_ANSEL, as well)

...

If we had to keep track of all that for *every* pin on *every* architecture, then feed the appropriate register to the appropriate macro... Yeah, talk about NON-architecture-unspecific.

So, just use _BIT and _PORT, and let the rest be handled by macros... and, in the end, in most cases, the math should be handled during compile time via the optimizer (or maybe even the preprocessor?), thus they'll result in *direct* writes to the *actual* register, rather than doing pointer-arithmetic during *every* call to determine *which* register to write.

(Again, these are *macros*, not *functions*, and their arguments are *expected to be* constants. (You could get away with non-constants, it'd function, but it would *definitely* be much slower))

Perty Handy... and at least a bit more architecture-unspecific.

And, having yet to meet many other architectures, I can only imagine some might have different predefined register names than, e.g., "PORTA" (maybe "port_reg0"?)... hey, as long as they have their various register-offsets in a predefined order (like DDRx = PORTx - 1, etc.) then it'd be just as easy to implement the associated macros for that architecture...

Sure, your LED_PORT wouldn't be as pretty as "PORTA", instead looking like "port_reg0", but functionally, it'd all be the same...

And, really, how often you think you're gonna use the same pinout on two *entirely* different architectures...? Hey, at least all ya's gots to do is find/replace a *couple* #defines for each pin, and can still use the same macros and the same arguments in the calls to those macros.