Hardware Proxy Plugin User Guide ​

1. Overview ​

The hardware proxy plugin (hwproxy) provides a mechanism for direct hardware access. Using this mechanism, service components can encapsulate their hardware access logic into plugins to control hardware directly while ensuring system stability.

Core features include:

1. Exclusive bus access: The plugin locks bus resources during execution to ensure operational integrity.
2. Custom protocol processing: Developers can freely implement data parsing and protocol conversion logic.
3. Flexible control: Developers can flexibly control the granularity and timing of hardware access through the plugin mechanism.

2. System Architecture and Execution Process ​

2.1 Access Flowchart ​

2.2 Execution Process Description ​

1. Request initialization: The service component constructs a context object that includes timeout configuration.
2. Plugin loading: hwproxy dynamically loads the Lua plugin from the /opt/bmc/lualib/hwproxy directory.
3. Command verification: The system verifies that the command exists through the has_cmd method of the plugin.
4. Channel passing: The system passes the chip object, which encapsulates hardware operation capabilities, as the first parameter.
5. Custom execution: The plugin implements specific operation logic through the run_cmd interface.
6. Return result: The system returns the processing result to the caller as a binary array.

3. Core Interfaces ​

3.1 PluginRequest Interface Specification ​

3.1.1 Function Signature ​

-- Example: result = chip:PluginRequest(ctx, plugin_name, cmd, args)
function PluginRequest(
    ctx: Context,          -- Context object (timeout can be set).
    plugin_name: string,   -- Plugin name (must match the filename in the directory).
    cmd: string,           -- Command name (function defined in the plugin).
    args: string           -- Parameter (packed using skynet.pack)
): string                  -- Return value (parsed using skynet.unpack)

3.1.2 Parameters ​

3.1.3 Return Value ​

• Type: String (Parse it into the original data type via skynet.unpack.)
• Content: Execution result of the plugin, such as binary data or an error code

4. Plugin Development Specification ​

Each valid plugin must contain the following structure:

-- Basic plugin template
local plugin_class = class()

-- Command existence verification
function plugin_class:has_cmd(cmd_name)
    return self.commands[cmd_name] ~= nil
end

-- Command execution entry
function plugin_class:run_cmd(chip, cmd, ...)
    return self.commands[cmd](chip, ...)
end

-- Collection of command implementations
plugin_class.commands = {
    read_data = function(chip, offset, length)
        -- Specific operation logic
    end,
    write_data = function(chip, data)
        -- Specific operation logic
    end
}

return plugin_class

Precautions:

1. The chip object is a memory instance of chip.lua from the hwproxy component. In the specific operation logic, call only the read and write functions.
2. In principle, a single operation cannot be executed continuously for more than 1 second.

5. Typical Application Scenarios ​

5.1 Case of Long Data Reading ​

-- Plugin implementation: reading hardware logs in chunks
function read_log_by_mcu(chip, total_size)
    local buffer = ""
    local input = object_pool.new('input_args', OFFSET, DEFAULT_MASK, BLOCK_ACCESS_TYPE, READ_LEN, nil)
    while total_size > 0 do
        local chunk = math.min(total_size, MAX_CHUNK_SIZE)
        local ok, result = pcall(chip.read, chip, input)
        buffer = buffer .. result
        total_size = total_size - chunk
    end
    return buffer
end

-- Example: exporting logs
local function export_log_file(file_path)
    local ctx = context.new{ timeout=600 }
    local log_data = chip:PluginRequest(ctx, "logger", "read_log_by_mcu", 1024*1024)
    file:write(skynet.unpack(log_data))
end

6. Precautions ​

6.1 Code Structure Requirements ​

• The plugin must inherit from the base class and implement the has_cmd and run_cmd methods.
• Define command functions in the commands.[command_name] format.

6.2 Performance and Resources ​

Warning: The plugin occupies the bus exclusively during execution, which may cause access timeout of other hardware.

6.3 Parameter Passing Restrictions ​

• The system restricts the total length of a single parameter. If the parameter exceeds the limit, use a file path for transmission instead.

6.4 Timeout Configuration ​

• The default timeout period is 120 seconds (2 minutes). For long tasks, explicitly set ctx.timeout = N.