ipmb.h File Reference

Definitions used in IPMB Layer. More...

#include "FreeRTOS.h"
#include "task.h"
#include "queue.h"
#include "semphr.h"
#include "board_ipmb.h"

Include dependency graph for ipmb.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ipmi_msg
	IPMI message struct. More...
struct	ipmi_msg_cfg
	IPMI message configuration struct. More...

Macros
#define	IPMB_ADDR_DISCONNECTED   0xA2
	Address out of range of the MicroTCA Carrier's AMC Slot ID.
#define	IPMB_TXQUEUE_LEN   10
	Maximum count of messages to be sent.
#define	IPMB_CLIENT_QUEUE_LEN   10
	Maximum count of received messages to be delivered to client task.
#define	IPMB_MAX_RETRIES   3
	Maximum retries made by IPMB TX Task when sending a message.
#define	IPMB_MSG_TIMEOUT   250/portTICK_PERIOD_MS
	Timeout limit between the end of a request and start of a response (defined in IPMB timing specifications)
#define	CLIENT_NOTIFY_TIMEOUT   5
	Timeout limit waiting a free space in client queue to put a received message.
#define	IPMI_HEADER_CHECKSUM_POSITION   2
	Position of Header cheksum byte in a IPMI message.
#define	IPMI_MSG_MAX_LENGTH   32
	Maximum length in bytes of a IPMI message (including connection header)
#define	IPMB_REQ_HEADER_LENGTH   6
	Length of connection header in a request.
#define	IPMB_RESP_HEADER_LENGTH   7
	Length of connection header in a response.
#define	IPMB_NETFN_MASK   0xFC
#define	IPMB_DEST_LUN_MASK   0x03
#define	IPMB_SEQ_MASK   0xFC
#define	IPMB_SRC_LUN_MASK   0x03
#define	MCH_ADDRESS   0x20
	MicroTCA's MCH slave address.
#define	IS_RESPONSE(msg)   (msg.netfn & 0x01)
	Macro to check is the message is a response (odd netfn)
#define	IPMBL_TABLE_SIZE   27
	Size of IPMBL_TABLE.

Typedefs
typedef struct ipmi_msg	ipmi_msg
	IPMI message struct.
typedef struct ipmi_msg_cfg	ipmi_msg_cfg
	IPMI message configuration struct.
typedef enum ipmb_error	ipmb_error
	IPMB errors enumeration.

Enumerations
enum	GA_Pin_state { GROUNDED = 0 , POWERED , UNCONNECTED }
	GA pins definition. More...
enum	ipmb_error {   ipmb_error_unknown = 0 , ipmb_error_success , ipmb_error_failure , ipmb_error_timeout ,   ipmb_error_invalid_req , ipmb_error_hdr_chksum , ipmb_error_msg_chksum , ipmb_error_queue_creation }
	IPMB errors enumeration. More...

Functions
void	IPMB_TXTask (void *pvParameters)
	IPMB Transmitter Task.
void	IPMB_RXTask (void *pvParameters)
	IPMB Receiver Task.
void	ipmb_init (void)
	Initializes the IPMB Layer.
ipmb_error	ipmb_send_request (ipmi_msg *req)
	Format and send a request via IPMB channel.
ipmb_error	ipmb_send_response (ipmi_msg *req, ipmi_msg *resp)
	Format and send a response via IPMB channel.
ipmb_error	ipmb_register_rxqueue (QueueHandle_t *queue)
	Creates and returns a queue in which the client can block to receive the incoming requests.
ipmb_error	ipmb_assert_chksum (uint8_t *buffer, uint8_t buffer_len)
	Asserts the input message checksums by comparing them with our calculated ones.
uint8_t	get_ipmb_addr (void)
	Reads own I2C slave address using GA pins.

Variables
uint8_t	ipmb_addr
	AMC IPMB Address.

Detailed Description

Definitions used in IPMB Layer.

Author

Henrique Silva henri.nosp@m.que..nosp@m.silva.nosp@m.@lnl.nosp@m.s.br, LNLS

Macro Definition Documentation

CLIENT_NOTIFY_TIMEOUT

#define CLIENT_NOTIFY_TIMEOUT   5

Timeout limit waiting a free space in client queue to put a received message.

IPMB_ADDR_DISCONNECTED

#define IPMB_ADDR_DISCONNECTED   0xA2

Address out of range of the MicroTCA Carrier's AMC Slot ID.

IPMB_CLIENT_QUEUE_LEN

#define IPMB_CLIENT_QUEUE_LEN   10

Maximum count of received messages to be delivered to client task.

IPMB_DEST_LUN_MASK

