Skip to content

F
FMC Software Support
Commit 6e1be9f7 authored by Federico Vaga's avatar Federico Vaga
Browse files
Options

Merge branch '2-fix-documentation' into 'master' 

Resolve "fix documentation"

Closes #2

See merge request be-cem-edl/fec/hardware-modules/fmc!2
parents a697fda8 deabe09a
Hide whitespace changes
Inline Side-by-side
Showing with 189 additions and 50 deletions
drivers/fmc/fmc-core.c
View file @ 6e1be9f7
......@@ -24,7 +24,7 @@ static struct class fmc_class;
/**
* Check if an FMC slot is present in a carrier slot
* fmc_slot_present() - Check if an FMC slot is present in a carrier slot
* @slot: FMC slot to verify
*
* Return: 1 if the slot is present, 0 if it is not present, otherwise a
......@@ -125,7 +125,7 @@ static const struct device_type fmc_carrier_type = {
/**
* Generate a device ID for slot
* fmc_slot_id() - Generate a device ID for slot
* @carrier: an FMC carrier instance (already configured)
* @lun slot Logical Unit Number
*
......@@ -138,7 +138,7 @@ static inline uint32_t fmc_slot_id(struct fmc_carrier *carrier,
}
/**
* Add an initialized slot to the given carrier
* fmc_carrier_add_slot() - Add an initialized slot to the given carrier
* @carrier: the carrier instance
* @info: slot information from the carrier driver
*
......@@ -217,9 +217,10 @@ err_ida:
}
/**
* Remove the given slot from its carrier (previously added with
* fmc_carrier_add_slot())
* fmc_carrier_del_slot() - Remove the given slot from its carrier
* @slot: a previously added slot
*
* NOTE: previously added with fmc_carrier_add_slot()
*/
static void fmc_carrier_del_slot(struct fmc_slot *slot)
{
......@@ -231,7 +232,7 @@ static void fmc_carrier_del_slot(struct fmc_slot *slot)
}
/**
* Register an FMC carrier device
* fmc_carrier_register() - Register an FMC carrier device
* @parent: the parent device for the FMC carrier
* @ops: carrier operations
* @nr_slot: number of available slots
......@@ -329,7 +330,7 @@ err_ida:
EXPORT_SYMBOL(fmc_carrier_register);
/**
* Unregister an FMC carrier instance
* fmc_carrier_unregister() - Unregister an FMC carrier instance
* @parent: parent device
*
* Return: 0 on success, otherwise a negative error code
......@@ -352,6 +353,10 @@ int fmc_carrier_unregister(struct device *parent)
EXPORT_SYMBOL(fmc_carrier_unregister);
/**
* __fmc_class_find_carrier_match() - match device with carrier
* @dev: fmc carrier from the loop
* @data: fmc slot looking for its parent
*
* A device matches only when the device instance is a carrier and it has
* the parent we asked.
*/
......@@ -364,7 +369,7 @@ static int __fmc_class_find_carrier_match(struct device *dev,
}
/**
* Retrieve, and pin, the FMC carrier associated to the given device
* fmc_carrier_get() - Retrieve, and pin, the FMC carrier of a device
* @parent: parent device
*
* This pointer must be released with a call to fmc_carrier_put()
......@@ -382,7 +387,7 @@ struct fmc_carrier *fmc_carrier_get(struct device *parent)
EXPORT_SYMBOL(fmc_carrier_get);
/**
* Release the given FMC carrier
* fmc_carrier_put() - Release the given FMC carrier
* @carrier: FMC carrier to release
*/
void fmc_carrier_put(struct fmc_carrier *carrier)
......@@ -392,8 +397,7 @@ void fmc_carrier_put(struct fmc_carrier *carrier)
EXPORT_SYMBOL(fmc_carrier_put);
/**
* Retrieve, and pin, the FMC slot associated to the given set
* of device, I2C adapter and geographical address
* fmc_slot_get() - Retrieve, and pin, the FMC slot of a slot
* @parent: parent device
* @lun: Slot Logical Unit Number
*
......@@ -429,7 +433,7 @@ struct fmc_slot *fmc_slot_get(struct device *parent,
EXPORT_SYMBOL(fmc_slot_get);
/**
* Releases the given FMC slot
* fmc_slot_put() - Releases the given FMC slot
* @slot: FMC slot to release
*/
void fmc_slot_put(struct fmc_slot *slot)
......
drivers/fmc/fmc-eeprom.c
View file @ 6e1be9f7
......@@ -19,7 +19,7 @@
#define FRU_EEPROM_NAME "fru_eeprom"
/**
* Default EEPROM type according to the standard.
* FMC_EEPROM_TYPE_DEFAULT - Default EEPROM type according to the standard.
*/
#define FMC_EEPROM_TYPE_DEFAULT "24c02"
......@@ -38,7 +38,7 @@ static void fmc_slot_eeprom_setup(struct memory_accessor *macc, void *context)
slot->macc = macc;
}
/**
/*
* Default configuration for AT24C02 EEPROM type
*/
static const struct at24_platform_data at24_24c02 = {
......@@ -50,7 +50,7 @@ static const struct at24_platform_data at24_24c02 = {
#endif /* KERNEL_VERSION(4, 6, 0) <= LINUX_VERSION_CODE */
/**
* Initialize I2C EEPROM info with standard values
* fmc_slot_eeprom_init() - Initialize I2C EEPROM info with standard values
*/
static void fmc_slot_eeprom_init(struct fmc_slot *slot,
struct i2c_board_info *info,
......@@ -104,11 +104,13 @@ int fmc_nvmem_device_find_match(struct device *dev, const void *data)
}
/**
* Read from EEPROM
* fmc_slot_eeprom_read() - Read from EEPROM
* @slot: FMC slot instance
* @buf: destination buffer
* @offset: EEPROM offset in bytes
* @count: how many bytes to read
*
* Return: the number of bytes read
*/
ssize_t fmc_slot_eeprom_read(struct fmc_slot *slot,
void *buf, off_t offset, size_t count)
......@@ -130,7 +132,7 @@ ssize_t fmc_slot_eeprom_read(struct fmc_slot *slot,
EXPORT_SYMBOL(fmc_slot_eeprom_read);
/**
* Add EEPROM which will be associated to the given FMC slot
* __fmc_slot_eeprom_add() - Add EEPROM to the given FMC slot
* @slot: FMC slot instance
* @info: I2C EEPROM information
*
......@@ -202,7 +204,7 @@ static int __fmc_slot_eeprom_add(struct fmc_slot *slot,
}
/**
* Add EEPROM to a given FMC slot
* fmc_slot_eeprom_add() - Add EEPROM to the given FMC slot
* @slot: FMC slot instance
*
* Return: 0 on success, otherwise a negative error number
......@@ -216,7 +218,7 @@ int fmc_slot_eeprom_add(struct fmc_slot *slot)
}
/**
* Remove EEPROM associated to the given FMC slot
* fmc_slot_eeprom_del() - Remove EEPROM associated to the given FMC slot
* @slot: FMC slot instance
*
* This should be used only by the FMC framework itself. But, this is also
......@@ -243,7 +245,7 @@ void fmc_slot_eeprom_del(struct fmc_slot *slot)
}
/**
* Replace current EEPROM instance with a given one
* fmc_slot_eeprom_replace() - Replace current EEPROM instance with a given one
* @slot: FMC slot instance
* @info: I2C EEPROM information
*
......@@ -326,7 +328,7 @@ int fmc_slot_eeprom_type_set(struct fmc_slot *slot, const char *type)
EXPORT_SYMBOL(fmc_slot_eeprom_type_set);
/**
* Check if an FMC mezzanine in the FMC slot has a valid FRU
* fmc_slot_fru_valid() - Check if an FMC mezzanine has a valid FRU
* @slot: FMC slot to verify
*
* Return: 1 if the slot is present, otherwise 0
......
drivers/fmc/fru-parse.c
View file @ 6e1be9f7
......@@ -8,13 +8,24 @@
#include <linux/slab.h>
#include <linux/ipmi/fru.h>
/* The fru parser is both user and kernel capable: it needs alloc */
/**
* Allocate memory
* @size: memory size
*
* Return: a pointer to the new allocated buffer
*/
void *fru_alloc(size_t size)
{
return kzalloc(size, GFP_KERNEL);
}
/* Some internal helpers */
/**
* Get a board info area type-length value
* @header: FRU header
* @nr: type-length number
*
* Return: a `n` type-length
*/
static struct fru_type_length *
__fru_get_board_tl(struct fru_common_header *header, int nr)
{
......@@ -32,6 +43,13 @@ __fru_get_board_tl(struct fru_common_header *header, int nr)
return tl;
}
/**
* Get the string from a type-length
* @header: FRU header
* @nr: type-length number
*
* Return: a pointer to an allocated string containing the type-length value
*/
static char *__fru_alloc_get_tl(struct fru_common_header *header, int nr)
{
struct fru_type_length *tl;
......@@ -47,25 +65,48 @@ static char *__fru_alloc_get_tl(struct fru_common_header *header, int nr)
return fru_strcpy(res, tl);
}
/* Get various stuff, trivial */
/**
* Get the manufacturer name
* @header: FRU header
*
* Return: a pointer to the manufacturer string (user must free the memory)
*/
char *fru_get_board_manufacturer(struct fru_common_header *header)
{
return __fru_alloc_get_tl(header, 0);
}
EXPORT_SYMBOL(fru_get_board_manufacturer);
/**
* Get the preduct name
* @header: FRU header
*
* Return: a pointer to the produtct string (user must free the memory)
*/
char *fru_get_product_name(struct fru_common_header *header)
{
return __fru_alloc_get_tl(header, 1);
}
EXPORT_SYMBOL(fru_get_product_name);
/**
* Get the serial number
* @header: FRU header
*
* Return: a pointer to the serial number string (user must free the memory)
*/
char *fru_get_serial_number(struct fru_common_header *header)
{
return __fru_alloc_get_tl(header, 2);
}
EXPORT_SYMBOL(fru_get_serial_number);
/**
* Get the part number
* @header: FRU header
*
* Return: a pointer to the part number string (user must free the memory)
*/
char *fru_get_part_number(struct fru_common_header *header)
{
return __fru_alloc_get_tl(header, 3);
......
include/linux/fmc.h
View file @ 6e1be9f7
......@@ -34,7 +34,7 @@ struct fmc_slot;
#define FMC_EEPROM_ADDR_SPACE 0x50
/**
* Convert a Geographical Address suffix into an I2C address
* fmc_ga_to_i2c_addr() - Convert a Geographical Address into an I2C address
* @ga: geographical address
*
* Return: an I2C address suffix
......@@ -51,7 +51,7 @@ static inline uint8_t fmc_ga_to_i2c_addr(uint8_t ga)
}
/**
* Fix given address with the FMC geographical address
* fmc_slot_i2c_address() - Fix given address with the FMC geographical address
* @addr: an address
* @ga: geographical address to apply
*
......@@ -97,7 +97,7 @@ struct fmc_slot {
};
/**
* struct fmc_flot_info - information for adding new slots
* struct fmc_slot_info - information for adding new slots
* @i2c_bus_nr: I2C bus number
* @ga: Geographical Address according to FMC standard
* @lun: slot logical unit number
......@@ -109,7 +109,7 @@ struct fmc_slot_info {
};
/**
* Get an FMC slot from its Linux device
* to_fmc_slot() - Get an FMC slot from its Linux device
* @dev_ptr: pointer to device structure
*
* Return: correspondent fmc_carrier structure
......@@ -129,7 +129,7 @@ ssize_t fmc_slot_eeprom_read(struct fmc_slot *slot,
void *buf, off_t offset, size_t count);
/**
* sturct fmc_carrier_operations - FMC operations for carriers
* struct fmc_carrier_operations - FMC operations for carriers
* @owner: the module that will execute the operations
* @is_present: check if an FMC slot is present or not in the slot
* (present: 1, not present or error: 0). The carrier
......@@ -160,7 +160,7 @@ struct fmc_carrier {
};
/**
* Get an FMC carrier from its Linux device
* to_fmc_carrier() - Get an FMC carrier from its Linux device
* @dev_ptr: pointer to device structure
*
* Return: correspondent fmc_carrier structure
......
include/uapi/linux/ipmi/fru.h
View file @ 6e1be9f7
......@@ -27,35 +27,62 @@ extern "C" {
* (http://download.intel.com/design/servers/ipmi/FRU1011.pdf)
*/
/* chapter 8, page 5 */
/**
* struct fru_common_header - FRU header structure
* @format: must be 0x01
* @internal_use_off: for internal user - multiple of 8 bytes
* @chassis_info_off: chassis info - multiple of 8 bytes
* @board_area_off: board info area - multiple of 8 bytes
* @product_area_off: product area - multiple of 8 bytes
* @multirecord_off: multirecord - multiple of 8 bytes
* @pad: must be 0
* @checksum: sum modulo 256 must be 0
*
* FRU specification chapter 8, page 5
*/
struct fru_common_header {
uint8_t format; /* 0x01 */
uint8_t internal_use_off; /* multiple of 8 bytes */
uint8_t chassis_info_off; /* multiple of 8 bytes */
uint8_t board_area_off; /* multiple of 8 bytes */
uint8_t product_area_off; /* multiple of 8 bytes */
uint8_t multirecord_off; /* multiple of 8 bytes */
uint8_t pad; /* must be 0 */
uint8_t checksum; /* sum modulo 256 must be 0 */
uint8_t format;
uint8_t internal_use_off;
uint8_t chassis_info_off;
uint8_t board_area_off;
uint8_t product_area_off;
uint8_t multirecord_off;
uint8_t pad;
uint8_t checksum;
};
/* chapter 9, page 5 -- internal_use: not used by us */
/* chapter 10, page 6 -- chassis info: not used by us */
/* chapter 13, page 9 -- used by board_info_area below */
/**
* struct fru_type_length
* @type_length: type and length
* @data: pointer to value
*
* FRU specification chapter 13, page 9 -- used by board_info_area below
*/
struct fru_type_length {
uint8_t type_length;
uint8_t data[0];
};
/* chapter 11, page 7 */
/**
* struct fru_board_info_area - Board Info Area Section
* @format: must be 0x01
* @area_len: area length- multiple of 8 bytes
* @language: I hope it's 0
* @mfg_date: LSB, minutes since 1996-01-01
* @tl: type-length stuff follows
*
* FRU specification chapter 11, page 7
*/
struct fru_board_info_area {
uint8_t format; /* 0x01 */
uint8_t area_len; /* multiple of 8 bytes */
uint8_t language; /* I hope it's 0 */
uint8_t mfg_date[3]; /* LSB, minutes since 1996-01-01 */
struct fru_type_length tl[0]; /* type-length stuff follows */
uint8_t format;
uint8_t area_len;
uint8_t language;
uint8_t mfg_date[3];
struct fru_type_length tl[0];
/*
* the TL there are in order:
......@@ -71,6 +98,13 @@ struct fru_board_info_area {
*/
};
/**
* enum fru_type - List of possible FRU types
* @FRU_TYPE_BINARY: binary value
* @FRU_TYPE_BCDPLUS: BCD+ value
* @FRU_TYPE_ASCII6: ascii value
* @FRU_TYPE_ASCII: not ascii: depends on language
*/
enum fru_type {
FRU_TYPE_BINARY = 0x00,
FRU_TYPE_BCDPLUS = 0x40,
......@@ -78,8 +112,11 @@ enum fru_type {
FRU_TYPE_ASCII = 0xc0, /* not ascii: depends on language */
};
/*
* some helpers
/**
* fru_get_board_area() - Get the board info area
* @header: FRU header pointer
*
* Return: pointer to the board info area
*/
static inline struct fru_board_info_area *fru_get_board_area(
const struct fru_common_header *header)
......@@ -88,22 +125,48 @@ static inline struct fru_board_info_area *fru_get_board_area(
return (struct fru_board_info_area *)(header + header->board_area_off);
}
/**
* fru_type() - Get the FRU section type
* @tl: the type-length
*
* Return: FRU section type
*/
static inline int fru_type(struct fru_type_length *tl)
{
return tl->type_length & 0xc0;
}
/**
* fru_length() - Get the FRU section length
* @tl: the type-length
*
* Return: FRU section length
*/
static inline int fru_length(struct fru_type_length *tl)
{
return (tl->type_length & 0x3f) + 1; /* len of whole record */
}
/* assume ascii-latin1 encoding */
/**
* fru_strlen() - Compute the string value length from type-length
* @tl: the type-length
*
* Return: string length
*
* assume ascii-latin1 encoding
*/
static inline int fru_strlen(struct fru_type_length *tl)
{
return fru_length(tl) - 1;
}
/**
* fru_strcpy() - Copy the string value from type-length
* @dest: destination string buffer
* @tl: the type-length
*
* Return: it returns the pointer to dest
*/
static inline char *fru_strcpy(char *dest, struct fru_type_length *tl)
{
int len = fru_strlen(tl);
......@@ -112,17 +175,38 @@ static inline char *fru_strcpy(char *dest, struct fru_type_length *tl)
return dest;
}
/**
* fru_next_tl() - Retrieve the next type-length structure
* @tl: the current type-length
*
* Return: the next type-length structure
*/
static inline struct fru_type_length *fru_next_tl(struct fru_type_length *tl)
{
return tl + fru_length(tl);
}
/**
* fru_is_eof() - fru_is_eofCheck if there are no more type-length
* @tl: the current type-length
*
* Return:
* - 1 if the current type-length is the last one
* - 0 if the current type-length is not the last one
*/
static inline int fru_is_eof(struct fru_type_length *tl)
{
return tl->type_length == 0xc1;
}
/* Public checksum verifiers */
/**
* fru_header_cksum_ok() - Validate FRU header checksum
* @header: FRU header pointer
*
* Return:
* - 1 if the FRU header checksum is correct
* - 0 if the FRU header checksum is not correct
*/
static inline int fru_header_cksum_ok(struct fru_common_header *header)
{
uint8_t *ptr = (uint8_t *)header;
......@@ -134,6 +218,14 @@ static inline int fru_header_cksum_ok(struct fru_common_header *header)
return (sum & 0xff) == 0;
}
/**
* fru_bia_cksum_ok() -Validate Board Info Area checksum
* @bia: board info area pointer
*
* Return:
* - 1 if the FRU board info area checksum is correct
* - 0 if the FRU board info area checksum is not correct
*/
static inline int fru_bia_cksum_ok(struct fru_board_info_area *bia)
{
uint8_t *ptr = (uint8_t *)bia;
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment