# IO
[Core]

A mechanism to manage the 64 IO lines on the controller. More...

## Modules
| IO Indices
| Indices (0-63) for each of the processor's IO lines.

| IO Bits
| The values to use to create a mask to pass into any of the Bits style functions.

## Functions
int | Io_Start (int index, bool lock)
| Get access to an IO line, possibly locking it.
int | Io_Stop (int index)
| Release your lock on an IO line, possibly deactivating it.
bool | Io_GetActive (int index)
| Read whether an IO pin is in use.
int | Io_SetDirection (int index, bool output)
| Set whether an IO line is an output or an input.
bool | Io_GetDirection (int index)
| Read whether an IO line is an output or an input.
int | Io_SetValue (int index, bool value)
| Turn an IO line on or off.
bool | Io_GetValue (int index)
| Read whether an IO line, presumably set as an output, is on or off.
int | Io_SetPeripheralA (int index)
| Configure an IO line to be part of its peripheral A.
int | Io_SetPeripheralB (int index)
| Configure an IO line to be part of its peripheral B.
int | Io_SetPio (int index, bool enable)
| Configure an IO line to be a general purpose IO.
bool | Io_GetPio (int index)
| Read whether an IO line is configured as a general purpose IO.
int | Io_SetPullup (int index, bool enable)
| Set the pullup resistor for an IO line on or off.
bool | Io_GetPullup (int index)
| Read whether the pullup resistor for an IO line on or off.
void | Io_SetValueBits (longlong bits, longlong values)
| Set the values of a batch of IO lines at once.
void | Io_SetDirectionBits (longlong bits, bool output)
| Set a batch of IO lines to a particular direction (in or out) at once.
void | Io_SetPioBits (longlong bits, bool enable)
| Set a batch of IO lines to being general IOs at once.
longlong | Io_GetValueBits ()
| Get a bitmask with the output values of all the IO lines.
longlong | Io_GetPullupBits ()
| Get a bitmask with the state of the internal pullup for all the IO lines.
longlong | Io_GetPioBits ()
| Get a bitmask indicating PIO configuration for all the IO lines.
longlong | Io_GetDirectionBits ()
| Get a bitmask indicating the in-or-out configuration for all the IO lines.

## Detailed Description

A mechanism to manage the 64 IO lines on the controller.

The 64 IO (Input/Output) lines on the Make Controller are grouped into 2 ports of 32 lines each, port A and port B. Each line has many parameters that can be configured:

- whether it's an input or an output
- whether it's turned on or off (if it's an output)
- whether the internal pullup is enabled
- whether the glitch filter is enabled
- and more...

In addition, all IO pins serve at least double and sometimes triple duty, being general IO lines and also being IO lines for one or more of the controller's many on-chip peripherals, such as the Ethernet system, USB system, SPI, UART, etc. To help address this, the IO system provides a mechanism to "lock" the IO lines, so that you can always be sure that your line has not been altered by some other system while you weren't looking.

## IO API

This API can be used in two ways - either one line at a time or many at a time. Functions to set the values of all the lines at once end in Bits. For example, the one-at-a-time mechanism for setting an IO line configured as an output to true is called Io_SetTrue(). It takes a single index and the one for setting a number of lines is Io_SetTrueBits( ) which takes a mask with the values of all the lines.

To find the index to use for a single line, please see IO Indices. For the constants to help create masks for the Bits style, please see IO Bits.

## Normal Use

The pattern of use is to call Io_Start() prior to using an IO line. If it returns successfully, the line was not previously locked and you can use it as you please. Otherwise, you don't have access to the IO line, and should not make any calls to configure or use it.

Todo:
  Add glitch filter control

## Function Documentation

bool Io_GetActive | ( | int | index | ) |

Read whether an IO pin is in use.

Parameters:

  | index | An int specifying which IO line. Use the appropriate entry from the IO Indices

Returns:
  non-zero if active, 0 if inactive

Example

      if( Io_GetActive( IO_PA23 ) )
      {
        // it's already active
      }
      else
      {
        // not yet active
      }

Definition at line 270 of file io.c.

bool Io_GetDirection | ( | int | index | ) |

