{"id":13420893,"url":"https://github.com/pfalcon/libperipha","last_synced_at":"2025-03-19T20:30:49.413Z","repository":{"id":8159896,"uuid":"9581226","full_name":"pfalcon/libperipha","owner":"pfalcon","description":"Grand unified collection of headers to access various hardware chips and components","archived":false,"fork":false,"pushed_at":"2015-08-19T20:33:25.000Z","size":346,"stargazers_count":18,"open_issues_count":0,"forks_count":3,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-03-17T10:21:40.144Z","etag":null,"topics":["embedded","hardware","reverse-engineering"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pfalcon.png","metadata":{"files":{"readme":"README","changelog":null,"contributing":null,"funding":null,"license":"licenses.yaml","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-04-21T15:19:15.000Z","updated_at":"2022-12-30T23:28:43.000Z","dependencies_parsed_at":"2022-09-14T08:22:30.165Z","dependency_job_id":null,"html_url":"https://github.com/pfalcon/libperipha","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfalcon%2Flibperipha","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfalcon%2Flibperipha/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfalcon%2Flibperipha/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfalcon%2Flibperipha/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pfalcon","download_url":"https://codeload.github.com/pfalcon/libperipha/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244501165,"owners_count":20462810,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["embedded","hardware","reverse-engineering"],"created_at":"2024-07-30T22:01:43.606Z","updated_at":"2025-03-19T20:30:49.122Z","avatar_url":"https://github.com/pfalcon.png","language":"C","funding_links":[],"categories":["TODO scan for Android support in followings"],"sub_categories":[],"readme":"libperipha (lib peripheral access) is a collection of headers and\ndefinitions to access internal registers of various hardware components.\n\nLicense\n-------\nlibperipha consists of number of components, developed by project\ncontributors, collected from existing projects, or imported from\nvendor releases. All components of libperipha are released under\nwell-known liberal Open Source licenses (such as BSD or MIT), or\nare in public domain. Please consult each individual file for\nlicensing/copyright terms applying to it. Following provides\n(possibly incomplete) information for major libperihpa components:\n\n1. Default libperipha license unless otherwise specified: 3-clause BSD.\nIf you contribute materials of which you are copyright holder, please\nconsider using this license to minimize complexity and confusion.\n\n2. scripts/ subdirectory: It's common practice in Open Source community\nto release development and support tools on stricter freedom and\ncommunity protecting license, like GPL. However, to minimize confusion\nand to keep automatic licensing scanners happy, libperipha adopts to use\nsame 3-clause BSD license for support scripts.\n\n3. arm/cortex-m/arm-cmsis/ subdir: CMSIS library, copyrighted by ARM Ltd.\nand released under 3-clause BSD license.\n\n\nDownloading\n-----------\nlibperipha is distributed via git repository. To checkout:\n\n    git clone --recursive https://github.com/pfalcon/libperipha.git\n\nIf you cloned without --recursive, run:\n\n    git submodule update --init --recursive\n\n\nInterface/API\n-------------\nThere're a few well-known ways to define hardware registers and access\nthem:\n\n1. Define iomem addresses of registers, and provide functions/macros\nto access them. E.g.:\n\n#define REG_DATA 0x40\n#define READ_R8(addr) ...\n#define WRITE_R8(addr, val) ...\nuint8_t v = READ_R8(REG_DATA);\nWRITE_R8(REG_DATA, 'a');\n\n2. Define registers as \"virtual variables\", so they can be read/written\ndirectly. This is really a variation of the previous method, where\nregister symbol is defined to a dereferenced pointer to an address:\n\n#define _REG_DATA 0x40\n#define R8(addr) (*(volatile uint8_t*)(addr))\n#define REG_DATA R8(_REG_DATA)\nuint8_t v = REG_DATA;\nREG_DATA = 'a';\n\n3. More complex hardware may have number of similar blocks, so instead\nof using just scalar address with method 1, separate block base address\nand in-block register offsets are defines, with corresponding accessors:\n\n#define BLOCK1 0x10\n#define BLOCK2 0x20\n#define REG_DATA 0x00\n#define REG_CTRL 0x02\n#define READ_R16(base, offset) ...\n#define WRITE_R16(base, offset, val) ...\nuint16_t v = READ_R16(BLOCK1, REG_DATA);\nWRITE_R16(BLOCK2, REG_DATA, 0xaa55);\n\n4. Generalization of method 2 to a repeating blocks is using structures\nto define block register layouts, then defining block symbols as structure\npointers using block base addresses:\n\nstruct BLOCK {\n    uint16_t REG_DATA;\n    uint16_t REG_CTRL;\n};\n#define _BLOCK1 0x10\n#define _BLOCK2 0x20\n#define BLOCK1 ((volatile struct BLOCK*)_BLOCK1)\n#define BLOCK2 (*(volatile struct BLOCK*)_BLOCK1)\nuint16_t v = BLOCK1-\u003eREG_DATA;\nBLOCK1-\u003eREG_DATA = 0xaa55;\nBLOCK2.REG_CTRL = CMD_RESET;\n\n\nIt's hard to say that one method is \"better\" than another, each of them has\nits pros and cons. For example, for simple hardware, it makes no sense\nto mandate usage of extra parameters in accessor methods or define\nstructures, methods 1 \u0026 2 work pretty well. Methods 2 \u0026 4 are more\nconcise, but require registers to be memory-mapped (or special pointer\ntypes support from compiler).\n\nSo, libperipha doesn't try to postulate any of these as primary, but\nembraces them all. It is however recommended to whenever possible support\nall of them. It's not as hard as it seems, methods 1 \u0026 2 have basically\nthe same underlying definitions (register addresses as scalar), and from\n4 to 3 it is possible to go with offsetof macro. All these cases can be\ncovered by simple codegeneration script. Going from method 3 to 4 is more\ncomplicated, but a tool to layout structures based on register offsets\nand sizes is just a bit more complicated than trivial.\n\n\n(Re)generating headers from YAML descriptions\n---------------------------------------------\nlibperipha favors declaritive descriptions encoded in easy to understand YAML\nfiles. To generate headers from .yaml files, run scripts/yaml2h.py tool\nin a directory with such files.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpfalcon%2Flibperipha","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpfalcon%2Flibperipha","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpfalcon%2Flibperipha/lists"}