#define IPMB_DEST_LUN_MASK   0x03

IPMB_MAX_RETRIES

#define IPMB_MAX_RETRIES   3

Maximum retries made by IPMB TX Task when sending a message.

IPMB_MSG_TIMEOUT

#define IPMB_MSG_TIMEOUT   250/portTICK_PERIOD_MS

Timeout limit between the end of a request and start of a response (defined in IPMB timing specifications)

IPMB_NETFN_MASK

#define IPMB_NETFN_MASK   0xFC

IPMB_REQ_HEADER_LENGTH

#define IPMB_REQ_HEADER_LENGTH   6

Length of connection header in a request.

The connection header in a request is made by:

• rsSA -> Destination Address
• NetFN:6 rsLUN:2 -> Net function and dest LUN
• HeaderChecksum -> 2's complement of the sum of preceding bytes
• rqSA -> Source address
• rqSeq:6 rqLUN:2 -> Sequence Number and source LUN
• CMD -> Command
• Messagechecksum -> 2's complement of the sum of preceding bytes

IPMB_RESP_HEADER_LENGTH

#define IPMB_RESP_HEADER_LENGTH   7

Length of connection header in a response.

The connection header in a response is made by:

• rqSA -> Destination Address
• NetFN:6 rqLUN:2 -> Net function and dest LUN
• HeaderChecksum -> 2's complement of the sum of preceding bytes
• rsSA -> Source address
• rqSeq:6 rsLUN:2 -> Sequence Number and source LUN
• CMD -> Command
• CC -> Completion Code
• Messagechecksum -> 2's complement of the sum of preceding bytes

  Note

  Response header is 1 byte longer than request's because it must include the completion code

IPMB_SEQ_MASK

#define IPMB_SEQ_MASK   0xFC

IPMB_SRC_LUN_MASK

#define IPMB_SRC_LUN_MASK   0x03

IPMB_TXQUEUE_LEN

#define IPMB_TXQUEUE_LEN   10

Maximum count of messages to be sent.

IPMBL_TABLE_SIZE

#define IPMBL_TABLE_SIZE   27

Size of IPMBL_TABLE.

IPMI_HEADER_CHECKSUM_POSITION

#define IPMI_HEADER_CHECKSUM_POSITION   2

Position of Header cheksum byte in a IPMI message.

IPMI_MSG_MAX_LENGTH

#define IPMI_MSG_MAX_LENGTH   32

Maximum length in bytes of a IPMI message (including connection header)

IS_RESPONSE

#define IS_RESPONSE

(

msg

)

(msg.netfn & 0x01)

Macro to check is the message is a response (odd netfn)

MCH_ADDRESS

#define MCH_ADDRESS   0x20

MicroTCA's MCH slave address.

Typedef Documentation

ipmb_error

typedef enum ipmb_error ipmb_error

IPMB errors enumeration.

ipmi_msg

typedef struct ipmi_msg ipmi_msg

IPMI message struct.

ipmi_msg_cfg

typedef struct ipmi_msg_cfg ipmi_msg_cfg

IPMI message configuration struct.

This struct is used in the IPMB layer in order to keep the informations about the request/response being handled

Enumeration Type Documentation

GA_Pin_state

enum GA_Pin_state

GA pins definition.

Enumerator
GROUNDED
POWERED
UNCONNECTED

ipmb_error

enum ipmb_error

IPMB errors enumeration.

Enumerator
ipmb_error_unknown	Unknown error
ipmb_error_success	Generic no-error flag
ipmb_error_failure	Generic failure on IPMB
ipmb_error_timeout	Error raised when a message takes too long to be responded
ipmb_error_invalid_req	A invalid request was received
ipmb_error_hdr_chksum	Invalid header checksum from incoming message
ipmb_error_msg_chksum	Invalid message checksum from incoming message
ipmb_error_queue_creation	Client queue couldn't be created. Invalid pointer to handler was given

Function Documentation

get_ipmb_addr()

uint8_t get_ipmb_addr

(

void

)

Reads own I2C slave address using GA pins.

Based on coreipm/coreipm/mmc.c

Author

Gokhan Sozmen

The state of each GA signal is represented by G (grounded), U (unconnected), or P (pulled up to Management Power).

The MMC drives P1 low and reads the GA lines. The MMC then drives P1 high and reads the GA lines. Any line that changes state between the two reads indicate an unconnected (U) pin.

The IPMB-L address of a Module can be calculated as (70h + Site Number x 2).
G = 0, P = 1, U = 2