Read whether an IO line is an output or an input.

Parameters:

  | index | An int specifying which IO line. Use the appropriate entry from the IO Indices

Returns:
  Non-zero if the pin is an output, 0 if it's an input.

Example

      // Check whether IO 23 is an output or input
      if( Io_GetDirection( IO_PA23 ) )
      {
        // then we're an output
      }
      else
      {
        // we're an input
      }

Definition at line 320 of file io.c.

longlong Io_GetDirectionBits | ( | void |  | ) |

Get a bitmask indicating the in-or-out configuration for all the IO lines.

Returns:
  A longlong (64 bit) value specifying which lines are inputs and which are outputs. Non-zero values indicate that a line is configured as an output.

Example

      longlong directions = Io_GetDirectionBits( );
      if( directions & IO_PA18_BIT )
      {
        // then we know PA18 is configured as an output
      }

Definition at line 834 of file io.c.

bool Io_GetPio | ( | int | index | ) |

Read whether an IO line is configured as a general purpose IO.

Parameters:

  | index | An int specifying which IO line. Use the appropriate entry from the IO Indices

Returns:
  true if it is a PIO, false if it's not.

Example

      if( Io_GetPio( IO_PA18) )
      {
        // then we know PA18 is a PIO
      }

Definition at line 501 of file io.c.

longlong Io_GetPioBits | ( | void |  | ) |

Get a bitmask indicating PIO configuration for all the IO lines.

Returns:
  A longlong (64 bit) value specifying which lines are configured as PIOs.

Example

      longlong pios = Io_GetPioBits( );
      if( pios & IO_PA18_BIT )
      {
        // then we know PA18 is configured as a PIO
      }

Definition at line 815 of file io.c.

bool Io_GetPullup | ( | int | index | ) |

Read whether the pullup resistor for an IO line on or off.

Parameters:

  | index | An int specifying which IO line. Use the appropriate entry from the IO Indices

Returns:
  CONTROLLER_OK (0) on success, otherwise non-zero.

Example

      // Turn on the pullup for IO 17
      Io_GetPullup( IO_PA17 );

Definition at line 573 of file io.c.

longlong Io_GetPullupBits | ( | void |  | ) |

Get a bitmask with the state of the internal pullup for all the IO lines.

Returns:
  A longlong (64 bit) value with the status of the pullups.

Example

      longlong pullups = Io_GetPullupBits( );
      if( pullups & IO_PA18_BIT )
      {
        // then we know PA18 has its pullup turned on
      }

Definition at line 797 of file io.c.

bool Io_GetValue | ( | int | index | ) |

Read whether an IO line, presumably set as an output, is on or off.

Parameters:

  | index | An int specifying which IO line. Use the appropriate entry from the IO Indices

Returns:
  CONTROLLER_OK (0) on success, otherwise non-zero.

Example

      // Turn on IO 17
      Io_SetValue( IO_PA17, 1 );

Definition at line 410 of file io.c.

longlong Io_GetValueBits | ( | void |  | ) |

Get a bitmask with the output values of all the IO lines.

Returns:
  A longlong (64 bit) value with the values of the output lines.

Example

      longlong values = Io_GetValueBits( );
      if( values & IO_PA18_BIT )
      {
        // then we know PA18 is configured as an output
      }

Definition at line 779 of file io.c.

int Io_SetDirection | ( | int | index,
|  | bool | output |
| ) |  |  |

Set whether an IO line is an output or an input.

Use the IO_INPUT and IO_OUTPUT symbols to avoid confusion.

Parameters:

  | index | An int specifying which IO line. Use the appropriate entry from the IO Indices
  | output | Specify 1 for an output, or 0 for an input.

Returns:
  CONTROLLER_OK (0) on success, non-zero otherwise.

Example

      // Set io23 to an input
      if( Io_SetDirection( IO_PA23, IO_INPUT ) == CONTROLLER_OK )
      {
        // success
      }

Definition at line 294 of file io.c.

void Io_SetDirectionBits | ( | longlong | bits,
|  | bool | output |
| ) |  |  |

Set a batch of IO lines to a particular direction (in or out) at once.

