I/O Ports Abstraction Layer. More...

Collaboration diagram for PAL Driver:

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.

#define PAL_MODE_RESET 0

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.

#define PAL_MODE_INPUT 2

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.

#define PAL_LOW 0

Logical low state.

Definition at line 101 of file pal.h.

#define PAL_HIGH 1

Logical high state.

Definition at line 106 of file pal.h.

#define PAL_PORT_BIT ( n ) ((ioportmask_t)(1 << (n)))

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:

[in] width group width

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:

{                                        \
  palWritePort(port, palReadLatch(port) | (bits));                      \
}

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:

{                                      \
  palWritePort(port, palReadLatch(port) & ~(bits));                     \
}

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:

{                                     \
  palWritePort(port, palReadLatch(port) ^ (bits));                      \
}

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:

{                       \
  palWritePort(port, (palReadLatch(port) & ~((mask) << (offset))) |     \
                     (((bits) & (mask)) << (offset)));                  \
}

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:

{                                   \
  palWritePort(port, (palReadLatch(port) & ~PAL_PORT_BIT(pad)) |        \
                     (((bit) & 1) << pad));                             \
}

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

ioportmask_t palReadBus ( IOBus * bus )

Read from 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 function internally uses the palReadGroup() macro. The use of this function is preferred when you value code size, readability and error checking over speed.

Parameters:

[in] bus the I/O bus, pointer to a IOBus structure

Returns:: The bus logical states.

Definition at line 69 of file pal.c.

References IOBus::bus_mask, IOBus::bus_offset, IOBus::bus_portid, chDbgCheck, PAL_IOPORTS_WIDTH, and palReadGroup.

void palWriteBus	(	IOBus *	bus,
		ioportmask_t	bits
	)

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.

void palSetBusMode	(	IOBus *	bus,
		uint_fast8_t	mode
	)

Programs a bus with the specified mode.

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]`	mode	the mode

Definition at line 113 of file pal.c.

References IOBus::bus_mask, IOBus::bus_offset, IOBus::bus_portid, chDbgCheck, PAL_IOPORTS_WIDTH, and palSetGroupMode.

PAL Driver [HAL]

Description

Implementation Rules

Writing on input pads

Reading from output pads

Writing unused or unimplemented port bits

Reading from unused or unimplemented port bits

Reading or writing on pins associated to other functionalities

Usage

Data Structures

Modules

Defines

Functions

Define Documentation

Function Documentation

PAL Driver
[HAL]