sysfs

As Linux Kernel documentation implies, sysfs is:

> sysfs is a ram-based filesystem initially based on ramfs. It provides
a means to export kernel data structures, their attributes, and the
linkages between them to userspace.

Currently, sysfs contains many information vital for HostInfo: i.e. NUMA
topology and properties of block devices.

Because each attribute represented as a single file, accessing it
require following actions:
1. Build path of sysfs file (usually done by path_join_aas).
2. Open that file and check for errors
3. Read data and coerce types where needed
Following functions can do that in a single call.

Paths

Path is usually passed to these functions in three arguments:

• root -- root directory where objects that are currently processed are located
  
• name -- name of processed object
  
• object -- name or path of attribute
  

These arguments are then passed to path_join* functions as varargs, so
If you set one of them to NULL, following arguments will be omitted,
so if you do not have name, you should pass attribute name as name
and NULL as object.

I.e. to get UUID of DM device, /sys/block, dm-0 and dm/uuid are passed.
It is useful because, /sys/block is global for all devices, and dm/uuid is
a universal path to UUID, while dm-0 may be easily replaced with other DM names.

Functions

hi_linux_sysfs_readstr

Read string into statically allocated buffer.

ARGUMENTS

• str - pointer to buffer
  
• len - length of buffer
  

RETURN VALUES
HI_LINUX_SYSFS_ERROR if file cannot be opened or HI_LINUX_SYSFS_OK

NOTES
Returned string is NULL-terminated, but may contain trailing NL symbol Use fixstr functions to fix that
If there are additional characters in sysfs file, they would be ignored. If you are not sure about size of buffer, use aas version

int hi_linux_sysfs_readstr(const char* root, const char* name, const char* object,char* str, int len)

hi_linux_sysfs_readstr_aas

Read string into auto-allocated string

ARGUMENTS

• aas - pointer to auto-allocated string
  

RETURN VALUES
HI_LINUX_SYSFS_ERROR if file cannot be opened or HI_LINUX_SYSFS_OK

NOTES
Returned string is NULL-terminated, but may contain trailing NL symbol Use fixstr functions to fix that

int hi_linux_sysfs_readstr_aas(const char* root, const char* name, const char* object,char** aas)

hi_linux_sysfs_readuint

Read unsigned integer represented in decimal form from sysfs

ARGUMENTS

• defval - if reading was unsuccessful, returns this value
  

RETURN VALUES
value from sysfs is everything went fine or defval

uint64_t hi_linux_sysfs_readuint(const char* root, const char* name, const char* object,uint64_t defval)

hi_linux_sysfs_readbitmap

Read bitmap represented in human readable form from sysfs

ARGUMENTS

• bitmap - pointer to pre-allocated bitmap
  
• len - length of bitmap in double words
  

RETURN VALUES
HI_LINUX_SYSFS_OK if everything went fine or HI_LINUX_SYSFS_ERROR if reading failed or overflow occured.

int hi_linux_sysfs_readbitmap(const char* root, const char* name, const char* object,uint32_t* bitmap, int len)

hi_linux_sysfs_fixstr

Fix sysfs string: replace newlines \n with spaces in-place

void hi_linux_sysfs_fixstr(char* p)

hi_linux_sysfs_fixstr2

Fix sysfs string 2: replace last newline \n with null-terminator

void hi_linux_sysfs_fixstr2(char* p)

hi_linux_sysfs_walk

Walk over sysfs directory and call function for each entry

ARGUMENTS

• root - path to directory
  
• proc - walker function that receives file name
  
• arg - argument passed as second argument to proc()
  

RETURN VALUES
HI_LINUX_SYSFS_OK if everything went fine or HI_LINUX_SYSFS_ERROR if opening directory failed

int hi_linux_sysfs_walk(const char* root,void (*proc)(const char* name, void* arg), void* arg)

hi_linux_sysfs_walkbitmap

Parse bitmap using hi_linux_sysfs_readbitmap() and call function proc()
for all bits that are set to 1.

ARGUMENTS

• count - maximum number of bits
  
• proc - walker function that receives bit id
  
• arg - argument passed as second argument to proc()
  

RETURN VALUES
HI_LINUX_SYSFS_OK if everything went fine or HI_LINUX_SYSFS_ERROR if reading failed or overflow occured.

REFERENCE
hi_linux_sysfs_readbitmap

int hi_linux_sysfs_walkbitmap(const char* root, const char* name, const char* object, int count,void (*proc)(int id, void* arg), void* arg)

hi_linux_sysfs_readlink_aas

Reads symbolic link destination from sysfs, and copies it to
auto-allocated string aas.

ARGUMENTS

• aas - auto-allocated string
  
• basename - if this flag is set, take basename of link destination before copying
  

RETURN VALUES
HI_LINUX_SYSFS_OK if everything went fine or HI_LINUX_SYSFS_ERROR if path_join_aas() or readlink() were failed

int hi_linux_sysfs_readlink_aas(const char* root, const char* name, const char* object,char** aas, boolean_t basename)