Pin	Ternary	Decimal	Address
GGG	000	0	0x70
GGP	001	1	0x8A
GGU	002	2	0x72
GPG	010	3	0x8E
GPP	011	4	0x92
GPU	012	5	0x90
GUG	020	6	0x74
GUP	021	7	0x8C
GUU	022	8	0x76
PGG	100	9	0x98
PGP	101	10	0x9C
PGU	102	11	0x9A
PPG	110	12	0xA0
PPP	111	13	0xA4
PPU	112	14	0x88
PUG	120	15	0x9E
PUP	121	16	0x86
PUU	122	17	0x84
UGG	200	18	0x78
UGP	201	19	0x94
UGU	202	20	0x7A
UPG	210	21	0x96
UPP	211	22	0x82
UPU	212	23	0x80
UUG	220	24	0x7C
UUP	221	25	0x7E
UUU	222	26	0xA2

Returns

7-bit Slave Address

ipmb_assert_chksum()

ipmb_error ipmb_assert_chksum	(	uint8_t *	buffer,
		uint8_t	buffer_len )

Asserts the input message checksums by comparing them with our calculated ones.

Parameters

buffer	Pointer to the message bytes.
buffer_len	Size of the message.

Return values

ipmb_error_success	The message's checksum bytes are correct, therefore the message is valid.
ipmb_error_hdr_chksum	The header checksum byte is invalid.
ipmb_error_hdr_chksum	The final checksum byte is invalid.

ipmb_init()

void ipmb_init

(

void

)

Initializes the IPMB Layer.

Configures the I2C Driver, creates the TX queue for the IPMB Task and both IPMB RX and IPMB TX tasks

ipmb_register_rxqueue()

ipmb_error ipmb_register_rxqueue

(

QueueHandle_t *

queue

)

Creates and returns a queue in which the client can block to receive the incoming requests.

The queue is created and its handler is written at the given pointer (queue). Also keeps a copy of the handler to know where to write the incoming messages.

Parameters

queue

Pointer to a QueueHandle_t variable which will be written by this function.

Return values

ipmb_error_success	The queue was successfully created.
ipmb_error_queue_creation	Queue creation failed due to lack of Heap space.

IPMB_RXTask()

void IPMB_RXTask

(

void *

pvParameters

)

IPMB Receiver Task.

Similarly to IPMB_TXTask, this task remains blocked until a new message is received by the I2C driver. The message passes through checksum checking to assure its integrity.
If the message is a request, we have to check if it's a new one or just a retransmission of the last. In order to do this, the sequential number is tested, since every request has a different one.
Right after that, the arrival time and the message body are stored for future checking and the specified client is notified using ipmb_notify_client.

If we have received a response instead, we match it with the last stored request and also check if the awating request hasn't timed-out yet.

Note

When a malformed message, a response without a request or a repeated request are received, they are just ignored, following the IPMB specifications.

Parameters

pvParameters

Default parameter to FreeRTOS tasks, not used here.

See also

IPMB_TXTask

ipmb_notify_client

ipmb_send_request()

ipmb_error ipmb_send_request

(

ipmi_msg *

req

)

Format and send a request via IPMB channel.

ipmb_send_response()

ipmb_error ipmb_send_response	(	ipmi_msg *	req,
		ipmi_msg *	resp )

Format and send a response via IPMB channel.

IPMB_TXTask()

void IPMB_TXTask

(

void *

pvParameters

)

IPMB Transmitter Task.

When ipmb_send_request or ipmb_send_response put a message in ipmb_txqueue, this task unblocks. First step to send a message is differentiating requests from responses. It does this analyzing the parity of NetFN (even for requests, odd for responses).

When sending a response, this task has to check if it matches with the sequence number from the last known request and the amount of time it took to be built (timeout checking). Last step is checking if it has already tried to send this message more than IPMB_MAX_RETRIES value.
After passing all checking, the message is formatted as the IPMB protocol demands and passed down to the I2C driver, using the function xI2CWrite().
If an error comes out of the I2C driver when sending the message, it increases the retry counter in the ipmi_msg_cfg struct and send the message to the front of ipmb_txqueue.
If no errors occurs, the task that put the message in the queue is notified with a success flag.

The proccess is analog when sending a request, but the only check that is made is the retry number. The task skip all checking because, when sending a request, the message is formatted using it's own functions ipmb_send_request or ipmb_send_response and they are guaranteed to put only valid messages in queue.

Parameters

pvParameters

Default parameter to FreeRTOS tasks, not used here.

See also

IPMB_RXTask

ipmb_send_request

ipmb_send_response

Variable Documentation

ipmb_addr

uint8_t ipmb_addr

extern

AMC IPMB Address.

This variable saves this module's IPMB address read through the Geographical Address pins

See also

get_ipmb_addr