I/O Ports Abstraction Layer.
More...
Description
I/O Ports Abstraction Layer.
This module defines an abstract interface for digital I/O ports. Note that most I/O ports functions are just macros. The macros have default software implementations that can be redefined in a PAL Low Level Driver if the target hardware supports special features like, as example, atomic bit set/reset/masking. Please refer to the ports specific documentation for details.
The PAL Driver has the advantage to make the access to the I/O ports platform independent and still be optimized for the specific architectures.
Note that the PAL Low Level Driver may also offer non standard macro and functions in order to support specific features but, of course, the use of such interfaces would not be portable. Such interfaces shall be marked with the architecture name inside the function names.
Implementation Rules
In implementing an PAL Low Level Driver there are some rules/behaviors that should be respected.
Writing on input pads
The behavior is not specified but there are implementations better than others, this is the list of possible implementations, preferred options are on top:
- The written value is not actually output but latched, should the pads be reprogrammed as outputs the value would be in effect.
- The write operation is ignored.
- The write operation has side effects, as example disabling/enabling pull up/down resistors or changing the pad direction. This scenario is discouraged, please try to avoid this scenario.
Reading from output pads
The behavior is not specified but there are implementations better than others, this is the list of possible implementations, preferred options are on top:
- The actual pads states are read (not the output latch).
- The output latch value is read (regardless of the actual pads states).
- Unspecified, please try to avoid this scenario.
Writing unused or unimplemented port bits
The behavior is not specified.
Reading from unused or unimplemented port bits
The behavior is not specified.
Reading or writing on pins associated to other functionalities
The behavior is not specified.
Usage
The use of I/O ports requires the inclusion of the header file pal.h
, this file is not automatically included ch.h
like the other header files.
Data Structures |
struct | IOBus |
| I/O bus descriptor. More...
|
Modules |
| PAL Low Level Driver |
| PAL Driver low level driver template.
|
Defines |
#define | PAL_MODE_MASK 0xF |
| Bits in a mode word dedicated as mode selector.
|
#define | PAL_MODE_RESET 0 |
| After reset state.
|
#define | PAL_MODE_UNCONNECTED 1 |
| Safe state for unconnected pads.
|
#define | PAL_MODE_INPUT 2 |
| Regular input high-Z pad.
|
#define | PAL_MODE_INPUT_PULLUP 3 |
| Input pad with weak pull up resistor.
|
#define | PAL_MODE_INPUT_PULLDOWN 4 |
| Input pad with weak pull down resistor.
|
#define | PAL_MODE_INPUT_ANALOG 5 |
| Analog input mode.
|
#define | PAL_MODE_OUTPUT_PUSHPULL 6 |
| Push-pull output pad.
|
#define | PAL_MODE_OUTPUT_OPENDRAIN 7 |
| Open-drain output pad.
|
#define | PAL_LOW 0 |
| Logical low state.
|
#define | PAL_HIGH 1 |
| Logical high state.
|
#define | PAL_PORT_BIT(n) ((ioportmask_t)(1 << (n))) |
| Port bit helper macro.
|
#define | PAL_GROUP_MASK(width) ((ioportmask_t)(1 << (width)) - 1) |
| Bits group mask helper.
|
#define | _IOBUS_DATA(name, port, width, offset) {port, PAL_GROUP_MASK(width), offset} |
| Data part of a static I/O bus initializer.
|
#define | IOBUS_DECL(name, port, width, offset) IOBus name = _IOBUS_DATA(name, port, width, offset) |
| Static I/O bus initializer.
|
#define | palInit(config) pal_lld_init(config) |
| PAL subsystem initialization.
|
#define | palReadPort(port) ((void)(port), 0) |
| Reads the physical I/O port states.
|
#define | palReadLatch(port) ((void)(port), 0) |
| Reads the output latch.
|
#define | palWritePort(port, bits) ((void)(port), (void)(bits)) |
| Writes a bits mask on a I/O port.
|
#define | palSetPort(port, bits) |
| Sets a bits mask on a I/O port.
|
#define | palClearPort(port, bits) |
| Clears a bits mask on a I/O port.
|
#define | palTogglePort(port, bits) |
| Toggles a bits mask on a I/O port.
|
#define | palReadGroup(port, mask, offset) ((palReadPort(port) >> (offset)) & (mask)) |
| Reads a group of bits.
|
#define | palWriteGroup(port, mask, offset, bits) |
| Writes a group of bits.
|
#define | palSetGroupMode(port, mask, mode) |
| Pads group mode setup.
|
#define | palReadPad(port, pad) ((palReadPort(port) >> (pad)) & 1) |
| Reads an input pad logical state.
|
#define | palWritePad(port, pad, bit) |
| Writes a logical state on an output pad.
|
#define | palSetPad(port, pad) palSetPort(port, PAL_PORT_BIT(pad)) |
| Sets a pad logical state to PAL_HIGH .
|
#define | palClearPad(port, pad) palClearPort(port, PAL_PORT_BIT(pad)) |
| Clears a pad logical state to PAL_LOW .
|
#define | palTogglePad(port, pad) palTogglePort(port, PAL_PORT_BIT(pad)) |
| Toggles a pad logical state.
|
#define | palSetPadMode(port, pad, mode) palSetGroupMode(port, PAL_PORT_BIT(pad), mode) |
| Pad mode setup.
|
Functions |
ioportmask_t | palReadBus (IOBus *bus) |
| Read from an I/O bus.
|
void | palWriteBus (IOBus *bus, ioportmask_t bits) |
| Write to an I/O bus.
|
void | palSetBusMode (IOBus *bus, uint_fast8_t mode) |
| Programs a bus with the specified mode.
|
Define Documentation
#define PAL_MODE_MASK 0xF |
Bits in a mode word dedicated as mode selector.
The other bits are not defined and may be used as device-specific option bits.
Definition at line 49 of file pal.h.
After reset state.
The state itself is not specified and is architecture dependent, it is guaranteed to be equal to the after-reset state. It is usually an input state.
Definition at line 57 of file pal.h.
#define PAL_MODE_UNCONNECTED 1 |
Safe state for unconnected pads.
The state itself is not specified and is architecture dependent, it may be mapped on PAL_MODE_INPUT_PULLUP
, PAL_MODE_INPUT_PULLDOWN
or PAL_MODE_OUTPUT_PUSHPULL
as example.
Definition at line 66 of file pal.h.
Regular input high-Z pad.
Definition at line 71 of file pal.h.
#define PAL_MODE_INPUT_PULLUP 3 |
Input pad with weak pull up resistor.
Definition at line 76 of file pal.h.
#define PAL_MODE_INPUT_PULLDOWN 4 |
Input pad with weak pull down resistor.
Definition at line 81 of file pal.h.
#define PAL_MODE_INPUT_ANALOG 5 |
Analog input mode.
Definition at line 86 of file pal.h.
#define PAL_MODE_OUTPUT_PUSHPULL 6 |
Push-pull output pad.
Definition at line 91 of file pal.h.
#define PAL_MODE_OUTPUT_OPENDRAIN 7 |
Open-drain output pad.
Definition at line 96 of file pal.h.
Logical low state.
Definition at line 101 of file pal.h.
Logical high state.
Definition at line 106 of file pal.h.
Port bit helper macro.
This macro calculates the mask of a bit within a port.
- Parameters:
-
[in] | n | bit position within the port |
- Returns:
- The bit mask.
Definition at line 157 of file pal.h.
#define PAL_GROUP_MASK |
( |
|
width |
) |
((ioportmask_t)(1 << (width)) - 1) |
Bits group mask helper.
This macro calculates the mask of a bits group.
- Parameters:
-
- Returns:
- The group mask.
Definition at line 167 of file pal.h.
#define _IOBUS_DATA |
( |
|
name, |
|
|
|
port, |
|
|
|
width, |
|
|
|
offset | |
|
) |
| | {port, PAL_GROUP_MASK(width), offset} |
Data part of a static I/O bus initializer.
This macro should be used when statically initializing an I/O bus that is part of a bigger structure.
- Parameters:
-
[in] | name | name of the IOBus variable |
[in] | port | I/O port descriptor |
[in] | width | bus width in bits |
[in] | offset | bus bit offset within the port |
Definition at line 179 of file pal.h.
#define IOBUS_DECL |
( |
|
name, |
|
|
|
port, |
|
|
|
width, |
|
|
|
offset | |
|
) |
| | IOBus name = _IOBUS_DATA(name, port, width, offset) |
Static I/O bus initializer.
- Parameters:
-
[in] | name | name of the IOBus variable |
[in] | port | I/O port descriptor |
[in] | width | bus width in bits |
[in] | offset | bus bit offset within the port |
Definition at line 190 of file pal.h.
#define palInit |
( |
|
config |
) |
pal_lld_init(config) |
PAL subsystem initialization.
- Parameters:
-
[in] | config | pointer to an architecture specific configuration structure. This structure is defined in the low level driver header. |
Definition at line 200 of file pal.h.
Referenced by halInit().
#define palReadPort |
( |
|
port |
) |
((void)(port), 0) |
Reads the physical I/O port states.
- Note:
- The default implementation always return zero and computes the parameter eventual side effects.
- Parameters:
-
[in] | port | port identifier |
- Returns:
- The port logical states.
Definition at line 211 of file pal.h.
#define palReadLatch |
( |
|
port |
) |
((void)(port), 0) |
Reads the output latch.
The purpose of this function is to read back the latched output value.
- Note:
- The default implementation always return zero and computes the parameter eventual side effects.
- Parameters:
-
[in] | port | port identifier |
- Returns:
- The latched logical states.
Definition at line 227 of file pal.h.
#define palWritePort |
( |
|
port, |
|
|
|
bits | |
|
) |
| | ((void)(port), (void)(bits)) |
Writes a bits mask on a I/O port.
- Note:
- The default implementation does nothing except computing the parameters eventual side effects.
- Parameters:
-
[in] | port | port identifier |
[in] | bits | bits to be written on the specified port |
Definition at line 241 of file pal.h.
#define palSetPort |
( |
|
port, |
|
|
|
bits | |
|
) |
| | |
Value:
Sets a bits mask on a I/O port.
- Note:
- The operation is not guaranteed to be atomic on all the architectures, for atomicity and/or portability reasons you may need to enclose port I/O operations between
chSysLock()
and chSysUnlock()
.
-
The default implementation is non atomic and not necessarily optimal. Low level drivers may optimize the function by using specific hardware or coding.
- Parameters:
-
[in] | port | port identifier |
[in] | bits | bits to be ORed on the specified port |
Definition at line 260 of file pal.h.
#define palClearPort |
( |
|
port, |
|
|
|
bits | |
|
) |
| | |
Value:
Clears a bits mask on a I/O port.
- Note:
- The operation is not guaranteed to be atomic on all the architectures, for atomicity and/or portability reasons you may need to enclose port I/O operations between
chSysLock()
and chSysUnlock()
.
-
The default implementation is non atomic and not necessarily optimal. Low level drivers may optimize the function by using specific hardware or coding.
- Parameters:
-
[in] | port | port identifier |
[in] | bits | bits to be cleared on the specified port |
Definition at line 282 of file pal.h.
#define palTogglePort |
( |
|
port, |
|
|
|
bits | |
|
) |
| | |
Value:
Toggles a bits mask on a I/O port.
- Note:
- The operation is not guaranteed to be atomic on all the architectures, for atomicity and/or portability reasons you may need to enclose port I/O operations between
chSysLock()
and chSysUnlock()
.
-
The default implementation is non atomic and not necessarily optimal. Low level drivers may optimize the function by using specific hardware or coding.
- Parameters:
-
[in] | port | port identifier |
[in] | bits | bits to be XORed on the specified port |
Definition at line 303 of file pal.h.
#define palReadGroup |
( |
|
port, |
|
|
|
mask, |
|
|
|
offset | |
|
) |
| | ((palReadPort(port) >> (offset)) & (mask)) |
Reads a group of bits.
- Parameters:
-
[in] | port | port identifier |
[in] | mask | group mask, a logical AND is performed on the input data |
[in] | offset | group bit offset within the port |
- Returns:
- The group logical states.
Definition at line 320 of file pal.h.
Referenced by palReadBus().
#define palWriteGroup |
( |
|
port, |
|
|
|
mask, |
|
|
|
offset, |
|
|
|
bits | |
|
) |
| | |
Value:
Writes a group of bits.
- Parameters:
-
[in] | port | port identifier |
[in] | mask | group mask, a logical AND is performed on the output data |
[in] | offset | group bit offset within the port |
[in] | bits | bits to be written. Values exceeding the group width are masked. |
Definition at line 337 of file pal.h.
Referenced by palWriteBus().
#define palSetGroupMode |
( |
|
port, |
|
|
|
mask, |
|
|
|
mode | |
|
) |
| | |
Pads group mode setup.
This function programs a pads group belonging to the same port with the specified mode.
- Note:
- Programming an unknown or unsupported mode is silently ignored.
- Parameters:
-
[in] | port | port identifier |
[in] | mask | group mask |
[in] | mode | group mode |
Definition at line 359 of file pal.h.
Referenced by palSetBusMode().
#define palReadPad |
( |
|
port, |
|
|
|
pad | |
|
) |
| | ((palReadPort(port) >> (pad)) & 1) |
Reads an input pad logical state.
- Note:
- The default implementation not necessarily optimal. Low level drivers may optimize the function by using specific hardware or coding.
-
The default implementation internally uses the
palReadPort()
.
- Parameters:
-
[in] | port | port identifier |
[in] | pad | pad number within the port |
- Returns:
- The logical state.
- Return values:
-
| PAL_LOW | low logical state. |
| PAL_HIGH | high logical state. |
Definition at line 379 of file pal.h.
#define palWritePad |
( |
|
port, |
|
|
|
pad, |
|
|
|
bit | |
|
) |
| | |
Value:
Writes a logical state on an output pad.
- Note:
- The operation is not guaranteed to be atomic on all the architectures, for atomicity and/or portability reasons you may need to enclose port I/O operations between
chSysLock()
and chSysUnlock()
.
-
The default implementation is non atomic and not necessarily optimal. Low level drivers may optimize the function by using specific hardware or coding.
-
The default implementation internally uses the
palReadLatch()
and palWritePort()
.
- Parameters:
-
[in] | port | port identifier |
[in] | pad | pad number within the port |
[in] | bit | logical value, the value must be PAL_LOW or PAL_HIGH |
Definition at line 402 of file pal.h.
#define palSetPad |
( |
|
port, |
|
|
|
pad | |
|
) |
| | palSetPort(port, PAL_PORT_BIT(pad)) |
Sets a pad logical state to PAL_HIGH
.
- Note:
- The operation is not guaranteed to be atomic on all the architectures, for atomicity and/or portability reasons you may need to enclose port I/O operations between
chSysLock()
and chSysUnlock()
.
-
The default implementation is non atomic and not necessarily optimal. Low level drivers may optimize the function by using specific hardware or coding.
-
The default implementation internally uses the
palSetPort()
.
- Parameters:
-
[in] | port | port identifier |
[in] | pad | pad number within the port |
Definition at line 425 of file pal.h.
#define palClearPad |
( |
|
port, |
|
|
|
pad | |
|
) |
| | palClearPort(port, PAL_PORT_BIT(pad)) |
Clears a pad logical state to PAL_LOW
.
- Note:
- The operation is not guaranteed to be atomic on all the architectures, for atomicity and/or portability reasons you may need to enclose port I/O operations between
chSysLock()
and chSysUnlock()
.
-
The default implementation is non atomic and not necessarily optimal. Low level drivers may optimize the function by using specific hardware or coding.
-
The default implementation internally uses the
palClearPort()
.
- Parameters:
-
[in] | port | port identifier |
[in] | pad | pad number within the port |
Definition at line 445 of file pal.h.
#define palTogglePad |
( |
|
port, |
|
|
|
pad | |
|
) |
| | palTogglePort(port, PAL_PORT_BIT(pad)) |
Toggles a pad logical state.
- Note:
- The operation is not guaranteed to be atomic on all the architectures, for atomicity and/or portability reasons you may need to enclose port I/O operations between
chSysLock()
and chSysUnlock()
.
-
The default implementation is non atomic and not necessarily optimal. Low level drivers may optimize the function by using specific hardware or coding.
-
The default implementation internally uses the
palTogglePort()
.
- Parameters:
-
[in] | port | port identifier |
[in] | pad | pad number within the port |
Definition at line 465 of file pal.h.
#define palSetPadMode |
( |
|
port, |
|
|
|
pad, |
|
|
|
mode | |
|
) |
| | palSetGroupMode(port, PAL_PORT_BIT(pad), mode) |
Pad mode setup.
This function programs a pad with the specified mode.
- Note:
- The default implementation not necessarily optimal. Low level drivers may optimize the function by using specific hardware or coding.
-
Programming an unknown or unsupported mode is silently ignored.
- Parameters:
-
[in] | port | port identifier |
[in] | pad | pad number within the port |
[in] | mode | pad mode |
Definition at line 484 of file pal.h.
Function Documentation
Write to an I/O bus.
- Note:
- The operation is not guaranteed to be atomic on all the architectures, for atomicity and/or portability reasons you may need to enclose port I/O operations between
chSysLock()
and chSysUnlock()
.
-
The default implementation is non atomic and not necessarily optimal. Low level drivers may optimize the function by using specific hardware or coding.
- Parameters:
-
[in] | bus | the I/O bus, pointer to a IOBus structure |
[in] | bits | the bits to be written on the I/O bus. Values exceeding the bus width are masked so most significant bits are lost. |
Definition at line 92 of file pal.c.
References IOBus::bus_mask, IOBus::bus_offset, IOBus::bus_portid, chDbgCheck, PAL_IOPORTS_WIDTH, and palWriteGroup.