Parameters:

  | bits | The bitmask containing the IO lines you'd like to configure - see IO Bits. Must be a longlong to accommodate all 64 bits.
  | output | true to set the lines as outputs, false to set them as inputs

Definition at line 667 of file io.c.

int Io_SetPeripheralA | ( | int | index | ) |

Configure an IO line to be part of its peripheral A.

Parameters:

  | index | An int specifying which IO line. Use the appropriate entry from the IO Indices

Returns:
  0 on success, non-zero on failure

Example

      Io_SetPeripheralA( IO_PA18);

Definition at line 431 of file io.c.

int Io_SetPeripheralB | ( | int | index | ) |

Configure an IO line to be part of its peripheral B.

Parameters:

  | index | An int specifying which IO line. Use the appropriate entry from the IO Indices

Returns:
  0 on success, non-zero on failure

Example

      Io_SetPeripheralB( IO_PA18);

Definition at line 455 of file io.c.

int Io_SetPio | ( | int | index,
|  | bool | enable |
| ) |  |  |

Configure an IO line to be a general purpose IO.

Parameters:

  | index | An int specifying which IO line. Use the appropriate entry from the IO Indices
  | enable | Whether to enable a pin as a PIO or disable it, reverting to an unconfigured state.

Returns:
  0 on success, non-zero on failure

Example

      Io_SetPio( IO_PA18);

Definition at line 480 of file io.c.

void Io_SetPioBits | ( | longlong | bits,
|  | bool | enable |
| ) |  |  |

Set a batch of IO lines to being general IOs at once.

Parameters:

  | bits | The bitmask containing the IO lines you'd like to configure - see IO Bits. Must be a longlong to accommodate all 64 bits.
  | enable | true to configure the lines as PIOs, false un-configure them

Definition at line 687 of file io.c.

int Io_SetPullup | ( | int | index,
|  | bool | enable |
| ) |  |  |

Set the pullup resistor for an IO line on or off.

Parameters:

  | index | An int specifying which IO line. Use the appropriate entry from the IO Indices
  | enable | Non-zero for on, 0 for off.

Returns:
  CONTROLLER_OK (0) on success, otherwise non-zero.

Example

      // Turn on the pullup for IO 17
      Io_SetPullup( IO_PA17, 1 );

Definition at line 554 of file io.c.

int Io_SetValue | ( | int | index,
|  | bool | value |
| ) |  |  |

Turn an IO line on or off.

This IO should have already been set to be an output via Io_SetDirection( )

Parameters:

  | index | An int specifying which IO line. Use the appropriate entry from the IO Indices
  | value | Non-zero for on, 0 for off.

Returns:
  CONTROLLER_OK (0) on success, otherwise non-zero.

Example

      // Turn on IO 17
      Io_SetValue( IO_PA17, 1 );

Definition at line 374 of file io.c.

void Io_SetValueBits | ( | longlong | bits,
|  | longlong | values |
| ) |  |  |

Set the values of a batch of IO lines at once.

Parameters:

  | bits | The bitmask containing the IO lines you'd like to configure - see IO Bits. Must be a longlong to accommodate all 64 bits.
  | values | The mask of 0 or non-0 values that you'd like to write into those lines.

Definition at line 648 of file io.c.

int Io_Start | ( | int | index,
|  | bool | lock |
| ) |  |  |

Get access to an IO line, possibly locking it.

Parameters:

  | index | The IO line to start - use the appropriate entry from IO Indices
  | lock | Whether to lock this line from being used by another system.

Returns:
  0 on success, < 0 on failure

Example

      if( Io_Start(IO_PA18, true) == CONTROLLER_OK)
      {
        // then we have access to PA18 and successfully locked it
      }
      else
        // can't use PA18

Definition at line 120 of file io.c.

int Io_Stop | ( | int | index | ) |

Release your lock on an IO line, possibly deactivating it.

When you call Io_Stop(), it will remove the lock you placed on the line. If no other systems are using it, the line will be deactivated.

Parameters:

  | index | The IO line to stop - use the appropriate entry from IO Indices

Returns:
  0 on success, < 0 on failure

Example

      Io_Stop(IO_PA18);

Definition at line 158 of file io.c.